@mjasnikovs/pi-task 0.18.14 → 0.18.16

package/dist/task/phases.js

@@ -28,7 +28,10 @@ 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 { findAbsenceConflicts, absenceProbeText, siblingTitlesFromPlanContext } from './verify-reconcile.js';
+import { existsSync } from 'node:fs';
 import { readContracts, buildContractsBlock, buildContractsVerifyBlock } from './contracts.js';
+import { readRequirements, buildRequirementsBlock } from './requirements.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 ────────────────────────────
@@ -128,9 +131,25 @@ export async function phaseContractsBlock(deps) {
     const contracts = await readContracts(deps.cwd).catch(() => '');
     return buildContractsBlock(contracts);
 }
+/**
+ * The carried-context blocks a GENERATIVE phase (refine, compose) receives: the
+ * cross-slice contracts plus the carried cross-cutting requirements (mx5 run 11,
+ * goals A/C — `.pi-tasks/requirements.md`, written at plan time). The verbatim
+ * requirement quotes travel INTO every task's spec generation, so a mandated
+ * methodology ("a test lands in the same change as each new route") reaches the
+ * task's GOAL/CONSTRAINTS and its VERIFY — a pointer back to the spec doc
+ * recovered the dropped §10 in only 1 of ~6 applicable run-11 tasks; content
+ * travels, pointers don't. Both blocks are '' outside their runs, so a bare
+ * /task is byte-identical to before.
+ */
+export async function phaseCarriedBlocks(deps) {
+    const contracts = await phaseContractsBlock(deps);
+    const requirements = buildRequirementsBlock(await readRequirements(deps.cwd).catch(() => ''));
+    return [contracts, requirements].filter(b => b.length > 0).join('\n');
+}
 export const phaseRefine = async (deps, raw, planContext) => {
     const existingFiles = await refineExistingFilesBlock(deps).catch(() => '');
-    const contracts = await phaseContractsBlock(deps);
+    const contracts = await phaseCarriedBlocks(deps);
     // Imperative tool directives the user wrote into the RAW prompt ("via web
     // search", "fetch <url>"). Refine paraphrases the task and a weak model drops
     // these some of the time (mx5 run 9: "via web search" vanished, the whole run
@@ -750,7 +769,7 @@ export async function phaseGrill(deps, ctx, widgetState, refined, research) {
     return out.join('\n');
 }
 export async function phaseCompose(deps, refined, research, qa) {
-    const contracts = await phaseContractsBlock(deps);
+    const contracts = await phaseCarriedBlocks(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
@@ -772,7 +791,7 @@ export async function phaseCompose(deps, refined, research, qa) {
         return { ok: true, value: stripped };
     }, problem => new Error(`compose_invalid: ${problem}`));
 }
-export async function phaseCritique(deps, spec, refined, qa) {
+export async function phaseCritique(deps, spec, refined, qa, planContext) {
     // Fast triage before the expensive full rewrite. The rewrite regenerates
     // the entire spec from scratch and is the costliest tail of the pipeline
     // (observed up to ~240s). Most compose drafts are already good, so we first
@@ -813,6 +832,24 @@ export async function phaseCritique(deps, spec, refined, qa) {
     if (wiringProbe) {
         deps.logDebug?.(`synthesized wiring flagged in spec: ${wiring.map(w => w.line).join(' | ')}`);
     }
+    // DETERMINISTIC plan-contradiction probe (mx5 run 11, goal D): a VERIFY line
+    // asserting the ABSENCE of an artifact the plan pins elsewhere — a path a prior
+    // task already shipped to disk, a sibling title's deliverable, a contract-pinned
+    // boundary. Run 11: the scope fence leaked into TASK_0009's verify as "the admin
+    // page must NOT exist" (TASK_0008's deliverable); the guaranteed FAIL became an
+    // accepted debt that the final-gate autofix then "fixed" by deleting the sibling's
+    // work. The conflict must die here, at spec time — forced into the rewrite like
+    // the skip-escape finding; delete-tasks keep their check by declaring the delete.
+    const absenceConflicts = findAbsenceConflicts(spec, {
+        fileExists: p => existsSync(resolve(deps.cwd, p)),
+        siblingTitles: siblingTitlesFromPlanContext(planContext),
+        contracts: registryRaw
+    });
+    const absenceProbe = absenceConflicts.length > 0 ? absenceProbeText(absenceConflicts) : null;
+    if (absenceProbe) {
+        deps.logDebug?.('plan-contradiction flagged in VERIFY: '
+            + absenceConflicts.map(c => `${c.assertion.target} (${c.against})`).join(' | '));
+    }
     let triageDefects = null;
     if (parseVerifyBlock(spec) !== null) {
         const tTriage = Date.now();
@@ -829,21 +866,23 @@ export async function phaseCritique(deps, spec, refined, qa) {
         }
         deps.recordSubStep?.('triage', Date.now() - tTriage);
         if (verdict !== null) {
-            // 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).
+            // A deterministic skip-escape, synthesized-wiring, or plan-contradiction
+            // 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 any of them reliably).
             if (isCritiqueClean(verdict)) {
-                if (skipDefects === null && wiringProbe === null)
+                if (skipDefects === null && wiringProbe === null && absenceProbe === 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;
+    // Merge the deterministic skip-escape + synthesized-wiring + plan-contradiction
+    // defects with any triage defects for the rewrite (all are forced FOCUS items).
+    const rewriteDefects = [skipDefects, wiringProbe, absenceProbe, 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, rewriteDefects, contractsBlock), text => {
@@ -863,7 +902,7 @@ export async function phaseCritique(deps, spec, refined, qa) {
 // ─── Critique with fallback ──────────────────────────────────────────────────
 export async function critiqueWithFallback(d, p) {
     try {
-        return await phaseCritique(d, p.spec, p.refined, p.qa);
+        return await phaseCritique(d, p.spec, p.refined, p.qa, p.planContext);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);

package/dist/task/prompts.js

@@ -324,6 +324,8 @@ VERIFY must exercise the surface area the task actually touches. Draw VERIFY com
 - Python / Go / Rust / other source changes → MUST include the language's standard verification from TOOLING (e.g. \`pytest\`, \`go test ./...\`, \`cargo test\`) plus lint/typecheck if configured.
 - Config / infra-only changes with no executable verification → state that explicitly with a single command that re-reads or validates the config (e.g. \`docker compose config\`, \`nginx -t\`, \`yamllint file.yml\`). Never leave VERIFY with only \`true\` or \`echo ok\`.
 
+When this task is one step of a larger plan: sibling steps' deliverables may already exist in the tree and more will land after this task. NEVER write a VERIFY check that fails because sibling work exists (e.g. "file X must not exist" when another step owns X). The plan context forbids you from BUILDING other steps' work — it does not make their work absent. Verify what THIS task adds or changes.
+
 If TOOLING is empty for a category the change clearly touches, still include the best-effort standard command for that ecosystem (e.g. \`npx tsc --noEmit\` for a TS repo with no script) and note that the receiving agent may need to install it.
 
 If the research contains an "API CORRECTIONS" section, it is AUTHORITATIVE — each line was verified against the installed types. For every correction: use the import it prescribes, never the specifier it marks non-existent, and add a CONSTRAINT recording it verbatim (e.g. Use \`import { sql } from "bun"\`; \`bun:sql\` is not a module — do not import it or declare a module for it). This overrides any conflicting identifier carried up from the refined task or the spec doc.

package/dist/task/render-check.d.ts

@@ -0,0 +1,32 @@
+export type RenderOutcome = {
+    outcome: 'pass';
+    detail: string;
+} | {
+    outcome: 'fail';
+    detail: string;
+} | {
+    outcome: 'skip';
+    note: string;
+};
+/**
+ * A launchable Chrome-family binary, or null when this box has none: the explicit
+ * CHROME_BIN override first, then the Playwright cache (headless shell — reliable
+ * on network URLs), then a system browser on PATH as a last resort. Null → the
+ * render check SKIPs (env gap) — it never installs anything.
+ */
+export declare function findHeadlessBrowser(): string | null;
+/**
+ * Judge a RENDERED (post-JS) DOM: the body must carry visible text or concrete
+ * visual/interactive elements. Pure text analysis so the judgment is unit-tested
+ * against real captured DOMs; `detail` describes what was (or wasn't) found.
+ */
+export declare function judgeRenderedDom(html: string): {
+    ok: boolean;
+    detail: string;
+};
+/**
+ * Load `url` once in a headless Chrome and judge the rendered DOM. Blocking
+ * (spawnSync) by design — the caller holds the booted server alive exactly for
+ * this window. `browser` is injectable for tests; the default is discovery.
+ */
+export declare function runRenderCheck(url: string, browser?: string | null): RenderOutcome;

package/dist/task/render-check.js

@@ -0,0 +1,186 @@
+/**
+ * render-check — one headless-browser page load against the booted app's live
+ * listener, judging whether the client actually RENDERED anything (mx5 runs 8 and
+ * 11).
+ *
+ * The failure class: every "renders without runtime errors" check in the pipeline
+ * was curl — and curl cannot execute JavaScript. Run 8 shipped an app whose ESM
+ * bundle was loaded in a classic script tag: HTTP 200 on every route, permanently
+ * BLANK page, all gates green. Run 11 shipped a router with no <Switch> (the 404
+ * fallback rendered on every page) — invisible to every gate for the same reason.
+ * The gate's boot check proves a LISTENER exists (run 10); this proves the
+ * listener serves a page whose client code MOUNTS something.
+ *
+ * Mechanism, deterministic and dependency-free: discover a Chrome-family binary
+ * (system chromium/chrome or the Playwright browser cache — nothing is installed,
+ * only found), load the page once with `--headless --dump-dom` (which executes the
+ * page's JS under a virtual-time budget), and judge the RENDERED body: it must
+ * contain visible text or concrete visual/interactive elements. A blank mount
+ * point after JS ran is the run-8 class — FAIL with the body's shape. What it
+ * deliberately does NOT judge: correctness of what rendered (run 11's 404-below-
+ * login needs app knowledge no generic gate has).
+ *
+ * Env-gap contract as everywhere: no browser found, a browser that cannot launch,
+ * or a dump that produced nothing → SKIP with a note (the caller surfaces it as
+ * UNOBSERVED), never a false FAIL. Only a page the browser really loaded and
+ * rendered EMPTY fails.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/** PATH names tried in order for a system Chrome-family binary. */
+const CHROME_PATH_CANDIDATES = [
+    'chromium',
+    'chromium-browser',
+    'google-chrome-stable',
+    'google-chrome',
+    'chrome'
+];
+/** Does `bin` resolve on PATH? (`command -v` shape, portable via spawnSync.) */
+function onPath(bin) {
+    const probe = process.platform === 'win32' ? 'where' : 'which';
+    const r = spawnSync(probe, [bin], { encoding: 'utf8', timeout: 4000 });
+    return !r.error && r.status === 0 && (r.stdout ?? '').trim().length > 0;
+}
+/**
+ * The newest Playwright-cache Chromium, if any — the HEADLESS SHELL preferred over
+ * the full build. Found, never installed: the cache exists on any box that ever ran
+ * Playwright browsers (the mx5-class projects install it as their own test
+ * dependency). The headless shell is purpose-built for `--dump-dom` and returns
+ * promptly on a network URL where the full system chromium can stall under a
+ * virtual-time budget (validated live on this box: shell exits 0 in ~1s, full
+ * chromium times out at 30s on the same http:// URL).
+ */
+function playwrightCachedChromium() {
+    const cache = process.env.PLAYWRIGHT_BROWSERS_PATH
+        ?? (process.platform === 'darwin' ?
+            path.join(os.homedir(), 'Library', 'Caches', 'ms-playwright')
+            : path.join(os.homedir(), '.cache', 'ms-playwright'));
+    let entries;
+    try {
+        entries = readdirSync(cache);
+    }
+    catch {
+        return null;
+    }
+    // Headless shell first (fast, purpose-built), then the full chromium build.
+    // Within each family the newest revision wins (revs sort ascending → reverse).
+    const families = [
+        {
+            prefix: 'chromium_headless_shell-',
+            rels: [
+                path.join('chrome-headless-shell-linux64', 'chrome-headless-shell'),
+                path.join('chrome-linux', 'headless_shell')
+            ]
+        },
+        {
+            prefix: 'chromium-',
+            rels: [path.join('chrome-linux64', 'chrome'), path.join('chrome-linux', 'chrome')]
+        }
+    ];
+    for (const { prefix, rels } of families) {
+        const revs = entries.filter(e => e.startsWith(prefix)).sort();
+        for (const rev of revs.reverse()) {
+            for (const rel of rels) {
+                const p = path.join(cache, rev, rel);
+                if (existsSync(p))
+                    return p;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * A launchable Chrome-family binary, or null when this box has none: the explicit
+ * CHROME_BIN override first, then the Playwright cache (headless shell — reliable
+ * on network URLs), then a system browser on PATH as a last resort. Null → the
+ * render check SKIPs (env gap) — it never installs anything.
+ */
+export function findHeadlessBrowser() {
+    const explicit = process.env.CHROME_BIN;
+    if (explicit && existsSync(explicit))
+        return explicit;
+    const cached = playwrightCachedChromium();
+    if (cached)
+        return cached;
+    for (const bin of CHROME_PATH_CANDIDATES) {
+        if (onPath(bin))
+            return bin;
+    }
+    return null;
+}
+/** Elements whose presence means the page rendered CONCRETE UI even with no text. */
+const VISUAL_ELEMENT_RE = /<(?:img|svg|canvas|video|audio|input|button|textarea|select|iframe)\b/i;
+/**
+ * Judge a RENDERED (post-JS) DOM: the body must carry visible text or concrete
+ * visual/interactive elements. Pure text analysis so the judgment is unit-tested
+ * against real captured DOMs; `detail` describes what was (or wasn't) found.
+ */
+export function judgeRenderedDom(html) {
+    const bodyMatch = /<body\b[^>]*>([\s\S]*)<\/body>/i.exec(html);
+    // No <body> at all in a dumped DOM → the browser rendered something degenerate;
+    // judge the whole document rather than fail on shape.
+    const body = bodyMatch ? bodyMatch[1] : html;
+    const visible = body
+        .replace(/<(script|style|template|noscript)\b[\s\S]*?<\/\1>/gi, '')
+        .replace(/<!--[\s\S]*?-->/g, '');
+    const text = visible
+        .replace(/<[^>]*>/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (text.length > 0) {
+        return { ok: true, detail: `rendered visible text ("${text.slice(0, 80)}")` };
+    }
+    if (VISUAL_ELEMENT_RE.test(visible)) {
+        return { ok: true, detail: 'rendered visual/interactive elements (no text)' };
+    }
+    return {
+        ok: false,
+        detail: 'the rendered body is EMPTY after client JS executed — no visible text, no '
+            + 'visual or interactive elements (the blank-page class: HTTP serves, nothing mounts)'
+    };
+}
+/** Wall-clock cap for the whole browser run; virtual-time budget for the page JS. */
+const RENDER_TIMEOUT_MS = 30_000;
+const VIRTUAL_TIME_BUDGET_MS = 8_000;
+/**
+ * Load `url` once in a headless Chrome and judge the rendered DOM. Blocking
+ * (spawnSync) by design — the caller holds the booted server alive exactly for
+ * this window. `browser` is injectable for tests; the default is discovery.
+ */
+export function runRenderCheck(url, browser) {
+    const bin = browser === undefined ? findHeadlessBrowser() : browser;
+    if (!bin) {
+        return {
+            outcome: 'skip',
+            note: 'no headless Chrome-family browser found on this box (PATH, CHROME_BIN, Playwright cache)'
+        };
+    }
+    const r = spawnSync(bin, [
+        '--headless',
+        '--disable-gpu',
+        '--no-sandbox',
+        '--disable-dev-shm-usage',
+        `--virtual-time-budget=${VIRTUAL_TIME_BUDGET_MS}`,
+        '--dump-dom',
+        url
+    ], { encoding: 'utf8', timeout: RENDER_TIMEOUT_MS, env: { ...process.env } });
+    if (r.error || r.status === null) {
+        return { outcome: 'skip', note: `browser did not run (${r.error?.message ?? 'timeout'})` };
+    }
+    const dom = (r.stdout ?? '').trim();
+    if (r.status !== 0 || dom.length === 0) {
+        // A crash/empty dump is a browser/env condition on this box, not proof the
+        // app is blank — skip with the tail so the trail explains it.
+        const tail = (r.stderr ?? '').trim().slice(-200);
+        return {
+            outcome: 'skip',
+            note: `browser exited ${r.status} with no DOM${tail ? ` — ${tail}` : ''}`
+        };
+    }
+    const judged = judgeRenderedDom(dom);
+    return judged.ok ?
+        { outcome: 'pass', detail: judged.detail }
+        : { outcome: 'fail', detail: judged.detail };
+}

package/dist/task/requirements.d.ts

@@ -0,0 +1,88 @@
+export interface RequirementEntry {
+    /** The verbatim quote from the source doc — the obligation. */
+    quote: string;
+    /** Where it came from (heading/section, or 'prose'). */
+    anchor: string;
+}
+export declare function requirementsFile(cwd: string): string;
+/** Parse `REQUIREMENT: "<quote>" [anchor: …]` lines (mirrors parseContractLines). */
+export declare function parseRequirementLines(text: string): RequirementEntry[];
+/** THE ANTI-SYNTHESIS GUARD: keep only entries whose quote is a normalised
+ *  substring of the source doc (same rule as keepGroundedContracts). Does NOT
+ *  cap — capping is capRequirements' job, which protects obligation-marked
+ *  passages from doc-order truncation. */
+export declare function keepGroundedRequirements(entries: RequirementEntry[], sourceDoc: string): RequirementEntry[];
+/**
+ * Bound the list WITHOUT doc-order truncation: measured live, an eager model
+ * extracts 40+ items top-down (every §1 decision row), so a plain first-N cap
+ * systematically drops the TAIL sections — exactly where mx5 keeps its testing
+ * obligations. Rule (deterministic priority, not a knob): entries quoting an
+ * obligation-marked passage survive first; the remainder fills in given order.
+ */
+export declare function capRequirements(entries: RequirementEntry[], passages: string[]): RequirementEntry[];
+/**
+ * DETERMINISTIC RECALL FLOOR (same medicine as the launch-contract checklist):
+ * paragraphs carrying an obligation marker (word-bounded "required"/"must").
+ * Extraction recall over a 20KB doc is the weak model's, and it is variance-
+ * prone — measured live, 1 of 5 runs kept 16 quotes with ZERO §10 items. The
+ * host enumerates the marked passages; the prompt lists their head lines as a
+ * checklist, and uncoveredPassages() below turns "a marked passage produced no
+ * quote" into hard evidence for one forced re-extraction.
+ */
+export declare function enumerateObligationPassages(doc: string): string[];
+/** Marked passages none of the kept quotes came from — the hard evidence that
+ *  extraction recall failed there (a kept quote "covers" a passage when the
+ *  passage contains it, normalised). */
+export declare function uncoveredPassages(passages: string[], kept: RequirementEntry[]): string[];
+/** Reprompt hint for the forced re-extraction over uncovered passages. */
+export declare function extractionRetryHint(uncovered: string[]): string;
+/** The plan-time extraction prompt. Runs with --no-tools; every quote is
+ *  re-grounded host-side, so guessing wastes effort. Spec-shape-agnostic.
+ *  `passages` is enumerateObligationPassages' checklist ([] ⇒ prompt unchanged). */
+export declare const REQUIREMENT_EXTRACT_PROMPT: (feature: string, passages?: string[]) => string;
+export type ReqMapping = {
+    kind: 'task';
+    task: number;
+} | {
+    kind: 'cross';
+} | {
+    kind: 'none';
+};
+/** Per-requirement coverage verdicts against a task list. Runs with --no-tools. */
+export declare const COVERAGE_MAP_PROMPT: (requirements: RequirementEntry[], titles: string[]) => string;
+/**
+ * Parse the mapping output. Index-aligned with `requirements` (0-based); a
+ * requirement the model skipped, or mapped to an out-of-range task, is `none` —
+ * distrust by default: an unaccounted requirement is exactly what this gate
+ * exists to surface, so parsing leniency must never manufacture coverage.
+ */
+export declare function parseCoverageMap(text: string, reqCount: number, taskCount: number): ReqMapping[];
+export interface CoverageAccounting {
+    mapped: Array<{
+        req: RequirementEntry;
+        task: number;
+    }>;
+    crossCutting: RequirementEntry[];
+    /** Requirements NO task covers — drives the decompose reprompt / surfacing. */
+    unmapped: RequirementEntry[];
+}
+/** Deterministic accounting over the parsed map — the host, not the model,
+ *  decides completeness. */
+export declare function accountCoverage(requirements: RequirementEntry[], mappings: ReqMapping[]): CoverageAccounting;
+/** The stored carried-requirements text ('' when none recorded). */
+export declare function readRequirements(cwd: string): Promise<string>;
+/**
+ * Append carried requirements (cross-cutting, plus any left unmapped after the
+ * retry rounds — better carried into every task than silently lost), deduped
+ * against what is stored. Host-side only; children never write it. Best-effort.
+ */
+export declare function appendCarriedRequirements(cwd: string, crossCutting: RequirementEntry[], unresolved?: RequirementEntry[]): Promise<void>;
+/**
+ * The read-only block refine/compose receive when carried requirements exist.
+ * Verbatim content travels with every task (the directive pattern that works),
+ * and the VERIFY mandate is explicit — goal C rides here.
+ */
+export declare function buildRequirementsBlock(requirements: string): string;
+/** The decompose-prompt ledger block (goal E's belt): the grounded requirement
+ *  list rides into decompose so structure-mirroring can't discharge it. */
+export declare function buildRequirementsLedger(requirements: RequirementEntry[]): string;