@mjasnikovs/pi-task 0.18.2 → 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.
@@ -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/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 };

package/dist/task/prompts.js

@@ -61,7 +61,7 @@ ${title}`;
  * "Scaffold …" title re-expands the entire design into one task (validated: a real
  * /task-auto run implemented all 24 steps under step 1).
  */
-const REFINE_PROMPT = (raw, planContext, existingFiles) => `${planContext ? planContext + '\n\n---\n\n' : ''}You receive a user's task description for an AI coding agent. Rewrite it to be unambiguous and actionable.
+const REFINE_PROMPT = (raw, planContext, existingFiles, contracts) => `${planContext ? planContext + '\n\n---\n\n' : ''}You receive a user's task description for an AI coding agent. Rewrite it to be unambiguous and actionable.
 
 Output structure (four sections, exact headings, in this order):
 
@@ -86,8 +86,9 @@ Rules:
 - Preserve every concrete identifier verbatim (paths, function names, ports, env vars, file:line refs).
 - Do not invent requirements not implied by the input.
 - If the task references a design/spec document (an @-path or a named spec file), READ it and treat it as authoritative. Carry its concrete schema verbatim into GOAL/CONSTRAINTS — table and column names, types, endpoint methods and paths, enum values. The task title is only a pointer into that spec: where the title and the spec disagree, follow the spec, and never introduce a table, column, endpoint, or dependency the spec does not define.
+- CITE interface WIRING, do NOT synthesize it. A wiring specific — how modules/endpoints/files connect (a mount prefix, a route/mount table, a module→path mapping, an exported function/type signature, a file or module layout) — must be citable from the design or the CROSS-SLICE CONTRACTS. The design often pins the interface FACTS (the exact endpoint paths, exported names, layouts) WITHOUT stating the wiring that produces them; when it does, any wiring you write MUST reproduce those pinned facts EXACTLY. Do NOT infer a "uniform" or "tidy" pattern from them — e.g. do not assume one module maps to one mount prefix when the design's pinned facts for that module do not all sit under a single prefix (that exact inference is a seam bug: the consumers follow the pinned facts, the assembly follows your invented pattern, and the seam ships broken). If the design pins neither the fact nor the wiring, leave the detail unspecified rather than inventing a specific.
 - Do not output any preamble, commentary, or markdown headings beyond the four sections above.
-${existingFiles && existingFiles.trim() ? `\n${existingFiles.trim()}\n` : ''}
+${contracts && contracts.trim() ? `\n${contracts.trim()}\n` : ''}${existingFiles && existingFiles.trim() ? `\n${existingFiles.trim()}\n` : ''}
 Task: ${raw}`;
 // ─── Research fan-out prompts ─────────────────────────────────────────────────
 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.`;
@@ -288,7 +289,7 @@ function composeRetryEmphasis(problem) {
     }
     return `\nPREVIOUS ATTEMPT was invalid (${problem}). Ensure all four sections are present and the output starts with the literal word GOAL.\n`;
 }
-const COMPOSE_PROMPT = (refined, research, qa, retryProblem) => `You are composing the final implementation spec for an AI coding agent. Combine the refined task, the research, and the user's Q&A answers into one spec.
+const COMPOSE_PROMPT = (refined, research, qa, retryProblem, contracts) => `You are composing the final implementation spec for an AI coding agent. Combine the refined task, the research, and the user's Q&A answers into one spec.
 
 CRITICAL FORMAT RULES (read first):
 - Output the spec as plain markdown text. Do NOT wrap your entire output in a code block, shell fence, or heredoc. Do NOT prefix with \`\`\`sh / \`\`\`bash. Do NOT use \`cat << EOF > file\` patterns. Your response begins literally with "GOAL" on the first line.
@@ -334,14 +335,15 @@ Research:
 ${research}
 
 User Q&A:
-${qa}`;
+${qa}
+${contracts && contracts.trim() ? `\n${contracts.trim()}\n` : ''}`;
 // Fast triage pass run before the (expensive) full rewrite. It produces either
 // the single token CLEAN — meaning the compose draft needs no rewrite — or a
 // short defect list. When CLEAN, the orchestrator returns the draft unchanged
 // and skips the rewrite entirely; otherwise the defects are fed into
 // CRITIQUE_PROMPT as a focus list so the rewrite targets real problems instead
 // of re-deriving them from scratch.
-const CRITIQUE_TRIAGE_PROMPT = (spec, refined, qa) => `You are triaging an implementation spec for an AI coding agent. Decide whether it needs a rewrite. Do NOT rewrite it — only judge it.
+const CRITIQUE_TRIAGE_PROMPT = (spec, refined, qa, contracts) => `You are triaging an implementation spec for an AI coding agent. Decide whether it needs a rewrite. Do NOT rewrite it — only judge it.
 
 The refined task and the user's Q&A below are GROUND TRUTH. Judge the spec against them. Look for SUBSTANTIVE defects only:
 - ambiguity that would let the agent build the wrong thing
@@ -349,7 +351,8 @@ The refined task and the user's Q&A below are GROUND TRUTH. Judge the spec again
 - a VERIFY block that is missing, unrunnable, full of placeholders, or does not exercise the surface the task touches
 - scope drift: requirements, files, or deliverables not implied by the refined task or Q&A
 - a dropped or weakened CONSTRAINT from the refined task
-
+- a synthesized interface WIRING specific — a mount/route table, a module→path mapping, an exported signature, a file layout — that the design does not pin AND that does not reproduce the design's pinned interface facts. A "uniform" pattern (one module → one mount prefix, etc.) applied to an interface whose pinned facts are NOT uniform is a SEAM BUG: flag it naming the pinned fact it contradicts.
+${contracts && contracts.trim() ? `\n${contracts.trim()}\n` : ''}
 Do NOT flag cosmetic wording, style, or anything you would change only to "polish" prose. The bar is: would this defect change what the agent builds or whether the work can be verified?
 
 Output format — read carefully:
@@ -364,7 +367,7 @@ ${qa}
 
 Spec to triage:
 ${spec}`;
-const CRITIQUE_PROMPT = (spec, refined, qa, addVerifyEmphasis, triageDefects = null) => `You are reviewing the implementation spec below for ambiguity, weak acceptance criteria, and missing or unrunnable VERIFY commands.
+const CRITIQUE_PROMPT = (spec, refined, qa, addVerifyEmphasis, triageDefects = null, contracts) => `You are reviewing the implementation spec below for ambiguity, weak acceptance criteria, and missing or unrunnable VERIFY commands.
 
 CRITICAL FORMAT RULES (read first):
 - Output the rewritten spec as plain markdown. Do NOT wrap your entire output in a code block, shell fence, or heredoc. Do NOT prefix with \`\`\`sh / \`\`\`bash. Do NOT use \`cat << EOF > file\` patterns. Your response begins literally with "GOAL" on the first line.
@@ -378,6 +381,7 @@ SCOPE RULES (equally critical — do not break these):
 - CONSTRAINTS from the refined task MUST be preserved in spirit. Do not silently drop or weaken them.
 - If the spec below is malformed, empty, or wrapped in a heredoc, reconstruct it from the refined task and Q&A — not from your own invention.
 - Your job is to tighten language, sharpen acceptance criteria, and ensure VERIFY is runnable. Not to redesign the task.
+- WIRING vs pinned facts: if the spec states interface wiring (a mount/route table, a module→path mapping, an exported signature, a file layout), reconcile EACH wiring specific against the design's pinned interface facts (the CROSS-SLICE CONTRACTS below, if present, are those facts quoted verbatim). Keep every wiring specific that reproduces the pinned facts exactly; CORRECT any that do not; and do NOT invent wiring the design leaves unspecified. Watch specifically for a "uniform" pattern (one module → one mount prefix, one naming scheme) applied to an interface whose pinned facts are NOT uniform — that is a seam bug, fix only the entry that breaks, and leave the conforming entries unchanged.
 
 Rewrite the spec in the same four-section format (GOAL, CONSTRAINTS, ACCEPTANCE, VERIFY). Fix any issues you find within the scope rules above.
 
@@ -390,6 +394,7 @@ VERIFY QUALITY CHECK (apply during the rewrite):
 - Never accept \`true\`, \`echo ok\`, or other no-op commands as VERIFY content.
 
 ${addVerifyEmphasis ? 'REQUIRED: The output MUST include a VERIFY: section followed by a ```sh fenced block of runnable shell commands. The previous attempt was missing this.' : ''}
+${contracts && contracts.trim() ? `\n${contracts.trim()}\n` : ''}
 ${triageDefects ?
     `FOCUS — a triage pass already found these specific defects. Fix every one of them in your rewrite (without breaking the scope rules above):\n${triageDefects}\n`
     : ''}

package/dist/task/skip-escape.d.ts

@@ -0,0 +1,25 @@
+export interface SkipEscapeFinding {
+    /** The offending VERIFY command line, verbatim. */
+    line: string;
+    /** Why it is a skip-escape (human- and prompt-readable). */
+    reason: string;
+}
+/**
+ * Scan a composed spec's VERIFY block for skip-announcing escapes. Returns one
+ * finding per offending command line; empty when the spec has no VERIFY block or
+ * no skip-escapes. Comment/blank lines are already dropped by parseVerifyBlock.
+ */
+export declare function findSkipEscapes(spec: string): SkipEscapeFinding[];
+/**
+ * Render skip-escape findings as a defect block for the critique rewrite: a
+ * numbered instruction list the rewrite must resolve (remove the escape / run the
+ * check unconditionally, or drop the check if it is genuinely not required).
+ */
+export declare function skipEscapeDefectText(findings: SkipEscapeFinding[]): string;
+/**
+ * Render skip-escape findings as verify-child prompt lines (the deterministic
+ * finding that makes rule 5c fire reliably — the model does not self-discover a
+ * graceful skip-escape, but acts on a finding that names the exact line). Empty
+ * findings → empty array (caller emits no block).
+ */
+export declare function skipEscapeVerifyFindings(findings: SkipEscapeFinding[]): string[];

package/dist/task/skip-escape.js

@@ -0,0 +1,80 @@
+/**
+ * Deterministic skip-escape scanner for authored VERIFY blocks (run-8 F2).
+ *
+ * A skip-escape is a `||` fallback that lets a REQUIRED check pass SILENTLY when
+ * its tool is absent or it fails — e.g. `playwright test … || echo "skipping"`.
+ * mx5 run-8 shipped a blank/dead app partly because its only behavioral smoke
+ * tests were wrapped this way: the tool was absent, the check silently skipped,
+ * and the verify child blessed it as "correctly skipped".
+ *
+ * FP-MEASURED on the historical VERIFY blocks (~/hub/mx5/.pi-tasks, 22 tasks): a
+ * blanket `|| true` flag is ~90% false positives — teardown (`kill … || true`,
+ * `docker compose down … || true`), setup (`… install … || true`), and negative
+ * tests (`… && exit 1 || true`, where `|| true` catches an EXPECTED failure). Of
+ * 45 `||` uses, exactly one was the real F2 skip-escape, and it ANNOUNCED the skip
+ * ("Playwright not available — skipping browser smoke test"). So the crisp,
+ * ~zero-FP signal is a fallback whose text ADMITS it is dodging the check — that is
+ * the actionable finding here. Bare `|| true` is left to the verify child's runtime
+ * rule 5c, which can actually observe whether the check ran (a static scan cannot
+ * tell a required-check `|| true` from a teardown `|| true`).
+ *
+ * Pure shell-shape / text analysis; no stack or tool-name assumptions.
+ */
+import { parseVerifyBlock } from './spec-validation.js';
+/**
+ * A `||` (optionally after a `2>/dev/null`) whose fallback text ADMITS it is
+ * skipping / that a tool is unavailable. Anchored on the fallback wording, so it
+ * fires on `|| echo "skipping"`, `|| { echo "playwright not installed"; }`,
+ * `|| echo "runner unavailable — skipped"`, and misses benign teardown `|| true`.
+ */
+const SKIP_ANNOUNCE_RE = /\|\|[^|]*\b(skip|skipping|skipped|not\s+installed|not\s+available|unavailable)\b/i;
+/**
+ * Scan a composed spec's VERIFY block for skip-announcing escapes. Returns one
+ * finding per offending command line; empty when the spec has no VERIFY block or
+ * no skip-escapes. Comment/blank lines are already dropped by parseVerifyBlock.
+ */
+export function findSkipEscapes(spec) {
+    const cmds = parseVerifyBlock(spec);
+    if (!cmds)
+        return [];
+    const found = [];
+    for (const { raw } of cmds) {
+        if (SKIP_ANNOUNCE_RE.test(raw)) {
+            found.push({
+                line: raw,
+                reason: 'its `||` fallback announces skipping the check when a tool is absent — a '
+                    + 'required check must run unconditionally, not self-waive into a silent pass'
+            });
+        }
+    }
+    return found;
+}
+/**
+ * Render skip-escape findings as a defect block for the critique rewrite: a
+ * numbered instruction list the rewrite must resolve (remove the escape / run the
+ * check unconditionally, or drop the check if it is genuinely not required).
+ */
+export function skipEscapeDefectText(findings) {
+    return [
+        'SKIP-ESCAPE in the VERIFY block — a required check is wrapped so that a missing',
+        'tool or a failure passes SILENTLY (run-8 F2: the only smoke tests shipped this',
+        'way, skipped unnoticed, and a blank app was blessed). Rewrite the VERIFY block so',
+        'each of these checks RUNS UNCONDITIONALLY and its failure fails the block — remove',
+        'the `|| echo skipping`-style fallback. PREFER a check that needs no special tool at',
+        'all (start the artifact and probe its real behavior directly). Do NOT merely reshape',
+        'the escape into a `command -v X`/`if`-guard that still skips silently when the tool',
+        'is absent — that is the same defect: if the check truly needs a tool, its absence',
+        'must make the block EXIT NON-ZERO (surface it), never exit 0. If a check genuinely',
+        'cannot be required here, remove it entirely rather than leaving a self-waiving stub:',
+        ...findings.map((f, i) => `  ${i + 1}. ${f.line}`)
+    ].join('\n');
+}
+/**
+ * Render skip-escape findings as verify-child prompt lines (the deterministic
+ * finding that makes rule 5c fire reliably — the model does not self-discover a
+ * graceful skip-escape, but acts on a finding that names the exact line). Empty
+ * findings → empty array (caller emits no block).
+ */
+export function skipEscapeVerifyFindings(findings) {
+    return findings.map(f => `${f.line} — ${f.reason}`);
+}

package/dist/task/task-gates.js

@@ -96,17 +96,29 @@ export async function runGatesForTask(ctxIn, deps, p) {
                     continue;
                 }
             }
-            const recOutcome = deps.recommend ?
-                await deps.recommend(active, p.cwd, p.title, p.taskId, failReason)
-                : { recommend: 'autofix', rationale: failReason };
-            await rec(`resolution: recommended ${recOutcome.recommend.toUpperCase()}`);
+            // UNOBSERVED (rule 5c): a spec-required behavioral check could not run because
+            // its observation tooling is absent. An unattended AUTOFIX re-run cannot install
+            // a missing tool, so it would only burn MAX_AUTO_AUTOFIX turns and re-FAIL — the
+            // decision (provision the tool, or accept the unproven behavior) is the human's.
+            // Skip the (moot) recommendation research and force the picker.
+            const isUnobserved = verified.unobserved === true;
+            const recOutcome = isUnobserved ? { recommend: 'autofix', rationale: failReason }
+                : deps.recommend ?
+                    await deps.recommend(active, p.cwd, p.title, p.taskId, failReason)
+                    : { recommend: 'autofix', rationale: failReason };
+            await rec(isUnobserved ?
+                'resolution: verify UNOBSERVED — spec-required check could not run (tooling absent); '
+                    + 'forcing the human picker, an unattended re-run cannot provision it'
+                : `resolution: recommended ${recOutcome.recommend.toUpperCase()}`);
             // AUTO-RESOLVE the AUTOFIX path: when the research says the work is
             // genuinely wrong, re-run the fix WITHOUT prompting the user. The picker is
             // reserved for the ACCEPT recommendation (the human decides whether to bless
             // an artifact the gate FAILed) and for the bounded fallback: after
             // MAX_AUTO_AUTOFIX consecutive unattended attempts that still FAIL, hand
             // control back so a person can break a non-converging loop.
-            const autoFixNow = recOutcome.recommend === 'autofix' && autoFixCount < MAX_AUTO_AUTOFIX;
+            const autoFixNow = !isUnobserved
+                && recOutcome.recommend === 'autofix'
+                && autoFixCount < MAX_AUTO_AUTOFIX;
             let choice;
             if (autoFixNow) {
                 autoFixCount += 1;

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

@@ -21,6 +21,12 @@ export interface VerifyOutcome {
     /** Short, human-readable reason. Always set when ok === false; on the pass
      *  path set to the no-op cause ('disabled', 'no spec to verify'). */
     reason?: string;
+    /** True when the FAIL is specifically an UNOBSERVED outcome (rule 5c): a
+     *  spec-required behavioral check could not run because its tooling is absent.
+     *  The gate routes this straight to the human picker instead of an unattended
+     *  AUTOFIX re-run, which cannot provision a missing tool. Only meaningful when
+     *  ok === false. */
+    unobserved?: boolean;
 }
 /**
  * Slice the delivered spec (GOAL / CONSTRAINTS / ACCEPTANCE / VERIFY) out of a
@@ -55,17 +61,24 @@ export declare function extractSpecForVerification(taskBody: string): string | n
  * Guard: honest-clean fixture (prohibition in spec, probe silent) 5/5 PASS — no
  * paranoia. Reverted-violation ≡ clean at the diff level (no entry → no finding).
  */
-export declare function buildVerifyPrompt(spec: string, probeFindings?: string[], envNotes?: string, prohibitionFindings?: string[]): string;
+export declare function buildVerifyPrompt(spec: string, probeFindings?: string[], envNotes?: string, prohibitionFindings?: string[], skipEscapeFindings?: string[], contracts?: string): string;
 /**
- * Parse the child's verdict. Scans for the LAST `WORK-VERIFIED: PASS|FAIL` marker
- * (the model discusses before concluding, and bash output may echo the word
+ * Parse the child's verdict. Scans for the LAST `WORK-VERIFIED: PASS|FAIL|UNOBSERVED`
+ * marker (the model discusses before concluding, and bash output may echo the word
  * "VERIFY", so a distinct token and last-match win matter).
  *
+ * UNOBSERVED (rule 5c) is a distinct third outcome: a spec-required behavioral check
+ * could not run because its observation tooling is absent, so the behavior is neither
+ * proven nor shown broken. It is NOT a pass (`pass: false`) but carries `unobserved`
+ * so the gate can route it straight to the human — an unattended AUTOFIX re-run cannot
+ * provision a missing tool, so it must never auto-loop on this.
+ *
  * No marker at all is NOT a pass: a verification that cannot state a verdict is a
  * gray area, and the contract is that unverified work is reported as such.
  */
 export declare function parseVerifyVerdict(text: string): {
     pass: boolean;
+    unobserved?: boolean;
     detail: string;
 };
 export interface VerificationDeps {
@@ -124,6 +137,14 @@ export interface VerificationDeps {
         read: () => Promise<string>;
         append: (notes: string[]) => Promise<void>;
     };
+    /**
+     * Per-run cross-slice contract registry (see contracts.ts): `read` supplies the
+     * verbatim interface facts the SOURCE design pins that more than one slice
+     * touches, injected so the verify child checks THIS slice's boundary against
+     * them (F3 seam bugs are locally right but globally wrong). ABSENT/empty → no
+     * block (single `/task` runs, or a design pinning no shared boundary), unchanged.
+     */
+    contracts?: () => Promise<string>;
 }
 /**
  * Run the verification pass for one task. A missing spec is a pass. Otherwise run

package/dist/task/verify-work.js

@@ -69,6 +69,8 @@
  */
 import { USER_CANCELLED } from './child-runner.js';
 import { buildEnvNotesBlock, ENV_NOTE_EMIT_INSTRUCTION, extractEnvNotes } from './env-notes.js';
+import { buildContractsVerifyBlock } from './contracts.js';
+import { findSkipEscapes, skipEscapeVerifyFindings } from './skip-escape.js';
 /**
  * The verification child gets exactly two tools: `read` and `bash`.
  *
@@ -137,7 +139,7 @@ export function extractSpecForVerification(taskBody) {
  * Guard: honest-clean fixture (prohibition in spec, probe silent) 5/5 PASS — no
  * paranoia. Reverted-violation ≡ clean at the diff level (no entry → no finding).
  */
-export function buildVerifyPrompt(spec, probeFindings, envNotes, prohibitionFindings) {
+export function buildVerifyPrompt(spec, probeFindings, envNotes, prohibitionFindings, skipEscapeFindings, contracts) {
     const probeBlock = probeFindings && probeFindings.length > 0 ?
         [
             'SELF-VERIFICATION NOTICE (deterministic, computed by the orchestrator from the diff):',
@@ -164,7 +166,23 @@ export function buildVerifyPrompt(spec, probeFindings, envNotes, prohibitionFind
             ''
         ]
         : [];
+    const skipEscapeBlock = skipEscapeFindings && skipEscapeFindings.length > 0 ?
+        [
+            "SKIP-ESCAPE NOTICE (deterministic, computed by the orchestrator from the spec's",
+            'OWN VERIFY block): these VERIFY commands wrap a required check in a fallback that',
+            'ANNOUNCES skipping it when a tool is absent — so the check can "pass" while never',
+            'actually running:',
+            ...skipEscapeFindings.map(f => `- ${f}`),
+            'Do NOT accept a skipped check as a passed check. For each, determine whether it',
+            'ACTUALLY ran and observed the real behavior. If its tool is absent so the required',
+            'behavior was never observed, that area is UNOBSERVED (rule 5c) — verdict UNOBSERVED,',
+            'not PASS. Only if you observe the required behavior another way (running the real',
+            'artifact directly) may it count as verified.',
+            ''
+        ]
+        : [];
     const envBlock = envNotes && envNotes.trim().length > 0 ? [buildEnvNotesBlock(envNotes)] : [];
+    const contractsBlock = contracts && contracts.trim().length > 0 ? [buildContractsVerifyBlock(contracts)] : [];
     return [
         'You are a strict verification pass running right after an AI coding agent',
         'finished a task and committed it. The agent is known to mark work "done"',
@@ -179,8 +197,10 @@ export function buildVerifyPrompt(spec, probeFindings, envNotes, prohibitionFind
         spec.trim(),
         '',
         ...envBlock,
+        ...contractsBlock,
         ...probeBlock,
         ...prohibitionBlock,
+        ...skipEscapeBlock,
         'How to verify — verify the REAL, shipped deliverable exactly as an unaided fresh',
         'checkout (or CI run) would experience it:',
         '',
@@ -242,6 +262,24 @@ export function buildVerifyPrompt(spec, probeFindings, envNotes, prohibitionFind
         '   server never starts, no entrypoint exists — that inability IS the defect:',
         '   report FAIL naming it. Do not stand up a substitute to get to green.',
         '',
+        '3e. NEGATIVE CONTROL IS MANDATORY — a success you cannot make fail is not evidence,',
+        '   and a check that only ever ran on the RIGHT input has not been shown to',
+        '   discriminate working from broken. For EACH behavioral check whose passing outcome',
+        '   you rely on (an endpoint returned success, a command exited 0, a call returned the',
+        '   expected value) you MUST also run that SAME check with one input deliberately',
+        '   wrong — a nonsense path, a bogus flag or subcommand, a malformed or absent',
+        '   argument, a target that does not exist — recreating whatever setup the check needs',
+        '   to do so (restart the server if a prior step killed it, re-invoke the command).',
+        '   Require a DIFFERENT, failing outcome from the wrong input. If the wrong input',
+        '   yields the SAME success (same status code, same body, same exit 0), the check',
+        '   cannot tell working from broken: it is VOID and the behavior it was meant to prove',
+        '   is UNVERIFIED — a FAIL naming the indiscriminate check (e.g. "a POST to a nonsense',
+        '   path returns the same 200 and body as the real endpoint, so the route is unproven',
+        '   — a catch-all fallback is masking it"). Skipping the control is not neutral: a',
+        '   required behavior left without a discriminating check is UNVERIFIED, and',
+        '   unverified is a FAIL, never a PASS. A wrong-input control exists for every',
+        '   artifact — HTTP request, CLI invocation, library call, schema load, config parse.',
+        '',
         '4. Treat the ACCEPTANCE criteria as the bar. If a command fails, or its real output',
         '   contradicts an ACCEPTANCE criterion, the work has NOT verified.',
         '',
@@ -282,8 +320,36 @@ export function buildVerifyPrompt(spec, probeFindings, envNotes, prohibitionFind
         '   that is a FAIL naming the gap. Any schema surgery you performed to reach green IS the',
         '   defect.',
         '',
-        '6. If the spec legitimately has no runnable verification (a pure docs / config change',
-        '   with nothing to build or run), validating it cleanly is a PASS.',
+        '5c. A SPEC-REQUIRED CHECK THAT DID NOT ACTUALLY RUN IS NOT VERIFIED. The env-gap',
+        '   exception (rule 5) covers ONLY a genuinely EXTERNAL service the finished product',
+        "   connects to (a database, an API host). It does NOT cover a check the SPEC's own",
+        "   VERIFY block authored to OBSERVE the deliverable's required behavior. If such a",
+        '   check did not actually execute — the tool or runner it needs is not installed, or',
+        '   the VERIFY line short-circuits ITSELF with a skip-escape (`|| true`, `|| echo',
+        '   skipping`, `2>/dev/null || exit 0`, `command -v X ||` …) so a missing tool passes',
+        '   silently — then that behavior was NEVER OBSERVED. A skipped check is not a passed',
+        '   check: you may not count the area as verified, and "correctly skipped" is NOT a',
+        "   PASS. Do not let the work's own skip-escape waive the work's own gate. When a",
+        '   REQUIRED behavior could not be observed because its observation tooling is absent,',
+        '   the verdict is UNOBSERVED — report exactly what could not be observed and which',
+        '   tool was missing, so a human decides whether to provision the tool or accept the',
+        '   unproven behavior.',
+        '   DISCRIMINATOR (rule 5 vs rule 5c) — when something needed is absent, ask which it',
+        '   is: (rule 5, env-gap, do NOT fail the code) a SERVICE the FINISHED PRODUCT itself',
+        '   connects to at runtime to FUNCTION — a database, an API host, a message broker —',
+        '   whose absence is an environment gap; versus (rule 5c, UNOBSERVED) a HARNESS that',
+        '   exists only to OBSERVE or DRIVE the product during a check — a browser driver, a',
+        "   UI/terminal smoke, a snapshot or fuzz tool — whose absence leaves the product's own",
+        '   behavior unproven. The product NEEDS the former to work at all; it needs the latter',
+        '   only to be CHECKED. A command that fails because such a runtime SERVICE is absent',
+        '   stays a rule-5 env-gap and is NOT UNOBSERVED; a required behavior you could not',
+        '   OBSERVE because its test harness is absent IS UNOBSERVED.',
+        '',
+        '6. If the spec legitimately has no runnable verification at all (a pure docs / config',
+        '   change with nothing to build or run), validating it cleanly is a PASS. This is NOT',
+        '   the same as a required behavioral check that self-skipped or whose tool is absent',
+        '   (that is UNOBSERVED, rule 5c) — "nothing to verify" means the spec never demanded',
+        '   an observation, not that an observation was demanded and then dodged.',
         '',
         '7. Do NOT edit anything to make a check pass. Report what you actually saw.',
         '',
@@ -291,32 +357,53 @@ export function buildVerifyPrompt(spec, probeFindings, envNotes, prohibitionFind
         'acceptance criterion is unmet — a required function absent, required data not persisted,',
         'a required behavior missing — the verdict is FAIL, even if typecheck and lint are green',
         'and even if the gap seems minor. Never downgrade an unmet criterion to a warning note.',
+        'Before concluding PASS, confirm every behavioral check you relied on has its paired',
+        'negative control (rule 3e) showing it CAN fail; a required behavior with no',
+        'discriminating check is UNVERIFIED, and the verdict is FAIL.',
         '',
         ENV_NOTE_EMIT_INSTRUCTION,
         '',
         'When you are done, output EXACTLY ONE of these as the final line:',
         "  WORK-VERIFIED: PASS              (the project's own command, run unaided, met the spec)",
         '  WORK-VERIFIED: FAIL <text>      (the shipped command failed or did not meet the spec; say what failed)',
+        '  WORK-VERIFIED: UNOBSERVED <text> (a spec-required behavioral check could not run because',
+        '                                    its observation tooling is absent — the behavior is',
+        '                                    unproven, not passed and not a code failure; rule 5c)',
         'Output the verdict line verbatim — it is parsed mechanically.'
     ].join('\n');
 }
 /**
- * Parse the child's verdict. Scans for the LAST `WORK-VERIFIED: PASS|FAIL` marker
- * (the model discusses before concluding, and bash output may echo the word
+ * Parse the child's verdict. Scans for the LAST `WORK-VERIFIED: PASS|FAIL|UNOBSERVED`
+ * marker (the model discusses before concluding, and bash output may echo the word
  * "VERIFY", so a distinct token and last-match win matter).
  *
+ * UNOBSERVED (rule 5c) is a distinct third outcome: a spec-required behavioral check
+ * could not run because its observation tooling is absent, so the behavior is neither
+ * proven nor shown broken. It is NOT a pass (`pass: false`) but carries `unobserved`
+ * so the gate can route it straight to the human — an unattended AUTOFIX re-run cannot
+ * provision a missing tool, so it must never auto-loop on this.
+ *
  * No marker at all is NOT a pass: a verification that cannot state a verdict is a
  * gray area, and the contract is that unverified work is reported as such.
  */
 export function parseVerifyVerdict(text) {
-    const re = /WORK-VERIFIED:\s*(PASS|FAIL)\b[ \t]*(.*)/gi;
+    const re = /WORK-VERIFIED:\s*(PASS|FAIL|UNOBSERVED)\b[ \t]*(.*)/gi;
     let last = null;
     for (let m = re.exec(text); m !== null; m = re.exec(text))
         last = m;
     if (!last)
         return { pass: false, detail: 'no verdict emitted' };
-    const pass = last[1].toUpperCase() === 'PASS';
-    return { pass, detail: pass ? '' : last[2].trim() || 'unspecified failure' };
+    const kind = last[1].toUpperCase();
+    if (kind === 'PASS')
+        return { pass: true, detail: '' };
+    if (kind === 'UNOBSERVED') {
+        return {
+            pass: false,
+            unobserved: true,
+            detail: last[2].trim() || 'a required behavior could not be observed'
+        };
+    }
+    return { pass: false, detail: last[2].trim() || 'unspecified failure' };
 }
 /**
  * Run the verification pass for one task. A missing spec is a pass. Otherwise run
@@ -370,6 +457,23 @@ export async function runWorkVerification(deps) {
             envNotes = '';
         }
     }
+    // Cross-slice contracts from decompose-time extraction (best-effort; a read
+    // fault must never block verification).
+    let contracts = '';
+    if (deps.contracts) {
+        try {
+            contracts = await deps.contracts();
+        }
+        catch {
+            contracts = '';
+        }
+    }
+    // DETERMINISTIC skip-escape finding, computed purely from the spec's own VERIFY
+    // block (see skip-escape.ts): a required check wrapped in a skip-announcing `||`
+    // fallback. Injected so rule 5c fires reliably — the model does not self-discover a
+    // graceful skip-escape (A/B: rule alone ~1-3/5), but acts on a finding naming the
+    // exact line, per the proven probe+rule pattern. Pure text analysis, no dep needed.
+    const skipEscapes = skipEscapeVerifyFindings(findSkipEscapes(deps.spec));
     // A child that emits NO verdict never judged the work (budget/context death mid-
     // investigation — seen live: an 11-minute verify wandered, died verdict-less, and
     // the resulting FAIL burned a full implementation re-run on an unjudged artifact).
@@ -377,7 +481,7 @@ export async function runWorkVerification(deps) {
     for (let attempt = 1;; attempt++) {
         let text;
         try {
-            text = await deps.runChild(VERIFY_TOOLS, buildVerifyPrompt(deps.spec, findings, envNotes, prohibitions), deps.signal);
+            text = await deps.runChild(VERIFY_TOOLS, buildVerifyPrompt(deps.spec, findings, envNotes, prohibitions, skipEscapes, contracts), deps.signal);
         }
         catch (err) {
             if (err instanceof Error && err.message === USER_CANCELLED)
@@ -414,6 +518,12 @@ export async function runWorkVerification(deps) {
             return { ok: true };
         if (verdict.detail === 'no verdict emitted' && attempt === 1)
             continue;
+        // UNOBSERVED (rule 5c): a spec-required behavioral check could not run because
+        // its tooling is absent. Block like any FAIL, but flag it so the gate hands it
+        // straight to the human — re-running the impl turn cannot install a missing tool.
+        if (verdict.unobserved) {
+            return { ok: false, unobserved: true, reason: `work unobserved: ${verdict.detail}` };
+        }
         return {
             ok: false,
             reason: `work did not verify: ${verdict.detail}${verdict.detail === 'no verdict emitted' ? ' (after verify retry)' : ''}`

package/dist/task/wiring-claims.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Deterministic synthesized-wiring scanner for a composed spec (run-8 F3, gen side).
+ *
+ * F3 (the dominant run-8 shipped defect): refine/compose invent a "uniform" wiring
+ * table — one module → one mount prefix, `/api/<x>` → `<x>Routes` for every module —
+ * though the design pins ENDPOINTS, not mounts, and one module's pinned endpoints do
+ * NOT all sit under a single prefix (photos: `POST /api/listings/:id/photos` AND
+ * `GET/DELETE /api/photos/:id`). Mounting that module at `/api/photos` double-prefixes
+ * the upload; consumers follow the pinned paths, assembly follows the invented table,
+ * the seam ships broken. See [[contract-registry-f3]] (#4, the verify-side + registry
+ * lever) — this is its GENERATION-side complement.
+ *
+ * A/B-measured on the live 27B (F3 critique trap): the CROSS-SLICE CONTRACTS registry
+ * is NECESSARY but the prompt+registry alone is a WEAK catcher (A/B arms 0/8, +registry
+ * only 1/8) — the model's attention goes to the obvious VERIFY weakness and it rarely
+ * does the path-composition reasoning even with the facts in front of it. The reliable
+ * lever is the SAME probe+rule pattern as [[skip-escape-scanner-f2]] / [[verify-
+ * substitution-ab]]: a deterministic finding that NAMES the exact synthesized mappings
+ * and juxtaposes the verbatim pinned facts, forcing focused reconciliation.
+ *
+ * This scanner does NOT decide which mapping is wrong — that needs routing-composition
+ * knowledge (a forbidden stack assumption). It surfaces every mapping that (a) is not a
+ * verbatim substring of the design/registry (so it is INFERRED, not cited) AND (b) touches
+ * a pinned cross-slice boundary (an operand appears in the registry) — i.e. it reshapes a
+ * shared contract. The 4 coincidentally-correct mappings are surfaced too, but framed as
+ * "reconcile each; keep the conforming ones" — the LLM decides, informed. Pure text/
+ * substring analysis; no stack, framework, or routing assumptions. Empty registry (single
+ * `/task`, or no shared boundary) ⇒ no-op.
+ */
+export interface WiringClaim {
+    /** The offending mapping line, verbatim (trimmed). */
+    line: string;
+    /** Left operand (the mapped-from token, e.g. a mount prefix). */
+    from: string;
+    /** Right operand (the mapped-to token, e.g. a module name). */
+    to: string;
+}
+/**
+ * Find synthesized wiring mappings in `spec`: `A <arrow> B` lines whose whole mapping
+ * is NOT a verbatim substring of `grounding` (design ∪ registry) yet an operand appears
+ * in `registry` (so it reshapes a pinned cross-slice boundary). Returns [] when the
+ * registry is empty (no shared contracts to reshape) — the whole check is a no-op then.
+ */
+export declare function findSynthesizedWiring(spec: string, grounding: string, registry: string): WiringClaim[];
+/**
+ * Render findings as the critique probe (probe+rule pattern): NAME the inferred
+ * mappings and juxtapose the verbatim pinned facts, then instruct focused
+ * reconciliation. Deliberately does NOT accuse a specific mapping — the model decides
+ * which (if any) fails to reproduce a pinned fact. Empty findings ⇒ '' (no block).
+ */
+export declare function wiringProbeText(findings: WiringClaim[], registry: string): string;
+/**
+ * Render findings as a critique-rewrite defect block (fed into the FOCUS list): the
+ * rewrite must reconcile each mapping against the pinned facts and correct only the
+ * one(s) that break. Mirrors skipEscapeDefectText's shape.
+ */
+export declare function wiringDefectText(findings: WiringClaim[], registry: string): string;
+/**
+ * Concatenate the design/spec docs the given texts @-reference (best-effort, readable
+ * files only) as extra grounding for findSynthesizedWiring — so a mapping the design
+ * states verbatim is treated as CITED, not synthesized. Unreadable/absent mentions are
+ * skipped; returns '' when nothing resolves.
+ */
+export declare function readReferencedDocs(cwd: string, ...texts: string[]): string;

package/dist/task/wiring-claims.js

@@ -0,0 +1,149 @@
+/**
+ * Deterministic synthesized-wiring scanner for a composed spec (run-8 F3, gen side).
+ *
+ * F3 (the dominant run-8 shipped defect): refine/compose invent a "uniform" wiring
+ * table — one module → one mount prefix, `/api/<x>` → `<x>Routes` for every module —
+ * though the design pins ENDPOINTS, not mounts, and one module's pinned endpoints do
+ * NOT all sit under a single prefix (photos: `POST /api/listings/:id/photos` AND
+ * `GET/DELETE /api/photos/:id`). Mounting that module at `/api/photos` double-prefixes
+ * the upload; consumers follow the pinned paths, assembly follows the invented table,
+ * the seam ships broken. See [[contract-registry-f3]] (#4, the verify-side + registry
+ * lever) — this is its GENERATION-side complement.
+ *
+ * A/B-measured on the live 27B (F3 critique trap): the CROSS-SLICE CONTRACTS registry
+ * is NECESSARY but the prompt+registry alone is a WEAK catcher (A/B arms 0/8, +registry
+ * only 1/8) — the model's attention goes to the obvious VERIFY weakness and it rarely
+ * does the path-composition reasoning even with the facts in front of it. The reliable
+ * lever is the SAME probe+rule pattern as [[skip-escape-scanner-f2]] / [[verify-
+ * substitution-ab]]: a deterministic finding that NAMES the exact synthesized mappings
+ * and juxtaposes the verbatim pinned facts, forcing focused reconciliation.
+ *
+ * This scanner does NOT decide which mapping is wrong — that needs routing-composition
+ * knowledge (a forbidden stack assumption). It surfaces every mapping that (a) is not a
+ * verbatim substring of the design/registry (so it is INFERRED, not cited) AND (b) touches
+ * a pinned cross-slice boundary (an operand appears in the registry) — i.e. it reshapes a
+ * shared contract. The 4 coincidentally-correct mappings are surfaced too, but framed as
+ * "reconcile each; keep the conforming ones" — the LLM decides, informed. Pure text/
+ * substring analysis; no stack, framework, or routing assumptions. Empty registry (single
+ * `/task`, or no shared boundary) ⇒ no-op.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/** Mapping arrows a wiring/mount table uses across notations. A colon is deliberately
+ *  NOT an arrow — it matches endpoint params (`/photos/:id`), section headers, and prose,
+ *  which would drown the signal. */
+const ARROW = '(?:→|->|=>|⇒|↦)';
+/** A `left <arrow> right` mapping on one line, tolerating a leading list bullet. */
+const MAPPING_LINE_RE = new RegExp(`^[ \\t]*[-*]?[ \\t]*(.+?)[ \\t]*${ARROW}[ \\t]*(.+?)[ \\t]*$`);
+/** An operand shorter than this is too generic to anchor a boundary match. */
+const MIN_OPERAND_LENGTH = 4;
+/** Collapse whitespace + lowercase; drop markdown backticks so quoting formatting
+ *  differences don't defeat the substring match. Mirrors contracts.ts's normalise. */
+function normalise(s) {
+    return s.replace(/`/g, '').replace(/\s+/g, ' ').trim().toLowerCase();
+}
+/**
+ * Find synthesized wiring mappings in `spec`: `A <arrow> B` lines whose whole mapping
+ * is NOT a verbatim substring of `grounding` (design ∪ registry) yet an operand appears
+ * in `registry` (so it reshapes a pinned cross-slice boundary). Returns [] when the
+ * registry is empty (no shared contracts to reshape) — the whole check is a no-op then.
+ */
+export function findSynthesizedWiring(spec, grounding, registry) {
+    if (registry.trim().length === 0)
+        return [];
+    const groundHay = normalise(grounding + '\n' + registry);
+    const regHay = normalise(registry);
+    const found = [];
+    const seen = new Set();
+    for (const rawLine of spec.split('\n')) {
+        const m = MAPPING_LINE_RE.exec(rawLine);
+        if (!m)
+            continue;
+        const from = m[1].trim();
+        const to = m[2].trim();
+        const line = rawLine.replace(/^[ \t]*[-*][ \t]*/, '').trim();
+        const key = normalise(line);
+        if (key.length === 0 || seen.has(key))
+            continue;
+        // Cited, not synthesized: the whole mapping appears verbatim in the source.
+        if (groundHay.includes(key))
+            continue;
+        // Only a mapping that touches a PINNED shared boundary is an F3 suspect — this
+        // is the crisp discriminator that keeps internal-flow prose ("input → output")
+        // out. An operand (long enough to be specific) must appear in the registry.
+        const touchesBoundary = [from, to].some(op => {
+            const n = normalise(op);
+            return n.length >= MIN_OPERAND_LENGTH && regHay.includes(n);
+        });
+        if (!touchesBoundary)
+            continue;
+        seen.add(key);
+        found.push({ line, from: from.replace(/`/g, ''), to: to.replace(/`/g, '') });
+    }
+    return found;
+}
+/**
+ * Render findings as the critique probe (probe+rule pattern): NAME the inferred
+ * mappings and juxtapose the verbatim pinned facts, then instruct focused
+ * reconciliation. Deliberately does NOT accuse a specific mapping — the model decides
+ * which (if any) fails to reproduce a pinned fact. Empty findings ⇒ '' (no block).
+ */
+export function wiringProbeText(findings, registry) {
+    if (findings.length === 0)
+        return '';
+    return [
+        'SYNTHESIZED WIRING (deterministic finding) — the spec states these connect-the-',
+        'modules mappings that are NOT quoted verbatim from the design (they are INFERRED,',
+        'not cited) and that touch a pinned cross-slice boundary:',
+        ...findings.map((f, i) => `  ${i + 1}. ${f.line}`),
+        'The design pins these interface FACTS instead (verbatim, authoritative):',
+        ...registry
+            .trim()
+            .split('\n')
+            .filter(l => l.trim().length > 0)
+            .map(l => `  - ${l.trim()}`),
+        'For EACH mapping above, confirm it REPRODUCES the pinned facts EXACTLY. A module',
+        'whose pinned facts do NOT all sit under the single prefix it is mapped to CANNOT be',
+        'wired that way without breaking a path — that is a SEAM BUG: name the mapping and the',
+        'pinned fact it fails to produce. KEEP every mapping that does reproduce its facts; do',
+        'NOT alter a conforming one. If a boundary detail is genuinely unpinned, leave it',
+        'unspecified rather than inventing a mapping.'
+    ].join('\n');
+}
+/**
+ * Render findings as a critique-rewrite defect block (fed into the FOCUS list): the
+ * rewrite must reconcile each mapping against the pinned facts and correct only the
+ * one(s) that break. Mirrors skipEscapeDefectText's shape.
+ */
+export function wiringDefectText(findings, registry) {
+    return wiringProbeText(findings, registry);
+}
+// An @-file mention in a spec ("@DESIGN/foo.md"), minus trailing prose punctuation.
+// Mirrors phantom-imports' mention rules so grounding sees the same source docs.
+const MENTION_RE = /(?:^|\s)@([^\s]+)/g;
+const MENTION_TRAILING_PUNCT = /[.,;:!?)\]}>"']+$/;
+/**
+ * Concatenate the design/spec docs the given texts @-reference (best-effort, readable
+ * files only) as extra grounding for findSynthesizedWiring — so a mapping the design
+ * states verbatim is treated as CITED, not synthesized. Unreadable/absent mentions are
+ * skipped; returns '' when nothing resolves.
+ */
+export function readReferencedDocs(cwd, ...texts) {
+    const seen = new Set();
+    const parts = [];
+    for (const text of texts) {
+        for (const m of text.matchAll(MENTION_RE)) {
+            const rel = m[1].replace(MENTION_TRAILING_PUNCT, '');
+            if (rel === '' || seen.has(rel))
+                continue;
+            seen.add(rel);
+            try {
+                parts.push(fs.readFileSync(path.resolve(cwd, rel), 'utf8'));
+            }
+            catch {
+                // not a readable file — skip
+            }
+        }
+    }
+    return parts.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.18.2",
+    "version": "0.18.3",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",