@davesheffer/hunch 1.47.2 → 1.48.0

package/dist/store/hunchStore.js

@@ -24,7 +24,7 @@ import { cochangeFor } from "../core/cochange.js";
 import { withServedDatabase } from "../core/served.js";
 import { normalizePath, rankTaskRecords, recordIdsOf, selectLatestTasks, selectTaskSlots } from "../core/taskRanking.js";
 import { resolveTaskRankingMode } from "../core/taskRankingMode.js";
-import { currentForTopic, isInForce } from "../core/topics.js";
+import { currentForTopic, isInForce, isLive, liveForTopic } from "../core/topics.js";
 import { edgeId } from "../core/ids.js";
 import { WHY_GENERATED_ID, WHY_RECORD_ID } from "../core/whyRecord.js";
 import { isStrictBlocker, isVetoBlocker } from "../core/strictgate.js";
@@ -878,10 +878,11 @@ export class HunchStore {
         return { embedded, skipped: docs.length - todo.length, total: docs.length };
     }
     /** Post-fusion rerank by graph PRIORS (dec_25e277f479): relevance ordering, not
-     *  just reachability. Trust weight w = liveness × provenance × recency: liveness 0.6
-     *  for superseded/retired/rejected, provenance 1.0 / 0.85 / 0.75 for
-     *  human_confirmed / llm_draft / extracted-inferred, recency 0.7 + 0.3·½^(age/90d),
-     *  and proven anchored-file staleness 0.8. Every factor is ranking-only.
+     *  just reachability. Trust weight w = provenance × recency: provenance 1.0 / 0.9 /
+     *  0.85 / 0.75 for human_confirmed / agent_recorded / llm_draft / extracted-inferred,
+     *  recency 0.7 + 0.3·½^(age/90d), and proven anchored-file staleness 0.8. Liveness
+     *  (superseded/retired/rejected) is a separate DEAD_PRIOR_SHIFT, and a superseded
+     *  decision always lands just below its live successor. Every factor is ranking-only.
      *  Runbook trigger phrases matching the query boost ×1.5 (exact intent beats
      *  keyword luck). Structural refs (symbols/components/edges) stay neutral.
      *
@@ -899,40 +900,46 @@ export class HunchStore {
      *  they were the #1 fused hit, and 88% from fused rank 8. Both retrieval layers
      *  ranked the record first and the rerank alone threw it away.
      *
-     *  A shift of at most ±MAX_PRIOR_SHIFT positions restores the intended semantics:
+     *  A shift of at most ±MAX_PRIOR_SHIFT positions (+DEAD_PRIOR_SHIFT for history)
+     *  restores the intended semantics:
      *  a stale or low-provenance record visibly dims, an exact runbook-trigger match
      *  visibly promotes, and neither can leapfrog the whole pool. Same measurement
-     *  after: 0% evicted from fused ranks 0–8. Deterministic; ties keep fused order. */
+     *  after: 0% of live records evicted from fused ranks 0–8 (a dead record is meant to
+     *  sink; only from fused #0/#1 is it guaranteed to stay on an 8-hit page).
+     *  Deterministic; ties keep fused order. */
     rerankByPriors(hits, limit, query, freshnessRoot = this.paths.root) {
         if (!hits.length)
             return hits; // a SINGLE hit still runs — topic-chain promotion must fire for the lone stale match
         const now = Date.now();
         const q = query?.toLowerCase();
-        // Topic-chain promotion: for every superseded decision in the pool whose topic
-        // has a live successor NOT already in the pool, inject the successor at the
-        // predecessor's rank — the reader asked about the topic, and the graph's one
-        // live answer must be reachable even when only history matches lexically.
+        const decisionsById = new Map(this.recs("decisions").map((decision) => [decision.id, decision]));
+        // Successor promotion: for every superseded decision in the pool whose live
+        // successor (its topic's current decision, or the open end of its superseded_by
+        // chain) is NOT already in the pool, inject the successor — the reader asked about
+        // the subject, and the graph's one live answer must be reachable even when only
+        // history matches lexically. Where it lands is settled after scoring, below.
         const present = new Set(hits.map((h) => h.ref));
-        // Each candidate carries its fused POSITION; an injected successor inherits its
-        // predecessor's position + a half step, so it lands immediately after it and an
-        // exact-match live record already in the pool is never displaced by an injection.
         const pool = hits.map((h, i) => ({ h, pos: i }));
-        for (const [i, h] of hits.entries()) {
+        const successorOf = new Map(); // superseded ref -> live successor ref
+        for (const h of hits) {
             if (h.kind !== "decisions")
                 continue;
-            const d = this.recs("decisions").find((x) => x.id === h.ref);
-            if (!d?.topic || !(d.status === "superseded" || d.superseded_by))
+            const d = decisionsById.get(h.ref);
+            if (!d || !(d.status === "superseded" || d.superseded_by))
+                continue;
+            const succ = liveSuccessor(d, decisionsById, this.recs("decisions"));
+            const cur = succ?.decision;
+            if (!succ || !cur || cur.id === h.ref)
                 continue;
-            const cur = currentForTopic(this.recs("decisions"), d.topic);
-            if (!cur || cur.id === h.ref || present.has(cur.id))
+            successorOf.set(h.ref, cur.id);
+            if (present.has(cur.id))
                 continue;
             present.add(cur.id);
             pool.push({
-                h: { ref: cur.id, kind: "decisions", title: cur.title, snippet: `current for topic "${d.topic}" (supersedes ${h.ref})`, score: h.score },
-                pos: i + 0.5,
+                h: { ref: cur.id, kind: "decisions", title: cur.title, snippet: succ.via === "topic" ? `current for topic "${d.topic}" (supersedes ${h.ref})` : `live end of the supersede chain from ${h.ref}`, score: h.score },
+                pos: Infinity, // it matched nothing itself: placed only by its predecessor, below
             });
         }
-        const decisionsById = new Map(this.recs("decisions").map((decision) => [decision.id, decision]));
         const staleDecisionIds = this.staleDecisionIds(pool.filter(({ h }) => h.kind === "decisions")
             .map(({ h }) => decisionsById.get(h.ref))
             .filter((decision) => !!decision), freshnessRoot);
@@ -940,8 +947,6 @@ export class HunchStore {
             const m = this.priorMeta(h.ref, h.kind);
             let w = 1;
             if (m) {
-                if (m.dead)
-                    w *= 0.6;
                 // agent_recorded sits BETWEEN human_confirmed and llm_draft. It is testimony —
                 // a human directed the capture but did not countersign it through /capture — so
                 // it must not carry human authority (strict/veto gates key on human_confirmed).
@@ -965,14 +970,45 @@ export class HunchStore {
                 if (q && m.triggers?.some((tr) => q.includes(tr) || tr.includes(q)))
                     w *= 1.5;
             }
-            // w > 1 (a trigger match) shifts UP, w < 1 shifts DOWN, both clamped.
-            const shift = Math.max(-MAX_PRIOR_SHIFT, Math.min(MAX_PRIOR_SHIFT, (1 - w) * PRIOR_SHIFT_SCALE));
+            // w > 1 (a trigger match) shifts UP, w < 1 shifts DOWN, both clamped. A dead record
+            // (superseded/retired/rejected) takes the full bound PLUS DEAD_PRIOR_SHIFT: folded
+            // into w, liveness was a no-op exactly where it mattered — an old or non-human
+            // live record already reaches the clamp on provenance × recency, so its superseded
+            // twin landed at the same position and fused order alone decided which one
+            // answered "what is the rule now". Never below the bound, so a dead memory record
+            // cannot leapfrog any live memory record that fused ahead of it.
+            const shift = m?.dead ? MAX_PRIOR_SHIFT + DEAD_PRIOR_SHIFT
+                : Math.max(-MAX_PRIOR_SHIFT, Math.min(MAX_PRIOR_SHIFT, (1 - w) * PRIOR_SHIFT_SCALE));
             // Recorded intent outranks code that merely shares the query's vocabulary. Applied
             // OUTSIDE the clamp above: that bound keeps the trust dimmer from becoming the sort
             // key, whereas this is a kind-level tie-break between two different answer types.
             const memory = MEMORY_KINDS.has(h.kind) ? -MEMORY_PRIOR_SHIFT : 0;
-            return { h, pos: pos + shift + memory };
+            return { h, fused: pos, shift, memory, dead: !!m?.dead, pos: pos + shift + memory };
         });
+        // A superseded decision never outranks its own live successor, whatever the
+        // provenance tiers or fused order (dec_e622668785: promotion ADDS the current truth
+        // above the stale hit, never erases the trail). The successor takes the
+        // predecessor's FUSED rank weighed by its OWN trust — the query matched the subject
+        // there — bounded on both sides: never above a live record that fused ahead of the
+        // predecessor (it does not borrow a match it never made), always above the
+        // predecessor itself. The floor is taken in memory-neutral space: the kind-level
+        // memory shift is not part of the match, and mixing it in let one code symbol fused
+        // ahead (shift 0 vs memory's −16) pin the successor to just above its dead
+        // predecessor, behind code and behind live records the predecessor outranked. Dead
+        // records never raise the floor — a closed record does not shield the live answer.
+        // The bounds cannot cross: a live record fused ahead sits at most at (f − 1) + MAX,
+        // below the predecessor's f + MAX + DEAD − 0.5.
+        const at = new Map(scored.map((x) => [x.h.ref, x]));
+        for (const [oldRef, curRef] of successorOf) {
+            const prev = at.get(oldRef), cur = at.get(curRef);
+            if (!prev || !cur)
+                continue;
+            let floor = -Infinity;
+            for (const x of scored)
+                if (x !== cur && !x.dead && x.fused < prev.fused)
+                    floor = Math.max(floor, x.pos - x.memory);
+            cur.pos = Math.min(cur.pos, Math.max(prev.fused + cur.shift - 0.5, floor + 0.25) + cur.memory, prev.pos - 0.5);
+        }
         scored.sort((a, b) => a.pos - b.pos);
         return scored.slice(0, limit).map((x) => x.h);
     }
@@ -2410,6 +2446,32 @@ function supersessionChain(d, decs) {
     }
     return [...back, d, ...fwd].map((x) => ({ id: x.id, status: x.status, title: x.title }));
 }
+/** The decision that answers "what is the rule now" for a superseded `d`: its topic's
+ *  single live decision when it has a topic, otherwise the end of its superseded_by
+ *  chain when that end is still in force. Null when the graph has no unambiguous one. */
+function liveSuccessor(d, byId, all) {
+    if (d.topic) {
+        const cur = currentForTopic(all, d.topic);
+        if (cur)
+            return { decision: cur, via: "topic" };
+        // A collision has no single answer; an empty topic just means the successor was
+        // recorded without one, so its superseded_by link is still the authority.
+        if (liveForTopic(all, d.topic).length > 1)
+            return null;
+    }
+    const seen = new Set([d.id]);
+    let end;
+    for (let cur = d.superseded_by ? byId.get(d.superseded_by) : undefined; cur && !seen.has(cur.id); cur = cur.superseded_by ? byId.get(cur.superseded_by) : undefined) {
+        seen.add(cur.id);
+        end = cur;
+    }
+    if (!end || !isLive(end))
+        return null;
+    // The chain end is one side of its own topic's collision: still no single answer.
+    if (end.topic && liveForTopic(all, end.topic).length > 1)
+        return null;
+    return { decision: end, via: "chain" };
+}
 function round(n) {
     return Math.round(n * 100) / 100;
 }
@@ -2438,6 +2500,13 @@ const GRAPH_TOKEN_CAP = boundedWhole(numEnv("HUNCH_GRAPH_TOKEN_CAP", 2_000), 2_0
  *  rerankByPriors for the measurement that fixed it at 4. */
 const PRIOR_SHIFT_SCALE = numEnv("HUNCH_PRIOR_SHIFT_SCALE", 12);
 const MAX_PRIOR_SHIFT = numEnv("HUNCH_MAX_PRIOR_SHIFT", 4);
+/** Positions a superseded/retired/rejected record drops BEYOND the trust clamp. Inside the
+ *  clamp, liveness (×0.6 → 4.8) always saturated it, so a dead record got the same +4 as
+ *  any old or non-human live record and fused order alone decided between them. A dead
+ *  record now shifts MAX_PRIOR_SHIFT + this (6): 2 breaks that tie by one fused rank, and
+ *  the own-successor case is handled separately by successor placement. Still well inside
+ *  an 8-hit page. Set HUNCH_DEAD_PRIOR_SHIFT=0 to restore the old flat +4. */
+const DEAD_PRIOR_SHIFT = numEnv("HUNCH_DEAD_PRIOR_SHIFT", 2);
 /** A stale anchored decision stays visible and authoritative; it moves down by at most the shared prior clamp. */
 const STALE_DECISION_PRIOR_WEIGHT = Math.min(1, numEnv("HUNCH_STALE_DECISION_PRIOR_WEIGHT", 0.8));
 const DECISION_FRESHNESS_SCOPE_QUERY_CAP = 256;

package/dist/synthesis/prContext.d.ts

@@ -0,0 +1,75 @@
+/** Upper bound on PR description characters that reach a prompt. */
+export declare const PR_BODY_MAX_CHARS = 8000;
+/** Upper bound on rendered review-thread characters that reach a prompt. */
+export declare const PR_THREAD_MAX_CHARS = 14000;
+export interface PrContext {
+    number: number;
+    title: string;
+    /** may be "" when only a review thread exists */
+    body: string;
+    /** true when the body was cut to PR_BODY_MAX_CHARS */
+    truncated: boolean;
+    /** the rendered human review thread, oldest first (only when requested) */
+    thread?: string;
+    /** true when the thread was cut to PR_THREAD_MAX_CHARS */
+    threadTruncated?: boolean;
+}
+/** One review-thread message: a conversation comment, a review body, or an inline comment. */
+export interface PrThreadMessage {
+    author: string;
+    bot: boolean;
+    kind: "comment" | "review" | "inline";
+    state?: string;
+    body: string;
+    at: string;
+}
+/** A PR's review thread as fetched: the newest messages, and whether older ones exist. */
+export interface PrThread {
+    messages: PrThreadMessage[];
+    /** true when GitHub holds older messages than were fetched */
+    truncated: boolean;
+}
+/** (owner/repo, PR number, cwd) → the PR's thread, or null when GitHub has no such PR;
+ *  throws when the lookup itself fails. Same contract as PrFetcher. */
+export type PrThreadFetcher = (repository: string, pr: number, cwd: string) => Promise<PrThread | null>;
+/** What the fetcher returns: the raw GitHub pull-request fields we use. */
+export interface PrRecord {
+    title: string;
+    body: string | null;
+    merge_commit_sha: string | null;
+    merged_at: string | null;
+}
+/** (owner/repo, PR number, cwd) → the PR, or null when GitHub has none; throws when the
+ *  lookup itself fails. Injectable for tests. */
+export type PrFetcher = (repository: string, pr: number, cwd: string) => Promise<PrRecord | null>;
+/** The PR number a commit subject names: squash "Title (#N)" or a GitHub merge commit. */
+export declare function prNumberFromSubject(subject: string): number | undefined;
+/** owner/repo of a GitHub `origin`, or null for any other host or no origin. Memoized per root. */
+export declare function githubRepositoryOf(root: string): Promise<string | null>;
+/** One `gh api` call. `gh` brings the user's own auth, so no token passes through Hunch.
+ *  Resolves null when GitHub answers but has no usable PR (404, an issue number);
+ *  THROWS when gh itself is unusable (missing, offline, timed out, unauthenticated). */
+export declare const ghPrFetcher: PrFetcher;
+/** Does this failed `gh api graphql` run carry GitHub's NOT_FOUND answer? (GraphQL
+ *  errors exit non-zero but still print the JSON answer on stdout.) */
+export declare function isNotFoundAnswer(err: unknown): boolean;
+/** The thread out of a successful THREAD_QUERY answer, or null when there is no such PR. */
+export declare function parseThreadAnswer(stdout: string): PrThread | null;
+/** One `gh api graphql` call for the PR's conversation comments, review bodies, and
+ *  inline review comments. Resolves null when GitHub has no such PR; throws when gh
+ *  itself is unusable, exactly like ghPrFetcher. */
+export declare const ghPrThreadFetcher: PrThreadFetcher;
+/** The PR context for one commit, or null. One fetch per (repo, PR, sha, thread?) per
+ *  process. `thread` also fetches the human review thread for a matching PR. */
+export declare function prContextFor(root: string, commit: {
+    sha: string;
+    subject: string;
+}, opts?: {
+    fetcher?: PrFetcher;
+    threadFetcher?: PrThreadFetcher;
+    thread?: boolean;
+    repository?: string | null;
+    env?: NodeJS.ProcessEnv;
+}): Promise<PrContext | null>;
+/** Test seam: forget memoized fetches, origins and the failure count. */
+export declare function clearPrContextMemo(): void;

package/dist/synthesis/prContext.js

@@ -0,0 +1,265 @@
+/**
+ * Pull-request context for commit synthesis (#562 phase 1).
+ *
+ * On squash-merge repos the *why* often lives in the PR description, not the commit
+ * that lands. When a commit subject names its PR ("Title (#N)", or GitHub's
+ * "Merge pull request #N from owner/branch"), fetch that PR's description through the
+ * user's own `gh` CLI and hand it to synthesis as a separate, bounded, labeled section.
+ *
+ * Phase 2: when the caller asks (only the Critic-verified path does), also fetch the
+ * PR's human review/comment thread as a second bounded section. Bots are dropped; a
+ * thread lookup that fails keeps the description.
+ *
+ * Everything here degrades to `null` silently: no GitHub `origin`, no `gh`, offline,
+ * unauthenticated, a PR that does not match the commit, or HUNCH_PR_CONTEXT=0.
+ * PR text is untrusted author-written data; the prompt labels it as such.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { canonicalRemoteRepositoryIdentity } from "../extractors/git.js";
+/** Upper bound on PR description characters that reach a prompt. */
+export const PR_BODY_MAX_CHARS = 8000;
+/** Upper bound on rendered review-thread characters that reach a prompt. */
+export const PR_THREAD_MAX_CHARS = 14000;
+const SQUASH_SUBJECT = /\s\(#(\d{1,9})\)$/;
+const MERGE_SUBJECT = /^Merge pull request #(\d{1,9}) from \S+$/;
+/** The PR number a commit subject names: squash "Title (#N)" or a GitHub merge commit. */
+export function prNumberFromSubject(subject) {
+    const s = subject.trim();
+    const m = SQUASH_SUBJECT.exec(s) ?? MERGE_SUBJECT.exec(s);
+    return m ? Number(m[1]) : undefined;
+}
+const run = promisify(execFile);
+const origins = new Map();
+/** owner/repo of a GitHub `origin`, or null for any other host or no origin. Memoized per root. */
+export async function githubRepositoryOf(root) {
+    if (origins.has(root))
+        return origins.get(root);
+    let repository = null;
+    try {
+        const { stdout } = await run("git", ["-C", root, "remote", "get-url", "origin"], { encoding: "utf8", timeout: 10_000, windowsHide: true });
+        const m = /^provider:github:([a-z0-9-]+\/[a-z0-9._-]+)$/i.exec(canonicalRemoteRepositoryIdentity(stdout.trim(), root));
+        repository = m ? m[1] : null;
+    }
+    catch { /* no origin */ }
+    origins.set(root, repository);
+    return repository;
+}
+/** One `gh api` call. `gh` brings the user's own auth, so no token passes through Hunch.
+ *  Resolves null when GitHub answers but has no usable PR (404, an issue number);
+ *  THROWS when gh itself is unusable (missing, offline, timed out, unauthenticated). */
+export const ghPrFetcher = async (repository, pr, cwd) => {
+    let out;
+    try {
+        // --hostname: the origin is github.com even when the user's gh defaults to an Enterprise host.
+        ({ stdout: out } = await run("gh", ["api", "--hostname", "github.com", `repos/${repository}/pulls/${pr}`], {
+            cwd, encoding: "utf8", timeout: 15_000, maxBuffer: 4 * 1024 * 1024, windowsHide: true,
+        }));
+    }
+    catch (err) {
+        // gh exits non-zero on an HTTP error but still prints GitHub's JSON error body.
+        const e = err;
+        let answer = {};
+        try {
+            answer = JSON.parse(e.stdout ?? "");
+        }
+        catch { /* not an API answer */ }
+        if (typeof e.code === "number" && (answer.status === "404" || answer.status === "422" || answer.message === "Not Found"))
+            return null;
+        throw err;
+    }
+    const raw = JSON.parse(out);
+    if (typeof raw.title !== "string")
+        return null;
+    return {
+        title: raw.title,
+        body: typeof raw.body === "string" ? raw.body : null,
+        merge_commit_sha: typeof raw.merge_commit_sha === "string" ? raw.merge_commit_sha : null,
+        merged_at: typeof raw.merged_at === "string" ? raw.merged_at : null,
+    };
+};
+// `last:`, not `first:`: a review thread converges at its end, so a long one keeps
+// its newest messages and reports the older ones as truncated.
+const THREAD_QUERY = `query($owner: String!, $name: String!, $number: Int!) {
+  repository(owner: $owner, name: $name) { pullRequest(number: $number) {
+    comments(last: 40) { pageInfo { hasPreviousPage } nodes { author { login __typename } body createdAt } }
+    reviews(last: 30) { pageInfo { hasPreviousPage } nodes { author { login __typename } state body submittedAt
+      comments(last: 30) { pageInfo { hasPreviousPage } nodes { author { login __typename } body createdAt } } } }
+  } }
+}`;
+/** Does this failed `gh api graphql` run carry GitHub's NOT_FOUND answer? (GraphQL
+ *  errors exit non-zero but still print the JSON answer on stdout.) */
+export function isNotFoundAnswer(err) {
+    const e = err;
+    if (typeof e?.code !== "number" || typeof e.stdout !== "string")
+        return false;
+    try {
+        const answer = JSON.parse(e.stdout);
+        return Array.isArray(answer.errors) && answer.errors.some((x) => x?.type === "NOT_FOUND");
+    }
+    catch {
+        return false;
+    }
+}
+/** The thread out of a successful THREAD_QUERY answer, or null when there is no such PR. */
+export function parseThreadAnswer(stdout) {
+    const raw = JSON.parse(stdout);
+    const pull = raw.data?.repository?.pullRequest;
+    if (!pull)
+        return null;
+    const message = (n, kind, at) => {
+        const login = typeof n.author?.login === "string" ? n.author.login : "";
+        return {
+            author: login || "ghost",
+            bot: !n.author || !login || n.author.__typename === "Bot" || /\[bot\]$/i.test(login),
+            kind,
+            ...(kind === "review" && typeof n.state === "string" ? { state: n.state } : {}),
+            body: typeof n.body === "string" ? n.body : "",
+            at: typeof at === "string" ? at : "",
+        };
+    };
+    const older = (page) => page?.pageInfo?.hasPreviousPage === true;
+    let truncated = older(pull.comments) || older(pull.reviews);
+    const messages = [];
+    for (const c of pull.comments?.nodes ?? [])
+        if (c)
+            messages.push(message(c, "comment", c.createdAt));
+    for (const r of pull.reviews?.nodes ?? []) {
+        if (!r)
+            continue;
+        messages.push(message(r, "review", r.submittedAt));
+        truncated ||= older(r.comments);
+        for (const c of r.comments?.nodes ?? [])
+            if (c)
+                messages.push(message(c, "inline", c.createdAt));
+    }
+    return { messages, truncated };
+}
+/** One `gh api graphql` call for the PR's conversation comments, review bodies, and
+ *  inline review comments. Resolves null when GitHub has no such PR; throws when gh
+ *  itself is unusable, exactly like ghPrFetcher. */
+export const ghPrThreadFetcher = async (repository, pr, cwd) => {
+    const [owner, name] = repository.split("/");
+    let out;
+    try {
+        // `-f` (raw string) for owner/name: `-F` would coerce a repo named "2048" to an Int.
+        ({ stdout: out } = await run("gh", [
+            "api", "graphql", "--hostname", "github.com",
+            "-f", `query=${THREAD_QUERY}`, "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `number=${pr}`,
+        ], { cwd, encoding: "utf8", timeout: 15_000, maxBuffer: 4 * 1024 * 1024, windowsHide: true }));
+    }
+    catch (err) {
+        if (isNotFoundAnswer(err))
+            return null;
+        throw err;
+    }
+    return parseThreadAnswer(out);
+};
+/** Template comments and runs of blank lines carry no intent; drop them before bounding. */
+function cleanBody(body) {
+    return body.replace(/<!--[\s\S]*?-->/g, "").replace(/\r\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+/** Does this PR belong to this commit? A same-numbered PR in another repo (a fork,
+ *  a cherry-pick) must never lend its description. Accept the exact squash/merge
+ *  sha, or GitHub's default squash subject "<PR title> (#N)". */
+function prMatchesCommit(rec, sha, subject, pr) {
+    if (!rec.merged_at)
+        return false;
+    if (rec.merge_commit_sha && rec.merge_commit_sha.toLowerCase() === sha.toLowerCase())
+        return true;
+    const norm = (s) => s.replace(/\s+/g, " ").trim().toLowerCase();
+    return norm(subject) === norm(`${rec.title} (#${pr})`);
+}
+/** Human messages only, oldest first, one `[login …] body` block each. */
+function renderThread(messages) {
+    const time = (m) => Date.parse(m.at) || 0;
+    return messages
+        .filter((m) => !m.bot)
+        .map((m) => ({ ...m, body: cleanBody(m.body) }))
+        .filter((m) => m.body)
+        .sort((a, b) => time(a) - time(b))
+        .map((m) => `[${m.author}${m.kind === "review" ? ` review${m.state ? ` ${m.state}` : ""}` : m.kind === "inline" ? " inline" : ""}] ${m.body}`)
+        .join("\n\n---\n");
+}
+/** Bound a rendered thread: keep its opening (the question) and its end (where review
+ *  converges), dropping the middle. */
+function boundThread(thread) {
+    if (thread.length <= PR_THREAD_MAX_CHARS)
+        return thread;
+    const gap = "\n\n[… middle of the review thread omitted …]\n\n";
+    const head = Math.floor(PR_THREAD_MAX_CHARS / 4);
+    return thread.slice(0, head) + gap + thread.slice(thread.length - (PR_THREAD_MAX_CHARS - head - gap.length));
+}
+const memo = new Map();
+const MAX_CONSECUTIVE_FAILURES = 2;
+let failures = 0;
+// Separate from `failures`: a GraphQL-only problem (its own rate limit, a token REST
+// accepts but GraphQL refuses) must stop thread lookups, not the working descriptions.
+let threadFailures = 0;
+/** The PR context for one commit, or null. One fetch per (repo, PR, sha, thread?) per
+ *  process. `thread` also fetches the human review thread for a matching PR. */
+export async function prContextFor(root, commit, opts = {}) {
+    const env = opts.env ?? process.env;
+    if (env.HUNCH_PR_CONTEXT === "0")
+        return null;
+    const pr = prNumberFromSubject(commit.subject);
+    if (pr === undefined)
+        return null;
+    const repository = opts.repository !== undefined ? opts.repository : await githubRepositoryOf(root);
+    if (!repository)
+        return null;
+    // A description-only answer must never satisfy a thread lookup.
+    const key = `${repository.toLowerCase()}#${pr}@${commit.sha}${opts.thread ? "+thread" : ""}`;
+    if (memo.has(key))
+        return memo.get(key);
+    // Offline or without gh, every fetch would wait out its timeout: after a couple of
+    // straight lookup failures, stop asking for the rest of this process (e.g. a long
+    // backfill). A PR GitHub simply doesn't have is an answer, not a failure.
+    if (failures >= MAX_CONSECUTIVE_FAILURES)
+        return null;
+    let rec;
+    try {
+        rec = await (opts.fetcher ?? ghPrFetcher)(repository, pr, root);
+        failures = 0;
+    }
+    catch {
+        failures++;
+        return null;
+    }
+    let ctx = null;
+    if (rec && prMatchesCommit(rec, commit.sha, commit.subject, pr)) {
+        const body = cleanBody(rec.body ?? "");
+        const described = {
+            number: pr,
+            title: rec.title.replace(/\s+/g, " ").trim().slice(0, 300),
+            body: body.slice(0, PR_BODY_MAX_CHARS),
+            truncated: body.length > PR_BODY_MAX_CHARS,
+        };
+        let thread = "";
+        let olderOmitted = false;
+        if (opts.thread && threadFailures < MAX_CONSECUTIVE_FAILURES) {
+            try {
+                const fetched = await (opts.threadFetcher ?? ghPrThreadFetcher)(repository, pr, root);
+                threadFailures = 0;
+                thread = renderThread(fetched?.messages ?? []);
+                olderOmitted = !!fetched?.truncated;
+            }
+            catch {
+                // A failed thread lookup trips only the thread breaker and keeps the description.
+                threadFailures++;
+                return body ? described : null;
+            }
+        }
+        if (thread) {
+            ctx = { ...described, thread: boundThread(thread), threadTruncated: olderOmitted || thread.length > PR_THREAD_MAX_CHARS };
+        }
+        else if (body) {
+            ctx = described;
+        }
+    }
+    memo.set(key, ctx);
+    return ctx;
+}
+/** Test seam: forget memoized fetches, origins and the failure count. */
+export function clearPrContextMemo() { memo.clear(); origins.clear(); failures = 0; threadFailures = 0; }
+//# sourceMappingURL=prContext.js.map

package/dist/synthesis/provider.d.ts

@@ -1,5 +1,6 @@
 import { type DiffAnalysis } from "../extractors/diff.js";
 import type { Decision } from "../core/types.js";
+import type { PrContext } from "./prContext.js";
 /**
  * Run a command, optionally feeding `input` to its stdin, and resolve its
  * stdout. Uses spawn (not execFile) so we can:
@@ -35,6 +36,7 @@ export interface DecisionDraft {
     verifyOutcome?: "applied" | "unavailable" | "failed";
     fellBackTo?: string;
     fallbackReason?: string;
+    fallbackKind?: string;
 }
 /** A skeptical audit of a DecisionDraft against the commit it was derived from.
  *  `grounded` is 0..1 (how well decision+consequences are supported by the diff);
@@ -84,6 +86,9 @@ export interface CommitInput {
     diff: string;
     /** structured "what changed" — lets even the no-LLM path be informative */
     analysis?: DiffAnalysis;
+    /** the merged pull request's description, already bounded (#562); absent when
+     *  unavailable and for local-only captures */
+    pr?: PrContext;
 }
 export interface FailureInput {
     test: string;
@@ -280,6 +285,39 @@ export declare function applyVerdict(draft: DecisionDraft, v: VerifyVerdict): De
  *  the Critic call stacks after sampling, and a single transient failure on that
  *  extra call shouldn't drop the audit. */
 export declare function verifyDecisionSafe(verifier: SynthProvider | null, input: CommitInput, draft: DecisionDraft): Promise<DecisionDraft>;
+type FieldSchema = {
+    type: string | readonly string[];
+    description?: string;
+    items?: {
+        type: string;
+    };
+    enum?: readonly string[];
+};
+/** The output contract for a prompt-only provider. A JSON Schema pasted verbatim
+ *  gets echoed back as the answer: claude-cli on haiku returned the schema itself
+ *  for about 1 in 5 commit drafts (issue #561), which then fell back to the
+ *  heuristic. So describe each key in plain words and ask for the filled-in object. */
+export declare function jsonInstruction(schema: {
+    properties: Record<string, FieldSchema>;
+}): string;
+declare const UNUSABLE_DETAIL: {
+    readonly "echoed-schema": "echoed the schema instead of an answer";
+    readonly "no-json": "no JSON object";
+    readonly empty: "empty output";
+    readonly "missing-fields": "JSON lacked the required fields";
+};
+export type UnusableKind = keyof typeof UNUSABLE_DETAIL;
+/** A provider answered, but its output held no usable record. Distinct from a
+ *  transport failure (timeout, crash, auth) because a second sample can succeed:
+ *  the safe wrappers retry this kind only. `kind` names what was wrong without
+ *  quoting the model output, so the reason is safe to print and to persist. */
+export declare class UnusableOutputError extends Error {
+    readonly kind: UnusableKind;
+    constructor(provider: string, what: string, kind: UnusableKind);
+}
+/** Why `text` produced no record: no object at all, the schema echoed back, or
+ *  objects that lack the fields the mapper needs. */
+export declare function classifyUnusableOutput(text: string): UnusableKind;
 /** Every parseable top-level JSON object in arbitrary model text, in order. */
 export declare function extractJsonObjects(text: string): Record<string, unknown>[];
 /** Convenience: the FIRST parseable top-level object, or null. (The mappers below