docs: canonicalize codebase docs — delete duplicate docs/codebase/, fix phantom paths, add path ratchet - #2927
Conversation
…s, add ratchet (#2552) - Delete docs/codebase/ (stale duplicate of docs/reference/codebase/) - Remove dead codebase/** exclusion from mkdocs.yml not_in_nav - Fix ARCHITECTURE.md: remove datalayer_sqlite.py shim row (file deleted); convert bracket-notation flow paths to backtick format for ratchet coverage - Fix STRUCTURE.md: remove phantom case_actor_setup.py row; update plan/ evidence paths (BUILD_LEARNINGS.md / IMPLEMENTATION_PLAN.md removed) - Fix CONVENTIONS.md: update backward-compat example datalayer_sqlite.py -> datalayer_sqlite/ (the package that actually exists) - Fix CONCERNS.md: remove stale datalayer_sqlite.py debt row; update high-churn row (drop deleted planning files); fix case_actor_setup.py ref - Add test/architecture/test_codebase_docs_paths.py: ratchet that extracts backtick-quoted paths from all 7 docs/reference/codebase/*.md files and asserts each exists on disk; strips line-number suffixes; excludes anchor-qualified paths and gitignored ephemeral files Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Document why pytest ratchet was chosen over pre-commit hook for AC-6 - Note that .codebase-scan.txt is intentionally excluded (gitignored generated file; ratchet should not check uncommitted paths) - Reference #2924 for the CI trigger follow-up Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…c-check - Add docs/reference/codebase/** to push/pull_request path filters so docs-only PRs touching these files trigger spec-check (Issue #2924) - Add docs-path-ratchet job that runs test_codebase_docs_paths.py so a phantom path citation introduced in these files fails CI immediately Closes #2924. Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
sei-ahouseholder
left a comment
sei-ahouseholder
left a comment
There was a problem hiding this comment.
PR Triage: #2927 — docs: canonicalize codebase docs — delete duplicate docs/codebase/, fix phantom paths, add path ratchet
Linked issues: #2552 (docs/codebase/ and docs/reference/codebase/ are diverged duplicates), #2924 (feat(ci): add docs-path ratchet to spec-corpus CI gate)
Changed files: 15 files — docs/reference/codebase, .github/workflows, test/architecture, plan/incoming/learnings
CI status: ✅ passing (all 16 checks green)
Merge state: ✅ MERGEABLE (BLOCKED — awaiting required reviewer approval)
Base branch: main
Needs integration tests: no
Findings
| # | Phase | Severity | Description | Outcome |
|---|---|---|---|---|
| phase3-missing-verification-section-0 | pr-body-format | PR adds a .py test file but body has no ## Verification section with test counts |
fix-now | |
| phase12-blocked-merge-state-0 | merge-state | merge_state_status: BLOCKED — awaiting required reviewer approval (not fixable by execute) |
fix-now |
Total: 0 FAIL · 2 IMPROVE · 0 NEW-ISSUE
Triage artifact: .claude/pr-2927-triage.json
Next step: run /pr-execute or /pr-ship to apply fixes.
sei-ahouseholder
left a comment
sei-ahouseholder
left a comment
There was a problem hiding this comment.
PR Execute: #2927
Findings processed: 2 total (1 fixed, 1 skipped)
CI status: ✅ passing (16/16 checks)
Merge state: MERGEABLE · BLOCKED (awaiting required reviewer approval)
Sync commit: 8d54fcb (merged origin/main cleanly)
Finding Outcomes
| Finding | Outcome | Detail |
|---|---|---|
| phase3-missing-verification-section-0 | ✅ fixed | Added ## Verification section to PR body: 8341 tests pass (1 new), all linters clean |
| phase12-blocked-merge-state-0 | ⏭ skipped | Requires human reviewer approval — not fixable by execute |
xfail Check
All 33 xfail markers reviewed. Issue #1991 is closed but the marker explicitly states "supersedes closed #1991" and points to live tracking issues #2288 and #2289 (both open). No unmanaged xfails found.
Execute artifact: .claude/pr-2927-execute.json
Next step: run /pr-verify to produce final verdict.
sei-ahouseholder
left a comment
sei-ahouseholder
left a comment
There was a problem hiding this comment.
PR Verify: #2927 — docs: canonicalize codebase docs — delete duplicate docs/codebase/, fix phantom paths, add path ratchet
Overall verdict: READY-TO-MERGE
Merge state: MERGEABLE (BLOCKED — awaiting required reviewer approval) — base main
CI status: ✅ passing (16/16 checks)
Finding Verdicts
| Finding | Severity | Outcome | Verdict |
|---|---|---|---|
| phase3-missing-verification-section-0 | IMPROVE | fixed | ✅ CONFIRMED — ## Verification section present in PR body |
| phase12-blocked-merge-state-0 | IMPROVE | skipped | 📋 NOTED — BLOCKED status requires reviewer approval; non-blocking on verdict |
Merge State Detail
mergeable: MERGEABLE ✅merge_state_status: BLOCKED — a required review is pending. This is a repo policy gate (not a PR defect) and does not block the verdict.- No conflict markers found in working tree.
- Branch synced with
main(sync commit8d54fcbc).
CI Detail
All 16 checks green on the post-sync run (completed 2026-09-01T14:22:47Z):
- Tests (pytest) ✅ · Codebase Docs Path Ratchet ✅ · docs-build-check ✅
- All lint/type checks ✅ · Spec Corpus Tests ✅ · CodeQL ✅
Artifacts cleaned up.
PR #2927 is READY-TO-MERGE — pending required reviewer approval.
… PRs Replace two `ADR-0073 decision 5` references introduced by PRs #2916 and #2927 while resolving merge conflicts with origin/main: - test/adapters/driving/fastapi/routers/test_actors.py:447 - vultron/adapters/driving/fastapi/routers/actors/_routes.py:166 Both are replaced with ADR-0073#peer-records-in-knowers-store. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2 participants
Summary
Deletes the stale `docs/codebase/` duplicate, fixes invalid path citations in `docs/reference/codebase/`, adds a ratchet test that prevents phantom file references from reappearing, and wires that ratchet into CI so docs-only PRs trigger it.
Changes
Verification
Acceptance criteria (#2552)
Acceptance criteria (#2924)