@davesheffer/hunch 1.31.0 → 1.32.0

package/dist/synthesis/provider.d.ts

@@ -0,0 +1,307 @@
+import { type DiffAnalysis } from "../extractors/diff.js";
+import type { Decision } from "../core/types.js";
+/**
+ * Run a command, optionally feeding `input` to its stdin, and resolve its
+ * stdout. Uses spawn (not execFile) so we can:
+ *   1. Pass untrusted content (the prompt/diff) via STDIN, never as an argv
+ *      element — so a `shell:true` resolution can't shell-interpret it.
+ *   2. Resolve Windows shims: the npm `claude` is a `.cmd`/`.ps1`, which
+ *      `execFile` (CreateProcess, *.exe only) cannot launch → it threw ENOENT
+ *      and made the CLI provider look unavailable on Windows. `shell:true` on
+ *      win32 routes through cmd.exe so the shim resolves. Safe here because
+ *      every argv we pass is a trusted, space-free flag (the prompt is stdin).
+ */
+export declare function pexecIn(cmd: string, args: string[], opts?: {
+    input?: string;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    timeout?: number;
+    maxBuffer?: number;
+}): Promise<{
+    stdout: string;
+}>;
+export interface DecisionDraft {
+    title: string;
+    context: string;
+    decision: string;
+    consequences: string[];
+    alternatives_rejected: string[];
+    confidence: number;
+    source: string;
+    samples?: number;
+    agreement?: number;
+    grounded?: number;
+    pruned?: number;
+    verifyOutcome?: "applied" | "unavailable" | "failed";
+    fellBackTo?: string;
+    fallbackReason?: 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);
+ *  the lists name draft entries the evidence does NOT support (likely hallucinated).
+ *  Used to PRUNE unsupported alternatives/consequences and to LOWER confidence —
+ *  never to raise it or arm enforcement (auto stays advisory; dec_9a2f2fe72a). */
+export interface VerifyVerdict {
+    grounded: number;
+    unsupported_alternatives: string[];
+    unsupported_claims: string[];
+}
+export interface BugDraft {
+    title: string;
+    symptom: string;
+    root_cause: string;
+    severity: "low" | "medium" | "high" | "critical";
+    confidence: number;
+    source: string;
+    fellBackTo?: string;
+    fallbackReason?: string;
+}
+/** A harness judgment of one auto-drafted decision, used by `hunch auto-review`
+ *  to decide keep vs delete. `relevant` = does this record a real, reusable design
+ *  choice worth keeping (not noise, not a mechanical restatement)? `duplicate_of`
+ *  names an existing decision id this merely restates. The judge NEVER approves —
+ *  approval stays gated on the Critic's grounding (dec_a466655539); this only adds
+ *  the "is it worth keeping at all" signal the deterministic layers can't express. */
+export interface RelevanceVerdict {
+    relevant: boolean;
+    /** 0..1 confidence in the relevance call. */
+    confidence: number;
+    /** id of an existing decision this draft duplicates, or null. */
+    duplicate_of: string | null;
+    /** one-line justification (for the review plan / audit trail). */
+    reason: string;
+}
+/** A decision already in the store, reduced to what the relevance judge needs. */
+export interface ExistingDecisionRef {
+    id: string;
+    title: string;
+    decision: string;
+}
+export interface CommitInput {
+    subject: string;
+    body: string;
+    files: string[];
+    diff: string;
+    /** structured "what changed" — lets even the no-LLM path be informative */
+    analysis?: DiffAnalysis;
+}
+export interface FailureInput {
+    test: string;
+    message: string;
+    recentDiff: string;
+    suspects: string[];
+}
+export interface SynthProvider {
+    readonly name: string;
+    available(): Promise<boolean>;
+    draftDecision(input: CommitInput): Promise<DecisionDraft>;
+    draftBug(input: FailureInput): Promise<BugDraft>;
+    /** Optional skeptical audit of a draft against its commit (the Critic pass).
+     *  Only LLM-backed providers implement it; the deterministic provider
+     *  and the bare ensemble omit it, so callers must feature-detect. */
+    verifyDecision?(input: CommitInput, draft: DecisionDraft): Promise<VerifyVerdict>;
+    /** Optional free-form grounded prose (the wiki's Overview section). LLM-backed
+     *  providers implement it through their normal guarded transport, so callers
+     *  must feature-detect and degrade to a deterministic template when absent. */
+    draftProse?(prompt: string): Promise<string>;
+    /** Optional harness judgment of an auto-drafted decision's relevance, for
+     *  `hunch auto-review`. Only LLM-backed providers implement it, so callers
+     *  feature-detect. */
+    judgeDraft?(draft: Decision, existing: ExistingDecisionRef[]): Promise<RelevanceVerdict>;
+}
+/** Every selectable synthesis mode. `auto` is a preference value rather than a
+ * provider: it resolves the invocation's origin without choosing by availability.
+ * "openai-compat" is the opt-in local/self-hosted HTTP provider (Ollama, vLLM,
+ * LM Studio, ...) — not a subscription, but explicitly selectable like one. */
+export declare const SYNTH_PROVIDER_NAMES: readonly ["claude-cli", "codex-cli", "cursor-agent", "kimi-cli", "openai-compat", "deterministic"];
+export declare const SYNTH_PREFERENCES: readonly ["auto", "claude-cli", "codex-cli", "cursor-agent", "kimi-cli", "openai-compat", "deterministic"];
+export type SynthProviderName = (typeof SYNTH_PROVIDER_NAMES)[number];
+export type SynthPreference = (typeof SYNTH_PREFERENCES)[number];
+export interface ProviderStatus {
+    name: SynthProviderName;
+    label: string;
+    subscription: string | null;
+    available: boolean;
+}
+export interface ProviderResolution {
+    provider: SynthProvider;
+    /** Why this provider was chosen. `ambiguous` is intentionally deterministic. */
+    source: "environment" | "local" | "single-available" | "ambiguous" | "none" | "unavailable-preference" | "initiator" | "unavailable-initiator" | "unknown-initiator";
+    initiator?: string | null;
+    preference: SynthPreference;
+    statuses: ProviderStatus[];
+}
+export interface ProviderSelectionOptions {
+    /** Repo root used for the gitignored, per-user `.hunch/local.json` preference. */
+    root?: string;
+    /** Injectable for tests; defaults to process.env. */
+    env?: NodeJS.ProcessEnv;
+    /** Injectable for tests; normal callers use the built-in CLI registry. */
+    providers?: readonly SynthProvider[];
+    /** Explicit local CLI adapter config; never loaded automatically from repository content. */
+    cliConfig?: string;
+}
+type PromptOutput = "json" | "text";
+declare abstract class PromptSynthProvider implements SynthProvider {
+    abstract readonly name: string;
+    abstract available(): Promise<boolean>;
+    protected abstract run(prompt: string, output?: PromptOutput): Promise<string>;
+    /** Run a CLI with the prompt on stdin, stripping API-key env vars so the tool
+     *  falls through to its SUBSCRIPTION credentials. Shared by codex/cursor. */
+    protected runCli(bin: string, args: string[], stripEnv: string[], prompt: string, timeoutMs?: number): Promise<string>;
+    draftDecision(input: CommitInput): Promise<DecisionDraft>;
+    draftBug(input: FailureInput): Promise<BugDraft>;
+    /** Grounded prose for the wiki. Uses text mode rather than the structured JSON
+     *  mode required by the record mappers. Throws on empty output so the caller
+     *  falls back to its deterministic template page. */
+    draftProse(prompt: string): Promise<string>;
+    /** The Critic pass: audit a draft against its commit through the provider's
+     *  guarded transport.
+     *  Throws on unusable output so verifyDecisionSafe degrades to the un-audited
+     *  draft (a verifier failure must never lose the draft — dec_18a81c8291). */
+    verifyDecision(input: CommitInput, draft: DecisionDraft): Promise<VerifyVerdict>;
+    /** Judge whether an auto-drafted decision is worth keeping (for auto-review).
+     *  Uses the provider's guarded transport. Throws on unusable
+     *  output so the caller can degrade to a keep-for-human verdict. */
+    judgeDraft(draft: Decision, existing: ExistingDecisionRef[]): Promise<RelevanceVerdict>;
+}
+export declare function safeModel(v: string | undefined, fallback: string): string;
+export declare function safeModel(v: string | undefined, fallback: undefined): string | undefined;
+/** Build the non-interactive Codex invocation used from Hunch's neutral temp
+ * directory. Codex normally refuses to start outside a trusted Git repository;
+ * the explicit skip flag preserves that neutral-cwd isolation without loading a
+ * target repo's agent rules or MCP configuration. */
+export declare function codexExecArgs(model?: string): string[];
+export declare function safeTimeout(v: string | undefined, fallback: number): number;
+export declare function safeMaxTokens(v: string | undefined, fallback: number): number;
+export declare function meteredHostsAllowed(env?: NodeJS.ProcessEnv): boolean;
+export declare class OpenAICompatProvider extends PromptSynthProvider {
+    readonly name = "openai-compat";
+    available(): Promise<boolean>;
+    protected run(prompt: string, output?: PromptOutput): Promise<string>;
+}
+/** Best-effort: does the configured openai-compat endpoint look like Ollama with
+ *  an UNSET num_ctx? Returns
+ *  an advisory warning string when so, or null when the endpoint isn't reachable,
+ *  doesn't look like Ollama's /api/show shape, or already has num_ctx set — this
+ *  is diagnostics only, never thrown, never blocking. Deliberately does NOT try to
+ *  report the model's effective context length: modern Ollama defaults may come
+ *  from server configuration or VRAM tiers, and model_info keys are not a stable
+ *  parse target. We therefore report only the observed fact — whether num_ctx is
+ *  pinned in the model — without guessing an effective token count. */
+export declare function probeOllamaNumCtx(baseUrl: string, model: string): Promise<string | null>;
+export declare class DeterministicProvider implements SynthProvider {
+    readonly name = "deterministic";
+    available(): Promise<boolean>;
+    draftDecision(input: CommitInput): Promise<DecisionDraft>;
+    draftBug(input: FailureInput): Promise<BugDraft>;
+}
+/** Extract the final assistant message from `codex exec --json` output (newline-
+ *  delimited JSON events). Codex tags assistant turns as `item.type ==="agent_message"`,
+ *  but it ALSO emits `item.text` for reasoning and may append trailing events — so we
+ *  prefer the last AGENT message and only fall back to the last any-text when none is
+ *  tagged. If nothing parses, hand the raw output to the mapper (→ it finds the JSON
+ *  draft or throws → deterministic fallback). Tolerant by design: drift degrades, never crashes. */
+export declare function extractCodexText(out: string): string;
+/** Test-only: clears the availability memoization cache so a test that toggles
+ *  env vars mid-process (e.g. HUNCH_SYNTH_BASE_URL) isn't served a stale result
+ *  cached by an earlier call in the same process. Never call from production code. */
+export declare function __resetAvailabilityCacheForTests(): void;
+/** "ollama" is accepted as an alias for "openai-compat" — the provider is not
+ *  Ollama-specific (it speaks the OpenAI chat-completions format any self-hosted
+ *  server can implement), but Ollama is the most common self-hosted target and
+ *  users reach for that name first. Applied to the HUNCH_SYNTH_PROVIDER env var in
+ *  resolveSynthesisProvider below, and exported so the `hunch provider <name>` CLI
+ *  command (index.ts) normalizes it the same way before validating/persisting a
+ *  local preference — the two paths must agree, or a user who sets one and reads
+ *  the other back gets a confusing "unknown provider" message for a name that
+ *  actually works. */
+export declare function normalizeProviderName(v: string | undefined): string | undefined;
+/** Read a per-user, gitignored choice. Invalid/missing local state is treated as auto;
+ * `writeSynthesisPreference` refuses to overwrite malformed data so this forgiveness
+ * never destroys someone else's local settings. */
+export declare function readSynthesisPreference(root: string): SynthPreference;
+/** Persist the user's provider choice only in `.hunch/local.json`, which is never a
+ * repository policy. That means each developer controls their own subscription spend. */
+export declare function writeSynthesisPreference(root: string, preference: SynthPreference): void;
+/** Respect offline mode, then bind to invocation origin. Explicit terminal preferences
+ * apply only without an agent origin; installed executables never select an account. */
+export declare function resolveSynthesisProvider(opts?: ProviderSelectionOptions): Promise<ProviderResolution>;
+/** The provider used by normal synthesis. See `resolveSynthesisProvider` for a
+ * diagnosable result with the selection source and every candidate's availability. */
+export declare function selectProvider(opts?: ProviderSelectionOptions): Promise<SynthProvider>;
+/** Only the resolved origin-bound worker. No cross-account fan-out. */
+export declare function selectWorkers(opts?: ProviderSelectionOptions): Promise<SynthProvider[]>;
+/** Reconcile N worker drafts into one. DETERMINISTIC (no second LLM call): the richest
+ *  draft is the spine; alternatives/consequences are unioned; confidence is AGREEMENT-
+ *  WEIGHTED and CAPPED at 0.78 — below STRICT_MIN_CONFIDENCE (0.8) — so an ensemble
+ *  auto-draft can never arm enforcement. `samples`/`agreement` ride along as advisory
+ *  telemetry for `hunch review` (not schema-bound). */
+export declare function mergeDecisionDrafts(drafts: DecisionDraft[]): DecisionDraft;
+export declare class EnsembleProvider implements SynthProvider {
+    private readonly workers;
+    readonly name = "ensemble";
+    private readonly samples;
+    constructor(workers: SynthProvider[], opts?: {
+        samples?: number;
+    });
+    available(): Promise<boolean>;
+    /** Production selection supplies one origin-bound worker with N samples.
+     * Direct callers can also supply multiple workers subject to origin checks. */
+    private decisionTasks;
+    draftDecision(input: CommitInput): Promise<DecisionDraft>;
+    draftBug(input: FailureInput): Promise<BugDraft>;
+}
+/** Build the Deep-Synthesis provider, or null if no LLM provider is available
+ *  (the caller then falls back to the normal single-provider path). `samples` sets
+ *  the self-consistency depth for the single-provider case. */
+export declare function selectEnsemble(opts?: ProviderSelectionOptions & {
+    samples?: number;
+}): Promise<EnsembleProvider | null>;
+/** Pick a provider to run the Critic pass — the same resolved provider normal
+ *  synthesis would use (subscription CLI or the opt-in openai-compat endpoint),
+ *  honoring the same env/local-preference/auto policy. Returns null when that
+ *  resolves to the deterministic fallback — verification then no-ops and the
+ *  un-audited draft stands (graceful degradation; dec_18a81c8291). */
+export declare function selectVerifier(opts?: ProviderSelectionOptions): Promise<SynthProvider | null>;
+/** Map model text → RelevanceVerdict, or null when nothing usable parses (→ the
+ *  caller keeps the draft for a human). Tolerant of missing/loose fields. */
+export declare function relevanceFromText(text: string): RelevanceVerdict | null;
+/** Map model text → VerifyVerdict, or null when nothing usable parses (→ the caller
+ *  keeps the un-audited draft). Tolerant of arrays-as-strings and missing fields. */
+export declare function verdictFromText(text: string): VerifyVerdict | null;
+/** Apply a verdict to a draft: drop unsupported alternatives (so they never scaffold
+ *  tripwires) and consequences, and scale confidence DOWN by grounding. Confidence is
+ *  clamped so it can only fall — verification never arms a stronger claim than the
+ *  draft already made (R2). Records `grounded` as advisory telemetry. */
+export declare function applyVerdict(draft: DecisionDraft, v: VerifyVerdict): DecisionDraft;
+/** Run the Critic pass and apply it, degrading to the un-audited draft when the
+ *  provider can't verify (deterministic / no CLI) or the call keeps failing. Never
+ *  throws. Marks the OUTCOME on the draft (applied / unavailable / failed) so the
+ *  degradation is visible in telemetry instead of silent. Retries once: under --deep
+ *  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>;
+/** 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
+ *  do their own content-based selection; this is just a generic accessor.) */
+export declare function extractJson(text: string): Record<string, unknown> | null;
+/** Map model text → DecisionDraft, or null when there's nothing usable to keep.
+ *  Null (not a hollow draft) is the signal for the caller to fall back to the
+ *  deterministic provider — we only claim "llm_draft" when the LLM actually
+ *  produced substance. The model is asked for ONE object; if it emits several (a
+ *  template/example plus the answer), take the FIRST with real (non-placeholder)
+ *  substance — robust whether the junk leads or trails the answer. */
+export declare function decisionDraftFromText(text: string, fallbackTitle: string): DecisionDraft | null;
+/** Map model text → BugDraft, or null. A root_cause is the LLM's full value-add;
+ *  a deliberate non-"medium" severity is worth keeping on its own (it carries the
+ *  LLM's classification into the bug record rather than the deterministic "medium").
+ *  Pick the BEST candidate object — most substantiated (root-caused) then most
+ *  severe — NOT the positionally first/last, so a trailing low-severity recap can't
+ *  downgrade a real critical finding. Without a root_cause the draft is labeled
+ *  honestly as partial at lower confidence; constraint promotion is gated on a real
+ *  root_cause downstream (see shouldPromoteConstraint), so a bare severity label
+ *  preserves its signal in the record without auto-minting an invariant. */
+export declare function bugDraftFromText(text: string, fallbackTitle: string, fallbackSymptom: string): BugDraft | null;
+export {};

package/dist/synthesis/synthesize.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The learning loop's write step (DESIGN.md §4, §5 "write_back").
+ *   - syncCommit:   commit diff -> Claude/heuristic -> Decision draft -> Hunch
+ *   - recordFailure: failing test -> suspect ranking -> Bug draft -> Hunch
+ *
+ * Idempotent: a Decision id is derived from (commit, title) so re-running sync on
+ * the same commit updates rather than duplicates. New records are LOW-confidence
+ * and `proposed` until confirmed — advisory and cheap to discard.
+ */
+import type { HunchStore } from "../store/hunchStore.js";
+import { type DiffAnalysis } from "../extractors/diff.js";
+import { type SynthProvider, type DecisionDraft, type BugDraft, type CommitInput, type FailureInput } from "./provider.js";
+import type { Decision, Bug, Constraint } from "../core/types.js";
+import type { TestReport } from "../extractors/testreport.js";
+export interface SyncResult {
+    status: "written" | "skipped";
+    reason?: string;
+    decision?: Decision;
+    provider?: string;
+}
+/** Trivial-subject commits (merge/revert/bump/format/...) are noise UNLESS the body
+ *  carries real content — a squash/PR description often lands there, not on the
+ *  subject. Gated on body length ALONE (not the full isSignificant() heuristic): a
+ *  large auto-generated reformat or dependency-bump diff with no narrative must stay
+ *  skipped even though it would trip isSignificant()'s line/file/structural checks. */
+export declare function isTrivialSubject(meta: {
+    subject: string;
+    body: string;
+}): boolean;
+/** Is a commit substantive enough to spend a paid LLM synthesis call on? Pure and
+ *  deterministic. Any structural change (symbol/dependency delta), non-trivial
+ *  churn, several files, OR an explanatory commit body signals a real decision
+ *  worth the model. Everything below (typo/tweak/one-liner with no message) falls
+ *  to the free deterministic draft — shallower but honestly low-confidence.
+ *  `files` is whatever the caller is synthesizing from (code and/or markdown, per
+ *  isSubstantive) — the line/file-count checks are format-agnostic. */
+export declare function isSignificant(meta: {
+    body: string;
+}, a: DiffAnalysis, files: string[]): boolean;
+/** Capture a Decision from a commit. Defaults to HEAD. Pass `{ force: true }` to
+ *  re-synthesize a commit that already has an (auto-drafted) decision. */
+export declare function syncCommit(store: HunchStore, root: string, sha?: string, opts?: {
+    force?: boolean;
+    private?: boolean;
+    home?: "public" | "private";
+    localOnly?: boolean;
+    deep?: boolean;
+    verify?: boolean;
+    samples?: number;
+}): Promise<SyncResult>;
+export interface FailureResult {
+    status: "written";
+    bug: Bug;
+    constraint?: Constraint;
+    provider: string;
+    touchedHomes: Array<"public" | "private">;
+}
+/** Capture a Bug from a test failure. Suspects are ranked churn×recency×fan-in. */
+export declare function recordFailure(store: HunchStore, root: string, failure: {
+    test: string;
+    message: string;
+    recentDiff?: string;
+}, opts?: {
+    private?: boolean;
+}): Promise<FailureResult>;
+export interface CapturedFailure {
+    bug: Bug;
+    constraint?: Constraint;
+}
+export interface TestRunCapture {
+    results: CapturedFailure[];
+    /** Bugs resolved because their test now passes. */
+    fixed: Bug[];
+    /** True when the output wasn't recognized TAP/spec and we captured one coarse bug. */
+    fallback: boolean;
+    touchedHomes: Array<"public" | "private">;
+}
+/** Orchestrate one `hunch test` run into graph writes: capture each failing test
+ *  as a Bug (recordFailure → suspects / recurrence / Constraint promotion), and
+ *  resolve any open Bug whose test now passes. Kept free of console I/O so the
+ *  whole capture→resolve→promote loop is unit-testable. Does NOT reindex — the
+ *  caller does, once. `status` is the runner's exit code (null if unknown). */
+export declare function captureTestRun(store: HunchStore, root: string, input: {
+    report: TestReport;
+    status: number | null;
+    cmd: string;
+    output: string;
+    private?: boolean;
+}): Promise<TestRunCapture>;
+/** Whether a bug should auto-promote a regression Constraint (a do-not-break
+ *  invariant). A recurrence always does. Otherwise it must be high/critical AND
+ *  substantiated by a real root cause — a bare severity label with no analysis
+ *  (e.g. an LLM "test_failure+llm_partial" draft) keeps its severity on the bug
+ *  record for human review but must not silently mint an invariant from thin air. */
+export declare function shouldPromoteConstraint(severity: Bug["severity"], rootCause: string, isRecurrence: boolean): boolean;
+/** Turn a bug into a regression constraint scoped to its files.
+ *
+ *  Severity policy mirrors buildCorrectionConstraint's scope-footgun guard, for the
+ *  same reason: a BLOCKING constraint DENIES edits under strict firmness, and neither
+ *  input here is human-confirmed. `bug.severity` is whatever the synthesis provider's
+ *  enum emitted (provenance "derived", an LLM label no human saw), and `affected_files`
+ *  is EMPTY whenever suspect ranking resolves nothing — the common case for a failure
+ *  that names no known symbol. Left unguarded those compose into the worst outcome:
+ *  one model-labeled "critical" failure with no resolvable suspects mints
+ *  scope ["**"] + severity "blocking", a repo-wide deny on every subsequent edit.
+ *
+ *  So blocking requires BOTH a real file scope AND deterministic corroboration — a
+ *  recurrence, meaning the graph itself already saw and closed this symptom. Everything
+ *  else lands as a warning: still surfaced at edit time and in CI, and still promotable
+ *  by a human via `hunch record-constraint`, but never an automatic deny.
+ *
+ *  Exported for the same reason as shouldPromoteConstraint — it is policy, and policy
+ *  should be provable without spinning up a provider. */
+export declare function shouldBlockOnPromotion(severity: Bug["severity"], affectedFiles: string[], isRecurrence: boolean): boolean;
+export declare function salientTerms(text: string): Set<string>;
+export declare function draftDecisionSafe(provider: SynthProvider, input: CommitInput): Promise<DecisionDraft>;
+export declare function draftBugSafe(provider: SynthProvider, input: FailureInput): Promise<BugDraft>;

package/dist/synthesis/tripwires.d.ts

@@ -0,0 +1,9 @@
+import type { RejectedTripwire } from "../core/types.js";
+/** Scaffold one draft tripwire per rejected alternative. Scope = directory globs of
+ *  the decision's related files. `forbids` is best-effort from the prose: known repo
+ *  dependencies named in the text, plus backticked identifiers as candidate symbols.
+ *  Empty `forbids` is fine — the tripwire is then inert until a human fills it in. */
+export declare function draftTripwires(alternatives: string[], relatedFiles: string[], knownDeps: string[]): RejectedTripwire[];
+/** External dependency names declared in the repo's package.json (every section),
+ *  used to recognise a dep named in a rejected-alternative sentence. */
+export declare function knownRepoDeps(root: string): string[];

package/dist/taskReports.d.ts

@@ -0,0 +1,76 @@
+import { type ReportClaim, type ReportRecord, type LessonReference } from "./core/taskReport.js";
+import { runReportCheck } from "./core/taskReportEvidence.js";
+import type { DeliveryEnvelope } from "./core/delivery.js";
+export type { TaskReport, ReportTask, ReportClaim, ReportCheck, ReportConformance, ReportSave, ReportDurability, ReportRefusal, ReportRecord, TaskDelivery, LessonReference, LessonHistory } from "./core/taskReport.js";
+export { TASK_REPORT_SCHEMA, TaskIdSchema } from "./core/taskReport.js";
+export { renderTaskReport, renderTaskReportHtml } from "./core/taskReportRender.js";
+/** Create this only after authorizing a local repository/worktree. A task ID is
+ * a correlation reference, never an access token. Remote adapters must enforce
+ * their own principal/partition boundary before reaching this local API. */
+export declare function createTaskReporter(root: string): {
+    /** Omit identity for a fresh task, or supply the harness's stable task AND
+     * execution attempt for idempotent retries. Raw identities are not retained. */
+    start(title: string, identity?: {
+        task: string;
+        attempt: string;
+    }): {
+        task_id: string;
+        scope: string;
+        title: string;
+        started_at: string;
+        finished_at: string | null;
+        state: "open" | "completed" | "interrupted";
+    };
+    /** The caller supplies the exact envelope it issued plus snapshots of the
+     * included revisions. Return the occurrence with the context to the agent.
+     * Issuance alone does not prove the model applied or even attended to it. */
+    delivered(taskId: string, envelope: DeliveryEnvelope, records: ReportRecord[], occurrenceId?: string): string;
+    applied(taskId: string, claim: ReportClaim): string;
+    /** Runs locally as argv, without a shell. Only use commands authorized by
+     * the task owner. This API does not accept remote claimed-success receipts. */
+    verify(taskId: string, command: string[], label: string, options?: Parameters<typeof runReportCheck>[5]): Promise<{
+        label: string;
+        command: string[];
+        exit_code: number | null;
+        output_hash: string;
+        before_snapshot: string | null;
+        after_snapshot: string | null;
+        snapshot_limitations: string[];
+        timed_out: boolean;
+        source: "local-command-runner";
+        check_id?: string | undefined;
+        cancelled?: boolean | undefined;
+    }>;
+    /** Hunch evaluates each delivered lesson's declared rule against the changed
+     * files. Deterministic and local; the harness supplies no verdict. */
+    conform(taskId: string): {
+        source: "local-rule-check";
+        record_id: string;
+        kind: "decisions" | "constraints";
+        content_hash: string;
+        rule: "constraint-forbids" | "decision-conformance";
+        outcome: "satisfied" | "violated" | "not-exercised" | "unavailable";
+        files: string[];
+        snapshot: string | null;
+        detail: string;
+    }[];
+    finish(taskId: string, outcome?: "completed" | "interrupted"): {
+        report: import("./core/taskReport.js").TaskReport;
+        contribution_card: string | null;
+    };
+    report: (taskId: string) => import("./core/taskReport.js").TaskReport;
+    history: () => {
+        task_id: string;
+        scope: string;
+        title: string;
+        started_at: string;
+        finished_at: string | null;
+        state: "open" | "completed" | "interrupted";
+    }[];
+    lesson: (reference: LessonReference, options?: {
+        limit?: number;
+        before?: number;
+    }) => import("./core/taskReport.js").LessonHistory;
+    html: (taskId: string, publicOnly?: boolean) => string;
+};
+export type TaskReporter = ReturnType<typeof createTaskReporter>;

package/dist/taskReports.js

@@ -0,0 +1,67 @@
+/** Provider-neutral, local engine integration. The authorized harness owns
+ * lifecycle and display; neither operation depends on model compliance. */
+import { realpathSync } from "node:fs";
+import { z } from "zod";
+import { finishReportTask, listReportTasks, readTaskReport, readLessonHistory, recordReportClaim, recordTaskDelivery, reportHash, reportPresentationEnabled, startReportTask } from "./core/taskReport.js";
+import { reportSourceSnapshot, runReportCheck, runReportConformance } from "./core/taskReportEvidence.js";
+import { renderTaskReport, writeTaskReportHtml } from "./core/taskReportRender.js";
+import { hunchPaths } from "./core/paths.js";
+import { HunchStore } from "./store/hunchStore.js";
+export { TASK_REPORT_SCHEMA, TaskIdSchema } from "./core/taskReport.js";
+export { renderTaskReport, renderTaskReportHtml } from "./core/taskReportRender.js";
+const IdentitySchema = z.object({ task: z.string().min(1).max(1024), attempt: z.string().min(1).max(1024) }).strict();
+/** Create this only after authorizing a local repository/worktree. A task ID is
+ * a correlation reference, never an access token. Remote adapters must enforce
+ * their own principal/partition boundary before reaching this local API. */
+export function createTaskReporter(root) {
+    const scope = realpathSync(root);
+    const report = (taskId) => readTaskReport(scope, taskId, reportSourceSnapshot(scope).hash);
+    return {
+        /** Omit identity for a fresh task, or supply the harness's stable task AND
+         * execution attempt for idempotent retries. Raw identities are not retained. */
+        start(title, identity) {
+            const key = identity === undefined ? undefined : IdentitySchema.parse(identity);
+            const id = key ? `htask_${reportHash([scope, "hunch.harness-task/1", key]).slice(7, 31)}` : undefined;
+            return startReportTask(scope, title, id);
+        },
+        /** The caller supplies the exact envelope it issued plus snapshots of the
+         * included revisions. Return the occurrence with the context to the agent.
+         * Issuance alone does not prove the model applied or even attended to it. */
+        delivered(taskId, envelope, records, occurrenceId) {
+            return recordTaskDelivery(scope, taskId, envelope, records, occurrenceId);
+        },
+        applied(taskId, claim) { return recordReportClaim(scope, taskId, claim); },
+        /** Runs locally as argv, without a shell. Only use commands authorized by
+         * the task owner. This API does not accept remote claimed-success receipts. */
+        verify(taskId, command, label, options) {
+            return runReportCheck(scope, taskId, command, label, 120_000, options);
+        },
+        /** Hunch evaluates each delivered lesson's declared rule against the changed
+         * files. Deterministic and local; the harness supplies no verdict. */
+        conform(taskId) {
+            const store = new HunchStore(hunchPaths(scope));
+            try {
+                return runReportConformance(scope, store, taskId);
+            }
+            finally {
+                store.close();
+            }
+        },
+        finish(taskId, outcome = "completed") {
+            if (outcome === "completed") {
+                try {
+                    this.conform(taskId);
+                }
+                catch { /* the report's unknowns disclose it */ }
+            }
+            finishReportTask(scope, taskId, outcome);
+            const result = report(taskId);
+            return { report: result, contribution_card: reportPresentationEnabled(scope) ? renderTaskReport(result) : null };
+        },
+        report,
+        history: () => listReportTasks(scope),
+        lesson: (reference, options) => readLessonHistory(scope, reference, options),
+        html: (taskId, publicOnly = false) => writeTaskReportHtml(scope, taskId, publicOnly),
+    };
+}
+//# sourceMappingURL=taskReports.js.map

package/dist/wiki/adopt.d.ts

@@ -0,0 +1,22 @@
+import type { Decision } from "../core/types.js";
+import type { RepoDoc } from "../core/docscan.js";
+/** Page slug for an adopted doc: full rel path, kebab-cased ("docs/api-v2.md" →
+ *  "docs-api-v2"). Kebab-casing can collide across DIFFERENT rels ("docs/api-v2.md"
+ *  vs "docs-api/v2.md"), so a `taken` set disambiguates with a short content hash
+ *  of the rel — deterministic, and wikiStatus is the single caller that assigns
+ *  slugs (renderers receive the resulting paths; they never re-derive). */
+export declare function adoptedSlug(rel: string, taken: Set<string>): string;
+/** The freshness hash of an adopted copy: source content + what the graph
+ *  currently says for each pinned topic (everything the renderer quotes,
+ *  including rejected alternatives) + the grade's issues. Any of these moving
+ *  re-heals the copy; the copy's own bytes are never an input. */
+export declare function adoptionHash(content: string, decisions: readonly Decision[], doc: RepoDoc): string;
+/** Prompt for the optional PROSE-HEAL tier (dec roadmap.adoption-prose-heal):
+ *  a subscription-CLI rewrite of what the stale doc SHOULD say now. The output
+ *  is garnish on the deterministic skeleton — never hashed, never a substitute
+ *  for the graph corrections rendered below it. */
+export declare function adoptProsePrompt(doc: RepoDoc, content: string, decisions: readonly Decision[]): string;
+/** Render the wiki-managed copy of a stale doc, healed against the graph.
+ *  `reconciled` (optional, LLM prose-heal) slots in under the banner; the
+ *  deterministic corrections below remain the authoritative layer. */
+export declare function renderAdoptedDoc(doc: RepoDoc, content: string, decisions: readonly Decision[], reconciled?: string | null): string;