@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/serve-entry.js

@@ -1,21 +1,16 @@
 /**
  * serve-entry — the project builds a server app, expects to SERVE, and nothing in
- * the tree ever starts a listener (nexttask 2 part B).
+ * the tree ever starts a listener.
  *
- * THE FAILURE THIS CLOSES (mx5 run 18, measured). The shipped `src/server/index.ts`
- * is 28 lines that construct a Hono app, mount five `/api` routers, add an SPA
- * fallback reading `Bun.file('dist/index.html')` — and end at `export {app}`. There
- * is no `Bun.serve`, no `export default app`, no `serve()` from an adapter, no
- * `start` script. Running the entry directly exits 0 in milliseconds:
+ * THE FAILURE THIS CLOSES. A `src/server/index.ts` constructs a Hono app, mounts
+ * its `/api` routers, adds an SPA fallback reading `Bun.file('dist/index.html')` —
+ * and ends at `export {app}`. No `Bun.serve`, no `export default app`, no `serve()`
+ * from an adapter. Running that entry exits 0 immediately: the product cannot be
+ * started at all.
  *
- *     $ DATABASE_URL=… timeout 15 bun run src/server/index.ts   → EXIT=0
- *
- * The product could not be started at all, and the run shipped green: the gate's
- * boot command resolved to a `docker compose up` orchestrator, docker was absent in
- * the sandbox, and the boot SKIPPED. This is the SECOND run to lose this exact
- * clause — mx5 run 16 shipped a server that never served the client bundle
- * (scripts/live-owned-requirement-compose-ab.ts) — so a dynamic-only gate has now
- * failed to catch it twice.
+ * A dynamic gate does not necessarily catch it. If the boot command resolves to an
+ * orchestrator the environment cannot run, the boot SKIPS under the env-gap
+ * contract and the run ships green.
  *
  * WHY STATIC. The check needs no runtime, no browser, no docker, no database and no
  * model: the tree either contains a bind or it does not. It runs in milliseconds and
@@ -50,9 +45,9 @@ const CONSTRUCT_PATTERNS = [
     { re: /(?:^|[^.\w])express\s*\(\s*\)/, construct: 'express()' },
     { re: /(?:^|[^.\w])[Ff]astify\s*\(/, construct: 'fastify()' },
     { re: /(?:^|[^.\w])polka\s*\(/, construct: 'polka()' }
-    // `connect()` (the middleware framework) is deliberately absent: gofer's
-    // src/store/db.ts calls `connect()` on a DATABASE, and a construct signal that
-    // cannot tell a server from a db handle is not a construct signal.
+    // `connect()` (the middleware framework) is deliberately absent: `connect()` is
+    // also what a database module calls, and a construct signal that cannot tell a
+    // server from a db handle is not a construct signal.
 ];
 /**
  * Anything that starts (or hands off) a listener. Deliberately GENEROUS: every
@@ -72,7 +67,8 @@ const BIND_PATTERNS = [
  *  Vercel) starts whatever is exported. A default-exported config object
  *  (`export default defineConfig({…})`) is not one of them, and neither is a React
  *  component — hence the identifier must be a name the tree BOUND to a server-app
- *  construction (aiz-client's `export default App` is a component, not a listener). */
+ *  construction. `export default App` on a component names nothing this scan
+ *  constructed, so it is not a bind. */
 function defaultExportBind(src, appNames) {
     for (const m of src.matchAll(/export\s+default\s+([A-Za-z_$][\w$]*)/g)) {
         if (appNames.has(m[1]))
@@ -147,7 +143,7 @@ export function findServeExpectation(src) {
     return null;
 }
 /** A design/spec clause that names a served path — the plan-side half of the same
- *  expectation (mx5's `DESIGN/PROJECT.md:285`: "serves `/api` + static `dist/`"). */
+ *  expectation, e.g. a design that says "serves `/api` + static `dist/`". */
 export function planExpectsServing(planText) {
     if (!planText)
         return null;
@@ -182,8 +178,8 @@ export function opaqueLauncher(cwd) {
     return null;
 }
 // The tree walk, the caps, the skip sets and the comment strip live in
-// task/shipped-source.ts — this scan and artifact-closure's were the same walker
-// written twice, and their skip sets had drifted apart on `bench`/`benchmarks`.
+// task/shipped-source.ts, shared with artifact-closure's scan so the two cannot
+// drift apart on which directories they skip.
 const scanCandidates = (cwd) => shippedSources(cwd, { ext: SOURCE_JS_RE });
 /** A `/…/flags` literal whose body carries a regex METACHARACTER — `[`, `\`, `+`,
  *  `?`, `|`, a group. A path string like `'/api/admin'` has none, so it survives. */
@@ -192,10 +188,11 @@ const METACHAR_RE = /[\\[\]+*?^$|(){}]/;
 /**
  * Blank out regex literals. A project that MATCHES on `new Hono` — a linter, a
  * codemod, this very module — does not construct one, and a source scanner that
- * cannot tell the two apart reports every detector as an app (pi-task scanned
- * itself and found "9 server apps", all of them pattern tables). Only literals
- * carrying a metacharacter are stripped, so `'/api/v1'` is untouched, and because
- * stripping can only REMOVE matches it is safe in the FP direction by construction.
+ * cannot tell the two apart reports every detector as an app. With this in place
+ * `scanServeEntry` finds ZERO apps in pi-task's own tree, whose pattern tables name
+ * every construct it looks for. Only literals carrying a metacharacter are
+ * stripped, so `'/api/v1'` is untouched, and because stripping can only REMOVE
+ * matches it is safe in the FP direction by construction.
  */
 function stripRegexLiterals(src) {
     return src.replace(REGEX_LITERAL_RE, (whole, body) => METACHAR_RE.test(body) ? ' ' : whole);

package/dist/task/service-blocks.js

@@ -5,8 +5,10 @@ export function formatServiceBlock(name, fullQuery, results) {
     const bullets = results.map(r => `- **${r.title}** — ${r.url}\n  ${r.description}`).join('\n');
     return `${header}\n${bullets}`;
 }
-// Only the brave provider can be unconfigured (exa/ddg are keyless), so the
-// skip reason names its missing key directly.
+// Only brave can be unconfigured: `SEARCH_PROVIDER_KEY_ENV` (search-types.ts)
+// lists no env var for exa or ddg, so `searchProviderKey` answers '' for them and
+// the `no_key` result this block reports is unreachable. The reason therefore
+// names brave's key outright rather than describing a generic misconfiguration.
 export function formatFreshnessSkippedBlock(names) {
     return `### freshness-check skipped\nCould not verify external services (search provider is brave but BRAVE_SEARCH_API_KEY is not set):\n${names.map(n => `- ${n}`).join('\n')}`;
 }

package/dist/task/shipped-source.d.ts

@@ -1,35 +1,17 @@
 /**
- * What counts as SHIPPED SOURCE — the input every run-level closure scan reads.
+ * What counts as SHIPPED SOURCE — the input the run-level closure scans read.
  *
- * `CLOSURE_SCANS` (final-gate.ts) deepened the DRIVER of these scans: the fault
- * isolation, the rank, the stage. It did not unify their INPUT, and the copies
- * had drifted.
+ * ONE walker, ONE skip set, ONE extension regex, ONE comment strip, shared by
+ * `serve-entry.ts` and `artifact-closure.ts`. Two copies of this drift: a skip set
+ * that gains a directory on one side makes a file a run-level finding for one scan
+ * while the sibling scan cannot see it at all, and nothing in either file would say
+ * so.
  *
- *  - `scanCandidates` existed twice, near-byte-identical — `serve-entry.ts` and
- *    `artifact-closure.ts` — same `readdirSync().sort()` → `statSync` → recurse,
- *    same 3000-file cap, same 400 KB per-file cap, same dot-dir rule.
- *  - The skip sets had diverged: serve-entry carried `bench|benchmarks` and
- *    `*.bench.*`; artifact-closure did not, so a dangling artifact reference in a
- *    benchmark file was a run-level finding while the same file was invisible to
- *    the sibling scan. Nothing in either file acknowledged the other.
- *  - The same extension regex was declared twice under two names (`SCAN_RE`,
- *    `SCAN_JS_RE`), and `stripCommentLines` was byte-identical in both.
- *  - `.pi-tasks` was hardcoded into both skip sets rather than derived from
- *    `TASKS_DIR_NAME`.
- *
- * The locality proof is in the suites: `artifact-closure.test.ts` has 28
- * references to the pure extractors and 5 calls to the driver, and NO test in the
- * cluster asserted a skip set at all. That is the shape recorded under
- * `resolveTypeSource` — pure functions extracted for testability while the real
- * logic stayed in how they are CALLED.
- *
- * NOT unified here: `env-template-closure.ts`. It asks a different question —
- * which TRACKED files could read an env var, including `.py`/`.go`, including
- * tests — and answering it over this walk would silently change which env
- * findings a run produces. Its comment rule is not this one either: it is a
- * per-line predicate that also treats `#` as a comment opener, which it must,
- * and which would be wrong for JS/TS. Recorded as a real divergence rather than
- * harmonised; changing it is an env-policy change with its own A/B.
+ * NOT unified here: `env-template-closure.ts`. It asks a different question — which
+ * TRACKED files could read an env var, `.py` and `.go` included, tests included —
+ * and answering it over this walk would silently change which env findings a run
+ * produces. Its comment rule differs too: a per-line predicate that also treats `#`
+ * as an opener, which it must, and which would be wrong for JS/TS.
  */
 /** Authored JS/TS. The one declaration — it was two constants under two names. */
 export declare const SOURCE_JS_RE: RegExp;

package/dist/task/shipped-source.js

@@ -1,35 +1,17 @@
 /**
- * What counts as SHIPPED SOURCE — the input every run-level closure scan reads.
+ * What counts as SHIPPED SOURCE — the input the run-level closure scans read.
  *
- * `CLOSURE_SCANS` (final-gate.ts) deepened the DRIVER of these scans: the fault
- * isolation, the rank, the stage. It did not unify their INPUT, and the copies
- * had drifted.
+ * ONE walker, ONE skip set, ONE extension regex, ONE comment strip, shared by
+ * `serve-entry.ts` and `artifact-closure.ts`. Two copies of this drift: a skip set
+ * that gains a directory on one side makes a file a run-level finding for one scan
+ * while the sibling scan cannot see it at all, and nothing in either file would say
+ * so.
  *
- *  - `scanCandidates` existed twice, near-byte-identical — `serve-entry.ts` and
- *    `artifact-closure.ts` — same `readdirSync().sort()` → `statSync` → recurse,
- *    same 3000-file cap, same 400 KB per-file cap, same dot-dir rule.
- *  - The skip sets had diverged: serve-entry carried `bench|benchmarks` and
- *    `*.bench.*`; artifact-closure did not, so a dangling artifact reference in a
- *    benchmark file was a run-level finding while the same file was invisible to
- *    the sibling scan. Nothing in either file acknowledged the other.
- *  - The same extension regex was declared twice under two names (`SCAN_RE`,
- *    `SCAN_JS_RE`), and `stripCommentLines` was byte-identical in both.
- *  - `.pi-tasks` was hardcoded into both skip sets rather than derived from
- *    `TASKS_DIR_NAME`.
- *
- * The locality proof is in the suites: `artifact-closure.test.ts` has 28
- * references to the pure extractors and 5 calls to the driver, and NO test in the
- * cluster asserted a skip set at all. That is the shape recorded under
- * `resolveTypeSource` — pure functions extracted for testability while the real
- * logic stayed in how they are CALLED.
- *
- * NOT unified here: `env-template-closure.ts`. It asks a different question —
- * which TRACKED files could read an env var, including `.py`/`.go`, including
- * tests — and answering it over this walk would silently change which env
- * findings a run produces. Its comment rule is not this one either: it is a
- * per-line predicate that also treats `#` as a comment opener, which it must,
- * and which would be wrong for JS/TS. Recorded as a real divergence rather than
- * harmonised; changing it is an env-policy change with its own A/B.
+ * NOT unified here: `env-template-closure.ts`. It asks a different question — which
+ * TRACKED files could read an env var, `.py` and `.go` included, tests included —
+ * and answering it over this walk would silently change which env findings a run
+ * produces. Its comment rule differs too: a per-line predicate that also treats `#`
+ * as an opener, which it must, and which would be wrong for JS/TS.
  */
 import { readdirSync, statSync } from 'node:fs';
 import * as path from 'node:path';

package/dist/task/skip-escape.js

@@ -1,22 +1,18 @@
 /**
- * Deterministic skip-escape scanner for authored VERIFY blocks (run-8 F2).
+ * Deterministic skip-escape scanner for authored VERIFY blocks.
  *
  * A skip-escape is a `||` fallback that lets a REQUIRED check pass SILENTLY when
  * its tool is absent or it fails — e.g. `playwright test … || echo "skipping"`.
- * mx5 run-8 shipped a blank/dead app partly because its only behavioral smoke
- * tests were wrapped this way: the tool was absent, the check silently skipped,
- * and the verify child blessed it as "correctly skipped".
+ * A spec whose only behavioural check is wrapped that way passes its gate on a
+ * machine without the tool, and the verify child reads it as "correctly skipped".
  *
- * FP-MEASURED on the historical VERIFY blocks (~/hub/mx5/.pi-tasks, 22 tasks): a
- * blanket `|| true` flag is ~90% false positives — teardown (`kill … || true`,
- * `docker compose down … || true`), setup (`… install … || true`), and negative
- * tests (`… && exit 1 || true`, where `|| true` catches an EXPECTED failure). Of
- * 45 `||` uses, exactly one was the real F2 skip-escape, and it ANNOUNCED the skip
- * ("Playwright not available — skipping browser smoke test"). So the crisp,
- * ~zero-FP signal is a fallback whose text ADMITS it is dodging the check — that is
- * the actionable finding here. Bare `|| true` is left to the verify child's runtime
- * rule 5c, which can actually observe whether the check ran (a static scan cannot
- * tell a required-check `|| true` from a teardown `|| true`).
+ * Flagging every `|| true` would be almost all false positives: teardown
+ * (`kill … || true`, `docker compose down … || true`), setup (`… install
+ * … || true`) and negative tests (`… && exit 1 || true`, where `|| true` catches
+ * an EXPECTED failure) are all legitimate, and a static scan cannot tell a
+ * required-check `|| true` from a teardown one. The crisp signal is narrower: a
+ * fallback whose TEXT admits it is dodging the check. Bare `|| true` is left to
+ * the verify child's runtime rule 5c, which can observe whether the check ran.
  *
  * Pure shell-shape / text analysis; no stack or tool-name assumptions.
  */

package/dist/task/spec-urls.d.ts

@@ -1,60 +1,28 @@
 /**
- * PROMPT 4 / F-2(b) — the design document's own cited URLs, ranked as fetch candidates for
- * the APIS research worker.
+ * The design document's own cited URLs, ranked as fetch candidates for the APIS
+ * research worker.
  *
- * THE FACT THIS CLOSES. mx5's DESIGN/PROJECT.md is a literal reference list: §5 line 184
- * cites https://hono.dev/docs/guides/rpc and §13 lists four hono.dev URLs plus
- * https://bun.com/docs/runtime/sql. Neither of the two pages that document the semantics
- * behind run 15's two fatal defects was ever fetched — worker:apis' 6 distinct fetches went
- * to bun.com/reference/*, tailwindcss.com/* and nothing on hono.dev at all. Measured
- * afterwards (scripts/spec-url-reach.ts): 31 of 44 tasks asked pi-worker-docs about a package
- * for which the design cites a page, 215 (task, URL) pairs, and 15 of the 17 reachable cited
- * URLs were never fetched by anyone. The pages were named, in the project's own spec, and the
- * worker went looking somewhere else.
+ * A design that names its references by URL has already chosen which pages
+ * document the packages it uses. Nothing makes a research worker prefer them: it
+ * searches, and lands wherever the search lands. This module extracts the cited
+ * URLs, keeps the ones documenting a package THIS task touches, and renders them
+ * as a ranked prompt block.
  *
- * WHY THIS IS A POPULATION LEVER AND THE TYPE-ONLY GUARD WAS NOT. PROMPT 2's detector fires
- * on 0.54% of docs answers (9/1680 live) because it has to RECOGNISE something about an
- * answer. This one recognises nothing: the URLs are already sitting in the spec text, so its
- * reach is "every task whose design cites a page for a package the task uses" — the 31/44
- * above, measured before any of this was written.
+ * RANKING, NOT REPLACING. The block says the cited pages outrank a page the model
+ * would pick itself, and says in terms that they are not the only pages it may
+ * fetch. A worker that can no longer follow a question off the design's reference
+ * list has been narrowed, not improved.
  *
- * RANKING, NOT REPLACING. The block says the cited pages outrank a page the model would pick
- * itself, and says in terms that they are not the only pages it may fetch. A worker that can
- * no longer follow a question off the design's reference list has been narrowed, not
- * improved; PROMPT 4 invariant 3 asserts that explicitly in the A/B.
- *
- * ── *** NOT WIRED. THE LIVE A/B FAILED. READ THIS BEFORE RE-ENABLING IT. *** ─────────────
- *
- * scripts/live-spec-url-fetch-ab.ts, 2026-07-22, 40 reps, both arms in one process, real
- * phaseResearch, offline fixture web, metric = WHICH URL WAS FETCHED at the tool layer:
- *
- *     task27-hono     baseline 2/10   treatment 3/10    Fisher one-tailed p = 0.50
- *     task28-wouter   baseline 0/10   treatment 0/10    p = 1.00
- *     POOLED          baseline 2/20   treatment 3/20    p = 0.50
- *
- * Everything that could have made that a false negative was ruled out, not assumed:
- *   - the surgery held in every rep (baseline block 0 chars 20/20, treatment non-empty 20/20);
- *   - a positive control proved a real child can reach the stubbed pi-worker-fetch;
- *   - the block was proven to REACH the APIS prompt, not merely to be built — the prompt is
- *     19,473 chars and ends with the six ranked URLs
- *     (scripts/spec-url-prompt-delivery-check.ts).
- * So the model reads the instruction and does not act on it.
- *
- * AND THE PREMISE ITSELF DID NOT SURVIVE. PROMPT 4 rests on run 15 having fetched the WRONG
- * pages. Across all 40 reps the only URL any worker ever fetched, in either arm, was
- * https://hono.dev/docs/guides/rpc — the cited one. The worker does not choose badly between
- * pages; it almost never fetches at all (5 of 40 reps). A lever that improves URL RANKING is
- * aimed at a decision this worker rarely makes.
- *
- * The module is kept — deterministic, unit-tested against the real run-15 design text, and
- * the A/B harness's string surgery targets it — so the experiment can be re-run cheaply if
- * the fetch rate itself is ever moved. It is NOT called from phases.ts, deliberately.
+ * NOT WIRED. `buildSpecUrlBlock` has no production caller — phases.ts says so at
+ * the site where it would go. The module is kept deterministic and unit-tested
+ * against real design text so the experiment can be re-run cheaply, but nothing in
+ * a run reads it today.
  */
 /**
- * How many cited pages the block may name. The design cites 21 URLs; listing all of them in
- * every APIS prompt would be prefill spent on pages the task has no use for, and a list long
- * enough to skim past is a list the model ignores. Eight is above the highest per-task
- * reachable count measured on run 15 (5 hono.dev pages for a hono task) with headroom.
+ * How many cited pages the block may name. A design's whole reference list, repeated in
+ * every APIS prompt, is prefill spent on pages the task has no use for, and a list long
+ * enough to skim past is a list the model ignores. The ranking already drops every URL
+ * documenting nothing this task touches, so this only bounds a task that touches a lot.
  */
 export declare const MAX_SPEC_URLS = 8;
 /** http(s) URLs in a text, deduped, with local and placeholder hosts dropped. */
@@ -72,7 +40,7 @@ export declare function packageTokens(pkg: string): string[];
  * Does this cited URL document this package? Host OR path, deliberately: wouter's page is
  * github.com/molefrog/wouter#readme and @hono/zod-validator's is
  * github.com/honojs/middleware/tree/main/packages/zod-validator — both real associations that
- * live in the path. A host-only rule scored 0 tasks for either.
+ * live in the path, and a host-only rule matches neither.
  */
 export declare function urlDocumentsPackage(url: string, pkg: string): boolean;
 export interface RankedSpecUrl {
@@ -92,24 +60,17 @@ export interface RankedSpecUrl {
 export declare function rankSpecUrls(urls: string[], packages: string[]): RankedSpecUrl[];
 /**
  * The prompt block, or '' when nothing is cited for anything this task uses.
- *
- * NOTE FOR ANYONE EDITING THE GUARD CLAUSE BELOW: scripts/live-spec-url-fetch-ab.ts strips
- * this lever for its baseline arm by replacing that exact statement in the compiled output,
- * and asserts it occurs exactly once. Reshaping it (an early `return` on the caller's side, a
- * ternary, a different variable name) silently makes both arms identical, which reads as
- * "the lever had no effect". Update the harness's anchor in the same commit.
  */
 export declare function buildSpecUrlBlock(urls: string[], packages: string[]): string;
 /**
  * The manifest dependencies this task's refined text actually names — the relevance signal
- * the ranking needs, and the reason the block does not simply list all 21 cited URLs.
+ * the ranking needs, and the reason the block does not simply list every cited URL.
  *
- * WHY NOT extractEnrichTargets. That parser is tuned for the EXTERNAL-DEPENDENCIES section
- * and, run over TASK_0027's refined text, returns ["any", "api", "hc", "package.json",
- * "tsconfig.json", "eslint.config.js"] — and NOT "hono". Ranking off that would drop the one
- * package the task is about while promoting URL noise. The manifest is the authoritative list
- * of what the project actually depends on; matching it against the task text is both
- * deterministic and impossible to fool with prose.
+ * WHY NOT extractEnrichTargets (enrichment.ts). That parser is tuned for the
+ * EXTERNAL-DEPENDENCIES section, so over an ordinary refined text it returns whatever
+ * identifiers and config filenames the prose mentions rather than the packages the task is
+ * about. The manifest is the authoritative list of what the project actually depends on;
+ * matching it against the task text is deterministic and cannot be fooled by prose.
  *
  * Word-boundary matched, so `react` does not match inside `react-dom` or `@types/react`, and
  * a package genuinely named twice is still listed once.

package/dist/task/spec-urls.js

@@ -1,63 +1,31 @@
 /**
- * PROMPT 4 / F-2(b) — the design document's own cited URLs, ranked as fetch candidates for
- * the APIS research worker.
+ * The design document's own cited URLs, ranked as fetch candidates for the APIS
+ * research worker.
  *
- * THE FACT THIS CLOSES. mx5's DESIGN/PROJECT.md is a literal reference list: §5 line 184
- * cites https://hono.dev/docs/guides/rpc and §13 lists four hono.dev URLs plus
- * https://bun.com/docs/runtime/sql. Neither of the two pages that document the semantics
- * behind run 15's two fatal defects was ever fetched — worker:apis' 6 distinct fetches went
- * to bun.com/reference/*, tailwindcss.com/* and nothing on hono.dev at all. Measured
- * afterwards (scripts/spec-url-reach.ts): 31 of 44 tasks asked pi-worker-docs about a package
- * for which the design cites a page, 215 (task, URL) pairs, and 15 of the 17 reachable cited
- * URLs were never fetched by anyone. The pages were named, in the project's own spec, and the
- * worker went looking somewhere else.
+ * A design that names its references by URL has already chosen which pages
+ * document the packages it uses. Nothing makes a research worker prefer them: it
+ * searches, and lands wherever the search lands. This module extracts the cited
+ * URLs, keeps the ones documenting a package THIS task touches, and renders them
+ * as a ranked prompt block.
  *
- * WHY THIS IS A POPULATION LEVER AND THE TYPE-ONLY GUARD WAS NOT. PROMPT 2's detector fires
- * on 0.54% of docs answers (9/1680 live) because it has to RECOGNISE something about an
- * answer. This one recognises nothing: the URLs are already sitting in the spec text, so its
- * reach is "every task whose design cites a page for a package the task uses" — the 31/44
- * above, measured before any of this was written.
+ * RANKING, NOT REPLACING. The block says the cited pages outrank a page the model
+ * would pick itself, and says in terms that they are not the only pages it may
+ * fetch. A worker that can no longer follow a question off the design's reference
+ * list has been narrowed, not improved.
  *
- * RANKING, NOT REPLACING. The block says the cited pages outrank a page the model would pick
- * itself, and says in terms that they are not the only pages it may fetch. A worker that can
- * no longer follow a question off the design's reference list has been narrowed, not
- * improved; PROMPT 4 invariant 3 asserts that explicitly in the A/B.
- *
- * ── *** NOT WIRED. THE LIVE A/B FAILED. READ THIS BEFORE RE-ENABLING IT. *** ─────────────
- *
- * scripts/live-spec-url-fetch-ab.ts, 2026-07-22, 40 reps, both arms in one process, real
- * phaseResearch, offline fixture web, metric = WHICH URL WAS FETCHED at the tool layer:
- *
- *     task27-hono     baseline 2/10   treatment 3/10    Fisher one-tailed p = 0.50
- *     task28-wouter   baseline 0/10   treatment 0/10    p = 1.00
- *     POOLED          baseline 2/20   treatment 3/20    p = 0.50
- *
- * Everything that could have made that a false negative was ruled out, not assumed:
- *   - the surgery held in every rep (baseline block 0 chars 20/20, treatment non-empty 20/20);
- *   - a positive control proved a real child can reach the stubbed pi-worker-fetch;
- *   - the block was proven to REACH the APIS prompt, not merely to be built — the prompt is
- *     19,473 chars and ends with the six ranked URLs
- *     (scripts/spec-url-prompt-delivery-check.ts).
- * So the model reads the instruction and does not act on it.
- *
- * AND THE PREMISE ITSELF DID NOT SURVIVE. PROMPT 4 rests on run 15 having fetched the WRONG
- * pages. Across all 40 reps the only URL any worker ever fetched, in either arm, was
- * https://hono.dev/docs/guides/rpc — the cited one. The worker does not choose badly between
- * pages; it almost never fetches at all (5 of 40 reps). A lever that improves URL RANKING is
- * aimed at a decision this worker rarely makes.
- *
- * The module is kept — deterministic, unit-tested against the real run-15 design text, and
- * the A/B harness's string surgery targets it — so the experiment can be re-run cheaply if
- * the fetch rate itself is ever moved. It is NOT called from phases.ts, deliberately.
+ * NOT WIRED. `buildSpecUrlBlock` has no production caller — phases.ts says so at
+ * the site where it would go. The module is kept deterministic and unit-tested
+ * against real design text so the experiment can be re-run cheaply, but nothing in
+ * a run reads it today.
  */
 /** Never candidates: a local dev URL is not documentation. */
 const LOCAL_HOST = /^(localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\]|.*\.local)$/i;
 const PLACEHOLDER_HOST = /^(example\.(com|org|net)|your-.*|<.*)$/i;
 /**
- * How many cited pages the block may name. The design cites 21 URLs; listing all of them in
- * every APIS prompt would be prefill spent on pages the task has no use for, and a list long
- * enough to skim past is a list the model ignores. Eight is above the highest per-task
- * reachable count measured on run 15 (5 hono.dev pages for a hono task) with headroom.
+ * How many cited pages the block may name. A design's whole reference list, repeated in
+ * every APIS prompt, is prefill spent on pages the task has no use for, and a list long
+ * enough to skim past is a list the model ignores. The ranking already drops every URL
+ * documenting nothing this task touches, so this only bounds a task that touches a lot.
  */
 export const MAX_SPEC_URLS = 8;
 /** http(s) URLs in a text, deduped, with local and placeholder hosts dropped. */
@@ -110,7 +78,7 @@ export function packageTokens(pkg) {
  * Does this cited URL document this package? Host OR path, deliberately: wouter's page is
  * github.com/molefrog/wouter#readme and @hono/zod-validator's is
  * github.com/honojs/middleware/tree/main/packages/zod-validator — both real associations that
- * live in the path. A host-only rule scored 0 tasks for either.
+ * live in the path, and a host-only rule matches neither.
  */
 export function urlDocumentsPackage(url, pkg) {
     const toks = packageTokens(pkg);
@@ -152,12 +120,6 @@ export function rankSpecUrls(urls, packages) {
 }
 /**
  * The prompt block, or '' when nothing is cited for anything this task uses.
- *
- * NOTE FOR ANYONE EDITING THE GUARD CLAUSE BELOW: scripts/live-spec-url-fetch-ab.ts strips
- * this lever for its baseline arm by replacing that exact statement in the compiled output,
- * and asserts it occurs exactly once. Reshaping it (an early `return` on the caller's side, a
- * ternary, a different variable name) silently makes both arms identical, which reads as
- * "the lever had no effect". Update the harness's anchor in the same commit.
  */
 export function buildSpecUrlBlock(urls, packages) {
     const ranked = rankSpecUrls(urls, packages);
@@ -189,14 +151,13 @@ export function buildSpecUrlBlock(urls, packages) {
 }
 /**
  * The manifest dependencies this task's refined text actually names — the relevance signal
- * the ranking needs, and the reason the block does not simply list all 21 cited URLs.
+ * the ranking needs, and the reason the block does not simply list every cited URL.
  *
- * WHY NOT extractEnrichTargets. That parser is tuned for the EXTERNAL-DEPENDENCIES section
- * and, run over TASK_0027's refined text, returns ["any", "api", "hc", "package.json",
- * "tsconfig.json", "eslint.config.js"] — and NOT "hono". Ranking off that would drop the one
- * package the task is about while promoting URL noise. The manifest is the authoritative list
- * of what the project actually depends on; matching it against the task text is both
- * deterministic and impossible to fool with prose.
+ * WHY NOT extractEnrichTargets (enrichment.ts). That parser is tuned for the
+ * EXTERNAL-DEPENDENCIES section, so over an ordinary refined text it returns whatever
+ * identifiers and config filenames the prose mentions rather than the packages the task is
+ * about. The manifest is the authoritative list of what the project actually depends on;
+ * matching it against the task text is deterministic and cannot be fooled by prose.
  *
  * Word-boundary matched, so `react` does not match inside `react-dom` or `@types/react`, and
  * a package genuinely named twice is still listed once.

package/dist/task/spec-validation.d.ts

@@ -13,15 +13,15 @@ export declare function parseVerifyBlock(spec: string): VerifyCommand[] | null;
 /**
  * parseVerifyBlock, but only when the fenced block is actually CLOSED.
  *
- * An unterminated fence makes the lenient parser swallow the rest of the file:
- * mx5 run 19's `TASK_0001.md` opens ```sh and never closes it, so its "VERIFY
- * commands" include the phase-timings table and every appended gate-trail line.
+ * An unterminated fence makes the lenient parser swallow the rest of the file: a
+ * task file that opens ```sh and never closes it yields "VERIFY commands" that
+ * include every line appended after the spec — a timings table, a gate-trail line.
  * That is harmless where the parser only asks "is there something runnable here",
- * and NOT harmless where a parsed line is treated as provenance — a debt reason
- * quoting `bun run lint` would match a gate-trail sentence and mint a stored,
+ * and NOT harmless where a parsed line is treated as PROVENANCE: a debt reason
+ * quoting `bun run lint` would then match a trail sentence and mint a stored,
  * re-runnable command the spec never asked for (accept-debt.ts
- * verifyCommandFromReason, `inv-command-provenance`). Callers that need the block
- * to MEAN something use this one: an unclosed fence is no block at all.
+ * `verifyCommandFromReason`, `inv-command-provenance`). Callers that need the
+ * block to MEAN something use this one: an unclosed fence is no block at all.
  */
 export declare function parseVerifyBlockStrict(spec: string): VerifyCommand[] | null;
 export declare function isCritiqueClean(text: string): boolean;
@@ -40,24 +40,21 @@ export declare const REFINE_SECTIONS: readonly ["GOAL", "CONSTRAINTS", "KNOWN-UN
 /**
  * Is a refine child's output shaped like a refined prompt?
  *
- * Refine shipped with NO shape check at all — `phaseRefine` passes no validator,
- * unlike compose and critique — and every downstream reader of a refined prompt
- * is a PARTIAL parser that tolerates a missing section SILENTLY:
- * `extractCapsSection` (refuted-constraint.ts) returns null, `scopedToolingGoal`
- * (phases.ts) returns the whole text, `deriveTitle` and `extractEnrichTargets`
- * fall back. So a refine answer that dropped a heading degrades four features at
- * once and says nothing. This names the contract in one place.
+ * Every downstream reader of a refined prompt is a PARTIAL parser that tolerates a
+ * missing section SILENTLY: `extractCapsSection` (refuted-constraint.ts) returns
+ * null, `scopedToolingGoal` (phases.ts) returns the whole text, and `deriveTitle`
+ * (parsers.ts) and `extractEnrichTargets` (enrichment.ts) fall back. So a refine
+ * answer that dropped a heading degrades four features at once and says nothing.
+ * This names the contract in one place; phases.ts calls it after refine.
  *
  * WHAT IT CHECKS, and why it is only this. Every one of those consumers looks
  * for a BARE ALL-CAPS heading alone on its own line — `l.trim() === heading`,
  * `/^GOAL[ \t]*\n/m`. That is the operative contract, so that is the test.
  *
- * It does NOT require the text to START with GOAL, even though REFINE_PROMPT
- * says "four sections, exact headings, in this order" and forbids a preamble.
- * Measured over the 57-task mx5 corpus: 55/56 non-empty refined prompts carry
- * all four bare headings, but only 25/56 open with one — a preamble is what real
- * refine output usually looks like, and production has always consumed it fine.
- * A validator stricter than its consumers would reject work that works.
+ * It does NOT require the text to START with GOAL, even though REFINE_PROMPT asks
+ * for the four headings in order and forbids a preamble. None of the four
+ * consumers above cares where the heading sits, so a validator that did would
+ * reject work every one of them handles.
  *
  * Returns a problem string, or null when the shape is good — same contract as
  * `validateSpecShape` above.