@mjasnikovs/pi-task 0.18.2 → 0.18.4

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 { 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
 // barrage the user — the real mx5 run asked 10, several of them redundant.
@@ -513,6 +514,25 @@ export async function planAuto(ctx, cwd, feature, deps) {
             + unresolvedMissing.join('; ').slice(0, 300));
         ctx.ui.notify(`/task-auto: plan may be missing coverage — ${unresolvedMissing.join('; ').slice(0, 200)} — review the plan before running.`, 'warning');
     }
+    // Cross-slice contract registry (mx5 run 8, F3): now that the plan is settled,
+    // extract the interface facts MORE THAN ONE slice must agree on — endpoint paths,
+    // exported signatures, file layouts, env var names the DESIGN pins — into a
+    // run-level artifact each downstream refine/compose/verify reads. The extraction
+    // child EMITs `CONTRACT:` lines, but every quote is re-grounded HOST-SIDE against
+    // the design (keepGroundedContracts): a fact the child paraphrased or invented is
+    // not a substring of the doc and is dropped, so a fabricated contract — exactly
+    // the F3 bug — can never enter the registry. Best-effort: any fault here is
+    // swallowed (the registry is a sharpener, never a planning blocker).
+    try {
+        const contractRaw = await deps.runChild('contract-extract', '', CONTRACT_EXTRACT_PROMPT(featureForModel, planTitles));
+        const grounded = keepGroundedContracts(parseContractLines(contractRaw), featureForModel);
+        logPlanDebug(cwd, `contract extraction: ${grounded.length} grounded contract(s) kept`
+            + ` from ${parseContractLines(contractRaw).length} emitted`);
+        await appendContracts(cwd, grounded);
+    }
+    catch {
+        // best-effort registry
+    }
     // Thread the feature's spec doc(s) into every title so each per-task
     // pipeline — which only ever sees its title — reads the real spec instead of
     // a lossy one-line paraphrase of it.
@@ -540,7 +560,8 @@ export async function planAuto(ctx, cwd, feature, deps) {
 const AUTO_PLAN_STEPS = {
     'auto-clarify': { step: 'clarify', stepNum: 1 },
     'auto-decompose': { step: 'decompose', stepNum: 2 },
-    'decompose-coverage': { step: 'coverage', stepNum: 2 }
+    'decompose-coverage': { step: 'coverage', stepNum: 2 },
+    'contract-extract': { step: 'contracts', stepNum: 2 }
 };
 const AUTO_PLAN_STEP_TOTAL = 2;
 function defaultDeps(ctx, cwd, signal, title) {

package/dist/task/contracts.d.ts

@@ -0,0 +1,54 @@
+export interface ContractEntry {
+    /** The verbatim quote from the source doc — the pinned interface fact. */
+    quote: string;
+    /** Where in the source it came from (a header, a section name) — free text. */
+    anchor: string;
+}
+export declare function contractsFile(cwd: string): string;
+/** The stored registry text ('' when none recorded yet). */
+export declare function readContracts(cwd: string): Promise<string>;
+/**
+ * Parse `CONTRACT:` lines out of a child's answer text into entries. The line shape
+ * the extraction prompt asks for is:
+ *   CONTRACT: "<verbatim quote>" [anchor: <where>]
+ * The quote (between the first pair of double quotes) is the pinned fact; the
+ * optional `[anchor: …]` trailer records provenance. A line without a quoted span
+ * is skipped — an unquoted "contract" is a summary, which this registry rejects.
+ */
+export declare function parseContractLines(text: string): ContractEntry[];
+/**
+ * THE ANTI-SYNTHESIS GUARD (the F3 defense): keep only entries whose quote actually
+ * appears in the source document. A paraphrase or fabrication is not a substring of
+ * the doc, so it is dropped — the registry cannot be poisoned with a synthesized
+ * contract. Matching is whitespace-insensitive and case-insensitive so a faithful
+ * quote across a line wrap still counts. Deduplicated (case-insensitive on the quote).
+ */
+export declare function keepGroundedContracts(entries: ContractEntry[], sourceDoc: string): ContractEntry[];
+/**
+ * Append grounded entries to the registry, deduplicated (case-insensitive on the
+ * quote) against what is already stored, keeping the newest MAX_CONTRACTS. Failures
+ * are swallowed — the registry is a sharpener, never a blocker.
+ */
+export declare function appendContracts(cwd: string, entries: ContractEntry[]): Promise<void>;
+/**
+ * The read-only prompt block a downstream slice (refine/compose) receives when the
+ * registry is non-empty. It is authoritative: these are the pinned cross-slice
+ * contracts from the SOURCE doc, and a slice must not restate them differently.
+ */
+export declare function buildContractsBlock(contracts: string): string;
+/**
+ * The block the VERIFY child receives: the same registry, plus the mandate to check
+ * the slice's actual boundary against it (F3 is a seam bug — locally right, globally
+ * wrong — so per-slice verification must look at the boundary, not just the interior).
+ */
+export declare function buildContractsVerifyBlock(contracts: string): string;
+/**
+ * The full decompose-time extraction prompt: the design and the just-decomposed
+ * task titles (so the child can judge which facts a boundary is SHARED on), plus
+ * the emit instruction. Runs with --no-tools — pure extraction over text in hand.
+ * The host re-grounds every emitted quote against the design (keepGroundedContracts),
+ * so a hallucinated contract cannot survive even if the child fabricates one here.
+ */
+export declare const CONTRACT_EXTRACT_PROMPT: (feature: string, titles: string[]) => string;
+/** The emit instruction for the decompose-time extraction child. */
+export declare const CONTRACT_EMIT_INSTRUCTION: string;

package/dist/task/contracts.js

@@ -0,0 +1,226 @@
+/**
+ * contracts — a per-run registry of CROSS-SLICE INTERFACE FACTS, recorded once at
+ * decompose time and read (never written) by every downstream slice.
+ *
+ * The failure this serves (mx5 run 8, F3 — the dominant shipped-defect class): the
+ * SOURCE design pins an interface contract (a SPLIT route table: `POST
+ * /api/listings/:id/photos` but `GET/DELETE /api/photos/:id`). One slice's refine
+ * FABRICATED a uniform mount table ("/api/photos → photosRoutes") with no anchor in
+ * the doc; the consumer slices followed the spec, the assembly slice followed the
+ * fabrication, and the seam between them shipped broken while each slice was locally
+ * "right". Class: refine synthesizes plausible interface specifics instead of citing.
+ *
+ * Mechanism (mirrors env-notes.ts): interface facts that MORE THAN ONE task will
+ * touch — endpoint paths, exported signatures, file layouts, env var names, whatever
+ * the SOURCE DOC pins — are extracted ONCE (a decompose-time child EMITs `CONTRACT:`
+ * lines) and appended HOST-SIDE to `.pi-tasks/contracts.md`. Children never write the
+ * file (no artifact corruption). It lives under `.pi-tasks/`, surviving discardEdits
+ * and the git-state guard.
+ *
+ * HARD DESIGN RULE (this is exactly how F3 happened): a registry entry is a VERBATIM
+ * QUOTE from the source doc plus a source anchor — NEVER a model-synthesized summary.
+ * The anti-synthesis guard is deterministic: a candidate quote is kept only if it is
+ * an actual substring of the source document (normalised for whitespace). A quote the
+ * model paraphrased or invented is not in the doc, so it is dropped — a fabricated
+ * contract can never enter the registry.
+ *
+ * Stack-agnostic: an "interface fact" is any pinned boundary string; the guard is
+ * pure substring matching over the source text, with no assumption about its shape.
+ */
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { tasksDir } from './task-io.js';
+const CONTRACTS_FILE = 'contracts.md';
+/** Cap kept entries so the injected block stays bounded on a large design. */
+const MAX_CONTRACTS = 40;
+/** A single contract entry is one line; longer is prose, not a pinned fact. */
+const MAX_CONTRACT_LENGTH = 300;
+/** A quote shorter than this is too generic to anchor a contract (and to match). */
+const MIN_QUOTE_LENGTH = 6;
+export function contractsFile(cwd) {
+    return path.join(tasksDir(cwd), CONTRACTS_FILE);
+}
+/** The stored registry text ('' when none recorded yet). */
+export async function readContracts(cwd) {
+    try {
+        return (await fsp.readFile(contractsFile(cwd), 'utf8')).trim();
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Normalise for substring matching: collapse all whitespace runs to one space and
+ * lowercase. Quoting across a line wrap or with reflowed spacing still matches the
+ * source; casing differences do not defeat the anti-synthesis guard.
+ */
+function normalise(s) {
+    return s.replace(/\s+/g, ' ').trim().toLowerCase();
+}
+/**
+ * Parse `CONTRACT:` lines out of a child's answer text into entries. The line shape
+ * the extraction prompt asks for is:
+ *   CONTRACT: "<verbatim quote>" [anchor: <where>]
+ * The quote (between the first pair of double quotes) is the pinned fact; the
+ * optional `[anchor: …]` trailer records provenance. A line without a quoted span
+ * is skipped — an unquoted "contract" is a summary, which this registry rejects.
+ */
+export function parseContractLines(text) {
+    const entries = [];
+    for (const m of text.matchAll(/^[ \t]*CONTRACT:[ \t]*(.+)$/gim)) {
+        const body = m[1].trim();
+        const q = /"([^"]+)"/.exec(body);
+        if (!q)
+            continue;
+        const quote = q[1].trim();
+        if (quote.length < MIN_QUOTE_LENGTH || quote.length > MAX_CONTRACT_LENGTH)
+            continue;
+        const a = /\[anchor:\s*([^\]]+)\]/i.exec(body);
+        entries.push({ quote, anchor: a ? a[1].trim() : '' });
+    }
+    return entries;
+}
+/**
+ * THE ANTI-SYNTHESIS GUARD (the F3 defense): keep only entries whose quote actually
+ * appears in the source document. A paraphrase or fabrication is not a substring of
+ * the doc, so it is dropped — the registry cannot be poisoned with a synthesized
+ * contract. Matching is whitespace-insensitive and case-insensitive so a faithful
+ * quote across a line wrap still counts. Deduplicated (case-insensitive on the quote).
+ */
+export function keepGroundedContracts(entries, sourceDoc) {
+    const haystack = normalise(sourceDoc);
+    const seen = new Set();
+    const kept = [];
+    for (const e of entries) {
+        const key = normalise(e.quote);
+        if (key.length === 0 || seen.has(key))
+            continue;
+        if (!haystack.includes(key))
+            continue; // fabricated / paraphrased ⇒ reject
+        seen.add(key);
+        kept.push(e);
+    }
+    return kept;
+}
+/** Render one entry as a stored/displayed line. */
+function formatEntry(e) {
+    return e.anchor ? `"${e.quote}" [anchor: ${e.anchor}]` : `"${e.quote}"`;
+}
+/**
+ * Append grounded entries to the registry, deduplicated (case-insensitive on the
+ * quote) against what is already stored, keeping the newest MAX_CONTRACTS. Failures
+ * are swallowed — the registry is a sharpener, never a blocker.
+ */
+export async function appendContracts(cwd, entries) {
+    if (entries.length === 0)
+        return;
+    try {
+        const existingLines = (await readContracts(cwd))
+            .split('\n')
+            .filter(l => l.trim().length > 0);
+        const seen = new Set(existingLines.map(l => {
+            const q = /"([^"]+)"/.exec(l);
+            return normalise(q ? q[1] : l);
+        }));
+        const merged = [...existingLines];
+        for (const e of entries) {
+            const key = normalise(e.quote);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            merged.push(formatEntry(e));
+        }
+        const kept = merged.slice(-MAX_CONTRACTS);
+        await fsp.mkdir(tasksDir(cwd), { recursive: true });
+        await fsp.writeFile(contractsFile(cwd), kept.join('\n') + '\n', 'utf8');
+    }
+    catch {
+        // best-effort registry
+    }
+}
+/**
+ * The read-only prompt block a downstream slice (refine/compose) receives when the
+ * registry is non-empty. It is authoritative: these are the pinned cross-slice
+ * contracts from the SOURCE doc, and a slice must not restate them differently.
+ */
+export function buildContractsBlock(contracts) {
+    if (contracts.trim().length === 0)
+        return '';
+    return [
+        'CROSS-SLICE CONTRACTS — interface facts the SOURCE design pins and that more than',
+        'one task touches (endpoint paths, exported signatures, file layouts, env var names).',
+        'Each is a VERBATIM quote from the design; treat them as AUTHORITATIVE and BINDING:',
+        ...contracts
+            .trim()
+            .split('\n')
+            .map(l => `- ${l}`),
+        'Your slice MUST match these exactly at its boundary. Do NOT invent, rename, reshape,',
+        'or "tidy" a path/signature/layout/name that appears here — a difference between what',
+        'your slice emits and a contract above is a SEAM BUG, even if your slice is internally',
+        'consistent. If the design is silent on a boundary detail, leave it unspecified rather',
+        'than fabricating a specific — do not add contracts of your own.',
+        ''
+    ].join('\n');
+}
+/**
+ * The block the VERIFY child receives: the same registry, plus the mandate to check
+ * the slice's actual boundary against it (F3 is a seam bug — locally right, globally
+ * wrong — so per-slice verification must look at the boundary, not just the interior).
+ */
+export function buildContractsVerifyBlock(contracts) {
+    if (contracts.trim().length === 0)
+        return '';
+    return [
+        'CROSS-SLICE CONTRACTS (verbatim from the source design; authoritative):',
+        ...contracts
+            .trim()
+            .split('\n')
+            .map(l => `- ${l}`),
+        'These are boundaries MULTIPLE slices share. Check the shipped work at its boundary',
+        'against them: does the code this task produced use each path/signature/layout/name',
+        'EXACTLY as quoted? A slice that is internally consistent but wires a boundary',
+        'differently from a contract above is a SEAM BUG — report FAIL naming the mismatch',
+        '(what the code uses vs what the contract pins). Matching every contract it touches',
+        'is part of the bar, not an extra.',
+        ''
+    ].join('\n');
+}
+/**
+ * The full decompose-time extraction prompt: the design and the just-decomposed
+ * task titles (so the child can judge which facts a boundary is SHARED on), plus
+ * the emit instruction. Runs with --no-tools — pure extraction over text in hand.
+ * The host re-grounds every emitted quote against the design (keepGroundedContracts),
+ * so a hallucinated contract cannot survive even if the child fabricates one here.
+ */
+export const CONTRACT_EXTRACT_PROMPT = (feature, titles) => [
+    'You are recording the CROSS-SLICE INTERFACE CONTRACTS for a feature that has just',
+    'been split into the task list below. Each task will later be implemented by a',
+    'SEPARATE pipeline that sees only its own title — so any interface fact TWO OR MORE',
+    'of these tasks must agree on (a shared endpoint path, an exported signature, a file',
+    'or module layout, an env var name, a wire/disk format) has to be pinned ONCE here,',
+    'exactly as the design states it, or the slices will drift apart at the seam.',
+    '',
+    'TASK LIST (the slices that will share these boundaries):',
+    ...titles.map((t, i) => `${i + 1}. ${t}`),
+    '',
+    'DESIGN (the ONLY source of truth — quote from it, never from your own knowledge):',
+    feature.trim(),
+    '',
+    CONTRACT_EMIT_INSTRUCTION,
+    '',
+    'Output the CONTRACT: lines and nothing else. If the design pins no shared boundary,',
+    'output nothing.'
+].join('\n');
+/** The emit instruction for the decompose-time extraction child. */
+export const CONTRACT_EMIT_INSTRUCTION = [
+    'CROSS-SLICE CONTRACTS — extract the interface facts that MORE THAN ONE task above will',
+    'touch and that the design PINS: endpoint paths and methods, exported function/type',
+    'signatures, file/module layout, env var names, on-disk or wire formats. For each, emit',
+    '  CONTRACT: "<verbatim quote copied EXACTLY from the design>" [anchor: <section/header>]',
+    'one per line. RULES: (1) the quoted text MUST be copied verbatim from the design — do',
+    'NOT paraphrase, summarise, normalise, or complete it; a quote that is not a literal',
+    'substring of the design is DISCARDED. (2) Only facts a boundary is shared on — skip',
+    'anything a single task fully owns. (3) If the design does not pin a detail, do NOT invent',
+    'one. Quotes only; never your own synthesis — a fabricated contract is exactly the bug',
+    'this registry exists to prevent.'
+].join('\n');

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;