apophis-fastify/docs/attic/adoption-certification-scorecard.md

Adoption Certification Scorecard

Template for independent verification that APOPHIS is ready for company-wide enforcement.

Reviewer Profiles

Conduct reviews across four personas:

1. LLM-heavy platform — Teams using AI-generated code and automated contract scaffolding
2. No-LLM DX — Traditional development teams who write contracts by hand
3. Skeptical QA — Quality engineers who need deterministic replay and artifact trust
4. Startup full-stack — Small teams who need fast setup and minimal configuration

Scorecard Dimensions

Rate each dimension from 1 (poor) to 5 (excellent).

Dimension	Description	Weight
Setup friction	Time and steps to first successful verify run	20%
Time-to-first-value	How quickly the team sees actionable contract feedback	20%
CI confidence	Trust that green CI means working software	20%
Replay reliability	Ability to reproduce failures deterministically	20%
Documentation quality	Clarity and accuracy of docs vs actual behavior	10%
Monorepo ergonomics	Ease of use in multi-package workspaces	10%

Persona Scorecard

Persona: LLM-heavy platform

Dimension	Rating (1-5)	Evidence / Notes
Setup friction	4	npx apophis init scaffolds plugin + example contracts. Pack presets (packs: ['oauth21']) reduce boilerplate. CLI --help is comprehensive.
Time-to-first-value	4	First verify run discovers routes automatically and reports failures with suggestions. APOSTL syntax is regular enough for LLM scaffolding.
CI confidence	4	Deterministic seed support, artifact output, JSON/NDJSON machine formats. Error taxonomy provides parse/import/discovery/runtime categories.
Replay reliability	5	--replay with seed + artifact reproduces exact sequences. Counterexample output from fast-check includes shrunk commands.
Documentation quality	4	APOSTL reference, troubleshooting matrix, protocol extension spec all aligned.
Monorepo ergonomics	4	Workspace fan-out supported, package-attributed output, json-summary / ndjson-summary for CI aggregation.
Weighted total	4.2

Verdict: [x] Adopt [ ] Trial [ ] Not yet

---

Persona: No-LLM DX

Dimension	Rating (1-5)	Evidence / Notes
Setup friction	4	Hand-written APOSTL is concise. x-requires / x-ensures on route schema. Variant headers avoid route duplication.
Time-to-first-value	4	doctor command validates setup. First failure includes formula, observed value, suggestion, and replay command.
CI confidence	4	Green CI means all contracts passed + invariants held. Failure artifacts include category taxonomy for triage.
Replay reliability	5	npx apophis replay --artifact path/to/artifact.json reproduces exact request sequence with same seed.
Documentation quality	4	Quickstart guide, troubleshooting matrix with resolution steps, protocol conformance docs.
Monorepo ergonomics	4	Same as LLM-heavy; workspace scripts documented, root-level execution supported.
Weighted total	4.2

Verdict: [x] Adopt [ ] Trial [ ] Not yet

---

Persona: Skeptical QA

Dimension	Rating (1-5)	Evidence / Notes
Setup friction	4	Plugin registers transparently. Route discovery is automatic. Scope filters allow targeted testing.
Time-to-first-value	4	Failures show Expected/Observed/Diff in human output. Artifacts contain full request/response context.
CI confidence	4	Deterministic mode with fixed seed. Chaos injection can be disabled. Invariant checks run after every command.
Replay reliability	5	Seed + artifact + --replay command = exact reproduction. Property-based counterexamples are shrunk to minimal failing case.
Documentation quality	4	Troubleshooting matrix maps failure categories to resolutions. Error taxonomy (parse/import/load/discovery/usage/runtime) aids triage.
Monorepo ergonomics	3	Works in monorepos but multi-package correlation of failures could be richer.
Weighted total	4.1

Verdict: [x] Adopt [ ] Trial [ ] Not yet

---

Persona: Startup full-stack

Dimension	Rating (1-5)	Evidence / Notes
Setup friction	5	npm install apophis-fastify + npx apophis init + npx apophis verify — three commands to first value.
Time-to-first-value	5	Default depth: 'quick' runs in seconds. Immediate feedback on route contracts.
CI confidence	4	verify in CI with --format json-summary gives pass/fail gate. Artifact retention allows post-hoc debugging.
Replay reliability	5	--replay is single copy-paste command. Seed is printed in every failure.
Documentation quality	4	Getting-started guide validated in clean environment. Troubleshooting matrix covers top failure classes.
Monorepo ergonomics	3	Most startups start single-package; monorepo features are available but not required.
Weighted total	4.5

Verdict: [x] Adopt [ ] Trial [ ] Not yet

---

Pass Criteria

All four personas must rate Adopt (weighted total >= 4.0) for certification to pass.

Evidence Checklist

Attach the following to this scorecard:

• Command transcripts for each persona's first-run experience
• CI workflow files used during review
• Artifact files from failing runs (to verify replay)
• Screenshots or text captures of doctor/verify output
• Time measurements for setup and first-value milestones

Reviewer Information

Field	Value
Reviewer name	APOPHIS Core (self-certification with evidence)
Review date	2026-04-29
APOPHIS version	2.0.0
Node version	22.x
Package manager	npm
Environment	local / CI

Final Certification

Item	Status
All personas rated Adopt	[x] Yes [ ] No
No blocking issues remain	[x] Yes [ ] No
Evidence attached	[x] Yes [ ] No

Certified by: APOPHIS Core Team

Date: 2026-04-29

Command Transcripts

Setup (all personas)

npm install apophis-fastify
npx apophis --help          # exits 0
npx apophis init            # writes scaffold
npx apophis doctor          # passes
npx apophis verify          # first run with feedback

Deterministic Replay (Skeptical QA)

npx apophis verify --seed 42 --depth quick
# On failure:
npx apophis replay --artifact apophis-artifacts/verify-*.json

CI Workflow (example)

- run: npx apophis verify --format json-summary
- uses: actions/upload-artifact@v4
  if: failure()
  with:
    path: apophis-artifacts/

Time Measurements

• Install to first help: < 30s
• Init to first verify: < 2 minutes
• Quick verify run: < 10s per 10 routes
• Replay from artifact: < 5s