@davesheffer/hunch 1.31.1 → 1.32.0

package/dist/core/declarationClusters.d.ts

@@ -0,0 +1,149 @@
+export declare const FILE_FIRST_DECLARATION_CLUSTER_RULE: "flat-file-anchored-semantic-clusters-v3";
+export declare const FILE_FIRST_FILE_LIMIT = 5;
+export declare const FILE_FIRST_CLUSTER_LIMIT = 2;
+export declare const FILE_FIRST_MEMBER_LIMIT = 3;
+export declare const PROGRESSIVE_DECLARATION_PLAN_RULE: "promoted-only-progressive-inspection-v4";
+export declare const PROGRESSIVE_DECLARATION_BASELINE_LIMIT = 5;
+export declare const PROGRESSIVE_DECLARATION_PRIMARY_LIMIT = 10;
+export declare const PROGRESSIVE_DECLARATION_TOTAL_LIMIT = 11;
+export declare const FILE_FIRST_DECLARATION_CLUSTER_TRANSFER: {
+    readonly benchmark: "flat-file-anchored-clusters-transfer-v3";
+    readonly scorable_tasks: 12;
+    readonly baseline_top_five_hits: 3;
+    readonly combined_hits: 6;
+    readonly combined_improvement_points: 0.25;
+    readonly baseline_file_hits: 8;
+    readonly cluster_file_hits: 10;
+    readonly rescues: 3;
+    readonly average_inspected_declarations: 18.83;
+    readonly max_inspected_declarations: 24;
+    readonly decision: "promoted-supplemental-diagnostic";
+    readonly exact_owner_policy: "disabled";
+};
+export declare const PROGRESSIVE_DECLARATION_DEVELOPMENT: {
+    readonly benchmark: "revealed-cluster-transfer-v1-v2-v3-replay";
+    readonly scorable_tasks: 36;
+    readonly baseline_top_five_hits: 15;
+    readonly progressive_plan_hits: 21;
+    readonly full_cluster_union_hits: 21;
+    readonly previous_average_inspected_declarations: 19.81;
+    readonly progressive_max_inspected_declarations: 11;
+    readonly inspection_reduction: 0.4446;
+    readonly decision: "candidate-awaiting-fresh-transfer";
+    readonly exact_owner_policy: "disabled";
+};
+export declare const PROGRESSIVE_DECLARATION_TRANSFER: {
+    readonly benchmark: "progressive-inspection-cross-repository-transfer-v4";
+    readonly scorable_tasks: 12;
+    readonly baseline_top_five_hits: 5;
+    readonly progressive_plan_hits: 5;
+    readonly full_cluster_union_hits: 5;
+    readonly rescues: 0;
+    readonly losses: 0;
+    readonly average_inspected_declarations: 11;
+    readonly previous_average_inspected_declarations: 18.92;
+    readonly inspection_reduction: 0.4185;
+    readonly decision: "retain-efficiency-advisory-v4";
+    readonly accuracy_promotion: "rejected-no-fresh-rescue";
+    readonly exact_owner_policy: "disabled";
+};
+export interface ClusterableDeclarationCandidate {
+    owner: string;
+    score: number;
+    runtime_declaration: boolean;
+    type_scaffolding: boolean;
+}
+export interface DeclarationClusterMember {
+    owner: string;
+    global_rank: number;
+    static_score: number;
+    runtime_declaration: boolean;
+    type_scaffolding: boolean;
+}
+export interface SemanticDeclarationCluster {
+    cluster_id: string;
+    label: string;
+    semantic_terms: string[];
+    representative: string;
+    representative_global_rank: number;
+    members: DeclarationClusterMember[];
+    members_truncated: number;
+}
+export interface FileFirstDeclarationCluster {
+    path: string;
+    file_rank: number;
+    file_score: number;
+    first_candidate_rank: number;
+    declaration_clusters: SemanticDeclarationCluster[];
+}
+export interface FileFirstDeclarationClusterReceipt {
+    version: 3;
+    receipt_id: string;
+    rule: typeof FILE_FIRST_DECLARATION_CLUSTER_RULE;
+    source_candidates: number;
+    file_limit: number;
+    cluster_limit_per_file: number;
+    member_limit_per_cluster: number;
+    selected_files: string[];
+    selected_cluster_ids: string[];
+    file_selection_strategy: "flat-shortlist-file-anchor";
+    flat_shortlist_anchor_size: 5;
+    flat_shortlist_preserved: true;
+    exact_owner_enabled: false;
+}
+export interface FileFirstDeclarationDiagnostic {
+    files: FileFirstDeclarationCluster[];
+    receipt: FileFirstDeclarationClusterReceipt;
+    transfer_calibration: typeof FILE_FIRST_DECLARATION_CLUSTER_TRANSFER;
+}
+export interface ProgressiveInspectionCandidate {
+    owner: string;
+    inspection_rank: number;
+    phase: "flat-shortlist" | "cluster-expansion" | "cluster-fallback";
+    file_path: string;
+    global_rank: number;
+    cluster_id: string | null;
+    cluster_label: string | null;
+    runtime_declaration: boolean;
+    type_scaffolding: boolean;
+}
+export interface ProgressiveInspectionPhase {
+    phase: ProgressiveInspectionCandidate["phase"];
+    instruction: string;
+    stop_condition: string;
+    candidates: ProgressiveInspectionCandidate[];
+}
+export interface ProgressiveDeclarationPlanReceipt {
+    version: 1;
+    receipt_id: string;
+    rule: typeof PROGRESSIVE_DECLARATION_PLAN_RULE;
+    baseline_limit: number;
+    primary_limit: number;
+    total_limit: number;
+    selected_owners: string[];
+    selected_cluster_ids: string[];
+    promoted_mechanisms: readonly ["repository-adaptive-ranking", "flat-file-anchored-semantic-clusters"];
+    rejected_rerankers_disabled: true;
+    flat_shortlist_preserved: true;
+    exact_owner_enabled: false;
+}
+export interface ProgressiveDeclarationPlan {
+    phases: ProgressiveInspectionPhase[];
+    candidates: ProgressiveInspectionCandidate[];
+    receipt: ProgressiveDeclarationPlanReceipt;
+    development_calibration: typeof PROGRESSIVE_DECLARATION_DEVELOPMENT;
+    transfer_calibration: typeof PROGRESSIVE_DECLARATION_TRANSFER;
+}
+/** Build a hierarchical diagnostic from the existing static ranking. The flat
+ * shortlist remains untouched: this view collapses related declaration
+ * scaffolding into semantic families so one noisy family cannot consume every
+ * inspection slot inside a promising file. It is still a candidate view, not
+ * an exact-owner claim. */
+export declare function buildFileFirstDeclarationClusters(rankedCandidatesValue: ClusterableDeclarationCandidate[], requestedFileLimit?: number, requestedClusterLimit?: number, requestedMemberLimit?: number): FileFirstDeclarationDiagnostic;
+/** Turn the promoted flat shortlist and semantic clusters into a progressive
+ * inspection queue. The first five candidates remain byte-for-byte intact.
+ * Supplemental candidates must already belong to a selected semantic family,
+ * and are ordered by the frozen repository-adaptive rank instead of widening
+ * to every declaration in the file. The last slot is explicitly a fallback so
+ * callers can stop after ten inspections when the behavior is already owned. */
+export declare function buildProgressiveDeclarationPlan(rankedCandidatesValue: ClusterableDeclarationCandidate[], clusters: FileFirstDeclarationDiagnostic, requestedBaselineLimit?: number, requestedTotalLimit?: number): ProgressiveDeclarationPlan;

package/dist/core/delivery.d.ts

@@ -0,0 +1,110 @@
+import type { AssembledContext } from "../store/hunchStore.js";
+import type { Component, Decision, Symbol } from "./types.js";
+import type { ExecutionObligation } from "./pipeline.js";
+import { type LandscapeDeliveryFragment } from "./landscapeDelivery.js";
+export declare const DELIVERY_ENVELOPE_SCHEMA_VERSION: "hunch.delivery-envelope/1";
+export declare const DELIVERY_PROFILE_POLICY_VERSION: "hunch.delivery-profile/1";
+export declare const DELIVERY_PROFILES: readonly ["builder", "reviewer", "architect"];
+export type DeliveryProfile = (typeof DELIVERY_PROFILES)[number];
+export type DeliveryKind = "constraints" | "decisions" | "bugs" | "findings" | "resources" | "relationships";
+export type CommitReachability = "reachable" | "unreachable" | "unknown";
+export interface DeliveryRef {
+    kind: DeliveryKind;
+    record_id: string;
+}
+export type DeliveryReason = "ranked" | "blocking-reserved";
+export type DeliveryProvenanceStatus = "current" | "unverified" | "stale";
+export interface DeliveredItem extends DeliveryRef {
+    /** One-based position in the eligible memory ranking. */
+    rank: number;
+    delivery_reason: DeliveryReason;
+    provenance_status: DeliveryProvenanceStatus;
+    /** Deterministic approximation: four Unicode code points per token. */
+    token_cost: number;
+}
+export interface DeliverySupplement {
+    id: string;
+    kind: string;
+    text: string;
+    /** Higher values are attempted first after ranked memory. */
+    priority?: number;
+}
+export interface DeliveredSupplement {
+    id: string;
+    kind: string;
+    delivered: boolean;
+    reason: "supplemental" | "budget" | "empty" | "abstained";
+    rank: number;
+    token_cost: number;
+}
+export interface DeliveryOmission extends DeliveryRef {
+    reason: "budget" | "stale-provenance" | "retired" | "actionability-cap" | "endpoint-not-delivered" | "landscape-cap" | "profile-cap" | DeliveryAbstentionReason;
+    detail: string;
+}
+export type DeliveryAbstentionReason = "low-confidence" | "insufficient-context" | "low-relevance";
+export interface DeliveryAbstention {
+    /** True when Hunch found prescriptive memory but deliberately withheld it. */
+    active: boolean;
+    withheld: number;
+    reasons: Record<DeliveryAbstentionReason, number>;
+    /** A concrete recovery path instead of a silent empty result. */
+    retry_hint: string | null;
+}
+/** A bounded, falsifiable interpretation of one delivered decision. The packet
+ * is derived only from stored record/query fields; it never invents a fix. */
+export interface DeliveryHypothesis {
+    kind: "decision";
+    record_id: string;
+    /** Rank of the corresponding delivered record in this envelope. */
+    rank: number;
+    why: string;
+    where: string[];
+    historical_pattern: string;
+    verify: string;
+    disprove: string;
+    /** Observable controller checks derived from immutable record evidence. */
+    obligations: ExecutionObligation[];
+}
+export interface DeliveryEnvelope {
+    schema_version: typeof DELIVERY_ENVELOPE_SCHEMA_VERSION;
+    /** Role-specific ordering only; never enforcement or authority. */
+    profile: DeliveryProfile;
+    ranking_policy: typeof DELIVERY_PROFILE_POLICY_VERSION;
+    /** Content-addressed identity for exactly what this envelope returned. */
+    receipt_id: string;
+    text: string;
+    delivered: DeliveredItem[];
+    hypotheses: DeliveryHypothesis[];
+    obligations: ExecutionObligation[];
+    supplements: DeliveredSupplement[];
+    omitted: DeliveryOmission[];
+    /** Reviewed graph records delivered through this same budget and receipt. */
+    landscape: LandscapeDeliveryFragment | null;
+    budget_tokens: number;
+    used_chars: number;
+    /** Conservative text + structured landscape payload accounting. */
+    accounted_chars: number;
+    /** True only when the requested budget is mathematically too small to name
+     * every active blocking invariant. Safety wins, and the overflow is explicit. */
+    blocking_overflow: boolean;
+    abstention: DeliveryAbstention;
+}
+export interface DeliveryOptions {
+    /** Defaults to builder for day-to-day coding work. */
+    profile?: DeliveryProfile;
+    root?: string;
+    symbols?: readonly Pick<Symbol, "id" | "name" | "file">[];
+    components?: readonly Pick<Component, "id" | "status" | "paths">[];
+    /** Full decision corpus lets the envelope explain only decisions it actually delivered. */
+    decisionCorpus?: readonly Decision[];
+    /** Caller-specific grounding that must share the same hard output budget. */
+    supplements?: readonly DeliverySupplement[];
+    /** Time-travel contexts intentionally include records that are retired at HEAD. */
+    historical?: boolean;
+    /** Injectable for deterministic tests. Omit to use the local Git graph. */
+    commitReachability?: (commit: string) => CommitReachability;
+}
+/** Validate the public receipt without trusting a caller-supplied identity. */
+export declare function assertDeliveryEnvelope(envelope: DeliveryEnvelope): void;
+/** Build the one envelope used by CLI, MCP, and the edit hook. */
+export declare function buildDeliveryEnvelope(ctx: AssembledContext, options?: DeliveryOptions): DeliveryEnvelope;

package/dist/core/docanchors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Markdown topic anchors — decision-grounding for PROSE (the doc≠graph spoke,
+ * extended to the files the ecosystem already funnels team knowledge into:
+ * AGENTS.md, CLAUDE.md, docs/*.md).
+ *
+ * A tracked markdown file declares which decision topic a section describes:
+ *
+ *   <!-- hunch:topic auth.session -->               grounding only
+ *   <!-- hunch:topic auth.session dec_a1b2c3d4e5 --> PINNED: prose written against that decision
+ *
+ * Deterministic by construction: drift fires ONLY on an explicit pin whose
+ * decision has been superseded — never on a semantic guess (the same philosophy
+ * as `anchor-stale` in drift.ts). Unpinned markers still ground the pre-edit
+ * hook but can never fire drift.
+ */
+import type { Decision } from "./types.js";
+export interface DocAnchor {
+    topic: string;
+    /** The decision id the prose was written against, or null for an unpinned marker. */
+    pin: string | null;
+    /** 1-based line of the marker in the document. */
+    line: number;
+}
+/** Parse every hunch:topic marker out of a markdown document. Markers inside
+ *  fenced code blocks or inline code spans are examples, not declarations,
+ *  and are skipped. */
+export declare function parseDocAnchors(text: string): DocAnchor[];
+/** Pre-edit grounding for a markdown document that carries topic anchors: the
+ *  CURRENT decision per declared topic (graph over prose), what it rejected,
+ *  and a stale-pin warning the editor can heal inline. Empty when no anchor
+ *  resolves to a decision. */
+export declare function renderDocGrounding(anchors: readonly DocAnchor[], decisions: readonly Decision[]): string;

package/dist/core/docscan.d.ts

@@ -0,0 +1,26 @@
+import type { Decision } from "./types.js";
+export declare const STALE_MARKER: RegExp;
+export declare const SRC_REF: RegExp;
+/** Bounded walk for repo markdown (root + docs/, depth-limited; heavy/irrelevant trees skipped). */
+export declare function markdownDocs(root: string): Array<{
+    path: string;
+    rel: string;
+}>;
+export type DocStatus = "grounded" | "stale" | "unverified";
+export interface RepoDoc {
+    /** repo-relative POSIX path. */
+    rel: string;
+    /** First `# ` heading, or the path when the doc has none. */
+    title: string;
+    /** Topics the doc declares via hunch:topic markers. */
+    topics: string[];
+    /** src/*.ts files the doc mentions (the component-association signal). */
+    srcRefs: string[];
+    status: DocStatus;
+    /** Human-readable reasons behind a "stale" grade (empty otherwise). */
+    issues: string[];
+}
+/** Grade every repo doc. GENERATED wiki pages (hunch:wiki header) are views of
+ *  the graph, not specs — they are excluded here and freshness-gated by their
+ *  own manifest hash instead. */
+export declare function scanRepoDocs(decisions: readonly Decision[], root: string): RepoDoc[];

package/dist/core/drift.d.ts

@@ -0,0 +1,13 @@
+import type { HunchStore } from "../store/hunchStore.js";
+export type DriftKind = "dead-ref" | "supersede" | "doc-stale" | "anchor-stale" | "doc-anchor-stale" | "doc-anchor-dangling" | "wiki-stale" | "finding-stale" | "premise-stale" | "commit-unresolvable" | "madr-stale" | "madr-edited" | "madr-orphan";
+export interface DriftFinding {
+    kind: DriftKind;
+    id: string;
+    detail: string;
+}
+export interface DriftReport {
+    findings: DriftFinding[];
+}
+export declare function computeDrift(store: HunchStore, root: string, deps?: {
+    commitResolvable?: (sha: string) => boolean;
+}): DriftReport;

package/dist/core/drift.js

@@ -26,7 +26,8 @@ import { parseDocAnchors } from "./docanchors.js";
 import { markdownDocs, STALE_MARKER, SRC_REF } from "./docscan.js";
 import { computeWikiDrift } from "../wiki/wiki.js";
 import { computeMadrDrift } from "../integrations/madrManifest.js";
-export function computeDrift(store, root) {
+import { commitsExist, isGitRepo } from "../extractors/git.js";
+export function computeDrift(store, root, deps = {}) {
     const findings = [];
     const decisions = store.recs("decisions");
     const byId = new Map(decisions.map((d) => [d.id, d]));
@@ -46,6 +47,25 @@ export function computeDrift(store, root) {
         return liveFiles.has(p) || liveDirs.some((dir) => p.startsWith(dir));
     };
     const premiseEnv = { now: new Date().toISOString(), exists: (p) => existsSync(join(root, p)) };
+    // A plain existence check is meaningless outside a git repo — computed once,
+    // not per decision, and never a false positive for a directory that merely
+    // happens to hold .hunch/ without being a git checkout. Injectable so tests
+    // (and callers with a cheaper oracle) never have to shell out per decision.
+    const gitRepo = isGitRepo(root);
+    // One batched `git cat-file --batch-check` for every commit-bearing decision,
+    // not one `rev-parse` per decision — skipped entirely when a predicate is
+    // injected (tests/callers with a cheaper oracle never pay for this at all).
+    const resolvableCommits = gitRepo && !deps.commitResolvable
+        ? commitsExist([...new Set(decisions.filter((d) => d.commit).map((d) => d.commit))], root)
+        : null;
+    const defaultCommitResolvable = (sha) => {
+        if (!gitRepo)
+            return true; // never flag outside a git repo
+        if (resolvableCommits === null)
+            return true; // the batch check itself failed, or was skipped — fail open
+        return resolvableCommits.has(sha);
+    };
+    const commitResolvable = deps.commitResolvable ?? defaultCommitResolvable;
     for (const d of decisions) {
         // 1. DEAD-REFERENCE — only for in-force decisions; a superseded one referencing
         //    a since-deleted file is legitimate history, not drift.
@@ -58,6 +78,16 @@ export function computeDrift(store, root) {
                     findings.push({ kind: "dead-ref", id: d.id, detail: `references missing file "${f}"` });
                 }
             }
+            // 8. COMMIT-UNRESOLVABLE — an in-force decision's commit provenance no longer
+            //    resolves at all (source branch gone + gc'd past recovery). The
+            //    opportunistic post-merge repair (commitrepair.ts) is the fix path; this
+            //    is purely the "nothing caught it" signal — deterministic, never auto-fixed.
+            //    Mirrors repair.ts:59's live-records-only rule: `inForce` alone doesn't
+            //    exclude a never-adopted "rejected" decision (superseded_by is null for
+            //    those too), so exclude it explicitly here.
+            if (d.commit && d.status !== "rejected" && !commitResolvable(d.commit)) {
+                findings.push({ kind: "commit-unresolvable", id: d.id, detail: `commit ${d.commit} no longer resolves in this repository — provenance may need manual repair` });
+            }
         }
         // 2. SUPERSEDE-INTEGRITY — a contradiction class: A.supersedes = B, but B is
         //    either gone or still in force (the private-supersede bug shape).

package/dist/core/dupdetect.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Deterministic near-duplicate detection for auto-drafted decisions — hygiene,
+ * not judgment (the human vouch stays untouchable; dec_a466655539 doctrine).
+ *
+ * The duplicate factory: a human records a decision via MCP (commit: null),
+ * then commits the code — the post-commit hook synthesizes a SECOND record of
+ * the same choice under a commit-keyed id. Review triage showed 7 of 14 queued
+ * drafts were exactly this.
+ *
+ * Two layers, both model-free:
+ *  - commitCoveredBy(): PRE-draft gate in syncCommit — a recent human-confirmed
+ *    decision already claims this commit's files (+ subject terms) → skip the
+ *    draft entirely (also saves the subscription call). Recency-windowed so an
+ *    OLD decision on the same files can never suppress genuinely new work.
+ *  - draftDuplicateOf(): review-time flag for drafts already in the store —
+ *    full-text term overlap + file overlap against accepted records, so
+ *    `hunch review` marks likely duplicates and can batch-reject them.
+ */
+import type { Decision } from "./types.js";
+/** Lowercased salient terms (≥4 chars, non-stopword) — deliberately simple and
+ *  deterministic; shared by both layers so their notion of "similar" agrees. */
+export declare function dupTerms(text: string): Set<string>;
+export interface Coverage {
+    id: string;
+    title: string;
+    hoursAgo: number;
+    fileOverlapPct: number;
+}
+/** Does a RECENT human-confirmed live decision already claim this commit's
+ *  files (and roughly its subject)? Deterministic pre-draft gate. */
+export declare function commitCoveredBy(codeFiles: readonly string[], subject: string, existing: readonly Decision[], nowMs: number): Coverage | null;
+export interface DupMatch {
+    of: Decision;
+    /** 0..1 combined similarity (term Jaccard, file-overlap boosted). */
+    score: number;
+}
+/** Only a finalized, still-live human decision can justify deleting a draft as
+ *  redundant. Proposed records may resemble one another, but choosing which one
+ *  survives is review judgment—not deterministic hygiene. */
+export declare function isAcceptedDuplicateAnchor(d: Decision): boolean;
+/** Is an existing DRAFT a near-duplicate of an accepted record? Review-time
+ *  flag; threshold callers use 0.35 (batch-reject) — conservative on purpose. */
+export declare function draftDuplicateOf(draft: Decision, existing: readonly Decision[]): DupMatch | null;

package/dist/core/escalations.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Inline escalations — the "ask the human IN THE PROMPT, not in a background queue"
+ * half of the auto-trust model.
+ *
+ * Captured memory auto-trusts the moment it lands (status accepted, advisory), so
+ * there is no draft queue to drain. The only things that still need a human are the
+ * rare cases the graph genuinely CANNOT resolve on its own — and those are surfaced
+ * as a short, question-framed list the assistant raises in conversation at the
+ * moment, then normally EMPTY.
+ *
+ * Deterministic only. Memory questions include a topic conflict (>1 live decision for
+ * one topic — a git merge can create these; see topics.topicCollisions) and one
+ * exact imported ADR awaiting a hash-bound approve/decline answer. We do NOT
+ * guess semantically which un-anchored decisions "contradict" each other — that
+ * stays the assistant's judgment, asked in chat, never a machine verdict (same
+ * explicit-anchors-only ethos as the drift detector).
+ *
+ * Pure over a Decision[] — no store, no IO — so the CLI, the MCP read tool, and the
+ * session-start orientation all share one source of truth.
+ */
+import type { Decision } from "./types.js";
+import { type CommitRewrite } from "./commitrepair.js";
+export type EscalationKind = "topic-conflict" | "imported-adr-review" | "policy-candidate" | "policy-proposal" | "policy-repaired" | "premise-stale" | "commit-repair-pending";
+export interface Escalation {
+    kind: EscalationKind;
+    /** the topic (or other key) the conflict is about. */
+    topic: string;
+    /** the decisions the human must choose between. */
+    decisionIds: string[];
+    /** a one-line, human-facing question the assistant should raise in the prompt. */
+    question: string;
+    /** the supporting detail (ids + titles) for the question. */
+    detail: string;
+    /** the concrete resolution the human's answer maps to. */
+    resolution: string;
+    /** false ONLY for an entry whose own resolution requires acting on a
+     *  DIFFERENT entry first (a duplicate-id queue's non-drop, non-apply
+     *  follower) — it still surfaces, for transparency, but gating surfaces
+     *  (CI exit code, "needs your call" tallies) must not count it: resolving
+     *  the actionable entry ahead of it is what clears it, not anything a
+     *  human can do to this row directly (#61). Omitted (undefined) means
+     *  true — every other escalation kind is always directly actionable. */
+    actionable?: boolean;
+}
+/** Escalations gating surfaces (CI exit codes, "needs your call" counts/lists)
+ *  should act on: everything except an entry explicitly marked
+ *  actionable:false (#61). The full list — including non-actionable
+ *  entries — still belongs in any transparency-facing output (e.g. --json). */
+export declare function actionableEscalations(items: readonly Escalation[]): Escalation[];
+export interface EscalationSummary {
+    /** the subset a gating surface should count/exit/ask on. */
+    actionable: Escalation[];
+    /** how many entries were filtered out — informational-only, shown for
+     *  transparency but not itself a decision to raise. */
+    context: number;
+}
+/** One computation for every "N need your call (+M shown for context)"
+ *  consumer (CLI `escalations`, SessionStart, the `hunch_now`/`hunch_escalations`
+ *  MCP tools) — introduced alongside `actionable` (#61) specifically so a
+ *  future consumer of Escalation[] can't repeat the mistake of hand-rolling
+ *  the filter and forgetting it (the VS Code panel did, before this existed). */
+export declare function summarizeEscalations(items: readonly Escalation[]): EscalationSummary;
+/** "you" (the CLI, talking directly to the operator) vs "mcp" (an assistant
+ *  relaying a question to the human, third person). */
+export type EscalationAudience = "cli" | "mcp";
+/** The ONE "N need your call (+M shown for context)" headline, shared by the
+ *  CLI `escalations` command and the `hunch_escalations` MCP tool (#61) —
+ *  including its own "nothing actionable, but N item(s) queued for context"
+ *  fallback, so that unreachable-today prose exists in exactly one place
+ *  instead of being hand-copied per consumer (the copy-paste is how the VS
+ *  Code panel missed the filter entirely before `actionable` existed).
+ *  Callers are expected to have already special-cased `items.length === 0`
+ *  (a plainer "nothing needs your decision" message, no tally at all). */
+export declare function escalationHeadline(items: readonly Escalation[], audience: EscalationAudience): string;
+/** The decisions a human must make NOW, to be asked INLINE. Empty in a healthy graph. */
+export declare function pendingEscalations(decisions: readonly Decision[]): Escalation[];
+/** A commit-provenance repair the post-merge hook detected and queued
+ *  (src/core/repairqueue.ts) but never applied — the match signal (related_files
+ *  overlap) isn't strong enough to write unattended, so it's a question for the
+ *  human, exactly like every other entry here, never a silent write.
+ *
+ *  `decisions` is the caller's VISIBLE scope (supplies the title only) —
+ *  MCP/SessionStart pass store.advisoryRecs(), which is public-only in
+ *  private mode. `live` is the scope liveRewrites checks the repair against;
+ *  it defaults to `decisions` but callers on an advisory scope must pass the
+ *  FULL store (store.recs()) here, since repair-provenance itself reads the
+ *  full store — an overlay decision's repair is fully answerable even where
+ *  its title isn't visible, and must not go silent just because the title is
+ *  private.
+ *
+ *  `withheld` (from repairqueue.ts's withheldRewrites — a git-facing check
+ *  this module deliberately stays free of, so the caller runs it and passes
+ *  the result in) names entries whose proposed `to` doesn't resolve to a
+ *  real commit here. `--apply --only <id>` can never resolve one of these —
+ *  advertising it as the answer would be advice guaranteed to no-op
+ *  forever, which is worse than not asking at all. Such an entry still
+ *  needs a human (only `--drop` can retire it), so it still escalates, just
+ *  with wording that doesn't promise `--apply` will help.
+ *
+ *  Keyed by OBJECT, not by id, matching withheldForUnresolvableTo's own
+ *  contract: a corrupted queue file can carry two entries sharing an id
+ *  (one resolvable, one not) — an id-keyed set couldn't tell them apart and
+ *  would wrongly tag the resolvable sibling as unresolvable too. Every
+ *  caller of this function already passes the SAME `queued` array to both
+ *  this function and withheldRewrites, so identity holds. */
+export declare function commitRepairEscalations(queued: readonly CommitRewrite[], decisions: readonly Decision[], live?: readonly Decision[], withheld?: ReadonlySet<CommitRewrite>): Escalation[];
+/** The minimal policy shape the escalation scan needs — a structural subset of
+ *  constitution PolicySpec, so this module stays dependency-free of the
+ *  Constitution schemas (core must not import constitution). */
+export interface PolicyLite {
+    id: string;
+    state: string;
+    statement: string;
+    proof: string | null;
+    authority: unknown;
+    activation_gate?: {
+        kind: string;
+        status: string;
+        reason: string;
+    } | null;
+    /** the policy's most recent audit action, when the caller has it — lets the
+     *  scan surface auto-repaired policies that need a fresh proof. */
+    last_action?: string | null;
+}
+/** The Constitution's genuine human moments (§59.5.3), framed as inline questions:
+ *  a candidate awaiting review, and a proposed policy whose next step (prove, or
+ *  accept/reject) is a human call. Machine conclusions never appear here as
+ *  approvals — every entry is a QUESTION with its explicit resolution verb. */
+export declare function policyEscalations(policies: readonly PolicyLite[]): Escalation[];