@mjasnikovs/pi-task 0.33.0 → 0.35.0

package/dist/task/env-template-closure.d.ts

@@ -0,0 +1,63 @@
+/** Variables the PLATFORM supplies, not the project. Deliberately short: every
+ *  entry is a name no `.env.example` is expected to carry. */
+export declare const AMBIENT_ENV: Set<string>;
+/** The same rule by MECHANISM rather than by name: a variable INJECTED by a
+ *  platform (CI runner, package manager, freedesktop base dirs). STEP 0 found
+ *  `GITHUB_ENV` (written by GitHub Actions), `npm_execpath` and `XDG_CACHE_HOME`
+ *  classified as required in real trees; a template that declared them would be
+ *  wrong, so the exclusion is the prefix, not a growing list of names. */
+export declare const AMBIENT_PREFIXES: string[];
+/** Rule 4: is this variable the platform's to supply? */
+export declare function isAmbient(name: string): boolean;
+/** Basenames that count as the project's env TEMPLATE. */
+export declare const ENV_TEMPLATE_NAMES: string[];
+/** Why a read does not require a declaration. `null` ⇒ it does. */
+export type StepAside = 'default' | 'compared' | 'assigned' | 'ambient' | 'optional-api' | 'probe';
+export interface EnvRead {
+    /** Variable name, always a literal. */
+    name: string;
+    /** Repo-relative file the read lives in. */
+    file: string;
+    /** 1-indexed line of the read. */
+    line: number;
+    /** The matched construct (`process.env`, `os.getenv`, …). */
+    construct: string;
+    /** null ⇒ REQUIRED; otherwise the mechanical reason it stepped aside. */
+    stepAside: StepAside | null;
+}
+export interface EnvClosure {
+    /** Tracked template files found (repo-relative). Empty ⇒ check is inert. */
+    templates: string[];
+    /** Every variable any template declares. */
+    declared: Set<string>;
+    /** Every literal env read seen in tracked source, step-asides included. */
+    reads: EnvRead[];
+    /** Required reads whose variable no template declares — the findings. */
+    missing: EnvRead[];
+}
+/** An inert result: what every tree with no tracked template returns. */
+export declare function inertClosure(): EnvClosure;
+/** Tracked files, repo-root-relative. null when `cwd` is not a git work tree. */
+export declare function trackedFiles(cwd: string): string[] | null;
+/** Variables a template file declares. A bare `X=` line declares `X`. */
+export declare function parseTemplate(text: string): string[];
+/** Every literal env read in one file's text. */
+export declare function scanSource(file: string, text: string): EnvRead[];
+/**
+ * Scan a tree: tracked templates × required reads in tracked source.
+ *
+ * Inert (empty templates, no findings) when the tree is not a git work tree or
+ * carries no tracked env template — the ENOENT=pass contract.
+ */
+export declare function scanEnvTemplateClosure(cwd: string): EnvClosure;
+/**
+ * The gate's view: one finding per VARIABLE (first read site, source order), not
+ * one per read — a var read in four files is one artifact defect, and the ranked
+ * failure list is read by a human and seeds the autofix prompt.
+ */
+export declare function findMissingEnvDeclarations(cwd: string): {
+    templates: string[];
+    missing: EnvRead[];
+};
+/** One finding, as the final gate would phrase it. */
+export declare function envGateFailureText(t: EnvRead, templates: string[]): string;

package/dist/task/env-template-closure.js

@@ -0,0 +1,397 @@
+/**
+ * env-template-closure — a shipped source file requires an env var the shipped
+ * template never mentions (nexttask 10).
+ *
+ * The failure this closes (mx5 run 19, `dfbdd6f`, validated): `src/server/seed.ts`
+ * reads `process.env.ADMIN_PHONE` / `ADMIN_PASSWORD` with no default, the tracked
+ * `.env.example` declares only `DATABASE_URL` + `APP_URL`, and `bun run seed` was
+ * one of the run's final-gate commands. It exited 1; the gate's autofix wrote the
+ * two vars into `.env`, which is GITIGNORED (nexttask 4) — so the committed tree
+ * still cannot seed and nothing at run end ever said why. Coverage credits the
+ * CONSUMING side (seed.ts exists, is owned, passes its own VERIFY); the template is
+ * a separate artifact nobody re-reads after TASK_0001.
+ *
+ * THE RULE. Every REQUIRED env read in TRACKED source must appear in the TRACKED
+ * env template. One-directional: a variable DECLARED but never read is silence, not
+ * a finding (dace-pro ships 13 declared / 7 required and must stay clean).
+ *
+ * REQUIRED is mechanical. A read steps aside when it:
+ *   1. carries a default — `?? …`, `|| …`, `os.getenv('X', d)`, `environ.get('X', d)`;
+ *   2. is compared, not consumed — `===`, `!==`, `==`, `!=` on either side;
+ *   3. is an assignment TARGET — `process.env.DATABASE_URL = testDbUrl`, which is
+ *      what every one of mx5's seven test files does and is the single largest FP
+ *      source in the corpus;
+ *   4. names an AMBIENT variable — a short fixed allowlist (below) of things the
+ *      platform, not the project, supplies.
+ *
+ * FP discipline (the artifact-closure discipline, one layer up):
+ *   • literal names only. `process.env[key]`, `const {A} = process.env` and every
+ *     other dynamic form is OPAQUE and steps aside — a false negative is free, a
+ *     false rank-0 gate failure is not.
+ *   • TRACKED files only, via `git ls-files`, so a gitignored `.env` or an
+ *     untracked scratch file can neither declare nor require anything.
+ *   • generated/vendored trees (`dist/`, `build/`, `node_modules/`, …) are not
+ *     authored source and are skipped; they only ever mirror a read we already saw.
+ *   • NO TEMPLATE IN THE TREE ⇒ THE CHECK IS INERT (as `repo-health-check` does
+ *     with a missing manifest). This must never invent a file the project chose
+ *     not to have.
+ *
+ * Not npm-shaped (`memory/gate-blind-on-non-npm-projects.md`): JS/TS
+ * (`process.env` / `Bun.env`), Python (`os.environ[…]`, `os.environ.get`,
+ * `os.getenv`) and Go (`os.Getenv`) read the same way. Go's `os.LookupEnv` is the
+ * explicit may-be-absent API and is treated as its own step-aside.
+ */
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import * as path from 'node:path';
+/** Variables the PLATFORM supplies, not the project. Deliberately short: every
+ *  entry is a name no `.env.example` is expected to carry. */
+export const AMBIENT_ENV = new Set([
+    'NODE_ENV',
+    'CI',
+    'PATH',
+    'HOME',
+    'TZ',
+    'PORT',
+    'USER',
+    'SHELL',
+    'TMPDIR',
+    'LANG',
+    // Windows/OS equivalents of the above, and the package manager's own vars —
+    // every one of these was OBSERVED as a "required" read during STEP 0's
+    // hand-read (gofer-rag `npm_execpath`, the pi-task corpus's `LOCALAPPDATA` /
+    // `XDG_CACHE_HOME`), and none of them belongs in a project's template.
+    'APPDATA',
+    'LOCALAPPDATA',
+    'USERPROFILE',
+    'TEMP',
+    'TMP',
+    'PWD',
+    'HOSTNAME',
+    'LOGNAME',
+    'TERM',
+    'COMSPEC'
+]);
+/** The same rule by MECHANISM rather than by name: a variable INJECTED by a
+ *  platform (CI runner, package manager, freedesktop base dirs). STEP 0 found
+ *  `GITHUB_ENV` (written by GitHub Actions), `npm_execpath` and `XDG_CACHE_HOME`
+ *  classified as required in real trees; a template that declared them would be
+ *  wrong, so the exclusion is the prefix, not a growing list of names. */
+export const AMBIENT_PREFIXES = ['npm_', 'GITHUB_', 'RUNNER_', 'CI_', 'XDG_', 'BUN_', 'NODE_'];
+/** Rule 4: is this variable the platform's to supply? */
+export function isAmbient(name) {
+    return AMBIENT_ENV.has(name) || AMBIENT_PREFIXES.some(p => name.startsWith(p));
+}
+/** Basenames that count as the project's env TEMPLATE. */
+export const ENV_TEMPLATE_NAMES = ['.env.example', '.env.sample', '.env.template', '.env.dist'];
+/** Source extensions we can read env accesses out of. */
+const SOURCE_EXT_RE = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs|py|go)$/i;
+/** Generated / vendored trees — not authored source. */
+const GENERATED_RE = /(?:^|\/)(?:node_modules|dist|build|out|vendor|coverage|\.next|\.output)\//;
+/** An inert result: what every tree with no tracked template returns. */
+export function inertClosure() {
+    return { templates: [], declared: new Set(), reads: [], missing: [] };
+}
+function git(cwd, args) {
+    const r = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    if (r.error || r.status !== 0 || typeof r.stdout !== 'string')
+        return null;
+    return r.stdout;
+}
+/** Tracked files, repo-root-relative. null when `cwd` is not a git work tree. */
+export function trackedFiles(cwd) {
+    const out = git(cwd, ['ls-files', '-z']);
+    if (out === null)
+        return null;
+    return out.split('\0').filter(p => p.length > 0);
+}
+/** Variables a template file declares. A bare `X=` line declares `X`. */
+export function parseTemplate(text) {
+    const names = [];
+    for (const raw of text.split(/\r?\n/)) {
+        const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(raw);
+        if (m)
+            names.push(m[1]);
+    }
+    return names;
+}
+/** Strip line comments so a read quoted in prose is not a read. Conservative:
+ *  only whole-line `//`, `#`, `*` and `/*` openers — never mid-line, because a
+ *  `//` inside a string literal (a URL) would eat real code. */
+function isCommentLine(line) {
+    return /^\s*(?:\/\/|#|\*|\/\*)/.test(line);
+}
+/** A trailing `, default` inside the call — `os.getenv('X', 'y')`. */
+const callHasDefault = (after) => /^\s*,/.test(after);
+const MATCHERS = [
+    // JS/TS — dotted and bracketed.
+    { re: /\b(?:process|Bun)\.env\s*\.\s*([A-Za-z_][A-Za-z0-9_]*)/g, construct: 'process.env' },
+    {
+        re: /\b(?:process|Bun)\.env\s*\[\s*['"]([A-Za-z_][A-Za-z0-9_]*)['"]\s*\]/g,
+        construct: 'process.env[]'
+    },
+    // Python.
+    {
+        re: /\bos\.environ\s*\[\s*['"]([A-Za-z_][A-Za-z0-9_]*)['"]\s*\]/g,
+        construct: 'os.environ[]'
+    },
+    {
+        re: /\bos\.environ\.get\s*\(\s*['"]([A-Za-z_][A-Za-z0-9_]*)['"]/g,
+        construct: 'os.environ.get',
+        call: true,
+        classify: (_m, after) => (callHasDefault(after) ? 'default' : null)
+    },
+    {
+        re: /\bos\.getenv\s*\(\s*['"]([A-Za-z_][A-Za-z0-9_]*)['"]/g,
+        construct: 'os.getenv',
+        call: true,
+        classify: (_m, after) => (callHasDefault(after) ? 'default' : null)
+    },
+    // Go.
+    { re: /\bos\.Getenv\s*\(\s*"([A-Za-z_][A-Za-z0-9_]*)"/g, construct: 'os.Getenv', call: true },
+    {
+        re: /\bos\.LookupEnv\s*\(\s*"([A-Za-z_][A-Za-z0-9_]*)"/g,
+        construct: 'os.LookupEnv',
+        call: true,
+        classify: () => 'optional-api'
+    }
+];
+/** Does the text right after the read supply a default, or continue onto a line
+ *  that opens with one? (`process.env.X\n    ?? 'y'` is one expression.)
+ *
+ *  A ternary CONDITION counts: `process.env.npm_execpath ? a : b` names both
+ *  outcomes, so nothing is required (gofer-rag, hand-read in STEP 0). `?.` is
+ *  optional chaining, not a ternary, and must not match. */
+function hasDefault(before, after, nextLine) {
+    // The read IS the fallback: `X ?? process.env.BRAVE_API_KEY` (brave-warning.ts)
+    // — an alternative to another source, never independently required.
+    if (/(?:\?\?|\|\|)\s*$/.test(before))
+        return true;
+    if (/^\s*(?:\?\?|\|\||\?(?![.?]))/.test(after))
+        return true;
+    if (after.trim().length === 0 && nextLine !== undefined && /^\s*(?:\?\?|\|\|)/.test(nextLine))
+        return true;
+    return false;
+}
+/**
+ * Rule 5 — a PRESENCE PROBE: the read asks whether the variable is set and the
+ * code carries on either way. Demanded by the STEP-0 hand-read, which found three
+ * shapes of it in real trees and NONE of them belongs in a template:
+ *
+ *   `if (process.env.PI_BIN) {…}`            pi-invocation.ts — a test override
+ *   `const c = process.env.CHROME_BIN`       render-check.ts — falls back to the
+ *   `if (c) …`                               Playwright cache when unset
+ *
+ * The discriminator is the SIGN of the guard, and it is exactly what separates
+ * those from the lead: mx5's seed.ts writes `const phone = process.env.ADMIN_PHONE`
+ * … `if (!phone) throw`. A NEGATED guard means the variable is required and the
+ * program stops without it; a POSITIVE guard means it is an override. So a bare
+ * `if (` / `while (` head steps aside, `if (!` does not, and an assign-then-guard
+ * is resolved by looking ahead for the FIRST guard on that variable.
+ */
+const GUARD_HEAD_RE = /\b(?:if|while)\s*\(\s*$/;
+/** How far an assign-then-guard may reach. mx5's is 4 lines; 10 is slack. */
+const GUARD_LOOKAHEAD = 10;
+function isProbeHead(before) {
+    return GUARD_HEAD_RE.test(before);
+}
+/** `const v = process.env.X` → the variable's name, else null. */
+function assignedTo(before) {
+    const m = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*$/.exec(before);
+    return m ? m[1] : null;
+}
+/**
+ * What the guard's own body does. A NEGATED guard only means "required" when the
+ * program STOPS without the variable — `if (!phone) throw` (mx5, the lead). When
+ * it merely returns or falls through — `if (!process.env.PI_REMOTE_PUSH_DEBUG)
+ * return` (push.ts, a debug flag) — the variable is optional and the negation
+ * proves nothing. Same syntax, opposite meaning; the body is the discriminator.
+ */
+const HARD_STOP_RE = /\bthrow\b|process\.exit\s*\(|\bos\.Exit\s*\(|\bsys\.exit\s*\(|\bpanic\s*\(|\braise\b/;
+const HARD_STOP_LOOKAHEAD = 3;
+function bodyStops(lines, at) {
+    for (let i = at; i < Math.min(lines.length, at + HARD_STOP_LOOKAHEAD); i++) {
+        if (HARD_STOP_RE.test(lines[i]))
+            return true;
+    }
+    return false;
+}
+/** First `if (v)` / `if (!v)` on `name` within the window. `required` only for a
+ *  negated guard that stops; anything else is an override probe. */
+function guardVerdict(lines, from, name) {
+    const re = new RegExp(`\\bif\\s*\\(\\s*(!?)\\s*${name}\\b`);
+    for (let i = from; i < Math.min(lines.length, from + GUARD_LOOKAHEAD); i++) {
+        const m = re.exec(lines[i]);
+        if (m)
+            return m[1] === '!' && bodyStops(lines, i) ? 'required' : 'probe';
+    }
+    return null;
+}
+/** Rule 6 — a file that WRITES the variable is not a consumer of the project's
+ *  env contract for it. Covers the test save/restore idiom (`prev =
+ *  process.env.X` in `beforeEach`, `process.env.X = prev` in `afterEach`), which
+ *  reads the variable only to put it back. File-scoped extension of rule 3. */
+function locallySupplied(text, name) {
+    const n = name.replace(/[$]/g, '\\$');
+    return (new RegExp(`(?:process|Bun)\\.env\\s*\\.\\s*${n}\\s*(?:\\+|\\?\\?|\\|\\|)?=(?![=>])`).test(text)
+        || new RegExp(`(?:process|Bun)\\.env\\s*\\[\\s*['"]${n}['"]\\s*\\]\\s*=(?![=>])`).test(text)
+        || new RegExp(`delete\\s+(?:process|Bun)\\.env\\s*\\.\\s*${n}\\b`).test(text)
+        || new RegExp(`\\bos\\.environ\\s*\\[\\s*['"]${n}['"]\\s*\\]\\s*=(?![=])`).test(text)
+        || new RegExp(`\\bos\\.[Ss]etenv\\s*\\(\\s*['"]${n}['"]`).test(text));
+}
+/** Rule 5b — a file that PRESENCE-CHECKS the variable positively anywhere treats
+ *  it as an override, so every read of it in that file is a probe. Without this,
+ *  the CONSUMING read inside the guarded branch — `if (process.env.PI_BIN) return
+ *  {command: process.env.PI_BIN}` (pi-invocation.ts), `process.env.GOFER_PYTHON ?
+ *  [process.env.GOFER_PYTHON] : [...]` (gofer) — reads as required. */
+function locallyProbed(text, name) {
+    const e = `(?:process|Bun)\\.env\\s*\\.\\s*${name}`;
+    return (new RegExp(`\\b(?:if|while)\\s*\\(\\s*${e}\\b`).test(text)
+        || new RegExp(`${e}\\s*\\?(?![.?])`).test(text)
+        || new RegExp(`\\bBoolean\\s*\\(\\s*${e}\\b`).test(text));
+}
+/** Comparison on either side — a probe of the environment, not a consumption. */
+function isCompared(before, after) {
+    if (/^\s*(?:===|!==|==|!=)/.test(after))
+        return true;
+    if (/(?:===|!==|==|!=)\s*$/.test(before))
+        return true;
+    return false;
+}
+/** Rule 3: the read is a WRITE — `process.env.X = …` (but not `==`/`===`), or
+ *  `delete process.env.X`. Both mean the file SUPPLIES the variable rather than
+ *  consuming it; mx5's seven test files are the assignment case and gofer's
+ *  `wdio.packaged.conf.ts` (`delete process.env.GOFER_GDFORMAT`) is the delete
+ *  case — a scrub of a developer override, the opposite of a requirement. */
+function isAssigned(before, after) {
+    if (/^\s*=(?![=>])/.test(after))
+        return true;
+    if (/\bdelete\s*$/.test(before))
+        return true;
+    return false;
+}
+/** Every literal env read in one file's text. */
+export function scanSource(file, text) {
+    const lines = text.split(/\r?\n/);
+    const reads = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (isCommentLine(line))
+            continue;
+        for (const matcher of MATCHERS) {
+            matcher.re.lastIndex = 0;
+            let m;
+            while ((m = matcher.re.exec(line)) !== null) {
+                const name = m[1];
+                const before = line.slice(0, m.index);
+                const raw = line.slice(m.index + m[0].length);
+                let stepAside = matcher.classify?.(m, raw) ?? null;
+                // Past the call's own closing paren, so an operator that applies to
+                // the RESULT is seen (`os.Getenv("X") == ""`).
+                const after = matcher.call ? raw.replace(/^\s*\)/, '') : raw;
+                // …and past any WRAPPING call's brackets, so `Number(process.env.X)
+                // || 32` (gofer-rag, the largest FP class the STEP-0 hand-read
+                // found) reads as defaulted. Stepping aside when the `||` in fact
+                // defaults an enclosing expression is a false NEGATIVE, which this
+                // check spends freely; a false rank-0 gate failure it does not.
+                // …and past a trailing accessor chain, so `process.env.X?.trim() ||
+                // '/tmp/…'` (push.ts) is the defaulted read it plainly is.
+                const unwrapped = after
+                    .replace(/^(?:\s*\??\.\s*[A-Za-z_$][\w$]*(?:\([^()]*\))?)*/, '')
+                    .replace(/^[\s)\]]+/, '');
+                if (stepAside === null && isAmbient(name))
+                    stepAside = 'ambient';
+                if (stepAside === null && isAssigned(before, after))
+                    stepAside = 'assigned';
+                if (stepAside === null && isCompared(before, unwrapped))
+                    stepAside = 'compared';
+                if (stepAside === null && hasDefault(before, unwrapped, lines[i + 1]))
+                    stepAside = 'default';
+                if (stepAside === null && locallySupplied(text, name))
+                    stepAside = 'assigned';
+                if (stepAside === null && (isProbeHead(before) || locallyProbed(text, name)))
+                    stepAside = 'probe';
+                // `if (!process.env.X) …` — required only if the body stops.
+                if (stepAside === null
+                    && /\b(?:if|while)\s*\(\s*!\s*$/.test(before)
+                    && !bodyStops(lines, i))
+                    stepAside = 'probe';
+                if (stepAside === null) {
+                    const v = assignedTo(before);
+                    if (v !== null && guardVerdict(lines, i + 1, v) === 'probe')
+                        stepAside = 'probe';
+                }
+                reads.push({ name, file, line: i + 1, construct: matcher.construct, stepAside });
+            }
+        }
+    }
+    return reads;
+}
+/**
+ * Scan a tree: tracked templates × required reads in tracked source.
+ *
+ * Inert (empty templates, no findings) when the tree is not a git work tree or
+ * carries no tracked env template — the ENOENT=pass contract.
+ */
+export function scanEnvTemplateClosure(cwd) {
+    const tracked = trackedFiles(cwd);
+    if (tracked === null)
+        return inertClosure();
+    const templates = tracked.filter(p => ENV_TEMPLATE_NAMES.includes(path.posix.basename(p)));
+    if (templates.length === 0)
+        return inertClosure();
+    const declared = new Set();
+    for (const t of templates) {
+        try {
+            for (const n of parseTemplate(readFileSync(path.join(cwd, t), 'utf8')))
+                declared.add(n);
+        }
+        catch {
+            // a tracked-but-absent template (dirty worktree) declares nothing
+        }
+    }
+    const reads = [];
+    for (const f of tracked) {
+        if (!SOURCE_EXT_RE.test(f) || GENERATED_RE.test(f))
+            continue;
+        let text;
+        try {
+            text = readFileSync(path.join(cwd, f), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        // Cheap prefilter. Case-insensitive substring, NOT a word boundary:
+        // `os.Getenv(` / `os.LookupEnv(` carry no boundary before `env`, and a
+        // boundary-anchored filter silently drops every Go file (caught by the
+        // go fixture in STEP 0).
+        if (!/env/i.test(text))
+            continue;
+        reads.push(...scanSource(f, text));
+    }
+    const missing = reads.filter(r => r.stepAside === null && !declared.has(r.name));
+    return { templates, declared, reads, missing };
+}
+/**
+ * The gate's view: one finding per VARIABLE (first read site, source order), not
+ * one per read — a var read in four files is one artifact defect, and the ranked
+ * failure list is read by a human and seeds the autofix prompt.
+ */
+export function findMissingEnvDeclarations(cwd) {
+    const c = scanEnvTemplateClosure(cwd);
+    const seen = new Set();
+    const missing = [];
+    for (const r of c.missing) {
+        if (seen.has(r.name))
+            continue;
+        seen.add(r.name);
+        missing.push(r);
+    }
+    return { templates: c.templates, missing };
+}
+/** One finding, as the final gate would phrase it. */
+export function envGateFailureText(t, templates) {
+    return (`env closure: \`${t.name}\` is required by ${t.file}:${t.line} (${t.construct}) but no `
+        + `tracked env template declares it (${templates.join(', ')}) — a fresh clone cannot `
+        + 'supply it.');
+}

package/dist/task/final-gate.js

@@ -58,6 +58,7 @@ import { collectProjectEnv, pinnedLocalPort, runDeepRenderCheck } from './deep-r
 import { resolveRunner, runnerEnv, isCommandNotFound } from './runner-resolve.js';
 import { taskThatIntroduced } from './task-provenance.js';
 import { findDanglingArtifacts, danglingGateFailureText } from './artifact-closure.js';
+import { findMissingEnvDeclarations, envGateFailureText } from './env-template-closure.js';
 import { findMissingServeEntry, serveEntryGateFailureText } from './serve-entry.js';
 import { makefileRecipe } from './command-shrink.js';
 function packageScripts(cwd) {
@@ -1604,6 +1605,22 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
     catch {
         // best-effort scan — a scanner fault must never break the gate
     }
+    // Env-template closure (mx5 run 19, nexttask 10): a shipped source file
+    // requires an env var the shipped template never mentions. `seed.ts` read
+    // `process.env.ADMIN_PHONE`/`ADMIN_PASSWORD`, `.env.example` declared neither,
+    // `bun run seed` exited 1, and the autofix "fixed" it by writing the GITIGNORED
+    // `.env` — so the committed tree still cannot seed and nothing at run end said
+    // why. Same shape and rank as the dangling-artifact scan one layer up: naming
+    // the ARTIFACT that is wrong, statically, instead of only the command that
+    // failed. Inert on any tree with no tracked template (ENOENT = pass).
+    try {
+        const env = findMissingEnvDeclarations(cwd);
+        for (const m of env.missing)
+            fail(envGateFailureText(m, env.templates), 0);
+    }
+    catch {
+        // best-effort scan — a scanner fault must never break the gate
+    }
     if (failures.length > 0) {
         // Stable sort: boot/render (rank 0) leads, everything else keeps execution
         // order. One failure keeps the exact single-failure wording; several become

package/dist/task/phases.d.ts

@@ -158,6 +158,27 @@ export interface PhaseAutoAnswerDeps {
 }
 export declare function phaseAutoAnswer(deps: PhaseDeps, refined: string, research: string, question: string, autoDeps?: PhaseAutoAnswerDeps): Promise<AutoAnswer>;
 export declare function phaseGrill(deps: PhaseDeps, ctx: ExtensionCommandContext, widgetState: WidgetState, refined: string, research: string): Promise<string>;
+/**
+ * A refutation is a DELETION. Where the run's own research explicitly says a
+ * dependency refine invented is not needed, drop that token from CONSTRAINTS —
+ * compose cannot forbid the design's own API "because the refined task
+ * explicitly requires `argon2`" if the refined task no longer requires it.
+ *
+ * Applied to the REFINED TASK ITSELF, not to compose's copy of it, and that is
+ * load-bearing: critique receives the refined task as GROUND TRUTH and is told
+ * its CONSTRAINTS "MUST be preserved in spirit — do not silently drop or weaken
+ * them", so a deletion visible only to compose is restored one phase later. Both
+ * spec-producing phases have to see the same text.
+ *
+ * Purely subtractive and never touches an owned line (task/refuted-constraint.ts).
+ * Idempotent, so a resumed run re-deriving `refined` from the task file lands in
+ * the same place. The task file's `## refined prompt` is deliberately left as
+ * refine wrote it; the drop is recorded on the `## gates` trail with both source
+ * lines quoted, so the decision stays auditable after the fact.
+ *
+ * STEP 0 `scripts/refuted-constraint-baserate.ts`; A/B-1 `…-ab.ts` (PASS).
+ */
+export declare function dropRefutedConstraints(deps: PhaseDeps, refined: string, research: string): Promise<string>;
 export declare function phaseCompose(deps: PhaseDeps, refined: string, research: string, qa: string): Promise<string>;
 export declare function phaseCritique(deps: PhaseDeps, spec: string, refined: string, qa: string, planContext?: string, research?: string, 
 /**

package/dist/task/phases.js

@@ -23,7 +23,8 @@ import { resolve } from 'node:path';
 import { formatServiceBlock, formatFreshnessSkippedBlock } from './service-blocks.js';
 import { gatherExternalContext } from './external-context.js';
 import { REFINE_PROMPT, RESEARCH_FILES_PROMPT, RESEARCH_APIS_PROMPT, RESEARCH_CONTEXT_PROMPT, RESEARCH_TOOLING_PROMPT, GRILL_GEN_PROMPT, GRILL_AUTO_ANSWER_PROMPT, GRILL_AUTO_FORMAT_HINT, COMPOSE_PROMPT, CRITIQUE_PROMPT, CRITIQUE_TRIAGE_PROMPT, VERIFY_TOOLING_PROMPT, MAX_GRILL_QUESTIONS, appendNoThink } from './prompts.js';
-import { readSection, removeTaskSection, setTaskSection, updateTaskFrontMatter } from './task-io.js';
+import { appendGateRecord, readSection, removeTaskSection, setTaskSection, updateTaskFrontMatter } from './task-io.js';
+import { applyRefutations } from './refuted-constraint.js';
 import { spawnSync } from 'node:child_process';
 import { renderInlineMarkdown, stripInlineMarkdown } from './inline-markdown.js';
 import { isDuplicateQuestion, MAX_DUP_STRIKES, DUP_REPROMPT_HINT } from './question-dedup.js';
@@ -639,13 +640,21 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
     // the pattern nexxtasks exists to prevent. To re-run the experiment, restore the block
     // this comment replaces — see the git history of this file and the PROMPT 4 entry in
     // nexxtasks.txt RESULTS.
-    // nexttask 5B fan-out bounds. Both read their env ONCE per research phase, so
-    // every worker in a run sees the same policy and a harness cannot half-apply
-    // an arm; both are null in the shipped configuration.
+    // nexttask 5B fan-out bounds. All four read their env ONCE per research
+    // phase, so every worker in a run sees the same policy and a harness cannot
+    // half-apply an arm. CAP, SCALE and carry-forward are null/false in the
+    // shipped configuration; the progress deadline shipped ON (nexttask 9).
     const fanoutBudget = projectDocsBudget();
     const fanoutTimeout = fanoutTimeoutPolicy();
     const carryForward = workerCarryForward();
     const progressCeilingMs = workerProgressCeilingMs();
+    // Which deadline policy was in force is a fact about how every number below
+    // was produced. Run 18's 120 discarded minutes were only recoverable because
+    // 5A started writing down what the workers actually did; a run whose logs do
+    // not say which policy it ran under cannot be compared with one that does.
+    deps.logDebug?.(progressCeilingMs === null ?
+        'phase:research: worker deadline = fixed elapsed cap (progress deadline DISABLED)'
+        : `phase:research: worker deadline = no-progress, ceiling ${progressCeilingMs}ms`);
     let doneCount = 0;
     const updateProgress = () => {
         doneCount++;
@@ -842,9 +851,11 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             // 5B SCALE arm — null unless both env vars are set. Only the
             // docs-capable worker can fan out, so only it can be scaled.
             ...(spec.fanoutBounded && fanoutTimeout ? { fanoutTimeout } : {}),
-            // 5B RESCUE arm — off unless its env vars are set. Applies to
-            // EVERY research worker, not just the docs-capable one: any
-            // worker that gets killed loses its work the same way.
+            // 5B RESCUE. Applies to EVERY research worker, not just the
+            // docs-capable one: any worker that gets killed loses its work
+            // the same way. carry-forward stays OFF unless asked for
+            // (measured harmful on its own); the progress deadline SHIPPED
+            // ON in nexttask 9 and is null only when explicitly disabled.
             ...(carryForward ? { carryForward: true } : {}),
             ...(progressCeilingMs !== null ?
                 { progressTimeoutCeilingMs: progressCeilingMs }
@@ -1324,6 +1335,36 @@ export async function phaseGrill(deps, ctx, widgetState, refined, research) {
         return '(no questions produced)';
     return out.join('\n');
 }
+/**
+ * A refutation is a DELETION. Where the run's own research explicitly says a
+ * dependency refine invented is not needed, drop that token from CONSTRAINTS —
+ * compose cannot forbid the design's own API "because the refined task
+ * explicitly requires `argon2`" if the refined task no longer requires it.
+ *
+ * Applied to the REFINED TASK ITSELF, not to compose's copy of it, and that is
+ * load-bearing: critique receives the refined task as GROUND TRUTH and is told
+ * its CONSTRAINTS "MUST be preserved in spirit — do not silently drop or weaken
+ * them", so a deletion visible only to compose is restored one phase later. Both
+ * spec-producing phases have to see the same text.
+ *
+ * Purely subtractive and never touches an owned line (task/refuted-constraint.ts).
+ * Idempotent, so a resumed run re-deriving `refined` from the task file lands in
+ * the same place. The task file's `## refined prompt` is deliberately left as
+ * refine wrote it; the drop is recorded on the `## gates` trail with both source
+ * lines quoted, so the decision stays auditable after the fact.
+ *
+ * STEP 0 `scripts/refuted-constraint-baserate.ts`; A/B-1 `…-ab.ts` (PASS).
+ */
+export async function dropRefutedConstraints(deps, refined, research) {
+    const refuted = applyRefutations(refined, research);
+    if (refuted.trail.length === 0)
+        return refined;
+    for (const line of refuted.trail) {
+        deps.logDebug?.(`compose: ${line}`);
+        await appendGateRecord(deps.cwd, deps.taskId, line).catch(() => { });
+    }
+    return refuted.refined;
+}
 export async function phaseCompose(deps, refined, research, qa) {
     // CLAIM before the belt is built: an obligation an earlier task had to
     // detach (its own spec froze the only file that could satisfy it) becomes
@@ -1627,7 +1668,10 @@ export const PHASES = [
         name: 'compose',
         section: 'spec',
         field: 'spec',
-        run: (d, p) => phaseCompose(d, p.refined, p.research, p.qa)
+        run: async (d, p) => {
+            p.refined = await dropRefutedConstraints(d, p.refined, p.research);
+            return await phaseCompose(d, p.refined, p.research, p.qa);
+        }
     },
     {
         name: 'critique',

package/dist/task/refuted-constraint.d.ts

@@ -0,0 +1,82 @@
+/**
+ * A refutation is a DELETION, not an addition.
+ *
+ * THE LEAD (mx5 run 19, `~/hub/mx5 @ dfbdd6f`, TASK_0001). Refine invented a
+ * dependency the design explicitly rules out; the run's own research said so, in
+ * writing, in the same file; the composed spec then turned the invention into a
+ * capitalised prohibition against the design's own API:
+ *
+ *   :21   refine CONSTRAINTS   "Add only new entries the task requires (e.g.,
+ *                              `hono`, `bun-sql`-equivalent, …, `argon2`, …)"
+ *   :92   research CONTEXT     "Password hashing uses `Bun.password` (built-in
+ *                              argon2id) — no external `argon2` or
+ *                              `@node-rs/argon2` dependency needed despite the
+ *                              task's mention of it."
+ *   :132  spec CONSTRAINTS     "Do NOT use built-in `Bun.password` for hashing —
+ *                              the refined task explicitly requires `argon2`."
+ *
+ * `argon2@^0.41.0` shipped as a runtime dependency of a repo that never imports
+ * it, locked in by a VERIFY assertion, next to a spec telling the next
+ * implementer not to use `Bun.sql` — the API the whole data layer is built on.
+ *
+ * This is `memory/phantom-correction-additive-not-subtractive.md` at spec scale:
+ * the correction was APPENDED to research CONTEXT while the wrong text stayed in
+ * refine's CONSTRAINTS, and CONSTRAINTS is what the implementer is told is
+ * authoritative.
+ *
+ * THE LEVER. Deterministic detection, then a scoped removal, BEFORE compose sees
+ * the refined task. Never a model rewrite: every model-rewrite lever at this seam
+ * has resolved contradictions by deleting the AUTHORITATIVE side
+ * (`memory/owned-freeze-critique-lever-refuted.md`, 11/20). This pass can only
+ * delete a refine-invented token, and can never touch an owned line.
+ *
+ * The match is lexical, never semantic: a research CONTEXT bullet refutes a
+ * refine constraint when it carries one of a closed set of negation-of-need
+ * shapes AROUND a backticked token, and that same token appears backticked in a
+ * refine CONSTRAINTS line. Both sides are already separate strings in the task
+ * file.
+ *
+ * STEP 0 (`scripts/refuted-constraint-baserate.ts`) measured the closed set over
+ * every recorded task file in the corpus before any of it was wired.
+ */
+export type Refutation = {
+    /** The token as it appears inside the backticks, e.g. `argon2`. */
+    token: string;
+    /** Index into the refined prompt's lines. */
+    line: number;
+    /** The refine CONSTRAINTS line, verbatim, before the drop. */
+    constraint: string;
+    /** The research CONTEXT bullet that refutes it, verbatim. */
+    research: string;
+    /** Which member of the closed negation set fired. */
+    pattern: string;
+};
+/** Section body between a bare ALL-CAPS header and the next one (or EOF). */
+export declare function extractCapsSection(text: string, heading: string): string | null;
+/**
+ * Find every (refine constraint line, research refutation bullet, shared token)
+ * triple. `refined` is the refined prompt, `research` the research output; both
+ * are the exact strings compose is handed.
+ */
+export declare function detectRefutations(refined: string, research: string): Refutation[];
+/**
+ * Delete one token from a constraint line: the backticked span, any word-suffix
+ * glued to it (`` `bun-sql` ``-equivalent), and ONE adjacent list separator —
+ * the preceding one where there is one, so the list keeps its shape.
+ *
+ * Returns null when nothing but boilerplate would be left, which the caller
+ * turns into a whole-line drop. Never rephrases, never adds a character.
+ */
+export declare function dropToken(line: string, token: string): string | null;
+export type RefutationResult = {
+    /** The refined prompt with every refuted token deleted. */
+    refined: string;
+    /** One trail line per drop, both source lines quoted. */
+    trail: string[];
+    refutations: Refutation[];
+};
+/**
+ * Apply every detected refutation to the refined prompt. Purely subtractive: the
+ * result is always a character subsequence of the input (`inv-no-line-invention`).
+ */
+export declare function applyRefutations(refined: string, research: string): RefutationResult;

package/dist/task/refuted-constraint.js

@@ -0,0 +1,281 @@
+/**
+ * A refutation is a DELETION, not an addition.
+ *
+ * THE LEAD (mx5 run 19, `~/hub/mx5 @ dfbdd6f`, TASK_0001). Refine invented a
+ * dependency the design explicitly rules out; the run's own research said so, in
+ * writing, in the same file; the composed spec then turned the invention into a
+ * capitalised prohibition against the design's own API:
+ *
+ *   :21   refine CONSTRAINTS   "Add only new entries the task requires (e.g.,
+ *                              `hono`, `bun-sql`-equivalent, …, `argon2`, …)"
+ *   :92   research CONTEXT     "Password hashing uses `Bun.password` (built-in
+ *                              argon2id) — no external `argon2` or
+ *                              `@node-rs/argon2` dependency needed despite the
+ *                              task's mention of it."
+ *   :132  spec CONSTRAINTS     "Do NOT use built-in `Bun.password` for hashing —
+ *                              the refined task explicitly requires `argon2`."
+ *
+ * `argon2@^0.41.0` shipped as a runtime dependency of a repo that never imports
+ * it, locked in by a VERIFY assertion, next to a spec telling the next
+ * implementer not to use `Bun.sql` — the API the whole data layer is built on.
+ *
+ * This is `memory/phantom-correction-additive-not-subtractive.md` at spec scale:
+ * the correction was APPENDED to research CONTEXT while the wrong text stayed in
+ * refine's CONSTRAINTS, and CONSTRAINTS is what the implementer is told is
+ * authoritative.
+ *
+ * THE LEVER. Deterministic detection, then a scoped removal, BEFORE compose sees
+ * the refined task. Never a model rewrite: every model-rewrite lever at this seam
+ * has resolved contradictions by deleting the AUTHORITATIVE side
+ * (`memory/owned-freeze-critique-lever-refuted.md`, 11/20). This pass can only
+ * delete a refine-invented token, and can never touch an owned line.
+ *
+ * The match is lexical, never semantic: a research CONTEXT bullet refutes a
+ * refine constraint when it carries one of a closed set of negation-of-need
+ * shapes AROUND a backticked token, and that same token appears backticked in a
+ * refine CONSTRAINTS line. Both sides are already separate strings in the task
+ * file.
+ *
+ * STEP 0 (`scripts/refuted-constraint-baserate.ts`) measured the closed set over
+ * every recorded task file in the corpus before any of it was wired.
+ */
+/** Bare ALL-CAPS section header, the boundary convention used across the
+ *  refined prompt and every research section. */
+const HEADER = /^[A-Z][A-Z -]*$/;
+/** A backticked run with no whitespace inside — the only thing this pass will
+ *  ever treat as a token. */
+const TOKEN = '`[^`\\s]+`';
+/** One token, or a list of them joined by `,` / `or` / `and`. */
+const TOKEN_LIST = `${TOKEN}(?:(?:\\s*,\\s*|\\s+or\\s+|\\s+and\\s+)${TOKEN})*`;
+/**
+ * The closed negation set. Each pattern anchors the token list INSIDE the
+ * negation, so a bullet that names one package negatively and another positively
+ * ("no `@node-rs/argon2` dependency — we use `argon2`") can only ever refute the
+ * one inside the phrase.
+ *
+ * Kept deliberately small. `inv-precision` is a FAIL of the whole task on one
+ * false drop, so a shape earns its place here only by surviving a hand-read of
+ * every corpus hit it produces.
+ */
+const NEGATIONS = [
+    {
+        // "no external `argon2` or `@node-rs/argon2` dependency needed" — THE LEAD
+        name: 'no-external-dep-needed',
+        re: new RegExp(`\\bno\\s+external\\s+(${TOKEN_LIST})\\s+(?:\\w+\\s+){0,2}dependenc(?:y|ies)\\b[^.;]{0,40}?\\b(?:needed|required)\\b`, 'i')
+    },
+    {
+        // "no `bun-sql` npm package exists"
+        name: 'no-package-exists',
+        re: new RegExp(`\\bno\\s+(${TOKEN_LIST})\\s+(?:npm\\s+)?(?:package|module)\\s+exists\\b`, 'i')
+    },
+    {
+        // "no `argon2` dependency is needed".
+        //
+        // The trailing need-negation is NOT optional, and STEP 0 is why. The
+        // first cut of this pattern was the bare "no `X` dependency", and it
+        // fired 300 times in 306 corpus hits — every one of them on a
+        // MANIFEST-STATE bullet that says the exact opposite of a refutation:
+        //
+        //   "`package.json` currently lists no `hono` or `@hono/zod-validator`
+        //    dependencies; they MUST BE ADDED at versions 4.12.27 and 0.8.0"
+        //   "`package.json` has … and no `sharp` dependency — MUST ADD `sharp`
+        //    as devDependency"
+        //
+        // Dropping on that signal mutilated real constraints ("use  with the
+        // shared `loginSchema`"). "The repo does not have X yet" is a fact about
+        // the tree; "X is not needed" is a claim about the task. Only the second
+        // one refutes anything.
+        name: 'no-dep-needed',
+        re: new RegExp(`\\bno\\s+(${TOKEN_LIST})\\s+dependenc(?:y|ies)\\s+(?:is\\s+|are\\s+)?(?:needed|required|necessary)\\b`, 'i')
+    },
+    // The two shapes below name no dependency noun of their own, so they carry a
+    // DEP_WORD guard. STEP 0's near-miss census is the reason: "does not require"
+    // appears in 412 corpus CONTEXT bullets, and the shape is overwhelmingly
+    // prose about behaviour, not dependencies — "the `GET /api/listings`
+    // endpoint does NOT require authentication for the `mine` filter". Token
+    // adjacency alone would eventually reach a backticked API expression there.
+    {
+        // "`argon2` is not needed" / "`argon2` and `sharp` are not required"
+        name: 'not-needed',
+        re: new RegExp(`(${TOKEN_LIST})\\s+(?:is|are)\\s+not\\s+(?:needed|required)\\b`, 'i'),
+        needsDepWord: true
+    },
+    {
+        // "does not require `argon2`"
+        name: 'does-not-require',
+        re: new RegExp(`\\b(?:does|do)\\s+not\\s+require\\s+(${TOKEN_LIST})`, 'i'),
+        needsDepWord: true
+    }
+];
+/** The claim has to be ABOUT a dependency for a dependency to be dropped. */
+const DEP_WORD = /\bdependenc(?:y|ies)\b|\bnpm\b|\bpackages?\b|\bdevDependenc(?:y|ies)\b/i;
+/** The owned-requirement stamp (requirements.ts:813). A line carrying it is a
+ *  design-sourced obligation and is NEVER refutable by research — this is the
+ *  guard that keeps this pass out of nexttask 2's failure mode. */
+const OWNED_MARKER = 'owned requirement from the source design';
+/** Section body between a bare ALL-CAPS header and the next one (or EOF). */
+export function extractCapsSection(text, heading) {
+    const lines = text.split('\n');
+    const start = lines.findIndex(l => l.trim() === heading);
+    if (start === -1)
+        return null;
+    const rest = lines.slice(start + 1);
+    const end = rest.findIndex(l => HEADER.test(l.trim()) && l.trim().length > 1);
+    return (end === -1 ? rest : rest.slice(0, end)).join('\n');
+}
+function tokensIn(span) {
+    return [...span.matchAll(/`([^`\s]+)`/g)].map(m => m[1]);
+}
+/**
+ * Does this look like a package/module name at all? Refutations are about
+ * DEPENDENCIES; a backticked prose fragment, a path, or an API expression is not
+ * one, and dropping it from a constraint would be a semantic edit.
+ */
+function isPackageToken(tok) {
+    if (tok.length > 64)
+        return false;
+    if (!/^@?[a-z0-9][a-z0-9._/-]*$/i.test(tok))
+        return false;
+    // `Bun.password`, `p.dependencies` — dotted API expressions, not packages.
+    if (/^[A-Z]/.test(tok))
+        return false;
+    return true;
+}
+/** Every research CONTEXT bullet, one entry per bullet (continuations joined). */
+function bullets(section) {
+    const out = [];
+    for (const raw of section.split('\n')) {
+        const line = raw.trimEnd();
+        if (!line.trim())
+            continue;
+        if (/^\s*[-*]\s+/.test(line))
+            out.push(line.trim());
+        else if (out.length > 0)
+            out[out.length - 1] += ` ${line.trim()}`;
+    }
+    return out.length > 0 ? out : section.split('\n').filter(l => l.trim());
+}
+/**
+ * Find every (refine constraint line, research refutation bullet, shared token)
+ * triple. `refined` is the refined prompt, `research` the research output; both
+ * are the exact strings compose is handed.
+ */
+export function detectRefutations(refined, research) {
+    const constraintsBody = extractCapsSection(refined, 'CONSTRAINTS');
+    const contextBody = extractCapsSection(research, 'CONTEXT');
+    if (constraintsBody === null || contextBody === null)
+        return [];
+    // Refuted token → the bullet that refuted it, and the pattern that fired.
+    const refuted = new Map();
+    for (const bullet of bullets(contextBody)) {
+        for (const { name, re, needsDepWord } of NEGATIONS) {
+            const m = re.exec(bullet);
+            if (!m)
+                continue;
+            if (needsDepWord && !DEP_WORD.test(bullet))
+                continue;
+            for (const tok of tokensIn(m[1])) {
+                if (!isPackageToken(tok))
+                    continue;
+                if (!refuted.has(tok))
+                    refuted.set(tok, { research: bullet, pattern: name });
+            }
+        }
+    }
+    if (refuted.size === 0)
+        return [];
+    const lines = refined.split('\n');
+    const constraintStart = lines.findIndex(l => l.trim() === 'CONSTRAINTS');
+    const out = [];
+    for (let i = constraintStart + 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (HEADER.test(line.trim()) && line.trim().length > 1)
+            break;
+        if (line.includes(OWNED_MARKER))
+            continue;
+        for (const [tok, src] of refuted) {
+            if (!new RegExp(`\`${escapeRe(tok)}\``).test(line))
+                continue;
+            out.push({
+                token: tok,
+                line: i,
+                constraint: line,
+                research: src.research,
+                pattern: src.pattern
+            });
+        }
+    }
+    return out;
+}
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Delete one token from a constraint line: the backticked span, any word-suffix
+ * glued to it (`` `bun-sql` ``-equivalent), and ONE adjacent list separator —
+ * the preceding one where there is one, so the list keeps its shape.
+ *
+ * Returns null when nothing but boilerplate would be left, which the caller
+ * turns into a whole-line drop. Never rephrases, never adds a character.
+ */
+export function dropToken(line, token) {
+    const tokRe = new RegExp(`\`${escapeRe(token)}\`[A-Za-z0-9-]*`, 'g');
+    let next = line;
+    for (;;) {
+        const m = tokRe.exec(next);
+        if (!m)
+            break;
+        const start = m.index;
+        const end = start + m[0].length;
+        // Prefer eating the separator BEFORE the token; fall back to the one
+        // after it (first element of a list).
+        const before = next.slice(0, start);
+        const sepBefore = /(?:,\s*|\s+or\s+|\s+and\s+)$/.exec(before);
+        if (sepBefore) {
+            next = next.slice(0, start - sepBefore[0].length) + next.slice(end);
+        }
+        else {
+            const sepAfter = /^(?:\s*,\s*|\s+or\s+|\s+and\s+)/.exec(next.slice(end));
+            next = before + next.slice(end + (sepAfter ? sepAfter[0].length : 0));
+        }
+        tokRe.lastIndex = 0;
+    }
+    if (next === line)
+        return line;
+    // An emptied list ("(e.g., )") or an emptied bullet is a whole-line drop.
+    const carcass = next
+        .replace(/^\s*[-*]\s*/, '')
+        .replace(/\(\s*e\.g\.,?\s*\)/gi, '')
+        .replace(/[\s,.;:()]/g, '');
+    if (carcass.length === 0)
+        return null;
+    return next;
+}
+/**
+ * Apply every detected refutation to the refined prompt. Purely subtractive: the
+ * result is always a character subsequence of the input (`inv-no-line-invention`).
+ */
+export function applyRefutations(refined, research) {
+    const refutations = detectRefutations(refined, research);
+    if (refutations.length === 0)
+        return { refined, trail: [], refutations };
+    const lines = refined.split('\n');
+    const dropped = new Set();
+    const trail = [];
+    for (const r of refutations) {
+        const current = lines[r.line];
+        const next = dropToken(current, r.token);
+        if (next === null) {
+            dropped.add(r.line);
+            trail.push(`constraint refuted by research — dropped the whole CONSTRAINTS line for '${r.token}'`
+                + ` | constraint: "${r.constraint.trim()}" | research: "${r.research.trim()}"`);
+        }
+        else {
+            lines[r.line] = next;
+            trail.push(`constraint refuted by research — dropped '${r.token}' from CONSTRAINTS`
+                + ` | constraint: "${r.constraint.trim()}" | research: "${r.research.trim()}"`);
+        }
+    }
+    const kept = lines.filter((_l, i) => !dropped.has(i));
+    return { refined: kept.join('\n'), trail, refutations };
+}

package/dist/task/research-fanout-budget.d.ts

@@ -1,13 +1,18 @@
 /**
  * nexttask 5B — the two candidate bounds on worker:apis's project-source fan-out.
  *
- * ⚠ NOT WIRED. Both levers here are OFF unless their env var is set, so the
- * shipped path is bit-for-bit what it was. They exist so
- * `scripts/live-research-fanout-budget-ab.ts` can run them against the shipped
- * baseline in the SAME build — the alternative (dist surgery) measures a patched
- * copy of the code and not the code. Nothing may read these outside that harness
- * until it reports PASS; a lever wired on argument rather than measurement is the
- * failure mode nexttasks exists to prevent.
+ * ⚠ ONE of the levers in this file is wired: the RESCUE progress deadline
+ * (`workerProgressCeilingMs`) SHIPPED ON in nexttask 9, on a PASS measured over 42
+ * trials per arm against an instrument whose own false-break rate is on record at
+ * 1.5%. CAP, SCALE and RESCUE-CARRY remain OFF unless their env var is set — CAP
+ * and SCALE were rejected on argument (see below), carry-forward was measured
+ * HARMFUL on its own.
+ *
+ * The OFF levers exist so `scripts/live-research-fanout-budget-ab.ts` can run them
+ * against the shipped baseline in the SAME build — the alternative (dist surgery)
+ * measures a patched copy of the code and not the code. Nothing may read them
+ * outside that harness until it reports PASS; a lever wired on argument rather
+ * than measurement is the failure mode nexttasks exists to prevent.
  *
  * THE FAULT THEY TARGET (mx5 run 18, measured — scripts/research-restart-baserate.ts):
  * `worker:apis` fans out `pi-worker-docs(module: ".")` project-source lookups, each
@@ -102,9 +107,40 @@ export declare function fanoutTimeoutPolicy(env?: Env): {
  */
 export declare function workerCarryForward(env?: Env): boolean;
 /**
- * The absolute backstop for the progress-based deadline, or null when off.
- * Required rather than defaulted: a progress deadline with no ceiling is an
- * unbounded worker, which is the one thing the fixed cap exists to prevent.
+ * The absolute backstop for the progress-based deadline.
+ *
+ * WHY THIS NUMBER. It is not a budget and it does not decide how long a worker
+ * may take — the no-progress deadline does that, and it resets on every tool call.
+ * This is the last-resort bound on a worker that never stops moving (an infinite
+ * tool-call loop the loop detector somehow misses), so its only requirement is to
+ * sit clear of the real workload. Measured on 42 progress-arm trials
+ * (`~/tmp/research-fanout-ab-v3`): median 275s, p90 523s, **max 730s**. 20 minutes
+ * is 1.6x the observed worst case, and 1.7x the 720s the SHIPPED path already
+ * spends on a worker that burns all three attempts and returns nothing.
+ *
+ * A ceiling that never fires in production is the correct behaviour for a
+ * backstop, not evidence it is untested: it fires under test
+ * (`pi-worker-core.test.ts` — 'the absolute ceiling still bounds a worker that
+ * never stops moving'), and a worker that goes QUIET is killed long before it, at
+ * `timeoutMs` without progress and by the stall probe.
+ */
+export declare const DEFAULT_WORKER_PROGRESS_CEILING_MS = 1200000;
+/**
+ * The progress-based deadline's ceiling, or null when the lever is OFF.
+ *
+ * SHIPPED ON as of nexttask 9 — the env var is now the OFF switch, not the on
+ * switch. Measured baseline vs progress over 42 trials/arm on a calibrated
+ * instrument (A/A false-break 1.5%): worker-timeout restarts 22/24 → 0/24,
+ * degrades 8/24 → 0/24, entries up on all four high-fan-out fixtures (TASK_0021
+ * 11.0 → 25.5), quality invariants HOLD, every treatment-arm ungrounded flag
+ * hand-verified as an instrument artifact rather than a fabrication.
+ *
+ *     unset            ON at DEFAULT_WORKER_PROGRESS_CEILING_MS
+ *     "0" | "off"      OFF — the fixed elapsed-time cap, exactly as before
+ *     positive int     ON at that ceiling, in ms
+ *
+ * A garbage value keeps the SHIPPED behaviour rather than silently disabling the
+ * lever: turning it off is a decision and has to be spelled.
  */
 export declare function workerProgressCeilingMs(env?: Env): number | null;
 /**

package/dist/task/research-fanout-budget.js

@@ -1,13 +1,18 @@
 /**
  * nexttask 5B — the two candidate bounds on worker:apis's project-source fan-out.
  *
- * ⚠ NOT WIRED. Both levers here are OFF unless their env var is set, so the
- * shipped path is bit-for-bit what it was. They exist so
- * `scripts/live-research-fanout-budget-ab.ts` can run them against the shipped
- * baseline in the SAME build — the alternative (dist surgery) measures a patched
- * copy of the code and not the code. Nothing may read these outside that harness
- * until it reports PASS; a lever wired on argument rather than measurement is the
- * failure mode nexttasks exists to prevent.
+ * ⚠ ONE of the levers in this file is wired: the RESCUE progress deadline
+ * (`workerProgressCeilingMs`) SHIPPED ON in nexttask 9, on a PASS measured over 42
+ * trials per arm against an instrument whose own false-break rate is on record at
+ * 1.5%. CAP, SCALE and RESCUE-CARRY remain OFF unless their env var is set — CAP
+ * and SCALE were rejected on argument (see below), carry-forward was measured
+ * HARMFUL on its own.
+ *
+ * The OFF levers exist so `scripts/live-research-fanout-budget-ab.ts` can run them
+ * against the shipped baseline in the SAME build — the alternative (dist surgery)
+ * measures a patched copy of the code and not the code. Nothing may read them
+ * outside that harness until it reports PASS; a lever wired on argument rather
+ * than measurement is the failure mode nexttasks exists to prevent.
  *
  * THE FAULT THEY TARGET (mx5 run 18, measured — scripts/research-restart-baserate.ts):
  * `worker:apis` fans out `pi-worker-docs(module: ".")` project-source lookups, each
@@ -113,12 +118,48 @@ export function workerCarryForward(env = defaultEnv) {
     return env(WORKER_CARRY_FORWARD_ENV) === '1';
 }
 /**
- * The absolute backstop for the progress-based deadline, or null when off.
- * Required rather than defaulted: a progress deadline with no ceiling is an
- * unbounded worker, which is the one thing the fixed cap exists to prevent.
+ * The absolute backstop for the progress-based deadline.
+ *
+ * WHY THIS NUMBER. It is not a budget and it does not decide how long a worker
+ * may take — the no-progress deadline does that, and it resets on every tool call.
+ * This is the last-resort bound on a worker that never stops moving (an infinite
+ * tool-call loop the loop detector somehow misses), so its only requirement is to
+ * sit clear of the real workload. Measured on 42 progress-arm trials
+ * (`~/tmp/research-fanout-ab-v3`): median 275s, p90 523s, **max 730s**. 20 minutes
+ * is 1.6x the observed worst case, and 1.7x the 720s the SHIPPED path already
+ * spends on a worker that burns all three attempts and returns nothing.
+ *
+ * A ceiling that never fires in production is the correct behaviour for a
+ * backstop, not evidence it is untested: it fires under test
+ * (`pi-worker-core.test.ts` — 'the absolute ceiling still bounds a worker that
+ * never stops moving'), and a worker that goes QUIET is killed long before it, at
+ * `timeoutMs` without progress and by the stall probe.
+ */
+export const DEFAULT_WORKER_PROGRESS_CEILING_MS = 1_200_000;
+/**
+ * The progress-based deadline's ceiling, or null when the lever is OFF.
+ *
+ * SHIPPED ON as of nexttask 9 — the env var is now the OFF switch, not the on
+ * switch. Measured baseline vs progress over 42 trials/arm on a calibrated
+ * instrument (A/A false-break 1.5%): worker-timeout restarts 22/24 → 0/24,
+ * degrades 8/24 → 0/24, entries up on all four high-fan-out fixtures (TASK_0021
+ * 11.0 → 25.5), quality invariants HOLD, every treatment-arm ungrounded flag
+ * hand-verified as an instrument artifact rather than a fabrication.
+ *
+ *     unset            ON at DEFAULT_WORKER_PROGRESS_CEILING_MS
+ *     "0" | "off"      OFF — the fixed elapsed-time cap, exactly as before
+ *     positive int     ON at that ceiling, in ms
+ *
+ * A garbage value keeps the SHIPPED behaviour rather than silently disabling the
+ * lever: turning it off is a decision and has to be spelled.
  */
 export function workerProgressCeilingMs(env = defaultEnv) {
-    return positiveInt(env(WORKER_PROGRESS_CEILING_ENV));
+    const raw = env(WORKER_PROGRESS_CEILING_ENV);
+    if (raw === undefined || raw.trim() === '')
+        return DEFAULT_WORKER_PROGRESS_CEILING_MS;
+    if (raw.trim() === '0' || raw.trim().toLowerCase() === 'off')
+        return null;
+    return positiveInt(raw) ?? DEFAULT_WORKER_PROGRESS_CEILING_MS;
 }
 /**
  * The upfront half of the CAP arm, appended to the APIS worker's prompt.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.33.0",
+    "version": "0.35.0",
     "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",