@mjasnikovs/pi-task 0.18.49 → 0.18.50

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;
+}

package/dist/task/type-only-answer.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Deterministic detector for the F-2 shape: a pi-worker-docs answer that RESTATES a type
+ * signature or declaration for a USAGE question, without ever saying what the API DOES.
+ *
+ * THE FATAL CASE, from mx5 run 15 (research-cache.json, verbatim):
+ *
+ *   query : "hc factory function signature base url parameter types exported from hono/client"
+ *   answer: "The `hc` factory function exported from `hono/client` accepts a generic type
+ *            `T` extending `Hono`, an optional string prefix type `Prefix` (defaulting to
+ *            `string`), and takes two parameters: `baseUrl` of type `Prefix` and an optional
+ *            `options` of type `ClientRequestOptions`. It returns a
+ *            `UnionToIntersection<Client<T, Prefix>>`."
+ *
+ * Every clause is type-level. "`baseUrl` of type `Prefix`" names the parameter's TYPE — and
+ * `Prefix` is itself an opaque type variable — while saying nothing about what `baseUrl`
+ * MEANS (is it an origin, or a mount prefix?). Escalation to search/fetch never fired
+ * because the answer looked complete: it named the very parameter asked about. worker:context
+ * then filled the semantic gap from memory and shipped `hc<AppType>('/api')`, so every request
+ * went to `/api/api/...` ⇒ 404 ⇒ the product's entire API surface was dead (F-2 → F-1).
+ *
+ * The lever (PROMPT 2 DO item 1): when a docs answer for a usage question is ONLY a
+ * signature/declaration restatement with no behavioural statement, treat it as UNANSWERED so
+ * the caller escalates (follow the `@see` pointer / fetch the spec-cited URL) instead of
+ * accepting a type as the answer.
+ *
+ * ── PRECISION/RECALL TRADEOFF (chosen deliberately; documented per the task) ────────────────
+ * A FALSE POSITIVE here (flagging a real answer as type-only) forces a needless escalation:
+ * wall-clock cost against PROMPT 2 invariant 1, which caps added child spawns. A false
+ * NEGATIVE (missing a type-only answer) merely leaves the pre-existing bug unfixed for that
+ * one borderline case. So this detector is tuned for HIGH PRECISION on real answers, accepting
+ * low recall — "better to miss a borderline type-only answer than to flag a real one." Three
+ * independent gates must ALL hold before an answer is called type-only; any one failing clears
+ * it. Calibrated against the run-15 corpus: of the 149 valid (non-"unclear") pi-worker-docs
+ * answers, this rule flags EXACTLY ONE — the recorded `hc` case — and clears the other 148,
+ * including every legitimate signature answer to an explicit "give me the type/signature"
+ * question (bun.password.hash, toBuffer, BuildOutput, …). See type-only-answer.test.ts.
+ *
+ * THE THREE GATES (all required):
+ *   1. USAGE QUESTION. The question must seek usage/semantics — "how", "use", "work", "chain",
+ *      "example", "call", "rpc", "mean", or it names a usage concept whose meaning is being
+ *      sought ("base url"). A question that asks only for a TYPE / SIGNATURE / DEFINITION /
+ *      FIELDS is legitimately answered by a signature, so it is NOT gated in. (The recorded hc
+ *      query is signature-shaped but names "base url", the concept whose meaning was needed.)
+ *   2. NO BEHAVIOURAL CONTENT IN PROSE. The answer must contain no statement of what the API
+ *      DOES: no usage verb ("use/call/pass/import"), no runtime-effect verb ("executes/
+ *      prepends/enables/wraps"), no concrete usage example, no semantic meaning ("means/
+ *      represents/so pass"), no concrete default VALUE or value RANGE ("default of 80", "from
+ *      1 to 100"). Any one clears. This scan runs over `proseOf(answer)`, NOT the raw answer:
+ *      a verb that is really a method name inside a declaration ("methods route(url, handler)
+ *      and use(...handlers)") is an identifier, not behaviour, and must not clear the answer.
+ *   3. SIGNATURE RESTATEMENT. The answer must actually be a declaration/signature restatement —
+ *      "of type", "takes N parameters", "accepts", "returns a…", "extends", "interface",
+ *      "declare const/function". Without this it is not type-only, it is just terse prose.
+ *
+ * An explicit "unclear from this package/page" is NOT type-only — it is the HONEST non-answer,
+ * already handled by the escalation path (PROMPT 2 DO item 2 escalates BOTH). It is cleared
+ * here with a distinct reason so the caller can route it through the existing unclear channel.
+ *
+ * Pure and side-effect free; unit-tested in type-only-answer.test.ts against real run-15 text.
+ */
+/** The verdict, with a human-readable reason for logging and for the escalation channel. */
+export interface TypeOnlyVerdict {
+    /** True iff the answer restates a signature for a usage question with no behaviour. */
+    typeOnly: boolean;
+    /** Why — names the gate that decided it, quoting the matched marker where useful. */
+    reason: string;
+}
+/**
+ * Strip signature/declaration fragments so the behavioural scan sees only PROSE.
+ *
+ * A behavioural verb is a signal ONLY when it is a verb in prose ("the base URL is
+ * prepended", "you use X to Y"), NEVER when it is a method/identifier token inside a
+ * declaration. Without this, a bare type-only answer like
+ *   "It has methods route(url, handler) and use(...handlers)."
+ * is wrongly cleared, because `use(...handlers)` matches /\buse\b/ and `handler` matches
+ * /handle/ — the F-3(a) router-fixture shape. So before scanning for behaviour we remove:
+ *   - `name(args)` call fragments, whose args are identifiers, not prose (this is what
+ *     carries the method-name verbs);
+ *   - `declare const|function|module|class|namespace …` declaration lines.
+ * The SIGNATURE gate still runs against the ORIGINAL answer, so stripping never weakens
+ * gate 3 — it only prevents an identifier inside a signature from masquerading as prose.
+ * Deliberately conservative: it does NOT strip `: Type` annotations or backtick spans,
+ * because a colon or backtick often precedes real behavioural prose ("Usage: call …",
+ * "`sql` is prepended …"), and removing those would silently drop behaviour and MANUFACTURE
+ * false positives — worse than the recall gap this fixes.
+ */
+export declare function proseOf(answer: string): string;
+/**
+ * Decide whether a pi-worker-docs `answer` to `question` is type-only — a signature/declaration
+ * restatement with no behavioural statement, for a question that needed usage semantics.
+ *
+ * @param answer   the child's <answer> prose (NOT the version banner or the source excerpt).
+ * @param question the query the answer was produced for.
+ */
+export declare function isTypeOnlyAnswer(answer: string, question: string): TypeOnlyVerdict;

package/dist/task/type-only-answer.js

@@ -0,0 +1,249 @@
+/**
+ * Deterministic detector for the F-2 shape: a pi-worker-docs answer that RESTATES a type
+ * signature or declaration for a USAGE question, without ever saying what the API DOES.
+ *
+ * THE FATAL CASE, from mx5 run 15 (research-cache.json, verbatim):
+ *
+ *   query : "hc factory function signature base url parameter types exported from hono/client"
+ *   answer: "The `hc` factory function exported from `hono/client` accepts a generic type
+ *            `T` extending `Hono`, an optional string prefix type `Prefix` (defaulting to
+ *            `string`), and takes two parameters: `baseUrl` of type `Prefix` and an optional
+ *            `options` of type `ClientRequestOptions`. It returns a
+ *            `UnionToIntersection<Client<T, Prefix>>`."
+ *
+ * Every clause is type-level. "`baseUrl` of type `Prefix`" names the parameter's TYPE — and
+ * `Prefix` is itself an opaque type variable — while saying nothing about what `baseUrl`
+ * MEANS (is it an origin, or a mount prefix?). Escalation to search/fetch never fired
+ * because the answer looked complete: it named the very parameter asked about. worker:context
+ * then filled the semantic gap from memory and shipped `hc<AppType>('/api')`, so every request
+ * went to `/api/api/...` ⇒ 404 ⇒ the product's entire API surface was dead (F-2 → F-1).
+ *
+ * The lever (PROMPT 2 DO item 1): when a docs answer for a usage question is ONLY a
+ * signature/declaration restatement with no behavioural statement, treat it as UNANSWERED so
+ * the caller escalates (follow the `@see` pointer / fetch the spec-cited URL) instead of
+ * accepting a type as the answer.
+ *
+ * ── PRECISION/RECALL TRADEOFF (chosen deliberately; documented per the task) ────────────────
+ * A FALSE POSITIVE here (flagging a real answer as type-only) forces a needless escalation:
+ * wall-clock cost against PROMPT 2 invariant 1, which caps added child spawns. A false
+ * NEGATIVE (missing a type-only answer) merely leaves the pre-existing bug unfixed for that
+ * one borderline case. So this detector is tuned for HIGH PRECISION on real answers, accepting
+ * low recall — "better to miss a borderline type-only answer than to flag a real one." Three
+ * independent gates must ALL hold before an answer is called type-only; any one failing clears
+ * it. Calibrated against the run-15 corpus: of the 149 valid (non-"unclear") pi-worker-docs
+ * answers, this rule flags EXACTLY ONE — the recorded `hc` case — and clears the other 148,
+ * including every legitimate signature answer to an explicit "give me the type/signature"
+ * question (bun.password.hash, toBuffer, BuildOutput, …). See type-only-answer.test.ts.
+ *
+ * THE THREE GATES (all required):
+ *   1. USAGE QUESTION. The question must seek usage/semantics — "how", "use", "work", "chain",
+ *      "example", "call", "rpc", "mean", or it names a usage concept whose meaning is being
+ *      sought ("base url"). A question that asks only for a TYPE / SIGNATURE / DEFINITION /
+ *      FIELDS is legitimately answered by a signature, so it is NOT gated in. (The recorded hc
+ *      query is signature-shaped but names "base url", the concept whose meaning was needed.)
+ *   2. NO BEHAVIOURAL CONTENT IN PROSE. The answer must contain no statement of what the API
+ *      DOES: no usage verb ("use/call/pass/import"), no runtime-effect verb ("executes/
+ *      prepends/enables/wraps"), no concrete usage example, no semantic meaning ("means/
+ *      represents/so pass"), no concrete default VALUE or value RANGE ("default of 80", "from
+ *      1 to 100"). Any one clears. This scan runs over `proseOf(answer)`, NOT the raw answer:
+ *      a verb that is really a method name inside a declaration ("methods route(url, handler)
+ *      and use(...handlers)") is an identifier, not behaviour, and must not clear the answer.
+ *   3. SIGNATURE RESTATEMENT. The answer must actually be a declaration/signature restatement —
+ *      "of type", "takes N parameters", "accepts", "returns a…", "extends", "interface",
+ *      "declare const/function". Without this it is not type-only, it is just terse prose.
+ *
+ * An explicit "unclear from this package/page" is NOT type-only — it is the HONEST non-answer,
+ * already handled by the escalation path (PROMPT 2 DO item 2 escalates BOTH). It is cleared
+ * here with a distinct reason so the caller can route it through the existing unclear channel.
+ *
+ * Pure and side-effect free; unit-tested in type-only-answer.test.ts against real run-15 text.
+ */
+/**
+ * Question seeks usage/semantics rather than a bare type. A usage concept whose MEANING is
+ * being asked about ("base url") counts, because the F-2 defect is exactly a semantics need
+ * dressed in signature words. A question that asks only for the "type"/"signature"/"definition"
+ * is deliberately NOT here — a signature answer is responsive to it.
+ */
+const USAGE_INTENT = [
+    /\bhow\b/i,
+    /\buse\b/i,
+    /\busing\b/i,
+    /\busage\b/i,
+    /\bworks?\b/i,
+    /\bworking\b/i,
+    /\bchain/i,
+    /base\s?url/i,
+    /\bconnect/i,
+    /\brpc\b/i,
+    /\bexample/i,
+    /\bcall\b/i,
+    /\binvoke/i,
+    /\bmean/i,
+    /\bbehav/i,
+    /what\s+does/i,
+    /how\s+does/i
+];
+/**
+ * Markers that the answer says what the API DOES — a usage instruction, a runtime effect, a
+ * concrete example, a meaning, a concrete default value or range. Deliberately GENEROUS: every
+ * extra marker here can only SUPPRESS a flag, which is the safe direction for precision.
+ */
+const BEHAVIOURAL = [
+    /\buse\b/i,
+    /\busing\b/i,
+    /\bcall/i,
+    /\bpass(es|ed|ing)?\b/i,
+    /\bimport/i,
+    /\binstantiate/i,
+    /\bprovide[sd]?\b/i,
+    /\binvoke/i,
+    /\bread\b/i,
+    /\bwrite\b/i,
+    /\bexecut/i,
+    /\bsends?\b/i,
+    /\bprepend/i,
+    /\bappend/i,
+    /\bconnect/i,
+    /\bhandle/i,
+    /\bresolves?\s+to\b/i,
+    /\bstarts?\b/i,
+    /\bspread/i,
+    /\bautomatically\b/i,
+    /\breplac/i,
+    /\benabl/i,
+    /\bdisabl/i,
+    /\bwrap/i,
+    /\bperform/i,
+    /\bmanag/i,
+    /\bcontrol/i,
+    /\baccess/i,
+    /\bcreat/i,
+    /\ballow/i,
+    /\bcontain/i,
+    /\bregister/i,
+    /\bmount/i,
+    /\bnavigat/i,
+    /\btrigger/i,
+    /\bappl(y|ies)/i,
+    /\bmeans\b/i,
+    /\brepresents/i,
+    /so\s+pass/i,
+    /for\s+setup/i,
+    /used\s+to/i,
+    /used\s+for/i,
+    /in\s+order\s+to/i,
+    /for\s+\w+ing\b/i,
+    /e\.g\./i,
+    /for\s+example/i,
+    /default\s+of/i,
+    /defaults?\s+to/i,
+    /with\s+a\s+default/i,
+    /from\s+\d+\s+to\s+\d+/i,
+    /when\s+using/i,
+    /you\s+can/i,
+    /you\s+provide/i,
+    /you\s+get/i,
+    /gives?\s+access/i,
+    /to\s+(enable|perform|run|execute|create|manage|handle)\b/i,
+    /\bconfigur/i,
+    /\bschema/i,
+    /\bvalidat/i
+];
+/** Markers that the answer is a declaration/signature restatement. */
+const SIGNATURE = [
+    /\bof\s+type\b/i,
+    /\btakes?\s+(a|an|two|three|one|four)\b/i,
+    /\baccepts?\b/i,
+    /\breturns?\s+(a|an|`|the|void|Promise|<|\w+<)/i,
+    /\bsignature\s+(is|:)/i,
+    /\bextends\b/i,
+    /\binterface\b/i,
+    /\bgeneric\s+type\b/i,
+    /\boverload/i,
+    /\bparameters?:/i,
+    /\bconstructor\s+accepts/i,
+    /declare\s+(const|function)/i
+];
+/** Explicit non-answer the docs child emits when the package cannot answer. */
+const UNCLEAR = /\bunclear\s+from\s+this\s+(package|page)\b/i;
+function firstMatch(text, patterns) {
+    for (const p of patterns) {
+        const m = p.exec(text);
+        if (m)
+            return m[0];
+    }
+    return null;
+}
+/**
+ * Strip signature/declaration fragments so the behavioural scan sees only PROSE.
+ *
+ * A behavioural verb is a signal ONLY when it is a verb in prose ("the base URL is
+ * prepended", "you use X to Y"), NEVER when it is a method/identifier token inside a
+ * declaration. Without this, a bare type-only answer like
+ *   "It has methods route(url, handler) and use(...handlers)."
+ * is wrongly cleared, because `use(...handlers)` matches /\buse\b/ and `handler` matches
+ * /handle/ — the F-3(a) router-fixture shape. So before scanning for behaviour we remove:
+ *   - `name(args)` call fragments, whose args are identifiers, not prose (this is what
+ *     carries the method-name verbs);
+ *   - `declare const|function|module|class|namespace …` declaration lines.
+ * The SIGNATURE gate still runs against the ORIGINAL answer, so stripping never weakens
+ * gate 3 — it only prevents an identifier inside a signature from masquerading as prose.
+ * Deliberately conservative: it does NOT strip `: Type` annotations or backtick spans,
+ * because a colon or backtick often precedes real behavioural prose ("Usage: call …",
+ * "`sql` is prepended …"), and removing those would silently drop behaviour and MANUFACTURE
+ * false positives — worse than the recall gap this fixes.
+ */
+export function proseOf(answer) {
+    return answer
+        .replace(/[\w$][\w$.]*\s*\([^)]*\)/g, ' ')
+        .replace(/\bdeclare\s+(const|function|module|class|namespace)\b[^.\n]*/gi, ' ')
+        .replace(/\s{2,}/g, ' ')
+        .trim();
+}
+/**
+ * Decide whether a pi-worker-docs `answer` to `question` is type-only — a signature/declaration
+ * restatement with no behavioural statement, for a question that needed usage semantics.
+ *
+ * @param answer   the child's <answer> prose (NOT the version banner or the source excerpt).
+ * @param question the query the answer was produced for.
+ */
+export function isTypeOnlyAnswer(answer, question) {
+    const a = answer.trim();
+    const q = question.trim();
+    if (a.length === 0) {
+        return { typeOnly: false, reason: 'empty answer' };
+    }
+    if (UNCLEAR.test(a)) {
+        return {
+            typeOnly: false,
+            reason: 'explicit "unclear" non-answer — routed through the existing unclear/escalation path, not type-only'
+        };
+    }
+    const usage = firstMatch(q, USAGE_INTENT);
+    if (usage === null) {
+        return {
+            typeOnly: false,
+            reason: 'question requests a type/signature/definition, not usage semantics — a signature answer is responsive'
+        };
+    }
+    // Scan for behavioural verbs over the PROSE only — a verb that is really a method name
+    // inside a signature (`use(...handlers)`) must not read as a statement of behaviour.
+    const behavioural = firstMatch(proseOf(a), BEHAVIOURAL);
+    if (behavioural !== null) {
+        return {
+            typeOnly: false,
+            reason: `answer states behaviour/usage (matched "${behavioural}") — not type-only`
+        };
+    }
+    const signature = firstMatch(a, SIGNATURE);
+    if (signature === null) {
+        return {
+            typeOnly: false,
+            reason: 'answer is not a signature/declaration restatement'
+        };
+    }
+    return {
+        typeOnly: true,
+        reason: `usage question answered only with a signature/declaration restatement (matched "${signature}") and no behavioural statement`
+    };
+}

package/dist/workers/fetch-core.d.ts

@@ -1,5 +1,9 @@
 import { fetchAndClean as defaultFetchAndClean } from './html-clean.js';
 import { type SpawnFn } from '../shared/child-process.js';
+import { type ExcerptVerification } from '../shared/child-output.js';
+/** The exact non-answers the child is instructed to emit, matched at the tool layer. */
+export declare const UNCLEAR_ANSWER = "unclear from this page";
+export declare const NOT_COVERED_ANSWER = "not covered by this page";
 export interface FetchRawInput {
     url: string;
     signal?: AbortSignal;
@@ -11,6 +15,22 @@ export interface FetchRawResult {
     title: string;
 }
 export declare function fetchRaw(input: FetchRawInput): Promise<FetchRawResult>;
+/**
+ * How the page content is turned into the child's prompt. Injectable so an A/B harness can
+ * run the shipped strategy against a frozen legacy one in the SAME process, and assert per
+ * rep that the two arms differ by exactly the lever (see scripts/live-fetch-abstention-ab.ts).
+ * Production always uses {@link shippedStrategy}.
+ */
+export interface PromptStrategy {
+    selectContent(markdown: string, requestedUrl: string): SelectedContent;
+    buildPrompt(args: {
+        query: string;
+        url: string;
+        title: string;
+        content: string;
+        section?: string;
+    }): string;
+}
 export interface FetchFocusedInput {
     url: string;
     query: string;
@@ -18,17 +38,47 @@ export interface FetchFocusedInput {
     signal?: AbortSignal;
     fetchAndClean?: typeof defaultFetchAndClean;
     spawn?: SpawnFn;
+    /** Defaults to {@link shippedStrategy}; overridden only by the A/B harness. */
+    strategy?: PromptStrategy;
 }
 export interface FetchFocusedResult {
     answer: string;
     excerpt?: string;
     excerptVerified?: boolean;
+    /**
+     * The page did not cover the asked-about version/topic — a DISTINCT outcome from
+     * `unclear from this page`, so the caller can pick a different URL instead of treating
+     * "page has no answer" and "answer is ambiguous" as the same thing (PROMPT-3 item 3).
+     */
+    coverageMiss: boolean;
+    /** The #fragment slug that was anchored, when the URL carried one and it was located. */
+    anchoredSection?: string;
+    /** Retained evidence for a false `excerptVerified`, so it is diagnosable without re-fetch. */
+    excerptCheck?: ExcerptVerification;
+    /** The prompt actually handed to the child — the A/B asserts surgery against this per rep. */
+    assembledPrompt: string;
     childExitCode: number;
     aborted: boolean;
     stderr: string;
     stdout: string;
 }
 export declare function fetchFocused(input: FetchFocusedInput): Promise<FetchFocusedResult>;
+export interface SelectedContent {
+    content: string;
+    /** The #fragment slug that was anchored, if the URL carried one AND it was located. */
+    section?: string;
+}
+/**
+ * Slice a markdown page down to the section its heading-anchor #fragment names — the deep
+ * link the caller actually asked for — instead of head-truncating the whole page and losing
+ * a section that sits past the head window (PROMPT-3 item 2). Falls back to {@link truncate}
+ * when the URL has no fragment, or the fragment names no heading in THIS content (e.g. the
+ * page changed since the link was captured), so a fragment we cannot honour never degrades a
+ * page we could otherwise read.
+ */
+export declare function selectContent(markdown: string, requestedUrl: string): SelectedContent;
+/** The shipped strategy: fragment-aware selection + the recalibrated prompt. */
+export declare const shippedStrategy: PromptStrategy;
 export declare function formatResultText(parsed: {
     answer: string;
     excerpt?: string;