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:

- [x] Command transcripts for each persona's first-run experience
- [x] CI workflow files used during review
- [x] Artifact files from failing runs (to verify replay)
- [x] Screenshots or text captures of doctor/verify output
- [x] 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)
```bash
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)
```bash
npx apophis verify --seed 42 --depth quick
# On failure:
npx apophis replay --artifact apophis-artifacts/verify-*.json
```

### CI Workflow (example)
```yaml
- 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