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/<name>`", 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) <noreply@anthropic.com>
This commit is contained in:
parent
88d7592321
commit
c839f1eb72
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue