@mjasnikovs/pi-task 0.38.16 → 0.38.17

package/dist/task/question-source.js

@@ -0,0 +1,174 @@
+/**
+ * Where the NEXT question comes from — the other half of `question-dialog.ts`.
+ *
+ * `question-dialog.ts` unified the ANSWER side of the adaptive dialogs (the picker
+ * cards, the reply mapping) and its own docstring makes the argument for doing so:
+ * *"It was written three times… the two mirrors were never converted, and they had
+ * already drifted apart in three ways… The next edit to any of them is where the
+ * bug lands."* The QUESTION side — generate → parse → pick the real question →
+ * dedupe → spend one corrective re-prompt → yield or exhaust — was left behind,
+ * and it had drifted between the two loops that use the SAME parser on the SAME
+ * prompt format (`plan-prompts.ts` says `parseClarifyList` parses it "UNCHANGED";
+ * `auto-prompts.ts` specifies the identical shape).
+ *
+ * The five drifts, all in clarify's favour of being wrong:
+ *
+ *  1. **Which entry is the question.** `parseClarifyList` pushes an entry for
+ *     EVERY numbered line, and the local model writes numbered analysis notes
+ *     before the question it was asked for (measured live). `pickQuestion` prefers
+ *     the first entry carrying a `SUGGESTED:` line; clarify took `parsed[0]`
+ *     blindly, showing the note as the question and losing the recommendation
+ *     attached further down.
+ *  2. **NONE vs unparseable.** The parser returns `[]` for both. Clarify's
+ *     `if (parsed.length === 0) break` ended the whole clarify — and decomposed the
+ *     feature with ZERO clarifications — on a formatting slip.
+ *  3. **A re-typed sentinel.** `isNoneReply`'s regex was a byte-identical second
+ *     copy of the parser's own.
+ *  4. **Missing SUGGESTED** bought one corrective re-prompt in plan and none in
+ *     clarify, so clarify showed a card-less question.
+ *  5. **The deferral guard.** It exists because an accepted "clarify with the user
+ *     before proceeding" rode into `/task`'s handoff AS AN AUTHORITATIVE DECISION
+ *     and produced a task whose VERIFY asserted no source file had changed.
+ *     Clarify's answers ride into the decompose prompt and the AUTO file with
+ *     exactly the same authority, and had no guard.
+ *
+ * NOT unified here: grill's generation loop. It uses a different parser
+ * (`parseGrillQuestions`, which yields bare strings) and has no `SUGGESTED` at
+ * generation time at all — grill's recommendation comes from `phaseAutoAnswer`
+ * one step later, so every quality rule below is inapplicable to it. Folding it in
+ * would mean a generic over the parsed shape with one consumer opting out of the
+ * entire rule table: a wider interface for less behaviour.
+ */
+import { parseClarifyList } from './parsers.js';
+import { DUP_REPROMPT_HINT, isDuplicateQuestion, MAX_DUP_STRIKES } from './question-dedup.js';
+import { stripInlineMarkdown } from './inline-markdown.js';
+/**
+ * The cap on distinct questions ONE adaptive dialog may ask.
+ *
+ * Clarify and plan each declared their own `8`, linked only by a comment saying
+ * "matches /task-auto's MAX_CLARIFY_QUESTIONS, for the same reason". They bound
+ * the same thing for the same reason; this is that reason, once.
+ */
+export const MAX_DIALOG_QUESTIONS = 8;
+/** True when the reply is the deliberate "nothing left to ask" sentinel, as
+ *  opposed to output the parser simply could not read. */
+export function isNoneReply(raw) {
+    return /^\s*NONE\s*$/m.test(raw);
+}
+/**
+ * Which of the parsed entries is the actual question.
+ *
+ * `parseClarifyList` turns EVERY numbered line into an entry, and the local model
+ * sometimes writes a numbered analysis note or two before the question it was
+ * asked for (measured live: the first numbered line was a note like
+ * "1. gateDebugWriter in orchestrator.ts — wraps a raw append function"). Taking
+ * entry 0 blindly then shows the note as the question and loses the SUGGESTED line
+ * attached further down. The prompt requires exactly one SUGGESTED, and the parser
+ * attaches it to the entry it follows.
+ */
+export function pickQuestion(parsed) {
+    return parsed.find(q => q.suggested !== undefined && q.suggested.length > 0) ?? parsed[0];
+}
+/**
+ * A deep module over a state machine that was five mutable locals per site.
+ *
+ * The interface is one method. Behind it: the cap, the duplicate backstop and its
+ * strike budget, the NONE-vs-unparseable distinction, `pickQuestion`, the one-shot
+ * budget shared by every quality rule, and the hint precedence between a format
+ * re-prompt and a duplicate re-prompt.
+ */
+export function makeQuestionSource(deps) {
+    const cap = deps.cap ?? MAX_DIALOG_QUESTIONS;
+    const rules = deps.rules ?? [];
+    const asked = [];
+    let dupStrikes = 0;
+    let dupHint = null;
+    // The one-shot budget is per QUESTION, not per dialog: a fresh draw starts
+    // with every rule available again. `hint` being non-null is also what spends
+    // it — a rule may not fire while another rule's re-prompt is in flight, which
+    // is what stops two rules ping-ponging a stateless child forever.
+    let hint = null;
+    async function next() {
+        for (;;) {
+            if (asked.length >= cap) {
+                deps.log?.(`question cap (${cap}) reached`);
+                return { kind: 'exhausted', why: 'cap' };
+            }
+            const raw = await deps.generate(hint ?? dupHint);
+            const parsed = parseClarifyList(raw);
+            if (parsed.length === 0) {
+                // `[]` means BOTH "deliberate NONE" and "could not parse". Ending
+                // the dialog on the second is how a formatting slip becomes a
+                // feature decomposed with zero clarifications.
+                if (!isNoneReply(raw) && hint === null) {
+                    deps.log?.('unparseable question reply — one format re-prompt');
+                    hint = deps.formatHint;
+                    continue;
+                }
+                // A SECOND unreadable reply is not a NONE. Recording it as one is
+                // the very conflation this module exists to end — it would put
+                // "model has no further questions" on the trail for a run where
+                // the model produced two malformed replies.
+                if (!isNoneReply(raw)) {
+                    deps.log?.('second unparseable reply — giving up on this draw');
+                    hint = null;
+                    return { kind: 'exhausted', why: 'unparseable' };
+                }
+                deps.log?.('model has no further questions (NONE)');
+                hint = null;
+                return { kind: 'exhausted', why: 'none' };
+            }
+            let picked = pickQuestion(parsed);
+            const plain = stripInlineMarkdown(picked.question);
+            // The duplicate backstop runs BEFORE any quality re-prompt: a question
+            // about to be discarded as a re-ask must not first buy itself an extra
+            // child call to be polished.
+            if (isDuplicateQuestion(asked, plain)) {
+                dupStrikes++;
+                deps.log?.(`duplicate question, strike ${dupStrikes}/${MAX_DUP_STRIKES}`);
+                hint = null;
+                if (dupStrikes >= MAX_DUP_STRIKES)
+                    return { kind: 'exhausted', why: 'dups' };
+                dupHint = DUP_REPROMPT_HINT;
+                continue;
+            }
+            let reprompted = false;
+            for (const rule of rules) {
+                const h = rule.detect(picked, plain);
+                if (h === null)
+                    continue;
+                if (hint === null) {
+                    deps.log?.(`${rule.id} — one re-prompt`);
+                    hint = h;
+                    reprompted = true;
+                    break;
+                }
+                // Survived its re-prompt: degrade rather than discard.
+                if (rule.repair) {
+                    deps.log?.(`${rule.id} — survived the re-prompt, repaired`);
+                    picked = rule.repair(picked);
+                }
+            }
+            if (reprompted)
+                continue;
+            hint = null;
+            dupStrikes = 0;
+            dupHint = null;
+            asked.push(plain);
+            return { kind: 'question', q: picked, plain, index: asked.length };
+        }
+    }
+    /**
+     * Clear the DUP strike budget after the caller supplies new context.
+     *
+     * `/task-plan` lets the user ask the model a question or state a decision
+     * mid-session; that is new context, so a generator that had struck out may now
+     * have something novel. The plan loop reset its own `dupStrikes` at two sites
+     * for exactly this; the budget lives here now, so the reset has to.
+     */
+    function reopen() {
+        dupStrikes = 0;
+        dupHint = null;
+    }
+    return { next, asked: () => asked, reopen };
+}

package/dist/task/serve-entry.js

@@ -38,8 +38,9 @@
  *
  * Ground truth is the file tree only. No model, no network.
  */
-import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import * as path from 'node:path';
+import { shippedSources, stripCommentLines, SOURCE_JS_RE } from './shipped-source.js';
 /** A server-app construction: framework, and the regex that recognises it. */
 const CONSTRUCT_PATTERNS = [
     { re: /\bnew\s+Hono\s*[<(]/, construct: 'new Hono()' },
@@ -180,62 +181,10 @@ export function opaqueLauncher(cwd) {
     }
     return null;
 }
-// Directories never scanned: VCS/dep trees, build output (bundled copies of the
-// same sources), and test/fixture/example/doc trees — a test that stands up a
-// throwaway listener is not the app's launch, and a doc snippet is not code.
-const SKIP_DIR_RE = /^(?:\.git|node_modules|\.pi-tasks|dist|build|out|coverage|target|vendor|__pycache__|\.venv|venv|tmp|test|tests|__tests__|__mocks__|__fixtures__|fixtures|e2e|examples|example|docs|doc|bench|benchmarks)$/;
-const SKIP_FILE_RE = /\.(?:test|spec|stories|bench)\.[a-z]+$|\.d\.[mc]?ts$/i;
-const SCAN_RE = /\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts)$/i;
-const MAX_SCAN_FILES = 3000;
-const MAX_FILE_BYTES = 400_000;
-/** Authored sources, bounded and in deterministic order. */
-function scanCandidates(cwd) {
-    const out = [];
-    const walk = (rel) => {
-        if (out.length >= MAX_SCAN_FILES)
-            return;
-        let entries;
-        try {
-            entries = readdirSync(path.join(cwd, rel)).sort();
-        }
-        catch {
-            return;
-        }
-        for (const name of entries) {
-            if (out.length >= MAX_SCAN_FILES)
-                return;
-            const relPath = rel === '' ? name : `${rel}/${name}`;
-            let st;
-            try {
-                st = statSync(path.join(cwd, relPath));
-            }
-            catch {
-                continue;
-            }
-            if (st.isDirectory()) {
-                if (name.startsWith('.') || SKIP_DIR_RE.test(name))
-                    continue;
-                walk(relPath);
-            }
-            else if (st.isFile() && st.size <= MAX_FILE_BYTES) {
-                if (SKIP_FILE_RE.test(name))
-                    continue;
-                if (SCAN_RE.test(name))
-                    out.push(relPath);
-            }
-        }
-    };
-    walk('');
-    return out;
-}
-/** Strip comment-only lines — a `Bun.serve` quoted in a comment is not a bind, and
- *  a commented-out catch-all is not a route. Inline comments are left alone. */
-function stripCommentLines(src) {
-    return src
-        .split('\n')
-        .filter(l => !/^\s*(?:\/\/|\*|\/\*)/.test(l))
-        .join('\n');
-}
+// The tree walk, the caps, the skip sets and the comment strip live in
+// task/shipped-source.ts — this scan and artifact-closure's were the same walker
+// written twice, and their skip sets had drifted apart on `bench`/`benchmarks`.
+const scanCandidates = (cwd) => shippedSources(cwd, { ext: SOURCE_JS_RE });
 /** A `/…/flags` literal whose body carries a regex METACHARACTER — `[`, `\`, `+`,
  *  `?`, `|`, a group. A path string like `'/api/admin'` has none, so it survives. */
 const REGEX_LITERAL_RE = /\/(?![*/])((?:\\.|\[(?:\\.|[^\]\\])*\]|[^/\\\n])+)\/[gimsuyd]*/g;

package/dist/task/shipped-source.d.ts

@@ -0,0 +1,67 @@
+/**
+ * What counts as SHIPPED SOURCE — the input every run-level closure scan reads.
+ *
+ * `CLOSURE_SCANS` (final-gate.ts) deepened the DRIVER of these scans: the fault
+ * isolation, the rank, the stage. It did not unify their INPUT, and the copies
+ * had drifted.
+ *
+ *  - `scanCandidates` existed twice, near-byte-identical — `serve-entry.ts` and
+ *    `artifact-closure.ts` — same `readdirSync().sort()` → `statSync` → recurse,
+ *    same 3000-file cap, same 400 KB per-file cap, same dot-dir rule.
+ *  - The skip sets had diverged: serve-entry carried `bench|benchmarks` and
+ *    `*.bench.*`; artifact-closure did not, so a dangling artifact reference in a
+ *    benchmark file was a run-level finding while the same file was invisible to
+ *    the sibling scan. Nothing in either file acknowledged the other.
+ *  - The same extension regex was declared twice under two names (`SCAN_RE`,
+ *    `SCAN_JS_RE`), and `stripCommentLines` was byte-identical in both.
+ *  - `.pi-tasks` was hardcoded into both skip sets rather than derived from
+ *    `TASKS_DIR_NAME`.
+ *
+ * The locality proof is in the suites: `artifact-closure.test.ts` has 28
+ * references to the pure extractors and 5 calls to the driver, and NO test in the
+ * cluster asserted a skip set at all. That is the shape recorded under
+ * `resolveTypeSource` — pure functions extracted for testability while the real
+ * logic stayed in how they are CALLED.
+ *
+ * NOT unified here: `env-template-closure.ts`. It asks a different question —
+ * which TRACKED files could read an env var, including `.py`/`.go`, including
+ * tests — and answering it over this walk would silently change which env
+ * findings a run produces. Its comment rule is not this one either: it is a
+ * per-line predicate that also treats `#` as a comment opener, which it must,
+ * and which would be wrong for JS/TS. Recorded as a real divergence rather than
+ * harmonised; changing it is an env-policy change with its own A/B.
+ */
+/** Authored JS/TS. The one declaration — it was two constants under two names. */
+export declare const SOURCE_JS_RE: RegExp;
+/** Markup a produced artifact can be referenced from. */
+export declare const SOURCE_HTML_RE: RegExp;
+/** Bounds. A scan is a gate step, not a search: it must terminate on any tree. */
+export declare const MAX_SCAN_FILES = 3000;
+export declare const MAX_FILE_BYTES = 400000;
+/** Is this directory NAME (not path) one no closure scan descends into? */
+export declare function isSkippedDir(name: string): boolean;
+/** Is this file NAME one no closure scan reads? */
+export declare function isSkippedFile(name: string): boolean;
+export interface ShippedSourceOptions {
+    /** Which extensions this scan reads. */
+    ext: RegExp;
+    /**
+     * Extra ROOT-LEVEL directory names to exclude. artifact-closure's own: a
+     * produced output tree re-referencing its own chunks is noise, and which dirs
+     * are produced is discovered per run, so it cannot live in the static set.
+     */
+    excludeRoots?: ReadonlySet<string>;
+}
+/**
+ * Walk `cwd` for shipped sources — bounded, deterministic order, never throws.
+ *
+ * Unreadable directories and unstattable entries are skipped rather than fatal:
+ * a closure scan runs against whatever tree the implementation left behind.
+ */
+export declare function shippedSources(cwd: string, opts: ShippedSourceOptions): string[];
+/**
+ * Strip comment-only lines. A `Bun.serve` quoted in a comment is not a bind, a
+ * commented-out catch-all is not a route, and a path in a comment is not a
+ * runtime read. Inline comments are left alone — strings may contain `//`.
+ */
+export declare function stripCommentLines(src: string): string;

package/dist/task/shipped-source.js

@@ -0,0 +1,144 @@
+/**
+ * What counts as SHIPPED SOURCE — the input every run-level closure scan reads.
+ *
+ * `CLOSURE_SCANS` (final-gate.ts) deepened the DRIVER of these scans: the fault
+ * isolation, the rank, the stage. It did not unify their INPUT, and the copies
+ * had drifted.
+ *
+ *  - `scanCandidates` existed twice, near-byte-identical — `serve-entry.ts` and
+ *    `artifact-closure.ts` — same `readdirSync().sort()` → `statSync` → recurse,
+ *    same 3000-file cap, same 400 KB per-file cap, same dot-dir rule.
+ *  - The skip sets had diverged: serve-entry carried `bench|benchmarks` and
+ *    `*.bench.*`; artifact-closure did not, so a dangling artifact reference in a
+ *    benchmark file was a run-level finding while the same file was invisible to
+ *    the sibling scan. Nothing in either file acknowledged the other.
+ *  - The same extension regex was declared twice under two names (`SCAN_RE`,
+ *    `SCAN_JS_RE`), and `stripCommentLines` was byte-identical in both.
+ *  - `.pi-tasks` was hardcoded into both skip sets rather than derived from
+ *    `TASKS_DIR_NAME`.
+ *
+ * The locality proof is in the suites: `artifact-closure.test.ts` has 28
+ * references to the pure extractors and 5 calls to the driver, and NO test in the
+ * cluster asserted a skip set at all. That is the shape recorded under
+ * `resolveTypeSource` — pure functions extracted for testability while the real
+ * logic stayed in how they are CALLED.
+ *
+ * NOT unified here: `env-template-closure.ts`. It asks a different question —
+ * which TRACKED files could read an env var, including `.py`/`.go`, including
+ * tests — and answering it over this walk would silently change which env
+ * findings a run produces. Its comment rule is not this one either: it is a
+ * per-line predicate that also treats `#` as a comment opener, which it must,
+ * and which would be wrong for JS/TS. Recorded as a real divergence rather than
+ * harmonised; changing it is an env-policy change with its own A/B.
+ */
+import { readdirSync, statSync } from 'node:fs';
+import * as path from 'node:path';
+import { TASKS_DIR_NAME } from './task-types.js';
+/**
+ * Directories never scanned: VCS/dep trees, build output (bundled copies of the
+ * same sources), and test/fixture/example/doc/bench trees — a test that stands up
+ * a throwaway listener is not the app's launch, a doc snippet is not code, and a
+ * benchmark references fixture paths freely.
+ */
+const SKIP_DIRS = new Set([
+    '.git',
+    'node_modules',
+    TASKS_DIR_NAME,
+    'dist',
+    'build',
+    'out',
+    'coverage',
+    'target',
+    'vendor',
+    '__pycache__',
+    '.venv',
+    'venv',
+    'tmp',
+    'test',
+    'tests',
+    '__tests__',
+    '__mocks__',
+    '__fixtures__',
+    'fixtures',
+    'e2e',
+    'examples',
+    'example',
+    'docs',
+    'doc',
+    'bench',
+    'benchmarks'
+]);
+const SKIP_FILE_RE = /\.(?:test|spec|stories|bench)\.[a-z]+$|\.d\.[mc]?ts$/i;
+/** Authored JS/TS. The one declaration — it was two constants under two names. */
+export const SOURCE_JS_RE = /\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts)$/i;
+/** Markup a produced artifact can be referenced from. */
+export const SOURCE_HTML_RE = /\.html?$/i;
+/** Bounds. A scan is a gate step, not a search: it must terminate on any tree. */
+export const MAX_SCAN_FILES = 3000;
+export const MAX_FILE_BYTES = 400_000;
+/** Is this directory NAME (not path) one no closure scan descends into? */
+export function isSkippedDir(name) {
+    return name.startsWith('.') || SKIP_DIRS.has(name);
+}
+/** Is this file NAME one no closure scan reads? */
+export function isSkippedFile(name) {
+    return SKIP_FILE_RE.test(name);
+}
+/**
+ * Walk `cwd` for shipped sources — bounded, deterministic order, never throws.
+ *
+ * Unreadable directories and unstattable entries are skipped rather than fatal:
+ * a closure scan runs against whatever tree the implementation left behind.
+ */
+export function shippedSources(cwd, opts) {
+    const out = [];
+    const walk = (rel) => {
+        if (out.length >= MAX_SCAN_FILES)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(path.join(cwd, rel)).sort();
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            if (out.length >= MAX_SCAN_FILES)
+                return;
+            const relPath = rel === '' ? name : `${rel}/${name}`;
+            let st;
+            try {
+                st = statSync(path.join(cwd, relPath));
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                if (isSkippedDir(name))
+                    continue;
+                if (rel === '' && opts.excludeRoots?.has(name))
+                    continue;
+                walk(relPath);
+            }
+            else if (st.isFile() && st.size <= MAX_FILE_BYTES) {
+                if (isSkippedFile(name))
+                    continue;
+                if (opts.ext.test(name))
+                    out.push(relPath);
+            }
+        }
+    };
+    walk('');
+    return out;
+}
+/**
+ * Strip comment-only lines. A `Bun.serve` quoted in a comment is not a bind, a
+ * commented-out catch-all is not a route, and a path in a comment is not a
+ * runtime read. Inline comments are left alone — strings may contain `//`.
+ */
+export function stripCommentLines(src) {
+    return src
+        .split('\n')
+        .filter(l => !/^\s*(?:\/\/|\*|\/\*)/.test(l))
+        .join('\n');
+}

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

@@ -31,7 +31,7 @@
 import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import type { RunSingleTaskResult } from './orchestrator.js';
 import type { CommitResult } from './auto-commit.js';
-import type { VerifyOutcome } from './verify-work.js';
+import { type VerifyOutcome } from './verify-work.js';
 import type { EnforceOutcome } from './enforce-guidelines.js';
 import { type ResolutionOutcome, type ResolutionChoice } from './verify-resolution.js';
 import { type RepairCandidate } from './root-cause-repair.js';

package/dist/task/task-gates.js

@@ -1,3 +1,4 @@
+import { verifyFailClass } from './verify-work.js';
 import { resolutionOptions, classifyResolutionAnswer } from './verify-resolution.js';
 import { SessionUI } from '../remote/bridge.js';
 import { isYoloMode, yoloVerifyResolution, YOLO_STAMP } from './yolo.js';
@@ -121,7 +122,8 @@ export async function resolveVerifyGate(ctxIn, deps, p, rec, routeRootCause) {
             // bounded fix attempt before the picker — smallest tool first. Applied →
             // re-verify and re-enter the loop on the fresh verdict; not applied (guard
             // trip, no convergence) → fall through to the ordinary picker unchanged.
-            if (!lintFixAttempted && deps.lintFix && failReason.startsWith('repo health:')) {
+            const failClass = verifyFailClass(verified);
+            if (!lintFixAttempted && deps.lintFix && failClass === 'repo-health') {
                 lintFixAttempted = true;
                 active.ui.notify(`${p.tag}: static findings on "${p.title}" — attempting bounded lint fix…`, 'info');
                 const fix = await deps.lintFix(active, p.cwd, p.title, p.taskId, failReason);
@@ -149,7 +151,7 @@ export async function resolveVerifyGate(ctxIn, deps, p, rec, routeRootCause) {
             // records the (already-recorded) defect as the human's call. Applies
             // only while the FAIL is still the repo-health one the contradiction
             // explains — a later, different FAIL gets the ordinary resolution path.
-            const isFrozenBlocked = frozenContradiction !== null && failReason.startsWith('repo health:');
+            const isFrozenBlocked = frozenContradiction !== null && failClass === 'repo-health';
             const recOutcome = isUnobserved ? { recommend: 'autofix', rationale: failReason }
                 : isFrozenBlocked ?
                     {

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

@@ -34,7 +34,53 @@ export interface VerifyOutcome {
      *  can record each as a durable debt if the user ACCEPTs anyway — the deletion
      *  then ships in the next commit and the final gate must re-check it. */
     crossTaskDeletions?: CrossTaskDeletion[];
+    /**
+     * 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.
+     */
+    failClass?: VerifyFailClass;
 }
+/**
+ * The kinds of verify FAIL. A new member is a compile error until it declares a
+ * display prefix below.
+ *
+ * `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.
+ */
+export type VerifyFailClass = 'repo-health' | 'static-checks' | 'unobserved' | 'model-verdict' | 'harness-fault';
+/**
+ * The prefix each class MINTS, stated once.
+ *
+ * These strings are byte-frozen: the debt ledger stores `reason` verbatim, so a
+ * reword would orphan every debt already on disk. The registry exists so minting
+ * and matching cannot drift apart, not to make the wording editable.
+ */
+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.
+ */
+export declare function verifyFailClass(o: Pick<VerifyOutcome, 'failClass' | 'reason'>): VerifyFailClass | undefined;
+/** The class a recorded reason STRING belongs to, by its minted prefix. */
+export declare function failClassOfReason(reason: string): VerifyFailClass | undefined;
+/** Does this class name a deterministic whole-repo static check, at either altitude? */
+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

package/dist/task/verify-work.js

@@ -87,6 +87,47 @@ import { crossTaskDeletionVerifyFindings } from './task-provenance.js';
  *    enforce pass had to drop `write` to stop.
  */
 const VERIFY_TOOLS = 'read,bash';
+/**
+ * The prefix each class MINTS, stated once.
+ *
+ * These strings are byte-frozen: the debt ledger stores `reason` verbatim, so a
+ * reword would orphan every debt already on disk. The registry exists so minting
+ * and matching cannot drift apart, not to make the wording editable.
+ */
+export const VERIFY_FAIL_PREFIX = {
+    'repo-health': 'repo health:',
+    'static-checks': 'static checks:',
+    unobserved: 'work unobserved:',
+    'model-verdict': 'work did not verify:',
+    'harness-fault': 'verification pass could not run:'
+};
+/**
+ * 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.
+ */
+export function verifyFailClass(o) {
+    if (o.failClass)
+        return o.failClass;
+    return failClassOfReason(o.reason ?? '');
+}
+/** The class a recorded reason STRING belongs to, by its minted prefix. */
+export function failClassOfReason(reason) {
+    const head = reason.trimStart().toLowerCase();
+    for (const [cls, prefix] of Object.entries(VERIFY_FAIL_PREFIX)) {
+        if (head.startsWith(prefix.toLowerCase()))
+            return cls;
+    }
+    return undefined;
+}
+/** Does this class name a deterministic whole-repo static check, at either altitude? */
+export function isStaticClass(cls) {
+    return cls === 'repo-health' || cls === 'static-checks';
+}
 /**
  * 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
@@ -762,8 +803,9 @@ export async function runWorkVerification(deps) {
     if (deps.repoHealth) {
         stage('repo health');
         const h = await deps.repoHealth();
-        if (!h.ok)
-            return { ok: false, reason: `repo health: ${h.reason}` };
+        if (!h.ok) {
+            return { ok: false, failClass: 'repo-health', reason: `repo health: ${h.reason}` };
+        }
     }
     if (!deps.spec || deps.spec.trim().length === 0) {
         return { ok: true, reason: 'no spec to verify' };
@@ -818,7 +860,11 @@ export async function runWorkVerification(deps) {
             if (err instanceof Error && err.message === USER_CANCELLED)
                 throw err;
             const msg = err instanceof Error ? err.message : String(err);
-            return { ok: false, reason: `verification pass could not run: ${msg}` };
+            return {
+                ok: false,
+                failClass: 'harness-fault',
+                reason: `${VERIFY_FAIL_PREFIX['harness-fault']} ${msg}`
+            };
         }
         // Capture the environment facts the child shared — regardless of verdict
         // (a FAIL run's discoveries are just as reusable).
@@ -860,12 +906,14 @@ export async function runWorkVerification(deps) {
             return {
                 ok: false,
                 unobserved: true,
+                failClass: 'unobserved',
                 reason: `work unobserved: ${verdict.detail}`,
                 ...deletions
             };
         }
         return {
             ok: false,
+            failClass: 'model-verdict',
             reason: `work did not verify: ${verdict.detail}${verdict.detail === 'no verdict emitted' ? ' (after verify retry)' : ''}`,
             ...deletions
         };