@mjasnikovs/pi-task 0.38.29 → 0.38.30

package/dist/task/implementation-turn.js

@@ -7,12 +7,13 @@
  *   • `aborted`     — a user ESC (or the command watchdog) cut the turn short;
  *   • `compaction`  — a threshold auto-compaction parked the turn at idle without
  *                     auto-continuing (the runtime expects a manual continue);
- *   • `error`       — the model/provider died mid-turn after pi's own retries;
+ *   • `error`       — the model or provider failed after pi exhausted the retries
+ *                     in its own retry settings;
  *   • `stop`        — genuine completion.
- * `classifyTurnEnd` reads the session entries and names ONE of those, in the
- * precedence the supervision sequence needs; `superviseImplementation` then
- * resumes across compactions, lets the user steer after an interrupt, and reports
- * the terminal outcome. The orchestrator calls it once.
+ * `classifyTurnEnd` reads the session entries and names ONE of those;
+ * `superviseImplementation` then resumes across compactions, lets the user steer
+ * after an interrupt, and reports the terminal outcome. The orchestrator calls it
+ * from one place, inside the `sendSpec` closure.
  */
 import { SessionUI } from '../remote/bridge.js';
 import { consumeWatchdogAbort, WATCHDOG_CANCEL_MARKER } from './command-watchdog.js';
@@ -33,21 +34,20 @@ function tailPositions(entries) {
 /**
  * Classify how the most recent turn ended, from the session entries alone.
  *
- * Precedence, when several signals are present at once (this is the order the
- * supervision sequence has always applied, now stated in one place):
+ * Precedence, when several signals are present at once:
  *   1. `aborted`    — the last assistant message has stopReason "aborted". A user
  *                     ESC (or watchdog abort) wins over everything: it is not a
  *                     compaction pause, and the steer loop owns it.
  *   2. `compaction` — a `compaction` entry sits AFTER the last assistant message.
- *                     Position-based, not timestamp-based: the runtime appends the
- *                     boundary to the tail of the branch after the message that
- *                     triggered it (`appendCompaction` → `_appendEntry` push), so a
+ *                     Position-based, not timestamp-based: `appendCompaction`
+ *                     pushes the boundary onto the tail of the entry list, and
+ *                     `getEntries()` returns that list in append order, so a
  *                     trailing compaction means we are parked with no continuation.
- *                     A finished turn ends on an assistant message; an *overflow*
- *                     compaction self-retries and never leaves us idle here.
- *   3. `error`      — the last assistant message has stopReason "error": the
- *                     model/provider died (context-overflow 400, disconnect, 5xx)
- *                     after pi exhausted its own retries.
+ *                     A finished turn ends on an assistant message. An overflow
+ *                     compaction that is going to retry continues the turn itself
+ *                     and never reaches us idle.
+ *   3. `error`      — the last assistant message has stopReason "error": the model
+ *                     or provider failed after pi exhausted its own retries.
  *   4. `stop`       — anything else, including a session with no assistant turn.
  */
 export function classifyTurnEnd(entries) {
@@ -143,9 +143,10 @@ export function turnDepsFor(ctx, opts = {}) {
 /**
  * Nudge that resumes an implementation turn the runtime parked at a compaction
  * boundary. It must let a turn that was genuinely finished (then tipped over the
- * threshold by its own final message) confirm completion without inventing busywork
- * — we cannot tell "paused mid-task by compaction" from "finished, then compacted"
- * from the boundary alone, so the wording lets a done turn end in one line.
+ * threshold by its own final message) confirm completion without inventing busywork.
+ * The classifier sees only the boundary's POSITION, so it cannot tell "paused
+ * mid-task by compaction" from "finished, then compacted"; the wording lets a done
+ * turn end in one line.
  */
 export const CONTINUE_AFTER_COMPACTION = 'Your context was automatically compacted. Continue implementing this task from '
     + 'exactly where you left off, and keep going until it is fully done. If the '
@@ -153,11 +154,10 @@ export const CONTINUE_AFTER_COMPACTION = 'Your context was automatically compact
     + 'extra work or restart the task.';
 /**
  * Safety cap on compaction-driven resumes for a single implementation turn. Each
- * resume follows a real compaction (which only fires after the model produced a
- * turn large enough to cross the threshold), so a legitimately large task may
- * resume a handful of times; the cap exists only to stop a pathological loop from
- * auto-sending forever with no user in the loop. Hitting it stops resuming and lets
- * the verify gate / `/task-auto-resume` catch any leftover incompleteness.
+ * resume follows a real compaction, which pi only runs once `shouldCompact` says
+ * the context crossed its threshold. The cap exists to stop a pathological loop
+ * from auto-sending forever with no user watching. Hitting it stops resuming and
+ * lets the verify gate and `/task-auto-resume` catch any leftover incompleteness.
  */
 export const MAX_COMPACTION_RESUMES = 20;
 /**
@@ -209,10 +209,12 @@ async function awaitWatchdogFollowUp(deps) {
  * `waitForIdle` resolves both on natural completion AND on an ESC (which aborts
  * the turn → idle). When the last turn was aborted, the host's main input loop is
  * blocked inside our command handler, so a message typed in the editor would only
- * queue, never run (interactive-mode routes idle input through onInputCallback,
- * which is unset while we hold the loop). We therefore solicit the steering text
- * ourselves and feed it back as another turn via sendUserMessage — which runs to
- * completion when the session is idle. Repeat until a turn finishes uninterrupted.
+ * queue, never run: interactive-mode's submit handler calls `onInputCallback` when
+ * the session is idle, and that callback is set only inside `getUserInput()` — the
+ * REPL loop we are holding — so the text lands in `pendingUserInputs` instead. We
+ * therefore solicit the steering text ourselves and feed it back as another turn
+ * via `sendUserMessage`, which forwards to `prompt()` and, on an idle session, runs
+ * the turn rather than queueing it. Repeat until a turn finishes uninterrupted.
  *
  * A WATCHDOG abort also ends the turn with stopReason 'aborted' — indistinguishable
  * from a human ESC by the session entries alone at that instant. The watchdog

package/dist/task/inline-markdown.d.ts

@@ -1,13 +1,26 @@
 /**
- * Inline-markdown helpers for the clarify/grill question dialogs.
+ * Inline-markdown helpers for the question dialogs (grill, clarify, /task-plan).
  *
- * The model often wraps the core question in **bold** (and code in backticks)
- * because it makes the question easier to read at a glance. ctx.ui.input titles
- * accept ANSI styling, so we RENDER those spans to terminal bold/code for the
- * displayed prompt, and STRIP them to plain text for the editable input default
- * and the persisted task file (which must stay ANSI-free).
+ * The question arrives carrying markdown because our own prompts ask for it:
+ * auto-prompts.ts and plan-prompts.ts both say "Put the core question in
+ * **bold** ... Backticks around code/identifiers are fine."
+ *
+ * One question then needs two forms, and question-dialog.ts `settleQuestion`
+ * builds both:
+ *   • RENDERED — passed as `localTitle`, which reaches `ctx.ui.input`. pi wraps
+ *     that title in `theme.fg("accent", ...)` and hands it to a pi-tui `Text`,
+ *     which passes embedded escape sequences straight through, so the bold and
+ *     code spans survive to the terminal.
+ *   • STRIPPED — passed as the browser card's `question`, as the editable
+ *     `recommended` default, and as the text recorded in QaTranscript, whose
+ *     `forRecord()` is written into the task file's `grill Q&A` section. All
+ *     three are plain text, never ANSI.
+ */
+/**
+ * Minimal theme surface we need. pi's `Theme` satisfies it: it declares
+ * `bold(text)` and `fg(color, text)`, and `mdCode` is one of its `ThemeColor`
+ * values, so `ctx.ui.theme` is passed in directly.
  */
-/** Minimal theme surface we need; ExtensionCommandContext['ui'].theme satisfies it. */
 export interface InlineMarkdownTheme {
     bold(text: string): string;
     fg(color: 'mdCode', text: string): string;

package/dist/task/inline-markdown.js

@@ -1,11 +1,20 @@
 /**
- * Inline-markdown helpers for the clarify/grill question dialogs.
+ * Inline-markdown helpers for the question dialogs (grill, clarify, /task-plan).
  *
- * The model often wraps the core question in **bold** (and code in backticks)
- * because it makes the question easier to read at a glance. ctx.ui.input titles
- * accept ANSI styling, so we RENDER those spans to terminal bold/code for the
- * displayed prompt, and STRIP them to plain text for the editable input default
- * and the persisted task file (which must stay ANSI-free).
+ * The question arrives carrying markdown because our own prompts ask for it:
+ * auto-prompts.ts and plan-prompts.ts both say "Put the core question in
+ * **bold** ... Backticks around code/identifiers are fine."
+ *
+ * One question then needs two forms, and question-dialog.ts `settleQuestion`
+ * builds both:
+ *   • RENDERED — passed as `localTitle`, which reaches `ctx.ui.input`. pi wraps
+ *     that title in `theme.fg("accent", ...)` and hands it to a pi-tui `Text`,
+ *     which passes embedded escape sequences straight through, so the bold and
+ *     code spans survive to the terminal.
+ *   • STRIPPED — passed as the browser card's `question`, as the editable
+ *     `recommended` default, and as the text recorded in QaTranscript, whose
+ *     `forRecord()` is written into the task file's `grill Q&A` section. All
+ *     three are plain text, never ANSI.
  */
 const BOLD_SPAN = /\*\*(.+?)\*\*/g;
 const CODE_SPAN = /`([^`]+)`/g;

package/dist/task/launch-config-gap.js

@@ -1,65 +1,51 @@
 /**
  * launch-config-gap — a launch script that cannot run because a variable the
  * project's own tracked template DECLARES is absent from this box is an
- * ENVIRONMENT GAP, not a code fault (mx5 run 20).
+ * ENVIRONMENT GAP, not a code fault.
  *
- * THE EPISODE. Attempt 3 of the final-gate autofix passed every guard, fixed the
- * failing test, and still lost the run:
- *
- *     autofix attempt 3 failed — did not converge: launch script: `bun run seed`
- *     exited 1 — $ bun run src/server/seed.ts  Missing required environment
- *     variable: ADMIN_PHONE  error: script "seed" exited with code 1
- *
- * Single-failure phrasing (final-gate.ts uses a numbered list for ≥2), so the
- * suite was green and this was the only remaining failure. The run failed on
- * exactly this, and it is self-inflicted at the last moment: pre-gate
- * `package.json` had no `seed` script at all, so `if (!present.has(name)) continue`
- * skipped it. Attempt 3 added the script to clear the launch-contract diff — and
- * thereby armed the check that killed the run.
- *
- * The loop was closed by construction. The gate runs every declared non-boot
- * script with `runnerEnv(runner)` = `process.env` plus a PATH prefix and nothing
- * else; "Missing required environment variable" matches neither ENV_GAP_OUTPUT_RE
- * nor INFRA_GAP_OUTPUT_RE, so it is a hard FAIL; and the only way to supply the
- * value is a gitignored `.env`, whose writes nexttask 4 correctly refuses to
- * credit. The static half of this already shipped and WORKED — `.env.example`
- * declares ADMIN_PHONE/ADMIN_PASSWORD, so `findMissingEnvDeclarations` was
- * correctly silent. This is the execution half.
+ * WHY THE GATE CANNOT SETTLE THIS ON ITS OWN. final-gate.ts runs every declared
+ * non-boot script (`runnableDeclaredScripts`, which filters on `BOOT_CLASS_RE`)
+ * as `bun run <name>`, with `runnerEnv(runner)` — `process.env` plus at most a
+ * PATH prefix, and nothing else. A project's own "missing environment variable"
+ * message matches neither `ENV_GAP_OUTPUT_RE` nor `INFRA_GAP_OUTPUT_RE`, so it
+ * lands as a hard FAIL. The only way to supply the value is a gitignored `.env`,
+ * and final-gate-fix.ts downgrades a converged PASS to UNOBSERVED when the gate
+ * stops passing with the ignored paths moved aside. Without this check the loop
+ * has no exit.
  *
  * FOUR STATIC CONDITIONS, ALL REQUIRED. Deliberately over-constrained: the
  * failure mode of getting this wrong is a gate that excuses real breakage.
  *
- *   1. the script's resolved body names a TRACKED SOURCE FILE
- *      (`bun run src/server/seed.ts` → `src/server/seed.ts`);
+ *   1. the script's resolved body names a TRACKED SOURCE FILE;
  *   2. that file REQUIRES an env var `X` under `scanSource` — i.e. none of its
- *      step-asides (default / compared / assigned / ambient / …) applies;
+ *      step-asides (`default`, `compared`, `assigned`, `ambient`,
+ *      `optional-api`, `probe`) applies;
  *   3. `X` is DECLARED in the tracked template. If it is NOT,
  *      `findMissingEnvDeclarations` has already failed the gate statically and
  *      this path must not fire — otherwise the two checks would cancel out and a
  *      project with no template at all would gain a blanket excuse;
  *   4. `X` is ABSENT from the env the gate spawned the child with.
  *
- * NOTHING IS PARSED FROM THE CHILD'S STDERR. `Missing required environment
- * variable: ADMIN_PHONE` is a string the PROJECT authored; matching on it would
- * be a rule about one project's phrasing, and every other project would phrase it
- * differently or not at all.
+ * NOTHING IS PARSED FROM THE CHILD'S STDERR. A "missing variable" message is a
+ * string the PROJECT authored; matching on it would be a rule about one project's
+ * phrasing, and the next project phrases it differently or not at all.
  *
  * THE FIFTH CONDITION IS DYNAMIC, AND IT IS WHAT MAKES THE RULE HONEST. The four
  * above cannot tell "exited BECAUSE the variable is absent" from "exited for its
  * own reasons, and also happens to read an absent variable". A script that throws
- * a TypeError on line 1 and also reads ADMIN_PHONE on line 3 satisfies all four.
+ * a TypeError on line 1 and also reads the variable on line 3 satisfies all four.
  * So the script is re-run once with the gap variables supplied as OBVIOUSLY
  * SYNTHETIC placeholders, and the exit code decides:
  *
- *     still non-zero → the absence did not cause it → FAIL, as today
- *     now zero       → the absence did cause it     → skip + UNOBSERVED + debt
+ *     still non-zero -> the absence did not cause it -> FAIL, unchanged
+ *     now zero       -> the absence did cause it     -> skip + UNOBSERVED + debt
  *
- * The probe run is a DIAGNOSTIC, never an observation. Its success is not
- * reported, and the verdict it produces is UNOBSERVED with debt — never a PASS
- * (memory/unobserved-gate-verdict-shipped.md). The placeholder is a fixed
- * harness-authored string; `.env.example`'s own values are never injected,
- * because they are placeholders too (`change-me`) and a green seed run against
- * them would be a fabricated observation.
+ * The probe run is a DIAGNOSTIC, never an observation. On a passing probe
+ * final-gate.ts calls `tally.unobserve()` and files the script as skipped, so the
+ * verdict is UNOBSERVED with debt and never a PASS. The placeholder is one fixed
+ * harness-authored string ({@link CONFIG_GAP_PROBE_VALUE}); the template's own
+ * values are never injected, because those are placeholders too and a green run
+ * against them would be a fabricated observation.
  */
 import { readFileSync } from 'node:fs';
 import * as path from 'node:path';

package/dist/task/launch-contract.d.ts

@@ -12,22 +12,20 @@ export declare function parseScriptLines(text: string): string[];
  */
 export declare function keepGroundedScripts(names: string[], sourceDoc: string): string[];
 /**
- * DETERMINISTIC RECALL (mx5 run 11): enumerate every backticked, script-name-shaped
+ * DETERMINISTIC RECALL: enumerate every backticked, script-name-shaped
  * token in a paragraph that mentions the word "script", as extraction CANDIDATES.
  *
- * The run-11 failure this closes: `test:ct` is backticked in the design's §2 tooling
- * paragraph, so the grounding guard would have KEPT it — but the extraction child
- * anchored on §9's one-line summary (`dev`,`build`,`migrate`,`seed`,`test`) and never
- * emitted it. Grounding can only DROP a candidate, never add one, so recall was
- * entirely the model's, over a 20KB doc. This makes recall mechanical: the host
- * enumerates candidates and hands them to the child as an explicit checklist; the
- * model's job flips from recall (weak) to per-candidate classification (strong).
+ * Grounding can only DROP a candidate, never add one, so without this the recall of a
+ * script declared far from the design's summary list is entirely the model's. This
+ * makes recall mechanical: the host enumerates the candidates and hands them to the
+ * child as an explicit checklist, so the model's job flips from recall (weak) to
+ * per-candidate classification (strong).
  *
  * The paragraph gate (`\bscripts?\b`, word-bounded so "TypeScript"/"JavaScript"
  * don't match) is a grounded-context filter, not a tuned knob: a design declares a
- * script by calling it one. It keeps package-name paragraphs (`hono`, `react`) out
- * of the checklist so a weak model isn't invited to keep junk the grounding guard
- * would then bless (every package name is backticked somewhere). A design with no
+ * script by calling it one. It keeps package-name paragraphs out of the checklist so
+ * a weak model isn't invited to keep junk the grounding guard would then bless —
+ * every package name is backticked somewhere. A design with no
  * such paragraph yields no candidates and the prompt is unchanged.
  */
 export declare function enumerateScriptCandidates(sourceDoc: string): string[];
@@ -38,13 +36,12 @@ export declare function readDeclaredScripts(cwd: string): Promise<string[]>;
 /** Append grounded script names, deduped against what is stored, keeping newest MAX. */
 export declare function appendDeclaredScripts(cwd: string, names: string[]): Promise<void>;
 /**
- * The declared scripts the final gate must EXECUTE as one-shot commands (mx5 run
- * 11): everything the launch contract declares that is neither boot-class (the
- * boot check exercises those) nor already covered by the gate's integration
- * commands (`covered`, case-insensitive — the test/build-shaped scripts that ran).
- * Run 11 shipped `migrate` and `seed` broken (`.rows` on a Bun sql array —
- * TypeError on first call) while the gate checked only that the scripts EXIST;
- * existence is not launchability.
+ * The declared scripts the final gate must EXECUTE as one-shot commands: everything
+ * the launch contract declares that is neither boot-class (the boot check exercises
+ * those) nor already covered by the gate's integration commands (`covered`,
+ * case-insensitive — the test/build-shaped scripts that ran). Checking only that a
+ * script is DECLARED says nothing about whether running it works; existence is not
+ * launchability.
  */
 export declare function runnableDeclaredScripts(declared: string[], covered: string[]): string[];
 /**
@@ -59,8 +56,8 @@ export declare function missingDeclaredScripts(declared: string[], manifestScrip
  * (keepGroundedScripts), so a hallucinated script cannot reach the diff.
  *
  * `candidates` is enumerateScriptCandidates' mechanical checklist. It exists so the
- * model cannot MISS a declared script buried far from the design's summary list (the
- * run-11 `test:ct` hole); the model still classifies each candidate against the
- * design, and the host grounding still applies. Empty ⇒ the prompt is unchanged.
+ * model cannot MISS a declared script buried far from the design's summary list; the
+ * model still classifies each candidate against the design, and the host grounding
+ * still applies. Empty ⇒ the prompt is unchanged.
  */
 export declare const LAUNCH_EXTRACT_PROMPT: (feature: string, candidates?: string[]) => string;

package/dist/task/launch-contract.js

@@ -3,13 +3,10 @@
  * declares the finished project must expose, extracted once at plan time and diffed
  * by the final gate against the shipped manifest.
  *
- * The failure this closes (mx5 run 10 item 4): the design's §9 "Build & run" listed
- * the required scripts verbatim — `dev`, `build`, `migrate`, `seed`, `test` — but the
- * shipped package.json declared only `dev`, `build`, `lint`, `test`, `test:ct`. No
- * task owned `migrate`/`seed` (they fell through decompose), and NOTHING re-checked
- * the finished manifest against the design's own list, so the run completed missing
- * two of its declared entrypoints. A per-slice gate cannot catch this — it is a
- * whole-project launch-surface fact — and the final gate never had the design's list.
+ * The gap it closes is structural. A script the design names but no task owned can
+ * fall through decompose and ship missing, and a per-slice gate cannot see that: it
+ * is a whole-project launch-surface fact, and nothing else re-reads the finished
+ * manifest against the design's own list.
  *
  * Mechanism (mirrors contracts.ts): a plan-time child EMITs `SCRIPT:` lines naming the
  * scripts the design declares; the host GROUNDS each against the design — a name is
@@ -17,9 +14,13 @@
  * form designs use to declare a script. A paraphrase or a script the model invented is
  * not grounded and is dropped, so the diff can never false-flag on a hallucinated
  * requirement. The grounded list is appended HOST-SIDE to `.pi-tasks/launch-contract.md`
- * (children never write it), which survives discardEdits and the git-state guard.
+ * — the extraction child runs `--no-tools` and so has no write tool at all. Both halves
+ * of `discardTreeEdits` skip that directory (`checkout -- . :(exclude).pi-tasks`, then
+ * `clean -fd -e .pi-tasks`), and the git-state guard excludes it from the tree it
+ * hashes, so the file outlives a discarded pass.
  *
- * At run end the final gate reads the list, reads the manifest's `scripts`, and FAILs
+ * At run end the final gate reads the list, reads the shipped manifest's script names
+ * (`readLaunchManifest`: package.json `scripts`, else a Makefile's targets), and FAILs
  * naming any declared script the manifest is missing. FP-safe by construction: an
  * empty/ungrounded list (a design that never backticks a script name) yields no check.
  */
@@ -93,22 +94,20 @@ export function keepGroundedScripts(names, sourceDoc) {
     return kept;
 }
 /**
- * DETERMINISTIC RECALL (mx5 run 11): enumerate every backticked, script-name-shaped
+ * DETERMINISTIC RECALL: enumerate every backticked, script-name-shaped
  * token in a paragraph that mentions the word "script", as extraction CANDIDATES.
  *
- * The run-11 failure this closes: `test:ct` is backticked in the design's §2 tooling
- * paragraph, so the grounding guard would have KEPT it — but the extraction child
- * anchored on §9's one-line summary (`dev`,`build`,`migrate`,`seed`,`test`) and never
- * emitted it. Grounding can only DROP a candidate, never add one, so recall was
- * entirely the model's, over a 20KB doc. This makes recall mechanical: the host
- * enumerates candidates and hands them to the child as an explicit checklist; the
- * model's job flips from recall (weak) to per-candidate classification (strong).
+ * Grounding can only DROP a candidate, never add one, so without this the recall of a
+ * script declared far from the design's summary list is entirely the model's. This
+ * makes recall mechanical: the host enumerates the candidates and hands them to the
+ * child as an explicit checklist, so the model's job flips from recall (weak) to
+ * per-candidate classification (strong).
  *
  * The paragraph gate (`\bscripts?\b`, word-bounded so "TypeScript"/"JavaScript"
  * don't match) is a grounded-context filter, not a tuned knob: a design declares a
- * script by calling it one. It keeps package-name paragraphs (`hono`, `react`) out
- * of the checklist so a weak model isn't invited to keep junk the grounding guard
- * would then bless (every package name is backticked somewhere). A design with no
+ * script by calling it one. It keeps package-name paragraphs out of the checklist so
+ * a weak model isn't invited to keep junk the grounding guard would then bless —
+ * every package name is backticked somewhere. A design with no
  * such paragraph yields no candidates and the prompt is unchanged.
  */
 export function enumerateScriptCandidates(sourceDoc) {
@@ -153,13 +152,12 @@ export async function appendDeclaredScripts(cwd, names) {
  */
 const BOOT_CLASS_RE = /^(?:dev|start|serve|preview|watch)(?:[:_-].*)?$/i;
 /**
- * The declared scripts the final gate must EXECUTE as one-shot commands (mx5 run
- * 11): everything the launch contract declares that is neither boot-class (the
- * boot check exercises those) nor already covered by the gate's integration
- * commands (`covered`, case-insensitive — the test/build-shaped scripts that ran).
- * Run 11 shipped `migrate` and `seed` broken (`.rows` on a Bun sql array —
- * TypeError on first call) while the gate checked only that the scripts EXIST;
- * existence is not launchability.
+ * The declared scripts the final gate must EXECUTE as one-shot commands: everything
+ * the launch contract declares that is neither boot-class (the boot check exercises
+ * those) nor already covered by the gate's integration commands (`covered`,
+ * case-insensitive — the test/build-shaped scripts that ran). Checking only that a
+ * script is DECLARED says nothing about whether running it works; existence is not
+ * launchability.
  */
 export function runnableDeclaredScripts(declared, covered) {
     const have = new Set(covered.map(s => s.toLowerCase()));
@@ -189,9 +187,9 @@ export function missingDeclaredScripts(declared, manifestScripts) {
  * (keepGroundedScripts), so a hallucinated script cannot reach the diff.
  *
  * `candidates` is enumerateScriptCandidates' mechanical checklist. It exists so the
- * model cannot MISS a declared script buried far from the design's summary list (the
- * run-11 `test:ct` hole); the model still classifies each candidate against the
- * design, and the host grounding still applies. Empty ⇒ the prompt is unchanged.
+ * model cannot MISS a declared script buried far from the design's summary list; the
+ * model still classifies each candidate against the design, and the host grounding
+ * still applies. Empty ⇒ the prompt is unchanged.
  */
 export const LAUNCH_EXTRACT_PROMPT = (feature, candidates = []) => [
     'You are recording the PACKAGE/BUILD SCRIPTS the design below says the finished',

package/dist/task/launch-manifest.d.ts

@@ -31,12 +31,16 @@ export declare function makeTargets(src: string): string[];
 export declare function readLaunchManifest(cwd: string): LaunchManifest;
 /**
  * The one line an INERT contract leaves behind. It rides in the gate's UNOBSERVED
- * channel rather than in `warnings` for the reason nexttask 16A gives: a check that
+ * channel rather than in `warnings` for one reason: a check that
  * silently did nothing must not read later as a check that passed.
  */
 export declare function inertLaunchContractNote(declared: string[], manifest: LaunchManifest): string;
 /** The `scripts` map of this tree's package.json, or `{}` when there isn't one.
  *  Shared by the gate and the boot probe — both ask the same manifest question. */
 export declare function packageScripts(cwd: string): Record<string, string>;
-/** Does this tree's Makefile declare `target`? */
+/**
+ * Does this tree's Makefile declare `target`? Reads the literal name `Makefile`
+ * only — unlike {@link readLaunchManifest}, this one does not walk make's lookup
+ * order, so a `GNUmakefile`-only tree answers false.
+ */
 export declare function makeHasTarget(cwd: string, target: string): boolean;

package/dist/task/launch-manifest.js

@@ -1,54 +1,50 @@
 /**
  * launch-manifest — WHICH manifest the launch-contract diff is entitled to diff
- * against, and whether there is one at all (nexttask 16A).
+ * against, and whether there is one at all.
  *
- * The defect this closes (unobserved, proven by construction). The extraction end
- * of the launch contract has no ecosystem test anywhere in it:
- * `enumerateScriptCandidates` scrapes backticked, script-name-shaped tokens out of
- * any design paragraph that says "script", and `keepGroundedScripts` can only DROP
- * a candidate. So a CMake / cargo / poetry / Makefile design saying *"the Makefile
- * must expose `build`, `test`, `migrate`"* records exactly the same artifact an npm
- * design does. The diff end hardcoded the ecosystem anyway:
+ * WHY THE DIFF NEEDS ITS OWN RESOLVER. The extraction end of the launch contract
+ * has no ecosystem test anywhere in it: `enumerateScriptCandidates` scrapes
+ * backticked, script-name-shaped tokens out of any design paragraph that says
+ * "script", and `keepGroundedScripts` can only DROP a candidate. A Makefile design
+ * saying *"the Makefile must expose `build`, `test`, `migrate`"* therefore records
+ * exactly the same artifact an npm design does.
  *
- *     missingDeclaredScripts(declared, Object.keys(packageScripts(cwd)))
- *     …where packageScripts' catch returns {} — so "this project has no
- *     package.json" was indistinguishable from "its package.json declares no
- *     scripts", and every declared script was reported missing, at rank 1, in
- *     wording that NAMES a file the project was never meant to have.
- *
- * That text seeds the autofix child's prompt (final-gate.ts's FinalGateOutcome.reason),
- * so the most likely repair on a CMake project was to write a package.json.
- *
- * IAR1 is how close this got: `plan-debug.log:10` records "launch-contract
- * extraction: 0 grounded script(s) kept from 3 emitted" — a non-npm project that
- * reached extraction and emitted three candidates, saved only by its design not
- * backticking them in a "script" paragraph.
+ * The diff cannot then reach for `packageScripts` alone. Its catch returns `{}`, so
+ * "this project has no package.json" is indistinguishable from "its package.json
+ * declares no scripts", and every declared script reads as missing — in wording that
+ * NAMES a file the project was never meant to have. `tally.fail` text becomes the
+ * gate's `reason`, which `buildFinalFixPrompt` hands to the autofix child, so on a
+ * non-npm tree the repair that text invites is to write a package.json.
  *
  * THE RULE, and it is deliberately two ecosystems wide, not three:
  *   • package.json present and parseable ⇒ diff against its `scripts` keys, exactly
- *     as before (byte-identical failure text on every npm tree — mx5's missing
+ *     as before (byte-identical failure text on every npm tree — a missing
  *     `build`/`seed` is a TRUE positive and must keep failing).
- *   • no package.json but a Makefile ⇒ diff against its TARGETS. The capability was
- *     already in final-gate.ts (`makeHasTarget`); the diff simply never called it.
+ *   • no package.json but a Makefile ⇒ diff against its TARGETS.
  *   • neither ⇒ the check is INERT. No failure, and a note saying the contract was
  *     recorded but is not checkable here, so the silence is not read later as a pass
  *     (the repo-health-check / env-template-closure discipline: ENOENT = pass, and a
  *     check must never invent a file the project chose not to have).
  *
- * cargo/poetry/gradle are NOT here on purpose. The corpus on this box contains one
- * project that ever recorded a launch contract (mx5, npm) and one non-npm project
- * that reached extraction (IAR1, CMake). A third ecosystem would be a guess.
+ * cargo/poetry/gradle are NOT here on purpose: nothing in this repo knows how to
+ * enumerate their entrypoints, and a third resolver written without one would be a
+ * guess that can only produce false FAILs.
  */
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import * as path from 'node:path';
-/** GNU make's own lookup order, and nothing beyond it — this is one ecosystem. */
+/**
+ * GNU make's own lookup order, and nothing beyond it — this is one ecosystem.
+ * Confirmed against `make` itself: with all three files present in one directory it
+ * runs GNUmakefile; with only `makefile` and `Makefile`, it runs `makefile`.
+ */
 const MAKEFILE_NAMES = ['GNUmakefile', 'makefile', 'Makefile'];
 /** A target we are willing to name in a failure: an ordinary word-shaped target. */
 const TARGET_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,39}$/i;
 /**
  * A variable assignment, in every form make accepts (`=`, `:=`, `::=`, `?=`, `+=`,
  * `!=`, with an optional `override`/`export`). Matched BEFORE the target rule
- * because `FLAGS ::= -O2` otherwise reads as a target named `FLAGS`.
+ * because `FLAGS ::= -O2` otherwise reads as a target named `FLAGS` — make itself
+ * reports that line as a variable, not a rule.
  */
 const ASSIGN_RE = /^(?:override\s+|export\s+)?[A-Za-z_][A-Za-z0-9_.]*\s*(?:::|:|\?|\+|!)?=/;
 /**
@@ -87,9 +83,10 @@ export function makeTargets(src) {
 }
 /**
  * The makefiles that really exist in `cwd`, in GNU make's lookup order, named as
- * the DIRECTORY spells them. `existsSync` cannot do this job: on a case-insensitive
- * filesystem (Windows, macOS) `existsSync('makefile')` is true for a `Makefile`, and
- * the failure text would then name a file the project does not have.
+ * the DIRECTORY spells them. The invariant is that `manifest.file` is always a name
+ * `readdirSync(cwd)` contains, so a failure can never name a file the project does
+ * not have. An `existsSync` probe per candidate name cannot promise that, because it
+ * answers about a name we chose rather than a name on disk.
  */
 function makefilesOnDisk(cwd) {
     let entries;
@@ -141,7 +138,7 @@ export function readLaunchManifest(cwd) {
 }
 /**
  * The one line an INERT contract leaves behind. It rides in the gate's UNOBSERVED
- * channel rather than in `warnings` for the reason nexttask 16A gives: a check that
+ * channel rather than in `warnings` for one reason: a check that
  * silently did nothing must not read later as a check that passed.
  */
 export function inertLaunchContractNote(declared, manifest) {
@@ -160,7 +157,11 @@ export function packageScripts(cwd) {
         return {};
     }
 }
-/** Does this tree's Makefile declare `target`? */
+/**
+ * Does this tree's Makefile declare `target`? Reads the literal name `Makefile`
+ * only — unlike {@link readLaunchManifest}, this one does not walk make's lookup
+ * order, so a `GNUmakefile`-only tree answers false.
+ */
 export function makeHasTarget(cwd, target) {
     try {
         const mk = readFileSync(path.join(cwd, 'Makefile'), 'utf8');

package/dist/task/ledger.js

@@ -3,24 +3,26 @@
  * `.pi-tasks/` (contracts, launch-contract, env-notes, accept-debt, repair-queue,
  * requirements, requirements-owned).
  *
- * Six modules each kept their own copy of the same seven steps: read the file
- * (ANY error → ''), parse it into records, key the records, drop an incoming item
- * whose key is already present, cap to the newest MAX (oldest dropped), mkdir the
- * tasks dir, write the whole file back (`lines.join('\n') + '\n'`, plain
- * `writeFile`, NOT atomic), and swallow every fault — a ledger is a sharpener or
- * an auditing aid, never a blocker of the phase or gate that calls it. What
- * genuinely varied per site is the DATA SHAPE (file name, cap, key, line format,
- * parser) and exactly one RULE — what an append does when it adds nothing new
- * (see `onNoop`). Everything else here is the ritual, so a module that keeps a
- * ledger is an ADAPTER: it declares its ledger and calls read/append/write.
+ * The ritual is seven steps: read the file (ANY error → ''), parse it into records,
+ * key the records, drop an incoming item whose key is already present, cap to the
+ * newest MAX (oldest dropped), mkdir the tasks dir, write the whole file back
+ * (`lines.join('\n') + '\n'`, plain `writeFile`, NOT atomic). Every fault is
+ * swallowed — a ledger is a sharpener or an auditing aid, never a blocker of the
+ * phase or gate that calls it.
+ *
+ * What varies per site is the DATA SHAPE (file name, cap, key, line format, parser)
+ * and exactly one RULE — what an append does when it adds nothing new (see
+ * `onNoop`). Everything else here is the ritual, so a module that keeps a ledger is
+ * an ADAPTER: it declares its ledger and calls read/append/write.
  *
  * Contract details a caller can rely on:
  *   • `readRaw` is the trimmed file text ('' when absent or unreadable). Prompt-block
  *     builders take this string.
- *   • `read` is `parse(readRaw)`; every parser skips blank lines and lines it cannot
- *     read, so a corrupt line is dropped, never thrown on.
- *   • `append` with an empty batch is a no-op (no read, no write). Within a batch
- *     the first item with a key wins; a key already stored wins over the batch.
+ *   • `read` is `parse(readRaw)`; every adapter's parser skips blank lines and lines
+ *     it cannot read, so a corrupt line is dropped, never thrown on.
+ *   • `append` with an empty batch is a no-op — it does not even create `.pi-tasks/`.
+ *     Within a batch the first item with a key wins; a key already stored wins over
+ *     the batch.
  *   • `write` overwrites with exactly these records; an empty list writes an empty
  *     file (this is how a drained queue and a fully-resolved debt ledger look).
  *   • Neither `append` nor `write` ever throws.