fix(skills): redraw patch versus defer, prefer patch over bad_spec, route scope-line findings on their merits

[pbean]

Why

The line between patch and defer is drawn by size. patch is "trivial, adds no public surface"; defer is "pre-existing issue not caused by this story". Under those definitions a real defect in a file the change edited, whose fix is a private helper and a test, is neither trivial nor caused by the change — so it is deferred. It lands in the ledger, the next run reads it back, and someone re-derives the context this run already had. The change that touched the file was the cheapest moment to fix it.

bad_spec has the same lean. "When in doubt between bad_spec and patch, prefer bad_spec" sends a deviation from a spec that is itself right into a revert-and-re-derive loop, when restoring what the spec says is a local edit.

And a finding that only a spec scope line excludes — a Never non-goal, a Code Map do-not-change — routes to intent_gap or bad_spec today, or gets deferred as out of scope. A scope line says where the work stops; it does not say the defect on the far side of it is not the change's problem.

What changed

Instruction text at all four triage sites: bmad-build step-04 and one-shot, bmad-build-auto step-04, bmad-code-review step-03. The two step-04 files stay in lockstep; only the human-present branches differ.

Patch is a locality test, not a size test. A patch is a fix inside the change's blast radius — the files in the diff, their tests, the code a test in the diff exercises, direct callers of symbols the diff introduced or changed, and sibling sites of a pattern the diff fixed or replaced when the fix is the one already in the diff — that contradicts no design decision the spec records, adds no external contract, and guards no state the finding did not demonstrate. A private helper, a new test, or a fifteen-line fix is still a patch. Patch also takes a defect the change did not cause when the fix is a direct correction smaller than the deferred entry would be; writing it up costs more than fixing it.

Defer is a positive test with every condition required. The defect was neither caused nor exposed by the change; it lives in a file and symbol the change did not touch, and is not a sibling copy of a pattern the change fixed; its fix is larger than the entry would be; and it is not an agent-context file the change made stale. The triage row names the tests it passes. A pre-existing defect in code the change edited is the change's problem. So is a gap in the change's own verification — a test that would still pass with the change reverted, or a touched site that skips the helper the change introduced — which is a patch, never a coverage-only defer. The existing severity-if-true gate for all-maybe-false entries is unchanged inside the new definition.

Design decisions versus scope lines. A design decision says how the work is done — the Approach, a Design Notes rationale, a forbidden approach. A scope line says where the work stops. intent_gap now includes a fix that would contradict a design decision inside the frozen block or intent contract. bad_spec means a local fix would contradict a recorded design decision outside it, or the same defect recurs wherever that design is applied. A deviation from a spec that is itself right is a patch. When in doubt, prefer patch: name the spec sentence a local fix would contradict; if you cannot, it is a patch.

Out of scope routes on its merits. A finding only a scope line, the plan, or the shape of the diff excludes is kept and routed like any other. In bmad-build-auto a local fix is applied with the crossed line named in its triage row and under residual risks. In bmad-build and one-shot, patches that cross a scope line or change a rule in an agent-context file are put to the human once, together; confirmed ones are applied, declined ones become defers with the human's reason as evidence.

Agent-context files split two ways. A description of behavior the change altered is stale documentation inside the blast radius — a patch. A new or changed rule, or an edit to another spec, is a policy change: the unattended skill defers it with the rule it would change as evidence; the interactive skills ask.

Code review without a spec keeps decision_needed. No spec means no recorded design decisions or scope lines, so decision_needed rests on the other grounds. An ambiguous fix stays decision_needed — the user is present and settles it in step 4 — and is no longer reclassified as defer for want of a spec.

Docs

docs/build/review-a-change.md "What a Run Does" describes the verdicts and the three routes as they now work.

Verification

npm test green: renderer 24/24, skill validator, lint, markdownlint, prettier.