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.

- [x] `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.
- [x] `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.
- [x] `E6-3` Normalize diagnostics structure across commands.
  - `FailureRecord` schema extended with optional `category` field.
  - Verify and qualify commands both emit categorized failures.
- [x] `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**

- [x] Precedence tests pass for mixed-failure fixtures.
- [x] User-facing errors map 1:1 to taxonomy.
- [x] 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.

- [x] `E7-1` Single authoritative quickstart path (`npx`/script-first, explicit).
  - `docs/getting-started.md` provides step-by-step first-run instructions.
- [x] `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.
- [x] `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`.
- [x] `E7-4` Troubleshooting matrix for top failure classes with resolution steps.
  - `docs/troubleshooting.md` provides categorized failure classes, symptoms, and resolutions.

**Acceptance**

- [x] "Docs-to-green" automated walkthrough passes in clean env.
- [x] 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.

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

**Preparation completed**

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

**Acceptance**

- [x] No "Not yet" verdicts remain.
- [x] 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:`