# Missing-spec runbook 24 packages either lack a folded `openspec/specs//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//` 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//spec.md` to `openspec/specs//spec.md`. 2. Verify the spec uses `### Requirement: ` heading style; rewrite if not. 3. Add `**Verified by:**` lines under every requirement. The implementations and tests already exist in `packages/crypto//`. 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/` — 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/.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/.md` end-to-end. 2. Read the genesis implementation under `packages///src/`. 3. Read existing tests to know what scenarios are already pinned. 4. Create `openspec/changes/-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//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/` - `bunx turbo test:coverage --filter=@suaveplan/` — 100/100/100/100 - `bun scripts/openspec-conformance.ts @suaveplan/` — 0 errors - `bunx turbo build --filter=@suaveplan/` 7. Fold spec delta into `openspec/specs//spec.md`. Move change folder to `openspec/archive/-/`. ### 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/.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//src/`. 2. Read the package's `CLAUDE.md` blurb (in `packages` listing) for intent. 3. Create `openspec/changes/-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`, `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//spec.md` where `` 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`. 2. In the per-package routine, look up `` in the map. Default to `[]`. 3. For each cap in the resolved list: - Check `openspec/specs//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//spec.md`), also iterate the resolved cap list rather than hard-coding ``. 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//`. --- ## 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*.