Project-Template/docs
null 694b161bb1 docs(tracker): an issue that produces a data shape names its surface
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>
2026-08-22 14:05:11 -05:00
..
architecture docs(tracker): an issue that produces a data shape names its surface 2026-08-22 14:05:11 -05:00
data fix(docs): two documents claimed files that must not exist 2026-08-17 22:45:35 -05:00
design chore(repo): put the template under version control 2026-08-17 22:44:26 -05:00
history chore(repo): put the template under version control 2026-08-17 22:44:26 -05:00
planning chore(repo): put the template under version control 2026-08-17 22:44:26 -05:00
qa feat(qa): pass I, money flowing backwards 2026-08-17 22:54:03 -05:00
security feat(docs): two markers for entries that do not apply everywhere 2026-08-17 22:55:56 -05:00
DOC_TRUST_MAP.md fix(docs): three documents named the template's layout, not the project's 2026-08-18 00:16:48 -05:00
OPERATIONS.md feat(docs): OPERATIONS.md, the runbook that did not exist 2026-08-17 22:57:20 -05:00
TOOLS.md fix(docs): three documents named the template's layout, not the project's 2026-08-18 00:16:48 -05:00
WORK_CYCLE.md fix(docs): three documents named the template's layout, not the project's 2026-08-18 00:16:48 -05:00