55 lines
4.8 KiB
Markdown
55 lines
4.8 KiB
Markdown
## 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).
|