From c839f1eb7263671f1e5303f280e9b081e8eb9e8f Mon Sep 17 00:00:00 2001 From: null Date: Tue, 18 Aug 2026 00:16:48 -0500 Subject: [PATCH] fix(docs): three documents named the template's layout, not the project's The remaining half of #16 was not a decision. It was three documents being wrong about their own audience. A freshly scaffolded project failed doc-claims on four PATH claims: docs/architecture/scripts (twice), docs/architecture/githooks, and docs/architecture/scripts/release.sh -- named by DOC_TRUST_MAP.md, TOOLS.md and WORK_CYCLE.md. I had modelled that as a tension between documents that were correct and a scaffold that declined to create what they named, and filed it needing a call from Kaspa between three unattractive options. The evidence says otherwise. Every script's own header reads "Copy to `scripts/`", the hooks install to `.githooks/`, and FIVE documents already use that project-relative form -- OPERATIONS.md, architecture/README.md, GUARDS.md and parts of TOOLS.md and DOC_TRUST_MAP.md. Only three used `docs/architecture/...`, which is where the scripts live in THIS repository and nowhere a project that adopts them will ever look. So the documents now name the layout their reader will actually have. No tooling change, no empty directories, and the claims get more accurate rather than vaguer -- the opposite of the direction I was leaning. Verified both ways, since a fix that only works in one tree is what produced the bug: the template stays green at 112 claims, and a freshly scaffolded project committed and checked exits 0 for the first time, with the bare-filename notes from f5fd67b reported as information rather than failure. Worth recording why this was invisible from inside: every path in question resolves here. The documents were only wrong from a vantage point this repository does not have, which is why scaffolding into a scratch directory found it and reading it here never would. closes #16 Co-Authored-By: Claude Opus 5 (1M context) --- docs/DOC_TRUST_MAP.md | 4 ++-- docs/TOOLS.md | 2 +- docs/WORK_CYCLE.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/DOC_TRUST_MAP.md b/docs/DOC_TRUST_MAP.md index bfda332..698ea44 100644 --- a/docs/DOC_TRUST_MAP.md +++ b/docs/DOC_TRUST_MAP.md @@ -39,9 +39,9 @@ disagree, and nothing will say which one is right. | Did QA pass, and what does the tester think? | `docs/qa/ClaudeReport.md` | | What did QA actually reach? | `docs/qa/ClaudeQACoverage.md` | | How is it built? | `docs/architecture/` | -| How do I release, back up, or check this? | `docs/architecture/scripts/` | +| How do I release, back up, or check this? | `scripts/` | | Which script do I run, and can it stop me? | `docs/TOOLS.md` — the signpost; `docs/architecture/README.md` has the table | -| What runs before a commit? | `docs/architecture/githooks/` | +| What runs before a commit? | `.githooks/` | | How do I write a check that will actually catch something? | `docs/architecture/GUARDS.md` | **Next action and blockers are recorded at the end of every piece of work, not diff --git a/docs/TOOLS.md b/docs/TOOLS.md index 5cd9a30..54f99f1 100644 --- a/docs/TOOLS.md +++ b/docs/TOOLS.md @@ -64,7 +64,7 @@ command and the table of what each hook runs. ## Adding one -Put it in `docs/architecture/scripts/`, give it a header saying what it does and +Put it in `scripts/`, give it a header saying what it does and **which incident motivated it**, state its exit codes, and add a row to `architecture/README.md`'s table — this file's `Review trigger` fires on exactly that. diff --git a/docs/WORK_CYCLE.md b/docs/WORK_CYCLE.md index e454875..8e00332 100644 --- a/docs/WORK_CYCLE.md +++ b/docs/WORK_CYCLE.md @@ -262,7 +262,7 @@ one, and never report progress the API did not return. - **Not the work list.** That is the tracker: milestones are batches, issues are deliverables. -- **Not the release procedure.** That is `docs/architecture/scripts/release.sh` +- **Not the release procedure.** That is `scripts/release.sh` and `docs/security/SECURITY_CHECKLIST.md`. - **Not the QA procedure.** That is `docs/qa/ClaudeQAPlan.md`, which ends in its own version of step 7.