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

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).