Initial Commit

openspec/changes/corpus-spec-hygiene/proposal.md

@@ -0,0 +1,54 @@
+## Why
+
+`openspec validate --specs --strict` reports 43 ✗ items across the live spec corpus. Every failure is structural — missing `# Title`, missing `## Purpose`, leftover delta-format headers (`## ADDED Requirements`, `## MODIFIED Requirements`, `**Status**: PROPOSED`, `# Capability Spec Delta: ...`). None of the failures are about wrong requirement content, missing tests, or behaviour drift; they are residue from past archive operations whose fold step never converted delta documents into live-spec format.
+
+This is the same failure mode that `types-spec-scenario-backfill` and `spec-hygiene-crypto-utils-typesense` already fixed for 3 specs. Closing the remaining 43 in one sweep:
+
+1. Restores `openspec validate --specs --strict` to fully green for the entire corpus.
+2. Removes a class of papercut where every future spec change risks aborting at the post-fold validation step against a sibling-corpus that's already malformed.
+3. Eliminates ambiguity for downstream tooling (capability dashboards, CI gates, doc generators) that assume live-spec format.
+
+The fix per spec is mechanical:
+
+- **Title (`# <capability-name>`)**: required at line 1; some specs inherited `# Capability Spec Delta: <name> (<change-name>)` from an unfolded archive.
+- **Purpose section (`## Purpose <paragraph>`)**: required immediately after title. Most specs have none.
+- **Requirements section (`## Requirements`)**: required exactly once. Some specs have `## ADDED Requirements` (delta-format leftover); a few have both `## Requirements` and a stray `## ADDED` / `## MODIFIED Requirements` block.
+- **Live-spec metadata only**: `**Status**: PROPOSED` and `**Package**: ...` belong only inside change folders; both must be removed from live specs.
+
+No requirement text, scenario content, or `**Verified by:**` pointer is changed. Every cited test continues to exist and pass.
+
+## What Changes
+
+- **MODIFIED 43 capabilities**: structural-cleanup of every live spec listed below. Per-spec changes:
+  - Add `# <capability-name>` title where missing.
+  - Add `## Purpose` paragraph (sourced from the package's `package.json` description and CLAUDE.md package listing where one exists; otherwise inferred from existing requirement text).
+  - Delete leftover `**Status**: PROPOSED`, `**Package**: ...`, `# Capability Spec Delta: ...` metadata.
+  - Rename leftover `## ADDED Requirements` / `## MODIFIED Requirements` to `## Requirements` (or merge into existing `## Requirements` block).
+- This change is **spec-only**. No source code changes, no test changes, no consumer changes. Per the openspec convention re-affirmed by `crypto-spec-restore-versioning`: zero source touch when the live spec is already supported by passing tests; only fix the spec-corpus structure.
+
+The 43 affected capabilities (alphabetical):
+
+`bytes`, `config`, `datetime`, `drive`, `env`, `error`, `events`, `i18n`, `idempotency`, `install-agent-skills`, `installer`, `json`, `locale-data`, `logging`, `mime`, `monorepo-structure`, `network`, `network-session`, `network-webrtc`, `noise-functions`, `packer`, `pagination`, `random-utilities`, `retry`, `seeded-prng`, `serialization`, `slsa`, `statistical-distributions`, `storage`, `templates`, `testing`, `testing-dom`, `testing-e2e`, `testing-integration`, `testing-integration-garage-s3`, `testing-integration-mailpit`, `testing-integration-postgres`, `testing-integration-redis`, `testing-integration-surrealdb`, `timing`, `undo`, `utils`, `validation`.
+
+## Capabilities
+
+### New Capabilities
+
+(none)
+
+### Modified Capabilities
+
+All 43 capabilities listed above. Zero requirements added, modified at the semantic level, or removed.
+
+## Impact
+
+- **Affected specs**: 43 files under `openspec/specs/`.
+- **Affected code**: none.
+- **Affected tests**: none. Every cited `**Verified by:**` pointer remains intact.
+- **Conformance impact**: `openspec validate --specs --strict` flips to fully green across the corpus. The existing 10 ✓ specs (the ones already in good shape) stay ✓.
+- **Downstream**: future spec changes can land cleanly through `openspec archive` against any capability without aborting at post-fold validation.
+- **Risk**: minimal — pure structural rewording of headers; no requirement text changes beyond title and Purpose insertions. Each Purpose paragraph is factually grounded in the package's existing description / requirement text.
+
+## Workflow note
+
+This change does not author per-spec deltas under `openspec/changes/corpus-spec-hygiene/specs/`. Authoring 43 deltas that each say "structural cleanup, no semantic change" would add ceremony without verification value — every spec edit is a verifiable structural transform that the post-fold `openspec validate --strict` gate confirms in one shot. The change is archived with `openspec archive --skip-specs` (the supported-by-CLI workflow for tooling / doc-only changes).

openspec/changes/corpus-spec-hygiene/tasks.md

@@ -0,0 +1,32 @@
+
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## 1. Audit
+
+- [ ] 1.1 Run `openspec validate --specs --strict` and capture the list of 43 ✗ specs.
+- [ ] 1.2 Per-spec audit: title present? purpose present? leftover `## ADDED` / `## MODIFIED` / `**Status**:` / delta-title? Bucket each spec into a fix category.
+
+## 2. Apply fixes via parallel sub-agents (5 batches)
+
+- [ ] 2.1 **Batch A — testing-integration family (6 specs)**: `testing-integration`, `testing-integration-garage-s3`, `testing-integration-mailpit`, `testing-integration-postgres`, `testing-integration-redis`, `testing-integration-surrealdb`. All have `# Capability Spec Delta:` titles, `## ADDED Requirements`, `**Status**: PROPOSED`, no Purpose. Full delta-to-live conversion.
+- [ ] 2.2 **Batch B — testing-infrastructure (4 specs)**: `testing`, `testing-dom`, `testing-e2e`, `monorepo-structure`. All missing title and Purpose. `error`, `events` also missing title.
+- [ ] 2.3 **Batch C — foundation (12 specs)**: `bytes`, `config`, `datetime`, `env`, `error`, `events`, `i18n`, `idempotency`, `json`, `logging`, `pagination`, `retry`, `serialization`, `validation`. Most have title, all missing Purpose; some have `**Status**:` or `## MODIFIED Requirements` to remove.
+- [ ] 2.4 **Batch D — domain (10 specs)**: `drive`, `install-agent-skills`, `installer`, `locale-data`, `mime`, `network`, `network-session`, `network-webrtc`, `noise-functions`, `packer`. All have title, all missing Purpose.
+- [ ] 2.5 **Batch E — primitives + remainder (10 specs)**: `random-utilities`, `seeded-prng`, `slsa`, `statistical-distributions`, `storage`, `templates`, `timing`, `undo`, `utils`. All have title, all missing Purpose; `timing` has `**Status**:` to remove.
+
+## 3. Verify
+
+- [ ] 3.1 `openspec validate --specs --strict` — every previously-failing spec flips to ✓.
+- [ ] 3.2 `openspec validate --specs` — full corpus all ✓.
+- [ ] 3.3 Spot-check 5 random specs: open and confirm the structural rewrite preserved every requirement, scenario, and `**Verified by:**` pointer.
+
+## 4. Archive
+
+- [ ] 4.1 `openspec archive corpus-spec-hygiene --skip-specs --yes` — moves the change folder without re-folding spec deltas (this change has none).
+- [ ] 4.2 Confirm the change appears in `openspec/changes/archive/<yyyy-mm-dd>-corpus-spec-hygiene/`.
+- [ ] 4.3 Confirm `openspec list` no longer shows the change.