@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/verify-resolution.js

@@ -1,42 +1,40 @@
 /**
- * Verify-FAIL resolution research for /task-auto.
+ * Verify-FAIL resolution research.
  *
- * When the work-verification gate (verify-work.ts) returns a FAIL, the run no
- * longer dead-stops with "fix and run /task-auto-resume". Instead the user is
- * shown a boxed two-choice picker:
+ * When the work-verification gate (verify-work.ts) FAILs a task, one of two
+ * things has to happen next:
  *
- *   • Autofix   — re-run the task's implementation turn against the failure, then
- *                 re-enter the verify gate.
- *   • Accept    — treat the artifact as good, override the gate, and proceed
- *                 (check off + commit) exactly as a PASS would.
+ *   • Autofix — re-run the task's implementation turn against the failure, then
+ *               re-enter the verify gate.
+ *   • Accept  — treat the artifact as good, override the gate, and proceed
+ *               (check off + commit) exactly as a PASS would.
  *
- * The recommendation now also GATES whether the user is prompted at all: an
- * AUTOFIX recommendation is auto-applied unattended (bounded — see
- * task-gates.ts MAX_AUTO_AUTOFIX), and the picker is shown only when the
- * recommendation is ACCEPT (blessing the artifact is a human's call) or when the
- * unattended-autofix cap is reached. This module only computes which of the two
- * cards is tinted RECOMMENDED, by handing the FAIL reason + the task spec to
- * a fresh read+bash child of the SAME local model and letting it INVESTIGATE the
- * real workspace: is the FAIL a genuine defect in the work (→ recommend AUTOFIX),
- * or a false alarm / an acceptable artifact the gate misjudged (→ recommend
- * ACCEPT)? This is the same shape of judgement a human reviewer makes when a CI
- * check is red — sometimes the code is broken, sometimes the check is wrong.
+ * This module only computes which of the two is RECOMMENDED. It hands the FAIL
+ * reason and the composed spec to a fresh read+bash child and lets it
+ * INVESTIGATE the real workspace: a genuine defect in the work (→ AUTOFIX), or
+ * an artifact the gate misjudged (→ ACCEPT).
  *
- * Tools: `read` + `bash` only — identical to the verify pass. The recommendation
- * observes; it never edits. (Autofix, when chosen, is what edits — and it goes
- * through the full implementation runner, not this pass.) A read-only research
- * step can never itself change the tree it is judging.
+ * The recommendation also decides whether a human is asked at all. In
+ * task-gates.ts an AUTOFIX recommendation is applied UNATTENDED, bounded by
+ * MAX_AUTO_AUTOFIX; the picker is reached on an ACCEPT recommendation, once that
+ * bound is spent, or when the FAIL is UNOBSERVED or frozen-blocked.
  *
- * The verdict defaults to AUTOFIX when missing/garbled — the conservative choice
- * (re-do the work rather than bless it), which is also the auto-applied path.
+ * Tools: `read` + `bash`, the same string as verify-work's VERIFY_TOOLS. That is
+ * a CONTRACT, not a capability — `bash` can write. gate-child.ts marks the
+ * `recommend` kind `guarded`, so the git-state guard restores whatever this pass
+ * moves.
+ *
+ * The verdict defaults to AUTOFIX when missing or garbled: re-doing the work
+ * rather than blessing it.
  */
 import { USER_CANCELLED } from './child-runner.js';
-/** 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. */
 const RESOLUTION_TOOLS = 'read,bash';
 /**
  * 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 function buildResolutionPrompt(spec, failReason) {
     return [
@@ -96,13 +94,14 @@ export function buildResolutionPrompt(spec, failReason) {
     ].join('\n');
 }
 /**
- * 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 function parseResolutionVerdict(text) {
     const re = /VERIFY-RESOLUTION:\s*(AUTOFIX|ACCEPT)\b[ \t]*(.*)/gi;
@@ -122,20 +121,20 @@ export function parseResolutionVerdict(text) {
 }
 // ─── Picker plumbing ─────────────────────────────────────────────────────────
 //
-// The user ALWAYS makes the final call on a verify FAIL. These pure helpers shape
-// the boxed two-choice picker (verify-resolution → SessionUI.ask in the loop) and
-// classify whatever comes back — a card value, a remote button label, or free
-// text typed via the "type a different answer" fallback — so the orchestration
-// stays mechanical and unit-tested.
+// These pure helpers shape the boxed two-choice picker (task-gates.ts
+// `askVerifyResolution` → SessionUI.ask) and classify whatever comes back — a
+// card value, a remote button label, or free text typed via the "type a
+// different answer" fallback — so the orchestration stays mechanical and
+// unit-tested.
 export const ACCEPT_VALUE = 'accept';
 export const AUTOFIX_VALUE = 'autofix';
 export const ACCEPT_LABEL = 'Accept — keep the artifact as-is and continue';
 export const AUTOFIX_LABEL = 'Autofix — re-run the task to fix it, then verify again';
 /**
- * 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 function resolutionOptions(recommend) {
     const accept = { label: ACCEPT_LABEL, value: ACCEPT_VALUE };
@@ -151,10 +150,11 @@ export function resolutionOptions(recommend) {
         ];
 }
 /**
- * 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 function classifyResolutionAnswer(answer) {
     if (answer === undefined)
@@ -171,9 +171,10 @@ export function classifyResolutionAnswer(answer) {
 }
 /**
  * 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 async function researchResolution(deps) {
     let text;

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

@@ -9,9 +9,9 @@ import { type CrossTaskDeletion } 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`.
  */
 declare const VERIFY_TOOLS = "read,bash";
 export interface VerifyOutcome {
@@ -37,26 +37,22 @@ export interface VerifyOutcome {
     /**
      * WHICH KIND of FAIL this is, as data. Only meaningful when ok === false.
      *
-     * `unobserved` was already carried as a typed field and read as one. Its
-     * siblings were not: the repo-health class travelled only as the `repo health:`
-     * PREFIX of `reason`, and three independent production sites recovered it by
-     * re-typing that literal with two different matchers — the graduated lint-fix
-     * gate, the frozen-blocked contradiction test, and the ONE auto-closing debt
-     * class. A reword of the mint disabled all three, with no compile error and a
-     * green suite. This is the `observedFailures` finding one altitude down: the
-     * outcome CLASS never travelled with the failure TEXT, so every classifier
-     * downstream had to guess.
+     * Without it the class travels only as the PREFIX of `reason`, and every
+     * downstream classifier has to recover it by re-typing that literal — a
+     * reword of the mint would then disarm them with no compile error.
+     * `VERIFY_FAIL_PREFIX` owns the strings so mint and match cannot drift, and
+     * `verifyFailClass` prefers this field over the prefix.
      */
     failClass?: VerifyFailClass;
 }
 /**
- * The kinds of verify FAIL. A new member is a compile error until it declares a
- * display prefix below.
+ * The kinds of verify FAIL. `VERIFY_FAIL_PREFIX` below is a
+ * `Record<VerifyFailClass, string>`, so a new member here is a compile error
+ * (TS2741, "Property 'x' is missing") until it declares a display prefix.
  *
- * `static-checks` is the RUN-level twin of `repo-health`: `final-gate.ts` mints
- * `static checks: …` for the same concept at the other altitude, which is why
- * `isStaticClassDebt` was structurally blind to every run-level static failure
- * that reached the ledger.
+ * `static-checks` is the RUN-level twin of `repo-health`: final-gate.ts mints
+ * `VERIFY_FAIL_PREFIX['static-checks']` for the same concept at the other
+ * altitude, and `isStaticClass` answers true for both.
  */
 export type VerifyFailClass = 'repo-health' | 'static-checks' | 'unobserved' | 'model-verdict' | 'harness-fault';
 /**
@@ -71,10 +67,10 @@ export declare const VERIFY_FAIL_PREFIX: Record<VerifyFailClass, string>;
  * 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 declare function verifyFailClass(o: Pick<VerifyOutcome, 'failClass' | 'reason'>): VerifyFailClass | undefined;
 /** The class a recorded reason STRING belongs to, by its minted prefix. */
@@ -83,46 +79,40 @@ export declare function failClassOfReason(reason: string): VerifyFailClass | und
 export declare function isStaticClass(cls: VerifyFailClass | undefined): boolean;
 /**
  * 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 declare function extractSpecForVerification(taskBody: string): string | null;
 /**
  * ─────────────────────────── THE PROBE TABLE ───────────────────────────
  *
- * Every deterministic probe that sharpens this prompt used to cost the same
- * ritual in four places: a `let x = []` + try/catch in runWorkVerification, a
- * positional parameter on buildVerifyPrompt, a `const xBlock =` ternary, and a
- * spread into the assembled prompt — plus its hand-numbered rule. Adding one
- * meant editing all of them and hoping none was missed; the ninth would not
- * even fit the signature (hence the `projectSurface` bag that used to group
- * three of them).
+ * Each deterministic probe is one ADAPTER row carrying only what is specific to
+ * it: its key (which names the thunk it reads from `deps.probes`), the empty
+ * value it degrades to, how its raw result becomes finding lines, the notice
+ * block those lines produce, and the numbered rule the notice routes the child
+ * to. The loop in `runWorkVerification` owns the ritual, so adding a probe is a
+ * `ProbeRaw` line, a row here, and a binding line in gate-deps — nothing else.
+ * (Same shape as `LOCKFILE_CHECKS` in final-gate.ts, where a whole package
+ * ecosystem is one row.)
  *
- * Each probe is now an ADAPTER: one row carrying only what is specific to it —
- * its key (which names the thunk it reads from `deps.probes`), the empty value it
- * degrades to, how its raw result becomes finding lines, the notice block those
- * lines produce, and the numbered rule the notice routes the child to. The loop
- * owns the ritual. (Same shape as
- * LOCKFILE_CHECKS in final-gate.ts, where a whole package ecosystem is one row.)
- *
- * THIS PROMPT IS A MEASURED ARTIFACT — its wording is A/B-tested on the live
- * local model and the verdicts are recorded in VALIDATION-DEBT.md, so the table
- * must emit BYTE-IDENTICAL text for the same findings. Two orders are
- * load-bearing and they are NOT the same order:
+ * TWO ORDERS ARE LOAD-BEARING AND THEY ARE NOT THE SAME ORDER:
  *   - NOTICE BLOCKS are emitted in TABLE order (the order the rows appear below).
- *   - RULES are emitted sorted by `ruleId`, because the 4b…4g band was
- *     hand-numbered long before this table existed and its numbering is what the
- *     notices cite ("rule 4b applies").
- * A row whose rule is woven into the numbered narrative elsewhere (3b inside the
- * substitution rules, 3f, 5c) carries `ruleId` for the reader and no `rule` text.
+ *   - RULES are emitted sorted by `ruleId`, because the 4b…4g band is
+ *     hand-numbered and that numbering is what the notices cite ("rule 4b
+ *     applies").
+ * A row whose rule is woven into the numbered narrative elsewhere (3b, 3f, 5c)
+ * carries `ruleId` for the reader and no `rule` text.
  */
 /**
  * What each probe channel's RAW probe returns — the one place a channel's shape
- * is declared. `ProbeKey` is derived from it, so a channel exists exactly when it
- * has a row here; delete one and the compiler names its table row and its single
- * binding line in gate-deps' `buildVerifyProbes`.
+ * is declared. `ProbeKey` is `keyof ProbeRaw`, so a channel exists exactly when
+ * it has a line here. Deleting one is a compile error at BOTH of its other sites:
+ * the table row's `key` ("not assignable to type 'keyof ProbeRaw'") and the
+ * binding line in gate-deps' `buildVerifyProbes` ("does not exist in type
+ * 'VerifyProbes'").
  */
 export interface ProbeRaw {
     substitution: string[];
@@ -166,8 +156,8 @@ export declare const BOUND_PROBE_KEYS: readonly BoundProbeKey[];
  * 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 declare function buildVerifyPrompt(spec: string, findings?: ProbeFindings, context?: {
     /** Environment facts earlier gate children discovered — see env-notes.ts. */
@@ -176,9 +166,11 @@ export declare function buildVerifyPrompt(spec: string, findings?: ProbeFindings
     contracts?: string;
 }): string;
 /**
- * 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
@@ -220,8 +212,8 @@ export interface VerificationDeps {
      * `probes` below, all of which run BEFORE the child (and therefore before the
      * child's own status widget exists). Called with a short label as each step
      * starts, so the caller can keep a live line on screen through what was
-     * otherwise the run's longest stretch of dead air (MEASURED at 15–69s per
-     * repo-health run). ABSENT → no progress reporting, same behaviour as before. */
+     * otherwise a long stretch of dead air. Wrapped in a try/catch by the caller,
+     * so a throwing hook cannot break the gate. ABSENT → no progress reporting. */
     onStage?: (stage: string) => void;
     /**
      * The DETERMINISTIC probes, one optional thunk per channel (see `PROBE_ADAPTERS`
@@ -236,7 +228,7 @@ export interface VerificationDeps {
      * Result of the git-state guard for the MOST RECENT runChild call (see
      * git-state-guard.ts): did the child mutate repo state (stash/checkout/file
      * rewrites), which the guard then restored? A verdict computed on a mutated
-     * tree is untrustworthy in BOTH directions — the mx5 run 6 child stashed the
+     * tree is untrustworthy in BOTH directions — a child that stashed the
      * work away and judged an empty tree — so it is discarded: the first mutated
      * run is retried once on the restored tree; a second mutation is a FAIL that
      * names the behavior. ABSENT → no guard (tests / non-git repos), unchanged. */
@@ -259,16 +251,17 @@ export interface VerificationDeps {
      * Per-run cross-slice contract registry (see contracts.ts): `read` supplies the
      * verbatim interface facts the SOURCE design pins that more than one slice
      * touches, injected so the verify child checks THIS slice's boundary against
-     * them (F3 seam bugs are locally right but globally wrong). ABSENT/empty → no
-     * block (single `/task` runs, or a design pinning no shared boundary), unchanged.
+     * them rather than only against itself. ABSENT/empty → no block (single
+     * `/task` runs, or a design pinning no shared boundary).
      */
     contracts?: () => Promise<string>;
 }
 /**
- * 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 declare function runWorkVerification(deps: VerificationDeps): Promise<VerifyOutcome>;
 export { VERIFY_TOOLS };