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>
forgejo-issue.py warns that a milestone title starting with a version token has
everything after it dropped from the dashboard phase -- `0.2 Payments` displays
as `0.2`. README.md was teaching exactly that form, and two adopted repos
followed it: Closer-Couples and fruit-fall both carry version-first titles and
lose their batch names on the card. PrivacyLLC-Web uses `Batch 05 — ...` and
displays whole.
The guidance now names the working form, and carries the comma rule the script
also enforces: a comma breaks the `milestones=` filter and the card shows the
wrong next action.
WORK_CYCLE.md gains the trap the same script documents and no document did: the
dashboard's next action is the NEWEST open issue in the current milestone, not
the most severe -- severity labels have no influence at all. Filing a routine P2
into the active batch silently replaces what the project card shows.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The basis for every project here was itself unversioned: no .git, no remote,
no history. Changes to it had no diff and no revert, and two of its own guards
could not run at all -- doc-claims.sh and doc-triggers.py both read git
history, so the script written to catch documentation drift could not be run
against the documents that define drift.
This is the tree as it stands, including work that until now existed only as
loose files on disk: WORK_CYCLE.md, TOOLS.md, the Portainer image-line fix in
deploy.py, the status vocabulary corrected to the four words the conformance
checker actually enforces, the Exempt: mechanism documented, and the Forgejo
instance named in README.md.
secrets.sh --tracked reports one candidate, migrate.sh:480. It is the comment
documenting the three Postgres credential shapes that script redacts, with
literal placeholders, and it is left alone deliberately: GUARDS.md section 2
is that a source-grep guard must tell code from the comment about code, and
deleting an explanation to quiet a scanner is the failure it names.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
null