@feigi/fleet-ctl 3.156.2 → 3.158.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/agents/fleet-fix-applier.agent.md +33 -6
- package/agents/fleet-review-runner.agent.md +3 -5
- package/agents/fleet-review-tests.agent.md +4 -1
- package/commands/review-and-fix.md +6 -4
- package/package.json +1 -1
- package/scripts/evict.mjs +23 -7
- package/scripts/fleet-event.mjs +23 -45
- package/scripts/fleet-state.mjs +14 -11
- package/scripts/fleet-tick.mjs +71 -26
- package/scripts/ledger-grammar.mjs +25 -6
- package/scripts/ledger.mjs +114 -19
- package/scripts/measure-copy.mjs +242 -0
- package/scripts/reclaim-scratch.mjs +149 -29
- package/scripts/review-core.mjs +31 -20
- package/scripts/review-eval.mjs +11 -17
- package/skills/run-team/SKILL.md +5 -5
- package/skills/run-team/references/finisher.md +2 -2
- package/skills/run-team/references/isolation.md +16 -0
- package/skills/run-team/references/ledger.md +1 -1
- package/skills/run-team/references/member-lifecycle.md +2 -2
- package/skills/run-team/references/reviewers.md +12 -0
package/scripts/review-eval.mjs
CHANGED
|
@@ -145,11 +145,12 @@ export async function runReviewOnOmp(args) {
|
|
|
145
145
|
// keep out of its context. The run root is the review's own
|
|
146
146
|
// `<scratch>/pr<pr>/run-XXXXXXXX`, the directory review-core.mjs's snapshot
|
|
147
147
|
// step made with `mktemp` and the snapshot it returns sits in, so two reviews
|
|
148
|
-
// of one PR — at one head or two — never write one file, and the
|
|
149
|
-
// names the run whose file it is. No
|
|
148
|
+
// of one PR — at one head or two — never write one file, and the `reviewed=`
|
|
149
|
+
// `ledger.mjs review --result` derives names the run whose file it is. No
|
|
150
|
+
// file is ever replaced. The file leaves
|
|
150
151
|
// with its run root: the snapshot step of a later review of the same PR
|
|
151
|
-
// removes that PR's run roots not touched for seven days, so a
|
|
152
|
-
// than that names a file that is gone.
|
|
152
|
+
// removes that PR's run roots not touched for seven days, so a `reviewed=`
|
|
153
|
+
// older than that names a file that is gone.
|
|
153
154
|
//
|
|
154
155
|
// Failure is a throw or an empty return. The holder of the review call retries
|
|
155
156
|
// once; a second failure returns `failed` with both errors, and writes no
|
|
@@ -186,22 +187,18 @@ export async function runReviewToFile(args, run = runReviewOnOmp) {
|
|
|
186
187
|
errors.push(`attempt ${attempt}: ${e?.message ?? String(e)}`);
|
|
187
188
|
continue;
|
|
188
189
|
}
|
|
189
|
-
// `
|
|
190
|
-
//
|
|
191
|
-
//
|
|
192
|
-
//
|
|
193
|
-
//
|
|
194
|
-
// `run(args)` call), leaving a half-written review file on disk
|
|
195
|
-
// that a fix-applier reading it would mistake for a completed review that
|
|
196
|
-
// never actually finished. Treated the same as an empty return: retried,
|
|
197
|
-
// then reported `failed`, and no file is written for it.
|
|
190
|
+
// A result with no object `counts` is no completed review: its digest
|
|
191
|
+
// would carry no counts, and `ledger.mjs review --result` derives no
|
|
192
|
+
// `reviewed=` from a file without them, so a fix-applier reading it would
|
|
193
|
+
// hold a review nothing can record. Treated the same as an empty return:
|
|
194
|
+
// retried, then reported `failed`, and no file is written for it.
|
|
198
195
|
if (!result || typeof result !== "object" || !result.counts || typeof result.counts !== "object") {
|
|
199
196
|
errors.push(`attempt ${attempt}: empty return (${String(result)})`);
|
|
200
197
|
continue;
|
|
201
198
|
}
|
|
202
199
|
// The run root is read off the result, never rebuilt: only the snapshot
|
|
203
200
|
// step's shell knew the `mktemp` name. A result whose snapshot is not in
|
|
204
|
-
// a run root of this PR under this scratch names no run
|
|
201
|
+
// a run root of this PR under this scratch names no run a `reviewed=`
|
|
205
202
|
// could point a reader back to, so it is a failed attempt like the one
|
|
206
203
|
// above.
|
|
207
204
|
const runRoot = runRootOf(result.snapshot, scratch, pr);
|
|
@@ -231,12 +228,9 @@ export async function runReviewToFile(args, run = runReviewOnOmp) {
|
|
|
231
228
|
errors.push(`attempt ${attempt}: could not write ${path}: ${e?.message ?? String(e)}`);
|
|
232
229
|
continue;
|
|
233
230
|
}
|
|
234
|
-
const { survived, refuted, unverified } = result.counts;
|
|
235
231
|
return {
|
|
236
232
|
status: "completed",
|
|
237
233
|
path,
|
|
238
|
-
// The review's result token, ready for `ledger.mjs review <pr>`.
|
|
239
|
-
ledger: `reviewed=${result.head}:${survived}/${refuted}/${unverified}:${basename(runRoot)}`,
|
|
240
234
|
attempts: attempt,
|
|
241
235
|
errors,
|
|
242
236
|
digest: digestOf(result),
|
package/skills/run-team/SKILL.md
CHANGED
|
@@ -223,7 +223,7 @@ Record each ruling with `ledger.mjs ruled <pr> <decision>`, one line with its re
|
|
|
223
223
|
|
|
224
224
|
### Dispatching the members a wake names
|
|
225
225
|
|
|
226
|
-
- **The reviewer.** **Dispatch the review, never wait on it, and act when its result lands. That is the default path.** `DISPATCH review PR#<M>`: a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch`. Record `review=member:review-pr-<pr#>` on the PR's row before the call, with `ledger.mjs review <pr> <token>`: the tick counts in-flight reviews off the ledger and nowhere else. `scratch` is the scratch root itself, never a `pr<N>` partition (`references/reviewers.md`). The runner writes the result file and reports its path
|
|
226
|
+
- **The reviewer.** **Dispatch the review, never wait on it, and act when its result lands. That is the default path.** `DISPATCH review PR#<M>`: a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch`. Record `review=member:review-pr-<pr#>` on the PR's row before the call, with `ledger.mjs review <pr> <token>`: the tick counts in-flight reviews off the ledger and nowhere else. `scratch` is the scratch root itself, never a `pr<N>` partition (`references/reviewers.md`). The runner writes the result file and reports its path.
|
|
227
227
|
A row with `review=` and no `reviewed=` is a review in flight, and the tick counts it as a live review unit unless gh reports its PR MERGED or CLOSED.
|
|
228
228
|
- **The fix-applier.** `DISPATCH fix-pr PR#<M>` on a `reviewed=` count that survived or unverified findings, with no fix-applier live: name `fix-pr-<pr#>` (the next suffix if that name is on record), never the PR's implementer; render with `dispatch-prompt.mjs render fix-applier --kind review --member fix-pr-<pr#> …`, then record `ledger.mjs dispatch <pr#> fix-pr-<pr#>` before the call. Its brief carries the PR number, the worktree abs path, the PR's branch, the same `testCmd` you passed the review, and the **path** `<scratch>/pr<pr>/<run>/review.json`, `<run>` off the PR's latest `reviewed=` — never the findings. Every `<scratch>` in that brief is the absolute path `scratch-root.mjs` printed. Its rulings are the fix-applier body's (`agents/fleet-fix-applier.agent.md`); you hold none, and a refuter report that surfaces to you is its to retrieve, never yours to scan or pass on. On a PR carrying `ready-to-merge`, its push moves the head after the label: a fresh finisher, per **Failure handling**.
|
|
229
229
|
- **The conflict hold.** `DISPATCH fix-pr PR#<M>` on a conflict hold: the row carries an unresolved `conflict-hold:#<M>`, the merge bot's or one you recorded off the tick's `CONFLICT` line. It is the same slot with a different job, and no review file to hand over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is on record; render with `dispatch-prompt.mjs render fix-applier --kind conflict --member <name> …`; dispatch with the `agent` `ledger.mjs dispatch` printed, in the PR's existing worktree. Settle `applied:<head>`, or `no-op` if no conflict was left, which lifts the merge hold; a dispatched-but-live one does not, and `failed`/`killed` leave the PR fix-due for a replacement; a second `failed` since its latest review escalates. It answers the hold and nothing else: review findings the row also carries get a review `DISPATCH fix-pr PR#<M>` once it lands.
|
|
@@ -256,9 +256,9 @@ references/isolation.md.
|
|
|
256
256
|
|
|
257
257
|
**You read the digest; the findings are the fix-applier's.**
|
|
258
258
|
`jq '{pr, head, resume, testEnvironment, suiteVerdict, dimensionsRun, dimensionsUnrun, cwdAudit, counts}' <scratch>/pr<pr>/<run>/review.json`
|
|
259
|
-
is the whole of your read
|
|
260
|
-
off `head`, `counts` and the run root's
|
|
261
|
-
|
|
259
|
+
is the whole of your read. The record is the `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>`
|
|
260
|
+
the `fleet-event.mjs review-result <pr> <path>` wake writes on the PR's row, off `head`, `counts` and the run root's
|
|
261
|
+
name, never one typed with `ledger.mjs review <pr>`. Every later path to the review is built from that token, before a
|
|
262
262
|
restart or after one: `<scratch>/pr<pr>/<run>/review.json`, `<run>` off the PR's
|
|
263
263
|
latest `reviewed=`. Findings never enter your context. The fix-applier
|
|
264
264
|
reads every one off the file and makes every ruling on them
|
|
@@ -748,7 +748,7 @@ decides the rest — two resolve automatically, every other one escalates:
|
|
|
748
748
|
| Cause | Resolution |
|
|
749
749
|
|---|---|
|
|
750
750
|
| `live-editor` | **Automatic.** Ask the live member **by name** for its report, wait for it, then dispatch `finisher-pr-<M>-b` at the current head. If the head moved in the meantime, resolve it as `past-pin` instead. |
|
|
751
|
-
| `past-pin` | **Automatic, through the tick: re-review.** The head carries commits no reviewer read. The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's
|
|
751
|
+
| `past-pin` | **Automatic, through the tick: re-review.** The head carries commits no reviewer read. The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's launch as any review's, with `ledger.mjs review <M>` onto the PR's row, its runner the next free letter `review` names, and its result reaches a fresh finisher through the same gate. |
|
|
752
752
|
| `rebase` | **Escalate** — comment and flag, nothing more. The report's `evidence.replay` reads `pure` only when `git range-diff origin/main <pin> HEAD` pairs every pinned commit with an unchanged one; `changed` (a commit dropped, edited or added, or a stale `origin/main`) or `unknown` means read `evidence.rangeDiff` before acting, and `evidence.remote.state` says whether that head is on the PR. No automatic rule until a live halt shows the case recurring. |
|
|
753
753
|
| `stray` | **Escalate** — comment and flag; nothing pushes it automatically. Read `evidence.cherry`, `.content` and `.remote`. Push or discard is yours, or the maintainer's if they cannot settle it. A pushed stray is unreviewed: `ledger.mjs review <M>` first. |
|
|
754
754
|
| `unreadable`, `missing`, `absent`, `other` | **Escalate** — comment and flag, no automatic retry. |
|
|
@@ -385,14 +385,14 @@ absent; `carries` null: the read could not be told, and `error` says why). A
|
|
|
385
385
|
commit that undoes something the pin carries reads clean by content (`paths`
|
|
386
386
|
empty) and only its `+` line catches it, so a `+` beside empty `paths` is not
|
|
387
387
|
by itself safe to discard. A pushed stray is a head no reviewer read: record
|
|
388
|
-
its review by hand with `ledger.mjs review <M>`, under the next runner letter
|
|
388
|
+
its review launch by hand with `ledger.mjs review <M>`, under the next runner letter
|
|
389
389
|
as for a `past-pin` re-review below, before any finisher is dispatched.
|
|
390
390
|
|
|
391
391
|
A `human` halt is a Ticketless PR whose diff is not inert: the maintainer adds
|
|
392
392
|
`ready-to-merge` at the pinned head, which the merge bot merges off the
|
|
393
393
|
finisher's `ready-to-merge-head:` comment; a moved head is merged by hand.
|
|
394
394
|
|
|
395
|
-
The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's
|
|
395
|
+
The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's launch as any review's, with `ledger.mjs review <M>` onto the PR's row, its runner under the next letter the PR's rows do not carry yet (`review-pr-<M>-b`, or `-c` where a retry already took `-b`) — `review` refuses a second `review-pr-<M>` and names the free one — and its result, recorded by the `review-result` wake, reaches a fresh finisher through the same gate.
|
|
396
396
|
|
|
397
397
|
A halt at duty 1 reads identical from a bare SHA mismatch whatever caused it,
|
|
398
398
|
and the causes `finisher-audit.mjs` names are the ones seen so far, not a
|
|
@@ -118,6 +118,22 @@ or a fix-applier into one; before you run code in one by hand, restore it with
|
|
|
118
118
|
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run evict.mjs --restore <tree> --apply`, which runs the
|
|
119
119
|
Install step there as a claim does.
|
|
120
120
|
|
|
121
|
+
**One script builds every measuring copy.** A copy an agent mutates or runs a
|
|
122
|
+
suite in — a fix-applier's own, its refuters', a review specialist's and a
|
|
123
|
+
review refuter's — is built by `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run measure-copy.mjs --worktree <abs-path> --pin <sha> --dest <abs> --pr <N> --scratch <scratch>`:
|
|
124
|
+
the tree at the pinned commit, made a repository of its own, with the Install
|
|
125
|
+
step run in it. It reads the Install step from the PR worktree, since a copy
|
|
126
|
+
holds no Recipe cache, and it refuses any `--dest` that is not a new directory
|
|
127
|
+
inside a `fix-*` round root or a `run-*` run root directly under
|
|
128
|
+
`<scratch>/pr<N>/`. A fix-applier makes its round root with `mktemp -d` before
|
|
129
|
+
its first copy, whatever kind of dispatch it is, and no `pr<N>/mutate/` is
|
|
130
|
+
made. Exit 0 means the copy is the pin's tree and the Install step exited 0;
|
|
131
|
+
any other exit is no usable copy. The root sweep evicts the installed
|
|
132
|
+
dependencies of every such tree once no member of the kind that made them is
|
|
133
|
+
live on the ledger, and the tick runs the sweep after each fix-applier,
|
|
134
|
+
failed review launch and finisher settles, so no fix-applier or finisher runs
|
|
135
|
+
an eviction step of its own.
|
|
136
|
+
|
|
121
137
|
## Filesystem isolation is not stack isolation
|
|
122
138
|
|
|
123
139
|
Private copy and test command solve different problems; conflating them is how second gets skipped: compose project name comes from environment, not working directory, so three agents on three snapshots still collide on one postgres. Observed: a probe returned `No test files found / No such container` and would have read as a test failure. Symlinking installed dependencies in does not help. "I'm on my own copy" is exactly the intuition that skips command — say both, every time. Which command depends on audience: member in worktree uses `./agent-test`; specialist on snapshot does not, takes one `review-and-fix.md` hands out. Which runner the worktree holds decides why: the runner a claim writes is untracked, so a `git archive` snapshot never carries it; one the repository tracks does ride along, but no claim exported ports into it — its isolation is whatever that repository built, not one triple per snapshot.
|
|
@@ -104,7 +104,7 @@ PR stays queued, label untouched, and no member is dispatched to restore the lin
|
|
|
104
104
|
|
|
105
105
|
## The review pair on a PR's row
|
|
106
106
|
|
|
107
|
-
A PR's review is not a member, so it carries its own pair of row tokens, written with `review` onto the PR's row (**The reviewer**): `review=wf:<runId>` | `review=member:<name>` at launch, `<name>` being `review-pr-<n>` for the PR's first runner and the next letter its rows do not carry yet (`review-pr-<n>-b`, `-c`, …) for every later one, settled dead as `…=failed`, then `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>` when the result lands, `<run>` the review's `run-XXXXXXXX` run root under `<scratch>/pr<n>/`, which holds its `review.json`.
|
|
107
|
+
A PR's review is not a member, so it carries its own pair of row tokens, written with `review` onto the PR's row (**The reviewer**): `review=wf:<runId>` | `review=member:<name>` at launch, `<name>` being `review-pr-<n>` for the PR's first runner and the next letter its rows do not carry yet (`review-pr-<n>-b`, `-c`, …) for every later one, settled dead as `…=failed`, then `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>` when the result lands, `<run>` the review's `run-XXXXXXXX` run root under `<scratch>/pr<n>/`, which holds its `review.json`. A `reviewed=` is a Gate verdict: `ledger.mjs review <pr> --result <path>` derives it from that file, and the `fleet-event.mjs review-result <pr> <path>` wake runs it. No `review` argument carries one, and one typed there is refused.
|
|
108
108
|
|
|
109
109
|
## The ledger's readability field: `ledger.ok`
|
|
110
110
|
|
|
@@ -6,7 +6,7 @@ Why member name load-bearing, why every member single-use, how a member's job ou
|
|
|
6
6
|
|
|
7
7
|
## Every member is named
|
|
8
8
|
|
|
9
|
-
The name is the ledger token and the hub address (`hub send <name>`, `agent://<name>`); omit it and the ledger cannot match the member. Names follow unit of work: `impl-<issue#>`, `fix-pr-<pr#>` (default path's applier), `review-pr-<pr#>` (the PR's first reviewer; every later one on the PR — failed-runner retry, past-pin re-review — takes the next letter the PR's row does not carry yet, `review-pr-<pr#>-b`, `-c`, …; a reviewer's launch
|
|
9
|
+
The name is the ledger token and the hub address (`hub send <name>`, `agent://<name>`); omit it and the ledger cannot match the member. Names follow unit of work: `impl-<issue#>`, `fix-pr-<pr#>` (default path's applier), `review-pr-<pr#>` (the PR's first reviewer; every later one on the PR — failed-runner retry, past-pin re-review — takes the next letter the PR's row does not carry yet, `review-pr-<pr#>-b`, `-c`, …; a reviewer's launch is recorded on the PR's row with `ledger.mjs review <pr#>`, its result by the `review-result` wake), `finisher-pr-<pr#>` (the finisher gate's finisher), `merge-bot-<n>` (one merge pass; `ledger.mjs dispatch merge-bot` numbers it from the ledger's `## Dispatched` list — a per-run counter, never a PR).
|
|
10
10
|
|
|
11
11
|
## The coordination contract
|
|
12
12
|
|
|
@@ -191,7 +191,7 @@ A mismatch on a ticket whose issue is already CLOSED holds nothing: the tick pro
|
|
|
191
191
|
|
|
192
192
|
## Dispatching the members a wake names, in full
|
|
193
193
|
|
|
194
|
-
- **The reviewer.** **Dispatch the review, never wait on it, and act when its result lands. That is the default path.** `DISPATCH review PR#<M>`: a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch`. Record `review=member:review-pr-<pr#>` on the PR's row before the call. `scratch` is the scratch root itself, never a `pr<N>` partition (`references/reviewers.md`). Write the `review=` token with `ledger.mjs review <pr> <token>`; `ledger.mjs` refuses a bad grammar. The tick names every PR owed one, oldest first, and each gets one review, once per PR. The tick counts in-flight reviews off the ledger and nowhere else, so a review you launched and never recorded is one it names again. The runner writes the result file and reports its path
|
|
194
|
+
- **The reviewer.** **Dispatch the review, never wait on it, and act when its result lands. That is the default path.** `DISPATCH review PR#<M>`: a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch`. Record `review=member:review-pr-<pr#>` on the PR's row before the call. `scratch` is the scratch root itself, never a `pr<N>` partition (`references/reviewers.md`). Write the `review=` token with `ledger.mjs review <pr> <token>`; `ledger.mjs` refuses a bad grammar. The tick names every PR owed one, oldest first, and each gets one review, once per PR. The tick counts in-flight reviews off the ledger and nowhere else, so a review you launched and never recorded is one it names again. The runner writes the result file and reports its path; the `fleet-event.mjs review-result <pr> <path>` wake records its `reviewed=`.
|
|
195
195
|
A row with `review=` and no `reviewed=` is a review in flight, and the tick counts it as a live review unit unless gh reports its PR MERGED or CLOSED.
|
|
196
196
|
- **The fix-applier.** `DISPATCH fix-pr PR#<M>` on a `reviewed=` count that survived or unverified findings, with no fix-applier live: name `fix-pr-<pr#>` (the next suffix if that name is on record), never the PR's implementer; render with `dispatch-prompt.mjs render fix-applier --kind review --member fix-pr-<pr#> …`, then record `ledger.mjs dispatch <pr#> fix-pr-<pr#>` before the call. Its brief carries the PR number, the worktree abs path, the PR's branch, the same `testCmd` you passed the review, and the **path** `<scratch>/pr<pr>/<run>/review.json`, `<run>` off the PR's latest `reviewed=` — never the findings. Every `<scratch>` in that brief is the absolute path `scratch-root.mjs` printed. Its rulings are the fix-applier body's (`agents/fleet-fix-applier.agent.md`); you hold none. It holds every finding and you hold none, so there is nothing for you to rank, relay or pre-rule — and a report from a refuter it spawns that surfaces to you is its to retrieve, never yours to scan or pass on. It answers the hold and nothing else: survived or unverified findings of a returned review the row also carries stay unanswered through its settle, so the tick prints `DISPATCH fix-pr PR#<M>` again once it lands, and that one is a review fix-applier, dispatched as above. On a PR carrying `ready-to-merge`, the push moves the head after the label, so the next merge bot refuses it `head-moved-after-label-#<M>` and its report's settle takes the label off; then a fresh finisher, per **Failure handling**.
|
|
197
197
|
- **The conflict hold.** `DISPATCH fix-pr PR#<M>` on a conflict hold: the row carries an unresolved `conflict-hold:#<M>`, the merge bot's or one you recorded off the tick's `CONFLICT` line. It is the same slot with a different job, and no review file to hand over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is on record; render with `dispatch-prompt.mjs render fix-applier --kind conflict --member <name> …`; dispatch with the `agent` `ledger.mjs dispatch` printed, in the PR's existing worktree. Read the definition off that output (`fleet-fix-applier` whatever the row's `tier=`), never recall it. Settle `applied:<head>`, or `no-op` if no conflict was left, which lifts the merge hold; a dispatched-but-live one does not, and `failed`/`killed` leave the PR fix-due for a replacement, but a second `failed` since the PR's latest review escalates (`ESCALATE fix-failed`).
|
|
@@ -237,3 +237,15 @@ diff.
|
|
|
237
237
|
## What an unbounded read costs
|
|
238
238
|
|
|
239
239
|
`review-and-fix.md`'s **Then bound the read** rests on this. The cost of not bounding is never one-off: a specialist that dumps a 37 KB file carries it in its prefix for every remaining turn, re-billed as cache-read on each. Over one run's 92 subagents the 88 unpiped whole-file calls carried 434 KB (~110k tokens) — the single largest attributed line item in that run — against 319 piped ones. Agents already reach for the bounded form; nothing told them when it is required.
|
|
240
|
+
|
|
241
|
+
## Bracing a ref held in a variable
|
|
242
|
+
|
|
243
|
+
`review-and-fix.md`'s **Brace a ref held in a variable** rests on this. The history modifier applies inside double quotes as well as outside. Measured, fully quoted: the construct that fails loudly on one path exits 0 on another and prints the *commit* instead of the blob — and the silent shape is the hazard, because a survival `grep -c` scores it as a plausible hit and re-anchors a citation that was correct. A literal ref is unaffected either way; quote regardless — not for zsh's sake, which splits and globs an expansion's *result* only under `SH_WORD_SPLIT`/`GLOB_SUBST`, both off by default (measured: `V="a b"` unquoted still arrives as one argument), but so the same line survives a `bash` runner, where an unquoted path holding a space does split — measured, `fatal: path 'has' does not exist`.
|
|
244
|
+
|
|
245
|
+
## Two refuters approved changes that could not both land
|
|
246
|
+
|
|
247
|
+
`review-and-fix.md`'s **Scan the findings against each other for MUTUAL EXCLUSION** rests on this. Two runs produced it; in one, a refuter proved a variable collapse behavior-equivalent over 844 cases while its own blast-radius scan named the two comment blocks a *different* refuter had just established as guarding distinct pinned hazards.
|
|
248
|
+
|
|
249
|
+
## What a comment's false claim cost
|
|
250
|
+
|
|
251
|
+
`review-and-fix.md`'s **Comments are findings** rests on this. One run shipped five: an invented citation, a mis-stated failure mode, a test file named as covering what it had zero coverage of, an overstated cast fix, a claim its own dependency's source contradicts.
|