@mjasnikovs/pi-task 0.18.3 → 0.18.5

package/dist/config/config.d.ts

@@ -12,6 +12,17 @@ export interface PiTaskConfig {
      * phases.ts). Turn on only for a parallel-capable backend.
      */
     parallelResearchWorkers: boolean;
+    /**
+     * Cache docs/search/fetch worker RESULTS for the duration of one /task-auto run
+     * so sibling tasks re-asking the same (package/url, query) reuse the first
+     * pipeline's digest instead of re-fetching (mx5 run-8 F10: the research phase
+     * burned 75 of 363 min largely re-fetching the same external docs across ~20
+     * siblings). Per-run isolated, external-only (project-source `.` lookups excluded),
+     * success-only. DEFAULT ON — the F10 live A/B showed no answer-quality regression
+     * (a cache hit serves byte-identical text to the first fetch; distinct queries never
+     * collide).
+     */
+    researchCache: boolean;
 }
 export declare function getConfig(): PiTaskConfig;
 export declare function saveConfig(config: PiTaskConfig): Promise<void>;

package/dist/config/config.js

@@ -9,7 +9,10 @@ const DEFAULTS = {
     orientation: true,
     enforceGuidelines: true,
     verifyWork: true,
-    parallelResearchWorkers: false
+    parallelResearchWorkers: false,
+    // ON: the F10 live A/B showed no answer-quality regression (fidelity 3/3, quality
+    // 3/3, 0 collisions; ~14.5s of repeated docs lookups collapse to 0ms on a hit).
+    researchCache: true
 };
 const CONFIG_PATH = path.join(os.homedir(), '.config', 'pi-task', 'config.json');
 const _g = globalThis;

package/dist/config/register.js

@@ -77,6 +77,11 @@ const ITEMS = [
         id: 'parallelResearchWorkers',
         label: 'parallel research',
         description: 'Run the 4 research workers concurrently. Leave OFF on a single-GPU local server (serial is measurably faster there); turn on only for a parallel-capable model backend'
+    },
+    {
+        id: 'researchCache',
+        label: 'research cache',
+        description: 'Cache docs/search/fetch results within one /task-auto run so sibling tasks reuse the first pipeline’s digest instead of re-fetching the same external docs. Per-run isolated, external-only, success-only'
     }
 ];
 function makeTheme(theme) {

package/dist/task/accept-debt.d.ts

@@ -0,0 +1,52 @@
+/** One accepted-despite-FAIL record: the task and why its VERIFY failed. */
+export interface AcceptDebt {
+    taskId: string;
+    reason: string;
+}
+export declare function acceptDebtFile(cwd: string): string;
+/** The raw stored ledger ('' when none recorded yet). Parse with parseAcceptDebts. */
+export declare function readAcceptDebtsRaw(cwd: string): Promise<string>;
+/**
+ * Parse the stored ledger into records. A line without the separator (a reason but
+ * no id, e.g. hand-edited) parses with an empty taskId rather than being dropped —
+ * a recorded debt is never silently lost.
+ */
+export declare function parseAcceptDebts(raw: string): AcceptDebt[];
+/** Read + parse in one step. */
+export declare function readAcceptDebts(cwd: string): Promise<AcceptDebt[]>;
+/**
+ * Append one accepted-despite-FAIL record, deduplicated against what is already
+ * stored (case-insensitive on task id + reason), keeping the newest MAX_DEBTS.
+ * Failures are swallowed — the ledger is an auditing aid, never a blocker of the
+ * gate sequence that calls it.
+ */
+export declare function recordAcceptDebt(cwd: string, taskId: string, reason: string): Promise<void>;
+/** Overwrite the ledger with exactly these records (used to prune resolved debts). */
+export declare function writeAcceptDebts(cwd: string, debts: AcceptDebt[]): Promise<void>;
+/**
+ * STATIC-CLASS debt: one whose accepted FAIL was the deterministic whole-repo static
+ * health check (`repo health: …`, the prefix runWorkVerification's repoHealth branch
+ * emits). This is the ONE class a deterministic re-check can prove resolved
+ * stack-agnostically — the final gate runs the same static check, so a later task
+ * that fixed the statics resolves the debt. Every other reason is model-judged or
+ * behavioral and cannot be proven resolved without re-running the model.
+ */
+export declare function isStaticClassDebt(reason: string): boolean;
+/**
+ * Re-check the ledger against the current run state. A static-class debt is RESOLVED
+ * iff the final gate's own static check now passes (`staticOk`); every other debt
+ * stays OPEN (unprovable ⇒ surface, never re-hide). FP-safe: the only auto-close is
+ * the one a deterministic check can stand behind.
+ */
+export declare function recheckAcceptDebts(debts: AcceptDebt[], opts: {
+    staticOk: boolean;
+}): {
+    open: AcceptDebt[];
+    resolved: AcceptDebt[];
+};
+/**
+ * A one-line-per-debt suffix appended to the final gate's report reason so the still
+ * -open accepted defects surface in the gate outcome the user sees (and in the fail
+ * picker). Empty when nothing is open.
+ */
+export declare function buildAcceptDebtNote(open: AcceptDebt[]): string;

package/dist/task/auto-orchestrator.d.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import { type FinalGateFixFn } from './gate-deps.js';
 import { type GateDeps } from './task-gates.js';
+import type { AcceptDebt } from './accept-debt.js';
 /**
  * Injectable seams so the planner and loop are testable without spawning pi.
  * `runChild` is the planning-only seam used by planAuto; everything else (runTask,
@@ -32,6 +33,7 @@ export interface AutoDeps extends GateDeps {
     finalGate?: (cwd: string) => Promise<{
         ok: boolean;
         reason: string;
+        openDebts?: AcceptDebt[];
     }>;
     /**
      * Bounded model-driven fix pass for a final-gate FAIL (see final-gate-fix.ts),

package/dist/task/auto-orchestrator.js

@@ -29,6 +29,7 @@ import { gitUnmergedPaths, gitStashRef } from './auto-commit.js';
 import { runFinalIntegrationGate } from './final-gate.js';
 import { classifyFinalGateAnswer, MAX_FINAL_GATE_AUTOFIX, FINAL_LEAVE_LABEL, FINAL_LEAVE_VALUE, FINAL_ACCEPT_LABEL, FINAL_ACCEPT_VALUE, FINAL_AUTOFIX_LABEL, FINAL_AUTOFIX_VALUE } from './final-gate-fix.js';
 import { getConfig } from '../config/config.js';
+import { configureResearchRun } from '../workers/research-cache.js';
 import { CONTRACT_EXTRACT_PROMPT, parseContractLines, keepGroundedContracts, appendContracts } from './contracts.js';
 // Hard ceiling on clarify questions per feature. The loop is open-ended (it stops
 // when the model emits NONE), but a model that never says NONE would otherwise
@@ -681,6 +682,18 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                     let fin = await deps.finalGate(cwd);
                     if (!fin.ok)
                         await recGate(`final-gate: FAIL — ${fin.reason.slice(0, 300)}`);
+                    // ACCEPT-debt re-check surfacing (mx5 run 4 B3 / run 8 TASK_0012):
+                    // tasks the user accepted despite a verify-FAIL that the gate could
+                    // not prove resolved against the current tree. Surface them at the
+                    // gate moment — on PASS or FAIL — so a run never completes silently
+                    // carrying an accepted defect. Informational: the per-task ACCEPT was
+                    // already a human decision, so this reports, it does not re-fail.
+                    if (fin.openDebts && fin.openDebts.length > 0) {
+                        for (const d of fin.openDebts) {
+                            await recGate(`accept-debt STILL OPEN — ${d.taskId || '(unknown task)'} was ACCEPTED despite verify-FAIL: ${d.reason.slice(0, 240)}`);
+                        }
+                        active.ui.notify(`${id}: ${fin.openDebts.length} task(s) accepted despite verify-FAIL are STILL unresolved at run end — see the gate trail.`, 'warning');
+                    }
                     // Resolution loop: Leave-failed (recommended) / Autofix (bounded,
                     // model-driven fix pass + gate re-run — run 7's gap: the picker
                     // had NO automated fix path) / Accept. The user always decides;
@@ -916,6 +929,10 @@ async function handleTaskAuto(args, ctx) {
         return;
     }
     autoRunning = true;
+    // Stamp a fresh per-run research-cache id (F10) BEFORE planning so enrichment and
+    // every task's research phase share one run's cache; disabled ⇒ clears any token a
+    // prior run left, so nothing is cached.
+    configureResearchRun(getConfig().researchCache);
     const abort = new AbortController();
     const deps = defaultDeps(ctx, cwd, abort.signal, deriveTitle(raw));
     let id;
@@ -958,6 +975,9 @@ async function handleTaskAutoResume(_args, ctx) {
     ctx.ui.notify(`Resuming ${id}…`, 'info');
     await updateTaskFrontMatter(cwd, id, { state: 'in_progress' });
     autoRunning = true;
+    // Fresh per-run research-cache id for the resumed run (F10); a resume re-fetches
+    // rather than reusing the interrupted run's digest — safe, only slightly less reuse.
+    configureResearchRun(getConfig().researchCache);
     const abort = new AbortController();
     // Resume only runs the loop (runTask); no planning children, so the loader
     // title is unused here — pass the id for clarity if that ever changes.

package/dist/task/enforce-guidelines.d.ts

@@ -61,14 +61,14 @@ export declare function discoverGuidelines(cwd: string, readFile?: (p: string) =
  * done, and the contract for the final verdict line. Kept pure so the wording
  * is unit-tested without spawning pi.
  */
-export declare function buildEnforcePrompt(rulesText: string, diff: string): string;
+export declare function buildEnforcePrompt(rulesText: string, diff: string, probeGamingFindings?: string[]): string;
 /**
  * Build the FLAG-ONLY enforcement prompt: same rules + diff, but the child has a
  * `read` tool only and is told to REPORT violations, not fix them. Kept pure so
  * the wording is unit-tested without spawning pi. Used when there is no
  * verification signal to guard a destructive edit (see ENFORCE_FLAG_TOOLS).
  */
-export declare function buildEnforceFlagPrompt(rulesText: string, diff: string): string;
+export declare function buildEnforceFlagPrompt(rulesText: string, diff: string, probeGamingFindings?: string[]): string;
 /**
  * Parse the child's final verdict. Scans for the LAST `ENFORCE: CLEAN` /
  * `ENFORCE: VIOLATION` marker (the model may discuss before concluding).

package/dist/task/enforce-guidelines.js

@@ -26,6 +26,7 @@ import * as path from 'node:path';
 import { runChildDefault } from '../shared/child-process.js';
 import { USER_CANCELLED } from './child-runner.js';
 import { TASKS_DIR_NAME } from './task-types.js';
+import { findProbeGamingInDiff } from './probe-gaming.js';
 /** Filenames discovered in the working directory (cwd only — no tree walk). */
 export const GUIDELINE_FILENAMES = ['AGENTS.md', 'CLAUDE.md'];
 /**
@@ -87,12 +88,33 @@ export async function discoverGuidelines(cwd, readFile = p => fsp.readFile(p, 'u
         return null;
     return { files, text: sections.join('\n\n') };
 }
+/**
+ * Render the deterministic probe-gaming findings (run-8 F6) as a prompt block, or
+ * an empty array when there are none. Shared by the edit and flag prompts: the
+ * finding is a concrete diff line whose stated purpose is to make a check pass
+ * rather than meet the requirement — the reliable lever the prompt rule leans on.
+ * The `action` line differs (fix vs report) between the two capability modes.
+ */
+function probeGamingEnforceBlock(findings, action) {
+    if (findings.length === 0)
+        return [];
+    return [
+        'CHECK-GAMING NOTICE (deterministic, computed from the diff): these added lines',
+        'state their own purpose is to make a CHECK pass (a test / verification / lint /',
+        'gate), not to meet the requirement the check stands for:',
+        ...findings.map(f => `- ${f}`),
+        'A check is a MESSENGER for a requirement; code written only to quiet the messenger',
+        'is a defect even when the check is green (run-8 F6: a handler returned 401 "so the',
+        `verification test passes" while the real route stayed dead). ${action}`,
+        ''
+    ];
+}
 /**
  * Build the enforcement child's prompt: the rules, the diff of the work just
  * done, and the contract for the final verdict line. Kept pure so the wording
  * is unit-tested without spawning pi.
  */
-export function buildEnforcePrompt(rulesText, diff) {
+export function buildEnforcePrompt(rulesText, diff, probeGamingFindings = []) {
     return [
         'You are a strict guideline-enforcement pass running right after an AI coding',
         'agent finished a task and committed it. The agent is known to skip project',
@@ -111,6 +133,9 @@ export function buildEnforcePrompt(rulesText, diff) {
         'CHANGES IN THE LAST COMMIT (verify these specifically against the rules):',
         diff.trim().length > 0 ? diff : '(no textual diff captured — nothing to verify)',
         '',
+        ...probeGamingEnforceBlock(probeGamingFindings, 'Treat this as a violation: replace the check-gaming code with a real'
+            + ' implementation of the requirement, or if you cannot, report it as a'
+            + ' VIOLATION naming the gamed check.'),
         'Your job:',
         '1. Read each changed file and check it against EVERY rule above.',
         '2. For each violation you find, FIX it directly with your `edit` tool, then',
@@ -130,7 +155,7 @@ export function buildEnforcePrompt(rulesText, diff) {
  * the wording is unit-tested without spawning pi. Used when there is no
  * verification signal to guard a destructive edit (see ENFORCE_FLAG_TOOLS).
  */
-export function buildEnforceFlagPrompt(rulesText, diff) {
+export function buildEnforceFlagPrompt(rulesText, diff, probeGamingFindings = []) {
     return [
         'You are a strict guideline-enforcement REVIEW pass running right after an AI',
         'coding agent finished a task and committed it. The agent is known to skip',
@@ -146,6 +171,8 @@ export function buildEnforceFlagPrompt(rulesText, diff) {
         'CHANGES IN THE LAST COMMIT (review these specifically against the rules):',
         diff.trim().length > 0 ? diff : '(no textual diff captured — nothing to verify)',
         '',
+        ...probeGamingEnforceBlock(probeGamingFindings, 'Treat this as a violation and REPORT it (do not fix it): name the gamed check'
+            + ' and the requirement left unmet.'),
         'Read each changed file and check it against EVERY rule above. Do NOT attempt',
         'to fix anything — only report what you find.',
         '',
@@ -279,9 +306,15 @@ export async function runGuidelineEnforcement(deps) {
     if (!doc)
         return { ok: true, reason: 'no guideline files' };
     const diff = await getDiff(deps.cwd, deps.signal);
+    // Deterministic probe-gaming findings (F6) straight from the captured diff — no
+    // extra git call, the diff is already in hand. Injected under the CHECK-GAMING
+    // rule so the child acts on a concrete line, not on self-discovered intent.
+    const probeGaming = findProbeGamingInDiff(diff);
     const flagOnly = deps.mode === 'flag';
     const tools = flagOnly ? ENFORCE_FLAG_TOOLS : ENFORCE_TOOLS;
-    const prompt = flagOnly ? buildEnforceFlagPrompt(doc.text, diff) : buildEnforcePrompt(doc.text, diff);
+    const prompt = flagOnly ?
+        buildEnforceFlagPrompt(doc.text, diff, probeGaming)
+        : buildEnforcePrompt(doc.text, diff, probeGaming);
     let text;
     try {
         text = await deps.runChild(tools, prompt, deps.signal);

package/dist/task/env-notes.d.ts

@@ -1,23 +1,39 @@
 export declare function envNotesFile(cwd: string): string;
-/** The cached notes, one fact per line ('' when none were recorded yet). */
+/** The raw stored file ('' when none were recorded yet). Parse with parseEnvNotes. */
 export declare function readEnvNotes(cwd: string): Promise<string>;
+/** One recorded fact plus the origin task that established it (may be ''). */
+export interface EnvNote {
+    fact: string;
+    origin: string;
+}
+/**
+ * Parse the stored file into fact+origin records. Legacy lines written before
+ * provenance (no separator) parse with an empty origin, so old caches still read.
+ */
+export declare function parseEnvNotes(raw: string): EnvNote[];
 /**
  * Pull `ENV-NOTE: <fact>` lines out of a child's answer text. Deduplicated,
  * length-capped; verdict markers can never match (different prefix).
  */
 export declare function extractEnvNotes(text: string): string[];
+/** True when a fact reads like a standing excuse (see EXCUSE_PATTERNS). */
+export declare function isExcuseNote(fact: string): boolean;
 /**
  * Append newly discovered facts to the cache, deduplicated against what is
- * already there (case-insensitive full-line match), keeping the newest
- * MAX_NOTES. Failures are swallowed — the cache is a sharpener, never a
+ * already there (case-insensitive fact match), keeping the newest MAX_NOTES.
+ * Each new fact is stamped with the `origin` task that recorded it; a fact
+ * already present keeps its ORIGINAL origin (provenance traces to who first
+ * established it). Failures are swallowed — the cache is a sharpener, never a
  * blocker.
  */
-export declare function appendEnvNotes(cwd: string, notes: string[]): Promise<void>;
+export declare function appendEnvNotes(cwd: string, notes: string[], origin?: string): Promise<void>;
 /**
- * The prompt block a gate child receives when notes exist. The caveat is
- * load-bearing: facts save re-discovery time but grant no waiver from the
- * verify-as-shipped rule.
+ * The prompt block a gate child receives when notes exist. Two things are
+ * load-bearing: the no-waiver caveat (facts save re-discovery time but grant no
+ * license to prepare/repair) and the trust discipline (a note is second-hand
+ * until re-validated; an EXCUSE-CLASS note may not wave off a failure without a
+ * live re-check; a grep of a generated artifact is not evidence of absence).
  */
-export declare function buildEnvNotesBlock(notes: string): string;
+export declare function buildEnvNotesBlock(raw: string): string;
 /** The emit instruction appended to bash-capable gate-child prompts. */
 export declare const ENV_NOTE_EMIT_INSTRUCTION: string;

package/dist/task/env-notes.js

@@ -18,6 +18,19 @@
  * project setup: the verify-as-shipped rule ("any prep you needed IS the
  * defect") still governs every verdict — the block injected into prompts says
  * so explicitly. The cache only kills re-discovery time.
+ *
+ * PROVENANCE + RE-VALIDATION (run 8, F7): a verify child once grepped component
+ * names in a MINIFIED bundle (identifiers mangled ⇒ 0 hits by construction),
+ * wrote "build tree-shakes ALL route components — pre-existing issue" to the
+ * cache, and ten later tasks inherited it verbatim as a standing "pre-existing,
+ * unrelated" excuse to wave off a genuinely broken deliverable — nobody
+ * re-checked. Two guards close that class: (a) each note is stamped host-side
+ * with the ORIGIN task that recorded it (a note is second-hand hearsay, not the
+ * reader's own observation); (b) the injected block demands the reader
+ * RE-VALIDATE a note in the CURRENT tree before citing it to excuse a failure,
+ * flags EXCUSE-CLASS notes ("pre-existing", "unrelated", "tree-shaken") for
+ * exactly that scrutiny, and forbids treating a grep of a generated artifact as
+ * evidence of absence. Provenance is mechanical; re-validation is prompt-level.
  */
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
@@ -27,10 +40,16 @@ const ENV_NOTES_FILE = 'env-notes.md';
 const MAX_NOTES = 40;
 /** A single fact is one line; anything longer is prose, not a fact. */
 const MAX_NOTE_LENGTH = 240;
+/**
+ * Field separator between a fact and its origin in the stored file. A tab never
+ * occurs in a one-line fact (facts are prose), so it round-trips cleanly and any
+ * stray tab in an emitted fact is normalised to a space before storage.
+ */
+const ORIGIN_SEP = '\t';
 export function envNotesFile(cwd) {
     return path.join(tasksDir(cwd), ENV_NOTES_FILE);
 }
-/** The cached notes, one fact per line ('' when none were recorded yet). */
+/** The raw stored file ('' when none were recorded yet). Parse with parseEnvNotes. */
 export async function readEnvNotes(cwd) {
     try {
         return (await fsp.readFile(envNotesFile(cwd), 'utf8')).trim();
@@ -39,6 +58,27 @@ export async function readEnvNotes(cwd) {
         return '';
     }
 }
+/**
+ * Parse the stored file into fact+origin records. Legacy lines written before
+ * provenance (no separator) parse with an empty origin, so old caches still read.
+ */
+export function parseEnvNotes(raw) {
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const t = line.trim();
+        if (t.length === 0)
+            continue;
+        const i = t.indexOf(ORIGIN_SEP);
+        if (i === -1)
+            out.push({ fact: t, origin: '' });
+        else
+            out.push({ fact: t.slice(0, i).trim(), origin: t.slice(i + 1).trim() });
+    }
+    return out;
+}
+function serializeNote(n) {
+    return n.origin ? `${n.fact}${ORIGIN_SEP}${n.origin}` : n.fact;
+}
 /**
  * Pull `ENV-NOTE: <fact>` lines out of a child's answer text. Deduplicated,
  * length-capped; verdict markers can never match (different prefix).
@@ -58,54 +98,110 @@ export function extractEnvNotes(text) {
     }
     return notes;
 }
+/**
+ * EXCUSE-CLASS wording: a note that waves a problem off as someone else's or a
+ * prior condition ("pre-existing … mismatch", "unrelated to this task",
+ * "tree-shaken", "not applicable"). These are the notes that propagate across
+ * slices as standing excuses (mx5 run-8 F7) — every one of the run-8 cache's
+ * dozen such notes was either the false tree-shake fact or the schema mismatch
+ * the final gate later proved was a REAL defect. Pure text, stack-agnostic; the
+ * flag never drops or fails a note, it only marks it as needing live
+ * re-validation before it may EXCUSE a failure. FP is harmless by construction:
+ * a benign fact re-validates and is used, the marker only bites a citation-to-
+ * wave-off. Benign status facts ("5 pre-existing warnings") do not match — a
+ * "pre-existing" match requires a co-located problem word.
+ */
+const EXCUSE_PATTERNS = [
+    /\bunrelated\b/i,
+    /\bnot (?:my|our|this) (?:task|concern|deliverable|slice|problem)\b/i,
+    /\boutside (?:the|this) deliverable\b/i,
+    /\bnot applicable\b/i,
+    /\bnot specific to\b/i,
+    /\btree[-\s]?shak/i,
+    /\bpre-?existing\b[^.\n]*\b(?:fail|issue|mismatch|bug|error|broken|problem|affect)/i,
+    /\baffect(?:ing|s)? all\b/i
+];
+/** True when a fact reads like a standing excuse (see EXCUSE_PATTERNS). */
+export function isExcuseNote(fact) {
+    return EXCUSE_PATTERNS.some(re => re.test(fact));
+}
 /**
  * Append newly discovered facts to the cache, deduplicated against what is
- * already there (case-insensitive full-line match), keeping the newest
- * MAX_NOTES. Failures are swallowed — the cache is a sharpener, never a
+ * already there (case-insensitive fact match), keeping the newest MAX_NOTES.
+ * Each new fact is stamped with the `origin` task that recorded it; a fact
+ * already present keeps its ORIGINAL origin (provenance traces to who first
+ * established it). Failures are swallowed — the cache is a sharpener, never a
  * blocker.
  */
-export async function appendEnvNotes(cwd, notes) {
+export async function appendEnvNotes(cwd, notes, origin = '') {
     if (notes.length === 0)
         return;
     try {
-        const existing = (await readEnvNotes(cwd)).split('\n').filter(l => l.trim().length > 0);
-        const seen = new Set(existing.map(l => l.trim().toLowerCase()));
+        const existing = parseEnvNotes(await readEnvNotes(cwd));
+        const seen = new Set(existing.map(n => n.fact.toLowerCase()));
         const merged = [...existing];
         for (const note of notes) {
-            const key = note.trim().toLowerCase();
-            if (seen.has(key))
+            const fact = note.trim().replace(/\t/g, ' ');
+            const key = fact.toLowerCase();
+            if (key.length === 0 || seen.has(key))
                 continue;
             seen.add(key);
-            merged.push(note.trim());
+            merged.push({ fact, origin: origin.trim() });
         }
         const kept = merged.slice(-MAX_NOTES);
         await fsp.mkdir(tasksDir(cwd), { recursive: true });
-        await fsp.writeFile(envNotesFile(cwd), kept.join('\n') + '\n', 'utf8');
+        await fsp.writeFile(envNotesFile(cwd), kept.map(serializeNote).join('\n') + '\n', 'utf8');
     }
     catch {
         // best-effort cache
     }
 }
 /**
- * The prompt block a gate child receives when notes exist. The caveat is
- * load-bearing: facts save re-discovery time but grant no waiver from the
- * verify-as-shipped rule.
+ * The prompt block a gate child receives when notes exist. Two things are
+ * load-bearing: the no-waiver caveat (facts save re-discovery time but grant no
+ * license to prepare/repair) and the trust discipline (a note is second-hand
+ * until re-validated; an EXCUSE-CLASS note may not wave off a failure without a
+ * live re-check; a grep of a generated artifact is not evidence of absence).
  */
-export function buildEnvNotesBlock(notes) {
-    if (notes.trim().length === 0)
+export function buildEnvNotesBlock(raw) {
+    const notes = parseEnvNotes(raw);
+    if (notes.length === 0)
         return '';
+    const lines = notes.map(n => {
+        const origin = n.origin ? ` — recorded by ${n.origin}` : ' — origin unrecorded';
+        const flag = isExcuseNote(n.fact) ?
+            '  [EXCUSE-CLASS — re-validate in the CURRENT tree before citing this to wave off any failure]'
+            : '';
+        return `- ${n.fact}${origin}${flag}`;
+    });
     return [
-        'KNOWN ENVIRONMENT FACTS — discovered by earlier verification passes in this run',
-        '(informational, may be stale):',
-        ...notes
-            .trim()
-            .split('\n')
-            .map(n => `- ${n}`),
+        'KNOWN ENVIRONMENT FACTS — recorded by earlier verification passes in this run',
+        '(second-hand, may be stale or WRONG):',
+        ...lines,
+        '',
         'These facts only save you re-discovery time (where credentials/config live, which',
         'tools are installed, which services are reachable). They are NOT a license to',
         'prepare or repair the run: the verify-as-shipped rules below still govern the',
         'verdict — if the project needs something its own committed files do not provide,',
         'that remains the defect no matter what is listed here.',
+        '',
+        'TRUST DISCIPLINE — a false "pre-existing, unrelated" note once masked a real shipped',
+        'defect across many tasks in this exact pipeline; do not repeat it:',
+        '- A note above is second-hand hearsay from another task, not your own observation.',
+        '  You may CITE one to EXCUSE, wave off, or down-grade a failure ONLY IF you',
+        '  RE-VALIDATE its claim in the CURRENT tree right now and state the command or',
+        '  observation you used to reconfirm it.',
+        '- If a note fails re-validation (its claim is not true in the current tree), do NOT',
+        "  inherit it: treat the underlying problem as UNexcused and report it. Don't silently",
+        '  carry a stale fact forward.',
+        '- EVIDENCE HYGIENE: string-searching a MINIFIED, bundled, or otherwise generated or',
+        '  compiled artifact is NOT evidence that something is absent — identifiers there are',
+        '  renamed or stripped by construction, so a zero-hit grep proves nothing. Derive',
+        '  presence/absence only from SOURCE files or by EXECUTING the artifact and observing.',
+        '- A claim that a defect is "pre-existing", "unrelated", or "not this task" is an',
+        '  EXCUSE, not a fact (the ones above are marked): re-establish it live, and if it',
+        '  actually holds as a real defect, escalate it (report FAIL) rather than passing it',
+        '  on as a standing waiver.',
         ''
     ].join('\n');
 }
@@ -115,7 +211,11 @@ export const ENV_NOTE_EMIT_INSTRUCTION = [
     'THIS MACHINE or the project environment (a service reachable/absent at an address, where',
     'credentials/config live, a tool or runtime present/missing and its version), emit a line',
     '  ENV-NOTE: <one-line fact>',
-    'anywhere in your answer, one per fact. Facts about the ENVIRONMENT only — never task',
-    'verdicts, never spec content, never code judgments. These are cached for later',
-    'verification passes in this run so they do not re-discover the same things.'
+    'anywhere in your answer, one per fact. A fact is something you OBSERVED to be true of the',
+    'machine or environment — never a task verdict, never spec content, never a judgment about',
+    'the code. In particular do NOT record an absence you inferred from grepping a built or',
+    'minified artifact (identifiers there are mangled — a zero-hit grep proves nothing), and',
+    'do NOT record "X is pre-existing / unrelated / not my task": that is a verdict, not an',
+    'environment fact. These are cached for later verification passes in this run so they do',
+    'not re-discover the same things.'
 ].join('\n');

package/dist/task/final-gate.d.ts

@@ -1,9 +1,17 @@
 import { type HealthCommand } from './repo-health-check.js';
+import { type AcceptDebt } from './accept-debt.js';
 export interface FinalGateOutcome {
     /** true → statics and every runnable integration command passed (or nothing to run). */
     ok: boolean;
     /** On a fail: the exact command, its exit code, and the tail of its output. */
     reason: string;
+    /**
+     * ACCEPT-despite-verify-FAIL debts still open at run end (mx5 run 4 B3 / run 8
+     * TASK_0012): tasks the user blessed as-is despite a verify-FAIL that a
+     * deterministic re-check could not prove resolved. The caller surfaces them so a
+     * run never completes silently carrying an accepted defect. Empty/absent = none.
+     */
+    openDebts?: AcceptDebt[];
 }
 /**
  * The project's OWN whole-repo integration commands (test, then build — test

package/dist/task/final-gate.js

@@ -42,6 +42,7 @@ import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import * as path from 'node:path';
 import { runRepoHealthCheck, discoverHealthCommands } from './repo-health-check.js';
+import { readAcceptDebts, recheckAcceptDebts, writeAcceptDebts, buildAcceptDebtNote } from './accept-debt.js';
 function packageScripts(cwd) {
     try {
         const j = JSON.parse(readFileSync(path.join(cwd, 'package.json'), 'utf8'));
@@ -280,13 +281,32 @@ function runGateCommand(cwd, [bin, args], timeoutMs) {
  */
 export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGraceMs = 10_000) {
     const stat = runRepoHealthCheck(cwd);
+    // ACCEPT-debt re-check (mx5 run 4 B3 / run 8 TASK_0012): read the ledger of tasks
+    // the user accepted despite a verify-FAIL and re-check each against the current
+    // tree. A static-class debt whose statics now pass is provably RESOLVED (a later
+    // task fixed it) and pruned; every other debt cannot be proven resolved
+    // deterministically, so it stays OPEN and is surfaced in this gate's report — a
+    // run may not complete silently carrying an accepted defect. FP-safe by
+    // construction (see accept-debt.ts). Best-effort: a ledger read/write failure
+    // must never break the gate.
+    const { open: openDebts, resolved } = recheckAcceptDebts(await readAcceptDebts(cwd), {
+        staticOk: stat.ok
+    });
+    if (resolved.length > 0)
+        await writeAcceptDebts(cwd, openDebts);
+    const debtNote = buildAcceptDebtNote(openDebts);
+    const withDebts = (o) => ({
+        ...o,
+        reason: `${o.reason}${debtNote}`,
+        openDebts
+    });
     if (!stat.ok)
-        return { ok: false, reason: `static checks: ${stat.reason}` };
+        return withDebts({ ok: false, reason: `static checks: ${stat.reason}` });
     const lockCmds = discoverLockfileChecks(cwd);
     const { cmds } = discoverIntegrationCommands(cwd);
     const boot = discoverBootCommand(cwd);
     if (lockCmds.length === 0 && cmds.length === 0 && !boot) {
-        return { ok: true, reason: 'no integration command found (statics passed)' };
+        return withDebts({ ok: true, reason: 'no integration command found (statics passed)' });
     }
     const ran = [];
     for (const { prefix, list } of [
@@ -299,10 +319,10 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
             if (r.outcome === 'skip')
                 continue;
             if (r.outcome === 'fail') {
-                return {
+                return withDebts({
                     ok: false,
                     reason: `${prefix}\`${label}\` exited ${r.status}${r.tail ? ` — ${r.tail}` : ''}`
-                };
+                });
             }
             ran.push(label);
         }
@@ -311,15 +331,15 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
         const label = `${boot[0]} ${boot[1].join(' ')}`;
         const b = await runBootCheck(cwd, boot, bootGraceMs);
         if (b.outcome === 'fail') {
-            return { ok: false, reason: `boot check: \`${label}\` ${b.detail}` };
+            return withDebts({ ok: false, reason: `boot check: \`${label}\` ${b.detail}` });
         }
         if (b.outcome === 'pass')
             ran.push(label);
     }
-    return {
+    return withDebts({
         ok: true,
         reason: ran.length > 0 ?
             `statics + ${ran.map(c => `\`${c}\``).join(', ')} passed`
             : 'statics passed (integration commands not runnable here)'
-    };
+    });
 }