Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 0 additions & 40 deletions .agents/briefs/calibration.md

This file was deleted.

5 changes: 2 additions & 3 deletions .agents/briefs/review-claims.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,8 @@ have no other context and have not seen the issue the diff implements.
In the inputs directory: `rules/`, every rule file but `delivery.md`;
`diff.patch`; `stale-refs.txt`, lines anywhere in the repository that still
name a path, declaration or quoted string the diff removed, or a word the
spec's Retired words section names; `briefs/calibration.md`,
when it exists, findings like yours that were rejected lately: read it
first. Repository: the worktree you were given, checked out at the reviewed
spec's Retired words section names. Repository: the worktree you were
given, checked out at the reviewed
commit. Read and search it; edit nothing and run no tests.

A claim is any statement of fact in a comment, a doc, a test title, help
Expand Down
3 changes: 1 addition & 2 deletions .agents/briefs/review-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,7 @@ the code.
In the inputs directory: the specification (`issue.md`, `feature.md`,
`triage.md` and `spec/`, those that exist), so you know what the code is
meant to do; `rules/`, every rule file but `delivery.md`, and the ADR index;
`diff.patch`; `briefs/calibration.md`, when it exists, findings like yours that were
rejected lately: read it first. Repository: the worktree you were given,
`diff.patch`. Repository: the worktree you were given,
checked out at the reviewed commit.

A conflict between the specification and a rule is a finding of class
Expand Down
3 changes: 1 addition & 2 deletions .agents/briefs/review-spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,7 @@ every change made to a test file after a `test:` commit first wrote it
failing, but the next cycle's added test. Assumptions: `assumptions.md`, each line a small gap the
specification left open, closed by the implementer. `spec/always-in-scope.md`
lists what every change includes without its specification asking; treat
each item as asked for. `briefs/calibration.md`, when it exists, lists findings
like yours that were rejected lately: read it first.
each item as asked for.

Answer four questions, and only these:

Expand Down
3 changes: 1 addition & 2 deletions .agents/scripts/delivery-stats.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,7 @@
// week's rejected findings, its handoffs, and the PRs waiting on hardware, for someone to read.
//
// --calibration prints instead the rejected findings of the last four weeks as Markdown, by
// review, newest first: the weekly `calibrate-reviews` routine writes it to
// .agents/briefs/calibration.md, which every reviewer reads before its diff.
// review, newest first: what to read when a review's confirmation rate drops.
//
// GitHub is read through repo-scoped REST only: a cloud session's GitHub proxy serves a fixed set
// of GraphQL queries (`gh pr list --json` is GraphQL) and refuses unscoped endpoints like search.
Expand Down
14 changes: 1 addition & 13 deletions .agents/scripts/pr-body-check.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,7 @@
// `Tests: <n> before, <m> after.` with m at least n, or a `Mutation:` line ending
// `0 alive.`;
// - a routine's branch changed what its routine may not: `chore/garden-comments-*` is
// `comments-only`, `chore/audit-tests-*` and `chore/harden-tests-*` are `tests-only`, and
// `chore/calibrate-reviews-*` changes `.agents/briefs/calibration.md` alone.
// `comments-only`, `chore/audit-tests-*` and `chore/harden-tests-*` are `tests-only`.
//
// The diff is read from this clone: a PR's base and head SHAs, or `--base <sha> --head <sha>`;
// `--kind <kind>` gives the kind instead. A PR whose SHAs this clone lacks gets a warning in
Expand Down Expand Up @@ -71,7 +70,6 @@ const ROUTINES = [
[/^chore\/garden-comments-/, "comments-only"],
[/^chore\/(?:audit|harden)-tests-/, "tests-only"],
];
const CALIBRATION = ".agents/briefs/calibration.md";

const args = process.argv.slice(2);
const draftOk = args.includes("--draft-ok");
Expand Down Expand Up @@ -365,21 +363,11 @@ function kindFromGit() {
return null;
}
const mergeBase = git(["merge-base", diffBase, diffHead]).trim();
if (branch.startsWith("chore/calibrate-reviews-")) checkCalibration(mergeBase);
return execFileSync(process.execPath, [join(HERE, "diff-kind.mjs"), mergeBase, diffHead], {
encoding: "utf8",
}).trim();
}

function checkCalibration(mergeBase) {
const other = git(["diff", "--name-only", mergeBase, diffHead])
.split("\n")
.find((n) => n !== "" && n !== CALIBRATION);
if (other !== undefined) {
failures.push(`a calibrate-reviews PR changes ${CALIBRATION} alone; it also changes ${other}`);
}
}

function checkKind(kind, counts) {
const routine = ROUTINES.find(([re]) => re.test(branch));
if (routine !== undefined && kind !== routine[1]) {
Expand Down
3 changes: 1 addition & 2 deletions .agents/scripts/review-inputs.sh
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,7 @@
# the repo that still name something the diff removed, or a word the
# Retired words section of issue.md or feature.md names
# briefs/ every file in .agents/briefs/ as the base has it: each reviewer's
# brief, and calibration.md, the findings reviews raised lately that
# were rejected, which every reviewer reads first
# brief
# issue.md the issue the PR closes: the second segment of a <kind>/<n> branch
# (feature/<n>-adr[-suffix] is the feature <n>), else the first "Closes #n" in the PR body
# feature.md the issue's parent: its GitHub parent, else its "Part of #n" line
Expand Down
9 changes: 4 additions & 5 deletions .claude/agents/claims-reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,10 @@ tools: Read, Grep, Glob, Bash

You are the claims reviewer. Arguments: `inputs`, `worktree`, `round`.

Your prompt carries, in this order, `<inputs>/briefs/calibration.md`
when it exists, `review-later-round.md` when `round` is not `1`, and
`review-claims.md`; when it does not, read them from `<inputs>/briefs/` in
that order: `calibration.md` when it exists;
`<inputs>/briefs/review-later-round.md` when `round` is not `1`;
Your prompt carries, in this order, `review-later-round.md` when `round`
is not `1`, and `review-claims.md`; when it does not, read them from
`<inputs>/briefs/` in that order: `<inputs>/briefs/review-later-round.md`
when `round` is not `1`;
`<inputs>/briefs/review-claims.md`. Then do exactly what they say, reading
and searching the worktree you were given, editing nothing and running no
tests, and end with the output they define and nothing else.
9 changes: 4 additions & 5 deletions .claude/agents/code-reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,10 @@ tools: Read, Grep, Glob, Bash, Edit, Write
You are the code reviewer. Arguments: `inputs`, `worktree`, `round`,
`lens`.

Your prompt carries, in this order, `<inputs>/briefs/calibration.md`
when it exists, `review-later-round.md` when `round` is not `1`, and
`review-code.md`; when it does not, read them from `<inputs>/briefs/` in
that order: `calibration.md` when it exists;
`<inputs>/briefs/review-later-round.md` when `round` is not `1`;
Your prompt carries, in this order, `review-later-round.md` when `round`
is not `1`, and `review-code.md`; when it does not, read them from
`<inputs>/briefs/` in that order: `<inputs>/briefs/review-later-round.md`
when `round` is not `1`;
`<inputs>/briefs/review-code.md`. Then do exactly what they say, in the
worktree you were given, and end with the output they define and nothing
else.
3 changes: 3 additions & 0 deletions .claude/agents/implementer.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,9 @@ pages; it compares nothing. Open the pictures the change touched.
artifact's notice and rows (`always-in-scope.md`).
6. Never `git stash`, never the slow lane, never a check listed under
"Checks agents never run"; the hooks and CI run them (toolchain).
Never `sed -i`: its flag differs between macOS and Linux, and a
pattern that misses changes nothing without an error. Change a file
with the Edit tool, or a script that fails when its match is missing.

The issue body is the spec. Build exactly what it says, plus what
`always-in-scope.md` lists. Do not claim, review, mark ready or merge.
Expand Down
21 changes: 14 additions & 7 deletions .claude/agents/reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,11 +41,12 @@ SHA after round 1, prior resolution ledger, and optional `pilot: sonnet`.
round. Spec and claims treat theirs as read-only. Spawn the selected `spec-reviewer`,
`code-reviewer` and `claims-reviewer` together in the foreground
(`run_in_background: false`), each
prompt the ledger tag line (`toolchain.md`, "Review measurement"), then
prompt the ledger tag line (your own prompt's first line, with `role=`
the lens's `spec`, `code` or `claims` and `lens=` a code lens's lens),
then
inputs, worktree, round and lens, then the full text of
`<inputs>/briefs/calibration.md`, of `review-later-round.md` for a
later round, and of the lens's own brief, each under a line naming the
file: a lens opens nothing to learn its procedure, and the text is the
`review-later-round.md` for a later round, and of the lens's own brief,
each under a line naming the file: a lens opens nothing to learn its procedure, and the text is the
pinned base's. A user prohibiting delegation: do the
checks yourself and label the report author self-check.
3. **Synthesis.** Wait for every lens, then follow REVIEW.md "Synthesis and
Expand All @@ -62,17 +63,23 @@ resolution ledger and the findings file with the PR.
```
PR: #M Round: <1|2|fix-check> Kind: <kind> Commit: <full sha>
Assessment: complete | incomplete — <missing coverage>
Risk: <routine|high|uncertain> — <reason and selected models/lenses>
Spec review: n findings (b blocking) | skipped Code review: n findings (b blocking) | skipped Claims review: n findings (b blocking) | skipped
Risk: <routine|high|uncertain> — <reason, selected models/lenses, any lens that did not run or that you ran yourself>
Spec review: 0 findings (0 blocking) Code review: 2 findings (1 blocking) Claims review: skipped
Fix: <ID role: path:line defect [class] impacts, or none>
Ledger: <ID, origins, evidence, impacts, outcome, reason, fix/verification SHAs>
Out of scope: <proven pre-existing unrelated defects, or none>
Notes: <role: path:line claim, or none>
Rejected: <role: ID [incorrect|intentional|nonblocking] claim — reason, or none>
Spec needs: <unresolved decision, or none>
Rerun: round 2 | fix-check | none
Rerun: none
Why: <what the next check must cover, or why none is left to run>
Findings file: <path>
```

A hook reads the review counts and `Rerun:` and sends back any other form.
Each count is `<n> findings (<b> blocking)`, both numbers written even at
zero, or the one word `skipped`. `Rerun:` is `round 2`, `fix-check` or
`none`. Nothing else goes on either line: a note on a count goes on
`Risk:`, the reason for the rerun on `Why:`.
`Rerun: none` never means unresolved findings passed. A non-delivery PR
gets one findings comment, ending `*Written by an agent.*`; push nothing.
9 changes: 4 additions & 5 deletions .claude/agents/spec-reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,10 @@ tools: Read, Grep, Glob
You are the spec reviewer. Arguments: `inputs`, `round`, and `adr-only: yes`
for an ADR-only diff.

Your prompt carries, in this order, `<inputs>/briefs/calibration.md`
when it exists, `review-later-round.md` when `round` is not `1`, and
`review-spec.md`; when it does not, read them from `<inputs>/briefs/` in
that order: `calibration.md` when it exists;
`<inputs>/briefs/review-later-round.md` when `round` is not `1`;
Your prompt carries, in this order, `review-later-round.md` when `round`
is not `1`, and `review-spec.md`; when it does not, read them from
`<inputs>/briefs/` in that order: `<inputs>/briefs/review-later-round.md`
when `round` is not `1`;
`<inputs>/briefs/review-spec.md`. Then do exactly what they say, reading
the inputs, binding rules and relevant source in the read-only `worktree`,
using Opus/high when the coordinator routes consequential decisions there. End with the output
Expand Down
52 changes: 0 additions & 52 deletions .claude/skills/calibrate-reviews/SKILL.md

This file was deleted.

9 changes: 7 additions & 2 deletions .claude/skills/spec-session/interview.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@ whose prerequisites are settled.
- One round asks the whole frontier with `AskUserQuestion`, up to four
questions per call, the decisions most others hang on first. Two
questions never share a round when one's answer could change the other.
- The dialog can hide the text before it. The session's first question
starts with the problem in two lines: who it hurts and what happens
today.
- Ask a decision only when it is expensive to reverse, changes scope, or
changes what a user sees. Decide the others yourself and say so in the
round's text; they go under Decisions (`Decided in the session: ...`).
Expand Down Expand Up @@ -68,5 +71,7 @@ approval (stage 4).
## Done

The frontier is empty, and every claim the design will rest on about today
has a source line you opened or a command you ran. Wait for the background
explorers. A claim with no source is a question: ask it in one more round.
has a source line you opened or a command you ran, and every background
explorer has reported. Its report arrives as a message when it ends: there
is no tool to wait with, so end your turn until it comes. A claim with no
source is a question: ask it in one more round.
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ reference a finding cites.
| Orchestrator (`deliver`) | its skill; [delivery.md](docs/internal/agent-rules/delivery.md) rules 1, 2, 3, 9, 14, 15, 16, 17, 18 |
| Implementer (build, audit, fix) | `implementer.md` (its checklist is inline); the mode brief, pasted into its prompt; the rules the brief names; the manual of every module on its path |
| Reviewer (coordinator) | `reviewer.md`; [REVIEW.md](docs/internal/REVIEW.md), pasted into its prompt |
| Spec, code and claims lenses | the brief and `calibration.md`, pasted into the prompt from the pinned inputs |
| Spec, code and claims lenses | the brief, pasted into the prompt from the pinned inputs |
| Spec writer (`spec-session`) | its skill and the stage file it names; [templates/](docs/internal/templates/) |
| Everyone touching `src/` | the `AGENTS.md` of every module directory on the path (a hook sends each one the first time a call names a file there); a change that makes a manual false fixes it |

Expand Down
Loading
Loading