@mjasnikovs/pi-task 0.38.28 → 0.38.30

package/dist/task/verify-work.js

@@ -1,71 +1,40 @@
 /**
- * Work verification for /task-auto.
+ * Work verification: the model half of the post-implementation gate.
  *
- * The root failure this addresses: pi-task never *runs* any verification. Each
- * task's composed spec carries a VERIFY block (and ACCEPTANCE criteria), but that
- * block is only authored and presence-checked — never executed. The task is then
- * marked `completed` at handoff. So a task whose implementation does not actually
- * work (a SPA that won't build, a route wired to a dead stub, a CI file nobody
- * runs) is indistinguishable from one that does.
+ * A composed spec carries a VERIFY block and ACCEPTANCE criteria, but authoring
+ * that block and presence-checking it proves nothing. This pass RUNS it. It hands
+ * the just-committed spec (GOAL / CONSTRAINTS / ACCEPTANCE / VERIFY) to a fresh
+ * child with a `read` and a `bash` tool in the real workspace, and turns the
+ * child's verdict line into a PASS / FAIL / UNOBSERVED outcome.
  *
- * This pass closes that gap WITHOUT assuming any particular shape of project. It
- * does NOT hardcode `build`, an HTTP probe, a server boot, or a test command —
- * many tasks have none of those. Instead it hands the just-committed spec (GOAL /
- * ACCEPTANCE / VERIFY) to a fresh child of the SAME local model, gives it a `read`
- * and a `bash` tool in the real workspace, and lets the model do its job: run the
- * verification the spec already declares, observe the REAL output, and report a
- * PASS / FAIL verdict. If the spec's VERIFY is legitimately a no-op (config-only
- * change, re-read of a file), the model says so and that is a PASS.
+ * Nothing about a project's shape is hardcoded — no `build`, no HTTP probe, no
+ * server boot, no test command. The spec names the checks; the child runs them.
+ * When a spec's VERIFY is legitimately a no-op (a docs or config change), saying
+ * so is a PASS (rule 6).
  *
- * It must verify the REAL deliverable AS SHIPPED, not a run the verifier itself
- * prepared into passing. The failure class is broader than a bad VERIFY block: the
- * child has `bash`, so it can quietly make almost anything go green — export an env
- * var, source a config file, run a different command, rebuild in a scratch dir,
- * fabricate the artifact by hand — and then report PASS, masking a defect a fresh
- * checkout or CI run would hit. (This is exactly what sank an mx5 run: the verify
- * child `export`ed the test DB URL its own shell, watched the suite go green, and
- * passed a project whose documented command failed unaided.) The prompt therefore
- * anchors the child to ONE principle: run the project's own commands verbatim in the
- * tree as found, and treat any preparation/repair/substitution it had to perform to
- * reach green as ITSELF the defect — while still distinguishing a genuinely-absent
- * EXTERNAL service (an environment gap, not a code fault) from the project mis-wiring
- * how it connects. This generalises across languages and toolchains and assumes no
- * tests, build, or particular runtime.
+ * The prompt anchors the child to ONE principle: run the project's own commands
+ * verbatim in the tree as found, and treat any preparation, repair or
+ * substitution it had to perform to reach green as ITSELF the defect. A child
+ * holding `bash` can make almost anything go green — export an env var, source a
+ * config file, rebuild in a scratch dir, fabricate the artifact by hand — and
+ * then report PASS on a defect a fresh checkout would hit. Rule 5 keeps the one
+ * genuine exception, an EXTERNAL service absent from this machine, and makes the
+ * child PROBE for that service first: reachable means the real verification must
+ * run against it.
  *
- * A/B-proven on the live local model (Qwen3.6-35B), 5 runs/arm on a work-around-to-pass
- * fixture (documented command fails unaided; greppable env file makes it pass): the old
- * prompt false-passed 2/5; the new prompt caught it 5/5, each time naming the unwired
- * config. Guards (3 runs/arm): a healthy project still PASSes 3/3 (no false-fail), a
- * genuinely-broken shipped build FAILs 3/3, and a genuine external-service gap — which
- * the OLD prompt wrongly blamed on the code 3/3 — now correctly PASSes 3/3.
+ * It runs as a GATE right after the implementation turn, before the task is
+ * checked off or committed, for both /task and /task-auto — they build these
+ * children through the same gate-deps.ts. A FAIL does not end the run:
+ * task-gates.ts routes it through verify-resolution.ts into an unattended AUTOFIX
+ * re-run or the human picker.
  *
- * The sibling failure class is GREP-THEATER (mx5 run 2, TASK_0002): the composed VERIFY
- * block was grep-only, so the child "verified" a schema.sql containing INVALID SQL by
- * grepping for its own broken text — while a live PostgreSQL sat reachable in the same
- * container, never touched. The prompt now (a) says a grep-only VERIFY block does not cap
- * the obligation to execute/apply an executable artifact, and (b) requires PROBING a
- * declared external service before invoking the absent-service exception — reachable ⇒
- * the real verification must run against it. A/B on the faithful fixture (invalid
- * `generate always as` schema, grep-only VERIFY, unadvertised trust-auth PostgreSQL on
- * the default port, DATABASE_URL unset — exactly the mx5 shape): old prompt false-PASSed
- * 4/5; new prompt FAILed 5/5, each naming the real syntax error. Guards: explicit-URL
- * variant old 5/5 / new 5/5 correct-FAIL (no regression), valid schema 3/3 PASS (no
- * paranoia), unreachable-DB 2/3 PASS via the env-gap exception + 1 conservative FAIL
- * that still named the genuine SQL defect (safe direction — only false-PASS trashes work).
+ * Tools: `read` + `bash`, no `edit`/`write`. Observing is the CONTRACT, not the
+ * capability — `bash` writes — so gate-child.ts runs this kind `guarded` and
+ * `mutationCheck` below discards a verdict computed on a tree the child moved.
  *
- * It runs as a GATE right after the implementation turn, BEFORE the task is
- * checked off or committed. A FAIL stops the /task-auto run exactly like an
- * implementation failure: the task is left unchecked and uncommitted so
- * /task-auto-resume re-runs it, rather than blessing work that does not run.
- *
- * Tools: `read` + `bash` only. No `edit`/`write` — verification observes, it does
- * not fix (fixing committed work is the enforcement pass's job, and a verify pass
- * that also edits would blur "did it work" with "make it work"). `bash` is what
- * makes this real: it is the difference between reading the VERIFY block and
- * RUNNING it.
- *
- * Gated by the `verifyWork` config flag. With the flag off, or with no spec to
- * verify, this is a pass (ok: true).
+ * The `verifyWork` config flag gates the whole pass, in gate-deps.ts. Inside here
+ * a missing or empty spec is a pass (ok: true) — but `repoHealth` runs FIRST and
+ * can FAIL before the spec is looked at.
  */
 import { USER_CANCELLED } from './child-runner.js';
 import { buildEnvNotesBlock, ENV_NOTE_EMIT_INSTRUCTION, extractEnvNotes } from './env-notes.js';
@@ -82,9 +51,9 @@ import { crossTaskDeletionVerifyFindings } from './task-provenance.js';
  *  - `read` lets it inspect a file the VERIFY output points at (a build error's
  *    source line, a config it just validated) to characterise a failure precisely.
  *  - No `edit`/`write`: this pass reports a verdict, it does not change the tree.
- *    Keeping it read-only means a verify run can never itself introduce a change
- *    that needs re-verifying, and never scaffolds the junk-file runaway that the
- *    enforce pass had to drop `write` to stop.
+ *    That is a CONTRACT, not a capability — `bash` can write — so the git-state
+ *    guard backs it up and `mutationCheck` throws away a verdict reached on a
+ *    mutated tree. The enforce pass, whose job IS editing, runs `read,edit`.
  */
 const VERIFY_TOOLS = 'read,bash';
 /**
@@ -105,10 +74,10 @@ export const VERIFY_FAIL_PREFIX = {
  * The class of a FAIL — from the typed field when it is there, else from the
  * prefix the registry above owns.
  *
- * The prefix test survives in exactly ONE place instead of three. It has to
- * survive somewhere: `GateDeps.verify` is a seam, a debt read back off disk is a
- * bare string with no outcome attached, and the run-level gate mints its own
- * `static checks:` line through a different path entirely.
+ * The prefix test has to survive somewhere: `GateDeps.verify` is a seam, a debt
+ * read back off disk is a bare string with no outcome attached, and final-gate.ts
+ * mints its `static checks:` line through a different path entirely. This is the
+ * only place in src/ that tests a reason against a prefix.
  */
 export function verifyFailClass(o) {
     if (o.failClass)
@@ -130,10 +99,11 @@ export function isStaticClass(cls) {
 }
 /**
  * Slice the delivered spec (GOAL / CONSTRAINTS / ACCEPTANCE / VERIFY) out of a
- * task file body. The composed spec lives under a `## spec` header and runs until
- * the next top-level `## ` section (`## phase timings`). Returns null when no spec
- * section is present (e.g. a task that never reached compose), which the caller
- * treats as a pass — there is nothing to verify against.
+ * task file body. The compose and critique phases write the section named `spec`,
+ * so the composed spec lives under `## spec` and runs to the next line matching
+ * `## ` plus non-space (`## phase timings`); a `### ` subheading stays inside.
+ * Returns null when there is no spec section or it is blank (a task that never
+ * reached compose), which the caller treats as a pass — nothing to verify against.
  */
 export function extractSpecForVerification(taskBody) {
     const lines = taskBody.split('\n');
@@ -197,17 +167,14 @@ function probeAdapter(row) {
 }
 /** Identity transform for the rows whose probe already returns finding lines. */
 const asLines = (raw) => raw;
-/**
- * The table. ROW ORDER IS THE NOTICE-BLOCK ORDER IN THE PROMPT — do not reorder
- * without re-running the byte-identity check.
- */
+/** The table. ROW ORDER IS THE NOTICE-BLOCK ORDER IN THE PROMPT: `buildVerifyPrompt`
+ *  flatMaps this array to build the notices, so reordering rows reorders the prompt. */
 const PROBE_ADAPTERS = [
     /**
-     * Deterministic self-verification probe (see substitution-probe.ts): the
-     * TEST-THE-COPY class is caught 5/5 only when the prompt carries both the rule
-     * (3b) AND a concrete finding naming the suspect file — the rule alone got 2/5
-     * attention on the local model. The findings are pure git shape (test files the
-     * task itself changed), so the mandate is language- and framework-agnostic.
+     * Deterministic self-verification probe (see substitution-probe.ts): test
+     * files this task itself authored or changed, with their added-line counts.
+     * Pure git shape, so the mandate is language- and framework-agnostic. Rule 3b
+     * lives in the numbered narrative, so this row carries no `rule` text.
      */
     probeAdapter({
         key: 'substitution',
@@ -229,17 +196,11 @@ const PROBE_ADAPTERS = [
     }),
     /**
      * Deterministic prohibition probe (see prohibition-probe.ts): spec-forbidden
-     * paths the task's diff modified anyway. Same probe+rule design, same reason:
-     * the VIOLATION-EXCUSAL class (mx5 run 7: child saw "Do NOT modify server-side
-     * code" violated, waived it as "additive, tests pass", PASSed) needs both the
-     * no-waiver rule (4b) AND the concrete diff fact — the baseline child usually
-     * never runs `git diff` at all, so without the finding it cannot even SEE the
-     * violation. A/B on the live local model (violated-but-working fixture,
-     * everything green, forbidden file modified additively): old prompt 5/5
-     * false-PASS (several runs affirmatively claimed the forbidden file was
-     * untouched); rule+finding 5/5 FAIL naming the constraint. Guard: honest-clean
-     * fixture (prohibition in spec, probe silent) 5/5 PASS — no paranoia.
-     * Reverted-violation ≡ clean at the diff level (no entry → no finding).
+     * paths the task's diff modified anyway, paired with the no-waiver rule 4b.
+     * The finding matters because a child left to itself rarely runs `git diff`,
+     * so it cannot even SEE the violation. Findings are computed from the diff's
+     * changed-file list, so a fully REVERTED violation leaves no entry there and
+     * produces no finding.
      */
     probeAdapter({
         key: 'prohibition',
@@ -274,11 +235,11 @@ const PROBE_ADAPTERS = [
         ]
     }),
     /**
-     * Deterministic cross-task deletion probe (see task-provenance.ts, mx5 run 12
-     * PROMPT 2): tracked files the task's diff DELETES whose introducing task (git
-     * provenance) differs from the current task. The only row whose probe does NOT
-     * return finding lines — the structured value also rides on a FAIL outcome so
-     * an ACCEPT records each deletion as a durable debt.
+     * Deterministic cross-task deletion probe (see task-provenance.ts): tracked
+     * files the task's diff DELETES whose introducing task (git provenance)
+     * differs from the current task. The only row whose probe does NOT return
+     * finding lines — the structured value also rides on a FAIL outcome so an
+     * ACCEPT records each deletion as a durable debt.
      */
     probeAdapter({
         key: 'crossTaskDeletion',
@@ -314,9 +275,9 @@ const PROBE_ADAPTERS = [
         ]
     }),
     /**
-     * Deterministic probe-gaming probe (see probe-gaming.ts, run-8 F6): added lines
-     * whose stated purpose is to make a CHECK pass instead of meeting the
-     * requirement it stands for ("return 401 so the verification test passes").
+     * Deterministic probe-gaming probe (see probe-gaming.ts): added lines whose
+     * stated purpose is to make a CHECK pass instead of meeting the requirement it
+     * stands for ("return 401 so the verification test passes").
      */
     probeAdapter({
         key: 'probeGaming',
@@ -357,11 +318,10 @@ const PROBE_ADAPTERS = [
     /**
      * DETERMINISTIC skip-escape finding, computed purely from the spec's own VERIFY
      * block (see skip-escape.ts): a required check wrapped in a skip-announcing `||`
-     * fallback. Injected so rule 5c fires reliably — the model does not self-discover
-     * a graceful skip-escape (A/B: rule alone ~1-3/5), but acts on a finding naming
-     * the exact line, per the proven probe+rule pattern. Pure text analysis over
-     * `deps.spec`, so this row needs no dep and reports no stage: it is the one probe
-     * that is never absent and never costs a git call.
+     * fallback, injected so rule 5c has an exact line to name. Pure text analysis
+     * over `deps.spec`, so this row binds no dep and declares no stage — it is the
+     * one probe that is never absent and never costs a git call, and the one key
+     * excluded from `BoundProbeKey`.
      */
     probeAdapter({
         key: 'skipEscape',
@@ -384,10 +344,10 @@ const PROBE_ADAPTERS = [
         ]
     }),
     /**
-     * Deterministic sandbox-path-leak probe (see foreign-path.ts, mx5 run 13 PROMPT
-     * 4 item 1): absolute paths this task committed that exist only inside the
-     * authoring child's own environment — `/workspace/src/shared` in a vite alias —
-     * while the real file sits at `src/shared` here.
+     * Deterministic sandbox-path-leak probe (see foreign-path.ts): absolute paths
+     * this task committed that exist only inside the authoring child's own
+     * environment — `/workspace/src/shared` in a vite alias — while the real file
+     * sits at `src/shared` here.
      */
     probeAdapter({
         key: 'foreignPath',
@@ -425,11 +385,11 @@ const PROBE_ADAPTERS = [
         ]
     }),
     /**
-     * Deterministic neutered-check-script probe (see script-escape.ts, mx5 run 13
-     * PROMPT 4 item 4): check-class scripts in a manifest THIS task changed whose
-     * exit status cannot be non-zero (`… || true`, an inverted-grep launder). The
-     * damage is second-order — the script still "passes" — which is exactly why the
-     * child cannot discover it by running the check.
+     * Deterministic neutered-check-script probe (see script-escape.ts): check-class
+     * scripts in a manifest THIS task changed whose exit status cannot be non-zero
+     * (`… || true`, an inverted-grep launder). The damage is second-order — the
+     * script still "passes" — which is exactly why the child cannot discover it by
+     * running the check.
      */
     probeAdapter({
         key: 'scriptEscape',
@@ -464,10 +424,9 @@ const PROBE_ADAPTERS = [
         ]
     }),
     /**
-     * Deterministic test-runner glob-collision probe (see runner-globs.ts, mx5 runs
-     * 7 AND 13, PROMPT 4 item 2): the manifest declares two runners whose file sets
-     * are not provably disjoint, so the scanning one imports the other's specs and
-     * dies during COLLECTION.
+     * Deterministic test-runner glob-collision probe (see runner-globs.ts): the
+     * manifest declares two runners whose file sets are not provably disjoint, so
+     * the scanning one imports the other's specs and dies during COLLECTION.
      */
     probeAdapter({
         key: 'runnerGlob',
@@ -500,8 +459,9 @@ const PROBE_ADAPTERS = [
     /**
      * Deterministic test-assembly probe (see test-assembly.ts): authored test files
      * that rebuild production WIRING — importing the leaf modules the shipped entry
-     * composes and assembling their own copy instead of the real assembly — under
-     * rule 3f (F4 test-the-copy, 3rd recurrence). Pure import-graph shape.
+     * composes and assembling their own copy instead of the real assembly. Pure
+     * import-graph shape; rule 3f lives in the numbered narrative, so this row
+     * carries no `rule` text.
      */
     probeAdapter({
         key: 'testAssembly',
@@ -538,8 +498,8 @@ export const BOUND_PROBE_KEYS = PROBE_ADAPTERS.filter(a => a.bound).map(a => a.k
  * workspace, judge against ACCEPTANCE, and end on exactly one verdict line.
  *
  * `findings` is the probe bag: one key per PROBE_ADAPTERS row (see the table
- * above for what each channel means and the A/B evidence behind it). A key that
- * is absent or empty emits no block — the probes are independently optional.
+ * above for what each channel means). A key that is absent or empty emits no
+ * block — the probes are independently optional.
  */
 export function buildVerifyPrompt(spec, findings = {}, context = {}) {
     const { envNotes, contracts } = context;
@@ -747,9 +707,11 @@ export function buildVerifyPrompt(spec, findings = {}, context = {}) {
     ].join('\n');
 }
 /**
- * Parse the child's verdict. Scans for the LAST `WORK-VERIFIED: PASS|FAIL|UNOBSERVED`
- * marker (the model discusses before concluding, and bash output may echo the word
- * "VERIFY", so a distinct token and last-match win matter).
+ * Parse the child's verdict out of the LAST `WORK-VERIFIED: PASS|FAIL|UNOBSERVED`
+ * marker, case-insensitively. Last match wins: the model discusses before
+ * concluding, and a bash command it runs can print the token back, so an earlier
+ * occurrence is not the verdict. A marker with no trailing text gets a stock
+ * detail, so FAIL and UNOBSERVED are never bare.
  *
  * UNOBSERVED (rule 5c) is a distinct third outcome: a spec-required behavioral check
  * could not run because its observation tooling is absent, so the behavior is neither
@@ -780,18 +742,19 @@ export function parseVerifyVerdict(text) {
     return { pass: false, detail: last[2].trim() || 'unspecified failure' };
 }
 /**
- * Run the verification pass for one task. A missing spec is a pass. Otherwise run
- * the child against the real workspace and turn its verdict into an ok/blocked
- * outcome. Never throws (except a user cancel, which propagates so the loop's
- * USER_CANCELLED handler reports a clean "cancelled — resume").
+ * Run the verification pass for one task. `repoHealth` runs first and can FAIL on
+ * its own; after it, a missing or empty spec is a pass. Otherwise the child runs
+ * against the real workspace and its verdict becomes an ok/blocked outcome. Never
+ * throws except on a user cancel, which propagates so the loop's USER_CANCELLED
+ * handler reports a clean "cancelled — resume".
  */
 export async function runWorkVerification(deps) {
     // DETERMINISTIC gate FIRST: run the project's own whole-repo static analysis and
-    // let its exit code decide, before spending a model turn. This catches the class
-    // the model gate misses — a task whose composed VERIFY block never lints (proven
-    // 5/5 false-PASS live) — because it does not depend on that block. A fail is the
-    // ordinary verify-FAIL outcome, so it flows into the existing resolution picker.
-    // Absent dep, or a no-op result (no tooling to run), falls through to the model.
+    // let its exit code decide, before spending a model turn. It catches what the
+    // model gate structurally cannot — a task whose composed VERIFY block never
+    // lints — precisely because it does not read that block. A fail is the ordinary
+    // verify-FAIL outcome, so it flows into the existing resolution picker. Absent
+    // dep, or an ok result, falls through to the spec check and the model.
     const stage = (label) => {
         try {
             deps.onStage?.(label);
@@ -847,10 +810,10 @@ export async function runWorkVerification(deps) {
             contracts = '';
         }
     }
-    // A child that emits NO verdict never judged the work (budget/context death mid-
-    // investigation — seen live: an 11-minute verify wandered, died verdict-less, and
-    // the resulting FAIL burned a full implementation re-run on an unjudged artifact).
-    // That is a verify-side fault, so retry the VERIFY once before reporting a FAIL.
+    // A child that emits NO verdict never judged the work — it died mid-investigation
+    // on budget or context. That is a verify-side fault, and the resulting FAIL would
+    // otherwise spend a full implementation re-run on an artifact nobody judged, so
+    // the VERIFY is retried once before the FAIL is reported.
     for (let attempt = 1;; attempt++) {
         let text;
         try {

package/dist/task/widget.d.ts

@@ -52,22 +52,22 @@ export interface AutoLoaderState {
     startedAt: number;
     lastLine?: string;
     contextUsage?: ContextSnapshot;
-    /** Which /task-auto stage this loader is for. Defaults to 'planning' (the
-     *  numbered clarify/decompose steps); 'enforce' is the per-task guideline
-     *  pass and 'verify' is the per-task work-verification pass, neither of which
-     *  has step numbering. 'recommend' is the read-only research that picks the
-     *  recommended action after a verify FAIL. 'lint-fix' is the bounded fix pass
-     *  for a repo-health verify FAIL; 'final-fix' the bounded fix pass for a
-     *  final-integration-gate FAIL. */
+    /** Which stage this loader is for. Defaults to 'planning', the numbered
+     *  clarify/decompose steps — the ONLY kind that carries step numbering. The
+     *  other five mirror `GateChildKind` in gate-child.ts: 'enforce' is the
+     *  guideline pass, 'verify' the work-verification pass, 'recommend' the
+     *  research that picks the recommended action after a verify FAIL, 'lint-fix'
+     *  the bounded fix pass for a repo-health verify FAIL, and 'final-fix' the
+     *  bounded fix pass for a final-integration-gate FAIL. */
     kind?: 'planning' | 'enforce' | 'verify' | 'recommend' | 'lint-fix' | 'final-fix';
-    /** Command shown in the head line. Defaults to '/task-auto', which is what
-     *  every existing producer is; /task-plan reuses this same loader and only
-     *  needs its own name on it. */
+    /** Command shown in the head line. Defaults to '/task-auto'; plan-orchestrator
+     *  is the one producer that overrides it, with '/task-plan'. */
     command?: string;
 }
 export declare function buildAutoLoaderLines(s: AutoLoaderState, theme?: WidgetTheme): string[];
-/** Structured mirror of buildAutoLoaderLines. Only the numbered planning stage
- *  carries done/total; the enforce/verify/recommend/lint-fix passes are unnumbered. */
+/** Structured mirror of buildAutoLoaderLines. Only the planning kind (or an
+ *  absent one) carries done/total; the other five kinds are unnumbered, and the
+ *  browser draws its progress bar only when both are present. */
 export declare function buildAutoLoaderData(s: AutoLoaderState): WidgetData;
 /**
  * Start the planning loader widget (same cadence/look as the phase widget).
@@ -85,7 +85,8 @@ export interface ImplState {
     contextUsage?: ContextSnapshot;
 }
 export declare function buildImplLines(s: ImplState, theme?: WidgetTheme): string[];
-/** Structured mirror of buildImplLines (the host implementation turn — no step
- *  numbering, so no progress bar; just the phase badge and elapsed clock). */
+/** Structured mirror of buildImplLines. The host implementation turn has no step
+ *  numbering, so `done`/`total` stay unset and the browser draws no progress bar —
+ *  just the phase badge and the elapsed clock. */
 export declare function buildImplData(s: ImplState): WidgetData;
 export declare function flashTerminalWidget(ctx: ExtensionCommandContext, state: Exclude<TaskState, 'pending' | 'in_progress' | 'completed'>, taskId: string, reason: string | undefined): void;

package/dist/task/widget.js

@@ -60,8 +60,10 @@ export function formatContextDetail(usage, theme) {
         return formatContextTokens(tokens);
     return null;
 }
-/** The current-action string for the structured widget (the browser ellipsizes
- *  it to one line, so send it lightly capped rather than terminal-truncated). */
+/** The current-action string for the structured widget. The browser's
+ *  `.widget-action` is `white-space: nowrap` + `text-overflow: ellipsis`, so it
+ *  ellipsizes to one line itself — send it capped at 200 rather than truncated to
+ *  the terminal's narrower WIDGET_LAST_LINE_MAX. */
 function widgetAction(lastLine) {
     if (!lastLine)
         return undefined;
@@ -115,11 +117,12 @@ export function buildWidgetData(s) {
 export function startWidget(ctx, getState) {
     if (!ctx.hasUI)
         return () => { };
-    // `ctx.ui` THROWS once the ctx goes stale (/reload, session replacement), so
-    // the theme read belongs INSIDE the guard, not one line above it. render()
-    // runs from a timer, where an unguarded throw is an uncaughtException that
-    // kills the whole pi process — and a swallowed one would throw again on
-    // every tick, so a stale ctx latches and stops the timer. Issue #15.
+    // pi's `ctx.ui` getter calls `runner.assertActive()`, which THROWS once the
+    // ctx goes stale (/reload, session replacement) — so the theme read belongs
+    // INSIDE the guard, not one line above it. render() runs from a timer, and a
+    // throw out of a timer callback is an uncaughtException that terminates the
+    // process. Merely swallowing it would throw again every tick, so the stale
+    // flag latches and the timer is cleared.
     let stale = false;
     const render = () => {
         if (stale)
@@ -138,9 +141,9 @@ export function startWidget(ctx, getState) {
         setTaskWidget(plain, s ? buildWidgetData(s) : null);
     };
     // The timer is created BEFORE the first render so `timer` is always bound
-    // when render's catch reaches for it: a ctx already stale on the very first
-    // paint now stops the loop there, instead of arming an interval that wakes
-    // up and returns early forever.
+    // when render's catch reaches for it. Calling render() first instead would
+    // hit the `const timer` temporal dead zone — "Cannot access 'timer' before
+    // initialization" — on a ctx that is already stale at the first paint.
     const timer = setInterval(render, WIDGET_REFRESH_MS);
     timer.unref?.();
     render();
@@ -175,8 +178,9 @@ export function buildAutoLoaderLines(s, theme) {
         lines.push(trailer);
     return lines;
 }
-/** Structured mirror of buildAutoLoaderLines. Only the numbered planning stage
- *  carries done/total; the enforce/verify/recommend/lint-fix passes are unnumbered. */
+/** Structured mirror of buildAutoLoaderLines. Only the planning kind (or an
+ *  absent one) carries done/total; the other five kinds are unnumbered, and the
+ *  browser draws its progress bar only when both are present. */
 export function buildAutoLoaderData(s) {
     const phase = s.kind === 'enforce' ? 'enforcing guidelines'
         : s.kind === 'verify' ? 'verifying work'
@@ -226,9 +230,9 @@ export function startAutoLoader(ctx, getState) {
         setTaskWidget(plain, s ? buildAutoLoaderData(s) : null);
     };
     // The timer is created BEFORE the first render so `timer` is always bound
-    // when render's catch reaches for it: a ctx already stale on the very first
-    // paint now stops the loop there, instead of arming an interval that wakes
-    // up and returns early forever.
+    // when render's catch reaches for it. Calling render() first instead would
+    // hit the `const timer` temporal dead zone — "Cannot access 'timer' before
+    // initialization" — on a ctx that is already stale at the first paint.
     const timer = setInterval(render, WIDGET_REFRESH_MS);
     timer.unref?.();
     render();
@@ -258,8 +262,9 @@ export function buildImplLines(s, theme) {
         lines.push(trailer);
     return lines;
 }
-/** Structured mirror of buildImplLines (the host implementation turn — no step
- *  numbering, so no progress bar; just the phase badge and elapsed clock). */
+/** Structured mirror of buildImplLines. The host implementation turn has no step
+ *  numbering, so `done`/`total` stay unset and the browser draws no progress bar —
+ *  just the phase badge and the elapsed clock. */
 export function buildImplData(s) {
     const d = {
         title: `${s.taskId} · ${titleForDisplay(s)}`,

package/dist/task/wiring-claims.d.ts

@@ -1,38 +1,30 @@
 /**
- * Deterministic synthesized-wiring scanner for a composed spec (run-8 F3, gen side).
+ * Deterministic synthesized-wiring scanner for a composed spec, wired as the
+ * `synthesized-wiring` critique probe.
  *
- * F3 (the dominant run-8 shipped defect): refine/compose invent a "uniform" wiring
- * table — one module → one mount prefix, `/api/<x>` → `<x>Routes` for every module —
- * though the design pins ENDPOINTS, not mounts, and one module's pinned endpoints do
- * NOT all sit under a single prefix (photos: `POST /api/listings/:id/photos` AND
- * `GET/DELETE /api/photos/:id`). Mounting that module at `/api/photos` double-prefixes
- * the upload; consumers follow the pinned paths, assembly follows the invented table,
- * the seam ships broken. See [[contract-registry-f3]] (#4, the verify-side + registry
- * lever) — this is its GENERATION-side complement.
- *
- * A/B-measured on the live 27B (F3 critique trap): the CROSS-SLICE CONTRACTS registry
- * is NECESSARY but the prompt+registry alone is a WEAK catcher (A/B arms 0/8, +registry
- * only 1/8) — the model's attention goes to the obvious VERIFY weakness and it rarely
- * does the path-composition reasoning even with the facts in front of it. The reliable
- * lever is the SAME probe+rule pattern as [[skip-escape-scanner-f2]] / [[verify-
- * substitution-ab]]: a deterministic finding that NAMES the exact synthesized mappings
- * and juxtaposes the verbatim pinned facts, forcing focused reconciliation.
+ * The failure it catches: a spec states a "uniform" wiring table — one module to one
+ * mount prefix, `/api/<x>` → `<x>Routes` — while the design pins ENDPOINTS, not
+ * mounts. When a module's pinned endpoints do NOT all sit under a single prefix
+ * (`POST /api/listings/:id/photos` AND `GET /api/photos/:id`), mounting it at
+ * `/api/photos` double-prefixes the upload. Consumers follow the pinned paths,
+ * assembly follows the invented table, and the seam ships broken.
  *
  * This scanner does NOT decide which mapping is wrong — that needs routing-composition
- * knowledge (a forbidden stack assumption). It surfaces every mapping that (a) is not a
- * verbatim substring of the design/registry (so it is INFERRED, not cited) AND (b) touches
- * a pinned cross-slice boundary (an operand appears in the registry) — i.e. it reshapes a
- * shared contract. The 4 coincidentally-correct mappings are surfaced too, but framed as
- * "reconcile each; keep the conforming ones" — the LLM decides, informed. Pure text/
- * substring analysis; no stack, framework, or routing assumptions. Empty registry (single
- * `/task`, or no shared boundary) ⇒ no-op.
+ * knowledge, which would be a stack assumption. It surfaces every mapping that (a) is
+ * not a verbatim substring of the design or registry, so it is INFERRED rather than
+ * cited, AND (b) touches a pinned cross-slice boundary, meaning an operand appears in
+ * the registry. Conforming mappings are surfaced too, framed as "reconcile each; keep
+ * the conforming ones" — the model decides, informed. Pure text and substring analysis;
+ * no stack, framework, or routing assumptions. An empty registry (a single `/task`, or
+ * a design pinning no shared boundary) is a no-op.
  */
 export interface WiringClaim {
-    /** The offending mapping line, verbatim (trimmed). */
+    /** The offending mapping line, trimmed and minus any leading list bullet.
+     *  Backticks are KEPT here — only `from`/`to` have them stripped. */
     line: string;
-    /** Left operand (the mapped-from token, e.g. a mount prefix). */
+    /** Left operand (the mapped-from token, e.g. a mount prefix), backticks stripped. */
     from: string;
-    /** Right operand (the mapped-to token, e.g. a module name). */
+    /** Right operand (the mapped-to token, e.g. a module name), backticks stripped. */
     to: string;
 }
 /**
@@ -50,15 +42,16 @@ export declare function findSynthesizedWiring(spec: string, grounding: string, r
  */
 export declare function wiringProbeText(findings: WiringClaim[], registry: string): string;
 /**
- * Render findings as a critique-rewrite defect block (fed into the FOCUS list): the
- * rewrite must reconcile each mapping against the pinned facts and correct only the
- * one(s) that break. Mirrors skipEscapeDefectText's shape.
+ * The same text under the name the critique-rewrite defect path uses. One rendering
+ * serves both readers, so the probe the model sees and the defect the rewrite is
+ * handed can never drift apart.
  */
 export declare function wiringDefectText(findings: WiringClaim[], registry: string): string;
 /**
  * Concatenate the design/spec docs the given texts @-reference (best-effort, readable
  * files only) as extra grounding for findSynthesizedWiring — so a mapping the design
- * states verbatim is treated as CITED, not synthesized. Unreadable/absent mentions are
- * skipped; returns '' when nothing resolves.
+ * states verbatim is treated as CITED, not synthesized. Each path is read once across
+ * all texts; unreadable or absent mentions are skipped; returns '' when nothing
+ * resolves.
  */
 export declare function readReferencedDocs(cwd: string, ...texts: string[]): string;