@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/final-gate.d.ts

@@ -11,40 +11,34 @@ export interface FinalGateOutcome {
     /**
      * On a fail: the exact command(s), exit code(s), and output tail(s) — the
      * MECHANICAL failures only. The accept-debt note is deliberately NOT folded in
-     * here (mx5 run 11): this string seeds the final-gate AUTOFIX child's prompt,
-     * and a debt included there is read as an instruction — the run-11 fix child
-     * `rm`'d a sibling task's verified deliverable to satisfy a recorded claim. The
-     * child cannot act on text it never receives; debts travel in `debtNote`.
-     * With multiple failures this is the numbered, ranked list (see `failures`).
+     * here, because this string is what `buildFinalFixPrompt` puts in front of the
+     * autofix child, and a recorded debt claim reaching a write-enabled child reads
+     * as an instruction to act on it. The child cannot act on text it never
+     * receives; debts travel in `debtNote`. With multiple failures this is the
+     * numbered, ranked list (see `failures`).
      */
     reason: string;
     /**
      * On a fail: EVERY section failure individually, ranked most load-bearing
      * first — boot/render ("the app does not serve/render") outranks any single
-     * test failure. The gate runs every section and aggregates rather than
-     * early-returning (mx5 run 13: a bun-test glob failure shadowed the boot +
-     * render probe, so the user accepted the FAIL having only ever seen 1 failing
-     * CT test while the shipped app 404'd on every non-API GET). Callers trail
-     * each entry and show the full list wherever an ACCEPT decision is made.
+     * test failure. The gate aggregates rather than early-returning: the boot and
+     * render probes run LAST, so a first-failure return would let any earlier test
+     * failure shadow the one signal that answers "does the app serve anything at
+     * all". Callers trail each entry and show the full list wherever an ACCEPT
+     * decision is made.
      */
     failures?: string[];
     /**
      * The SUBSET of `failures` that a PROBE returned after actually observing —
      * entries whose evidence is "we looked, and what we saw was bad", as opposed to
-     * "we could not look" (nexttask 19A).
+     * "we could not look".
      *
-     * The probes have always known this about themselves: `RenderOutcome` is
-     * `pass | fail | skip`, `f648f5b` (2026-07-14) turned a render `skip` into
-     * "render check UNOBSERVED: <reason>", and `b0f90a7` (2026-07-19) made an
-     * unenumerable boot return PASS-stamped-UNOBSERVED rather than FAIL. What was
-     * missing is that the outcome CLASS never travelled with the failure TEXT, so
-     * the non-progress classifier downstream had to guess — and guessed by string
-     * equality, which a deterministic un-fixed defect satisfies by definition.
-     *
-     * mx5 run 21: the render probe FAILED on a blank page, the same failure came
-     * back from two tree-changing fix attempts (because the defect was real and
-     * unfixed), the classifier read that as evidence against the INSTRUMENT, and
-     * the run shipped a product whose every page was blank as `completed`.
+     * The probes distinguish "we looked and it was bad" from "we could not look"
+     * in their own outcomes; this field carries that class alongside the failure
+     * TEXT. Without it the non-progress classifier downstream has only string
+     * equality to go on, and a deterministic un-fixed defect satisfies string
+     * equality by definition — so a real, still-broken check reads as an
+     * unfalsifiable one and gets demoted to debt.
      *
      * Membership is by exact text identity with an entry of `failures` — never a
      * pattern, never a re-derivation. Absent/empty on a pass.
@@ -57,10 +51,10 @@ export interface FinalGateOutcome {
      */
     debtNote?: string;
     /**
-     * ACCEPT-despite-verify-FAIL debts still open at run end (mx5 run 4 B3 / run 8
-     * TASK_0012): tasks the user blessed as-is despite a verify-FAIL that a
-     * deterministic re-check could not prove resolved. The caller surfaces them so a
-     * run never completes silently carrying an accepted defect. Empty/absent = none.
+     * ACCEPT-despite-verify-FAIL debts still open at run end: tasks the user
+     * blessed as-is despite a verify-FAIL that a deterministic re-check could not
+     * prove resolved. The caller surfaces them so a run never completes silently
+     * carrying an accepted defect. Empty/absent = none.
      */
     openDebts?: AcceptDebt[];
     /**
@@ -68,8 +62,8 @@ export interface FinalGateOutcome {
      * supposed to. Two independent triggers, either or both:
      *   - nothing dynamic ran at all — no command was discoverable, or every discovered
      *     one skipped as an environment gap (unobservedVerdict);
-     *   - a served app's boot command was discovered and SKIPPED, whatever else ran
-     *     (bootSkipVerdict, mx5 run 18 — test suites may not stand in for a launch).
+     *   - a served app's boot command was discovered and SKIPPED, whatever else ran.
+     *
      * `ok` is still true (the statics did pass and there is nothing to fix), but this is
      * NOT a PASS: the caller must record it as UNOBSERVED, never as "checked and fine".
      * Absent ⇒ everything the gate meant to observe, it observed.
@@ -82,24 +76,19 @@ export interface FinalGateOutcome {
  * manifest that exists wins, mirroring discoverHealthCommands. Empty means
  * "nothing to run" — the static half may still gate.
  *
- * THE MANIFEST ALLOWLIST BELOW IS NARROW, AND THAT IS A KNOWN, MEASURED GAP: a
- * C++/CMake project (no package.json) and a package.json whose only script is
- * `verify` both discover NOTHING here. That outcome is now reported as UNOBSERVED
- * rather than as a PASS (see unobservedVerdict), which makes the blindness loud and
- * durable — it does not remove it. The gap itself stands.
+ * THE MANIFEST ALLOWLIST BELOW IS NARROW, AND THAT IS A KNOWN GAP: a project with
+ * no package.json, Makefile, Cargo.toml, go.mod or pyproject.toml discovers
+ * NOTHING here, and so does a package.json whose only script is named something
+ * else. That outcome is reported as UNOBSERVED rather than as a PASS (see
+ * unobservedVerdict), which makes the blindness loud — it does not remove it.
  *
- * The obvious fix — harvest each task's own `## verified tooling` section, which
- * DOES record the missing commands — was measured on 2026-07-27 and REFUTED. That
- * section is model-authored and, despite its name, unverified: on godot-engine it
- * yields 3 commands that exit 0 and 8 that exit non-zero, six of those for purely
- * fabricated reasons (recorded without a required argument, pointing at files that
- * do not exist, naming a test runner the project does not use) — so harvesting it
- * turns that project's PASS into a FAIL citing "No scene path provided", plus ~15
- * minutes of hang. Full numbers, the reproduction rig, and why no pre-execution
- * filter can separate a fabricated command from a real one:
- * scripts/harvest-verified-tooling-step0.ts. DO NOT re-propose the harvest without
- * first fixing the PROVENANCE of `## verified tooling` (record cwd + exit code at
- * authoring time); widening this allowlist tool-by-tool is not the fix either.
+ * DO NOT close the gap by harvesting each task's own `## verified tooling`
+ * section. That section is the parsed output of a model child (phases.ts writes
+ * it from the verify-tooling worker), and despite its name nothing records the
+ * cwd the command was tried in or the code it exited with — so a fabricated
+ * command is indistinguishable from a real one before it runs, and running it is
+ * how the gate would find out. Fix that provenance first. Widening this allowlist
+ * tool-by-tool is not the fix either.
  */
 export declare function discoverIntegrationCommands(cwd: string): {
     ecosystem: string | null;
@@ -119,11 +108,11 @@ export declare function discoverGateCommandLabels(cwd: string): string[];
  * The RESOLVED BODY of every discoverable gate command, keyed by the same label
  * `discoverGateCommandLabels` produces.
  *
- * The label is what the gate CALLS; the body is what actually runs. mx5 run 19's
- * autofix changed `scripts.test` from `AGENT=1 bun test` to `AGENT=1 bun test
- * ./test` — the label `bun run test` was identical before and after, so the
- * label guard saw nothing while the suite stopped covering the repository. The
- * shrink guard compares these bodies (see command-shrink.ts).
+ * The label is what the gate CALLS; the body is what actually runs. A fix pass
+ * can rewrite `scripts.test` to run one subdirectory and leave the label
+ * `bun run test` identical, so the label guard sees nothing while the suite stops
+ * covering the repository. The shrink guard compares these bodies (see
+ * command-shrink.ts).
  *
  * A command with no indirection (`cargo test --quiet`, `pytest -q`) resolves to
  * itself: it cannot be narrowed without changing the label, which the label
@@ -145,10 +134,9 @@ export { deriveOpenDebts, rerunDebtVerifyCommand };
  *     with no runnable command at all still FAILS the scan instead of returning
  *     UNOBSERVED. A static check needs no runner; that is the whole point of
  *     deciding it in exactly the environment where every dynamic probe went blind.
- *   - `post-boot` runs after the dynamic sections, which is where these scans'
- *     failures have always landed relative to command/launch/boot failures.
- *     Execution order is the aggregate's tiebreak within a rank, so moving a row
- *     between stages MOVES it in the user-visible failure list.
+ *   - `post-boot` runs after the dynamic sections. Execution order is the
+ *     aggregate's tiebreak within a rank, so moving a row between stages MOVES it
+ *     in the user-visible failure list.
  */
 type ClosureScanStage = 'pre-discovery' | 'post-boot';
 /** Everything a closure scan may look at. Static and synchronous by construction:
@@ -181,13 +169,12 @@ interface ClosureScan {
      * finding.
      *
      * A GENERATOR rather than a function returning an array, for two reasons.
-     * First, the driver's try/catch wraps the ITERATION, so a scan that produces
-     * two findings and then faults still emits those two — precisely what the
-     * three hand-written `for (… ) fail(…)` loops inside try blocks did. Second,
-     * the three scans do not share a result shape (one nullable finding; a list;
-     * a list plus the template set its formatter also needs), and folding scan
-     * and format together lets each row keep its own arity instead of forcing a
-     * lowest-common-denominator result type on all of them.
+     * First, the driver's try/catch wraps the ITERATION, so a scan that yields two
+     * findings and then throws still emits those two. Second, the three scans do
+     * not share a result shape — one nullable finding, a list, and a list plus the
+     * template set its formatter also needs — and folding scan and format together
+     * lets each row keep its own arity instead of forcing a
+     * lowest-common-denominator result type on all three.
      */
     run: (input: ClosureScanInput) => Iterable<string>;
 }
@@ -195,12 +182,12 @@ interface ClosureScan {
  * The run-level closure scans, in emission order within their stage.
  *
  * ONLY checks of this shape belong here. Four other checks in this gate are
- * deliberately NOT rows: repo-health returns {ok, reason} and formats inline;
- * the launch-contract diff branches on manifest kind and can emit a NOTE instead
- * of a failure; the launch config-gap produces neither a failure nor a note but
- * UN-COUNTS a dynamic observation; and the boot check is an async, stateful,
- * port-binding exercise. Squeezing any of those in would mean a row type with
- * more escape hatches than content.
+ * deliberately NOT rows: repo-health returns {ok, reason} and formats inline; the
+ * launch-contract diff branches on manifest kind and can emit a NOTE instead of a
+ * failure; the launch config-gap produces neither a failure nor a note but
+ * UN-COUNTS a dynamic observation (`tally.unobserve()`); and the boot check is
+ * async, stateful and port-binding. Squeezing any of those in would mean a row
+ * type with more escape hatches than content.
  */
 declare const CLOSURE_SCANS: ClosureScan[];
 /**
@@ -217,36 +204,16 @@ declare const CLOSURE_SCANS: ClosureScan[];
 declare function runClosureScans(stage: ClosureScanStage, input: ClosureScanInput, fail: (text: string, rank: number) => void, scans?: readonly ClosureScan[]): void;
 export { CLOSURE_SCANS, runClosureScans };
 export type { ClosureScan, ClosureScanInput, ClosureScanStage };
-/**
- * Run the final gate: static analysis first, then the lockfile consistency
- * checks, then the discovered integration commands, then one boot exercise of
- * the start command — whole-repo, verbatim, unaided. Deterministic (no model).
- *
- * EVERY section runs and failures AGGREGATE (mx5 run 13): the gate used to
- * early-return on the first failing section, and the boot + render probe — built
- * after run 11 exactly for "app serves blank/nothing" — was ordered last, so any
- * earlier failure shadowed the most load-bearing signal. Run 13's user accepted
- * the FAIL having seen only 1 failing CT test while the app 404'd on every
- * non-API GET; boot/render never executed in any attempt. Now the outcome
- * carries the full ranked failure list (boot/render first — "the app does not
- * serve/render" outranks any single test), the ACCEPT decision is made on all of
- * it, and autofix converges only when the whole list is empty. Per-section
- * env-gap/INFRA_GAP skip semantics and orphan-port recovery are unchanged.
- */
 /**
  * Everything the run-end gate needs beyond the tree it is judging.
  *
- * An options object rather than a positional tail: the production call site read
- * `runFinalIntegrationGate(cwd, undefined, undefined, undefined, planText)`, and
- * `bootGraceMs`/`timeoutMs` are adjacent numbers that swap without a type error.
+ * An options object rather than a positional tail, because `bootGraceMs` and
+ * `timeoutMs` are adjacent numbers that would swap without a type error.
  *
- * `run`, `envClosure` and `trackedFiles` are SEAMS, by the same test GateDeps
- * states: a scenario needs to substitute them. `runGateCommand`,
- * `runVerifyCommandLine` and `rerunDebtVerifyCommand` each already take a
- * `CommandRunner`; this is the fourth and last driver in the file, and without it
- * the config-gap branch below is unreachable in test — not by oversight, but
- * because reaching it needs a git-tracked env template, so every launch-contract
- * test (bare `makeDir`, no `git init`) misses it by construction.
+ * `run`, `envClosure` and `trackedFiles` are test SEAMS. Without `run`, the
+ * config-gap branch below is unreachable from a test: reaching it needs a
+ * git-tracked env template, and the launch-contract tests build a bare directory
+ * with no `git init`, so they miss it by construction.
  */
 export interface FinalGateOptions {
     timeoutMs?: number;
@@ -262,9 +229,9 @@ export interface FinalGateOptions {
     trackedFiles?: (cwd: string) => string[] | null;
     /**
      * The run's cancel. Reaches every command the gate spawns — repo-health, the
-     * lockfile/integration/launch sections and the ACCEPT-debt re-runs. Nothing
-     * could be cancelled while `CommandRunner` was synchronous: the event loop
-     * never got a turn in which to notice.
+     * lockfile, integration and launch sections, and the ACCEPT-debt re-runs. It
+     * only works because `CommandRunner` is async: a synchronous spawn never gives
+     * the event loop a turn in which to notice an abort.
      */
     signal?: AbortSignal;
 }