A batch of twenty-eight issues in one adopting project could close in full —
every P1 included — with nothing new visible to anybody using the product.
Cost per project, hours with coverage bounds, model attribution and an
algorithm version on every stored figure: all of it verifiable through a JSON
flag, none of it required to appear on a screen.
Two of those issues exist specifically to correct what somebody believes when
they look at the admin — wall-clock is not summed effort, and figures computed
by different algorithm versions are not comparable. Satisfied in JSON, they
correct nobody.
So the rule, and the check that carries it:
README.md — a schema, a stored figure, a computed field or an API response
is not a deliverable by itself. Say which screen shows it, link the issue
that provides one, or record that it is deliberately not shown.
forgejo-issue.py — warns when the acceptance check's subject is the data
(retrievable, returned, reported, recorded) and nothing in it requires a
person to see the result.
Both tests read the `Verify:` line rather than the body. A first attempt read
the whole body and fired on 44 of 73 real open issues, because bodies say
"page" and "renders" incidentally; a warning at that rate is one nobody reads,
and it would have taken the `Verify:`-not-last warning down with it. Narrowed
to the acceptance line, it fires on 8 of the same 73 — all eight in the batch
that prompted this, none anywhere else.
A warning and not a refusal. API-only is a legitimate decision; it has to be a
decision rather than an omission.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two commits ago README's `Governs:` changed from `Projects/Template/**` -- true
while this was a folder inside Projects/, matching nothing once it became a
repository root -- to the three root documents it actually makes claims about.
Its `Review trigger:` was left describing the previous scope.
That is the drift this tree keeps finding, committed by me, in the header field
pair whose entire job is to stay coherent: a Governs updated on one line and a
trigger left describing what the document used to cover. Nothing checks the two
against each other, which is why it survived a commit and a peer review.
The trigger now names the events that should actually send somebody back here:
a change to how adoption works, a script added or removed from the day-one
table, and the QA run-state and reconcile grammar it already covered.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Two kinds of project arrive at this template and neither had a document written
for it. A new repository needs a first act. An existing one -- which is most of
them, since eight were surveyed and one had adopted anything -- needs a merge,
with documents and conventions already in place that must survive it.
What existed was README's "Adopting it": seven steps aimed at a person reading
top to bottom, silent about existing projects, and opening with the one form
that destroys work:
cp -r Projects/Template/docs <your-project>/docs
cp -r overwrites. scaffold.sh exists precisely because that is unsafe, and its
header argues the case at length: a clobbered document is work nothing notices
is gone, silent when it happens and silent afterwards. An existing project
following step 1 literally replaced its own architecture notes with
placeholders. The instruction and the tool disagreed and the instruction was the
dangerous one.
Both documents hold one prompt each, written to be handed to an agent whole, and
both open by putting it in PLAN MODE with nothing changed until the plan is
approved. Each plan must name what will be created, what kept, what deleted,
which scripts the project adopts -- and what will be left undone, by name. That
last is the one that gets skipped: an adoption quietly missing the webhook or
half the status headers looks identical to a complete one from outside.
The existing-project prompt is the harder half. Its spine is survey, reconcile,
destroy nothing: the survey IS the plan phase and is entirely read-only; the
scaffold's "kept" list is the merge worklist; existing prose is the project's own
knowledge and the template supplies shape, not content; and any markdown backlog
moves into the tracker and is deleted in the same commit, because two records of
what is open is the failure the whole convention exists to prevent.
Verified rather than asserted, since the whole document rests on it: a scratch
project with three written documents, scaffolded into, reported 16 created and 3
kept, and all three pre-existing files were byte-identical afterwards with their
prose intact.
README's section becomes a pointer to the two, since three descriptions of
adoption in one repository is the two-records failure with an extra copy, and the
sentence about the Command Center's generated prompt now says which is the
source rather than leaving a reader to pick.
Also corrected: README's `Governs: Projects/Template/**` was true when this was a
folder inside Projects/ and matched nothing once it became a repository root.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
README.md opened with "twenty scripts that enforce both". The directory holds
23 -- Batch 01 added restore-check.sh, controls.sh and preflight.sh.
Fixed the way scaffold.sh's header was fixed earlier in this batch, which said
"thirteen documents" and was three behind: by carrying no number at all rather
than a fresh one that goes stale after the next script. doc-claims.sh verifies
that named paths exist, not that stated quantities are true, so nothing catches
this class and the only durable fix is not to make the claim.
The day-one table also predated all three new scripts. It now names backup.sh
and restore-check.sh together, since sending a reader to backup.sh alone points
them at a script whose own header says it is half the job, and adds preflight.sh
and controls.sh. The secrets.sh row gained --built.
closes#13
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>
README.md's status header named a person; it now names _null.
healthcheck.sh's crontab example hard-coded one operator's home directory in
two lines. Those are now $HOME, rather than a literal /home/_null, because a
template copied into every project should not carry anyone's home path and an
invented one would be a path that does not exist -- which this tree refuses
everywhere else.
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