review: prompt disciplines and measured cost fixes

[jwbron]

Summary

Third of three PRs split out of #224; stacked on #227 (retarget as the stack merges). Prompt text only (review.md + README); no code changes. With this PR the stack matches #224 apart from the changesets and one follow-up: the budget-exhaustion trigger was reworded (per review feedback) to key off observable proxies rather than spend, which the agent cannot see.

Quality disciplines:

• Quote-the-rule. A skill or conventions violation may only be flagged when the exact rule text and the exact violating line can both be quoted (skill-auditor, conventions reviewer, and every lens-owned skill application); the validator never confirms a skill claim that cannot quote its rule. No spirit-of-the-doc inference.
• Amplification nuance. A claim about a mechanism that predates the diff confirms only when the diff materially amplifies its consequence, and the finding must say so explicitly; the correctness reviewer states introduce-vs-amplify on every pre-existing-bug finding.
• Method-angle procedures. The correctness reviewer works the diff through three named procedures instead of one flat checklist: a line scan (what input or state makes each line wrong), a removed-behavior audit (name the invariant every deleted line enforced; find where the new code re-establishes it), and a cross-file trace (callers and callees of every changed symbol).

Measured cost fixes:

• Graceful budget exhaustion. Nearing the run's hard ceilings (per-run AI-credits cap, job timeout), the orchestrator sheds remaining work in a fixed order (opt-in reviewers/lenses first, then the risks/patterns comment, then validation) and submits the verdict from findings validated so far plus skipped-dimension notes, instead of dying at a ceiling with everything spent and nothing posted. Since the agent cannot observe its own credit spend, the trigger is defined in terms of observable proxies: elapsed wall-clock vs runBudget.maxWallClockMinutes, dispatch count vs maxReviewerInvocations, the shared investigation journal vs maxTotalToolCalls, and overall trajectory.
• Batched safe-output tail. The orchestrator emits same-kind safe outputs together in as few calls and turns as possible; thread resolutions especially, which previously went out one turn apiece.

Prompt text carries no plan identifiers.

cc @jeresig

Testing

• npx vitest run workflows/review: 452 tests green (prompt-only change; smoke set gated).

[changeset-bot]

🦋 Changeset detected

Latest commit: 19164d2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
review	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[jeresig]

In general seems good - but I'm not sure about the budgeting aspect, I don't think that's something that it'll have access to?

[jeresig]

Does the agent even have insight into if it is running out of budget? Are messages being injected in to provide that context? I'm worried that this will make it paranoid and start to abandon steps due to imagined constraints.

[jwbron]

Good catch, you're right that it can't see spend directly. There's no channel that reports credits consumed back to the agent mid-run. The cap is enforced in gh-aw's api-proxy, and cost only shows up in the step summary after the run.

What the orchestrator does have is the target and a set of proxies: the router JSON it parses in Step 3 carries runBudget.maxUsd and maxWallClockMinutes, elapsed time is checkable from bash, the investigation-cap CLI already counts tool calls against maxTotalToolCalls in code, and it knows how many reviewers are still pending. The wall-clock side is just as load-bearing anyway, since timeout-minutes: 20 kills the job as surely as the credit cap does, and time is the one signal it can measure accurately.

So the shedding mechanism works as written, but the trigger sentence overpromises by leading with "spend". I'll reword it to say spend isn't observable and to lean on the observable proxies (elapsed minutes vs maxWallClockMinutes, reviewers dispatched vs maxReviewerInvocations, cap-CLI totals, diff size) before this merges. I'll also fix the "hard AI-credits cap (frontmatter)" aside, since the per-run cap is actually gh-aw's baked-in default, not something the frontmatter declares.