@mjasnikovs/pi-task 0.18.1 → 0.18.3

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;