@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/requirements.js

@@ -1,15 +1,12 @@
 /**
- * requirements — requirement-level coverage accounting for /task-auto planning
- * (mx5 run 11, goal A).
+ * requirements — requirement-level coverage accounting for /task-auto planning.
  *
- * The failure this closes: the design's §10 Testing section REQUIRES test-first
- * cadence, Playwright CT with screenshot baselines, a `test:ct` script, a
- * separate test DB, and a `test/` dir — and got ZERO tasks and ZERO per-task
- * injection. The coverage gate asked one holistic question ("do these tasks
- * cover the whole feature?"), and a task list that mirrors the spec's own
- * milestone list is structurally parity-complete, so the judge said COMPLETE in
- * round 1. Milestone-parity coverage is structurally blind to sections that
- * aren't milestones.
+ * The failure this closes: a single holistic coverage question ("do these tasks
+ * cover the whole feature?") is answerable YES by any task list that mirrors the
+ * spec's own milestone headings. Such a list is structurally parity-complete, so
+ * the sections that are NOT milestones — a Testing section demanding a test
+ * script, a test database, a test directory — can produce zero tasks and zero
+ * per-task injection while the judge still says COMPLETE.
  *
  * Mechanism (spec-shape-agnostic, contracts.ts pattern):
  *   1. EXTRACT requirement units as VERBATIM quotes from whatever structure the
@@ -25,10 +22,10 @@
  *      pattern: content travels, not a pointer); requirements still unmapped
  *      after the retry rounds are recorded user-visibly, never silently dropped.
  *
- * Goal C rides the same channel: when the spec mandates a verification
- * methodology ("a test lands in the same change as each new route"), that quote
- * is exactly what gets injected, and compose's VERIFY rules fold it into every
- * applicable task's runnable verification.
+ * A mandated verification methodology rides the same channel: when the spec says
+ * "a test lands in the same change as each new route", that quote is exactly what
+ * gets injected, and compose's VERIFY rules fold it into every applicable task's
+ * runnable verification.
  */
 import { normalise } from './contracts.js';
 import { makeLedger } from './ledger.js';
@@ -92,16 +89,12 @@ export function keepGroundedRequirements(entries, sourceDoc) {
     return kept;
 }
 /**
- * Bound the list WITHOUT doc-order truncation. Two measured failure shapes drive
- * the rule:
- *  - an eager model extracts 40+ items top-down (every §1 decision row), so a
- *    plain first-N cap systematically drops the TAIL sections — exactly where
- *    mx5 keeps its testing obligations;
- *  - "given order" as the tie-break re-creates the same tail bias one level up
- *    (mx5 run 16, measured live: the model emitted 185 requirements, 178
- *    grounded — INCLUDING §9's "serves `/api` + static `dist/`", the clause
- *    whose loss shipped a permanently blank app — and the cap's doc-order fill
- *    cut all 138 past the cap, every one from the design's tail).
+ * Bound the list WITHOUT doc-order truncation. An extractor that works top-down
+ * yields more entries than the cap from the doc's early sections alone, so a
+ * plain first-N cap drops the TAIL sections wholesale — and a spec keeps its
+ * testing and deployment obligations at the end. "Given order" as the tie-break
+ * re-creates the same bias one level up.
+ *
  * Rule (deterministic priority, not a knob): entries quoting an obligation-
  * marked passage survive first; the remaining budget is filled ROUND-ROBIN
  * across the source doc's sections (each section's entries in doc order), so
@@ -111,9 +104,9 @@ export function keepGroundedRequirements(entries, sourceDoc) {
  * cannot be located) the fill degrades to the old given-order behavior.
  */
 export function capRequirements(entries, passages, sourceDoc, 
-/** A/B seam: `false` reproduces the pre-budget rule, so an offline harness can
- *  score the shipped rule against the one it replaced without transcribing
- *  sectionFairFill and letting the copy drift. Production never passes it. */
+/** `false` skips the low-value deprioritisation, so a caller can compare the
+ *  two fills without transcribing sectionFairFill. Production never passes it
+ *  — auto-orchestrator.ts calls this with three arguments. */
 deprioritiseLowValue = true) {
     if (entries.length <= MAX_REQUIREMENTS)
         return entries;
@@ -131,22 +124,20 @@ deprioritiseLowValue = true) {
     // "MUST log every request" is 22 characters and every length-based rule reads
     // it as a fragment. Filtering ahead of the marked/rest split deleted it.
     //
-    // INSURANCE, not a measured win on mx5: across both 30-run pools exactly one
-    // distinct quote per pool is low-value AND marked, and it is a genuinely
-    // truncated one. The layering matters for specs whose obligations are SHORT,
-    // which mx5's are not. Do not cite it as the reason tail coverage holds —
-    // tail coverage is identical with the filter applied before the split.
+    // The ordering only matters for specs whose obligations are SHORT; it is not
+    // what makes tail coverage hold. That is sectionFairFill below.
     const pool = deprioritiseLowValue ? budgetedByObligation(rest, budget, sourceDoc) : rest;
     return [...marked.slice(0, MAX_REQUIREMENTS), ...sectionFairFill(pool, budget, sourceDoc)];
 }
 /** Longest a dependency-pin row can be before it is presumed to carry an
- *  obligation after the pin. Real pins in the measured corpus run 32..48 chars;
- *  the pin-prefixed lines that DO obligate ("TypeScript `6.0.3` — one strict
- *  `tsconfig.json`: `strict`, `noUncheckedIndexedAccess`, …") run 130..260. */
+ *  obligation after the pin. A bare pin is short; a pin-prefixed line that DOES
+ *  obligate ("TypeScript `6.0.3` — one strict `tsconfig.json`: `strict`,
+ *  `noUncheckedIndexedAccess`, …") is several times longer. */
 const MAX_PIN_LENGTH = 80;
 /** Cut mid-expression: an unbalanced fence or bracket, or a trailing separator.
  *  NOT `;` — a complete clause legitimately ends with one, and dropping on `;`
- *  discarded a runnable `lint` = `prettier … && eslint … && tsc --noEmit` line. */
+ *  would discard a runnable line like `lint` = `prettier … && eslint … && tsc
+ *  --noEmit`. */
 function isTruncatedQuote(q) {
     if ((q.match(/`/g) ?? []).length % 2 === 1)
         return true;
@@ -194,27 +185,20 @@ export function isLowValueQuote(quote) {
 /**
  * Deprioritise obligation-free quotes, but only as far as the BUDGET requires.
  *
- * Measured (mx5, 20402-char spec, two independent 30-run extraction pools): the
- * extractor's single-pass yield swings 20..160 for byte-identical input, and the
- * padding crowds real obligations out of the 40 that ship — high-yield runs land
- * FEWER critical obligations than low-yield ones. Critical obligations reaching
- * the shipped list go 8.50 → 9.37 of 16 on the design pool (10 runs better, 0
- * worse, p=0.0020) and 7.70 → 8.43 on the confirmation pool (12 / 0, p=0.0005).
+ * The extractor's single-pass yield swings wildly for byte-identical input, and
+ * the padding crowds real obligations out of the fixed number that ship — a
+ * high-yield run lands FEWER critical obligations than a low-yield one.
+ * Deprioritising the obligation-free quotes reverses that.
  *
  * BUDGETED, not absolute. Below the cap no slot is contested, so dropping there
- * destroys information and buys nothing; a run that filtered 55 quotes down to 20
- * lost its only carrier of the Argon2id obligation — a DDL row that was correctly
- * classified as one — while 20 slots sat empty. So the low-value entries come back
- * in source-doc order until the list reaches the cap.
- *
- * Absolute filtering scored marginally higher on raw count (24 gains vs 22 across
- * both pools) and was rejected anyway: its extra gains are one more obligation in
- * an already-populated list, while its one loss is an obligation vanishing from a
- * run outright. Those are not the same size of mistake.
+ * destroys information and buys nothing — a filter that runs unconditionally can
+ * leave slots empty while discarding the only carrier of a real obligation the
+ * lexical rules misread. So the low-value entries come back in source-doc order
+ * until the list reaches the cap.
  *
  * Doc order for the restore is the neutral choice: which entries return only
  * matters when more were dropped than there are free slots, and ordering by
- * anything fitted to an observed loss would be tuning the rule to one pool.
+ * anything else would fit the rule to one spec.
  */
 function budgetedByObligation(entries, budget, sourceDoc) {
     const keep = entries.filter(e => !isLowValueQuote(e.quote));
@@ -256,7 +240,7 @@ function normalisedSections(doc) {
  *  whose normalised text contains its quote (the same containment rule that
  *  grounded it), take each bucket's entries in in-section order, one per bucket
  *  per round. Entries that cannot be located (or no doc) go to a trailing
- *  bucket in given order — the pre-run-16 behavior, never worse. */
+ *  bucket in given order — the pre-behavior, never worse. */
 function sectionFairFill(entries, budget, sourceDoc) {
     if (budget <= 0)
         return [];
@@ -302,11 +286,11 @@ function sectionFairFill(entries, budget, sourceDoc) {
 /**
  * DETERMINISTIC RECALL FLOOR (same medicine as the launch-contract checklist):
  * paragraphs carrying an obligation marker (word-bounded "required"/"must").
- * Extraction recall over a 20KB doc is the weak model's, and it is variance-
- * prone — measured live, 1 of 5 runs kept 16 quotes with ZERO §10 items. The
- * host enumerates the marked passages; the prompt lists their head lines as a
- * checklist, and uncoveredPassages() below turns "a marked passage produced no
- * quote" into hard evidence for one forced re-extraction.
+ * Extraction recall over a long doc is the model's, and it varies run to run, so
+ * an entire section can come back with no quotes at all. The host enumerates the
+ * marked passages; the prompt lists their head lines as a checklist, and
+ * uncoveredPassages() below turns "a marked passage produced no quote" into hard
+ * evidence for one forced re-extraction.
  */
 export function enumerateObligationPassages(doc) {
     const out = [];
@@ -392,11 +376,10 @@ export const REQUIREMENT_EXTRACT_PROMPT = (feature, passages = []) => [
  * NOT exist or happen — there is no task that "delivers" an absence) or a GLOBAL
  * POLICY (a product-wide rule every slice obeys, not one slice's deliverable). The
  * per-task coverage map maps both to NONE forever, so left in the `unmapped` set
- * they kept the decompose loop's verdict INCOMPLETE and forced it to regenerate
- * the whole plan endlessly (mx5 run 12: 3 un-ownable NEGATIVE requirements drove a
- * complete full-stack plan to be overwritten by a backend-only one). These belong
- * in the CROSS-CUTTING carry — injected verbatim into every task — never fed back
- * as a missing area.
+ * they hold the decompose loop's verdict at INCOMPLETE and make it regenerate the
+ * whole plan every round — which can replace a good plan with a worse one. These
+ * belong in the CROSS-CUTTING carry, injected verbatim into every task, never fed
+ * back as a missing area.
  *
  * Deterministic and precision-biased: it only reclassifies clear prohibitions and
  * clearly product-global policies. It does NOT need to catch every un-ownable line
@@ -485,7 +468,7 @@ export function accountCoverage(requirements, mappings) {
             acc.crossCutting.push(requirements[i]);
         // NONE — but a prohibition/global-policy requirement can never be OWNED by
         // a task (it states an absence or a product-wide rule); the model maps it
-        // NONE every round, which used to force endless whole-plan regeneration.
+        // NONE every round, which forces endless whole-plan regeneration.
         // Carry it cross-cutting instead, so it stops driving the coverage loop.
         else if (isCrossCuttingRequirement(requirements[i].quote))
             acc.crossCutting.push(requirements[i]);
@@ -511,14 +494,13 @@ function formatEntry(e, marker) {
  *   • `unresolved`   — grounded requirements still unmapped after the retry rounds.
  *   • `judgeFlagged` — free-text areas the holistic coverage judge flagged as
  *     uncovered that requirement-extraction never captured as a tracked entry, so
- *     the grounded channels above are structurally blind to them (mx5 2026-07-16:
- *     §10's test-infra setup was seen ONLY by the judge and, having no carrier,
- *     was warned-about then dropped). These are plain strings, not quotes of the
- *     source; marked distinctly so a task can tell an inferred area from a verbatim
- *     obligation.
+ *     the grounded channels above are structurally blind to them: without this
+ *     channel such an area is warned about once and then dropped. These are plain
+ *     strings, not quotes of the source; marked distinctly so a task can tell an
+ *     inferred area from a verbatim obligation.
  *   • `danglingArtifacts` — runtime files the spec references but nothing
- *     produces (mx5 run 13: the served `index.html` no task, tree entry, or
- *     build output ever created), still unclaimed by any title at coverage
+ *     produces (an `index.html` the server serves that no task, tree entry or
+ *     build output ever creates), still unclaimed by any title at coverage
  *     exhaustion. Deterministically extracted (artifact-closure.ts), so like
  *     judge areas they are host-authored strings, not source quotes.
  */
@@ -543,8 +525,10 @@ export async function appendCarriedRequirements(cwd, crossCutting, unresolved =
 }
 /**
  * The read-only block refine/compose receive when carried requirements exist.
- * Verbatim content travels with every task (the directive pattern that works),
- * and the VERIFY mandate is explicit — goal C rides here.
+ * Verbatim content travels with every task — the REFINE_PRESERVE_DIRECTIVE
+ * pattern in phases.ts, content rather than a pointer — and the VERIFY mandate is
+ * spelled out, so a mandated verification methodology reaches every applicable
+ * task's runnable checks.
  */
 export function buildRequirementsBlock(requirements) {
     if (requirements.trim().length === 0)
@@ -566,17 +550,15 @@ export function buildRequirementsBlock(requirements) {
         ''
     ].join('\n');
 }
-// ─── Owned (task-mapped) requirements — the run-16 channel gap ──────────────
+// ─── Owned (task-mapped) requirements ────────────────────────────────
 //
-// Of run 16's 40 kept requirements only the 6 CROSS-CUTTING ones were persisted
-// and injected; the 33 TASK-MAPPED ones rode the decompose ledger (shaping the
-// title list) and then vanished — nothing ever showed a task its OWN mapped
-// obligations. TASK_0008's refine read §9's "serves `/api` + static `dist/`",
-// quoted it in a grill question, and still narrowed the composed spec to
-// "SPA fallback serves index.html"; the shipped server never served the client
-// bundle and the app was permanently blank. An obligation the coverage map
-// assigned to a task must travel INTO that task as verbatim authoritative text,
-// exactly like the cross-cutting channel that measurably works.
+// The CROSS-CUTTING requirements are persisted and injected into every task. The
+// TASK-MAPPED ones only ride the decompose ledger, which shapes the title list —
+// so without this channel nothing ever shows a task its OWN mapped obligations,
+// and a refine that merely READ the clause can still narrow it away in the
+// composed spec. An obligation the coverage map assigned to a task travels INTO
+// that task here, as verbatim authoritative text, on the same channel the
+// cross-cutting requirements use.
 const OWNED_REQUIREMENTS_FILE = 'requirements-owned.md';
 /**
  * Uncapped and never appended to — the mapping is recomputed whole per plan
@@ -650,48 +632,17 @@ export function buildOwnedRequirementsBlock(owned) {
     ].join('\n');
 }
 /**
- * BRACES for the owned channel (the PROMPT-1 pattern): deterministically append
- * each owned obligation the composed spec does not already carry as a
- * CONSTRAINTS bullet. Measured need (scripts/live-owned-requirement-compose-ab
- * .ts, 8 reps/arm on two real run-16 losses): with the belt block alone compose
- * folded the clause into CONSTRAINTS/ACCEPTANCE in only 2/8 reps per fixture
- * (baseline 0/8) — an instruction the model mostly ignores, the PROMPT-4 shape.
- * A host-side append cannot be ignored. "Already carries" = the normalised
- * quote appears anywhere in the spec — belt-obeying reps aren't double-stated.
- * No CONSTRAINTS section (shape-invalid spec) → returned unchanged; this runs
- * only on specs the shape gate already accepted.
- *
- * NOT EXTENDED TO CONSUMER TASKS — REFUTED AT STEP 0, 2026-07-27. The proposal
- * was to classify owned requirements INVARIANT (prohibition-shaped) vs
- * DELIVERABLE and propagate the INVARIANTs from here to every task whose spec
- * names the same symbol/file, because mx5 run 17 gave all three Hono-RPC
- * obligations to TASK_0021 (which complied perfectly) while the four CONSUMER
- * tasks that never saw them — 0027/0031/0033/0034 — hand-wrote casts and shipped
- * 7 dead client call sites. It was not built, for two measured reasons
- * (scripts/owned-consumer-generality-step0.ts, re-runnable):
- *
- *  1. IT DOES NOT GENERALIZE. The task's own kill condition was <20% of a second
- *     stack's OWNED requirements being prohibition-shaped. IAR1, 8 live
- *     regenerations of the real plan-time pipeline over its real 10-task list:
- *     2/42 pooled = 4.8% (narrow four-phrase reading 1/42 = 2.4%). mx5 itself is
- *     7/33 = 21.2% only under the BROAD rule above; under "never/don't/must
- *     not/do not" it is 2/33 = 6.1%. The structural reason is in accountCoverage
- *     right here: a prohibition the map leaves NONE is already carried
- *     cross-cutting to every task, so in the five reps that logged the split 18
- *     of IAR1's 19 prohibition-shaped requirements were never owner-only in the
- *     first place. mx5's 7 leaked because the model mapped them to a TASK.
- *  2. THE TARGETING RULE MISSES ITS OWN MOTIVATING CASE. Symbol/file relevance
- *     would not have reached the four violators for the clause they actually
- *     broke ("If a call isn't fully typed end-to-end via `hc`, fix the route
- *     chaining/export, don't paper over it…"): its only extractable symbol is
- *     `chaining/export`, which no consumer spec contains — 0 consumers. Its
- *     siblings would have reached all four, attaching to 13/41 tasks each; across
- *     mx5's 33 owned requirements the mean attach rate is 21% of all tasks and
- *     5/33 would attach to more than half of them (the task's own I1 trigger).
+ * The host-side belt for the owned channel: deterministically append each owned
+ * obligation the composed spec does not already carry as a CONSTRAINTS bullet.
+ * The injected block alone is an instruction compose can ignore; an append
+ * cannot be. "Already carries" = the normalised quote appears anywhere in the
+ * spec, so a spec that DID fold the clause in is not double-stated. No
+ * CONSTRAINTS section → returned unchanged; this runs only on specs the shape
+ * gate already accepted.
  *
- * Do not re-open on mx5 evidence alone. A future attempt needs a second stack
- * where prohibition-shaped requirements actually land OWNED, and a targeting rule
- * that survives a clause whose symbols are prose.
+ * Scoped to the OWNING task only. A prohibition the coverage map leaves unowned is
+ * already carried cross-cutting to every task by `accountCoverage` above, so the
+ * owned channel is not the place to reach a requirement's other readers.
  */
 export function appendOwnedConstraints(spec, owned) {
     if (owned.length === 0)
@@ -709,8 +660,9 @@ export function appendOwnedConstraints(spec, owned) {
         .join('\n');
     return `${spec.slice(0, insertAt)}\n${bullets}${spec.slice(insertAt)}`;
 }
-/** The decompose-prompt ledger block (goal E's belt): the grounded requirement
- *  list rides into decompose so structure-mirroring can't discharge it. */
+/** The decompose-prompt ledger block: the grounded requirement list rides into
+ *  decompose so a title list that mirrors the spec's own headings cannot
+ *  discharge it. */
 export function buildRequirementsLedger(requirements) {
     if (requirements.length === 0)
         return '';

package/dist/task/research-fanout-budget.d.ts

@@ -1,74 +1,48 @@
 /**
- * nexttask 5B — the two candidate bounds on worker:apis's project-source fan-out.
- *
- * ⚠ ONE of the levers in this file is wired: the RESCUE progress deadline
- * (`workerProgressCeilingMs`) SHIPPED ON in nexttask 9, on a PASS measured over 42
- * trials per arm against an instrument whose own false-break rate is on record at
- * 1.5%. CAP, SCALE and RESCUE-CARRY remain OFF unless their env var is set — CAP
- * and SCALE were rejected on argument (see below), carry-forward was measured
- * HARMFUL on its own.
- *
- * The OFF levers exist so `scripts/live-research-fanout-budget-ab.ts` can run them
- * against the shipped baseline in the SAME build — the alternative (dist surgery)
- * measures a patched copy of the code and not the code. Nothing may read them
- * outside that harness until it reports PASS; a lever wired on argument rather
- * than measurement is the failure mode nexttasks exists to prevent.
- *
- * THE FAULT THEY TARGET (mx5 run 18, measured — scripts/research-restart-baserate.ts):
- * `worker:apis` fans out `pi-worker-docs(module: ".")` project-source lookups, each
- * of which spawns its own summarising child, and the per-worker wall-clock cap is
- * 240s. Pearson r(project lookups, worker wall clock) = 0.909 over 24 tasks. 0-4
- * lookups never timed out; every worker at >=46 lookups burned the FULL restart
- * budget — 3 attempts, 720s, two of them discarded whole. The 240s ceiling and a
- * 46-call fan-out are jointly unsatisfiable, so the timeout is not a backstop
- * there, it is the guaranteed outcome.
- *
- * TWO WAYS TO MAKE THEM SATISFIABLE, and the A/B — not this comment — decides:
+ * research-fanout-budget — the levers bounding worker:apis's project-source
+ * fan-out, and which of them is on.
+ *
+ * `workerProgressCeilingMs` is ON by default; its env var is the OFF switch. CAP
+ * (`projectDocsBudget`), SCALE (`fanoutTimeoutPolicy`) and RESCUE-CARRY
+ * (`workerCarryForward`) are OFF unless their env var is set. They stay in the
+ * shipped build so a harness can run them against the shipped baseline in the SAME
+ * build — patching a copy of the code measures the copy, not the code. Nothing may
+ * read them outside such a harness.
+ *
+ * THE FAULT THEY TARGET. `worker:apis` fans out `pi-worker-docs(module: ".")`
+ * project-source lookups, and each one spawns its own summarising child. Under a
+ * fixed wall-clock cap, a large enough fan-out cannot finish inside it — so the
+ * timeout is not a backstop there, it is the guaranteed outcome.
  *
  *   CAP     bound the fan-out to fit the ceiling. Told to the worker upfront
  *           (projectDocsBudgetNotice) and enforced in the tool
- *           (projectDocsBudgetExhausted), because run 18 shows the prompt alone
- *           does not bind: the same worker is ALREADY told "be decisive" by
- *           WORKER_TIMEOUT_HINT on every restart.
- *   SCALE   bound the ceiling to fit the fan-out: each project-source lookup
- *           pushes the deadline out, up to a hard ceiling, so a worker that is
- *           making progress is not killed for making progress.
- *
- * The risk each carries, and why the A/B's quality invariant is load-bearing: CAP
- * can produce a faster worker that ships a THINNER APIS section, which is a
- * regression wearing a win's clothes (memory/apis-contract-stage2-failed.md: a
- * lever moved behaviour 20/20 while fabricating 15% of it). SCALE can simply
- * spend the extra time and still time out, buying nothing.
- *
- * ─────────────────────────────────────────────────────────────────────────────
- * BOTH OF THE ABOVE ANSWER THE WRONG QUESTION. Kept for the record and for the
- * A/B's other arms, but they are not the fix.
- *
- * They argue about how long a worker may run. The actual defect is what happens
- * when it runs out: the attempt is killed and everything it produced is THROWN
- * AWAY, and the re-spawn is given a hint but no findings — so it re-reads the
- * same files against the same clock and dies in the same place. That is why
- * every worker at >=46 lookups burned the FULL budget rather than converging.
- * The r=0.909 correlation measures the amnesia, not an over-long task.
+ *           (projectDocsBudgetExhausted). The prompt alone does not bind: the same
+ *           worker is ALREADY told "be decisive" by WORKER_TIMEOUT_HINT
+ *           (pi-worker-core.ts) on every restart.
+ *   SCALE   bound the ceiling to fit the fan-out: each project-source lookup pushes
+ *           the deadline out, up to a hard ceiling, so a worker that is making
+ *           progress is not killed for making progress.
+ *
+ * BOTH ANSWER THE WRONG QUESTION. They argue about how long a worker may run. The
+ * defect is what happens when it runs out: the attempt is killed, everything it
+ * produced is THROWN AWAY, and the re-spawn gets a hint but no findings — so it
+ * re-reads the same files against the same clock and dies in the same place.
  *
  * Judged against "the worker must return its work", CAP makes the worker read
- * LESS — lowering the requirement so the metric goes green — and SCALE is a
- * per-file constant that dies on one big file, and, being wall-clock, makes
- * answer quality a function of the user's hardware: the same task on a slower
- * local model loses its work and degrades. No constant fixes that.
- *
- *   RESCUE  (pi-worker-core.ts) carry the killed attempt's findings into the
- *           next one and never return less than the best attempt produced, so a
- *           restart CONVERGES instead of repeating; and deadline on lack of
- *           PROGRESS rather than elapsed time, so "slow" and "stuck" stop being
- *           the same verdict. Being stuck is already detected separately and
- *           correctly by the output-stall probe (STALL_AFTER_MS), which resets
- *           on progress and only kills when the model endpoint is unreachable.
- *
- * Its risk is its own, and the same quality invariant catches it: a half-written
- * entry replayed under "work already done" is exactly how a fabrication gets
- * laundered into a final answer. Hence the carry is framed as unverified, and
- * ungrounded-symbol and anti-synthesis counts gate the arm.
+ * LESS, lowering the requirement so the metric goes green; and SCALE is a per-file
+ * constant that dies on one big file and, being wall-clock, makes answer quality a
+ * function of the user's hardware — the same task on a slower model loses its work.
+ *
+ *   RESCUE  (pi-worker-core.ts) carry the killed attempt's findings into the next
+ *           one and never return less than the best attempt produced, so a restart
+ *           CONVERGES instead of repeating; and deadline on lack of PROGRESS rather
+ *           than elapsed time, so "slow" and "stuck" stop being the same verdict.
+ *           Being stuck is already detected separately by the output-stall probe
+ *           (STALL_AFTER_MS, worker-profiles.ts), which resets on progress.
+ *
+ * The carry has a risk of its own: a half-written entry replayed under "work
+ * already done" is how a fabrication gets laundered into a final answer. That is
+ * why the carry is framed to the worker as unverified.
  */
 /** Max project-source (`module: "."`) docs lookups per worker ATTEMPT. Unset = no cap. */
 export declare const PROJECT_DOCS_BUDGET_ENV = "PI_TASK_PROJECT_DOCS_BUDGET";
@@ -93,12 +67,10 @@ export declare const RESEARCH_LEVER_ENVS: readonly string[];
  * The levers, read ONCE, as a reader the profile table can be handed.
  *
  * WHY A SNAPSHOT AND NOT `process.env`. Every worker in one research phase must
- * see the same arm. The three lever values used to be resolved once in
- * `phases.ts` and threaded down as three separate `ResearchWorkerRun` fields for
- * exactly that reason; moving the resolution into the `research` profile would
- * have moved the READ down to each worker with it, and a harness that flips a
- * var mid-phase would then half-apply its own arm. Freezing the reader keeps the
- * read-once property while letting the profile own what the values MEAN.
+ * see the same lever values. A profile that read `process.env` itself would move
+ * the read down to each worker, and a var flipped mid-phase would then apply to
+ * some workers and not others. Freezing the reader keeps the read-once property
+ * while letting the profile own what the values MEAN.
  */
 export declare function snapshotLeverEnv(env?: Env): Env;
 /**
@@ -129,14 +101,10 @@ export declare function workerCarryForward(env?: Env): boolean;
 /**
  * The absolute backstop for the progress-based deadline.
  *
- * WHY THIS NUMBER. It is not a budget and it does not decide how long a worker
- * may take — the no-progress deadline does that, and it resets on every tool call.
- * This is the last-resort bound on a worker that never stops moving (an infinite
- * tool-call loop the loop detector somehow misses), so its only requirement is to
- * sit clear of the real workload. Measured on 42 progress-arm trials
- * (`~/tmp/research-fanout-ab-v3`): median 275s, p90 523s, **max 730s**. 20 minutes
- * is 1.6x the observed worst case, and 1.7x the 720s the SHIPPED path already
- * spends on a worker that burns all three attempts and returns nothing.
+ * It is not a budget and it does not decide how long a worker may take — the
+ * no-progress deadline does that, and it resets on every tool call. This is the
+ * last-resort bound on a worker that never stops moving (a tool-call loop the loop
+ * detector misses), so its only requirement is to sit clear of the real workload.
  *
  * A ceiling that never fires in production is the correct behaviour for a
  * backstop, not evidence it is untested: it fires under test
@@ -148,12 +116,7 @@ export declare const DEFAULT_WORKER_PROGRESS_CEILING_MS = 1200000;
 /**
  * The progress-based deadline's ceiling, or null when the lever is OFF.
  *
- * SHIPPED ON as of nexttask 9 — the env var is now the OFF switch, not the on
- * switch. Measured baseline vs progress over 42 trials/arm on a calibrated
- * instrument (A/A false-break 1.5%): worker-timeout restarts 22/24 → 0/24,
- * degrades 8/24 → 0/24, entries up on all four high-fan-out fixtures (TASK_0021
- * 11.0 → 25.5), quality invariants HOLD, every treatment-arm ungrounded flag
- * hand-verified as an instrument artifact rather than a fabrication.
+ * ON by default, so the env var is the OFF switch, not the on switch:
  *
  *     unset            ON at DEFAULT_WORKER_PROGRESS_CEILING_MS
  *     "0" | "off"      OFF — the fixed elapsed-time cap, exactly as before
@@ -167,9 +130,9 @@ export declare function workerProgressCeilingMs(env?: Env): number | null;
  * The upfront half of the CAP arm, appended to the APIS worker's prompt.
  *
  * Upfront and NUMERIC on purpose. The worker cannot ration a budget it learns
- * about only when it is spent, and "be decisive" — which it already receives on
- * every timeout restart — is exactly the unquantified version that run 18 shows
- * it ignoring until the third attempt.
+ * about only when it is spent, and "be decisive" — WORKER_TIMEOUT_HINT, which it
+ * already receives on every timeout restart — is the unquantified version of the
+ * same ask.
  */
 export declare function projectDocsBudgetNotice(budget: number): string;
 /** The enforcement half: what the tool returns once the budget is spent. */