Production-Ready Scaffolding Roadmap

Canonical phased plan to elevate the monorepo to a professionally governed, observable, and scalable platform. Time units are compressed: 1 roadmap “day” = 3 focused engineering hours (deep work, excluding context switching). Use calendar translation as needed.

Executive Overview (Investor / Auditor)

This roadmap represents a capital‑efficient engineering investment to de-risk scale-out of additional brands and accelerate iteration throughput. Work is sequenced to front‑load hygiene and governance (verification, CI, deterministic types) before allocating time to optimizations (performance budgets) and experiential polish (design tokens, visual regression). Each phase yields measurable artifacts (metrics JSON, analyzer outputs, story coverage) enabling objective progress tracking.

Governance & Risk Posture Snapshot

Dimension	Current	Target Phase	Risk if Deferred
CI Enforcement	Pending	P1	Silent regressions, slower PR review
Type Drift Control	Baseline only	P2	Contract instability, higher refactor cost
Duplication Visibility	None	P3	Code bloat & maintenance cost
Bundle/Perf Budgets	None	P4	Unbounded bundle growth & infra spend
Design Tokens Enforcement	Partial	P5	Brand inconsistency, redesign cost
Asset Optimization	Manual	P6	Runtime perf degradation
Onboarding Efficiency	Medium	P7	Slower team scale-up
Visual Regression Gate	None	P8	UI regressions reaching production

Capital Efficiency Rationale

• Prevents compounding technical debt (cheapest time to add gates is prior to scale).
• Increases engineering leverage: automation substitutes for manual review cycles.
• Supports faster market experiments (new brand/app variants plug into governed scaffolding).

KPI Targets (to be reported post‑phase completion)

KPI	Baseline (Planned Capture)	Target	Measurement Source
Mean verify pipeline (warm)	P1	≤ 5 min	CI timing summary
Type count variance / week	P2	≤ 0.5%	metrics/types.json diff
Top-5 duplication LOC reduction	P3	≥ 20%	metrics/duplication.json
Median incremental build time	P4	< 60s	metrics/build-times.json
Bundle size delta / 4 weeks	P4	< 5%	metrics/bundles/*.json
Hard-coded color literals	P5	-50% vs baseline	Lint + token scan
New engineer time-to-first-run	P7	≤ 15 min	Onboarding dry run log
Visual diff false positive rate	P8	< 5% PRs	Visual regression report

External readers: Detailed operational mechanics reside in the phase breakdown below; immutable completion history resides in REMEDIATION_LOG.md.

0. Purpose & Scope

This document operationalizes the remediation/master plan previously aligned in discussion. It is implementation-facing: each phase lists objectives, deliverables, acceptance criteria, effort, dependencies, risks, and success metrics. The scope covers repository scaffolding, governance, quality gates, developer experience, and production readiness—not product feature work.

1. Audience

• Core engineering team (execution & PR review)
• Tech lead / architect (governance & approval of gates)
• DevOps / CI maintainers
• Future contributors (onboarding reference)

2. Time Unit & Scheduling Model

• 1 roadmap day = 3 engineering hours of focused implementation.
• Effort numbers are indicative; buffer ~15–20% for unplanned integration friction.
• Parallelization: Within a phase, items may be split across engineers once dependencies satisfied; phases are sequential unless explicitly noted.

3. Phase Overview (At a Glance)

Phase	Goal (Headline)	Key Outputs	Effort (Days=3h)	Depends On
P1	Baseline CI + Verification Gate	CI workflow, enhanced verify script, metrics snapshot	3	—
P2	Deterministic Types Integrity	Strict tsconfig, type metrics, policy doc	2	P1
P3	Duplication & Package Governance	Dup scan script, shared extraction playbook, license check	3	P1 (metrics), partial P2 (types)
P4	Size & Performance Budgets	Bundle analyzer, thresholds, build time capture	3	P1, P2
P5	Theming & Design System Hardening	Central tokens, Storybook coverage targets	4	P2, P3
P6	Asset & Media Pipeline	Image optimization & hashing workflow	2	P4 (size context)
P7	Developer Experience & Onboarding Excellence	Updated onboarding, env bootstrap script, docs portal index	2	P1–P6 outputs referenced
P8	Visual Regression & Release Confidence	Storybook CI + visual diff gating, release checklist	3	P5 (storybook), P4 (CI perf stability)
Total			22 days (~66 hrs)

Calendar framing (single engineer): ~3–4 calendar weeks. With 2 engineers parallelizing intra-phase tasks: ~2–2.5 weeks elapsed.

4. Detailed Phases

P1 – Foundational CI & Verification Enhancements (Days: 3)

Objectives

• Establish a single fast CI pipeline enforcing lint, typecheck, formatting, verification script.
• Enhance scripts/verify-repo.sh to check per-app start scripts and emit structured issues.
• Capture baseline metrics (type count, build times, bundle placeholders, cache stats) to anchor later deltas.

Deliverables

1. .github/workflows/ci.yml (or equivalent) with matrix or segmented jobs (install → verify → test → build critical subset).
2. Updated verify-repo.sh adding:
   • Start script presence check (outputs startScriptIssues array in JSON).
   • Baseline metrics JSON persisted (e.g. .verify/baseline.json).
3. Documentation update in verification.md referencing new fields.
4. Badge or status summary in README.md (CI status + verification summary link).

Acceptance Criteria

• CI run under 8 real minutes (cold) / 5 minutes (warm cache) for current project set.
• Failing start script or path issue causes non-zero exit & PR block.
• Baseline file committed & referenced in remediation log.

Effort & Dependencies: 3 days (no dependencies).

Risks & Mitigations

• Risk: Yarn PnP edge cases in CI. Mitigation: add corepack enable + explicit Node version.
• Risk: Flaky build tasks. Mitigation: isolate flaky packages; retry strategy for single step only.

Success Metrics

• 100% apps pass start script check.
• <5% variance in verify timing across 5 consecutive runs.

P2 – Deterministic Types & Tooling Integrity (Days: 2)

Objectives

• Make type system deterministic & auditable.
• Prevent accidental widening or silent any creep.

Deliverables

1. Hardened root tsconfig.base.json (no implicit any, consistent module resolution, composite builds where beneficial).
2. Script: yarn types:count (tsc API or grep on .d.ts) generating metrics/types.json.
3. Policy doc snippet appended to verification.md (type budget change requires PR note & delta review).
4. Add type count + error count to verify-repo.sh output.

Acceptance Criteria

• Type check stable: identical consecutive counts (± legitimate changes with rationale).
• CI fails on introduced implicit any.

Effort: 2 days. Depends on P1 pipeline.

Risks

• Performance regression using incremental builds. Mitigation: measure w/ and w/o incremental; keep fastest.

Success Metrics

• Baseline type count locked; variance tracked.
• Zero new any without justification after 2 weeks.

P3 – Duplication Control & Package Governance (Days: 3)

Objectives

• Detect & reduce code duplication and uncontrolled internal fork proliferation.
• Establish consistent license compliance & third-party usage transparency.

Deliverables

1. Script: yarn scan:dup producing JSON hotspots (line-level or token-level fingerprinting) targeting threshold first (report-only).
2. License audit step (e.g. yarn dlx license-checker) output stored under compliance/licenses.json.
3. Governance doc section describing when to extract shared code into packages/common or new domain package.
4. Playbook: duplication remediation workflow (prioritize top 5 hotspots → refactor plan logged in REMEDIATION_LOG.md).

Acceptance Criteria

• Dup scan JSON produced in CI artifact.
• Top 5 duplication hotspots documented with remediation status entries.

Effort: 3 days. Depends on P1 (CI) and partially P2 (stable types assist safe refactor).

Risks & Mitigations

• False positives in naive duplicate detector → allow suppression file.

Success Metrics

• 20% reduction in top-5 duplication segment lines by end of next sprint (tracked manually initially).

P4 – Size & Performance Budgets (Days: 3)

Objectives

• Introduce bundle size reporting & thresholds to prevent regression.
• Baseline build time performance & enforce soft budgets.

Deliverables

1. Integrate Vite / Metro bundle analyzer producing JSON (e.g., metrics/bundles/*.json).
2. Script: yarn metrics:build capturing cold/warm build times per representative app cohort.
3. Verify script enhancements: compare current vs baseline size; warn >5% increase; fail >10% unless flagged.
4. Update README.md with badge-like textual table (manually updated) summarizing bundle + build time baseline.

Acceptance Criteria

• At least 3 representative web + 3 mobile app bundle reports checked in.
• CI fails when size delta > threshold without override label / flag.

Effort: 3 days. Depends on P1, P2.

Risks

• Analyzer plugin overhead → run analyzer only on representative subset nightly, quick size estimator on PR.

Success Metrics

• <5% median bundle growth over 4 weeks.
• 90th percentile incremental build < 60s.

P5 – Theming & Design System Hardening (Days: 4)

Objectives

• Consolidate tokens & enforce usage consistency across apps.
• Improve UI component reliability & visual coverage.

Deliverables

1. Central token manifest (packages/theme/tokens.json) + generated TypeScript types.
2. Lint rule or codemod enforcing token usage instead of ad-hoc colors/spacings.
3. Storybook build integrated into CI (fail on broken stories).
4. Coverage target: add minimal interaction tests for critical components (navigation shell, primary buttons, typography scale).
5. Docs: ui/NAVIGATION_ARCHITECTURE.md cross-linked; new docs/design-system.md summarizing contracts & change management.

Acceptance Criteria

• 0 hard-coded brand colors in modified PR sample set (enforced by lint rule sampling).
• Storybook CI passes reproducibly; at least 20 baseline stories.

Effort: 4 days. Depends on P2 (types), P3 (governance patterns).

Risks

• Over-enforcement frustrating early adopters → introduce gradual “warn → error” progression.

Success Metrics

• 50% reduction in unique color literals.
• Component story count growth trend visible in remediation log.

P6 – Asset & Media Pipeline (Days: 2)

Objectives

• Optimize runtime performance via image sizing, hashing, and caching invariants.

Deliverables

1. Pre-commit or CI image optimization (sharp / imagemin) for new assets.
2. Content hash naming convention documented; update imports accordingly.
3. Cache-control recommendations added to deployment doc (future infra alignment).
4. Asset manifest JSON mapping logical names → hashed paths.

Acceptance Criteria

• New/changed raster images are optimized (size reduction evidence in PR examples).
• Asset manifest generated on build.

Effort: 2 days. Depends on P4 (performance context).

Risks

• Large binary diffs inflating repo. Mitigation: encourage external storage for videos / very large media.

Success Metrics

• Average new image weight reduction ≥ 25% vs original uploads.

P7 – Developer Experience & Onboarding Excellence (Days: 2)

Objectives

• Minimize time-to-productive for new engineers.
• Ensure docs remain current & verified.

Deliverables

1. Updated onboarding_guide.md (jq install, Yarn PnP + Expo usage, verification JSON interpretation, start scripts rationale).
2. Script: yarn dev:bootstrap (installs, verifies environment, prints next steps).
3. docs/index.md (lightweight docs portal map) linking all governance / verification / design system docs.
4. Automated doc drift check: verify key referenced files exist and are current (timestamp/hash snapshot optionally).

Acceptance Criteria

• Fresh clone to working app start ≤ 15 minutes documented dry run.
• Bootstrap script exits non-zero on missing prerequisites and suggests fix.

Effort: 2 days. Depends on prior phases for accurate references.

Success Metrics

• Onboarding survey (first 2 new devs) self-reported clarity ≥ 8/10.

P8 – Visual Regression & Release Confidence (Days: 3)

Objectives

• Catch unintended UI changes pre-merge.
• Formalize release readiness gate checklist.

Deliverables

1. Visual regression service integration (Chromatic / Percy) triggered on Storybook build.
2. release-checklist.md enumerating: verification pass, size thresholds, duplication diff, visual diff, bundle budgets.
3. PR template update referencing release gate checklist for applicable branches.
4. Optional: Golden screenshot set stored via provider; local approve workflow documented.

Acceptance Criteria

• PR fails on unapproved visual diffs.
• First tagged release uses checklist; log entry added to REMEDIATION_LOG.md.

Effort: 3 days. Depends on P5 (storybook) & P4 (performance stability).

Risks

• Flaky visual diffs due to nondeterministic rendering. Mitigation: stable fonts, deterministic dates, seed random data.

Success Metrics

• <5% of PRs exhibit flaky diffs after stabilization.

5. Cross-Cutting Governance Principles

• Single Source of Truth: This document + REMEDIATION_LOG.md (immutable ledger for completed items; active tasks tracked here).
• Automation Over Policy: Wherever feasible, scripts enforce standards instead of manual policing.
• Measurable Baselines: Every qualitative improvement pairs with at least one quantitative metric.
• Progressive Hardening: Introduce checks in warn mode → escalate to fail after adoption.

6. Metrics & Artifacts Directory Convention

Artifact	Path (proposed)	Notes
Verification last run	.verify/last-run.json	Always overwritten; human-inspectable
Verification baseline	.verify/baseline.json	Committed snapshot for diffing
Type metrics	metrics/types.json	Count, error tally, timestamp
Bundle metrics	metrics/bundles/*.json	Per representative app & platform
Dup scan	metrics/duplication.json	Rank ordered hotspots
Build times	metrics/build-times.json	Cold vs warm, median & p90
License audit	compliance/licenses.json	SPDX + notices

7. Phase Transition Checklist

Before moving to next phase:

1. All deliverables merged & documented.
2. Acceptance criteria demonstrably met (evidence linked in REMEDIATION_LOG.md).
3. Metrics captured post-implementation (serves as new baseline if needed).
4. Known deferred items explicitly logged (not silently dropped).

8. RACI (Lightweight)

Role	R	A	C	I
Tech Lead		X	X
Core Engineer(s)	X
DevOps			X	X
Design (P5 / P8)			X
New Hire (P7 validation)				X

(R = Responsible, A = Accountable, C = Consulted, I = Informed)

9. Risk Register (Aggregated)

Risk	Phase	Impact	Probability	Mitigation
CI flakiness due to cache variance	P1	Medium	Medium	Pin Node/Yarn, explicit cache restore order
Type strictness slows velocity	P2	Medium	Low	Introduce exceptions file w/ expiry dates
Dup scan noise	P3	Low	Medium	Allow suppression config & refine algorithm iteration
Analyzer overhead extends PR times	P4	Medium	Medium	Run full analysis nightly; PR uses quick heuristic
Design token adoption friction	P5	Medium	Medium	Warn mode → after 2 weeks escalate to error
Image optimization toolchain issues	P6	Low	Low	Optional manual override flag; fallback copy
Bootstrap script drift	P7	Low	Medium	Include script self-check against expected file hashes
Visual diff false positives	P8	Medium	Medium	Deterministic seeds, stable environment vars

10. Reporting Cadence

• Weekly: Update REMEDIATION_LOG.md with phase status delta (≤5 lines).
• Phase completion: Add entry in Completed Ledger summarizing deliverables & metrics delta.
• Monthly (or after P8): Reevaluate whether additional phases (e.g., Security Hardening, Observability) are required.

11. Extension Candidates (Post-P8 – Not In Scope Yet)

• Security static analysis (Semgrep / CodeQL integration)
• Runtime observability (OpenTelemetry instrumentation, error budget SLO dashboards)
• Automated dependency freshness score & risk heatmap

12. Activation Instructions (Immediate Next Steps)

1. Implement P1 tasks (CI workflow + verify script enhancements + baseline capture).
2. Record baseline metrics commit hash in REMEDIATION_LOG.md Completed Ledger.
3. Schedule P2 kickoff only after 3 consecutive green CI runs with stable timings.

---

Document version: 1.0.0 (initial creation)