@mjasnikovs/pi-task 0.18.49 → 0.18.51

package/dist/task/phases.js

@@ -12,6 +12,8 @@ import { search as defaultSearch } from '../workers/search-core.js';
 import { extractEnrichTargets } from './enrichment.js';
 import { isIntegrationUnknown } from './unknown-routing.js';
 import { extractUserDirectives, preserveDirectivesBlock, enforceDirectives } from './user-directives.js';
+import { demoteUnsourcedAttributions } from './context-attribution.js';
+import { classifyContextSilence, countBullets } from './context-silence.js';
 import { getFileInventory } from './file-inventory.js';
 import { buildOrientation, orientationTier } from './orientation.js';
 import { getConfig } from '../config/config.js';
@@ -328,6 +330,54 @@ export function degradedSectionBody(name, reason, partial) {
     const body = partial.trim();
     return body.length > 0 ? `${marker}\n\n${body}` : marker;
 }
+/**
+ * Dependency names declared by the project manifest, used by the CONTEXT post-check to
+ * tell "this bullet is about an external library" from "this bullet is about our source".
+ * A missing or malformed package.json yields none, which makes the post-check a no-op
+ * rather than an error — a non-node project must still be able to run research.
+ */
+async function manifestDependencyNames(cwd) {
+    try {
+        const raw = await readFile(resolve(cwd, 'package.json'), 'utf8');
+        const pkg = JSON.parse(raw);
+        return [...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.devDependencies ?? {})];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Prepended to worker:apis's prompt on the ONE retry the zero-retrieval gate triggers. It
+ * names the exact failure (a section written with no retrieval) so the correction is concrete,
+ * and bounds the retrieval to the symbols about to be listed — a broad "read everything" here
+ * would trade the memory-written section for the 37-read near-runaway at phases.ts's read tail.
+ */
+const APIS_ZERO_RETRIEVAL_PREAMBLE = 'STOP. Your previous attempt at this task wrote a complete APIS section without calling a '
+    + 'single retrieval tool — so every signature, type, and command in it was recalled from '
+    + 'memory, unverified, and must not be trusted. This time you MUST verify before you write: '
+    + 'call `pi-worker-docs` for each third-party package and each project symbol you are about '
+    + 'to list (or `read`/`grep` the project source for project symbols), and write each entry '
+    + 'from what the tool actually returned, not from memory. Look up only the symbols you will '
+    + 'list — no more, no less; do not read the whole tree.';
+/**
+ * Prepended to worker:context's prompt on the ONE retry the silent-retry gate triggers. The
+ * previous attempt produced ZERO bullets — STEP 0 (context-silence.ts) showed every such rep
+ * across 48 live reps was a genuine loss (a loop-degrade or a hallucinated non-bullet
+ * fragment), never a legitimate empty answer, because the same tree reliably yields 11–21
+ * bullets. So this names that failure and steers away from the two shapes that caused it:
+ * the repeated-grep thrash that trips the loop-killer, and emitting anything that is not a
+ * bullet. It does NOT loosen the sourced-bullet invariant — it explicitly repeats that
+ * external-API semantics stay open questions unless quoted.
+ */
+const CONTEXT_SILENT_RETRY_PREAMBLE = 'STOP. Your previous attempt at this task produced ZERO usable bullets — either it thrashed '
+    + 'the same search until it was killed, or it emitted text that was not a bullet list. That is '
+    + 'a dropped section, not an empty one: this repository has architecture worth surfacing. This '
+    + 'time, read a few key files (package.json, the entry point, the directory the task names), do '
+    + 'NOT repeat an identical grep — if a search returns nothing, move on rather than retrying it, '
+    + 'and once you have read enough, WRITE the bullet list and stop. Output ONLY `- <bullet>` lines, '
+    + 'nothing else. Keep the same rules as before: state an external library/API behaviour as fact '
+    + 'ONLY when quoting an EXTERNAL CONTEXT block; otherwise write it as an "unverified:" open '
+    + 'question. One claim per bullet. Better to emit three sharp sourced bullets than to say nothing.';
 export async function phaseResearch(deps, refined, researchDeps = {}) {
     const fileInventoryFn = researchDeps.getFileInventory ?? getFileInventory;
     const externalContext = await gatherExternalContext(refined, deps, researchDeps);
@@ -370,6 +420,18 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
         deps.logDebug?.(`orientation: pre-supplied ${orientation.supplied.size} core files`);
     }
     const promptHeader = externalContext + inventoryHeader;
+    // Braces for the CONTEXT worker's LIVE-DATA RULE (the belt is the prompt itself).
+    // Judged against the EXTERNAL CONTEXT this run actually gathered — the same string
+    // the worker is handed below — and the manifest's dependency names.
+    const manifestPackages = await manifestDependencyNames(deps.cwd);
+    // PROMPT 4's spec-cited-URL lever is NOT WIRED HERE. It is built and unit-tested in
+    // ./spec-urls.ts and its live A/B FAILED: baseline 2/20 vs treatment 3/20, Fisher
+    // one-tailed p = 0.50, over two fixtures, with delivery into this very prompt proven
+    // separately (scripts/spec-url-prompt-delivery-check.ts). Shipping it anyway would put
+    // ~1000 characters of prefill into every APIS prompt for no measured benefit, which is
+    // the pattern nexxtasks exists to prevent. To re-run the experiment, restore the block
+    // this comment replaces — see the git history of this file and the PROMPT 4 entry in
+    // nexxtasks.txt RESULTS.
     let doneCount = 0;
     const updateProgress = () => {
         doneCount++;
@@ -433,7 +495,30 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             extensions: [
                 DOCS_EXTENSION_PATH,
                 ...(searchConfigured() ? [SEARCH_EXTENSION_PATH] : [])
-            ]
+            ],
+            // ZERO-RETRIEVAL GATE (mx5 run-15 F-1, distinct from the STAGE 1-3 stopping-point
+            // thread). In a MINORITY of reps worker:apis emits a complete, plausible APIS section
+            // having made ZERO retrieval tool calls — the whole thing recalled from memory.
+            // The output contract at RESEARCH_APIS_PROMPT already INSTRUCTS tool use and the
+            // worker skips it anyway (STAGE 2 proved a prompt line does not move grounding), so
+            // this is a deterministic gate, not another instruction: groundingRetrievalCount === 0
+            // on a non-empty section is ungrounded BY CONSTRUCTION — no semantic judgement, the
+            // exact checkable handle STAGE 3's prose-clause gate lacked. The forced-retrieval
+            // retry recovers a grounded section rather than silencing the worker (entry count
+            // preserved). It bounds itself ("look up the symbols you will list — no more") away
+            // from the near-runaway 37-read tail.
+            //
+            // EFFICACY NOT DEMONSTRATED — read before trusting this to matter. The live A/B
+            // (scripts/live-apis-zero-retrieval-ab.ts) ABSTAINED, underpowered: the failure is
+            // RARE and intermittent (base rate 0/40 one session, pooled ~5%), so the primary
+            // reduction (baseline 1/40 zero-retrieval ships -> treatment 0/40) did NOT reach
+            // significance (Fisher p = 0.50 — needs ~5 baseline ships, ~85 reps at ~6%). What IS
+            // established: the gate is correct BY CONSTRUCTION; on the 3 firings observed it
+            // recovered a grounded section every time; and it did NO harm (ungrounded-symbol rate
+            // went DOWN not up, no entry collapse, no runaway, cost +4-6%). It is wired as a
+            // harmless safety net, NOT a proven-effective lever — do not cite it as a measured win
+            // (nexxtasks.txt "ZERO-RETRIEVAL GATE ... ABSTAIN"). A powered A/B is STILL OPEN.
+            zeroRetrievalRetry: APIS_ZERO_RETRIEVAL_PREAMBLE
         },
         {
             section: 'CONTEXT',
@@ -443,7 +528,40 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             // FILES handles that. Dropping `find`/`ls` keeps the worker from
             // spawning long enumeration loops whose output then inflates
             // prefill on every subsequent round.
-            tools: 'read,grep'
+            //
+            // RECORDED DECISION (mx5 run-15 F-1, PROMPT 1 item 4): this worker stays
+            // ISOLATED — it is NOT given the APIS worker's output. It keeps `read,grep`
+            // and is forbidden, by prompt and by the post-check below, from asserting
+            // external-API behaviour it cannot see. Handing it the APIS section would
+            // widen what it may assert without making any of it checkable here, and
+            // APIS' own answers are the ones F-2 shows are type-only and unverified.
+            tools: 'read,grep',
+            // SILENT-RETRY GATE. STEP 0 measured this worker silent (zero bullets) in ~10%
+            // of live reps (5/48, Wilson95 [4.5%, 22.2%]) and classified EVERY silent rep as
+            // a genuine loss — a loop-degrade banner (60%) or a hallucinated non-bullet
+            // fragment (40%) — never a legitimate empty answer, because the identical fixture
+            // reliably yields 11–21 bullets. A silent section is therefore a dropped section;
+            // retry once, keep the retry only if it emits bullets. See context-silence.ts.
+            retryIfSilent: CONTEXT_SILENT_RETRY_PREAMBLE,
+            // BRACES for the LIVE-DATA RULE. In run 15 this worker wrote, verbatim, "The
+            // `hono` dependency is pinned at `^4.12.31` in package.json, and the external
+            // context confirms `hc<AppType>` pattern with base URL `/api` ... works
+            // correctly (per Hono RPC docs LIVE data)". It has read+grep only, so the
+            // base-URL half came from memory; fused with the true version half under one
+            // attribution it read as sourced, became a hard requirement in TASK_0027's
+            // CONSTRAINTS and ACCEPTANCE, and every request went to /api/api/... ⇒ 404.
+            // A flagged bullet is demoted to an OPEN QUESTION here — before the section is
+            // persisted — so it cannot reach compose as fact. Demotion, not deletion: the
+            // bullet count is preserved, because a silenced worker is a different
+            // regression.
+            postProcess: text => {
+                const r = demoteUnsourcedAttributions(text, externalContext, manifestPackages);
+                for (const f of r.demoted) {
+                    deps.logDebug?.(`worker:context: demoted unsourced attribution [${f.unsourced.join(',')}]`
+                        + ` cue="${f.cue}" — ${f.bullet.slice(0, 160)}`);
+                }
+                return r.text;
+            }
         },
         {
             section: 'TOOLING',
@@ -484,8 +602,9 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             return { name: spec.section, text: cached.trim() };
         }
         deps.logDebug?.(`${spec.label}: start`);
-        const r = await recordWorker(spec.label, runWorker({
-            prompt: typeof spec.prompt === 'function' ? spec.prompt(prior) : spec.prompt,
+        const basePrompt = typeof spec.prompt === 'function' ? spec.prompt(prior) : spec.prompt;
+        const runOnce = (extraPreamble) => recordWorker(spec.label, runWorker({
+            prompt: extraPreamble ? `${extraPreamble}\n\n${basePrompt}` : basePrompt,
             cwd: deps.cwd,
             signal: deps.signal,
             spawn: deps.spawn,
@@ -496,6 +615,65 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
                 deps.onChildOutput?.(`${spec.label}: ${line}`);
             }
         }));
+        let r = await runOnce();
+        // ZERO-RETRIEVAL GATE — a deterministic handle, not another instruction. A non-empty
+        // section produced with no grounding-retrieval call was written from memory; retry ONCE
+        // with a forced retrieval-first pass and keep the retry only if it actually retrieved.
+        if (spec.zeroRetrievalRetry
+            && r.groundingRetrievalCount === 0
+            && r.text.trim().length > 0) {
+            deps.logDebug?.(`${spec.label}: ZERO grounding-retrieval on a non-empty section`
+                + ' — every symbol is unverified memory; re-running once with a forced'
+                + ' retrieval-first pass');
+            deps.onChildOutput?.(`${spec.label}: zero-retrieval — retrying with forced retrieval`);
+            const retry = await runOnce(spec.zeroRetrievalRetry);
+            if (retry.groundingRetrievalCount > 0 && retry.text.trim().length > 0) {
+                deps.logDebug?.(`${spec.label}: retry grounded (${retry.groundingRetrievalCount} retrieval`
+                    + ' calls) — replacing the memory-written section');
+                r = retry;
+            }
+            else {
+                deps.logDebug?.(`${spec.label}: retry STILL zero-retrieval`
+                    + ` (calls=${retry.groundingRetrievalCount}, len=${retry.text.trim().length})`
+                    + ' — keeping the original (no regression, entry count preserved)');
+            }
+        }
+        // SILENT-RETRY GATE — a deterministic handle over the section body, not another
+        // instruction. A section that parses to ZERO bullets from a loop-degrade banner or a
+        // hallucinated non-bullet fragment (classifyContextSilence → genuineLoss) dropped
+        // context that was there to surface; retry ONCE with a forced-emit preamble and keep
+        // the retry only if it produces bullets. A legitimately-empty section (an honest
+        // "nothing to surface") and a fatal failure are BOTH left alone — the former is not a
+        // loss, the latter throws below and must stay a loud failure, not a silent retry.
+        const silentBodyOf = (res) => {
+            const f = classifyResearchWorker(spec.section, res);
+            if (f?.kind === 'fatal')
+                return null;
+            return f?.kind === 'runaway' ?
+                degradedSectionBody(spec.section, f.reason, res.text)
+                : res.text.trim();
+        };
+        if (spec.retryIfSilent) {
+            const body = silentBodyOf(r);
+            const verdict = body === null ? null : classifyContextSilence(body);
+            if (verdict?.silent && verdict.genuineLoss) {
+                deps.logDebug?.(`${spec.label}: silent-retry first-silent cause=${verdict.cause}`
+                    + ` — zero bullets, re-running once with a forced-emit preamble`);
+                deps.onChildOutput?.(`${spec.label}: silent — retrying`);
+                const retry = await runOnce(spec.retryIfSilent);
+                const retryBody = silentBodyOf(retry);
+                const retryBullets = retryBody === null ? 0 : countBullets(retryBody);
+                if (retryBullets > 0) {
+                    deps.logDebug?.(`${spec.label}: silent-retry recovered bullets=${retryBullets}`
+                        + ' — replacing the silent section');
+                    r = retry;
+                }
+                else {
+                    deps.logDebug?.(`${spec.label}: silent-retry still-silent`
+                        + ` (bullets=${retryBullets}) — keeping the original`);
+                }
+            }
+        }
         deps.logDebug?.(`${spec.label}: done exit=${r.exitCode} wait=${r.waitMs}ms work=${r.workMs}ms`
             + (r.stderr ? ` stderr=${r.stderr.slice(0, 300)}` : '')
             + (r.leakedToolCall ? ` leaked=${r.leakedToolCall.trim().slice(0, 80)}` : ''));
@@ -503,12 +681,16 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
         const failure = classifyResearchWorker(spec.section, r);
         if (failure?.kind === 'fatal')
             throw failure.error;
-        const sectionText = failure?.kind === 'runaway' ?
+        const rawText = failure?.kind === 'runaway' ?
             degradedSectionBody(spec.section, failure.reason, r.text)
             : r.text.trim();
         if (failure?.kind === 'runaway') {
             deps.logDebug?.(`${spec.label}: degraded — ${failure.reason}`);
         }
+        // Post-check the worker's own output before it is persisted, so the cache a
+        // resume reads back is already gated. A degraded partial goes through it too —
+        // a truncated section can still carry a laundered claim.
+        const sectionText = spec.postProcess ? spec.postProcess(rawText) : rawText;
         await persistSection(cacheHeading, sectionText);
         return { name: spec.section, text: sectionText };
     };

package/dist/task/prompts.js

@@ -153,6 +153,17 @@ No section header. No other sections. No preamble.
 
 Task:
 ${refined}`;
+// STAGE 2 (2026-07-23): APIS_SEMANTICS_CONTRACT was wired in above and UNWIRED after its A/B
+// FAILED. It is the ONE lever of three that moved worker:apis's behaviour — behaviour-class
+// package queries 20/20 vs 2/20, Fisher p ≈ 0 — confirming Stage 1's mechanism (completion is
+// set by the output CONTRACT, not the answer or the target). But it failed invariant 2a: the
+// ungrounded-symbol rate rose 1.0% -> 4.7% (p(rise) = 0.0010) and the semantics clause it adds
+// carried 15% ungrounded symbols with the mandatory `UNVERIFIED:` abstention used 0 times in 40
+// reps. The model obeys "ask a behaviour question" and ignores "abstain when you cannot verify",
+// so it manufactures semantics — the exact F-1 laundering the file exists to prevent. The module
+// and its tests are KEPT as the durable asset (like spec-urls.ts after PROMPT 4); only this
+// interpolation is reverted. Full write-up: nexxtasks.txt "STAGE 2". Re-run: scripts/
+// live-apis-contract-ab.ts. Do NOT re-wire without a lever that closes the abstention gap.
 const RESEARCH_CONTEXT_PROMPT = (refined) => `You are doing targeted research for an AI coding agent. Use the read, grep, find, and ls tools to gather background knowledge and architectural context the agent will need for the following task.
 
 RELEVANCE — read carefully: keep it tight. Each bullet must be an architectural fact that changes HOW the agent implements THIS task — a constraint, a non-obvious data flow, a gotcha, a hidden coupling. No general project tour, no restating the task, no facts the agent would not act on. If a bullet would not change a single implementation decision, drop it. There is no fixed bullet count — include every fact that bears on the task and no filler; fewer sharp bullets beat many shallow ones. If the task is itself an analysis or review, these bullets capture facts that analysis will rely on — they are NOT the analysis; do not write findings or recommendations here.
@@ -166,6 +177,8 @@ LIVE-DATA RULE:
 - If EXTERNAL CONTEXT contains a "### service: <name>" block, those search results are LIVE web data and are authoritative over training data for that service's current API surface, deprecation status, and replacement systems. Do not contradict them from memory. If you must cite a version, status, or API name for that service, take it from the block.
 - If EXTERNAL CONTEXT contains a "### freshness-check skipped" block, you have no current data for the listed services. Do NOT claim their current state from memory; say "current state not verified" and recommend the user verify before implementation.
 - Do NOT write bullets like "X is the latest stable" or "version Y is current" from memory — your training data goes stale. Either quote from EXTERNAL CONTEXT or omit the claim entirely.
+- API USAGE SEMANTICS — how an external library's function is called, what one of its parameters MEANS, what value it defaults to, what it returns, or what behaviour results — is the same kind of claim. You have read and grep only: you CANNOT open any documentation, so you have no way to check it. State such a claim ONLY when you are quoting a block that is actually present in EXTERNAL CONTEXT, and quote the wording you are relying on. Otherwise write it as an open question — "unverified: does hc's base URL argument mean an origin or a mount prefix?" — never as a fact. A version number in an "### npm:" block tells you NOTHING about how the API behaves; it cannot support a semantics claim.
+- ONE CLAIM PER BULLET. Never fuse a sourced fact and an unsourced claim into one sentence under one attribution — a true half does not make the other half true, and the reader cannot tell which half was checked. If you write "package X is pinned at 1.2.3 AND <how its API behaves>", split it: keep the pinned version as its own bullet, and write the behaviour as its own bullet, marked as an open question unless you are quoting EXTERNAL CONTEXT.
 
 Output ONLY the content of a CONTEXT section — bullet list, one bullet per line, format:
   - <bullet>

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

@@ -0,0 +1,117 @@
+/**
+ * PROMPT 4 / F-2(b) — 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.
+ *
+ * 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; 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.
+ */
+/**
+ * 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.
+ */
+export declare const MAX_SPEC_URLS = 8;
+/** http(s) URLs in a text, deduped, with local and placeholder hosts dropped. */
+export declare function extractSpecUrls(text: string): string[];
+/**
+ * Tokens of a package specifier that could plausibly appear in its documentation URL: the
+ * root name plus every scope/path/hyphen segment. `hono/client` ⇒ {hono, client};
+ * `@hono/zod-validator` ⇒ {hono, zod, validator, zod-validator}. Segments of TWO characters or
+ * fewer are dropped — `pg` would match half the documentation web. Three is the floor rather
+ * than four because `zod` is a real dependency with a real cited page (zod.dev), and a rule
+ * that silently drops it is a rule that silently drops reach.
+ */
+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.
+ */
+export declare function urlDocumentsPackage(url: string, pkg: string): boolean;
+export interface RankedSpecUrl {
+    url: string;
+    /** The packages this URL documents, in the order they were supplied. */
+    packages: string[];
+}
+/**
+ * Cited URLs that document a package this task touches, most relevant first.
+ *
+ * `packages` is ordered by relevance by the CALLER — the task's own named dependencies
+ * before the rest of the manifest — and a URL inherits the rank of the earliest package it
+ * documents. A URL documenting no supplied package is dropped entirely rather than ranked
+ * last: the design cites pages for the whole project, and a task about the router has no use
+ * for the image-processing reference.
+ */
+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.
+ *
+ * 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.
+ *
+ * Word-boundary matched, so `react` does not match inside `react-dom` or `@types/react`, and
+ * a package genuinely named twice is still listed once.
+ */
+export declare function mentionedPackages(refined: string, manifest: string[]): string[];

package/dist/task/spec-urls.js

@@ -0,0 +1,214 @@
+/**
+ * PROMPT 4 / F-2(b) — 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.
+ *
+ * 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; 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.
+ */
+/** 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.
+ */
+export const MAX_SPEC_URLS = 8;
+/** http(s) URLs in a text, deduped, with local and placeholder hosts dropped. */
+export function extractSpecUrls(text) {
+    const out = [];
+    const seen = new Set();
+    for (const raw of text.match(/https?:\/\/[^\s)>`"']+/g) ?? []) {
+        // Trailing sentence punctuation is not part of the URL; a #fragment and a query are.
+        const url = raw.replace(/[.,;:]+$/, '');
+        if (seen.has(url))
+            continue;
+        let host;
+        try {
+            host = new URL(url).hostname;
+        }
+        catch {
+            continue;
+        }
+        if (LOCAL_HOST.test(host) || PLACEHOLDER_HOST.test(host))
+            continue;
+        seen.add(url);
+        out.push(url);
+    }
+    return out;
+}
+/**
+ * Tokens of a package specifier that could plausibly appear in its documentation URL: the
+ * root name plus every scope/path/hyphen segment. `hono/client` ⇒ {hono, client};
+ * `@hono/zod-validator` ⇒ {hono, zod, validator, zod-validator}. Segments of TWO characters or
+ * fewer are dropped — `pg` would match half the documentation web. Three is the floor rather
+ * than four because `zod` is a real dependency with a real cited page (zod.dev), and a rule
+ * that silently drops it is a rule that silently drops reach.
+ */
+export function packageTokens(pkg) {
+    const m = pkg.toLowerCase().trim();
+    if (m === '.' || m.length === 0)
+        return [];
+    const out = new Set();
+    for (const seg of m.split('/').filter(Boolean)) {
+        const bare = seg.replace(/^@/, '');
+        if (bare.length > 2)
+            out.add(bare);
+        for (const part of bare.split('-'))
+            if (part.length > 2)
+                out.add(part);
+    }
+    return [...out];
+}
+/**
+ * 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.
+ */
+export function urlDocumentsPackage(url, pkg) {
+    const toks = packageTokens(pkg);
+    if (toks.length === 0)
+        return false;
+    let scope;
+    try {
+        const u = new URL(url);
+        scope = `${u.hostname} ${u.pathname}`;
+    }
+    catch {
+        return false;
+    }
+    const inUrl = new Set(scope
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean));
+    return toks.some(t => inUrl.has(t));
+}
+/**
+ * Cited URLs that document a package this task touches, most relevant first.
+ *
+ * `packages` is ordered by relevance by the CALLER — the task's own named dependencies
+ * before the rest of the manifest — and a URL inherits the rank of the earliest package it
+ * documents. A URL documenting no supplied package is dropped entirely rather than ranked
+ * last: the design cites pages for the whole project, and a task about the router has no use
+ * for the image-processing reference.
+ */
+export function rankSpecUrls(urls, packages) {
+    const ranked = [];
+    for (const url of urls) {
+        const matched = packages.filter(p => urlDocumentsPackage(url, p));
+        if (matched.length === 0)
+            continue;
+        ranked.push({ r: { url, packages: matched }, rank: packages.indexOf(matched[0]) });
+    }
+    ranked.sort((a, b) => a.rank - b.rank || a.r.url.localeCompare(b.r.url));
+    return ranked.slice(0, MAX_SPEC_URLS).map(x => x.r);
+}
+/**
+ * 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);
+    if (ranked.length === 0)
+        return '';
+    // Grouped under the package rather than one package-name-per-URL: five consecutive lines
+    // reading "hono" is the shape a reader — and a small model — skims past, and the grouping
+    // is also what makes the ranking legible as a ranking.
+    const byPackage = new Map();
+    for (const r of ranked) {
+        const key = r.packages[0];
+        byPackage.set(key, [...(byPackage.get(key) ?? []), r.url]);
+    }
+    const rows = [...byPackage]
+        .map(([pkg, us]) => `  ${pkg}\n${us.map(u => `      ${u}`).join('\n')}`)
+        .join('\n');
+    return ("SPEC-CITED DOCUMENTATION — this project's own design document names these pages, by "
+        + "URL, for packages this task uses. They are the project's chosen references, so they "
+        + 'OUTRANK any page you would pick from a search result.\n'
+        + 'WHEN TO USE THEM: the moment a `pi-worker-docs` answer for one of these packages '
+        + 'does not actually answer your question — including when it hands you a type '
+        + 'signature instead of behaviour — call `pi-worker-fetch(<the URL below>)` and re-ask '
+        + 'the same question. Do NOT search for a page first, and do NOT fill the gap from '
+        + 'memory.\n'
+        + `${rows}\n`
+        + 'NOT AN ALLOW-LIST: these are ranked first, not exclusive. If your question is about '
+        + 'something these pages do not cover, use pi-worker-search / pi-worker-fetch on '
+        + 'whatever page does.\n\n');
+}
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * Word-boundary matched, so `react` does not match inside `react-dom` or `@types/react`, and
+ * a package genuinely named twice is still listed once.
+ */
+export function mentionedPackages(refined, manifest) {
+    const text = refined.toLowerCase();
+    const out = [];
+    for (const dep of manifest) {
+        const d = dep.toLowerCase();
+        const esc = d.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        if (new RegExp(`(^|[^a-z0-9@/._-])${esc}([^a-z0-9-]|$)`, 'i').test(text))
+            out.push(dep);
+    }
+    return out;
+}