diff --git a/.agents/briefs/calibration.md b/.agents/briefs/calibration.md deleted file mode 100644 index 4a294a2ba..000000000 --- a/.agents/briefs/calibration.md +++ /dev/null @@ -1,40 +0,0 @@ -# Findings rejected in the 4 weeks to 2026-10-14 - -Each line below was raised as blocking and rejected when it was verified against the code, -with the reason after the dash. A finding like one of these is right only with evidence that -distinguishes it from the rejected one: name the input or state that makes this one differ. - -Written by `node .agents/scripts/delivery-stats.mjs --calibration`; 484 rejected findings in all. - -## spec review - -- #509 `e2e/slow-agent-device.test.ts` short sample gap stays green — not blocking: Assumption 1 accepts it -- #382 the title "within the configured grace" promises more than the < 3 s bound proves — not blocking: the likely regression (the option ignored, so the 10 s default applies) fails the < 3 s assertion by name; only a grace between 0.1 s and 2.8 s gets through -- #497 edge.test.ts:493 "no idempotency key" unproven — unobservable at the daemon seam (Assumption 2) -- #497 allocate.ts:77 unknown target silently ignored — decided by Assumption 5 -- #497 host.ts:42 randomUUID bypasses the IdGenerator port — no rule requires it; Assumption 4 -- #497 front.ts:91 /rpc matched by exact path only — speculative, no evidence the proxy routes that path -- #497 edge.test.ts:515 no baseline for "offers no download" — duplicate of the code finding at :514, fixed -- #496 src/core/doctor.test.ts:463 optionalModules order unproven — duplicate of the code finding, fixed there - -## code review - -- #509 `e2e/helpers/env.ts` `restart()` has no timeout of its own — duplicate of a spec finding, fixed under it -- #509 `e2e/slow-agent-device.test.ts` `session list` exit code unchecked — not blocking: weakens no stated check -- #509 `e2e/helpers/env.ts:384` `restartSteps` keeps running after the 90 s limit — not blocking: slow-lane helper, teardown only -- #509 `src/agent-device/front/request-rules.ts:236` emulator name fallback may match another agent's emulator — not blocking: speculative -- #507 `allocate.ts:325` the "absent target reads as mobile" rule is decided twice — not blocking: both places give the same answer today, and no rule is broken -- #497 edge.test.ts:849 repeated cancel — duplicate of the spec finding at :849, fixed -- #495 supervisor.test.ts:1099 deleting removeRecord stays green — duplicate of the spec finding, fixed -- #495 supervisor.ts:745 stop-waiter removal untested — the leak is not observable without asserting private state - -## claims review - -- #509 `toolchain.md` package.json names only a short hash — not blocking: still true via vendor/README.md -- #468 src/leasing/lease-acquisition-coordinator.ts:299 cites ADR 0023, not in docs/internal/adr/ — ADR 0023 is accepted on draft PR #465, merged by the maintainer. -- #468 docs/EVENTS.md:26 "one-lease-per-requester" wording is stale — the default limit is still 1; the name is dated, not false. -- #468 src/leasing/lease-acquisition-coordinator.ts:322 "one-lease-per-requester check" is stale — it still describes the default limit. -- #462 src/daemon/dispatcher.ts:135 execEnv doc says driver keys are "layered on top"; unsetEnv now removes keys — not blocking: still true of the layering; unsetEnv is documented at the use site -- #458 src/leasing/lease-release-coordinator.ts:86 set doc omits return reclaims — incomplete, not false; deleted under rule 17 -- #458 src/contract/schemas.ts:204, src/core/doctor.ts:257, src/core/registry.ts:123 — each gives a why -- #458 src/daemon/server.test.ts:2032, :3087, src/leasing/lease-release-coordinator.ts:165, :274 — each gives a why (round 2) diff --git a/.agents/briefs/review-claims.md b/.agents/briefs/review-claims.md index 4e284cb7b..278172a47 100644 --- a/.agents/briefs/review-claims.md +++ b/.agents/briefs/review-claims.md @@ -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 diff --git a/.agents/briefs/review-code.md b/.agents/briefs/review-code.md index c62198f1b..fede3c88f 100644 --- a/.agents/briefs/review-code.md +++ b/.agents/briefs/review-code.md @@ -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 diff --git a/.agents/briefs/review-spec.md b/.agents/briefs/review-spec.md index ffd4c1a90..f1acf9ad1 100644 --- a/.agents/briefs/review-spec.md +++ b/.agents/briefs/review-spec.md @@ -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: diff --git a/.agents/scripts/delivery-stats.mjs b/.agents/scripts/delivery-stats.mjs index 7806d15c2..0ba909534 100755 --- a/.agents/scripts/delivery-stats.mjs +++ b/.agents/scripts/delivery-stats.mjs @@ -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. diff --git a/.agents/scripts/pr-body-check.mjs b/.agents/scripts/pr-body-check.mjs index fb2171284..f60b8bc28 100755 --- a/.agents/scripts/pr-body-check.mjs +++ b/.agents/scripts/pr-body-check.mjs @@ -37,8 +37,7 @@ // `Tests: before, 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 --head `; // `--kind ` gives the kind instead. A PR whose SHAs this clone lacks gets a warning in @@ -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"); @@ -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]) { diff --git a/.agents/scripts/review-inputs.sh b/.agents/scripts/review-inputs.sh index 1dd808071..4f3b8542a 100755 --- a/.agents/scripts/review-inputs.sh +++ b/.agents/scripts/review-inputs.sh @@ -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 / branch # (feature/-adr[-suffix] is the feature ), else the first "Closes #n" in the PR body # feature.md the issue's parent: its GitHub parent, else its "Part of #n" line diff --git a/.claude/agents/claims-reviewer.md b/.claude/agents/claims-reviewer.md index b504b67f4..dd62cb9ee 100644 --- a/.claude/agents/claims-reviewer.md +++ b/.claude/agents/claims-reviewer.md @@ -9,11 +9,10 @@ tools: Read, Grep, Glob, Bash You are the claims reviewer. Arguments: `inputs`, `worktree`, `round`. -Your prompt carries, in this order, `/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 `/briefs/` in -that order: `calibration.md` when it exists; -`/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 +`/briefs/` in that order: `/briefs/review-later-round.md` +when `round` is not `1`; `/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. diff --git a/.claude/agents/code-reviewer.md b/.claude/agents/code-reviewer.md index 5c4d74bb1..f7a010f8a 100644 --- a/.claude/agents/code-reviewer.md +++ b/.claude/agents/code-reviewer.md @@ -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, `/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 `/briefs/` in -that order: `calibration.md` when it exists; -`/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 +`/briefs/` in that order: `/briefs/review-later-round.md` +when `round` is not `1`; `/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. diff --git a/.claude/agents/implementer.md b/.claude/agents/implementer.md index 82b3b603c..bc121aff8 100644 --- a/.claude/agents/implementer.md +++ b/.claude/agents/implementer.md @@ -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. diff --git a/.claude/agents/reviewer.md b/.claude/agents/reviewer.md index c48f502ad..04e634d7a 100644 --- a/.claude/agents/reviewer.md +++ b/.claude/agents/reviewer.md @@ -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 - `/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 @@ -62,17 +63,23 @@ resolution ledger and the findings file with the PR. ``` PR: #M Round: <1|2|fix-check> Kind: Commit: Assessment: complete | incomplete — -Risk: — -Spec review: n findings (b blocking) | skipped Code review: n findings (b blocking) | skipped Claims review: n findings (b blocking) | skipped +Risk: — +Spec review: 0 findings (0 blocking) Code review: 2 findings (1 blocking) Claims review: skipped Fix: Ledger: Out of scope: Notes: Rejected: Spec needs: -Rerun: round 2 | fix-check | none +Rerun: none +Why: Findings file: ``` +A hook reads the review counts and `Rerun:` and sends back any other form. +Each count is ` findings ( 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. diff --git a/.claude/agents/spec-reviewer.md b/.claude/agents/spec-reviewer.md index 05cab79a4..62168724c 100644 --- a/.claude/agents/spec-reviewer.md +++ b/.claude/agents/spec-reviewer.md @@ -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, `/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 `/briefs/` in -that order: `calibration.md` when it exists; -`/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 +`/briefs/` in that order: `/briefs/review-later-round.md` +when `round` is not `1`; `/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 diff --git a/.claude/skills/calibrate-reviews/SKILL.md b/.claude/skills/calibrate-reviews/SKILL.md deleted file mode 100644 index 83c6e1070..000000000 --- a/.claude/skills/calibrate-reviews/SKILL.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -name: calibrate-reviews -description: Weekly routine — regenerate .agents/briefs/calibration.md from the last four weeks of rejected review findings and land it as one docs-only PR. Use when a routine or the user says "calibrate reviews". -model: sonnet -effort: low ---- - -# Calibrate reviews - -Rules: `docs/internal/agent-rules/delivery.md` rules 14 and 15. You are -the author of this PR: there is no issue and no implementer. - -## 1. Regenerate - -```bash -[ "$(git rev-parse --is-shallow-repository)" = true ] && git fetch -q --unshallow -git fetch -q origin -dir=$(.agents/scripts/worktree.sh chore/calibrate-reviews-$(date +%F)) && cd "$dir" -node .agents/scripts/delivery-stats.mjs --calibration > .agents/briefs/calibration.md -git diff --quiet -- .agents/briefs/calibration.md && echo unchanged -``` - -`unchanged`: report `PR: none` and stop. Otherwise: - -```bash -git add .agents/briefs/calibration.md -git commit -m "chore(reviews): calibration brief for the four weeks to $(date +%F)" -git push -u origin HEAD -gh api -X POST repos///pulls -f title="chore(reviews): calibration brief for the four weeks to $(date +%F)" \ - -f head="$(git branch --show-current)" -f base=main -F draft=true -F body=@/pr.md -q .number -``` - -The body: how many rejected findings the four weeks had, how many lines the -brief lists per review, and `*Written by an agent.*`. - -## 2. Review and merge - -As `toolchain.md` "Routines" says. The kind is `docs-only`, so only the -claims review runs. - -## Report - -``` -Routine: calibrate-reviews Rejected: in four weeks -PR: #M merged | #M open () | none -``` - -Calibration uses canonical incorrect findings, excluding duplicate, -intentional and nonblocking outcomes. Preserve unknown legacy outcomes; -do not infer false positives from raised-minus-fixed. For model promotion, -use the replay/shadow protocol and the run measurement in -`docs/internal/REVIEW.md`, not this rejection sample alone. diff --git a/.claude/skills/spec-session/interview.md b/.claude/skills/spec-session/interview.md index bab4398a3..01dc7e1a1 100644 --- a/.claude/skills/spec-session/interview.md +++ b/.claude/skills/spec-session/interview.md @@ -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: ...`). @@ -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. diff --git a/AGENTS.md b/AGENTS.md index ac38fe2f4..ab02188da 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 | diff --git a/docs/internal/DELIVERY.md b/docs/internal/DELIVERY.md index 067777c07..48e2fd9b5 100644 --- a/docs/internal/DELIVERY.md +++ b/docs/internal/DELIVERY.md @@ -184,8 +184,8 @@ ADRs to _Accepted_ (delivery rule 10) is yours too, unless delivery did it. `node .agents/scripts/delivery-stats.mjs` prints one row per week for the last five: blocking findings per review raised and fixed, notes, PRs needing a second round, median hours to merge, rounds and tokens, -handoffs. `--since ` lists PRs; `--calibration` prints the recent -incorrect findings every reviewer reads. `delivery-counters.mjs --since +handoffs. `--since ` lists PRs; `--calibration` prints the last four +weeks' rejected findings, to read when a review's confirmation rate drops. `delivery-counters.mjs --since ` prints the per-PR counters the process review judges delivery changes by (CI lines sent to fix runs, stack syncs, empty builds, fix runs that changed nothing, tests per Tests line), and `instruction-reads.mjs` @@ -193,7 +193,7 @@ how often each role opens each rule, brief and manual. Change one thing in the pipeline at a time and compare the rows before and after. Weekly routines keep the suite and the reviews in shape: `harden-tests`, -`audit-tests`, `garden-comments`, `calibrate-reviews` and `refactor` +`audit-tests`, `garden-comments` and `refactor` ([toolchain.md](agent-rules/toolchain.md) "Routines"). `check-upstream` reads every `upstream` issue's `## Waiting on upstream` links each week and comments when they are fixed in a release; you move the issue back to diff --git a/docs/internal/agent-rules/toolchain.md b/docs/internal/agent-rules/toolchain.md index 689160143..119fe40d2 100644 --- a/docs/internal/agent-rules/toolchain.md +++ b/docs/internal/agent-rules/toolchain.md @@ -109,7 +109,6 @@ kind gets and the merge gate: | Test hardening | `harden-tests` | weekly | | Test audit | `audit-tests` | weekly | | Comment gardening | `garden-comments` | weekly | -| Review calibration | `calibrate-reviews` | weekly | | Recurring findings | `recurring-findings` | weekly | | Refactor | `refactor` | weekly | | Upstream check | `check-upstream` | weekly | diff --git a/src/pr-body-check.test.ts b/src/pr-body-check.test.ts index 89e922fbc..b7288ab57 100644 --- a/src/pr-body-check.test.ts +++ b/src/pr-body-check.test.ts @@ -458,14 +458,11 @@ describe("pr-body-check.mjs", { timeout: 20_000 }, () => { }).trim(); git("init", "-q"); mkdirSync(join(repo, "src")); - mkdirSync(join(repo, ".agents", "briefs"), { recursive: true }); writeFileSync(join(repo, "src", "a.ts"), "export const a = 1;\n"); - writeFileSync(join(repo, ".agents", "briefs", "calibration.md"), "x\n"); git("add", "."); git("commit", "-qm", "base"); const base = git("rev-parse", "HEAD"); writeFileSync(join(repo, "src", "a.ts"), "export const a = 2;\n"); - writeFileSync(join(repo, ".agents", "briefs", "calibration.md"), "y\n"); git("commit", "-qam", "change"); const head = git("rev-parse", "HEAD"); const routine = (branch: string) => { @@ -494,9 +491,6 @@ describe("pr-body-check.mjs", { timeout: 20_000 }, () => { expect(routine("chore/audit-tests-2026-10-25")).toContainEqual( expect.stringContaining("must be tests-only"), ); - expect(routine("chore/calibrate-reviews-2026-10-25")).toContainEqual( - expect.stringContaining("it also changes src/a.ts"), - ); }); it("takes the repo from the origin remote when GH_REPO is unset", () => {