Initial Commit
This commit is contained in:
153
openspec/templates/missing-specs-runbook.md
Normal file
153
openspec/templates/missing-specs-runbook.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# 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/<pkg>.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*.
|
||||
Reference in New Issue
Block a user