apophis/apophis-fastify
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: crush git history - reborn from consolidation on 2026-03-10

Browse Source
This commit is contained in:
John Dvorak
2026-03-10 00:00:00 -07:00
commit d278c4b105
313 changed files with 87549 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/attic/adoption-certification-scorecard.md
+161
View File
@@ -0,0 +1,161 @@
# 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