@mjasnikovs/pi-task 0.38.29 → 0.38.30

package/dist/task/spec-validation.js

@@ -13,15 +13,15 @@ export function parseVerifyBlock(spec) {
 /**
  * parseVerifyBlock, but only when the fenced block is actually CLOSED.
  *
- * An unterminated fence makes the lenient parser swallow the rest of the file:
- * mx5 run 19's `TASK_0001.md` opens ```sh and never closes it, so its "VERIFY
- * commands" include the phase-timings table and every appended gate-trail line.
+ * An unterminated fence makes the lenient parser swallow the rest of the file: a
+ * task file that opens ```sh and never closes it yields "VERIFY commands" that
+ * include every line appended after the spec — a timings table, a gate-trail line.
  * That is harmless where the parser only asks "is there something runnable here",
- * and NOT harmless where a parsed line is treated as provenance — a debt reason
- * quoting `bun run lint` would match a gate-trail sentence and mint a stored,
+ * and NOT harmless where a parsed line is treated as PROVENANCE: a debt reason
+ * quoting `bun run lint` would then match a trail sentence and mint a stored,
  * re-runnable command the spec never asked for (accept-debt.ts
- * verifyCommandFromReason, `inv-command-provenance`). Callers that need the block
- * to MEAN something use this one: an unclosed fence is no block at all.
+ * `verifyCommandFromReason`, `inv-command-provenance`). Callers that need the
+ * block to MEAN something use this one: an unclosed fence is no block at all.
  */
 export function parseVerifyBlockStrict(spec) {
     const scan = scanVerifyBlock(spec);
@@ -119,24 +119,21 @@ export const REFINE_SECTIONS = [
 /**
  * Is a refine child's output shaped like a refined prompt?
  *
- * Refine shipped with NO shape check at all — `phaseRefine` passes no validator,
- * unlike compose and critique — and every downstream reader of a refined prompt
- * is a PARTIAL parser that tolerates a missing section SILENTLY:
- * `extractCapsSection` (refuted-constraint.ts) returns null, `scopedToolingGoal`
- * (phases.ts) returns the whole text, `deriveTitle` and `extractEnrichTargets`
- * fall back. So a refine answer that dropped a heading degrades four features at
- * once and says nothing. This names the contract in one place.
+ * Every downstream reader of a refined prompt is a PARTIAL parser that tolerates a
+ * missing section SILENTLY: `extractCapsSection` (refuted-constraint.ts) returns
+ * null, `scopedToolingGoal` (phases.ts) returns the whole text, and `deriveTitle`
+ * (parsers.ts) and `extractEnrichTargets` (enrichment.ts) fall back. So a refine
+ * answer that dropped a heading degrades four features at once and says nothing.
+ * This names the contract in one place; phases.ts calls it after refine.
  *
  * WHAT IT CHECKS, and why it is only this. Every one of those consumers looks
  * for a BARE ALL-CAPS heading alone on its own line — `l.trim() === heading`,
  * `/^GOAL[ \t]*\n/m`. That is the operative contract, so that is the test.
  *
- * It does NOT require the text to START with GOAL, even though REFINE_PROMPT
- * says "four sections, exact headings, in this order" and forbids a preamble.
- * Measured over the 57-task mx5 corpus: 55/56 non-empty refined prompts carry
- * all four bare headings, but only 25/56 open with one — a preamble is what real
- * refine output usually looks like, and production has always consumed it fine.
- * A validator stricter than its consumers would reject work that works.
+ * It does NOT require the text to START with GOAL, even though REFINE_PROMPT asks
+ * for the four headings in order and forbids a preamble. None of the four
+ * consumers above cares where the heading sits, so a validator that did would
+ * reject work every one of them handles.
  *
  * Returns a problem string, or null when the shape is good — same contract as
  * `validateSpecShape` above.

package/dist/task/stall-detector.d.ts

@@ -2,16 +2,11 @@
  * Progress-based runaway guard for phase children — the replacement for a
  * wall-clock cap.
  *
- * WHY NOT SECONDS. PHASE_CHILD_TIMEOUT_MS was sized against "measured HEALTHY
- * planning children" on one local backend: decompose 89s, so 600s looked like a
- * 6x margin. That sizing is not a property of the pathology, it is a property of
- * that day's model, that day's samplers and that day's design doc. Measured on
- * the same 27B backend with reasoning ON (2026-08-17, n=10 replays of one
- * captured auto-decompose request, everything else byte-identical): every single
- * healthy run took 610-927s and produced 26-42 correct titles. The cap would
- * have killed 10 out of 10 GOOD runs. A slower model, a bigger design doc or a
- * longer reasoning budget moves that number again — so any constant in seconds
- * is wrong for someone.
+ * WHY NOT SECONDS. A wall clock has to be sized against how long a HEALTHY child
+ * takes, and that is not a property of the pathology — it is a property of the
+ * model, its sampler settings, the reasoning budget and the size of the document
+ * being read. Any of those moving turns the margin into a killer of good runs.
+ * `PHASE_CHILD_TIMEOUT_MS` is 0 (off) for exactly that reason.
  *
  * WHAT REPLACES IT. Two bounds, both dimensionless — invariant to model speed,
  * project size and reasoning budget:
@@ -22,26 +17,25 @@
  *      never trips, however slow it is. A child re-opening the same four files
  *      trips after NO_PROGRESS_LIMIT of them, however fast it is.
  *
- *      Judged on the RESULT, not the arguments, because the arguments lie. The
- *      thrash measured on 2026-08-17 was 197 of 200 calls REFUSED by the
- *      single-read guard, each at a different rising offset — so by arguments it
- *      looked like textbook forward paging, and both an offset rule and the loop
- *      detector's path rule waved all 200 through. By result it is 197 identical
- *      refusals in a row, which is what it actually was.
+ *      Judged on the RESULT, not the arguments, because the arguments lie. A child
+ *      whose reads are all REFUSED — by the single-read guard, say — can issue
+ *      them at steadily rising offsets, so by arguments it looks like textbook
+ *      forward paging and an offset rule waves every one through. By result it is
+ *      one identical refusal after another.
  *
  *   2. CONTEXT CHURN. Sum the bytes of tool RESULTS the child has pulled in. Once
  *      that exceeds CONTEXT_CHURN_FACTOR times its own context window and it
  *      still has not answered, it has necessarily forgotten what it read first
- *      and is re-reading to fill a window pi keeps compacting. That is the
- *      mx5-n 2026-08-14 shape: 16m23s at 117,370 of a 120,064-token window,
- *      ~56k tokens of tool output per minute, forward-paging the whole time so
- *      rule 1 alone would not have caught it. The bound scales with the model's
+ *      and is re-reading to fill a window pi keeps compacting. This catches the
+ *      child rule 1 cannot: one that pages FORWARD the whole time, pulling in new
+ *      bytes on every call, and never converges. The bound scales with the model's
  *      OWN window, so a 1M-context model gets a 1M-context allowance.
  *
  *      The window is supplied by the PARENT at spawn (`PhaseDeps.contextWindow`),
- *      not read off the child's event stream: pi emits no context event at all,
- *      which is why this rule sat disarmed from the day it was written until
- *      GitHub issue #16.
+ *      not read off the child's event stream: pi's `--mode json` stream carries no
+ *      context event at all. A detector that waited to be told one sits at 0, and
+ *      `churnTripped` returns false on a non-positive window — so the rule would
+ *      never fire.
  *
  * Neither rule can fire on a child that is thinking rather than calling tools:
  * that case is bounded by the model's max tokens (server-enforced) and by the
@@ -58,11 +52,10 @@ import type { LoopHit, ToolCall } from '../shared/child-process.js';
  *
  * Eight, because the honest reasons to get back something you have already seen
  * are few and bounded: re-checking a file after an edit, a grep that lands in a
- * file already read, a retry after a malformed call, a missing path. A child
- * doing real work interleaves those with progress and resets the counter. In the
- * replayed thrash the counter never resets at all — the observed runs made
- * 188-201 consecutive dead calls. The gap between "a handful" and "two hundred"
- * is wide enough that the exact value is not load-bearing.
+ * file already read, a retry after a malformed call, a missing path. A child doing
+ * real work interleaves those with progress and RESETS the counter, so the streak
+ * only survives when nothing at all is being learned. The exact value is not
+ * load-bearing: a genuine thrash never resets and runs on indefinitely.
  */
 export declare const NO_PROGRESS_LIMIT = 8;
 /**
@@ -109,7 +102,7 @@ export declare class StallDetector {
 /**
  * Restart hint for a child killed by the stall detector. Names the specific
  * mistake — re-reading covered ground vs pulling in more than it can hold —
- * because "you ran out of time" (the old wall-clock hint) told a model that was
- * working correctly but slowly to truncate its work for no reason.
+ * because "you ran out of time" tells a model that was working correctly but
+ * slowly to truncate its work for no reason.
  */
 export declare function formatStallHint(kind: StallKind): string;

package/dist/task/stall-detector.js

@@ -2,16 +2,11 @@
  * Progress-based runaway guard for phase children — the replacement for a
  * wall-clock cap.
  *
- * WHY NOT SECONDS. PHASE_CHILD_TIMEOUT_MS was sized against "measured HEALTHY
- * planning children" on one local backend: decompose 89s, so 600s looked like a
- * 6x margin. That sizing is not a property of the pathology, it is a property of
- * that day's model, that day's samplers and that day's design doc. Measured on
- * the same 27B backend with reasoning ON (2026-08-17, n=10 replays of one
- * captured auto-decompose request, everything else byte-identical): every single
- * healthy run took 610-927s and produced 26-42 correct titles. The cap would
- * have killed 10 out of 10 GOOD runs. A slower model, a bigger design doc or a
- * longer reasoning budget moves that number again — so any constant in seconds
- * is wrong for someone.
+ * WHY NOT SECONDS. A wall clock has to be sized against how long a HEALTHY child
+ * takes, and that is not a property of the pathology — it is a property of the
+ * model, its sampler settings, the reasoning budget and the size of the document
+ * being read. Any of those moving turns the margin into a killer of good runs.
+ * `PHASE_CHILD_TIMEOUT_MS` is 0 (off) for exactly that reason.
  *
  * WHAT REPLACES IT. Two bounds, both dimensionless — invariant to model speed,
  * project size and reasoning budget:
@@ -22,26 +17,25 @@
  *      never trips, however slow it is. A child re-opening the same four files
  *      trips after NO_PROGRESS_LIMIT of them, however fast it is.
  *
- *      Judged on the RESULT, not the arguments, because the arguments lie. The
- *      thrash measured on 2026-08-17 was 197 of 200 calls REFUSED by the
- *      single-read guard, each at a different rising offset — so by arguments it
- *      looked like textbook forward paging, and both an offset rule and the loop
- *      detector's path rule waved all 200 through. By result it is 197 identical
- *      refusals in a row, which is what it actually was.
+ *      Judged on the RESULT, not the arguments, because the arguments lie. A child
+ *      whose reads are all REFUSED — by the single-read guard, say — can issue
+ *      them at steadily rising offsets, so by arguments it looks like textbook
+ *      forward paging and an offset rule waves every one through. By result it is
+ *      one identical refusal after another.
  *
  *   2. CONTEXT CHURN. Sum the bytes of tool RESULTS the child has pulled in. Once
  *      that exceeds CONTEXT_CHURN_FACTOR times its own context window and it
  *      still has not answered, it has necessarily forgotten what it read first
- *      and is re-reading to fill a window pi keeps compacting. That is the
- *      mx5-n 2026-08-14 shape: 16m23s at 117,370 of a 120,064-token window,
- *      ~56k tokens of tool output per minute, forward-paging the whole time so
- *      rule 1 alone would not have caught it. The bound scales with the model's
+ *      and is re-reading to fill a window pi keeps compacting. This catches the
+ *      child rule 1 cannot: one that pages FORWARD the whole time, pulling in new
+ *      bytes on every call, and never converges. The bound scales with the model's
  *      OWN window, so a 1M-context model gets a 1M-context allowance.
  *
  *      The window is supplied by the PARENT at spawn (`PhaseDeps.contextWindow`),
- *      not read off the child's event stream: pi emits no context event at all,
- *      which is why this rule sat disarmed from the day it was written until
- *      GitHub issue #16.
+ *      not read off the child's event stream: pi's `--mode json` stream carries no
+ *      context event at all. A detector that waited to be told one sits at 0, and
+ *      `churnTripped` returns false on a non-positive window — so the rule would
+ *      never fire.
  *
  * Neither rule can fire on a child that is thinking rather than calling tools:
  * that case is bounded by the model's max tokens (server-enforced) and by the
@@ -58,11 +52,10 @@ import { stableStringify } from './loop-detector.js';
  *
  * Eight, because the honest reasons to get back something you have already seen
  * are few and bounded: re-checking a file after an edit, a grep that lands in a
- * file already read, a retry after a malformed call, a missing path. A child
- * doing real work interleaves those with progress and resets the counter. In the
- * replayed thrash the counter never resets at all — the observed runs made
- * 188-201 consecutive dead calls. The gap between "a handful" and "two hundred"
- * is wide enough that the exact value is not load-bearing.
+ * file already read, a retry after a malformed call, a missing path. A child doing
+ * real work interleaves those with progress and RESETS the counter, so the streak
+ * only survives when nothing at all is being learned. The exact value is not
+ * load-bearing: a genuine thrash never resets and runs on indefinitely.
  */
 export const NO_PROGRESS_LIMIT = 8;
 /**
@@ -146,8 +139,8 @@ export class StallDetector {
 /**
  * Restart hint for a child killed by the stall detector. Names the specific
  * mistake — re-reading covered ground vs pulling in more than it can hold —
- * because "you ran out of time" (the old wall-clock hint) told a model that was
- * working correctly but slowly to truncate its work for no reason.
+ * because "you ran out of time" tells a model that was working correctly but
+ * slowly to truncate its work for no reason.
  */
 export function formatStallHint(kind) {
     if (kind === 'context-churn') {

package/dist/task/stream-watchdog.d.ts

@@ -2,12 +2,12 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 /**
  * MAIN-SESSION adapter for the model-stream watchdog.
  *
- * WHY (mx5 run 14): three implementation turns died mid-turn — the session jsonl's
- * last record is an ordinary assistant message, then silence forever, while the
- * model container stayed Up(healthy). No error is ever thrown for this shape, so
- * the connection-error retry (which needs a reported ModelError) cannot fire and
- * the command watchdog, which only covers tool executions, never arms. The run sat
- * dead for ~2.9h across the three until a human restarted it.
+ * WHY: a turn can die mid-stream — the last thing recorded is an ordinary
+ * assistant message, then silence forever, with the model endpoint still up.
+ * Nothing throws for that shape, so the connection-error retry (which needs a
+ * reported ModelError) cannot fire, and the command watchdog only covers tool
+ * executions, so it never arms. Without this the session sits dead until a human
+ * notices.
  *
  * HOW: pi's extension events ARE the stream. Any of them — a token delta, a
  * thinking delta, a tool-call delta, the provider's response headers — resets the
@@ -17,16 +17,18 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
  * blind re-send would re-run them).
  *
  * ONE ABORT CHANNEL: the fire path goes through the command watchdog's existing
- * {@link noteWatchdogAbort} flag and its WATCHDOG_CANCEL_MARKER, so
- * steerUntilDone's already-fixed abort/steer race (b543d15) covers this watchdog
- * too instead of racing a second, parallel abort mechanism.
+ * {@link noteWatchdogAbort} flag and its WATCHDOG_CANCEL_MARKER, so the abort/steer
+ * race steerUntilDone already handles covers this watchdog too, instead of racing a
+ * second, parallel abort mechanism.
  *
  * SUSPENDED DURING TOOLS: while a tool executes the model stream is legitimately
- * idle — a 12-minute build emits nothing. That window belongs to the command
+ * idle — a long build emits nothing on it. That window belongs to the command
  * watchdog (requestTimeoutMs); this one pauses between tool_execution_start and
  * tool_execution_end so the two can never double-fire on the same silence.
  *
- * SCOPE: main session only. Children run `--no-extensions`, so their equivalent
- * guard lives in runChild (shared/child-process.ts) and shares the same machine.
+ * SCOPE: main session only. Children run `--no-extensions` (CHILD_BASE_ARGS), so
+ * none of these events reaches them; their equivalent guard is a second
+ * `StreamWatchdog` inside runChild (shared/child-process.ts), on the same
+ * machine.
  */
 export declare function registerStreamWatchdog(pi: ExtensionAPI): void;

package/dist/task/stream-watchdog.js

@@ -4,12 +4,12 @@ import { noteWatchdogAbort, WATCHDOG_CANCEL_MARKER } from './command-watchdog.js
 /**
  * MAIN-SESSION adapter for the model-stream watchdog.
  *
- * WHY (mx5 run 14): three implementation turns died mid-turn — the session jsonl's
- * last record is an ordinary assistant message, then silence forever, while the
- * model container stayed Up(healthy). No error is ever thrown for this shape, so
- * the connection-error retry (which needs a reported ModelError) cannot fire and
- * the command watchdog, which only covers tool executions, never arms. The run sat
- * dead for ~2.9h across the three until a human restarted it.
+ * WHY: a turn can die mid-stream — the last thing recorded is an ordinary
+ * assistant message, then silence forever, with the model endpoint still up.
+ * Nothing throws for that shape, so the connection-error retry (which needs a
+ * reported ModelError) cannot fire, and the command watchdog only covers tool
+ * executions, so it never arms. Without this the session sits dead until a human
+ * notices.
  *
  * HOW: pi's extension events ARE the stream. Any of them — a token delta, a
  * thinking delta, a tool-call delta, the provider's response headers — resets the
@@ -19,17 +19,19 @@ import { noteWatchdogAbort, WATCHDOG_CANCEL_MARKER } from './command-watchdog.js
  * blind re-send would re-run them).
  *
  * ONE ABORT CHANNEL: the fire path goes through the command watchdog's existing
- * {@link noteWatchdogAbort} flag and its WATCHDOG_CANCEL_MARKER, so
- * steerUntilDone's already-fixed abort/steer race (b543d15) covers this watchdog
- * too instead of racing a second, parallel abort mechanism.
+ * {@link noteWatchdogAbort} flag and its WATCHDOG_CANCEL_MARKER, so the abort/steer
+ * race steerUntilDone already handles covers this watchdog too, instead of racing a
+ * second, parallel abort mechanism.
  *
  * SUSPENDED DURING TOOLS: while a tool executes the model stream is legitimately
- * idle — a 12-minute build emits nothing. That window belongs to the command
+ * idle — a long build emits nothing on it. That window belongs to the command
  * watchdog (requestTimeoutMs); this one pauses between tool_execution_start and
  * tool_execution_end so the two can never double-fire on the same silence.
  *
- * SCOPE: main session only. Children run `--no-extensions`, so their equivalent
- * guard lives in runChild (shared/child-process.ts) and shares the same machine.
+ * SCOPE: main session only. Children run `--no-extensions` (CHILD_BASE_ARGS), so
+ * none of these events reaches them; their equivalent guard is a second
+ * `StreamWatchdog` inside runChild (shared/child-process.ts), on the same
+ * machine.
  */
 export function registerStreamWatchdog(pi) {
     // The ctx whose abort() ends the in-flight turn, refreshed on every event so

package/dist/task/substitution-probe.d.ts

@@ -2,19 +2,15 @@
  * substitution-probe — deterministic detection of SELF-VERIFIED work, feeding the
  * verify gate's prompt.
  *
- * The failure class (mx5 run 3, TASK_0016/0017): the implementation hit a real bug
- * in the shipped app ("Context is not finalized" from a mis-signatured middleware),
- * blamed the framework, and shipped "integration tests" that re-implement the API
- * inline — an own server intercepting protected routes, and a 943-line hand-rolled
- * duplicate in a test-support file that imports the real app and never calls it.
- * The suite runs 26/26 green while every protected route of the real server 500s.
- * The verify child judged "do the tests pass", saw green, and PASSed.
+ * The failure class: an implementation that hits a real bug in the shipped app
+ * can ship "integration tests" that re-implement the API inline instead — a test
+ * file that stands up its own server, or imports the real app and never calls it.
+ * The suite then runs green while every route of the real server fails, and a
+ * verify child that asks "do the tests pass" sees green and PASSes.
  *
- * A/B on the live local model (5 runs/arm, the real mx5 tree as fixture) proved the
- * fix must be a DETERMINISTIC, CONCRETE finding in the prompt, not prompt language
- * alone: the bare substitution rule caught 2/5 (right verdicts, 40% attention); the
- * rule PLUS a probe finding naming the suspect file caught 5/5, each verdict naming
- * the exact inline handlers and confirming the real app crashes.
+ * The prompt rule alone is weak against that, because the child has to notice the
+ * substitution unprompted. This probe hands it a concrete finding naming the
+ * suspect file, so the rule fires on a line rather than on self-discovery.
  *
  * WHAT THE PROBE ASSERTS is deliberately the class INVARIANT, not any framework
  * shape: when a task's own diff includes the very tests whose green result would
@@ -23,15 +19,16 @@
  * That is computable from pure git diff shape (which changed files live in test
  * paths, and how many lines the task added there): no language parsing, no server-
  * constructor lists, no import syntax — a Python, Go, or Rust project produces the
- * same finding the same way. (An earlier draft pattern-matched JS server
- * constructors; that only re-encoded the one incident. A behavioral canary — rerun
- * the suite with shipped sources removed, still-green ⇒ copy — was also rejected:
- * the real mx5 copy still imported the shipped db module, so poisoning sources
- * breaks the copy's tests too and the conviction never fires.)
+ * same finding the same way.
  *
- * Findings are advisory: they mandate the spot-check, they never auto-FAIL. Honest
- * self-authored tests survive the spot-check (control fixtures PASS with the
- * mandate present); only tests that bypass the artifact get named in a FAIL.
+ * A behavioural canary — re-run the suite with the shipped sources removed, and
+ * treat still-green as proof of a copy — does NOT work here: a substituted test
+ * usually still imports SOMETHING real (a db module, a type), so poisoning the
+ * sources breaks it too and the canary never convicts.
+ *
+ * Findings are advisory: they mandate the spot-check, they never auto-FAIL. An
+ * honest self-authored test survives that spot-check; only one that bypasses the
+ * artifact gets named in a FAIL.
  */
 /** One changed file as the git-shape collector reports it. */
 export interface ChangedFile {

package/dist/task/substitution-probe.js

@@ -2,19 +2,15 @@
  * substitution-probe — deterministic detection of SELF-VERIFIED work, feeding the
  * verify gate's prompt.
  *
- * The failure class (mx5 run 3, TASK_0016/0017): the implementation hit a real bug
- * in the shipped app ("Context is not finalized" from a mis-signatured middleware),
- * blamed the framework, and shipped "integration tests" that re-implement the API
- * inline — an own server intercepting protected routes, and a 943-line hand-rolled
- * duplicate in a test-support file that imports the real app and never calls it.
- * The suite runs 26/26 green while every protected route of the real server 500s.
- * The verify child judged "do the tests pass", saw green, and PASSed.
+ * The failure class: an implementation that hits a real bug in the shipped app
+ * can ship "integration tests" that re-implement the API inline instead — a test
+ * file that stands up its own server, or imports the real app and never calls it.
+ * The suite then runs green while every route of the real server fails, and a
+ * verify child that asks "do the tests pass" sees green and PASSes.
  *
- * A/B on the live local model (5 runs/arm, the real mx5 tree as fixture) proved the
- * fix must be a DETERMINISTIC, CONCRETE finding in the prompt, not prompt language
- * alone: the bare substitution rule caught 2/5 (right verdicts, 40% attention); the
- * rule PLUS a probe finding naming the suspect file caught 5/5, each verdict naming
- * the exact inline handlers and confirming the real app crashes.
+ * The prompt rule alone is weak against that, because the child has to notice the
+ * substitution unprompted. This probe hands it a concrete finding naming the
+ * suspect file, so the rule fires on a line rather than on self-discovery.
  *
  * WHAT THE PROBE ASSERTS is deliberately the class INVARIANT, not any framework
  * shape: when a task's own diff includes the very tests whose green result would
@@ -23,15 +19,16 @@
  * That is computable from pure git diff shape (which changed files live in test
  * paths, and how many lines the task added there): no language parsing, no server-
  * constructor lists, no import syntax — a Python, Go, or Rust project produces the
- * same finding the same way. (An earlier draft pattern-matched JS server
- * constructors; that only re-encoded the one incident. A behavioral canary — rerun
- * the suite with shipped sources removed, still-green ⇒ copy — was also rejected:
- * the real mx5 copy still imported the shipped db module, so poisoning sources
- * breaks the copy's tests too and the conviction never fires.)
+ * same finding the same way.
  *
- * Findings are advisory: they mandate the spot-check, they never auto-FAIL. Honest
- * self-authored tests survive the spot-check (control fixtures PASS with the
- * mandate present); only tests that bypass the artifact get named in a FAIL.
+ * A behavioural canary — re-run the suite with the shipped sources removed, and
+ * treat still-green as proof of a copy — does NOT work here: a substituted test
+ * usually still imports SOMETHING real (a db module, a type), so poisoning the
+ * sources breaks it too and the canary never convicts.
+ *
+ * Findings are advisory: they mandate the spot-check, they never auto-FAIL. An
+ * honest self-authored test survives that spot-check; only one that bypasses the
+ * artifact gets named in a FAIL.
  */
 /** Is this a file whose job is testing — by suffix or by living in a test dir? */
 export function isTestFile(p) {

package/dist/task/task-gates.d.ts

@@ -69,10 +69,8 @@ export interface GateDeps {
      * it has always been, so production wiring is untouched.
      *
      * Its own field because it answers a different question from the gate above.
-     * While the two shared one field the only way to answer them differently was to
-     * count invocations — a `verifyCalls` state machine whose FIRST return existed
-     * solely to unlock `mode === 'edit'`, re-invented in the suite and again in
-     * scripts/enforce-revert-attribution-replay-ab.ts.
+     * Sharing one field would leave a caller — or a test — no way to answer the two
+     * differently except by counting invocations.
      */
     reVerify?: (ctx: ExtensionCommandContext, cwd: string, taskTitle: string, taskId: string) => Promise<VerifyOutcome>;
     /**
@@ -96,10 +94,10 @@ export interface GateDeps {
     /**
      * BOUNDED fix for a repo-health verify FAIL: a small read,edit,bash child fixes
      * exactly the static findings (revert-guarded — see lint-fix.ts), instead of the
-     * full implementation re-run AUTOFIX reaches for. Validated live: 64s/106s to
-     * lint-clean where the impl re-run burned 36–56 min and did not converge. Runs
-     * at most once per gate sequence; not-applied falls through to the picker.
-     * Absent → the loop goes straight to recommend/picker as before.
+     * full implementation re-run AUTOFIX reaches for. Smallest tool first: a static
+     * finding does not need the whole turn re-run to fix it. Runs at most once per
+     * gate sequence; not-applied falls through to the picker. Absent → the loop goes
+     * straight to recommend/picker.
      */
     lintFix?: (ctx: ExtensionCommandContext, cwd: string, taskTitle: string, taskId: string, failReason: string) => Promise<{
         ok: boolean;
@@ -107,15 +105,15 @@ export interface GateDeps {
     }>;
     /**
      * Deterministic whole-repo static check (repo-health), used as the PRE-COMMIT
-     * gate on an edit-mode enforce pass: live data shows enforce edits broke the
-     * repo's own lint in 11 of 16 tasks, each costing a commit + model re-verify +
-     * revert cycle. Checking before committing skips that cycle. Absent → the old
-     * commit-then-differential path runs unchanged.
+     * gate on an edit-mode enforce pass: an enforce edit that breaks the project's
+     * own lint would otherwise cost a commit, a model re-verify and a revert before
+     * anything noticed. Checking first skips that cycle. Absent → the
+     * commit-then-differential path runs on its own.
+     *
+     * Takes the live ctx and a label so the implementation can render a status line
+     * while it runs: it is as slow as the project's own lint, and a gate step that
+     * long with no widget is indistinguishable from a hang.
      */
-    /** Deterministic whole-repo static check for the enforce pre-commit gate. Takes
-     *  the live ctx and a label so the implementation can render a status line while
-     *  it runs — it is as slow as the project's own lint (15–69s measured), and a
-     *  gate step that long with no widget is indistinguishable from a hang. */
     repoHealth?: (ctx: ExtensionCommandContext, cwd: string, label: string) => Promise<{
         ok: boolean;
         reason: string;
@@ -131,10 +129,10 @@ export interface GateDeps {
      * Append one line to the task's durable gate trail (`## gates` in the task
      * file). Every gate outcome — each verify verdict, the user's FAIL resolution,
      * the commit result, enforce mode + verdict, the differential guard's decision —
-     * is recorded so the sequence is auditable from artifacts alone (the mx5 audit
-     * could not tell WHY 10 of 18 tasks show no enforce run: verdicts lived only in
-     * terminal notifies). Best-effort: absent in tests → skipped; failures are
-     * swallowed by the implementation, never by this sequence.
+     * is recorded so the sequence is auditable from artifacts alone. A verdict that
+     * lives only in a terminal notify cannot answer "why did enforce not run here?"
+     * after the fact. Best-effort: absent in tests → skipped; failures are swallowed
+     * by the implementation, never by this sequence.
      */
     record?: (cwd: string, taskId: string, line: string) => Promise<void>;
     /**
@@ -172,8 +170,8 @@ export interface GateDeps {
      * verify site); `committed` = the files the task snapshot + the ENFORCE commit
      * changed (the post-commit enforce site); `enforce-commit` = the ENFORCE COMMIT
      * ALONE, which is the only correct authorship question at the enforce
-     * differential (mx5 run 18 / nexttask 4 — that differential decides whether to
-     * discard the enforce commit, so what the TASK touched is irrelevant to it).
+     * differential — that differential decides whether to discard the ENFORCE
+     * COMMIT, so what the TASK touched is irrelevant to it.
      * `null` means UNKNOWN (git unavailable) and stands the whole channel down —
      * inconclusive is never evidence, so an unreadable tree can only cost a repair
      * task, never spawn a wrong one or wrongly keep a regression.
@@ -200,8 +198,9 @@ export interface GateDeps {
     /**
      * Restore the given frozen paths to their committed (HEAD) state, discarding a
      * gate child's edits to them, and return the files actually reverted. Prompt
-     * framing is A/B-proven insufficient for this class, so the deny is mechanical:
-     * the write is undone, not merely warned about. Absent → the guard warns only.
+     * framing is insufficient for this class (see frozen-path-guard.ts), so the deny
+     * is mechanical: the write is undone, not merely warned about. Absent → the
+     * guard warns only.
      */
     revertFrozenPaths?: (cwd: string, paths: string[]) => Promise<string[]>;
 }
@@ -286,13 +285,12 @@ export interface YoloAcceptContext {
 /**
  * The reason an auto-ACCEPT is being written — NAMED, not assumed.
  *
- * The line this replaces asserted "autofix budget spent" on every branch. It was
- * measured false in 2709 of 2709 recorded accepts (scripts/yolo-accept-baserate.ts):
- * the budget has never once reached MAX_AUTO_AUTOFIX anywhere in the corpus — 30%
- * of accepts are UNOBSERVED (the research is never even consulted) and 70% are an
- * ACCEPT recommendation with the budget fully untouched. A durable trail that
- * misstates why a defect shipped is worse than no trail: mx5 run 19's TASK_0009
- * reads as an exhausted fixer when nothing was ever attempted.
+ * Four disjoint branches reach the terminal auto-ACCEPT, and only ONE of them has
+ * spent the autofix budget. An UNOBSERVED FAIL never consults the research; a
+ * frozen-blocked one is a contradiction no re-run can resolve; an ACCEPT
+ * recommendation can arrive with the budget untouched. A single "autofix budget
+ * spent" line would be false on three of the four, and a durable trail that
+ * misstates why a defect shipped reads as an exhausted fixer that never tried.
  */
 export declare function yoloAcceptReason(c: YoloAcceptContext): string;
 /**
@@ -306,8 +304,8 @@ export declare function askVerifyResolution(ctx: ExtensionCommandContext, title:
 /**
  * Run the verify + enforce gates against a task's just-finished implementation.
  *
- * Lifted verbatim from /task-auto's per-task loop so the two commands gate
- * identically. Returns a GateResult; `done` means the caller should proceed (the
+ * Both commands gate identically because both call this. Returns a GateResult;
+ * `done` means the caller should proceed (the
  * work is verified-or-accepted, checked off, committed, and enforced), every other
  * kind is a terminal stop the caller announces. Never throws for a gate outcome —
  * only a user cancel inside a gate child propagates (handled by the caller's
@@ -346,12 +344,10 @@ type VerifyGateStep = {
  * recommendation → unattended autofix → picker) until it verifies, is accepted,
  * or terminates.
  *
- * Split out of `runGatesForTask` at the single boolean that crosses to the
- * ENFORCE half. It carries 8 mutable locals over ~290 lines and has four terminal
- * exits; enforce carries one local and always falls through. Joining them meant a
- * test of the enforce differential had to traverse this whole loop first, which is
- * why `deps.verify` was driven by an invocation counter whose first return existed
- * only to unlock `mode === 'edit'`.
+ * Split from `runGatesForTask` at the single boolean that crosses to the ENFORCE
+ * half (`cleanPass`). This loop has four terminal exits and carries the whole
+ * negotiation; enforce always falls through. Joined, a test of the enforce
+ * differential would have to traverse this entire loop first.
  */
 export declare function resolveVerifyGate(ctxIn: ExtensionCommandContext, deps: GateDeps, p: GateParams, rec: Recorder, routeRootCause: RootCauseRouter): Promise<VerifyGateStep>;
 /**
@@ -359,8 +355,7 @@ export declare function resolveVerifyGate(ctxIn: ExtensionCommandContext, deps:
  * then decide whether the pass\'s own commit survives.
  *
  * `reVerify` is deliberately NOT `deps.verify`. They answer two different
- * questions — the gate above, and this differential — and while they shared one
- * field the only way to answer them differently was to count invocations.
+ * questions — the gate above, and this differential — so they are two fields.
  *
  * Reads `active` and never reassigns it: nothing here can replace the live
  * session, unlike the autofix in the verify half.