@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/apis-contract.js

@@ -1,68 +1,36 @@
 /**
- * STAGE 2 LEVER — the APIS OUTPUT CONTRACT.
- *
- * ── WHAT STAGE 1 MEASURED, AND WHY THIS IS THE ONLY VARIABLE LEFT ─────────────────────────
- *
- * worker:apis terminates when every entry on its output list has a SIGNATURE. That is not an
- * inference; it is what 16 live reps say (commit 807ffad, raw data ~/tmp/apis-stopping-point):
- *   - it does not stop at a budget — docs calls/rep mean 8.5, sd 3.8, cv 0.45, range 3-14;
- *   - it does not stop because it is circling — near-repeats 2/45 = 4.4% over the last three
- *     calls, LOWER than the 10.2% whole-trajectory rate;
- *   - it does not stop because nothing new is arriving — the FINAL answer of a rep still
- *     returns 39 symbols no earlier answer in that rep carried;
- *   - it does not stop with holes in its own output — ungrounded symbols 2/588 = 0.3%,
- *     strict open-gap entries 2/277 = 0.7%.
- * What it does instead: 95.3% of its lookups reach the emitted section and 72.2% of emitted
- * entries were themselves asked about. The trajectory and the output are the SAME LIST. And
- * the list's format is `<name>  <one-line signature or use>` — so of 61 package queries across
- * 15 reps, 52 (85.2%) are signature questions and THREE are behaviour questions.
- *
- * The worker stops because the artifact it was asked for is complete by the standard its
- * format sets, and a signature satisfies that standard. "What does this parameter MEAN" is not
- * a field of the thing it is building, so nothing in its output is ever left unfilled by not
- * asking it. That is why it never escalates: escalation answers a question it has no reason to
- * ask.
- *
- * ── WHY THIS BLOCK AND NOT A THIRD INSTRUCTION ────────────────────────────────────────────
- *
- * Two levers have already failed against this seam, and they failed for the same reason:
- *   PROMPT 2  conditioned on RECOGNISING an answer as inadequate (type-only). Reach 9/1680 =
- *             0.54% of answers. But a type signature is not an inadequate answer to the
- *             question actually being asked — it is exactly the requested field.
- *   PROMPT 4  conditioned on nothing at all, and pointed the worker at the exact page that
- *             would have prevented the fatal bug. 2/20 vs 3/20, Fisher p = 0.50, with delivery
- *             of the block into the assembled prompt PROVEN separately. A pointer only helps a
- *             worker that has an unmet slot to fill.
- * Both acted on the ANSWER side or the TARGET side. This one adds a FIELD A SIGNATURE CANNOT
- * FILL, which is the variable that is not flat.
- *
- * ── STEP 3 OF THE FALLBACK IS LOAD-BEARING. DO NOT "CLOSE" IT ─────────────────────────────
- *
- * The `UNVERIFIED:` escape is mandatory and is not a loophole. Forbidding abstention is
- * precisely how F-1 manufactured the confident wrong claim that killed run 15: worker:context,
- * holding one true citable fact (the pinned hono version), fused it with an uncheckable one
- * (what `hc`'s base URL means) under a single attribution — `hc<AppType>('/api')` — and every
- * request in the shipped product went to /api/api/… and 404'd. A lever that buys behaviour
- * questions with fabrication is a FAIL, not a win. The A/B asserts it: excerptVerified===false
- * and the ungrounded-symbol rate must not rise.
- *
- * Exported unwired first, wired into RESEARCH_APIS_PROMPT in the same series; the STEP A
- * feasibility probe splices this exact text into a patched dist so the probe and the shipped
- * lever can never drift apart.
- */
-/**
- * The extra output-contract clause for RESEARCH_APIS_PROMPT.
- *
- * Wording notes, because each of these is answering something measured:
- *  - "NOT DONE WHEN THEY HAVE A SIGNATURE" is the whole lever. Stage 1's mechanism is
- *    completion-by-format, so the change has to move the completion bar, not add advice.
- *  - the worked example is the run-15 fatal case verbatim (`hc(baseUrl: Prefix, …)`), because
- *    a rule without an instance of what does NOT satisfy it reads as satisfied by anything.
- *  - step 2 says escalation is EXPECTED rather than permitted: bundled .d.ts files genuinely
- *    do not carry semantics, and a worker that reads "you may escalate" has been told nothing
- *    it did not already have (PROMPT 4 measured what permission alone achieves: nothing).
- *  - step 3 is stated as CORRECT and REQUIRED, in those words, so the field cannot be closed
- *    by guessing. See the header.
+ * An output-contract clause for the APIS research prompt that is NOT wired in.
+ *
+ * READ THIS FIRST: nothing splices this into `RESEARCH_APIS_PROMPT`. The only
+ * references to `APIS_SEMANTICS_CONTRACT` in the tree are its own tests and a
+ * regression guard in prompts.test.ts that asserts the shipped prompt does NOT
+ * contain it. The text is kept, and pinned by tests, so the lever can be read and
+ * re-tried — not because it is in use.
+ *
+ * WHAT IT WOULD CHANGE. `worker:apis` treats an entry as finished once it has a
+ * SIGNATURE, because that is what its output format asks for. A signature says
+ * nothing about what an argument MEANS, and the implementing agent has to guess —
+ * a plausible wrong guess about a base URL or a default is the most damaging thing
+ * this section can carry. The clause moves the completion bar: an entry is
+ * unfinished until it also carries a SEMANTICS field.
+ *
+ * STEP 3 OF THE FALLBACK IS LOAD-BEARING. DO NOT "CLOSE" IT. The `UNVERIFIED:`
+ * escape is mandatory and is not a loophole: a worker that may not abstain has
+ * nowhere to put an uncheckable fact except into a confident claim. A lever that
+ * buys behaviour questions with fabrication is a regression, not a win.
+ *
+ * Wording notes, each answering something the shape of the prompt forces. All four
+ * are present in the string below, checked:
+ *  - "NOT DONE WHEN THEY HAVE A SIGNATURE" is the whole lever. The worker stops by
+ *    format, so the change has to move the format's bar, not add advice.
+ *  - the worked example (`hc(baseUrl: Prefix, …)`) shows an entry that does NOT
+ *    satisfy the rule. A rule with no counter-example reads as satisfied by
+ *    anything.
+ *  - step 2 says escalation is EXPECTED — "Expect this:" — rather than permitted.
+ *    Bundled `.d.ts` files genuinely carry no semantics, and "you may escalate"
+ *    tells a worker nothing it did not already have.
+ *  - step 3 is stated as "A CORRECT AND REQUIRED OUTCOME", in those words, so the
+ *    field cannot be closed by guessing.
  */
 export const APIS_SEMANTICS_CONTRACT = `THIRD-PARTY PACKAGE ENTRIES ARE NOT DONE WHEN THEY HAVE A SIGNATURE. For every entry whose symbol comes from a third-party npm package — not this project's own source, not a runtime builtin — the line carries a SECOND field saying what the thing MEANS in use: what one of its arguments stands for, what it defaults to, what a path/URL/prefix it is handed is relative to, or what its return value actually is. Format:
   <name>  <one-line signature or use>  — SEMANTICS: <what it means in use>

package/dist/task/artifact-closure.d.ts

@@ -32,9 +32,16 @@ export interface ProducedOutputs {
     outdirs: Set<string>;
 }
 export declare function emptyProducers(): ProducedOutputs;
-/** Normalize a literal path: posix separators, strip ./ prefixes, query/hash
- *  tails (HTML), trailing slash. Returns null when the literal is not a
- *  checkable relative path (URL, absolute, template hole, glob — step aside). */
+/** Normalize a literal path: posix separators, strip `./` prefixes, query/hash
+ *  tails (HTML), wrapping quotes, trailing slash. Returns null when the literal
+ *  is not a checkable repo path — a scheme URL, protocol-relative `//host/x`,
+ *  `~`, a `${…}` hole, a glob, anything with embedded whitespace, and anything
+ *  under `node_modules/`.
+ *
+ *  A single leading `/` is NOT a rejection: it is treated as root-relative and
+ *  resolved from the repo root, which is what `<script src="/app.js">` means.
+ *  So `/app.js` normalizes to `app.js`. A drive-letter path like `C:\win\a.js`
+ *  is rejected, but as a SCHEME, not as an absolute path. */
 export declare function normalizeRefPath(raw: string): string | null;
 /** Extract runtime refs from one JS/TS source. */
 export declare function extractJsRefs(source: string, referencer: string): RuntimeRef[];
@@ -84,22 +91,29 @@ export declare function collectProducersFromCommand(cmd: string, prod: ProducedO
  * `writeFile(Sync)`, `createWriteStream`, `copyFile` dest, `mkdir(Sync)`),
  * `Bun.build({entrypoints, outdir})` (enumerable — unless a `naming` option
  * makes the output names underivable, then opaque), `outfile:`, and `Bun.spawn`
- * argv arrays re-fed through the shell-command collector (the mx5 build.ts
- * shape: tailwind's `-o dist/app.css` lives in a spawn array).
+ * argv arrays re-fed through the shell-command collector, for the build-script
+ * shape where a tool's `-o dist/app.css` lives inside a spawn array rather than
+ * in package.json. All four run as described: entrypoints give
+ * `dist{a,b}`, adding `naming` turns `dist` opaque and drops the stems, the spawn
+ * array yields `dist/app.css`, and `outfile:` yields its exact file.
  */
 export declare function collectProducersFromSource(source: string, prod: ProducedOutputs): void;
 /**
  * A WATCH/DEV script — one a production build never invokes.
  *
- * The load-bearing rule of nexttask 3 (mx5 run 18): `dist/app.css` had exactly
- * one producer, `dev:css` (`@tailwindcss/cli … -o dist/app.css --watch`), a
- * watch-mode dev script. The gate's own commands are `build`, `test`, `lint` —
- * none of them runs it, so the shipped page loaded zero CSS while the closure
- * table happily reported the file "produced". A production artifact closed only
- * by a watch script is dangling by construction.
+ * The rule this exists for: a file whose ONLY producer is a watch-mode script —
+ * `dev:css` running `tailwindcss … -o dist/app.css --watch` — is not produced by
+ * a release at all. The gate runs `build`, `test`, `lint`; none of them invokes
+ * it, so the shipped page loads no CSS while a naive producer table reports the
+ * file "produced". A production artifact closed only by a watch script is
+ * dangling by construction.
  *
- * Deterministic and name-or-flag based, exactly as pre-registered: a script
- * whose NAME starts with `dev`/`watch`, or whose BODY carries `--watch`.
+ * Deterministic, name-or-flag based: a script whose NAME starts with
+ * `dev`/`watch` (bare or before `:`/`_`/`-`), or whose BODY carries `--watch`.
+ * Run across the edge cases — `development` and `predev` are NOT dev scripts,
+ * while a script literally named `build` running `tsc --watch` IS one. And
+ * end-to-end: with `excludeDevScripts`, a `dist/app.css` produced only by
+ * `dev:css` drops out of the producer table entirely.
  */
 export declare function isDevScript(name: string, body: string): boolean;
 export interface ProducerOpts {

package/dist/task/artifact-closure.js

@@ -1,16 +1,20 @@
 /**
- * artifact-closure — dangling runtime file references (the run-13 index.html
- * class, nexttask PROMPT 2).
+ * artifact-closure — dangling runtime file references.
  *
- * The failure this closes (mx5 run 13, validated): a runtime file reference with
- * NO producer anywhere in the plan shipped silently. The server's SPA fallback
- * read `Bun.file('dist/index.html')`; the build emitted only `app.css` +
- * `main.js`; no task, script, or build output ever CREATES `index.html` — so the
- * shipped app 404'd on every non-API GET while coverage reported "0 unowned"
- * (sentence-grounded coverage credited the SERVING side to the server task and
- * was structurally blind to the missing PRODUCING side). The spec itself was
- * internally dangling: its prose required serving `index.html` while its file
- * tree and build section never defined it.
+ * The failure this closes: a runtime file reference with NO producer anywhere in
+ * the plan ships silently. A server's SPA fallback reads
+ * `Bun.file('dist/index.html')`; the build emits only `app.css` and `main.js`;
+ * nothing — no task, no script, no build output — ever CREATES `index.html`, so
+ * the app 404s on every non-API GET. Sentence-grounded coverage cannot see it,
+ * because it credits the SERVING side to the server's task and is structurally
+ * blind to the missing PRODUCING side. The spec can be internally dangling the
+ * same way: prose requiring `index.html` be served while the file tree and build
+ * section never define it.
+ *
+ * Reproduced end-to-end while checking this file. A tree whose build runs
+ * `bun build entry.ts --outdir dist` and `tailwindcss -o dist/app.css`, with a
+ * server reading `dist/index.html`, `dist/app.css` and `dist/entry.js`, reports
+ * exactly ONE dangle — `dist/index.html` — and the other two stay silent.
  *
  * Two seams consume this module:
  *   • plan-time (auto-orchestrator): refs extracted from the SPEC's own snippets
@@ -19,26 +23,30 @@
  *     `missing` list (forcing a round that assigns a producing task) and are
  *     carried into `.pi-tasks/requirements.md` when still unowned at exhaustion.
  *   • final gate: the shipped tree is scanned; a dangling reference is a ranked
- *     failure naming referencer + missing path (rides PROMPT 1's aggregation).
+ *     failure naming referencer + missing path.
  *
- * FP discipline (the run-12 groundedCoverage lesson — ground in artifacts the
- * model can't fake, and the standing guard direction — inconclusive is NEVER
- * evidence):
- *   • literal string paths only; any dynamic expression steps aside.
+ * FP discipline — ground in artifacts the model cannot fake, and treat
+ * inconclusive as never being evidence. Each rule below was run:
+ *   • literal string paths only. A template hole, a bare variable and a
+ *     concatenation each extract nothing; the literal beside them extracts.
  *   • a ref is DANGLING only on POSITIVE producer evidence: it must sit under a
- *     directory whose outputs we could actually ENUMERATE (parsed build
+ *     directory whose outputs could actually be ENUMERATED (parsed build
  *     script/flags) and not be among them — or be a missing source-extension
  *     script entrypoint, which nothing ever builds. A ref under a directory
- *     produced by machinery we could NOT enumerate (vite/tsc/next/unknown
- *     commands that mention it) is OPAQUE and always steps aside.
+ *     produced by machinery that could NOT be enumerated is OPAQUE and steps
+ *     aside. Demonstrated on ONE tree by changing only the build command:
+ *     `vite build` (opaque `dist`) reports zero dangles, while
+ *     `bun build entry.ts --outdir dist` (enumerable `dist`) reports both refs.
  *   • gitignored-but-built paths therefore never fire: being built means a
  *     producer names them (exact file, enumerable stem, or opaque dir).
- *   • existence is checked on the live tree (existsSync), so anything already
- *     present — committed, generated, or hand-made — is satisfied.
+ *   • existence is checked on the live tree, so anything already present —
+ *     committed, generated or hand-made — is satisfied. Creating a GITIGNORED
+ *     `dist/index.html` took the same tree from one dangle to none.
  *
- * Note the mx5 server GUARDED its read (`if (!(await htmlFile.exists())) return
- * c.notFound()`): an existence guard is exactly how the bug presents (permanent
- * 404), so guarded reads deliberately do NOT step aside.
+ * A GUARDED read does NOT step aside, deliberately. An existence guard
+ * (`if (!(await htmlFile.exists())) return c.notFound()`) is exactly how this bug
+ * presents — a permanent 404 rather than a crash — so the guard is a symptom, not
+ * an all-clear. Confirmed: the same ref flags with and without the guard.
  */
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import * as path from 'node:path';
@@ -52,9 +60,16 @@ export function emptyProducers() {
         outdirs: new Set()
     };
 }
-/** Normalize a literal path: posix separators, strip ./ prefixes, query/hash
- *  tails (HTML), trailing slash. Returns null when the literal is not a
- *  checkable relative path (URL, absolute, template hole, glob — step aside). */
+/** Normalize a literal path: posix separators, strip `./` prefixes, query/hash
+ *  tails (HTML), wrapping quotes, trailing slash. Returns null when the literal
+ *  is not a checkable repo path — a scheme URL, protocol-relative `//host/x`,
+ *  `~`, a `${…}` hole, a glob, anything with embedded whitespace, and anything
+ *  under `node_modules/`.
+ *
+ *  A single leading `/` is NOT a rejection: it is treated as root-relative and
+ *  resolved from the repo root, which is what `<script src="/app.js">` means.
+ *  So `/app.js` normalizes to `app.js`. A drive-letter path like `C:\win\a.js`
+ *  is rejected, but as a SCHEME, not as an absolute path. */
 export function normalizeRefPath(raw) {
     let p = raw.trim().replace(/\\/g, '/');
     // Markdown/shell wrapping (a spec bullet's `-o dist/app.css` arrives with a
@@ -147,26 +162,27 @@ export function extractHtmlRefs(source, referencer) {
     return out;
 }
 // ---------------------------------------------------------------------------
-// GENERATED HTML (nexttask 3, mx5 run 18).
+// GENERATED HTML.
 //
-// The run-13 checker fired correctly on `src/server/index.ts → dist/index.html`;
-// the autofix satisfied it by appending an HTML template literal to `build.ts`
-// and `Bun.write`ing it — and that page pointed at `/app.css`, which `bun run
-// build` never emits (only the watch-mode `dev:css` does). The re-run gate saw
-// nothing, because the extractor scans HTML FILES and JS READS, never the HTML a
-// source GENERATES. So one dangling reference was closed by creating another one
-// indirection deeper.
+// Without this pass there is a way to "fix" a dangle by moving it one
+// indirection deeper. The extractor scans HTML FILES and JS READS; it does not
+// see the HTML a source GENERATES. So a build script can satisfy a missing
+// `dist/index.html` by writing one from a template literal — and that page can
+// point at an asset the production build never emits, which nothing then checks.
 //
 // Scope discipline, the reason this does not become an FP machine: a literal is
 // scanned ONLY when it reaches a write whose destination is an HTML file inside a
-// directory a BUILD TOOL declared as its output (`prod.outdirs`). An email-body
-// template (`~/hub/aiz-server/src/connections/mailTemplate.ts` — `export default
-// \`<!doctype html>…\``) is never written to a build output and is therefore
-// never scanned, `<img src="cid:logo">` and all.
+// directory a BUILD TOOL declared as its output (`prod.outdirs`). Both halves
+// were run. The same `Bun.write("dist/index.html", …)` source yields refs when
+// `dist` is a declared outdir and NOTHING when it is not; a write into `report/`
+// — enumerable, but never an outdir — yields nothing either. An email-body
+// template that is only exported, never written, is not collected at all,
+// `<img src="cid:logo">` and all.
 // ---------------------------------------------------------------------------
-/** Asset attributes scanned in GENERATED HTML. Wider than HTML_PATTERNS (which
- *  keeps scanning on-disk .html files exactly as it always has) by the media
- *  tags nexttask 3 names. */
+/** Asset attributes scanned in GENERATED HTML: everything HTML_PATTERNS matches,
+ *  plus `<source>`, `<video>` and `<audio>` src. On-disk `.html` files keep using
+ *  the narrower HTML_PATTERNS — confirmed, a `<video src>` in a real HTML file
+ *  extracts nothing. */
 const GENERATED_HTML_PATTERNS = [
     ...HTML_PATTERNS,
     {
@@ -199,8 +215,10 @@ function readLiteral(src, i) {
     }
     return null;
 }
-/** `const NAME = <literal>` bindings (also let/var) — the mx5 build.ts shape is
- *  `const html = \`…\`` followed by `Bun.write('dist/index.html', html)`. */
+/** `const NAME = <literal>` bindings (also let/var). The shape this exists for is
+ *  a build script holding its page in a variable — `const html = \`…\`` followed by
+ *  `Bun.write('dist/index.html', html)` — where the literal and the write are not
+ *  the same expression. */
 function literalBindings(src) {
     const out = new Map();
     const re = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?=['"`])/g;
@@ -486,8 +504,11 @@ export function collectProducersFromCommand(cmd, prod, opts = {}) {
  * `writeFile(Sync)`, `createWriteStream`, `copyFile` dest, `mkdir(Sync)`),
  * `Bun.build({entrypoints, outdir})` (enumerable — unless a `naming` option
  * makes the output names underivable, then opaque), `outfile:`, and `Bun.spawn`
- * argv arrays re-fed through the shell-command collector (the mx5 build.ts
- * shape: tailwind's `-o dist/app.css` lives in a spawn array).
+ * argv arrays re-fed through the shell-command collector, for the build-script
+ * shape where a tool's `-o dist/app.css` lives inside a spawn array rather than
+ * in package.json. All four run as described: entrypoints give
+ * `dist{a,b}`, adding `naming` turns `dist` opaque and drops the stems, the spawn
+ * array yields `dist/app.css`, and `outfile:` yields its exact file.
  */
 export function collectProducersFromSource(source, prod) {
     const src = stripCommentLines(source);
@@ -637,15 +658,19 @@ function packageScripts(cwd) {
 /**
  * A WATCH/DEV script — one a production build never invokes.
  *
- * The load-bearing rule of nexttask 3 (mx5 run 18): `dist/app.css` had exactly
- * one producer, `dev:css` (`@tailwindcss/cli … -o dist/app.css --watch`), a
- * watch-mode dev script. The gate's own commands are `build`, `test`, `lint` —
- * none of them runs it, so the shipped page loaded zero CSS while the closure
- * table happily reported the file "produced". A production artifact closed only
- * by a watch script is dangling by construction.
+ * The rule this exists for: a file whose ONLY producer is a watch-mode script —
+ * `dev:css` running `tailwindcss … -o dist/app.css --watch` — is not produced by
+ * a release at all. The gate runs `build`, `test`, `lint`; none of them invokes
+ * it, so the shipped page loads no CSS while a naive producer table reports the
+ * file "produced". A production artifact closed only by a watch script is
+ * dangling by construction.
  *
- * Deterministic and name-or-flag based, exactly as pre-registered: a script
- * whose NAME starts with `dev`/`watch`, or whose BODY carries `--watch`.
+ * Deterministic, name-or-flag based: a script whose NAME starts with
+ * `dev`/`watch` (bare or before `:`/`_`/`-`), or whose BODY carries `--watch`.
+ * Run across the edge cases — `development` and `predev` are NOT dev scripts,
+ * while a script literally named `build` running `tsc --watch` IS one. And
+ * end-to-end: with `excludeDevScripts`, a `dist/app.css` produced only by
+ * `dev:css` drops out of the producer table entirely.
  */
 export function isDevScript(name, body) {
     return /^(?:dev|watch)\b|^(?:dev|watch)[:._-]/i.test(name) || /(?:^|\s)--watch\b/.test(body);
@@ -666,7 +691,8 @@ export function discoverProducers(cwd, opts = {}) {
         for (const cmd of splitShellCommands(body)) {
             collectProducersFromCommand(cmd, prod);
             // A script that runs a local JS/TS file may produce through it —
-            // parse that file's source too (the mx5 `bun build.ts` shape).
+            // parse that file's source too, for the `bun build.ts` shape where
+            // the real output flags live inside the script, not the command.
             for (const t of cmd.split(/\s+/)) {
                 if (isPathToken(t) && /\.(?:ts|js|mjs|cjs)$/.test(t)) {
                     const p = normalizeRefPath(t);
@@ -796,9 +822,9 @@ export function findDanglingArtifacts(cwd) {
     const prod = discoverProducers(cwd);
     // Second, PRODUCTION-only table: identical machinery minus watch/dev scripts.
     // Generated-HTML refs resolve against this one, so a file whose only producer
-    // is `dev:css --watch` does not close a reference the built page makes
-    // (nexttask 3's load-bearing rule). Everything else keeps resolving against
-    // the full table, so no existing finding moves.
+    // is a `--watch` script does not close a reference the built page makes.
+    // Everything else keeps resolving against the full table, so widening the
+    // production view cannot move an existing finding.
     const prodProduction = discoverProducers(cwd, { excludeDevScripts: true });
     const refs = [];
     const sources = [];
@@ -880,9 +906,9 @@ export function danglingGateFailureText(d) {
         + `but nothing in the tree, build outputs, or scripts produces it — ${d.reason}`);
 }
 // ---------------------------------------------------------------------------
-// Plan-time seam: the SPEC's own snippets referencing artifacts the spec never
-// defines (mx5 run 13: DESIGN/PROJECT.md L224 required serving index.html; the
-// file tree (§7) and build section (§9) never defined it).
+// Plan-time seam: the SPEC's own snippets and prose referencing artifacts the
+// spec never defines — a design document whose behaviour section requires
+// serving `index.html` while its file tree and build section never produce it.
 // ---------------------------------------------------------------------------
 /** Does the spec LIST the file as its own artifact — a file-tree entry or a
  *  bullet whose first token is (or ends with) the basename? Prose that merely
@@ -903,14 +929,16 @@ export function specListsFile(spec, refPath) {
     return false;
 }
 /** Consuming-side prose verbs: a spec sentence that SERVES/READS/LOADS a
- *  backticked file is referencing it at runtime (mx5 run 13, the exact line:
- *  "**SPA fallback:** non-`/api` GETs serve the built `index.html`."). */
+ *  backticked file is referencing it at runtime — the shape being a line like
+ *  "**SPA fallback:** non-`/api` GETs serve the built `index.html`." */
 const PROSE_CONSUME_RE = /\b(?:serves?|serving|served|fallback|reads?|loads?|renders?)\b/i;
 /** Runtime-artifact extensions the prose channel accepts. Prose is the loosest
- *  signal, so it is whitelist-tight: a backticked dotted identifier (`c.var.user`,
- *  `Bun.password.hash` — measured FPs on the real mx5 spec) must never read as a
- *  file, and doc files a spec tells the READER to read (`README.md`) don't
- *  count either. Code-construct refs are not subject to this list. */
+ *  signal, so the list is a tight whitelist rather than a blocklist: a backticked
+ *  dotted identifier must never read as a file, and neither must a doc file a
+ *  spec tells the READER to open. Run on a consuming-verb line, `c.var.user`,
+ *  `Bun.password.hash`, `foo.bar` and `README.md` all extract nothing, while
+ *  `index.html`, `data/seed.json` and `assets/logo.svg` all extract.
+ *  Code-construct refs are not subject to this list. */
 const PROSE_ASSET_EXT_RE = /\.(?:html?|css|m?js|cjs|json|svg|png|jpe?g|gif|webp|ico|woff2?|ttf|otf|wasm|webmanifest|xml|csv|sql|ya?ml|toml|pdf|mp[34]|db|sqlite)$/i;
 /** Backticked, asset-extension, path-shaped tokens on consuming-verb lines. */
 export function extractSpecProseRefs(spec) {

package/dist/task/auto-commit.d.ts

@@ -8,17 +8,23 @@ export interface CommitResult {
     /** UNTRACKED regenerable test-runner output this commit deliberately left out
      *  of the index (see `stagePathspec`). Empty/absent when nothing was excluded.
      *  Present so the caller can TRAIL it: a silent exclusion is the same failure
-     *  class as the silent ignored-path write nexttask 4 closed. */
+     *  class as a silent write to an ignored path. */
     excluded?: string[];
 }
 /**
- * Does this git stderr describe a missing author identity? Seen live (mx5 run 4):
- * the headless docker container has no HOME gitconfig, so EVERY per-task commit
- * failed "Author identity unknown" — which silently disabled enforce and every
- * commit-based differential guard for the whole run.
+ * Does this git stderr describe a missing author identity?
+ *
+ * The failure it catches is total rather than partial: with no usable gitconfig
+ * every per-task commit fails, which silently disables enforce and every
+ * commit-based differential guard for the rest of the run. Reproduced with real
+ * git — committing with `HOME` unset and both config files pointed at
+ * `/dev/null` prints "Author identity unknown" plus the `user.email` /
+ * `user.name` advice, and this predicate matches that text while rejecting an
+ * unrelated `fatal: not a git repository`.
  */
 export declare function isIdentityFailure(stderr: string): boolean;
-/** Fallback identity for environments with no git config (headless containers). */
+/** Fallback identity for environments with no git config. Confirmed against real
+ *  git: the same commit that fails with no identity succeeds with these args. */
 export declare const FALLBACK_IDENTITY_ARGS: readonly ["-c", "user.name=pi-task", "-c", "user.email=pi-task@local"];
 export declare function git(cwd: string, args: string[], signal: AbortSignal | undefined, spawnFn?: SpawnFn): Promise<{
     stdout: string;
@@ -31,40 +37,43 @@ export declare function git(cwd: string, args: string[], signal: AbortSignal | u
  * `test-results/`, `playwright-report/`, `coverage/`, `.nyc_output/`,
  * `.last-run.json`, `*.tsbuildinfo`.
  *
- * This is the other half of mx5 run 20. TASK_0027's snapshot ran a bare
- * `git add -A` over a tree the test run had just littered with three Playwright
- * FAILURE screenshots (`*-actual.png` — written only when a screenshot assertion
- * fails), committed them, and thereby made them tracked deliverables. Two whole
- * final-gate fix attempts were then rejected for deleting them. The deletion guard
- * fix (write-guard.ts) stops the rejection; this stops the tracking.
+ * The failure this closes: a bare `git add -A` sweeps up whatever the test run
+ * just littered the tree with — a failure screenshot, a coverage dir — and commits
+ * it, making regenerable output a TRACKED deliverable. A later task that cleans it
+ * up then reads as deleting someone's work.
  *
  * ONLY UNTRACKED PATHS ARE EXCLUDED, and that is load-bearing rather than tidy.
- * `git ls-files --others` lists untracked, non-ignored files and nothing else, so a
- * path git ALREADY tracks can never appear here — meaning a project that
- * deliberately commits, say, a `coverage/` badge keeps having its edits to it
- * committed. Excluding by directory pathspec instead (`:(exclude)coverage/`) would
- * silently stop committing those.
+ * Both halves measured with real git in a repo with a gitignored `coverage/` and
+ * an untracked `test-results/`:
+ *   • `ls-files --others --exclude-standard` returned the untracked file alone;
+ *     dropping the flag brought the gitignored one back too.
+ *   • a TRACKED file never appears, even while modified.
+ * So a project that deliberately commits, say, a `coverage/` badge keeps having
+ * its edits to it committed. Excluding by directory pathspec instead
+ * (`:(exclude)coverage/`) would silently stop committing those.
  *
- * Best-effort: any git failure yields an empty list, i.e. today's `git add -A`.
+ * Best-effort: any git failure yields an empty list, i.e. a plain `git add -A`.
  */
 export declare function untrackedArtifacts(cwd: string, signal?: AbortSignal, spawnFn?: SpawnFn): Promise<string[]>;
 /** `:(exclude)` pathspecs for `git add -A`; empty when nothing is excluded, so the
- *  common case is byte-identical to the previous bare `git add -A`. */
+ *  common case adds no arguments at all and stays a bare `git add -A`. */
 export declare function stagePathspec(excluded: readonly string[]): string[];
 /**
  * Paths with unmerged index entries (an in-progress merge conflict), deduped.
  * Empty outside a git repo or on any git error — this is a GUARD input, and a
  * guard that cannot conclude must not block.
  *
- * Why it exists (mx5 run 6): a stale `git stash pop` mid-task left two paths UU;
- * every later commit was doomed, three verify passes ran against a conflicted
- * tree, and — worse — a blind `git add -A` on that index would have silently
- * "resolved" the conflict with whatever happened to be on disk.
+ * Why it exists: with an unmerged index every later commit is doomed, verify runs
+ * against a conflicted tree, and — worst — a blind `git add -A` SILENTLY resolves
+ * the conflict with whatever is on disk. Reproduced on a real conflict: `git
+ * status` showed `UU c.txt`, then a bare `git add -A` turned it into `M  c.txt`
+ * and left `ls-files -u` empty. The conflict markers become staged content and
+ * nothing says so.
  */
 export declare function gitUnmergedPaths(cwd: string, signal?: AbortSignal, spawnFn?: SpawnFn): Promise<string[]>;
 /** Sha of `refs/stash`, or null when there is no stash (or not a git repo). Used
  *  to detect a stash created (or consumed) during a task and left behind — the
- *  exact landmine that detonated mx5 run 6 two days after it was pushed. */
+ *  exact landmine that detonates days after it is pushed. */
 export declare function gitStashRef(cwd: string, signal?: AbortSignal, spawnFn?: SpawnFn): Promise<string | null>;
 /**
  * Stage everything (`git add -A`) and commit it with `message`. Honors
@@ -81,17 +90,19 @@ export declare function gitCommitAll(cwd: string, message: string, signal?: Abor
  * verified task commit underneath it.
  *
  * `reset --hard` targets the enforce pass's in-place SOURCE edits. But it must NOT
- * rewind the forensic gate trail: `.pi-tasks/` is frequently TRACKED (the per-task
- * snapshots stage it via `git add -A`), so a bare reset restores TASK_00NN.md to the
- * snapshot commit and ERASES every trail line written after it — the "commit: task
- * snapshot committed", "enforce(edit): …", and resolution lines (mx5 run 9:
- * TASK_0007/0008/0012 each lost their whole post-snapshot trail on this exact path,
- * so a passing-then-reverted task looked like it had never been committed). So the
- * trail is snapshotted before the reset and restored after — the revert undoes code,
- * the audit log survives.
+ * rewind the forensic gate trail. `.pi-tasks/` is frequently TRACKED here — unlike
+ * the accept-debt ledger's writers, the per-task snapshot stages it with a plain
+ * `git add -A` and no exclusion — so a bare reset rewinds the task file along with
+ * the source and ERASES every trail line written after the snapshot.
+ *
+ * Both halves were run on a real repo. A bare `reset --hard HEAD~1` restored the
+ * source AND dropped the trail line added after the snapshot; calling this
+ * function on the identical setup restored the source and kept that line. The
+ * revert undoes code, the audit log survives.
  *
- * Best-effort and never throws: a git failure is swallowed (the caller has
- * already decided to keep the verified work; a failed reset only leaves the
- * enforce commit in place, which is surfaced as a warning).
+ * Best-effort and never throws: a git failure is swallowed, since the caller has
+ * already decided to keep the verified work and a failed reset only leaves the
+ * enforce commit in place, which is surfaced as a warning. Called on a directory
+ * that is not a repo at all, it returns without throwing.
  */
 export declare function gitDropLastCommit(cwd: string, signal?: AbortSignal, spawnFn?: SpawnFn): Promise<void>;