suaveplan/openspec/templates/missing-specs-runbook.md

Missing-spec runbook

24 packages either lack a folded openspec/specs/<cap>/spec.md entirely or have one that the conformance script cannot find for them. This runbook groups them by remediation type so an agent can work them in dependency order without re-discovering the categorisation.

For every group: read openspec/AGENTS.md Sections 13 and 14 first. Use templates in openspec/templates/. The 4-gate triple in CLAUDE.md "Pre-publish gate" applies.

---

Group 1 — Fold existing archive specs (4 packages)

These packages have specs in openspec/archive/2026-04-18-enterprise-crypto-family/specs/<cap>/ that were never folded into openspec/specs/. Mechanical archival cleanup — no spec writing needed.

Package	Archive cap → fold to
crypto-browser	crypto-browser-engine → openspec/specs/crypto-browser-engine/spec.md
crypto-keys	crypto-keys → openspec/specs/crypto-keys/spec.md
crypto-sodium	crypto-sodium-engine → openspec/specs/crypto-sodium-engine/spec.md
crypto-vault	crypto-vault → openspec/specs/crypto-vault/spec.md

Per-package steps

1. Copy openspec/archive/2026-04-18-enterprise-crypto-family/specs/<cap>/spec.md to openspec/specs/<cap>/spec.md.
2. Verify the spec uses ### Requirement: <name> heading style; rewrite if not.
3. Add **Verified by:** lines under every requirement. The implementations and tests already exist in packages/crypto/<pkg>/. Map scenarios to it(...) titles.
4. Confirm openspec/package-cap-map.yml has the entry (already populated for crypto-browser and crypto-sodium).
5. Run bun scripts/openspec-conformance.ts @suaveplan/<pkg> — must be 0 errors. Plus the standard 4-gate triple.
6. No new OpenSpec change folder needed (this is a fold, not a contract change). Note the fold in a single chore: fold archived crypto-family specs commit.

---

Group 2 — Package→cap mapping only (2 packages)

Package	Reason script missed it
random	Owns 4 caps (random-utilities, seeded-prng, noise-functions, statistical-distributions) — script defaulted to single-cap lookup
readline	Specified inside cli cap — script defaulted to looking for a readline cap

Per-package steps

1. Confirm openspec/package-cap-map.yml lists the package's caps (both already added).
2. Confirm the conformance script honors the YAML (see "Script integration" below).
3. Run conformance — should now find the spec.
4. If any of the mapped caps lack **Verified by:** lines, treat as Group 5 (annotation only) for that cap.

---

Group 3 — Brand-new specs from enterprise source (15 packages)

Each package has a canonical source at ../suaveplan/enterprise/<pkg>.md. Per AGENTS.md Section 14, every requirement must cite a line range in the source.

Package	Genesis path	Enterprise source
db	packages/database/db/	../suaveplan/enterprise/db.md
db-sqlite	packages/database/db-sqlite/	../suaveplan/enterprise/db-sqlite.md
storage	packages/storage/storage/	../suaveplan/enterprise/storage.md
streams	packages/flow/streams/	../suaveplan/enterprise/streams.md
qrcode	packages/barcode/qrcode/	../suaveplan/enterprise/qrcode.md
barcode	packages/barcode/barcode/	../suaveplan/enterprise/barcode.md
api-schemas	packages/api/api-schemas/	../suaveplan/enterprise/api-schemas.md
fsm	packages/flow/fsm/	../suaveplan/enterprise/fsm.md
domain-normalizer	packages/emails/domain-normalizer/	../suaveplan/enterprise/domain-normalizer.md
suppression	packages/emails/suppression/	../suaveplan/enterprise/suppression.md
compress-image	packages/image/compress-image/	../suaveplan/enterprise/compress-image.md
metadata	packages/audio/metadata/	../suaveplan/enterprise/metadata.md
diff	packages/data/diff/	../suaveplan/enterprise/diff.md
password-formats	packages/crypto/password-formats/	../suaveplan/enterprise/password-formats.md
security-codes	packages/platform/security-codes/	../suaveplan/enterprise/security-codes.md

Per-package steps

1. Read ../suaveplan/enterprise/<pkg>.md end-to-end.
2. Read the genesis implementation under packages/<plugin>/<pkg>/src/.
3. Read existing tests to know what scenarios are already pinned.
4. Create openspec/changes/<pkg>-spec-init/ from openspec/templates/:
   • proposal.md with ## Source mapping table covering every requirement (line ranges in enterprise source) and a ## Requirements with no source line table for genesis-only additions (e.g. 100% coverage policy).
   • tasks.md with the standard 7-section structure.
   • specs/<cap>/spec.md with ### Requirement: blocks. Every requirement carries **Verified by:** at authoring time.
5. If the spec exposes drift (e.g. enterprise source mandates an OTel histogram the impl doesn't emit), fix inline — do not defer. Standard from prior conformance audits.
6. Run the 4-gate triple:
   • bunx turbo lint typecheck test --filter=@suaveplan/<pkg>
   • bunx turbo test:coverage --filter=@suaveplan/<pkg> — 100/100/100/100
   • bun scripts/openspec-conformance.ts @suaveplan/<pkg> — 0 errors
   • bunx turbo build --filter=@suaveplan/<pkg>
7. Fold spec delta into openspec/specs/<cap>/spec.md. Move change folder to openspec/archive/<yyyy-mm-dd>-<change-id>/.

Suggested order (foundation first)

1. db (substrate for db-sqlite, surrealdb, etc.)
2. db-sqlite (depends on db)
3. streams (substrate for many media/data packages)
4. storage (depends on streams)
5. fsm (control-flow leaf with broad fan-in)
6. diff (leaf, used by undo/sync packages)
7. domain-normalizer, suppression, security-codes (leaves)
8. qrcode, barcode (codes leaves)
9. api-schemas (depends on validation)
10. compress-image, metadata (media leaves)
11. password-formats (security leaf)

---

Group 4 — Genesis-original specs (no enterprise source) (7 packages)

These have no ../suaveplan/enterprise/<pkg>.md and need specs derived from the implementation.

Package	Genesis path
testing-integration	packages/testing/testing-integration/
testing-integration-garage-s3	packages/testing/testing-integration-garage-s3/
testing-integration-mailpit	packages/testing/testing-integration-mailpit/
testing-integration-postgres	packages/testing/testing-integration-postgres/
testing-integration-redis	packages/testing/testing-integration-redis/
testing-integration-surrealdb	packages/testing/testing-integration-surrealdb/
testing-integration-typesense	packages/testing/testing-integration-typesense/

Per-package steps

1. Read the genesis implementation under packages/testing/<pkg>/src/.
2. Read the package's CLAUDE.md blurb (in packages listing) for intent.
3. Create openspec/changes/<pkg>-spec-init/ from templates.
4. In proposal.md:
   • ## Source mapping is required even with no source. Every requirement appears in the second table (## Requirements with no source line) with a justification — typically "Derived from genesis-original implementation; no enterprise/.md predecessor."
   • In a ## Design rationale section (add to the template if absent), explain why this is genesis-original and what design decisions shape the contract.
5. Draft specs/testing-integration*/spec.md with ### Requirement: blocks for every observable behavior. Every requirement carries **Verified by:**.
6. Run the 4-gate triple. Fold and archive.

Suggested order

1. testing-integration (core — ServiceFixture<TConfig>, TestEnvironment, HealthPoller, skipIfUnavailable).
2. The 6 adapters in any order (they depend on the core but not on each other).

---

Script integration — package-cap-map.yml lookup

The conformance script (scripts/openspec-conformance.ts) currently searches for openspec/specs/<bare>/spec.md where <bare> is the package's short name. To honour openspec/package-cap-map.yml:

1. At script start, load openspec/package-cap-map.yml once. Parse to a Record<string, string[]>.
2. In the per-package routine, look up <bare> in the map. Default to [<bare>].
3. For each cap in the resolved list:
   • Check openspec/specs/<cap>/spec.md exists and parses.
   • Run all spec-side checks (Verified-by lines, retroactive ticking, etc.) against that file.
   • Aggregate findings under the same package report.
4. For change-folder matching (openspec/changes/*/specs/<cap>/spec.md), also iterate the resolved cap list rather than hard-coding <bare>.

This is a small refactor — the existing findRelatedChangeFolders function already reads **Package**: frontmatter; it just needs to also accept any of the package's caps when matching specs/<cap>/.

---

Out of scope for the runbook

• The 11 packages reclassified by the Batch C agent as "spec.md missing entirely" (qrcode, barcode, api-schemas, fsm, domain-normalizer, suppression, compress-image, metadata, diff, password-formats, security-codes) are now in Group 3 of this runbook — they have enterprise source. The runbook supersedes the prior reclassification.
• enterprise-package-migration skill in .claude/skills/ already covers Group 3 + 4 workflows. This runbook is the triage list; the skill is the execution playbook.