Repository navigation
[SCR-216] Accept the heading names repos use - #220
Conversation
The standard invented a vocabulary and the fleet already had one. Every open issue in content-rabbit failed the checker, and most of that was the form disagreeing with an established convention rather than issues being thin. Counted across the open issues: What 23, Scope 17, Why 12, Done 11, Verification 7, Problem 6, Deliverables 4. Those are the same concepts under shorter names that were in use before the standard existed. AGENTS.md says to read a repo and reuse its domain terms, and the standard did not. Give each required heading a set of accepted names. Failures still name the canonical heading, so new issues converge on one vocabulary while old ones stop failing for spelling. Exit gate is deliberately not an alias of Acceptance criteria. A gate is a condition for leaving a phase; criteria are the testable statements of one issue. An epic is forbidden from carrying criteria, so treating the two as one name made every phase epic fail a rule it does not break. That was found by running the change against real issues rather than by reading it. Aliases go through the same label equality that lint already used, so a heading named in a description still does not count as a field.
|
Warning Review limit reachedNext included review available in 25 minutes. View limit detailsLimit details: You’ve used the included review currently available. Your 108 included PR review attempts over the past 7 days set your current allowance at 1 review per hour. Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab. Review configuration: ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Team Run ID: 📒 Files selected for processing (2)
Comment |
… canonical one findSection took the first section whose normalised heading matched any alias, so a stray "## Why" ahead of a filled-in "## Job to be done" made validateBody report the required heading as empty. It now prefers whichever match has real content. Also adds lintTemplates coverage for a required heading offered only through an alias label, and for a forbidden heading offered the same way.
There was a problem hiding this comment.
Reviewed head: decb75e291aedc3e96c9ed2aa7bbba015a10b5f0
Council findings verified against the code; one confirmed, two discarded. No fixes pushed this cycle — the one confirmed issue is proof text that only the author can correct, and the discarded items are described below.
Confirmed (Major) — ## How I verified is stale
The PR body reports node issue-standards.test.mjs -> tests 40, pass 40, fail 0 (29 before, 11 added). That count matches the state right after the first commit (75ac43b), which does add exactly 11 tests to reach 40. But the second commit (decb75e, the current head) adds 3 more tests (lint accepts a required heading offered only through an alias label, lint rejects a forbidden heading offered only through an alias label, and the stray-alias-collision test) — the file now has 43 test( calls and this diff adds 14, not 11. The verification block was never rerun after the fix commit that changed findSection's collision behavior, so the reported numbers describe a version of the diff that no longer exists. Please rerun node issue-standards.test.mjs on the current head and update the reported counts — I won't fabricate that evidence myself.
Discarded
- Scope: "alias labels weaken the canonical-only template requirement" (issue-standards.mjs:451-457). Checked: this is intentional and correct, not a regression. A form whose label is an accepted alias (e.g.
Why) produces issues whose body heading is that same alias, andvalidateBodyalready accepts that alias. Rejecting it at the template-lint stage while accepting it at the body-validation stage would just be a second, contradictory rule. The author added a passing test for exactly this case (lint accepts a required heading offered only through an alias label, line 470), so this is deliberate, not drift. - Scope: aliases without measured fleet evidence (
Repro,Regression,Last working,Metric,Success metrics). The PR's own census only covers 7 of the ~15 accepted alias names. That's a fair observation about the strength of the justification, but it names no failure — accepting an extra name an issue happens not to use is inert. Not blocking; noted below as a documentation point instead.
Minor (not blocking)
issue-standards.mdis described in its own first line as "the standard" and still lists only the canonical headings (## Job to be done,## Today / Wanted, etc.) with no mention that aliases are now accepted. Anyone reading the doc as the source of truth won't knowWhy/Impact/Scope/Done/... pass too. Worth a short note near "The spine" section, at the author's discretion — not pushed since it's a judgment call whether documenting the aliases undercuts the stated convergence goal.- The aliases without measured evidence noted above: consider trimming to the measured set or adding a one-line justification for the rest. Not a functional issue.
PR-standard lens
Branch, title, body sections, single Closes #216, Assisted-by: trailer, and the 500-line/40-file caps (206 counted lines, 2 files) all check out.
🧑⚖️ Council
| Model | Lens | Result |
|---|---|---|
| GPT-5.6 (Codex) | correctness | no findings |
| Gemini 3 Pro | performance | timed out |
| Kimi K3 | security | no findings |
| Grok 4.5 | maintainability | timed out |
| GPT-5.6 (scope) | scope | 1 confirmed (proof staleness), 2 rejected |
| assert.equal(validateBody(body, 'feature').failures.length, 0); | ||
| }); | ||
|
|
||
| test('lint accepts a required heading offered only through an alias label', () => { |
There was a problem hiding this comment.
This test (and the two after it) were added in decb75e, after the "## How I verified" block in the PR body was written. That block still reports 40 total / 11 added, but the file now has 43 test( calls and this diff adds 14. Please rerun node issue-standards.test.mjs on this head and update the reported counts.
Closes #216
What
Each required heading gains a set of accepted names. A section matches under any of them, and failure messages still name the canonical heading so new issues converge on one vocabulary.
Why
The standard invented a vocabulary and the fleet already had one. Counted across the open issues in content-rabbit:
Same concepts, shorter names, in use before the standard existed.
AGENTS.mdsays to read a repo and reuse its domain terms; the standard did not, and took its names from the spec-issue skill and another team's conventions instead.Correcting the claim that motivated this
The issue said most of the 133 failures came from this naming mismatch. That was wrong, and the measurement says so:
Broken down by type after the change:
92% of failures are missing labels, not heading names. That is expected rather than alarming: the label vocabulary existed in one repo out of five until #215 rolled it to the rest, so the issues had nothing to carry. Applying labels to existing issues is triage work, not a tooling change.
This change is still worth making. It stops the checker failing an issue for spelling, and it stops it failing every future issue written in the fleet's own vocabulary. It is a smaller win than the issue claimed, and the numbers above are the honest size of it.
The bug this found
Exit gatewas in the first draft as an alias ofAcceptance criteria. Running it against real issues showed why that is wrong: an epic is forbidden from carrying acceptance criteria, ten phase epics legitimately carry anExit gate, and the alias made all of them fail a rule they do not break.A gate is a condition for leaving a phase. Acceptance criteria are the testable statements of one issue. They are not the same thing and are no longer treated as one name.
That was found by running the change against live issues, not by reading it.
How I verified
The four cases that matter, checked directly rather than trusted:
Aliases go through the same label equality that
lintalready used, so a heading named in a form's description still does not count as an offered field. That hardening arrived from review on #192 and is deliberately not weakened here.How it was built
Delegated to
grok-4.6-xhighthrough thedevinCLI. The alias map,namesFor(), thefindSectionchange and theoffers()helper that keeps lint strict are its work, and it correctly extended the forbidden-heading check to aliases, which was the part most likely to be missed.Review found one design error, the
Exit gatealias, and it was mine: it was in the brief I gave. Three earlier attempts produced nothing because of permission flags I chose wrongly, not because of the model.Assisted-by: claude-personal-1:claude-opus-5