@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/unknown-routing.d.ts

@@ -4,10 +4,10 @@
  * The grill phase generates one clarifying question per KNOWN-UNKNOWN and lets a
  * `grill-auto` child either auto-answer it (ANSWER → the user never sees it) or
  * surface it (UNKNOWN → asked). The dangerous class is an integration / build-
- * wiring unknown — "how is this plugin wired into the build", "should the import
- * structure in the HTML entry change" — which `grill-auto` happily auto-answers
- * with a GUESS that then ships as a silent landmine (a real run shipped an
- * unstyled build this way).
+ * wiring unknown — "how is this plugin wired into the build", "where does the
+ * loader hook in" — which `grill-auto` will happily auto-answer with a GUESS. A
+ * wrong guess there is structural: the build still runs, and ships something the
+ * wiring never actually connected.
  *
  * This classifier identifies that class so the orchestrator can route it: try to
  * resolve it from fetched docs first, and if nothing grounded the answer, surface
@@ -24,5 +24,11 @@
  * surfaced to the user rather than auto-answered. Requires BOTH a tooling-surface
  * mention and wiring intent, so benign questions ("which log format?", "what
  * default page size?", "which file holds the auth handler?") do not trip it.
+ *
+ * Both factors are lexical, so the boundary is not exact in either direction. A
+ * bare `how is/are` counts as wiring intent, so "how is the plugin named?" trips
+ * it; and a wiring question phrased without one of the intent words — "should the
+ * import structure in the HTML entry change" — does not. Erring toward surfacing
+ * is the safe direction: the cost is one question the user waves through.
  */
 export declare function isIntegrationUnknown(question: string): boolean;

package/dist/task/unknown-routing.js

@@ -4,10 +4,10 @@
  * The grill phase generates one clarifying question per KNOWN-UNKNOWN and lets a
  * `grill-auto` child either auto-answer it (ANSWER → the user never sees it) or
  * surface it (UNKNOWN → asked). The dangerous class is an integration / build-
- * wiring unknown — "how is this plugin wired into the build", "should the import
- * structure in the HTML entry change" — which `grill-auto` happily auto-answers
- * with a GUESS that then ships as a silent landmine (a real run shipped an
- * unstyled build this way).
+ * wiring unknown — "how is this plugin wired into the build", "where does the
+ * loader hook in" — which `grill-auto` will happily auto-answer with a GUESS. A
+ * wrong guess there is structural: the build still runs, and ships something the
+ * wiring never actually connected.
  *
  * This classifier identifies that class so the orchestrator can route it: try to
  * resolve it from fetched docs first, and if nothing grounded the answer, surface
@@ -30,6 +30,12 @@ const WIRING_INTENT_RE = /\b(?:wir(?:e|ed|ing)|integrat(?:e|ed|es|ing|ion)|hook(
  * surfaced to the user rather than auto-answered. Requires BOTH a tooling-surface
  * mention and wiring intent, so benign questions ("which log format?", "what
  * default page size?", "which file holds the auth handler?") do not trip it.
+ *
+ * Both factors are lexical, so the boundary is not exact in either direction. A
+ * bare `how is/are` counts as wiring intent, so "how is the plugin named?" trips
+ * it; and a wiring question phrased without one of the intent words — "should the
+ * import structure in the HTML entry change" — does not. Erring toward surfacing
+ * is the safe direction: the cost is one question the user waves through.
  */
 export function isIntegrationUnknown(question) {
     if (!question)

package/dist/task/user-directives.d.ts

@@ -3,14 +3,11 @@
  * directives a user writes into a raw task prompt, so a downstream rewrite (refine)
  * cannot silently drop them.
  *
- * The failure this closes (mx5 run 9, validated): the raw prompt was
- *   "Research Playwright best practices VIA WEB SEARCH — focus on E2E testing…"
- * Refine rewrote the task well in every other respect (it correctly killed a wrong
- * "Next.js" framing) but the "via web search" instruction vanished from the refined
- * spec entirely — and the whole 2-run session then made ZERO pi-worker-search and
- * ZERO pi-worker-fetch calls. A user who explicitly asks for web search must get
- * web search; the model's paraphrase is not allowed to quietly demote it to
- * "research from local files".
+ * The failure this closes: a raw prompt saying "research X VIA WEB SEARCH" can be
+ * rewritten well in every other respect while the "via web search" instruction
+ * vanishes from the refined spec. Nothing downstream then asks for web search, so
+ * none happens. A user who explicitly names a tool must get that tool; a
+ * paraphrase is not allowed to quietly demote it to "research from local files".
  *
  * The mechanism is the lever, the prompt is the belt: refine is HANDED the
  * directives as a MUST-PRESERVE block (prompt), and — because a weak model still

package/dist/task/user-directives.js

@@ -3,14 +3,11 @@
  * directives a user writes into a raw task prompt, so a downstream rewrite (refine)
  * cannot silently drop them.
  *
- * The failure this closes (mx5 run 9, validated): the raw prompt was
- *   "Research Playwright best practices VIA WEB SEARCH — focus on E2E testing…"
- * Refine rewrote the task well in every other respect (it correctly killed a wrong
- * "Next.js" framing) but the "via web search" instruction vanished from the refined
- * spec entirely — and the whole 2-run session then made ZERO pi-worker-search and
- * ZERO pi-worker-fetch calls. A user who explicitly asks for web search must get
- * web search; the model's paraphrase is not allowed to quietly demote it to
- * "research from local files".
+ * The failure this closes: a raw prompt saying "research X VIA WEB SEARCH" can be
+ * rewritten well in every other respect while the "via web search" instruction
+ * vanishes from the refined spec. Nothing downstream then asks for web search, so
+ * none happens. A user who explicitly names a tool must get that tool; a
+ * paraphrase is not allowed to quietly demote it to "research from local files".
  *
  * The mechanism is the lever, the prompt is the belt: refine is HANDED the
  * directives as a MUST-PRESERVE block (prompt), and — because a weak model still

package/dist/task/verify-quality.d.ts

@@ -5,45 +5,41 @@ export interface GrepOnlyVerifyFinding {
     lines: string[];
 }
 /**
- * Scan a composed spec's VERIFY block: all-static block that grep/cat-asserts
- * runnable source ⇒ one finding per inspected file. Empty when the block
- * contains any execution command, has no VERIFY block, or inspects no runnable
- * source (doc/config-only tasks).
+ * Scan a composed spec's VERIFY block: one finding per runnable source file the
+ * block inspects, each carrying the verbatim lines that inspect it. Empty when
+ * the block contains any execution command, when the spec has no fenced VERIFY
+ * block, or when nothing runnable is inspected (doc/config-only tasks).
  */
 export declare function findGrepOnlyVerify(spec: string): GrepOnlyVerifyFinding[];
 /** One VERIFY command, classified by what it can observe. */
 export interface VerifyCommandClass {
     /** The command line, verbatim. */
     raw: string;
-    /** Every pipeline segment is a STATIC head (grep/test/tsc/…) — it inspects
-     *  files and can never observe the deliverable's behaviour. */
+    /** Every pipeline segment's head is in STATIC_HEADS (grep/test/tsc/…) — it
+     *  inspects files and can never observe the deliverable's behaviour. */
     staticOnly: boolean;
     /**
-     * The command observes RUNTIME behaviour: an HTTP request, a port probe, a
-     * process it starts and watches. This is the distinction nexttask 7's M3
-     * turns on — mx5 run 18's TASK_0023 VERIFY is all `node -e "…package.json…"`,
-     * which EXECUTES node yet can only assert that a string is present in a
-     * config file, and the behavioural half of the owned requirement ("serves
-     * `/api` + static `dist/`") is exactly what it cannot see.
+     * The command names an HTTP request (`curl`, `wget`, an http(s) URL,
+     * `fetch(`), a port probe (`nc -z`, `ss -`, `lsof`, `localhost`,
+     * `127.0.0.1`) or `playwright`. Executing something is not enough:
+     * `bun run start` and `node -e "…package.json…"` are both false here — they
+     * run, yet observe only a file's contents.
      */
     observesBehaviour: boolean;
 }
 /**
  * Classify each command of a spec's VERIFY block. Shares `segmentHead` with the
  * grep-theater detector, so "static" means one thing across the two measures.
- * Empty when the spec has no runnable VERIFY block.
+ * Empty when the spec has no fenced VERIFY block.
  */
 export declare function classifyVerifyCommands(spec: string): VerifyCommandClass[];
 /**
- * Retry hint when the critique rewrite KEPT the grep-theater block it was told
- * to fix (live A/B: 1/5 rewrites ignored the injected defect). Prepended to the
- * second rewrite attempt; the defect block naming the exact files is still in
- * the prompt body.
+ * Prepended to the SECOND `runWithEmphasisRetry` attempt when the first critique
+ * rewrite still leaves `findGrepOnlyVerify` non-empty. The generic emphasis line
+ * would claim the previous attempt had no VERIFY block, which is wrong here — it
+ * had one. The defect block naming the exact files stays in the prompt body
+ * underneath the hint.
  */
 export declare const GREP_THEATER_RETRY_HINT: string;
-/**
- * Render the findings as a defect block for the critique rewrite: VERIFY must
- * EXECUTE the runnable deliverable and assert an observable outcome of THAT
- * run, not grep its source.
- */
+/** Render the findings as the defect block handed to the critique rewrite. */
 export declare function grepOnlyVerifyDefectText(findings: GrepOnlyVerifyFinding[]): string;

package/dist/task/verify-quality.js

@@ -1,24 +1,17 @@
 /**
- * Grep-theater VERIFY detector (mx5 run-13 Bug B), compose-critique side.
+ * Grep-theater VERIFY detector, wired as the `grep-theater` compose-critique
+ * probe in `critique-probes.ts`.
  *
- * TASK_0018's VERIFY block "verified" a build script with tsc + three greps on
- * build.ts's SOURCE — it never ran `bun build.ts`. The greps asserted the
- * hallucinated `Bun.mkdirSync` line was present, so a broken build shipped
- * green and stayed broken for 14 tasks. Grep-on-source is not verification of
- * a runnable deliverable; only executing the artifact is.
- *
- * Deterministic shape (findSkipEscapes → critique-rewrite pattern): a finding
- * fires when the VERIFY block (a) grep/cat-asserts the SOURCE of a runnable
- * file (.ts/.js/.sh — a build script, server, CLI entry) and (b) contains NO
- * execution command at all — every command is static inspection (grep, test,
- * ls, cat, tsc --noEmit, eslint, prettier). Any real execution anywhere in the
- * block (bun/node/npm run/test, curl, ./script) means the deliverable-runs
- * question is at worst partially covered, and we step aside — the guard may
- * only cost time, never work, so recall is floored at the unambiguous
- * all-static case rather than chasing which command exercises which file.
+ * A finding fires when the spec's VERIFY block (a) inspects the source of a
+ * TypeScript/JavaScript/shell file with grep/rg/cat/head/tail/wc and (b)
+ * contains no execution command at all — every pipeline segment's head is in
+ * STATIC_HEADS. One unknown head anywhere in the block (bun, node, npm, yarn,
+ * pnpm, curl, `./script`, python3) counts as execution and the whole block is
+ * skipped. Recall is therefore floored at the unambiguous all-static case
+ * instead of deciding which command exercises which file.
  */
 import { parseVerifyBlock } from './spec-validation.js';
-/** Commands that only inspect — they never execute the shipped artifact. */
+/** Commands that only inspect — a segment headed by one never runs the deliverable. */
 const STATIC_HEADS = new Set([
     'grep',
     'rg',
@@ -57,25 +50,33 @@ const STATIC_HEADS = new Set([
     'prettier',
     'biome'
 ]);
-/** A bare (unquoted) path token ending in a runnable-source extension. */
+/**
+ * A bare path token ending in a runnable-source extension: ts, tsx, js, jsx,
+ * mjs, cjs, mts, cts, sh. The character class holds no quote, so a quoted
+ * `'build.ts'` never matches.
+ */
 const RUNNABLE_SRC_RE = /^[\w@./-]+\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts|sh)$/;
-/** Heads whose file arguments count as "inspecting the source of". */
+/**
+ * Heads whose file arguments count as "inspecting the source of". The other
+ * STATIC_HEADS (sed, awk, jq, ls, diff, file …) keep a block static but name
+ * no target of their own.
+ */
 const INSPECT_HEADS = new Set(['grep', 'rg', 'cat', 'head', 'tail', 'wc']);
 /**
- * Shell-control noise that precedes (or IS) a segment without being a command:
- * `if grep -q x f; then` splits into an `if`-prefixed segment plus bare `then`;
- * `… || { echo FAIL; exit 1; }` yields `{ echo …` and `}` segments. Treating
- * these as unknown heads would count them as execution and silently blind the
- * detector on exactly the incident shape (run-13's VERIFY used all of them).
+ * Shell-control noise that precedes (or IS) a segment without being a command.
+ * `if grep -q x f; then` splits into `if grep -q x f` plus a bare ` then`;
+ * `… || { echo FAIL; exit 1; }` yields ` { echo FAIL`, ` exit 1` and ` }`.
+ * An unknown head counts as execution and skips the whole block, so treating
+ * these tokens as heads would blind the detector on any guarded grep.
  */
 const CONTROL_PREFIX = new Set(['if', 'elif', 'while', 'until', 'then', 'else', 'do', '!']);
 const CONTROL_ONLY = new Set(['}', ')', 'fi', 'done', 'esac']);
 /**
- * The effective head of one pipeline segment: shell-control prefixes, leading
- * `(`/`{`, VAR=val prefixes and `timeout N` are skipped; `bunx`/`npx` resolve
- * to the tool they invoke (so `bunx tsc --noEmit` is static).
- * `bun`/`npm`/`yarn`/`pnpm`/`node` stay as themselves — whatever they run (a
- * script, a test suite, a file) is execution.
+ * The effective head of one pipeline segment: leading `(`/`{`/`!`,
+ * shell-control prefixes, VAR=val assignments and `timeout N` are skipped;
+ * `bunx`/`npx` resolve to the tool they invoke, so `bunx tsc --noEmit` stays
+ * static. `bun`/`npm`/`yarn`/`pnpm`/`node` stay as themselves and are absent
+ * from STATIC_HEADS, so whatever they run is execution.
  */
 function segmentHead(segment) {
     const tokens = segment.split(/\s+/).filter(t => t.length > 0);
@@ -112,10 +113,10 @@ function segmentHead(segment) {
     return { head, args: tokens.slice(i + 1) };
 }
 /**
- * Scan a composed spec's VERIFY block: all-static block that grep/cat-asserts
- * runnable source ⇒ one finding per inspected file. Empty when the block
- * contains any execution command, has no VERIFY block, or inspects no runnable
- * source (doc/config-only tasks).
+ * Scan a composed spec's VERIFY block: one finding per runnable source file the
+ * block inspects, each carrying the verbatim lines that inspect it. Empty when
+ * the block contains any execution command, when the spec has no fenced VERIFY
+ * block, or when nothing runnable is inspected (doc/config-only tasks).
  */
 export function findGrepOnlyVerify(spec) {
     const cmds = parseVerifyBlock(spec);
@@ -123,9 +124,10 @@ export function findGrepOnlyVerify(spec) {
         return [];
     const inspected = new Map();
     for (const { raw } of cmds) {
-        // Split into pipeline segments; quotes are rare in VERIFY one-liners and
-        // a mis-split only risks a MISSED finding (a quoted `&&` making a fake
-        // segment whose head is unknown ⇒ counted as execution ⇒ step aside).
+        // Split into pipeline segments. A mis-split — a quoted `&&` making a
+        // fake segment — leaves a segment whose head is unknown, which counts
+        // as execution and skips the block. The error direction is a MISSED
+        // finding, never a false one.
         for (const segment of raw.split(/&&|\|\||;|\|/)) {
             const s = segmentHead(segment);
             if (s === null)
@@ -152,7 +154,7 @@ const BEHAVIOUR_RE = /\bcurl\b|\bwget\b|\bhttpie?\b|https?:\/\/|\bnc\s+-z\b|\bss
 /**
  * Classify each command of a spec's VERIFY block. Shares `segmentHead` with the
  * grep-theater detector, so "static" means one thing across the two measures.
- * Empty when the spec has no runnable VERIFY block.
+ * Empty when the spec has no fenced VERIFY block.
  */
 export function classifyVerifyCommands(spec) {
     const cmds = parseVerifyBlock(spec);
@@ -171,10 +173,11 @@ export function classifyVerifyCommands(spec) {
     });
 }
 /**
- * Retry hint when the critique rewrite KEPT the grep-theater block it was told
- * to fix (live A/B: 1/5 rewrites ignored the injected defect). Prepended to the
- * second rewrite attempt; the defect block naming the exact files is still in
- * the prompt body.
+ * Prepended to the SECOND `runWithEmphasisRetry` attempt when the first critique
+ * rewrite still leaves `findGrepOnlyVerify` non-empty. The generic emphasis line
+ * would claim the previous attempt had no VERIFY block, which is wrong here — it
+ * had one. The defect block naming the exact files stays in the prompt body
+ * underneath the hint.
  */
 export const GREP_THEATER_RETRY_HINT = '[SYSTEM NOTE: Your previous rewrite still shipped a VERIFY block whose only signal '
     + 'on the runnable deliverable is grep-on-source — every command is static inspection '
@@ -183,11 +186,7 @@ export const GREP_THEATER_RETRY_HINT = '[SYSTEM NOTE: Your previous rewrite stil
     + 'deliverable (e.g. `bun <script>.ts`, `bun run <script>`, start it and curl it) and '
     + 'assert an observable outcome of that run (exit code, a file the run produces, a '
     + 'served response). Keep greps only as additions to the run, never as the only signal.]';
-/**
- * Render the findings as a defect block for the critique rewrite: VERIFY must
- * EXECUTE the runnable deliverable and assert an observable outcome of THAT
- * run, not grep its source.
- */
+/** Render the findings as the defect block handed to the critique rewrite. */
 export function grepOnlyVerifyDefectText(findings) {
     return [
         'GREP-THEATER VERIFY — every command in the VERIFY block is static inspection',

package/dist/task/verify-reconcile.d.ts

@@ -1,14 +1,17 @@
 export interface AbsenceAssertion {
-    /** The verify line carrying the assertion (trimmed). */
+    /** The trimmed fragment the assertion was read out of: the whole VERIFY
+     *  line, or only the condition when it came from an `if` header. */
     line: string;
     /** The path or grep pattern asserted absent (quotes stripped). */
     target: string;
     kind: 'path' | 'pattern';
 }
 /**
- * All absence assertions in the spec's VERIFY block. Scans the fenced commands:
- * `if` blocks whose body reaches `exit <nonzero>` contribute their condition's
- * POSITIVE probes; other lines contribute their NEGATED probes.
+ * All absence assertions in the spec's VERIFY block. An `if` line contributes
+ * its condition's POSITIVE probes only when a LATER line reaches
+ * `exit <nonzero>`: the body scan starts at the next command, so a one-line
+ * `if …; then exit 1; fi` yields nothing. Every other line contributes its
+ * NEGATED probes. Empty when the spec has no fenced VERIFY block.
  */
 export declare function findAbsenceAssertions(spec: string): AbsenceAssertion[];
 export interface AbsenceConflict {
@@ -25,12 +28,14 @@ export interface AbsenceConflictContext {
     /** The cross-slice contract registry text ('' when absent). */
     contracts: string;
 }
-/** Absence assertions that collide with the plan: the deterministic D lever. */
+/** Every absence assertion that collides with the plan. disk, sibling and
+ *  contract are tested independently, so one assertion can yield three. */
 export declare function findAbsenceConflicts(spec: string, ctx: AbsenceConflictContext): AbsenceConflict[];
-/** The forced critique-rewrite defect text (skip-escape pattern: MANDATORY,
- *  self-contained, names the reconciliation). */
+/** The defect block handed to the critique rewrite. Self-contained: it names
+ *  each conflict, why it is one, and the reconciliation to apply. */
 export declare function absenceProbeText(conflicts: AbsenceConflict[]): string;
-/** Parse SIBLING titles out of the scope-fence text (buildScopeFence's listing),
- *  excluding the "(THIS STEP)" line — a task may legitimately assert about its
- *  own deliverables. '' / undefined (bare /task, no plan) yields none. */
+/** Parse SIBLING titles out of `buildScopeFence`'s listing, whose rows read
+ *  `[N] head` and `[N] (THIS STEP) head`. The "(THIS STEP)" row is dropped — a
+ *  task may legitimately assert about its own deliverables. '' and undefined
+ *  (a bare /task with no plan) yield none. */
 export declare function siblingTitlesFromPlanContext(planContext: string | undefined): string[];

package/dist/task/verify-reconcile.js

@@ -1,47 +1,43 @@
 /**
  * verify-reconcile — deterministic reconciliation of a spec's VERIFY assertions
- * against the PLAN (mx5 run 11, goal D).
+ * against the plan. Wired as the `plan-contradiction` critique probe.
  *
- * The failure this closes: TASK_0009's composed spec carried
- *   `if [ -f src/client/pages/admin.tsx ] || grep -rn 'Admin' src/client/pages/ …; then … exit 1`
- * — a NEGATIVE EXISTENCE assertion on a SIBLING task's pinned deliverable
- * (TASK_0008 shipped the admin page; the design pins the admin routes). The
- * scope fence ("do NOT build other steps' work") leaked into the verify script
- * as "other steps' work must be ABSENT". Verify then correctly FAILed at run
- * end, the user accepted it as debt, and the final-gate autofix treated the
- * debt as an instruction and `rm`'d the sibling's deliverable.
+ * A sibling step's deliverable is a fact about the tree this task runs in, never
+ * a valid absence target. A VERIFY line asserting it is missing is a guaranteed
+ * run-end FAIL, and an automated fixer handed that FAIL can "resolve" it by
+ * deleting the sibling's work. The defect has to die at spec time instead.
  *
- * A sibling's deliverable is a CLAIM about the tree this task runs in — never a
- * valid absence target. The defect must die at SPEC time (a forced critique
- * rewrite, the skip-escape pattern), not surface as a run-end verify-FAIL.
+ * Two shapes read as "this must be absent":
+ *   - an `if` whose condition holds a POSITIVE existence probe (`[ -f P ]`,
+ *     `test -e P`, `grep PAT …`) and whose body reaches `exit <nonzero>`;
+ *   - a NEGATED probe anywhere else (`[ ! -f P ]`, `test ! -f P`,
+ *     `! grep PAT …`), `|| exit`-guarded or standing alone.
+ * `grep -v` / `--invert-match` is a filter, not a probe, and is skipped; so is
+ * a target starting with `-` or `$`.
  *
- * Detection is deterministic and shape-aware for how these specs actually write
- * absence checks (measured on the real run-11 artifacts):
- *   - `if <cond>; then … exit 1; fi` where <cond> contains a POSITIVE existence
- *     probe (`[ -f P ]`, `test -e P`, `grep PAT …`): P/PAT must be absent or the
- *     verify fails.
- *   - a standalone / `|| exit`-guarded NEGATED probe (`[ ! -f P ]`,
- *     `test ! -f P`, `! grep PAT …`): same meaning outside an if-header.
- * `grep -v` occurrences are filters, not probes, and are skipped.
- *
- * A detected absence target is a CONFLICT when the plan pins it elsewhere:
- *   - 'disk'     — the path already exists in the worktree at spec time (a
- *                  sibling shipped it; asserting its absence is a guaranteed
- *                  future FAIL);
+ * A detected target is a CONFLICT when the plan pins it elsewhere:
+ *   - 'disk'     — the path exists in the worktree at spec time;
  *   - 'sibling'  — a SIBLING task's title names it;
  *   - 'contract' — the cross-slice contract registry quotes it.
- * Matching: pattern targets by case-insensitive substring (all-words matching
- * false-fires on `bun:sql` vs a "Bun SQL connection" title); path targets by
- * full-path substring or a word-bounded basename. No similarity thresholds.
+ * The three are checked independently, so one assertion can raise all three.
+ *
+ * Matching: pattern targets by case-insensitive substring; path targets by
+ * full-path substring or a word-bounded basename. No similarity thresholds and
+ * no all-words matching — all-words matches `bun:sql` against a "Bun SQL
+ * connection" title, where substring does not.
  *
- * The finding is a PROBE, not a gate: it forces the critique rewrite and names
- * the reconciliation (delete-tasks legitimately assert absence — the rewrite
- * keeps the check when the GOAL explicitly deletes the artifact).
+ * The finding is a PROBE, not a gate: it only forces the critique rewrite, and
+ * `absenceProbeText` tells that rewrite to KEEP an absence check when the GOAL
+ * explicitly deletes the artifact.
  */
 import { parseVerifyBlock } from './spec-validation.js';
 /** A quoted or bare shell word. */
 const SHELL_WORD = `"[^"]+"|'[^']+'|[^\\s\\]&|;)]+`;
-/** Positive existence probes: `-f P` / `-e P` / `-d P` not preceded by `!`. */
+/**
+ * A `-f`/`-e`/`-d` existence probe, with or without a leading `test`. The three
+ * `(!?)` groups cover every place a negation can sit — before the `[`, inside
+ * it, and before the flag — so the caller can tell `[ ! -f P ]` from `[ -f P ]`.
+ */
 const EXIST_RE = new RegExp(`(!?)\\s*(?:\\[\\[?\\s*)?(!?)\\s*(?:test\\s+)?(!?)\\s*-[efd]\\s+(${SHELL_WORD})`, 'g');
 /** grep probes: optional leading `!`, flags, then the first pattern argument. */
 const GREP_RE = new RegExp(`(!\\s+)?\\bgrep\\s+((?:-{1,2}[\\w=,.-]+\\s+)*)(${SHELL_WORD})`, 'g');
@@ -80,9 +76,11 @@ function assertionsInFragment(fragment, positiveMeansAbsent) {
     return out;
 }
 /**
- * All absence assertions in the spec's VERIFY block. Scans the fenced commands:
- * `if` blocks whose body reaches `exit <nonzero>` contribute their condition's
- * POSITIVE probes; other lines contribute their NEGATED probes.
+ * All absence assertions in the spec's VERIFY block. An `if` line contributes
+ * its condition's POSITIVE probes only when a LATER line reaches
+ * `exit <nonzero>`: the body scan starts at the next command, so a one-line
+ * `if …; then exit 1; fi` yields nothing. Every other line contributes its
+ * NEGATED probes. Empty when the spec has no fenced VERIFY block.
  */
 export function findAbsenceAssertions(spec) {
     const cmds = parseVerifyBlock(spec);
@@ -93,8 +91,10 @@ export function findAbsenceAssertions(spec) {
     for (let i = 0; i < lines.length; i++) {
         const ifm = /^if\s+(.+?)(?:;\s*then\b.*)?$/.exec(lines[i]);
         if (ifm) {
-            // Collect the block body up to the matching fi (flat scan — generated
-            // VERIFY blocks don't nest ifs; a nested one just extends the body).
+            // Collect the block body up to the matching `fi`, counting nested
+            // `if`s. A nested if is never scanned as a condition of its own —
+            // its lines just extend the outer body, so an `exit 1` inside it
+            // arms the OUTER condition.
             let depth = 1;
             let body = '';
             let j = i + 1;
@@ -138,7 +138,8 @@ function namesTarget(haystack, a) {
         return false;
     return new RegExp(`\\b${escapeRe(base)}\\b`, 'i').test(haystack);
 }
-/** Absence assertions that collide with the plan: the deterministic D lever. */
+/** Every absence assertion that collides with the plan. disk, sibling and
+ *  contract are tested independently, so one assertion can yield three. */
 export function findAbsenceConflicts(spec, ctx) {
     const out = [];
     for (const a of findAbsenceAssertions(spec)) {
@@ -160,8 +161,8 @@ export function findAbsenceConflicts(spec, ctx) {
     }
     return out;
 }
-/** The forced critique-rewrite defect text (skip-escape pattern: MANDATORY,
- *  self-contained, names the reconciliation). */
+/** The defect block handed to the critique rewrite. Self-contained: it names
+ *  each conflict, why it is one, and the reconciliation to apply. */
 export function absenceProbeText(conflicts) {
     const what = {
         disk: 'ALREADY EXISTS in the worktree (a prior task shipped it)',
@@ -182,9 +183,10 @@ export function absenceProbeText(conflicts) {
         "exact artifact — then say so in the check's comment."
     ].join('\n');
 }
-/** Parse SIBLING titles out of the scope-fence text (buildScopeFence's listing),
- *  excluding the "(THIS STEP)" line — a task may legitimately assert about its
- *  own deliverables. '' / undefined (bare /task, no plan) yields none. */
+/** Parse SIBLING titles out of `buildScopeFence`'s listing, whose rows read
+ *  `[N] head` and `[N] (THIS STEP) head`. The "(THIS STEP)" row is dropped — a
+ *  task may legitimately assert about its own deliverables. '' and undefined
+ *  (a bare /task with no plan) yield none. */
 export function siblingTitlesFromPlanContext(planContext) {
     if (!planContext)
         return [];

package/dist/task/verify-resolution.d.ts

@@ -1,4 +1,5 @@
-/** Same read-only contract as the verify pass: observe, never edit. */
+/** The observe-only contract handed to the child. The same string as
+ *  verify-work's VERIFY_TOOLS, so both passes are told the same thing. */
 declare const RESOLUTION_TOOLS = "read,bash";
 /** Which card the picker tints RECOMMENDED. */
 export type ResolutionRecommendation = 'autofix' | 'accept';
@@ -11,18 +12,19 @@ export interface ResolutionOutcome {
 }
 /**
  * Build the resolution research child's prompt. Pure, so the wording is
- * unit-tested without spawning pi. The contract: investigate the real workspace
- * and end on exactly one RESOLUTION verdict line.
+ * unit-tested without spawning pi. The contract it states: investigate the real
+ * workspace and end on exactly one `VERIFY-RESOLUTION:` line.
  */
 export declare function buildResolutionPrompt(spec: string, failReason: string): string;
 /**
- * Parse the child's recommendation. Scans for the LAST
- * `VERIFY-RESOLUTION: AUTOFIX|ACCEPT` marker (the model reasons before
- * concluding, and bash output may echo these words, so a distinct token and
- * last-match-wins both matter).
+ * Parse the child's recommendation out of the LAST
+ * `VERIFY-RESOLUTION: AUTOFIX|ACCEPT` marker, case-insensitively. Last match
+ * wins: the model reasons before concluding, and a bash command it runs can
+ * print the token back, so an earlier occurrence is not the verdict.
  *
- * No marker → recommend AUTOFIX (conservative: re-do rather than bless), with a
- * rationale that says the research was inconclusive.
+ * No marker → AUTOFIX (re-do rather than bless), with a rationale saying the
+ * research was inconclusive. A marker with no trailing sentence gets a stock
+ * rationale, so `rationale` is never empty.
  */
 export declare function parseResolutionVerdict(text: string): ResolutionOutcome;
 export declare const ACCEPT_VALUE = "accept";
@@ -37,10 +39,10 @@ export interface ResolutionChoice {
     guidance?: string;
 }
 /**
- * The two cards for the picker, with the model-recommended one FIRST so the boxed
- * renderer tints it green (it marks index 0 as recommended). Values are the bare
- * tokens; remote buttons use the labels — {@link classifyResolutionAnswer}
- * accepts both.
+ * The two cards for the picker, model-recommended one FIRST because the boxed
+ * renderer marks index 0 as the recommended card (bridge.ts `askLocal` passes
+ * `recommended: i === 0`). Values are the bare tokens; remote buttons carry the
+ * labels — {@link classifyResolutionAnswer} accepts both.
  */
 export declare function resolutionOptions(recommend: ResolutionRecommendation): {
     label: string;
@@ -48,10 +50,11 @@ export declare function resolutionOptions(recommend: ResolutionRecommendation):
     recommended: boolean;
 }[];
 /**
- * Map a picker answer to an action. Handles the card value tokens, the remote
- * button labels, an empty/undefined dismissal (cancel), and arbitrary free text
- * typed via the fallback — which becomes an AUTOFIX with that text as guidance
- * (the user is steering the re-run rather than blessing the artifact).
+ * Map a picker answer to an action. undefined or blank is a dismissal (cancel).
+ * A LEADING `accept`/`autofix` word matches, which covers both the bare card
+ * values and the remote button labels. Anything else becomes an AUTOFIX carrying
+ * that text as guidance — including a sentence that mentions "accept" further
+ * along, since the user is steering the re-run, not blessing the artifact.
  */
 export declare function classifyResolutionAnswer(answer: string | undefined): ResolutionChoice;
 export interface ResolutionDeps {
@@ -67,9 +70,10 @@ export interface ResolutionDeps {
 }
 /**
  * Research a verify FAIL and return which action to recommend. Never throws
- * (except a user cancel, which propagates so the loop's USER_CANCELLED handler
- * reports a clean "cancelled — resume"). A child crash defaults to recommending
- * AUTOFIX — the picker is still shown, only the default tint changes.
+ * except on a user cancel, which propagates so the loop's USER_CANCELLED handler
+ * reports a clean "cancelled — resume". A child crash returns AUTOFIX with a
+ * "could not run" rationale; since AUTOFIX is the unattended path, a crash here
+ * costs an implementation re-run rather than a prompt.
  */
 export declare function researchResolution(deps: ResolutionDeps): Promise<ResolutionOutcome>;
 export { RESOLUTION_TOOLS };