@mjasnikovs/pi-task 0.34.0 → 0.36.0

package/dist/remote/bridge.d.ts

@@ -57,6 +57,12 @@ export interface AskSpec {
      * {@link AskQuestionBoxSpec.manualLabel}). Ignored without `options`.
      */
     manualLabel?: string;
+    /**
+     * Where the free-text card sits among `options` (see
+     * {@link AskQuestionBoxSpec.manualPosition}). Local picker only — remote
+     * browsers always render the text box above the action buttons.
+     */
+    manualPosition?: number;
     /**
      * Extra buttons the BROWSER card shows alongside the recommendation, each
      * answering with its own `value`. Unlike `options` — which are answers, and

package/dist/remote/bridge.js

@@ -101,6 +101,7 @@ export class SessionUI {
                     recommended: i === 0
                 })),
                 ...(spec.manualLabel !== undefined && { manualLabel: spec.manualLabel }),
+                ...(spec.manualPosition !== undefined && { manualPosition: spec.manualPosition }),
                 signal
             });
         }

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/plan-io.d.ts

@@ -43,13 +43,31 @@ export declare function buildPlanBody(task: string): string;
  * there is no hidden channel.
  */
 export declare function formatPlanDecisions(entries: readonly PlanEntry[]): string;
+/**
+ * The line that pins the DELIVERABLE, and it is not optional.
+ *
+ * The task prompt leads the handoff verbatim, and users reach /task-plan by
+ * phrasing the request as planning — live (aiz-client TASK_PLAN_0001,
+ * 2026-08-05): "Lets plan new tab and report @src/app/reports/". /task's refine
+ * read the verb as the deliverable and produced a task titled "Plan the addition
+ * of a new sub-tab…", whose ACCEPTANCE was "a planning document exists with
+ * placeholder sections" and whose VERIFY asserted that no `.ts`/`.tsx` file had
+ * changed. It passed. Nothing was built.
+ *
+ * Planning already happened — this prompt IS its output — so the handoff says so
+ * rather than letting the request's own wording re-open it. It rides on every
+ * handoff, decisions or none: the verb leaks regardless of how much got settled.
+ */
+export declare const HANDOFF_DELIVERABLE_RULE: string;
 /**
  * The prompt handed to /task when the user proceeds to execution.
  *
  * The task prompt leads, exactly as a bare `/task <prompt>` would, so refine sees
- * a normal task description first; the decisions follow as an authoritative block.
- * Anything the user did NOT settle is simply absent — /task's own grill phase asks
- * about what is left, which is why this block never invents a decision to fill a
- * gap.
+ * a normal task description first; the deliverable rule and then the decisions
+ * follow as an authoritative block. Anything the user did NOT settle is simply
+ * absent — /task's own grill phase asks about what is left, which is why this
+ * block never invents a decision to fill a gap. A question the user left
+ * unanswered is likewise absent: "(skipped)" is not a decision, and carrying it
+ * as one is how a non-answer becomes an instruction.
  */
 export declare function buildHandoffPrompt(task: string, entries: readonly PlanEntry[]): string;

package/dist/task/plan-io.js

@@ -73,20 +73,43 @@ export function buildPlanBody(task) {
 export function formatPlanDecisions(entries) {
     return entries.length === 0 ? '(none yet)' : formatPlanTranscript(entries);
 }
+/**
+ * The line that pins the DELIVERABLE, and it is not optional.
+ *
+ * The task prompt leads the handoff verbatim, and users reach /task-plan by
+ * phrasing the request as planning — live (aiz-client TASK_PLAN_0001,
+ * 2026-08-05): "Lets plan new tab and report @src/app/reports/". /task's refine
+ * read the verb as the deliverable and produced a task titled "Plan the addition
+ * of a new sub-tab…", whose ACCEPTANCE was "a planning document exists with
+ * placeholder sections" and whose VERIFY asserted that no `.ts`/`.tsx` file had
+ * changed. It passed. Nothing was built.
+ *
+ * Planning already happened — this prompt IS its output — so the handoff says so
+ * rather than letting the request's own wording re-open it. It rides on every
+ * handoff, decisions or none: the verb leaks regardless of how much got settled.
+ */
+export const HANDOFF_DELIVERABLE_RULE = 'PLANNING IS ALREADY DONE. This prompt is the OUTPUT of an interactive planning session '
+    + 'that has now ended; you are the implementation step. Build the thing. Do not produce a '
+    + 'plan, a design, a proposal, or a "planning-only" deliverable, do not write a document '
+    + 'whose acceptance is that no code changed, and do not defer the work pending user '
+    + 'confirmation — no user is available from here on.';
 /**
  * The prompt handed to /task when the user proceeds to execution.
  *
  * The task prompt leads, exactly as a bare `/task <prompt>` would, so refine sees
- * a normal task description first; the decisions follow as an authoritative block.
- * Anything the user did NOT settle is simply absent — /task's own grill phase asks
- * about what is left, which is why this block never invents a decision to fill a
- * gap.
+ * a normal task description first; the deliverable rule and then the decisions
+ * follow as an authoritative block. Anything the user did NOT settle is simply
+ * absent — /task's own grill phase asks about what is left, which is why this
+ * block never invents a decision to fill a gap. A question the user left
+ * unanswered is likewise absent: "(skipped)" is not a decision, and carrying it
+ * as one is how a non-answer becomes an instruction.
  */
 export function buildHandoffPrompt(task, entries) {
-    const decisions = entries.filter(e => e.kind !== 'note');
+    const decisions = entries.filter(e => e.kind !== 'note' && !(e.kind === 'decision' && /^\(skipped/i.test(e.answer.trim())));
+    const head = `${task.trim()}\n\n${HANDOFF_DELIVERABLE_RULE}`;
     if (decisions.length === 0)
-        return task.trim();
-    return (`${task.trim()}\n\n`
+        return head;
+    return (`${head}\n\n`
         + `PLANNING DECISIONS — these were settled with the user before this task was started. `
         + `They are authoritative: implement them as written, and do not re-open or contradict `
         + `them. They may not cover everything; decide anything they leave open as usual.\n\n`

package/dist/task/plan-prompts.js

@@ -67,6 +67,14 @@ repo, and any stated constraints; it is shown to the user as a recommendation th
 accept or override. When the question is a genuine binary "A or B?" fork, also give
 the single best alternative as an ALT line; otherwise emit only the one SUGGESTED.
 
+The SUGGESTED must DECIDE. Never recommend asking, clarifying, confirming, or
+checking with the user, and never recommend waiting, deferring, or leaving the
+question open — the user is answering this very question right now, so "find out
+from the user" is not an answer, it is the question you just asked. If you truly
+cannot tell which way to go, still commit to the option you would take if it were
+your call, and let the user override it. A default that could not be implemented
+as written is not a default.
+
 OUTPUT FORMAT (exact) — read as much as you like, but your written REPLY is 2 or
 3 lines and nothing else:
 - Do NOT report what you read. No preamble, no analysis, no findings, no numbered

package/dist/task/plan-session.d.ts

@@ -20,7 +20,10 @@
  *                                    doubles as "state a decision" when the model
  *                                    has nothing to ask
  *   ▶ proceed to execution        — stop planning, hand the decisions to /task
- *                                    (PLAN_PROCEED)
+ *                                    (PLAN_PROCEED). Always the LAST card in the
+ *                                    box — it ends the session, so it sits under
+ *                                    every move that continues it, including the
+ *                                    free-text card (see `manualPosition`).
  *
  * The loop is pure with respect to I/O: every side effect (child calls, dialogs,
  * persistence) arrives through {@link PlanSessionDeps}, so the whole interaction
@@ -85,6 +88,32 @@ export declare function pickQuestion<T extends {
  * Deliberately shallow — an "X or Y?" in the question's own clause.
  */
 export declare function looksLikeFork(question: string): boolean;
+/**
+ * Does the recommended default DEFER the decision instead of making one?
+ *
+ * The prompt asks for a "concrete, decisive default", and nothing enforced it.
+ * Live (aiz-client TASK_PLAN_0001, 2026-08-05): the model asked "what specific
+ * report should this new tab display?" and recommended
+ * "clarify with the user what the report is meant to show before proceeding".
+ * The user pressed enter, so it was recorded `(accepted recommendation)` and rode
+ * into /task's handoff as an AUTHORITATIVE decision — an order not to proceed,
+ * addressed to a run where no user exists. /task duly built a task whose
+ * ACCEPTANCE was "a planning document with placeholder sections" and whose VERIFY
+ * asserted that no source file had changed.
+ *
+ * A deferral is not an answer, and the one place it can never be one is here: the
+ * user IS present during planning, so "ask the user" is a null move — that IS the
+ * question. Detection is anchored to the START of the default, which keeps it off
+ * legitimate product behaviour ("prompt the user to confirm deletion" decides
+ * something; "ask the user which report" decides nothing).
+ */
+export declare function isDeferralSuggestion(suggested: string): boolean;
+/**
+ * Corrective re-prompt for a default that deferred the decision. Same one-shot
+ * budget and same quote-it-back shape as {@link planForkHint}, because the child
+ * is stateless and cannot otherwise know what it just recommended.
+ */
+export declare function planDecisiveHint(question: string, suggested: string): string;
 /**
  * Corrective re-prompt for a fork-shaped question that shipped only ONE option.
  *
@@ -109,6 +138,7 @@ export type PlanAskSpec = AskSpec & {
         value: string;
     }[];
     manualLabel: string;
+    manualPosition: number;
     actions: {
         label: string;
         value: string;
@@ -155,9 +185,10 @@ interface PendingQuestion {
 /**
  * Build the picker for a pending model question: the recommendation first (index
  * 0 is the green RECOMMENDED card), the alternative second when the question is a
- * binary fork, then the two control actions. The free-text card is appended by
+ * binary fork, then the two control actions. The free-text card is supplied by
  * askQuestionBox itself — that is the "answer in your own words" affordance, and
- * it is the same card grill and clarify already show.
+ * it is the same card grill and clarify already show — placed just above the
+ * trailing "proceed to execution" card so proceed stays last.
  */
 export declare function buildQuestionSpec(p: PendingQuestion): PlanAskSpec;
 /**
@@ -165,6 +196,8 @@ export declare function buildQuestionSpec(p: PendingQuestion): PlanAskSpec;
  * questions, or the cap/duplicate backstop stopped it. The same three moves are
  * still on offer; only "answer this question" is gone, because there is no
  * question, so the free-text card becomes "add a decision of your own".
+ * Proceed stays last here, as it is under a question: handing off to /task ends
+ * planning, so it never sits where a reflexive first-item press can hit it.
  */
 export declare function buildIdleSpec(): PlanAskSpec;
 /**

package/dist/task/plan-session.js

@@ -20,7 +20,10 @@
  *                                    doubles as "state a decision" when the model
  *                                    has nothing to ask
  *   ▶ proceed to execution        — stop planning, hand the decisions to /task
- *                                    (PLAN_PROCEED)
+ *                                    (PLAN_PROCEED). Always the LAST card in the
+ *                                    box — it ends the session, so it sits under
+ *                                    every move that continues it, including the
+ *                                    free-text card (see `manualPosition`).
  *
  * The loop is pure with respect to I/O: every side effect (child calls, dialogs,
  * persistence) arrives through {@link PlanSessionDeps}, so the whole interaction
@@ -98,6 +101,51 @@ export function pickQuestion(parsed) {
 export function looksLikeFork(question) {
     return /\bor\b/i.test(question.split('?')[0] ?? '');
 }
+/**
+ * Does the recommended default DEFER the decision instead of making one?
+ *
+ * The prompt asks for a "concrete, decisive default", and nothing enforced it.
+ * Live (aiz-client TASK_PLAN_0001, 2026-08-05): the model asked "what specific
+ * report should this new tab display?" and recommended
+ * "clarify with the user what the report is meant to show before proceeding".
+ * The user pressed enter, so it was recorded `(accepted recommendation)` and rode
+ * into /task's handoff as an AUTHORITATIVE decision — an order not to proceed,
+ * addressed to a run where no user exists. /task duly built a task whose
+ * ACCEPTANCE was "a planning document with placeholder sections" and whose VERIFY
+ * asserted that no source file had changed.
+ *
+ * A deferral is not an answer, and the one place it can never be one is here: the
+ * user IS present during planning, so "ask the user" is a null move — that IS the
+ * question. Detection is anchored to the START of the default, which keeps it off
+ * legitimate product behaviour ("prompt the user to confirm deletion" decides
+ * something; "ask the user which report" decides nothing).
+ */
+export function isDeferralSuggestion(suggested) {
+    const s = suggested.trim().replace(/^["'`*_\s]+/, '');
+    return (/^(ask|clarify|confirm|check|discuss|decide)\b[^.]{0,60}\b(with |from |the )?user\b/i.test(s)
+        || /^(wait|hold off|hold|defer|postpone|pause|park)\b/i.test(s)
+        || /^(tbd|to be (determined|decided|defined|specified))\b/i.test(s)
+        || /^(pending|awaiting|await)\b/i.test(s)
+        || /^leave (it|this|that)?\s*(to|for|open|undecided|unspecified)\b/i.test(s)
+        || /^the user (must|should|needs? to|has to|will)\b/i.test(s)
+        || /^(do not|don'?t|no)\b[^.]{0,40}\b(proceed|implement|build|start|write|decide)\b/i.test(s));
+}
+/**
+ * Corrective re-prompt for a default that deferred the decision. Same one-shot
+ * budget and same quote-it-back shape as {@link planForkHint}, because the child
+ * is stateless and cannot otherwise know what it just recommended.
+ */
+export function planDecisiveHint(question, suggested) {
+    return ('[SYSTEM NOTE: Your previous reply asked this question:\n'
+        + `"${question}"\n`
+        + `and recommended: "${suggested}"\n`
+        + 'That recommendation DEFERS the decision instead of making one — it tells the user to '
+        + 'ask, clarify, wait, or leave it open. The user is answering this question RIGHT NOW, so '
+        + '"find out from the user" is not an answer, it is the question you just asked. Ask the '
+        + 'SAME question again — do not change the subject — and this time make SUGGESTED a '
+        + 'concrete choice that could be implemented as written, naming real things from the repo. '
+        + 'If the question is a genuine A-or-B fork, add the ALT line too. Nothing else.]');
+}
 /**
  * Corrective re-prompt for a fork-shaped question that shipped only ONE option.
  *
@@ -124,9 +172,10 @@ export function planForkHint(question) {
 /**
  * Build the picker for a pending model question: the recommendation first (index
  * 0 is the green RECOMMENDED card), the alternative second when the question is a
- * binary fork, then the two control actions. The free-text card is appended by
+ * binary fork, then the two control actions. The free-text card is supplied by
  * askQuestionBox itself — that is the "answer in your own words" affordance, and
- * it is the same card grill and clarify already show.
+ * it is the same card grill and clarify already show — placed just above the
+ * trailing "proceed to execution" card so proceed stays last.
  */
 export function buildQuestionSpec(p) {
     const options = [];
@@ -153,7 +202,10 @@ export function buildQuestionSpec(p) {
         allowSkip: false,
         options: [...options, ...actions],
         actions,
-        manualLabel: PLAN_ANSWER_LABEL
+        manualLabel: PLAN_ANSWER_LABEL,
+        // The free-text card goes ABOVE "proceed to execution" — proceed ends the
+        // session, so it is the last card in the box, under every other move.
+        manualPosition: options.length + actions.length - 1
     };
 }
 /**
@@ -161,11 +213,13 @@ export function buildQuestionSpec(p) {
  * questions, or the cap/duplicate backstop stopped it. The same three moves are
  * still on offer; only "answer this question" is gone, because there is no
  * question, so the free-text card becomes "add a decision of your own".
+ * Proceed stays last here, as it is under a question: handing off to /task ends
+ * planning, so it never sits where a reflexive first-item press can hit it.
  */
 export function buildIdleSpec() {
     const actions = [
-        { label: PLAN_PROCEED_LABEL, value: PLAN_PROCEED },
-        { label: PLAN_ASK_LABEL, value: PLAN_ASK }
+        { label: PLAN_ASK_LABEL, value: PLAN_ASK },
+        { label: PLAN_PROCEED_LABEL, value: PLAN_PROCEED }
     ];
     return {
         localTitle: PLAN_NO_QUESTIONS,
@@ -177,7 +231,8 @@ export function buildIdleSpec() {
         allowSkip: false,
         options: actions,
         actions,
-        manualLabel: PLAN_STATE_LABEL
+        manualLabel: PLAN_STATE_LABEL,
+        manualPosition: actions.length - 1
     };
 }
 /**
@@ -278,11 +333,31 @@ export async function runPlanSession(deps) {
                 formatHint = PLAN_FORMAT_HINT;
                 continue;
             }
+            // A default that defers decides nothing, and an accepted deferral
+            // reaches /task dressed as an authoritative decision. One re-prompt to
+            // make it decisive; if it comes back deferring anyway the option is
+            // DROPPED rather than shown, so an empty submit records "(skipped)" —
+            // an unanswered question — instead of a decision the user never made.
+            const defers = suggested !== undefined && isDeferralSuggestion(suggested);
+            if (defers && formatHint === null) {
+                deps.logDebug?.('plan: SUGGESTED deferred the decision — one re-prompt');
+                formatHint = planDecisiveHint(plain, suggested);
+                continue;
+            }
+            // When only the recommendation defers, the ALT is still a real
+            // commitment: promote it so the question keeps a usable default.
+            const usableSuggested = defers ? alt : suggested;
+            const usableAlt = defers ? undefined : alt;
+            if (defers) {
+                deps.logDebug?.(usableSuggested === undefined ?
+                    'plan: SUGGESTED still deferred — question shown with no recommendation'
+                    : 'plan: SUGGESTED still deferred — promoted the ALT to the recommendation');
+            }
             // A question that offers a choice but ships one option leaves the
             // user typing out the alternative the model just named. Same one-shot
             // budget, quoting the question back so the (stateless) child re-asks
             // this one instead of a new one.
-            if (alt === undefined && formatHint === null && looksLikeFork(plain)) {
+            if (usableAlt === undefined && formatHint === null && !defers && looksLikeFork(plain)) {
                 deps.logDebug?.('plan: fork-shaped question with no ALT — one re-prompt');
                 formatHint = planForkHint(plain);
                 continue;
@@ -294,13 +369,13 @@ export async function runPlanSession(deps) {
             pending = {
                 plain,
                 shown: render(question),
-                ...(suggested !== undefined && {
-                    suggested: stripInlineMarkdown(suggested),
-                    shownSuggested: render(suggested)
+                ...(usableSuggested !== undefined && {
+                    suggested: stripInlineMarkdown(usableSuggested),
+                    shownSuggested: render(usableSuggested)
                 }),
-                ...(alt !== undefined && {
-                    alt: stripInlineMarkdown(alt),
-                    shownAlt: render(alt)
+                ...(usableAlt !== undefined && {
+                    alt: stripInlineMarkdown(usableAlt),
+                    shownAlt: render(usableAlt)
                 })
             };
         }

package/dist/task/question-box.d.ts

@@ -84,6 +84,14 @@ export interface AskQuestionBoxSpec {
      * what the card actually does.
      */
     manualLabel?: string;
+    /**
+     * Where the free-text card sits among the options. Defaults to the end, which
+     * is right when the picker is answering a question. /task-plan passes an
+     * earlier index so its "proceed to execution" card — the one that ENDS the
+     * session — is literally the last entry in the list, and never sits above a
+     * card the user is more likely to want.
+     */
+    manualPosition?: number;
 }
 /**
  * Show the boxed picker and resolve to the chosen option's `value`, the text the

package/dist/task/question-box.js

@@ -143,12 +143,14 @@ export class QuestionBoxComponent {
  */
 export async function askQuestionBox(ctx, spec) {
     const { question, options, inputTitle, signal } = spec;
+    const manualIndex = Math.max(0, Math.min(options.length, spec.manualPosition ?? options.length));
+    const asCard = (o) => ({ label: o.label, recommended: o.recommended });
     const cards = [
-        ...options.map(o => ({ label: o.label, recommended: o.recommended })),
-        { label: spec.manualLabel ?? MANUAL_CARD_LABEL }
+        ...options.slice(0, manualIndex).map(asCard),
+        { label: spec.manualLabel ?? MANUAL_CARD_LABEL },
+        ...options.slice(manualIndex).map(asCard)
     ];
     const colors = boxColors(ctx.ui.theme);
-    const manualIndex = options.length;
     const choice = await ctx.ui.custom((_tui, _theme, _kb, done) => {
         if (signal.aborted) {
             done(undefined);
@@ -167,5 +169,5 @@ export async function askQuestionBox(ctx, spec) {
     if (choice === manualIndex) {
         return ctx.ui.input(inputTitle, undefined, { signal });
     }
-    return options[choice]?.value;
+    return options[choice < manualIndex ? choice : choice - 1]?.value;
 }

package/package.json

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