Description
specs/README.md's index table references spec paths by number (e.g. 017-output-filtering/spec.md, 039-vault/spec.md, 051-security-capability-governance/spec.md) that no longer match the actual directory numbers under specs/. This was independently flagged by two agents during patch-release prep (2026-07-15) while auditing per-crate AGENTS.md files against their spec pointers.
A full diff (README-referenced number vs actual on-disk directory) turned up 36 mismatched entries, e.g.:
- README:
017-output-filtering -> actual: 016-output-filtering
- README:
039-vault -> actual: 038-vault
- README:
041-sanitizer -> actual: 040-sanitizer
- README:
043-zeph-commands -> actual: 042-zeph-commands
- README:
051-security-capability-governance -> actual: 050-security-capability-governance
- (31 more entries in the 017-056 range, all off by a consistent -1, then diverging further past ~056)
Additionally, the numbering scheme itself has collisions on disk (two different specs sharing the same number): 016-agent-feedback / 016-output-filtering, 057-agent-persistence / 057-autoskill-versioned-merging, 058-autoskill-query-rewriting / 058-plugins.
Reproduction Steps
ls specs/ | grep -E '^0[0-9]{2}-' | sortgrep -oE '[0-9]{3}-[a-z0-9-]+/spec\.md' specs/README.md | sort -u- Diff the two lists — most entries in the 017-056 range don't resolve to an existing path.
Expected Behavior
Every spec path referenced in specs/README.md resolves to an existing specs/<N>-<slug>/spec.md file, and each on-disk spec number is unique.
Actual Behavior
specs/README.md is the mandatory entry point per CLAUDE.md ("Before implementing any feature: read the relevant spec... Index: specs/README.md"). A contributor following a stale reference lands on the wrong subsystem's spec, or a 404. This has already caused at least one confirmed real-world instance: shipped rustdoc in crates/zeph-common/src/memory.rs / crates/zeph-config/src/memory/retrieval.rs cites "spec 064 Β§4" for the MemGuard type-aware-retrieval feature, but permanent spec slot 064 is actually 064-durable-execution — an unrelated subsystem.
Environment
- Version: main @ c50c4a3 (pre-v0.22.1 patch release)
- Features: N/A (docs-only)
Notes
This is pre-existing drift accumulated over many releases, not something introduced by the current release's commits. Fixing it properly requires reconciling each README section's description against its actual target directory's content (not a blind renumber), so it's being filed for a dedicated follow-up rather than rushed during release prep.
Description
specs/README.md's index table references spec paths by number (e.g.017-output-filtering/spec.md,039-vault/spec.md,051-security-capability-governance/spec.md) that no longer match the actual directory numbers underspecs/. This was independently flagged by two agents during patch-release prep (2026-07-15) while auditing per-crateAGENTS.mdfiles against their spec pointers.A full diff (README-referenced number vs actual on-disk directory) turned up 36 mismatched entries, e.g.:
017-output-filtering-> actual:016-output-filtering039-vault-> actual:038-vault041-sanitizer-> actual:040-sanitizer043-zeph-commands-> actual:042-zeph-commands051-security-capability-governance-> actual:050-security-capability-governanceAdditionally, the numbering scheme itself has collisions on disk (two different specs sharing the same number):
016-agent-feedback/016-output-filtering,057-agent-persistence/057-autoskill-versioned-merging,058-autoskill-query-rewriting/058-plugins.Reproduction Steps
ls specs/ | grep -E '^0[0-9]{2}-' | sortgrep -oE '[0-9]{3}-[a-z0-9-]+/spec\.md' specs/README.md | sort -uExpected Behavior
Every spec path referenced in
specs/README.mdresolves to an existingspecs/<N>-<slug>/spec.mdfile, and each on-disk spec number is unique.Actual Behavior
specs/README.mdis the mandatory entry point perCLAUDE.md("Before implementing any feature: read the relevant spec... Index: specs/README.md"). A contributor following a stale reference lands on the wrong subsystem's spec, or a 404. This has already caused at least one confirmed real-world instance: shipped rustdoc incrates/zeph-common/src/memory.rs/crates/zeph-config/src/memory/retrieval.rscites "spec 064 Β§4" for the MemGuard type-aware-retrieval feature, but permanent spec slot064is actually064-durable-execution— an unrelated subsystem.Environment
Notes
This is pre-existing drift accumulated over many releases, not something introduced by the current release's commits. Fixing it properly requires reconciling each README section's description against its actual target directory's content (not a blind renumber), so it's being filed for a dedicated follow-up rather than rushed during release prep.