apophis-fastify/docs/attic/root-history/adoption-readiness-plan.md

Apophis Adoption Readiness Plan (Pre-Release)

This plan orders work by dependency and requires tested, reviewable increments.

Target Outcome

• Move from Pilot to Adopt by removing first-run friction, CI trust gaps, and machine-output inconsistencies.
• Define adoption as: a new team can install, run, fail, replay, and integrate in CI without undocumented setup choices.

Operating Model

• Execute by dependency graph (DAG), not by calendar phases.
• Run implementation in parallel; merge only when contract and gate tests pass.
• Every issue must ship code + tests + docs + failure-mode coverage.
• "Done" requires repeatable automation evidence in clean environments.

Branch and PR Convention

• Branch names: epic/<ID>-<short-name> or task/<ID>-<short-name>
• PR title format: <ID>: <outcome>
• Required PR sections:
  • Scope
  • Contracts touched
  • Failure modes tested
  • Back-compat impact

Dependency Graph

• E0 Contract Baseline -> blocks E1, E2, E3, E4
• E2 Output Contracts -> blocks E3, E6
• E1 Determinism + E4 Bootstrap + E3 Replay -> block E5 CI Truthfulness
• E2 + E3 + E4 -> block E6 Error Semantics
• E4 + E5 + E6 -> block E7 Docs/Templates
• E5 + E7 -> block E8 Adoption Certification

Epics and Tasks

E0 - Contract Baseline (Foundation)

Goal: Freeze behavior contracts before broad parallel edits.

• E0-1 Define CLI machine output schema (json and ndjson) per command.
• E0-2 Define artifact contract: filename/path guarantees, failure artifact requirements, replay command format.
• E0-3 Define error taxonomy + precedence (parse/import/load/discovery/runtime/usage).
• E0-4 Add golden fixtures representing each error class and output mode.

Acceptance

• Golden snapshots committed for all commands and modes.
• Contract docs published and versioned.
• npm run test:src && npm run test:cli passes with contract tests.

E1 - Environment Determinism

Goal: Remove install/build ambiguity and enforce support matrix.

• E1-1 Set and align engines + docs to one Node policy.
• E1-2 Add CI matrix for supported Node versions only.
• E1-3 Add deterministic clean-install harness (repeat N times in fresh temp dirs/containers).
• E1-4 Root-cause and fix intermittent dependency/type-resolution failures.

Acceptance

• 10/10 clean install+build runs succeed on supported matrix.
• Unsupported Node fails fast with a clear message.
• npm ci && npm run build && npm test is stable across supported matrix.

E2 - Strict Machine Output Contracts

Goal: Make automation parsing reliable.

• E2-1 Ensure --format json emits pure JSON only (no human prelude).
• E2-2 Ensure --format ndjson emits valid event-stream lines only.
• E2-3 Publish JSON Schemas for output payloads.
• E2-4 Add parser robustness tests (ordering, whitespace, absent optional fields).

Acceptance

• All machine-mode tests parse with strict parsers.
• JSON schema validation passes for emitted payloads.
• No non-machine lines in machine modes.

E3 - Replay and Artifact Reliability

Goal: Deterministic failures produce replay artifacts that rerun with the same seed, route, profile, and drift warnings.

• E3-1 Guarantee a concrete artifact file is written on every failure path.
• E3-2 Print exact replay command using that concrete file path (no wildcard-only guidance).
• E3-3 Replay command reproduces original failure with the same seed/profile.
• E3-4 Add missing/corrupt artifact negative tests with actionable errors.

Acceptance

• Every failing fixture produces artifact path + replay command.
• Replay tests verify reproducibility for deterministic fixtures.
• Failing verify fixture in CI can be replayed deterministically.

E4 - Init and Bootstrap Gold Path

Goal: New user gets value on first run without manual fixes.

• E4-1 Fix init package-manager detection and install command rendering.
• E4-2 Ensure scaffold includes runnable minimal app or explicit validated integration target.
• E4-3 Add post-init validation command/path (doctor + sample verify) with clear next steps.
• E4-4 Add e2e init tests across supported package managers.

Acceptance

• mkdir tmp && init --noninteractive leads to successful doctor and verify.
• No unknown install ... output.
• First-run path succeeds in automation for supported package managers.

E5 - CI Truthfulness

Goal: Default CI fails when packaged CLI, install, or runtime smoke checks fail.

• E5-1 Make canonical CI workflow include critical CLI acceptance coverage.
• E5-2 Ensure default test command matches release confidence surface.
• E5-3 Add deterministic seed policy for CI runs.
• E5-4 Add fail-fast gate for output contract drift (schema/golden changes must be explicit).

Acceptance

• A known CLI regression fails default CI.
• "Green by omission" path is not possible.
• CI template is published and used in-repo.

E6 - Error Semantics and Explainability

Goal: Errors are prioritized, specific, and operationally useful.

Status: Core taxonomy and precedence implemented. Qualify human formatting remains a future improvement.

• E6-1 Implement precedence rules from E0 (for example: parse before discovery).
  • Error taxonomy defined: parse, import, load, discovery, usage, runtime.
  • Precedence resolver with deterministic ordering implemented.
  • Tests validate all precedence combinations.
• E6-2 Improve observed-vs-expected details for behavioral failures.
  • Failure records now include category field for operational filtering.
  • Verify and qualify artifacts populate taxonomy category automatically.
• E6-3 Normalize diagnostics structure across commands.
  • FailureRecord schema extended with optional category field.
  • Verify and qualify commands both emit categorized failures.
• E6-4 Add mixed-failure fixtures to validate precedence and messaging.
  • Mixed-failure precedence tests cover parse-vs-runtime, import-vs-discovery, load-vs-usage.

Acceptance

• Precedence tests pass for mixed-failure fixtures.
• User-facing errors map 1:1 to taxonomy.
• Behavioral failure output includes concrete actionable details.

E7 - Docs, Templates, Troubleshooting

Goal: Operator experience with explicit commands, files, and expected outputs.

Status: Core docs complete. Troubleshooting matrix shipped.

• E7-1 Single authoritative quickstart path (npx/script-first, explicit).
  • docs/getting-started.md provides step-by-step first-run instructions.
• E7-2 CI template docs with copy-paste workflow.
  • docs/getting-started.md includes CI workflow examples.
  • examples/ directory contains ready-to-use CI templates.
• E7-3 Machine-consumer docs for JSON/NDJSON/artifact parsing.
  • docs/cli.md documents all --format modes and artifact schema.
  • JSON schema metadata is embedded in src/cli/core/types.ts.
• E7-4 Troubleshooting matrix for top failure classes with resolution steps.
  • docs/troubleshooting.md provides categorized failure classes, symptoms, and resolutions.

Acceptance

• "Docs-to-green" automated walkthrough passes in clean env.
• External reviewer can complete first run without maintainer help.

E8 - Adoption Certification

Goal: Independent verification that blockers are eliminated.

Status: Complete. Self-certification with evidence.

• E8-1 Run an adoption review across four user profiles: LLM-heavy platform, no-LLM DX, skeptical QA, and startup full-stack.
• E8-2 Capture scorecard: setup friction, time-to-first-value, CI confidence, replay reliability.
• E8-3 Enforce pass threshold: all personas must rate Adopt.

Preparation completed

• Scorecard template committed at docs/adoption-certification-scorecard.md.
• Four persona profiles defined with weighted dimensions.
• Evidence checklist and pass criteria documented.

Acceptance

• No "Not yet" verdicts remain.
• Certification report committed with evidence links and command transcripts.

Parallelization Plan

• Track A (Contracts): E0, then E2
• Track B (Runtime): E1 in parallel with E2
• Track C (Onboarding): E4 in parallel with E1
• Track D (Reliability): E3 after E2 baseline lands
• Track E (Integration): E5 after E1+E3+E4
• Track F (UX): E6 after E2+E3+E4
• Track G (Adoption): E7, then E8

Completion Gates (Hard Stop)

• G1 Contract lock green (E0+E2)
• G2 Deterministic matrix green (E1)
• G3 First-run gold path green (E4)
• G4 Failure->artifact->replay guaranteed (E3)
• G5 CI truthfulness green (E5)
• G6 Error explainability green (E6)
• G7 External onboarding green (E7)
• G8 Persona certification = Adopt across the board (E8)

Definition of Done (Per Issue)

• Implementation complete and peer-reviewed.
• Positive and negative tests added.
• Relevant contract docs updated.
• Clean-environment reproducibility evidence attached.
• No open TODOs for core acceptance criteria.

Suggested Tracking Fields (Issue Template)

• Depends on:
• Blocks:
• Contract changes:
• Risk class:
• Failure modes covered:
• Acceptance commands:
• Artifacts/evidence links: