Skip to content

docs(specs): fix README.md spec-number index drift and resolve collisions#6312

Merged
bug-ops merged 1 commit into
mainfrom
fix/6308-specs-readme-drift
Jul 16, 2026
Merged

docs(specs): fix README.md spec-number index drift and resolve collisions#6312
bug-ops merged 1 commit into
mainfrom
fix/6308-specs-readme-drift

Conversation

@bug-ops

@bug-ops bug-ops commented Jul 16, 2026

Copy link
Copy Markdown
Owner

Summary

  • specs/README.md's Feature Docs table had drifted from the actual specs/ directory numbers across ~38 entries (the 017–056 range, off by one to two) — a contributor following the documented index would land on the wrong spec or a 404.
  • Three spec numbers were double-assigned on disk: 016 (agent-feedback / output-filtering), 057 (agent-persistence / autoskill-versioned-merging), 058 (plugins / autoskill-query-rewriting). Renumbered the newer/less-cross-referenced directory in each pair — 016-agent-feedback054-agent-feedback (fills a pre-existing gap), 057-agent-persistence078-agent-persistence, 058-plugins079-plugins — and updated every cross-reference (specs/, AGENTS.md files, CHANGELOG.md path mentions, spec wikilinks). The AutoSkill A1–A6 (056–061) and Gonka/SpeculationEngine numbering runs were kept intact since they're internally cross-referenced by number in code and other specs.
  • Corrected ~30 rustdoc citations across zeph-config, zeph-context, zeph-memory, zeph-agent-context, zeph-common, zeph-core, and src/init/mod.rs that mistakenly cited spec 064 (the permanent durable-execution slot) when they meant the MemGuard type-aware-retrieval spec at 004-memory/004-16-memory-type-aware-retrieval.md — a naming collision that spec's own info-callout already flagged as a known issue "for a future doc-only follow-up." Left the legitimate durable-execution spec 064/spec-064 citations in the same files untouched.
  • Fixed a stray 018-index017-index reference in specs/MOC-specs.md.
  • Added two previously-missing Feature Docs table rows for the renamed 078-agent-persistence and 079-plugins specs.
  • Updated the "Housekeeping Note" in specs/064-durable-execution/spec.md to reflect that the collisions it flagged as out-of-scope are now resolved.

Docs-only change — no runtime logic modified, only doc/rustdoc comment text and directory names.

Closes #6308

Test plan

  • cargo +nightly fmt --check
  • cargo clippy --profile ci --workspace --all-targets --features "desktop,ide,server,chat,pdf,scheduler,testing" -- -D warnings
  • cargo nextest run --config-file .github/nextest.toml --workspace --features "desktop,ide,server,chat,pdf,scheduler" --lib --bins (13792 passed; one unrelated timing-based concurrency test flaked once under load, confirmed passing in isolation and on a clean re-run of the full suite)
  • RUSTFLAGS="-D warnings" RUSTDOCFLAGS="--deny rustdoc::broken_intra_doc_links" cargo doc --no-deps --workspace --features desktop,ide,server,chat,pdf,scheduler
  • gitleaks protect --staged --no-banner --redact
  • Verified zero duplicate spec numbers remain on disk and every path referenced in specs/README.md resolves to an existing file

@github-actions github-actions Bot added documentation Improvements or additions to documentation memory zeph-memory crate (SQLite) rust Rust code changes core zeph-core crate size/L Large PR (201-500 lines) labels Jul 16, 2026
…ions

specs/README.md's Feature Docs table had drifted from the actual specs/
directory numbers across ~38 entries (017-056 range, off by one to two).
Additionally three spec numbers were double-assigned on disk (016, 057,
058). Renumber the newer directory in each colliding pair (016-agent-
feedback -> 054-agent-feedback, 057-agent-persistence -> 078-agent-
persistence, 058-plugins -> 079-plugins) and update every cross-reference
across specs/, AGENTS.md files, CHANGELOG.md, and rustdoc comments.

Also correct a batch of rustdoc citations that mistakenly referenced
"spec 064" (the permanent durable-execution slot) when they meant the
MemGuard type-aware-retrieval spec at 004-memory/004-16; the collision
was already flagged as a known issue in that spec's own info-callout.

Closes #6308
@bug-ops
bug-ops enabled auto-merge (squash) July 16, 2026 16:38
@bug-ops
bug-ops force-pushed the fix/6308-specs-readme-drift branch from eba2bcb to f1be670 Compare July 16, 2026 16:38
@bug-ops
bug-ops merged commit 77442b1 into main Jul 16, 2026
47 checks passed
@bug-ops
bug-ops deleted the fix/6308-specs-readme-drift branch July 16, 2026 16:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

core zeph-core crate documentation Improvements or additions to documentation memory zeph-memory crate (SQLite) rust Rust code changes size/L Large PR (201-500 lines)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

specs/README.md spec-number index drifted from actual specs/ directory names

1 participant