@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/accept-debt.js

@@ -1,18 +1,24 @@
 /**
  * accept-debt — a per-run ledger of tasks the user ACCEPTED despite a verify-FAIL.
  *
- * The failure this closes (mx5 run 4 B3, carried open; run 8 fixture TASK_0012):
+ * The failure this closes:
  * when a task's VERIFY gate FAILs and the resolution picker's ACCEPT branch is
  * chosen, the human blesses the artifact AS-IS — a real, recorded defect ships and
- * NOTHING revisits it. Run 8's TASK_0012 shipped a frozen-path violation that was
- * accepted and never re-checked; a later task could have fixed it, or it could
- * still be broken at run end, and no gate ever said which.
+ * NOTHING revisits it. A later task could have fixed it, or it could still be
+ * broken at run end, and no gate ever said which.
  *
- * Mechanism (mirrors env-notes.ts / contracts.ts): each ACCEPT-despite-FAIL is
- * appended HOST-SIDE to `.pi-tasks/accept-debt.md` as a durable `<taskId>\t<reason>`
- * record (the gate sequence never lets a child write the file — no artifact
- * corruption). The ledger lives under `.pi-tasks/`, so it survives discardEdits and
- * the git-state guard, both of which exclude that directory by design.
+ * Mechanism (mirrors env-notes.ts / contracts.ts, which share `makeLedger`): each
+ * ACCEPT-despite-FAIL is appended HOST-SIDE to `.pi-tasks/accept-debt.md` as a
+ * durable tab-separated record. The gate sequence never lets a child write the
+ * file, so it cannot be corrupted by the work it is recording.
+ *
+ * Living under `.pi-tasks/` is what makes it durable, and both exclusions are
+ * explicit rather than incidental. `discardEdits` runs
+ * `git checkout -- . ':(exclude).pi-tasks'` then `git clean -fd -e .pi-tasks`, and
+ * the git-state guard writes its tree with the same `:(exclude).pi-tasks` pathspec.
+ * Confirmed against a real repo: a discard restored the tracked file, removed the
+ * untracked one, and left the ledger byte-identical; and appending a debt did not
+ * move the guard's tree hash, while a one-line source edit did.
  *
  * RE-CHECK at run end (final-gate.ts): the final integration gate reads the ledger,
  * re-checks each debt against the CURRENT tree, and SURFACES the ones still open in
@@ -49,11 +55,11 @@ const FIELD_SEP = '\t';
 /**
  * Origin → the one-line provenance label the surfaced report prints for it
  * (describeDebt). This table IS the origin registry: `Record<DebtOrigin, string>`
- * makes a new union member a compile error until it has a label, and both the
- * describe side and the parse side read it, so adding an origin is one union member
- * plus one line here — not the six edit sites the per-origin recorder functions used
- * to cost. The label text is user-facing (it lands in the final gate's report and in
- * the FAIL picker), so these strings are byte-frozen.
+ * makes a new union member a compile error until it has a label, and BOTH the
+ * describe side and the parse side read it — `isKnownOrigin` tests membership of
+ * this very table — so adding an origin is one union member plus one line here.
+ * The label text is user-facing: it lands in the final gate's report and in the
+ * FAIL picker, so these strings are byte-frozen.
  */
 const DEBT_LABELS = {
     accepted: 'accepted despite verify-FAIL',
@@ -100,7 +106,7 @@ export function parseAcceptDebts(raw) {
             continue;
         }
         const origin = parts[2]?.trim();
-        // 4th field: the verbatim VERIFY command the reason names (nexttask 5).
+        // 4th field: the verbatim VERIFY command the reason names.
         // Absent in every legacy record, and absent in most new ones.
         const verifyCommand = parts[3]?.trim();
         out.push({
@@ -165,7 +171,7 @@ async function appendDebt(cwd, entry) {
         return;
     try {
         // Classify AT RECORD TIME, against the spec as it stands when the defect is
-        // recorded (nexttask 5). Doing it later would read a spec a subsequent task
+        // recorded. Doing it later would read a spec a subsequent task
         // may have rewritten — the provenance claim has to be made where it is true.
         const verifyCommand = entry.verifyCommand ?? (await classifyVerifyCommand(cwd, entry.taskId, entry.reason));
         if (verifyCommand !== null && verifyCommand !== undefined)
@@ -188,19 +194,18 @@ async function appendDebt(cwd, entry) {
  * Best-effort by construction (appendDebt swallows its own faults): the ledger is an
  * auditing aid and must never break the gate sequence that calls it.
  *
- * `origin` is REQUIRED and deliberately has no default. It used to default to
- * 'accepted' (the legacy 2-field on-disk shape), and that default silently absorbed
- * a dropped argument: the eight-recorder collapse migrated one call in
- * scripts/ignored-writes-ab.ts without its origin, so a run-level 'final-gate'
- * demotion was stamped as a human 'accepted'. The wrappers each carried their class
- * in the NAME, so no migration of them could lose it; a defaulted parameter can.
- * Making it explicit turns that whole class of slip into a compile error.
+ * `origin` is REQUIRED and deliberately has no default. A default of 'accepted'
+ * would be the tempting one, since that is the legacy 2-field on-disk shape — and
+ * that is exactly what makes it dangerous. A dropped argument would then be
+ * absorbed in silence, stamping a run-level 'final-gate' demotion as a human
+ * 'accepted': the one confusion this type exists to prevent. Requiring it turns
+ * that slip into a compile error instead.
  */
 export async function recordDebt(cwd, taskId, reason, origin) {
     await appendDebt(cwd, { taskId: taskId.trim(), reason: normaliseReason(reason), origin });
 }
 /**
- * The reason text a CROSS-TASK DELETION debt stores (mx5 run 12 PROMPT 2): the task's
+ * The reason text a CROSS-TASK DELETION debt stores: the task's
  * work deleted a file a DIFFERENT task's commit introduced, verify FAILed, and the
  * user ACCEPTed — so the deletion survives into the next commit. The shape is fixed
  * and machine-parseable so the final gate's re-check can extract the path and prove
@@ -237,16 +242,14 @@ export function isStaticClassDebt(reason) {
     return isStaticClass(failClassOfReason(reason));
 }
 /**
- * The VERIFY-COMMAND class (nexttask 5): the ONE command a recorded reason itself
+ * The VERIFY-COMMAND class: the ONE command a recorded reason itself
  * NAMES, quoted verbatim in backticks, and present byte-identically in the owning
  * task's VERIFY block.
  *
- * mx5 run 19 recorded `work did not verify: The VERIFY block command \`AGENT=1 bun
- * test test/listings.test.ts\` fails unaided …`; eleven minutes later the final-gate
- * autofix fixed exactly that, the gate's own re-run printed `121 pass 0 fail`, and
- * the run still ended reporting the debt STILL OPEN — because no reachable code path
- * could ever have closed it (see recheckAcceptDebts: two classes, neither reachable
- * for a `work did not verify:` reason).
+ * Without it, a debt whose reason reads `work did not verify: The VERIFY block
+ * command \`…\` fails unaided` can be FIXED by a later autofix and still be
+ * reported STILL OPEN at run end, because no reachable code path could close it:
+ * see recheckAcceptDebts, whose other two classes never match such a reason.
  *
  * Deliberately NOT fuzzy: a backticked span is accepted only when it equals a parsed
  * VERIFY line exactly (after trimming). No paraphrase, no reconstruction, no prefix
@@ -262,16 +265,18 @@ export function isStaticClassDebt(reason) {
  * than a command. Any of those ⇒ not stored ⇒ the debt is simply unclassified, i.e.
  * exactly as un-closable as it is today.
  *
- * …and one more condition (nexttask 19C): a command whose EXIT STATUS IS DESTROYED
- * BY ITS OWN CONSTRUCTION is not storable either. The whole auto-close rests on a
- * ZERO exit meaning "the check passed" (see recheckAcceptDebts below), and 16 of
- * the 612 store-eligible VERIFY lines on this box exit zero whatever the tree
- * contains — 12 of them in IAR1, a CMake/C++ OBS plugin with no database, no
- * frontend and no HTTP server, where one task is seven consecutive
- * `test -f … && echo "PASS" || echo "FAIL"` lines standing in for a build check.
+ * …and one more condition: a command whose EXIT STATUS IS DESTROYED BY ITS OWN
+ * CONSTRUCTION is not storable either. The whole auto-close rests on a ZERO exit
+ * meaning "the check passed" (see recheckAcceptDebts below), and a VERIFY line
+ * shaped like `test -f … && echo "PASS" || echo "FAIL"` exits zero whatever the
+ * tree contains. Run in a real shell with the file absent, it prints FAIL and
+ * exits 0; the bare `test -f` exits 1. So the chain does not merely weaken the
+ * signal, it inverts it — the one output a human would read as failure is the one
+ * a re-check would read as resolved.
+ *
  * Refusing to store one leaves the debt OPEN and surfaced, which is strictly the
- * smaller claim. See unfailable-command.ts for what is and is not decidable, and
- * why bare `|| true` stays out of scope.
+ * smaller claim. See unfailable-command.ts for what is and is not decidable; bare
+ * `|| true` stays out of scope, and is confirmed NOT to match.
  */
 function isStorableCommand(cmd) {
     return (cmd.length > 0
@@ -285,9 +290,9 @@ function isStorableCommand(cmd) {
  * VERIFY fence, or a reason that quotes nothing all yield null, and null simply
  * means the debt keeps today's behaviour (surfaced, never auto-closed).
  *
- * The STRICT parse matters here. mx5 run 19's `TASK_0001.md` opens ```sh and never
- * closes it, so the lenient parser hands back the phase-timings table and every
- * appended gate-trail line as "VERIFY commands" — including sentences that quote
+ * The STRICT parse matters here. A spec that opens ```sh and never closes it
+ * makes the lenient parser hand back the phase-timings table and every appended
+ * gate-trail line as "VERIFY commands" — including sentences that quote
  * `bun run lint`. Matching a reason against that would mint a stored, re-runnable
  * command with fabricated provenance, which is the one thing this class may not do.
  */
@@ -323,10 +328,11 @@ export function verifyCommandFromReason(reason, verifyCommands) {
     return null;
 }
 /**
- * Re-runs allowed per re-check. `inv-bounded`: a run that accepted many command-shaped
- * FAILs must not turn its own report into an unbounded second test suite. Three covers
- * every recorded run in the corpus (max classified per run: 1) with room to spare, and
- * anything past it stays open with the budget stated in the trail — never closed.
+ * Re-runs allowed per re-check. `inv-bounded`: a run that accepted many
+ * command-shaped FAILs must not turn its own report into an unbounded second test
+ * suite. The cap is a ceiling, not a target — a debt past it stays OPEN with the
+ * budget named in the trail, never closed. Confirmed by running the re-check with
+ * more command-class debts than the budget: the extras come back open.
  */
 const MAX_VERIFY_RERUNS = 3;
 /**
@@ -336,7 +342,7 @@ const MAX_VERIFY_RERUNS = 3;
  * task or a human restored it, so the deletion no longer holds); every other debt
  * stays OPEN (unprovable ⇒ surface, never re-hide) — unless it carries a stored
  * `verifyCommand` and `rerunVerify` re-runs that command to a ZERO exit, which is the
- * third class (nexttask 5): the debt named a command, the command was run, and it
+ * third class: the debt named a command, the command was run, and it
  * passed. FP-safe: the only auto-closes are ones a deterministic check can stand
  * behind, and here the check is the task spec's own command.
  */
@@ -401,16 +407,15 @@ export async function recheckAcceptDebts(debts, opts) {
     }
     return { open, resolved, trail };
 }
-// ─── Conflicting-claim classification (mx5 run 11) ──────────────────────────
+// ─── Conflicting-claim classification ──────────────────────────
 //
 // A recorded debt is a CLAIM about the tree, not an instruction to change it. The
 // one class a deterministic check can prove SELF-CONTRADICTORY is an
 // existence-as-failure claim ("<path> exists" fails the verify) whose named path is
 // a DIFFERENT task's committed deliverable: the plan shipped the file on purpose
 // and a sibling's verify indicts it — a plan defect (sibling scope-fence leaked
-// into a verify assertion), not a fixable fault. Run 11's TASK_0009 debt read
-// "src/client/pages/admin.tsx exists (introduced by prior TASK_0008…)" and the
-// final-gate autofix child, seeded with it, ran `rm` on the verified page.
+// into a verify assertion), not a fixable fault. A debt reading "<path> exists"
+// hands a final-gate autofix child a reason to `rm` a verified page.
 /** A path-like token: at least one directory separator, ending in a file name. */
 const PATH_TOKEN_RE = /(?:[\w.@-]+\/)+[\w.@-]+\.\w+/g;
 /**
@@ -418,7 +423,7 @@ const PATH_TOKEN_RE = /(?:[\w.@-]+\/)+[\w.@-]+\.\w+/g;
  * token immediately followed by "exists" / "still exists", or by "must/should not
  * exist". Only this narrow shape qualifies: a reason that merely MENTIONS a path
  * (a prohibition violation, a broken import) is an ordinary defect claim, not an
- * existence assertion, and must never be flagged (run 11's T1/T7 debts name paths
+ * existence assertion, and must never be flagged (such debts name paths
  * this way and are genuine).
  */
 export function extractExistenceClaims(reason) {
@@ -481,7 +486,7 @@ export function describeDebt(d) {
     return isKnownOrigin(d.origin) ? DEBT_LABELS[d.origin] : DEBT_LABELS.accepted;
 }
 /**
- * ACCEPT-debt re-check (mx5 run 4 B3 / run 8 TASK_0012): read the ledger of tasks
+ * ACCEPT-debt re-check: read the ledger of tasks
  * the user accepted despite a verify-FAIL and re-check each against the CURRENT
  * tree. A static-class debt whose statics now pass is provably RESOLVED (a later
  * task fixed it) and pruned from the ledger; every other debt cannot be proven
@@ -490,9 +495,9 @@ export function describeDebt(d) {
  * accept-debt.ts). Best-effort: a ledger read/write failure must never break the
  * caller.
  *
- * FACTORED OUT of runFinalIntegrationGate (nexttask 6): the derivation has to be
+ * FACTORED OUT of runFinalIntegrationGate: the derivation has to be
  * runnable at a SECOND moment — after a converged final-gate autofix, where the
- * orchestrator used to rebuild its gate outcome as a bare `{ok, reason}` and drop
+ * orchestrator rebuilds its gate outcome as a bare `{ok, reason}` and drops
  * `openDebts` entirely. The report a run ends on has to be derived from the tree
  * the run ends with, not from the tree as it was before the fix pass.
  *
@@ -509,14 +514,14 @@ run = spawnCommand, signal) {
         // tree — a deterministic existence check, corroborating the per-file
         // provenance the record already carries.
         fileExists: rel => existsSync(path.join(cwd, rel)),
-        // VERIFY-COMMAND class (nexttask 5): a debt that NAMES a command is settled
+        // VERIFY-COMMAND class: a debt that NAMES a command is settled
         // by running that command, under the gate's own env-gap contract and behind
         // the no-write guard below.
         rerunVerify: cmd => rerunDebtVerifyCommand(cwd, cmd, run, signal)
     });
     if (resolved.length > 0)
         await writeAcceptDebts(cwd, openRaw);
-    // Conflicting-claim annotation (mx5 run 11): an existence-as-failure debt whose
+    // Conflicting-claim annotation: an existence-as-failure debt whose
     // named file is another task's committed deliverable is a plan defect — surface
     // the contradiction with the debt so nobody (human or child) treats the claim as
     // a deletion instruction. Pure git-history lookup; degrades to no annotation.
@@ -529,10 +534,11 @@ const DEBT_RERUN_TIMEOUT_MS = 300_000;
 /**
  * Extra infrastructure-gap shapes recognised ONLY when re-running a debt's command,
  * never in the gate's own verdicts. A driver that reports its connection simply
- * closed (`ERR_POSTGRES_CONNECTION_CLOSED` — what bun's SQL client says when the
- * database is not there at all, as on this box with the mx5 container stopped) is an
- * absent dependency, and calling that "the defect is still present" would be a
- * finding the environment invented. Kept out of INFRA_GAP_OUTPUT_RE on purpose: in a
+ * closed is an absent dependency, not a defect, and calling it "the defect is
+ * still present" would be a finding the environment invented. The postgres code is
+ * verbatim from the runtime: pointed at a port with nothing behind it, bun's SQL
+ * client throws a `PostgresError` whose `code` is exactly
+ * `ERR_POSTGRES_CONNECTION_CLOSED`. Kept out of INFRA_GAP_OUTPUT_RE on purpose: in a
  * gate verdict the same wording can be a real fault the suite must own, and only the
  * debt re-check needs the conservative reading — where it costs nothing, because gap
  * and fail both leave the debt open.
@@ -547,9 +553,11 @@ const DEBT_INFRA_GAP_RE = /ERR_POSTGRES_CONNECTION_CLOSED|ERR_MYSQL_CONNECTION|E
  * a passing tree and have that count as the debt being fixed — the run would then be
  * certifying its own side effect. So tracked state is captured before and after, and
  * a pass that came with a tracked change is downgraded to INCONCLUSIVE with the
- * change named. Untracked output is left alone: it is what a build legitimately
- * produces, and `git status --porcelain` in a repo with the usual ignores does not
- * see it.
+ * change named. Untracked output is left alone because the guard asks git not to
+ * report it: `--untracked-files=no` is doing that work, NOT the project's ignore
+ * rules. Checked both ways — with and without a matching `.gitignore`, the flag
+ * returns an empty status for a fresh untracked build directory, while plain
+ * `--porcelain` reports it when it is not ignored.
  *
  * A repository the guard cannot read (no git, git absent) is not a licence to skip
  * the guard: the re-run is INCONCLUSIVE there, because "nothing changed" would be an

package/dist/task/api-synthesis.d.ts

@@ -1,30 +1,33 @@
 /**
- * Anti-synthesis guard for grill/clarify auto-answers (mx5 run-13 Bug A).
+ * Anti-synthesis guard for grill/clarify auto-answers.
  *
- * The grill auto-answer channel invented `Bun.mkdirSync` (does not exist) while
- * the task's own research APIS section carried the correct list (Bun.build,
- * Bun.spawn). Nothing cross-checked the answer against it, so the invention was
- * promoted into the task's title, requirements, acceptance criteria AND VERIFY
- * block, and the implementer shipped a fake ambient declare to compile it.
+ * The failure: an auto-answer names an API that does not exist, and nothing
+ * cross-checks it against the research the task already gathered. A
+ * plausible-looking invention is then promoted into the title, the requirements,
+ * the acceptance criteria and the VERIFY block, and the implementation fakes a
+ * declaration to make it compile. `Bun.mkdirSync` is the shape of it, and it is
+ * real: against the runtime, `typeof Bun.mkdirSync` is `undefined`, while
+ * `Bun.build` and `Bun.spawn` are both functions.
  *
- * Lever: the same verbatim-substring anti-synthesis check as the F3 contract
- * registry. Extract API-shaped identifiers (`Namespace.member`) from the answer;
- * an identifier is SYNTHESIZED when
+ * The lever is verbatim-substring membership, never a model judgement — the same
+ * technique the contract registry uses to reject a paraphrased key. Extract
+ * API-shaped identifiers (`Namespace.member`) from the answer; an identifier is
+ * SYNTHESIZED when
  *   (a) the full identifier appears nowhere in the research (APIS/docs/context
- *       sections, verbatim substring, case-sensitive) and nowhere in the
- *       question itself, AND
+ *       sections, case-sensitive substring) and nowhere in the question, AND
  *   (b) the research DOES mention that namespace's API surface (`Bun.` appears
- *       somewhere) — i.e. research claims coverage of the namespace, so a
- *       member absent from it is suspicious rather than merely uncovered.
- * Gate (b) is the step-aside rule: when research never mentions the namespace
- * at all (React.StrictMode in a task whose research covered no React API), the
- * check is INCONCLUSIVE and must not fire — the guard may only cost time,
- * never work. Same for the clarify-triage seam, whose research slot is a stub:
- * no namespace coverage ⇒ no findings ⇒ guard inert by construction.
+ *       somewhere) — research claims coverage of the namespace, so a member
+ *       absent from it is suspicious rather than merely uncovered.
  *
- * Caller contract (phaseAutoAnswer): findings ⇒ re-ask ONCE with the research
- * API lines injected (belt); a re-asked answer that still carries a flagged
- * identifier is surfaced to the user as UNKNOWN instead of being promoted.
+ * Gate (b) is the step-aside rule, and it is what keeps the guard costing time
+ * rather than work. Run both ways: `React.StrictMode` against research that
+ * mentions only `Bun.` produces NO finding, and research that is empty produces
+ * none either — so a caller with nothing gathered leaves the guard inert by
+ * construction instead of trigger-happy.
+ *
+ * Caller contract (phaseAutoAnswer): findings ⇒ re-ask exactly ONCE with the
+ * verified research lines injected; an answer that STILL carries a flagged
+ * identifier is surfaced to the user as `unknown` rather than promoted.
  */
 export interface SynthesizedApiFinding {
     /** The full flagged identifier, e.g. "Bun.mkdirSync". */

package/dist/task/api-synthesis.js

@@ -1,42 +1,48 @@
 /**
- * Anti-synthesis guard for grill/clarify auto-answers (mx5 run-13 Bug A).
+ * Anti-synthesis guard for grill/clarify auto-answers.
  *
- * The grill auto-answer channel invented `Bun.mkdirSync` (does not exist) while
- * the task's own research APIS section carried the correct list (Bun.build,
- * Bun.spawn). Nothing cross-checked the answer against it, so the invention was
- * promoted into the task's title, requirements, acceptance criteria AND VERIFY
- * block, and the implementer shipped a fake ambient declare to compile it.
+ * The failure: an auto-answer names an API that does not exist, and nothing
+ * cross-checks it against the research the task already gathered. A
+ * plausible-looking invention is then promoted into the title, the requirements,
+ * the acceptance criteria and the VERIFY block, and the implementation fakes a
+ * declaration to make it compile. `Bun.mkdirSync` is the shape of it, and it is
+ * real: against the runtime, `typeof Bun.mkdirSync` is `undefined`, while
+ * `Bun.build` and `Bun.spawn` are both functions.
  *
- * Lever: the same verbatim-substring anti-synthesis check as the F3 contract
- * registry. Extract API-shaped identifiers (`Namespace.member`) from the answer;
- * an identifier is SYNTHESIZED when
+ * The lever is verbatim-substring membership, never a model judgement — the same
+ * technique the contract registry uses to reject a paraphrased key. Extract
+ * API-shaped identifiers (`Namespace.member`) from the answer; an identifier is
+ * SYNTHESIZED when
  *   (a) the full identifier appears nowhere in the research (APIS/docs/context
- *       sections, verbatim substring, case-sensitive) and nowhere in the
- *       question itself, AND
+ *       sections, case-sensitive substring) and nowhere in the question, AND
  *   (b) the research DOES mention that namespace's API surface (`Bun.` appears
- *       somewhere) — i.e. research claims coverage of the namespace, so a
- *       member absent from it is suspicious rather than merely uncovered.
- * Gate (b) is the step-aside rule: when research never mentions the namespace
- * at all (React.StrictMode in a task whose research covered no React API), the
- * check is INCONCLUSIVE and must not fire — the guard may only cost time,
- * never work. Same for the clarify-triage seam, whose research slot is a stub:
- * no namespace coverage ⇒ no findings ⇒ guard inert by construction.
+ *       somewhere) — research claims coverage of the namespace, so a member
+ *       absent from it is suspicious rather than merely uncovered.
  *
- * Caller contract (phaseAutoAnswer): findings ⇒ re-ask ONCE with the research
- * API lines injected (belt); a re-asked answer that still carries a flagged
- * identifier is surfaced to the user as UNKNOWN instead of being promoted.
+ * Gate (b) is the step-aside rule, and it is what keeps the guard costing time
+ * rather than work. Run both ways: `React.StrictMode` against research that
+ * mentions only `Bun.` produces NO finding, and research that is empty produces
+ * none either — so a caller with nothing gathered leaves the guard inert by
+ * construction instead of trigger-happy.
+ *
+ * Caller contract (phaseAutoAnswer): findings ⇒ re-ask exactly ONCE with the
+ * verified research lines injected; an answer that STILL carries a flagged
+ * identifier is surfaced to the user as `unknown` rather than promoted.
  */
 /**
  * `Namespace.member` where the namespace starts uppercase (Bun, React, Deno —
- * the global/imported-namespace API shape; run-13's TP is exactly this) and
- * both sides are ≥2 chars (kills "U.S.", "e.G" prose shapes). Member may start
- * either case: `Bun.mkdirSync` and `React.StrictMode` are both API-shaped.
+ * the global or imported-namespace API shape) and BOTH sides are at least two
+ * characters. Run against the prose shapes it has to survive: `U.S. policy`,
+ * `e.G thing`, `A.b` and `fs.readFile` all extract nothing, while
+ * `Bun.mkdirSync` and `React.StrictMode` both match — the member may start
+ * either case.
  */
 const API_IDENT_RE = /\b([A-Z][A-Za-z0-9_$]+)\.([A-Za-z_$][A-Za-z0-9_$]+)\b/g;
 /**
  * Member names that make the match a file name, domain, or version-ish token
- * rather than an API (Node.js, App.tsx, README.md, Fly.io, Express.com). All
- * lowercase-compared, so `INDEX.HTML` is excluded too.
+ * rather than an API (Node.js, App.tsx, README.md, Fly.io, Express.com). The
+ * comparison is lowercased, so shouting does not slip through: `INDEX.HTML`
+ * extracts nothing, same as `App.tsx`.
  */
 const NON_API_MEMBERS = new Set([
     'js',

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

@@ -1,67 +1,35 @@
 /**
- * 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 declare 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 \u2014 not this project's own source, not a runtime builtin \u2014 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:\n  <name>  <one-line signature or use>  \u2014 SEMANTICS: <what it means in use>\n\nA TYPE SIGNATURE IS NOT A SEMANTICS CLAUSE, and restating one in prose does not make it one. `hc(baseUrl: Prefix, options?: ClientRequestOptions)` names the argument and says nothing about whether that argument is an origin, or a mount prefix, or how it is joined to each route path \u2014 which is the fact the implementing agent actually needs, and the one it will otherwise guess wrong. An entry whose SEMANTICS field is missing is UNFINISHED, and your section is not ready to emit while any package entry is unfinished.\n\nHOW TO FILL THAT FIELD \u2014 in this order. Do not skip a step, and do not stop after step 1 because you already hold the declaration:\n  1. ASK `pi-worker-docs` A BEHAVIOUR QUESTION about that package. NOT \"what is X's signature\", NOT \"what types does X export\" \u2014 those return the declaration you already have. Ask what an argument MEANS, what it DEFAULTS to, what it is RELATIVE to, what HAPPENS when it is given a particular value. For example: `pi-worker-docs(\"hono/client\", \"what does the baseUrl argument to hc MEAN \u2014 an origin or a mount prefix \u2014 and how is it joined to each route path?\")`.\n  2. IF THE PACKAGE TEXT DOES NOT ANSWER IT, ESCALATE. Expect this: bundled `.d.ts` declarations frequently carry no semantics at all, because the semantics live in the package's documentation. Call `pi-worker-search` with the question, or `pi-worker-fetch` on a documentation URL \u2014 including any `@see {@link https://\u2026}` link that appeared in the text `pi-worker-docs` just returned to you.\n  3. ONLY IF BOTH FAIL, WRITE THE OPEN QUESTION DOWN, in this exact form:\n       <name>  <signature>  \u2014 SEMANTICS: UNVERIFIED: <the exact question you could not answer>\n     THIS IS A CORRECT AND REQUIRED OUTCOME, not a failure. A named open question is worth far more to the implementing agent than a confident guess, and it is the only acceptable way to finish an entry you could not verify. NEVER fill this field from memory, from what the symbol is named, or from what the API \"obviously\" does: a plausible wrong semantics clause is the single most damaging thing this section can carry.";