@mjasnikovs/pi-task 0.18.1 → 0.18.3

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.
@@ -45,6 +46,32 @@ function coverageRepromptHint(missing) {
         + 'task your previous list already had (reworded freely) PLUS tasks covering '
         + 'the areas above. Output every task, one "- [ ] " line each, nothing else.]');
 }
+// Deterministic distrust floor for the coverage gate. The gate's judge is the
+// same stochastic model as the decompose call it guards, and live (mx5 2026-07-08,
+// A/B N=10) it rubber-stamps a 1-task plan for an 18KB spec 3/10 times — always
+// as the bare "COVERAGE: COMPLETE" line, which is byte-identical to a legitimate
+// verdict, so the rubber-stamp is NOT detectable from the judge's output. The
+// distrust signal must come from the input: a plan this small for a spec this
+// large is near-certainly the known degenerate-decompose flake (healthy runs on
+// the same inputs produce 10–30 titles). The floor only ever forces a REGENERATION
+// — it never rejects a plan on count alone (the v0.13.34 objection), so a model
+// that insists twice still ships its small plan, with a warning.
+const SUSPECT_PLAN_MAX_TITLES = 2;
+const SUSPECT_PLAN_MIN_SPEC_CHARS = 4000;
+function isSuspectPlan(titles, featureForModel) {
+    return (titles.length > 0
+        && titles.length <= SUSPECT_PLAN_MAX_TITLES
+        && featureForModel.length >= SUSPECT_PLAN_MIN_SPEC_CHARS);
+}
+/** Reprompt prefix for a suspect (degenerate-count) list; unlike
+ *  coverageRepromptHint there is no judge verdict yet, so no missing areas. */
+function suspectPlanHint(count) {
+    return (`[SYSTEM NOTE: Your previous answer contained only ${count} task(s), which `
+        + 'cannot decompose a feature specification of this size — it was almost '
+        + 'certainly an incomplete generation. Regenerate the FULL ordered checkbox '
+        + 'list for the ENTIRE feature, covering every part of the spec end to end. '
+        + 'Output every task, one "- [ ] " line each, nothing else.]');
+}
 // Matches pi's @-file completion token (a path after @, until whitespace).
 const MENTION_RE = /(?:^|\s)@([^\s]+)/g;
 // Trailing punctuation a user naturally types AFTER an @-mention when it sits in
@@ -411,6 +438,20 @@ export async function planAuto(ctx, cwd, feature, deps) {
     const listRaw = await deps.runChild('auto-decompose', 'read', decomposePrompt);
     let planTitles = parseDecomposeList(listRaw);
     logPlanDebug(cwd, `decompose produced ${planTitles.length} title(s)`);
+    // Distrust floor (see isSuspectPlan): a ≤2-title plan for a multi-KB spec is
+    // regenerated once BEFORE the judge runs — the judge cannot be trusted to
+    // catch it (3/10 live false-pass) and a hinted retry heals it reliably
+    // (5/5 live). Longer list wins; a still-suspect plan falls through to the
+    // judge loop as before, so this never blocks planning.
+    if (isSuspectPlan(planTitles, featureForModel)) {
+        logPlanDebug(cwd, `decompose suspect (${planTitles.length} title(s) for a ${featureForModel.length}-char spec)`
+            + ` — raw output: ${listRaw.trim().slice(0, 300)}`);
+        const retryRaw = await deps.runChild('auto-decompose', 'read', prependHint(suspectPlanHint(planTitles.length), decomposePrompt));
+        const retryTitles = parseDecomposeList(retryRaw);
+        logPlanDebug(cwd, `decompose suspect-retry produced ${retryTitles.length} title(s)`);
+        if (retryTitles.length > planTitles.length)
+            planTitles = retryTitles;
+    }
     // Coverage gate: a stochastic degenerate completion (live mx5: ONE task +
     // natural EOS for an 18KB design doc) is nonempty, so the length guard below
     // never fires and the whole run "completes" after one task. Judge the list
@@ -442,6 +483,14 @@ export async function planAuto(ctx, cwd, feature, deps) {
             unresolvedMissing = null;
             logPlanDebug(cwd, `decompose-coverage round ${round + 1}: `
                 + (verdict === null ? 'no verdict — accepting list' : 'COMPLETE'));
+            // A COMPLETE on a still-suspect plan is the judge's known live
+            // false-pass mode (bare verdict, indistinguishable from a real one).
+            // The plan still ships — the floor never rejects on count — but
+            // never silently: the user decides whether to trust it.
+            if (isSuspectPlan(planTitles, featureForModel)) {
+                ctx.ui.notify(`/task-auto: only ${planTitles.length} task(s) planned for a large spec`
+                    + ' and the regeneration did not grow the list — review the plan before running.', 'warning');
+            }
             break;
         }
         unresolvedMissing = verdict.missing;
@@ -465,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.
@@ -492,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/gate-deps.js

@@ -20,6 +20,7 @@ import { gitCommitAll, gitDropLastCommit, git } from './auto-commit.js';
 import { runGuidelineEnforcement, classifyEnforceChildFailure } from './enforce-guidelines.js';
 import { runWorkVerification, extractSpecForVerification } from './verify-work.js';
 import { readEnvNotes, appendEnvNotes } from './env-notes.js';
+import { readContracts } from './contracts.js';
 import { runRepoHealthCheck } from './repo-health-check.js';
 import { runFinalIntegrationGate, discoverGateCommandLabels } from './final-gate.js';
 import { runFinalGateAutofix } from './final-gate-fix.js';
@@ -314,7 +315,13 @@ export function buildGateDeps(params) {
                 envNotes: {
                     read: () => readEnvNotes(cwd2),
                     append: notes => appendEnvNotes(cwd2, notes)
-                }
+                },
+                // Per-run cross-slice contract registry under .pi-tasks/ (F3): the
+                // verbatim interface facts the design pins that multiple slices
+                // share, so the verify child checks this slice's boundary against
+                // them. Empty on single-`/task` runs or a design with no shared
+                // boundary → no block.
+                contracts: () => readContracts(cwd2)
             });
         },
         lintFix: (fixCtx, cwd2, taskTitle, failReason) => runBoundedLintFix({

package/dist/task/phases.d.ts

@@ -50,6 +50,14 @@ export declare function replaceToolingWithVerified(research: string, verifiedCom
  * a genuinely greenfield task is still free to create.
  */
 export declare function refineExistingFilesBlock(deps: PhaseDeps): Promise<string>;
+/**
+ * The read-only cross-slice contract block (see contracts.ts) for a phase that
+ * generates spec text — the verbatim interface facts the SOURCE design pins that
+ * more than one slice touches. Empty when the registry is absent/empty (single
+ * `/task` runs, or a design that pins no shared boundary), so this degrades to a
+ * no-op. Best-effort: a read fault yields '' rather than blocking the phase.
+ */
+export declare function phaseContractsBlock(deps: PhaseDeps): Promise<string>;
 export declare const phaseRefine: (deps: PhaseDeps, raw: string, planContext?: string) => Promise<string>;
 export declare function phaseVerifyTooling(deps: PhaseDeps, research: string): Promise<string>;
 export interface PhaseResearchDeps extends ExternalContextDeps {

package/dist/task/phases.js

@@ -24,6 +24,9 @@ import { isDuplicateQuestion, MAX_DUP_STRIKES, DUP_REPROMPT_HINT } from './quest
 import { parseGrillQuestions, parseAutoAnswer, autoAnswerHasTag, parseVerifyToolingOutput, deriveTitle } from './parsers.js';
 import { compressTitle } from './title-label.js';
 import { parseVerifyBlock, validateSpecShape, stripSpecPreamble, isCritiqueClean } from './spec-validation.js';
+import { findSkipEscapes, skipEscapeDefectText } from './skip-escape.js';
+import { findSynthesizedWiring, wiringProbeText, readReferencedDocs } from './wiring-claims.js';
+import { readContracts, buildContractsBlock, buildContractsVerifyBlock } from './contracts.js';
 import { runPhaseChild, runPhaseWithLoopGuard, runWithEmphasisRetry, prependHint, USER_CANCELLED } from './child-runner.js';
 import { SessionUI } from '../remote/bridge.js';
 // ─── Re-export constants from their home modules ────────────────────────────
@@ -112,9 +115,21 @@ export async function refineExistingFilesBlock(deps) {
     });
     return block.trim().length === 0 ? '' : `${REFINE_PRESERVE_DIRECTIVE}\n\n${block.trim()}`;
 }
+/**
+ * The read-only cross-slice contract block (see contracts.ts) for a phase that
+ * generates spec text — the verbatim interface facts the SOURCE design pins that
+ * more than one slice touches. Empty when the registry is absent/empty (single
+ * `/task` runs, or a design that pins no shared boundary), so this degrades to a
+ * no-op. Best-effort: a read fault yields '' rather than blocking the phase.
+ */
+export async function phaseContractsBlock(deps) {
+    const contracts = await readContracts(deps.cwd).catch(() => '');
+    return buildContractsBlock(contracts);
+}
 export const phaseRefine = async (deps, raw, planContext) => {
     const existingFiles = await refineExistingFilesBlock(deps).catch(() => '');
-    return runPhaseWithLoopGuard(deps, 'refine', 'read', hint => prependHint(hint, appendNoThink(REFINE_PROMPT(raw, planContext, existingFiles))), 
+    const contracts = await phaseContractsBlock(deps);
+    return runPhaseWithLoopGuard(deps, 'refine', 'read', hint => prependHint(hint, appendNoThink(REFINE_PROMPT(raw, planContext, existingFiles, contracts))), 
     // refine's deliverable is a 4-section text rewrite that never strictly
     // needs a successful read — on a test-writing task against a large
     // existing codebase the model over-explores (re-reads source hunting for
@@ -714,7 +729,8 @@ export async function phaseGrill(deps, ctx, widgetState, refined, research) {
     return out.join('\n');
 }
 export async function phaseCompose(deps, refined, research, qa) {
-    return runWithEmphasisRetry(deps, 'compose', 'read', problem => COMPOSE_PROMPT(refined, research, qa, problem), text => {
+    const contracts = await phaseContractsBlock(deps);
+    return runWithEmphasisRetry(deps, 'compose', 'read', problem => COMPOSE_PROMPT(refined, research, qa, problem, contracts), text => {
         // Trim any "here's the spec:" preamble before validating, so a
         // strippable lead-in doesn't burn a full retry — and the stored
         // value starts at GOAL.
@@ -747,6 +763,35 @@ export async function phaseCritique(deps, spec, refined, qa) {
     // When the draft is structurally sound and triage says CLEAN, return it as
     // is. Otherwise fall through to the rewrite, feeding the triage defects in
     // as a focus list. Triage failures are non-fatal — we just do the rewrite.
+    // DETERMINISTIC skip-escape gate (run-8 F2): a required VERIFY check wrapped in a
+    // skip-announcing `||` fallback (`… || echo "skipping (tool absent)"`) lets the
+    // check pass while never running. FP-measured 0/20 on the historical specs. When
+    // present, force the rewrite to strip it — never let the triage CLEAN short-circuit
+    // ship a self-waiving VERIFY block — and feed the offending lines in as defects.
+    const skipEscapes = findSkipEscapes(spec);
+    const skipDefects = skipEscapes.length > 0 ? skipEscapeDefectText(skipEscapes) : null;
+    // The cross-slice contract registry (run-8 F3): the design's pinned interface
+    // facts, quoted verbatim, that more than one slice touches. Threading them into
+    // critique lets the triage/rewrite RECONCILE a synthesized wiring specific (a
+    // fabricated uniform mount table) against the facts it must reproduce — the
+    // generation-side complement of the verify-side boundary check. Empty (single
+    // /task, or a design that pins no shared boundary) ⇒ no-op.
+    const registryRaw = await readContracts(deps.cwd).catch(() => '');
+    const contractsBlock = buildContractsVerifyBlock(registryRaw);
+    // DETERMINISTIC synthesized-wiring probe (run-8 F3, generation side). The registry
+    // alone is a WEAK catcher (live A/B: prompt+registry ~1/8) — the model's attention
+    // goes to the obvious VERIFY weakness and it rarely does the path-composition
+    // reasoning. The scanner NAMES the inferred mount mappings and juxtaposes the
+    // verbatim pinned facts, forcing focused reconciliation (probe+rule pattern, same
+    // lever as skip-escape / substitution-probe). FP-clean (1/18 files on the run-8
+    // trees). Grounding = the registry ∪ any design doc the spec/refined @-reference.
+    const wiring = registryRaw.trim().length > 0 ?
+        findSynthesizedWiring(spec, registryRaw + '\n' + readReferencedDocs(deps.cwd, refined, spec), registryRaw)
+        : [];
+    const wiringProbe = wiring.length > 0 ? wiringProbeText(wiring, registryRaw) : null;
+    if (wiringProbe) {
+        deps.logDebug?.(`synthesized wiring flagged in spec: ${wiring.map(w => w.line).join(' | ')}`);
+    }
     let triageDefects = null;
     if (parseVerifyBlock(spec) !== null) {
         const tTriage = Date.now();
@@ -756,21 +801,31 @@ export async function phaseCritique(deps, spec, refined, qa) {
             // Granting `read` here let it wander the repo to "verify" findings,
             // which made the supposedly-cheap pass cost as much as a rewrite
             // (observed ~133s). The judgement needs no file access.
-            verdict = await runPhaseChild(deps, 'critique-triage', '', appendNoThink(CRITIQUE_TRIAGE_PROMPT(spec, refined, qa)));
+            verdict = await runPhaseChild(deps, 'critique-triage', '', appendNoThink(CRITIQUE_TRIAGE_PROMPT(spec, refined, qa, contractsBlock)));
         }
         catch {
             verdict = null;
         }
         deps.recordSubStep?.('triage', Date.now() - tTriage);
         if (verdict !== null) {
-            if (isCritiqueClean(verdict))
-                return spec;
-            triageDefects = verdict.trim();
+            // A deterministic skip-escape OR synthesized-wiring finding overrides a CLEAN
+            // triage: the draft must be rewritten to resolve it even if the model judged
+            // the rest clean (the model does not self-discover either reliably).
+            if (isCritiqueClean(verdict)) {
+                if (skipDefects === null && wiringProbe === null)
+                    return spec;
+            }
+            else {
+                triageDefects = verdict.trim();
+            }
         }
     }
+    // Merge the deterministic skip-escape + synthesized-wiring defects with any triage
+    // defects for the rewrite (both are forced FOCUS items).
+    const rewriteDefects = [skipDefects, wiringProbe, triageDefects].filter(Boolean).join('\n\n') || null;
     const tRewrite = Date.now();
     try {
-        return await runWithEmphasisRetry(deps, 'critique', 'read', problem => CRITIQUE_PROMPT(spec, refined, qa, problem !== null, triageDefects), text => {
+        return await runWithEmphasisRetry(deps, 'critique', 'read', problem => CRITIQUE_PROMPT(spec, refined, qa, problem !== null, rewriteDefects, contractsBlock), text => {
             // The rewrite (thinking on) sometimes prepends narration before
             // GOAL; the prompt forbids it but this validator only checks for
             // a VERIFY block. Strip it so the delivered spec starts at GOAL.

package/dist/task/prompts.d.ts

@@ -47,7 +47,7 @@ export declare const COMPRESS_LABEL_PROMPT: (title: string, maxChars: number) =>
  * "Scaffold …" title re-expands the entire design into one task (validated: a real
  * /task-auto run implemented all 24 steps under step 1).
  */
-declare const REFINE_PROMPT: (raw: string, planContext?: string, existingFiles?: string) => string;
+declare const REFINE_PROMPT: (raw: string, planContext?: string, existingFiles?: string, contracts?: string) => string;
 declare const RESEARCH_READ_ONLY_CONSTRAINT = "IMPORTANT: You are ONLY allowed to READ. Do NOT create, modify, or delete any files. Use the read, grep, find, and ls tools to inspect the repo.";
 declare const RESEARCH_FILES_PROMPT: (refined: string) => string;
 declare const RESEARCH_APIS_PROMPT: (refined: string, filesMap?: string) => string;
@@ -57,8 +57,8 @@ declare const GRILL_GEN_PROMPT: (refined: string, research: string, priorQA: str
 declare const GRILL_AUTO_ANSWER_PROMPT: (refined: string, research: string, question: string) => string;
 export declare const GRILL_AUTO_FORMAT_HINT: string;
 declare function composeRetryEmphasis(problem: string): string;
-declare const COMPOSE_PROMPT: (refined: string, research: string, qa: string, retryProblem: string | null) => string;
-declare const CRITIQUE_TRIAGE_PROMPT: (spec: string, refined: string, qa: string) => string;
-declare const CRITIQUE_PROMPT: (spec: string, refined: string, qa: string, addVerifyEmphasis: boolean, triageDefects?: string | null) => string;
+declare const COMPOSE_PROMPT: (refined: string, research: string, qa: string, retryProblem: string | null, contracts?: string) => string;
+declare const CRITIQUE_TRIAGE_PROMPT: (spec: string, refined: string, qa: string, contracts?: string) => string;
+declare const CRITIQUE_PROMPT: (spec: string, refined: string, qa: string, addVerifyEmphasis: boolean, triageDefects?: string | null, contracts?: string) => string;
 declare const VERIFY_TOOLING_PROMPT: (tooling: string) => string;
 export { REFINE_PROMPT, RESEARCH_FILES_PROMPT, RESEARCH_APIS_PROMPT, RESEARCH_CONTEXT_PROMPT, RESEARCH_TOOLING_PROMPT, RESEARCH_READ_ONLY_CONSTRAINT, GRILL_GEN_PROMPT, GRILL_AUTO_ANSWER_PROMPT, COMPOSE_PROMPT, CRITIQUE_PROMPT, CRITIQUE_TRIAGE_PROMPT, VERIFY_TOOLING_PROMPT, composeRetryEmphasis };