aidimag 1.0.0

package/dist/capture/pr-miner.d.ts

@@ -0,0 +1,57 @@
+/**
+ * PR miner (Part 2 idea #4 — PR/review-comment capture).
+ *
+ * Mines merged GitHub pull requests — title, description, and crucially the
+ * REVIEW COMMENTS (where humans say "don't do X here", "we always Y", "this
+ * broke prod last time") — into memory proposals via the same LLM extraction
+ * contract as `dim mine --llm` and `dim harvest`.
+ *
+ * Uses the `gh` CLI (already authenticated on the developer's machine), so no
+ * token handling here. Cursor-tracked by merge time; every proposal is
+ * anchored to the PR's merge commit (COMMIT_REF) so verification can re-check
+ * it, and carries the reviewer's verbatim words in the rationale.
+ *
+ * Proposals land in the review queue (source `pr-miner`) — never directly in
+ * memory.
+ */
+import type { Proposal } from "../types.js";
+import type { MemoryStore } from "../db/store.js";
+export interface MinedPr {
+    number: number;
+    title: string;
+    body: string;
+    mergedAt: string;
+    mergeCommitSha: string | null;
+    headRefName: string;
+    files: string[];
+    /** review comments + top-level reviews, oldest first */
+    comments: Array<{
+        author: string;
+        path: string | null;
+        body: string;
+    }>;
+}
+export interface PrMineResult {
+    scanned: number;
+    proposed: Proposal[];
+    skippedDuplicates: number;
+    provider: string | null;
+}
+/** True if the `gh` CLI is installed and authenticated for this repo's host. */
+export declare function ghAvailable(repoRoot: string): boolean;
+/** List merged PRs (newest first), stopping at the cursor. */
+export declare function listMergedPrs(repoRoot: string, sinceMergedAt: string | null, limit?: number): MinedPr[];
+/** Fetch review comments (inline, with file paths) + review bodies for one PR. */
+export declare function fetchPrComments(repoRoot: string, prNumber: number): MinedPr["comments"];
+export declare const PR_EXTRACT_INSTRUCTIONS = "You are mining a merged GitHub pull request \u2014 its description and especially its REVIEW COMMENTS \u2014 for durable, project-specific knowledge worth remembering across AI coding sessions.\n\nReview comments are where senior engineers state the unwritten rules: \"we never call the DB from controllers\", \"this exact retry pattern caused the March outage\", \"always use the factory here\". Those are the claims to extract.\n\nRules:\n1. Most PRs contain NOTHING durable \u2014 routine reviews (\"nit\", \"LGTM\", style back-and-forth). Return zero claims for those. Do NOT invent.\n2. SYNTHESIZE falsifiable claims about the codebase \u2014 do not parrot the comment. Include the WHY when a reviewer gives one.\n3. Prefer claims grounded in review comments over the PR description; keep the reviewer's key phrase in the rationale.\n4. kinds: DECISION, CONVENTION, GOTCHA, FAILED_APPROACH, ARCHITECTURE, INVARIANT, GUARDRAIL (guardrail_level never|ask-first|always), SKILL, TODO_CONTEXT.\n5. Scope with the commented file paths; add \"static_check\" (cheap shell command, exit 0 iff true) when an honest one exists.\n6. 0\u20133 claims per PR. Zero is the common case.\n\nRespond with ONLY: {\"claims\":[{\"kind\":\"CONVENTION\",\"claim\":\"...\",\"paths\":[\"src/x\"],\"symbols\":[],\"guardrail_level\":null,\"rationale\":\"...\",\"static_check\":null}]}";
+export declare function buildPrPrompt(pr: MinedPr): string;
+/**
+ * Mine merged PRs since the cursor. Requires the `gh` CLI and an LLM
+ * provider; returns provider:null when no provider is available (the CLI
+ * explains how to get one — there is no regex fallback here because review
+ * threads need synthesis, and `dim mine` already covers merge-commit bodies).
+ */
+export declare function minePrs(store: MemoryStore, repoRoot: string, opts?: {
+    max?: number;
+    all?: boolean;
+}): Promise<PrMineResult>;

package/dist/capture/pr-miner.js

@@ -0,0 +1,185 @@
+/**
+ * PR miner (Part 2 idea #4 — PR/review-comment capture).
+ *
+ * Mines merged GitHub pull requests — title, description, and crucially the
+ * REVIEW COMMENTS (where humans say "don't do X here", "we always Y", "this
+ * broke prod last time") — into memory proposals via the same LLM extraction
+ * contract as `dim mine --llm` and `dim harvest`.
+ *
+ * Uses the `gh` CLI (already authenticated on the developer's machine), so no
+ * token handling here. Cursor-tracked by merge time; every proposal is
+ * anchored to the PR's merge commit (COMMIT_REF) so verification can re-check
+ * it, and carries the reviewer's verbatim words in the rationale.
+ *
+ * Proposals land in the review queue (source `pr-miner`) — never directly in
+ * memory.
+ */
+import { execFileSync } from "node:child_process";
+import { extractTicketId, readTicketsConfig, DEFAULT_TICKET_PATTERN } from "../tickets/provider.js";
+import { scopeFromFiles } from "./commit-miner.js";
+import { debugLog } from "../debug.js";
+const PR_CURSOR_KEY = "pr_miner_last_merged_at";
+const MAX_PRS_PER_RUN = 20; // LLM deep tier — keep runs bounded
+const MAX_COMMENT_CHARS = 800; // per comment, keeps the prompt honest
+const MAX_PROMPT_CHARS = 12_000;
+function gh(repoRoot, args) {
+    return execFileSync("gh", args, { cwd: repoRoot, encoding: "utf8", maxBuffer: 16 * 1024 * 1024 });
+}
+/** True if the `gh` CLI is installed and authenticated for this repo's host. */
+export function ghAvailable(repoRoot) {
+    try {
+        gh(repoRoot, ["auth", "status"]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** List merged PRs (newest first), stopping at the cursor. */
+export function listMergedPrs(repoRoot, sinceMergedAt, limit = MAX_PRS_PER_RUN) {
+    const raw = gh(repoRoot, [
+        "pr", "list",
+        "--state", "merged",
+        "--limit", String(limit),
+        "--json", "number,title,body,mergedAt,mergeCommit,headRefName,files",
+    ]);
+    const rows = JSON.parse(raw);
+    return rows
+        .filter((r) => !sinceMergedAt || r.mergedAt > sinceMergedAt)
+        .map((r) => ({
+        number: r.number,
+        title: r.title ?? "",
+        body: r.body ?? "",
+        mergedAt: r.mergedAt,
+        mergeCommitSha: r.mergeCommit?.oid ?? null,
+        headRefName: r.headRefName ?? "",
+        files: (r.files ?? []).map((f) => f.path),
+        comments: [],
+    }));
+}
+/** Fetch review comments (inline, with file paths) + review bodies for one PR. */
+export function fetchPrComments(repoRoot, prNumber) {
+    const comments = [];
+    // inline review comments carry the file path — the highest-signal source
+    try {
+        const raw = gh(repoRoot, ["api", `repos/{owner}/{repo}/pulls/${prNumber}/comments`, "--paginate"]);
+        for (const c of JSON.parse(raw)) {
+            if (c.body?.trim()) {
+                comments.push({ author: c.user?.login ?? "reviewer", path: c.path ?? null, body: c.body.trim() });
+            }
+        }
+    }
+    catch (err) {
+        // comments endpoint unavailable — reviews below still apply
+        debugLog(`pr #${prNumber} review comments fetch`, err);
+    }
+    // top-level review bodies ("Approving, but note that …")
+    try {
+        const raw = gh(repoRoot, ["pr", "view", String(prNumber), "--json", "reviews"]);
+        const { reviews } = JSON.parse(raw);
+        for (const r of reviews ?? []) {
+            if (r.body?.trim())
+                comments.push({ author: r.author?.login ?? "reviewer", path: null, body: r.body.trim() });
+        }
+    }
+    catch (err) {
+        // review list unavailable — PR body alone still has signal
+        debugLog(`pr #${prNumber} reviews fetch`, err);
+    }
+    return comments;
+}
+export const PR_EXTRACT_INSTRUCTIONS = `You are mining a merged GitHub pull request — its description and especially its REVIEW COMMENTS — for durable, project-specific knowledge worth remembering across AI coding sessions.
+
+Review comments are where senior engineers state the unwritten rules: "we never call the DB from controllers", "this exact retry pattern caused the March outage", "always use the factory here". Those are the claims to extract.
+
+Rules:
+1. Most PRs contain NOTHING durable — routine reviews ("nit", "LGTM", style back-and-forth). Return zero claims for those. Do NOT invent.
+2. SYNTHESIZE falsifiable claims about the codebase — do not parrot the comment. Include the WHY when a reviewer gives one.
+3. Prefer claims grounded in review comments over the PR description; keep the reviewer's key phrase in the rationale.
+4. kinds: DECISION, CONVENTION, GOTCHA, FAILED_APPROACH, ARCHITECTURE, INVARIANT, GUARDRAIL (guardrail_level never|ask-first|always), SKILL, TODO_CONTEXT.
+5. Scope with the commented file paths; add "static_check" (cheap shell command, exit 0 iff true) when an honest one exists.
+6. 0–3 claims per PR. Zero is the common case.
+
+Respond with ONLY: {"claims":[{"kind":"CONVENTION","claim":"...","paths":["src/x"],"symbols":[],"guardrail_level":null,"rationale":"...","static_check":null}]}`;
+export function buildPrPrompt(pr) {
+    const lines = [
+        `PR #${pr.number}: ${pr.title}`,
+        `Branch: ${pr.headRefName}`,
+        `Description:\n${pr.body?.trim() || "(none)"}`,
+        `Files touched: ${pr.files.slice(0, 30).join(", ") || "(unknown)"}`,
+        "",
+        `Review comments (${pr.comments.length}):`,
+    ];
+    for (const c of pr.comments) {
+        lines.push(`- @${c.author}${c.path ? ` on ${c.path}` : ""}: ${c.body.slice(0, MAX_COMMENT_CHARS)}`);
+    }
+    return lines.join("\n").slice(0, MAX_PROMPT_CHARS);
+}
+/**
+ * Mine merged PRs since the cursor. Requires the `gh` CLI and an LLM
+ * provider; returns provider:null when no provider is available (the CLI
+ * explains how to get one — there is no regex fallback here because review
+ * threads need synthesis, and `dim mine` already covers merge-commit bodies).
+ */
+export async function minePrs(store, repoRoot, opts = {}) {
+    const { getTextProvider } = await import("../knowledge/llm.js");
+    const { parseClaims } = await import("../knowledge/extract.js");
+    const provider = await getTextProvider();
+    if (!provider)
+        return { scanned: 0, proposed: [], skippedDuplicates: 0, provider: null };
+    const cursor = opts.all ? null : store.getMeta(PR_CURSOR_KEY);
+    const prs = listMergedPrs(repoRoot, cursor, Math.min(opts.max ?? MAX_PRS_PER_RUN, MAX_PRS_PER_RUN));
+    const ticketPattern = readTicketsConfig(repoRoot).pattern ?? DEFAULT_TICKET_PATTERN;
+    const proposed = [];
+    let skippedDuplicates = 0;
+    for (const pr of prs) {
+        pr.comments = fetchPrComments(repoRoot, pr.number);
+        // description-less PRs with no review discussion carry no reviewable signal
+        if (!pr.body.trim() && pr.comments.length === 0)
+            continue;
+        let claims;
+        try {
+            claims = parseClaims(await provider.generate(PR_EXTRACT_INSTRUCTIONS, buildPrPrompt(pr)));
+        }
+        catch (err) {
+            debugLog(`llm mining pr #${pr.number} (skipped)`, err);
+            continue; // provider hiccup on one PR shouldn't kill the run
+        }
+        const ticketRef = extractTicketId(`${pr.title}\n${pr.body}\n${pr.headRefName}`, ticketPattern) ?? undefined;
+        for (const cl of claims.slice(0, 3)) {
+            const evidence = [];
+            if (pr.mergeCommitSha)
+                evidence.push({ type: "COMMIT_REF", payload: pr.mergeCommitSha });
+            if (cl.staticCheck)
+                evidence.push({ type: "STATIC_CHECK", payload: cl.staticCheck });
+            if (ticketRef)
+                evidence.push({ type: "TICKET_REF", payload: ticketRef });
+            const p = store.propose({
+                kind: cl.kind,
+                claim: cl.claim,
+                paths: cl.paths ?? scopeFromFiles(pr.files),
+                symbols: cl.symbols,
+                guardrailLevel: cl.guardrailLevel,
+                evidence: evidence.length ? evidence : undefined,
+                source: "pr-miner",
+                sourceRef: `pr:${pr.number}`,
+                rationale: cl.rationale ?? `Mined from PR #${pr.number}: ${pr.title}`,
+                ticketRef,
+            });
+            if (p)
+                proposed.push(p);
+            else
+                skippedDuplicates++;
+        }
+    }
+    // advance cursor to the newest merge time seen (list is newest-first)
+    if (prs.length > 0)
+        store.setMeta(PR_CURSOR_KEY, prs[0].mergedAt);
+    return {
+        scanned: prs.length,
+        proposed,
+        skippedDuplicates,
+        provider: `${provider.name}/${provider.model}`,
+    };
+}
+//# sourceMappingURL=pr-miner.js.map

package/dist/capture/session-briefing.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Session-start briefing (KARPATHY_LAYERS Feature 6) — Spec layer.
+ *
+ * "Agile speccing" applied to each coding session. Before an agent starts work,
+ * this gathers what aidimag already knows about the area it's about to touch:
+ * relevant memories, stale warnings, in-scope guardrails, coverage gaps, and a
+ * few clarifying questions the agent should ask the human instead of guessing.
+ *
+ * Exposed as the MCP resource aidimag://session-briefing and the session_start
+ * prompt.
+ */
+import type { MemoryStore } from "../db/store.js";
+import type { GuardrailLevel, MemoryEntry } from "../types.js";
+export interface SessionBriefing {
+    branch: string | null;
+    ticket: string | null;
+    changedFiles: string[];
+    relevantMemories: MemoryEntry[];
+    staleWarnings: MemoryEntry[];
+    guardrailsInScope: Array<{
+        memory: MemoryEntry;
+        level: GuardrailLevel;
+    }>;
+    coverageGaps: string[];
+    /** recent searches (agent or human) that found NOTHING — questions memory couldn't answer */
+    unansweredSearches: Array<{
+        query: string;
+        misses: number;
+    }>;
+    suggestedQuestions: string[];
+}
+export declare function buildSessionBriefing(store: MemoryStore, root: string): SessionBriefing;
+/** Human/agent-readable rendering of the briefing for the MCP resource + prompt. */
+export declare function renderBriefing(b: SessionBriefing): string;
+/** Prompt that tells the agent to interview the user using the briefing (Karpathy: extract the true goal). */
+export declare function sessionStartPrompt(b: SessionBriefing): string;

package/dist/capture/session-briefing.js

@@ -0,0 +1,150 @@
+/**
+ * Session-start briefing (KARPATHY_LAYERS Feature 6) — Spec layer.
+ *
+ * "Agile speccing" applied to each coding session. Before an agent starts work,
+ * this gathers what aidimag already knows about the area it's about to touch:
+ * relevant memories, stale warnings, in-scope guardrails, coverage gaps, and a
+ * few clarifying questions the agent should ask the human instead of guessing.
+ *
+ * Exposed as the MCP resource aidimag://session-briefing and the session_start
+ * prompt.
+ */
+import { execFileSync } from "node:child_process";
+import { detectBranchTicket } from "../tickets/provider.js";
+function currentBranch(root) {
+    try {
+        return execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Files changed on this branch vs its merge-base with the default branch, plus uncommitted work. */
+function branchChangedFiles(root) {
+    const tryGit = (args) => {
+        try {
+            return execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        }
+        catch {
+            return "";
+        }
+    };
+    const files = new Set();
+    for (const base of ["origin/main", "origin/master", "main", "master"]) {
+        const mb = tryGit(["merge-base", base, "HEAD"]).trim();
+        if (mb) {
+            tryGit(["diff", "--name-only", `${mb}..HEAD`]).split("\n").filter(Boolean).forEach((f) => files.add(f));
+            break;
+        }
+    }
+    // include staged + unstaged working changes
+    tryGit(["diff", "--name-only", "HEAD"]).split("\n").filter(Boolean).forEach((f) => files.add(f));
+    return [...files];
+}
+export function buildSessionBriefing(store, root) {
+    const branch = currentBranch(root);
+    const ticket = detectBranchTicket(root);
+    const changedFiles = branchChangedFiles(root);
+    const scoped = changedFiles.length ? store.getForFiles(changedFiles, 100) : store.list(20).filter((m) => m.status !== "REFUTED");
+    const relevantMemories = scoped
+        .filter((m) => m.kind !== "GUARDRAIL" && m.status !== "REFUTED")
+        .sort((a, b) => b.confidence - a.confidence)
+        .slice(0, 8);
+    const staleWarnings = scoped.filter((m) => m.status === "STALE");
+    const guardrailsInScope = scoped
+        .filter((m) => m.kind === "GUARDRAIL" && m.status !== "REFUTED")
+        .map((m) => ({ memory: m, level: m.guardrailLevel ?? "ask-first" }));
+    // coverage gaps: changed files no memory is scoped to
+    const covered = new Set();
+    for (const m of scoped)
+        for (const sp of m.scope.paths)
+            for (const f of changedFiles)
+                if (f.startsWith(sp) || sp.startsWith(f))
+                    covered.add(f);
+    const coverageGaps = changedFiles.filter((f) => !covered.has(f));
+    // knowledge gaps: recent zero-hit searches (see store.searchGaps / `dim gaps`)
+    let unansweredSearches = [];
+    try {
+        unansweredSearches = store.searchGaps({ sinceDays: 14, limit: 5 }).map((g) => ({ query: g.query, misses: g.misses }));
+    }
+    catch {
+        /* pre-migration DB — gaps are advisory */
+    }
+    const suggestedQuestions = [];
+    for (const s of staleWarnings.slice(0, 2)) {
+        suggestedQuestions.push(`A ${s.kind} for ${s.scope.paths.join(", ") || "the repo"} is STALE — has it changed? ("${s.claim.slice(0, 80)}")`);
+    }
+    for (const f of coverageGaps.slice(0, 2)) {
+        suggestedQuestions.push(`No memory covers ${f} — want me to explore it before changing it?`);
+    }
+    if (unansweredSearches.length) {
+        suggestedQuestions.push(`Past sessions searched for "${unansweredSearches[0].query}" and found nothing — do you know the answer? (I'll save it with context_note.)`);
+    }
+    if (guardrailsInScope.some((g) => g.level === "ask-first")) {
+        suggestedQuestions.push("An ASK-FIRST guardrail applies to these files — confirm the intended scope before I proceed.");
+    }
+    return { branch, ticket, changedFiles, relevantMemories, staleWarnings, guardrailsInScope, coverageGaps, unansweredSearches, suggestedQuestions };
+}
+const GUARDRAIL_ICON = { never: "🚫", always: "✅", "ask-first": "🤚" };
+/** Human/agent-readable rendering of the briefing for the MCP resource + prompt. */
+export function renderBriefing(b) {
+    const lines = ["# Session briefing"];
+    lines.push(`branch: ${b.branch ?? "(unknown)"}${b.ticket ? ` · ticket: ${b.ticket}` : ""}`);
+    lines.push(b.changedFiles.length ? `in scope: ${b.changedFiles.length} changed file(s)` : "no branch diff detected — showing recent memory");
+    lines.push("");
+    if (b.guardrailsInScope.length) {
+        lines.push("## Guardrails in scope ⚠️");
+        for (const g of b.guardrailsInScope)
+            lines.push(`- ${GUARDRAIL_ICON[g.level]} ${g.level.toUpperCase()}: ${g.memory.claim}`);
+        lines.push("");
+    }
+    if (b.relevantMemories.length) {
+        lines.push("## Relevant memory");
+        for (const m of b.relevantMemories)
+            lines.push(`- (${m.status}, ${m.kind}) ${m.claim}`);
+        lines.push("");
+    }
+    if (b.staleWarnings.length) {
+        lines.push("## Stale — do NOT trust without re-verifying");
+        for (const m of b.staleWarnings)
+            lines.push(`- (${m.kind}) ${m.claim}`);
+        lines.push("");
+    }
+    if (b.coverageGaps.length) {
+        lines.push("## No memory coverage");
+        for (const f of b.coverageGaps.slice(0, 10))
+            lines.push(`- ${f}`);
+        lines.push("");
+    }
+    if (b.unansweredSearches.length) {
+        lines.push("## Unanswered questions (searches that found nothing)");
+        for (const g of b.unansweredSearches)
+            lines.push(`- "${g.query}"${g.misses > 1 ? ` (asked ${g.misses}×)` : ""}`);
+        lines.push("If this session answers one of these, persist it (context_note / memory_propose).");
+        lines.push("");
+    }
+    if (b.suggestedQuestions.length) {
+        lines.push("## Ask the user before guessing");
+        for (const q of b.suggestedQuestions)
+            lines.push(`- ${q}`);
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd() + "\n";
+}
+/** Prompt that tells the agent to interview the user using the briefing (Karpathy: extract the true goal). */
+export function sessionStartPrompt(b) {
+    return (`You're starting a coding session. Before writing any code, ground yourself in what this project already knows.\n\n` +
+        renderBriefing(b) +
+        `\nNow:\n` +
+        `1. Treat the guardrails above as binding (never = refuse, ask-first = confirm, always = do).\n` +
+        `2. Trust VERIFIED memory; re-verify anything STALE before relying on it (\`memory_verify\`).\n` +
+        `3. Ask the user the clarifying questions above instead of guessing — extract the true goal first.\n` +
+        `4. Use \`memory_search\` / \`memory_get_for_files\` as you go, and \`memory_critique\` before you finish.\n` +
+        `5. IMPORTANT: When the user states durable facts about the codebase (decisions, conventions, guardrails, architecture), IMMEDIATELY capture them with \`context_note\`. Examples:\n` +
+        `   • "We use X because Y" → capture as DECISION\n` +
+        `   • "Never do X" → capture as GUARDRAIL\n` +
+        `   • "We always do X" → capture as CONVENTION\n` +
+        `   • "We tried X and it failed" → capture as FAILED_APPROACH\n` +
+        `   Don't wait for session end. Capture facts as they're stated, then continue the conversation naturally.`);
+}
+//# sourceMappingURL=session-briefing.js.map

package/dist/capture/session-extraction.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Session-end extraction (Phase 2 capture pipeline).
+ *
+ * The agent does the summarizing — we provide a tight, structured prompt
+ * (exposed as an MCP prompt) and a `memory_propose` tool that routes the
+ * agent's structured proposals into the human review queue.
+ */
+export declare const SESSION_END_PROMPT = "You are finishing a coding session. Before you stop, extract durable knowledge about this codebase so future sessions don't have to re-discover it.\n\nReview what you learned this session and propose memories using the `memory_propose` tool. Rules:\n\n1. Only propose things that are DURABLE (true beyond this session) and NON-OBVIOUS (not derivable from a quick file read).\n2. Write each claim as a FALSIFIABLE statement \u2014 something a checker could verify against the code. Bad: \"the auth code is tricky\". Good: \"JWT refresh in src/auth/refresh.ts must run before middleware chain; reordering breaks session renewal (see commit abc123)\".\n3. Pick the right kind:\n   - DECISION: a choice made and why (alternatives rejected)\n   - CONVENTION: a rule consistently followed in this repo\n   - GOTCHA: surprising behavior that cost you time\n   - FAILED_APPROACH: something you tried that did NOT work, and why\n   - ARCHITECTURE: how components fit together\n   - INVARIANT: something that must always/never hold\n   - GUARDRAIL: a behavioral rule for future agents \u2014 pass guardrail_level: 'never' (refuse + explain), 'always' (do without asking), or 'ask-first' (confirm with the user first)\n   - SKILL: a reusable step-by-step procedure (e.g. \"Deploy: 1) \u2026 2) \u2026 3) \u2026\") that the team runs repeatedly\n   - TODO_CONTEXT: unfinished work + the context needed to resume it\n4. Scope each memory to the paths/symbols it applies to. Repo-wide only if truly global.\n5. Attach evidence whenever possible: COMMIT_REF (a sha), STATIC_CHECK (a grep/assertion command that passes iff the claim holds), TEST_RESULT (a test command), or HUMAN_ATTESTED as last resort.\n6. FAILED_APPROACH memories are especially valuable \u2014 they prevent future sessions from repeating dead ends.\n7. Propose 0\u20137 memories. Zero is fine if nothing durable was learned. Do NOT pad.\n8. Before proposing, call `memory_critique` with a short summary of what you did and the files you touched. It checks your work against the project's existing memory and guardrails \u2014 resolve any contradictions or guardrail concerns it raises first.\n\nRespect all GUARDRAIL memories you've seen this session: 'never' = refuse and explain why, 'always' = do without asking, 'ask-first' = ask the user before proceeding.\n\nYour proposals enter a human review queue (`dim review`); they do not become active memory until approved.";
+/**
+ * Ticket-aware variant (TICKETS_DESIGN T5): when the current branch carries a
+ * ticket id, teach the agent to pull the ticket's WHY into its proposals —
+ * "you fixed the race — should I remember that token refresh must never run
+ * concurrently?" The MCP agent is often the better prompting surface.
+ */
+export declare function sessionEndPromptFor(ticketId: string | null): string;
+/** One-line summary of a proposal for human review UIs. */
+export declare function proposalSummaryLine(p: {
+    id: string;
+    kind: string;
+    claim: string;
+    source: string;
+    rationale?: string;
+}): string;

package/dist/capture/session-extraction.js

@@ -0,0 +1,54 @@
+/**
+ * Session-end extraction (Phase 2 capture pipeline).
+ *
+ * The agent does the summarizing — we provide a tight, structured prompt
+ * (exposed as an MCP prompt) and a `memory_propose` tool that routes the
+ * agent's structured proposals into the human review queue.
+ */
+export const SESSION_END_PROMPT = `You are finishing a coding session. Before you stop, extract durable knowledge about this codebase so future sessions don't have to re-discover it.
+
+Review what you learned this session and propose memories using the \`memory_propose\` tool. Rules:
+
+1. Only propose things that are DURABLE (true beyond this session) and NON-OBVIOUS (not derivable from a quick file read).
+2. Write each claim as a FALSIFIABLE statement — something a checker could verify against the code. Bad: "the auth code is tricky". Good: "JWT refresh in src/auth/refresh.ts must run before middleware chain; reordering breaks session renewal (see commit abc123)".
+3. Pick the right kind:
+   - DECISION: a choice made and why (alternatives rejected)
+   - CONVENTION: a rule consistently followed in this repo
+   - GOTCHA: surprising behavior that cost you time
+   - FAILED_APPROACH: something you tried that did NOT work, and why
+   - ARCHITECTURE: how components fit together
+   - INVARIANT: something that must always/never hold
+   - GUARDRAIL: a behavioral rule for future agents — pass guardrail_level: 'never' (refuse + explain), 'always' (do without asking), or 'ask-first' (confirm with the user first)
+   - SKILL: a reusable step-by-step procedure (e.g. "Deploy: 1) … 2) … 3) …") that the team runs repeatedly
+   - TODO_CONTEXT: unfinished work + the context needed to resume it
+4. Scope each memory to the paths/symbols it applies to. Repo-wide only if truly global.
+5. Attach evidence whenever possible: COMMIT_REF (a sha), STATIC_CHECK (a grep/assertion command that passes iff the claim holds), TEST_RESULT (a test command), or HUMAN_ATTESTED as last resort.
+6. FAILED_APPROACH memories are especially valuable — they prevent future sessions from repeating dead ends.
+7. Propose 0–7 memories. Zero is fine if nothing durable was learned. Do NOT pad.
+8. Before proposing, call \`memory_critique\` with a short summary of what you did and the files you touched. It checks your work against the project's existing memory and guardrails — resolve any contradictions or guardrail concerns it raises first.
+
+Respect all GUARDRAIL memories you've seen this session: 'never' = refuse and explain why, 'always' = do without asking, 'ask-first' = ask the user before proceeding.
+
+Your proposals enter a human review queue (\`dim review\`); they do not become active memory until approved.`;
+/**
+ * Ticket-aware variant (TICKETS_DESIGN T5): when the current branch carries a
+ * ticket id, teach the agent to pull the ticket's WHY into its proposals —
+ * "you fixed the race — should I remember that token refresh must never run
+ * concurrently?" The MCP agent is often the better prompting surface.
+ */
+export function sessionEndPromptFor(ticketId) {
+    if (!ticketId)
+        return SESSION_END_PROMPT;
+    return (SESSION_END_PROMPT +
+        `
+
+This session's branch is tied to ticket ${ticketId}. Additionally:
+8. Call \`ticket_get\` first — the ticket usually carries the WHY (root cause, rejected alternatives, acceptance criteria) that the code alone doesn't.
+9. Combine sources: claim from what you did + ticket title/description for the rationale. A bug ticket's root cause is usually a GOTCHA; what didn't fix it is a FAILED_APPROACH; acceptance criteria are INVARIANT candidates.
+10. Proposals are tagged with ${ticketId} automatically (ticket_ref); you don't need to mention the id in claims.`);
+}
+/** One-line summary of a proposal for human review UIs. */
+export function proposalSummaryLine(p) {
+    return `[${p.id.slice(0, 8)}] (${p.kind}, via ${p.source}) ${p.claim}`;
+}
+//# sourceMappingURL=session-extraction.js.map

package/dist/capture/triage.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Proposal triage — keeps the review queue from becoming homework.
+ *
+ * Scores every pending proposal 0–1 from cheap, local signals:
+ *   + machine-checkable evidence attached (falsifiable on arrival)
+ *   + trusted source (human-stated context > knowledge docs > miners)
+ *   + concrete scope (paths/symbols)
+ *   − similarity to previously REJECTED claims (the correction loop:
+ *     what you drop teaches the queue what not to surface first)
+ *   − similarity to existing ACTIVE memory (likely duplicate knowledge)
+ *
+ * `dim review` walks the queue best-first and shows the score;
+ * `dim review approve all --min-score <s>` batch-approves above a bar.
+ */
+import type { MemoryStore } from "../db/store.js";
+import type { Proposal } from "../types.js";
+export interface TriagedProposal {
+    proposal: Proposal;
+    score: number;
+    reasons: string[];
+}
+export declare function tokenize(text: string): Set<string>;
+/** Jaccard similarity over content tokens — cheap, offline, good enough for triage. */
+export declare function claimSimilarity(a: string, b: string): number;
+export declare function scoreProposal(p: Proposal, rejectedClaims: string[], activeClaims: string[]): {
+    score: number;
+    reasons: string[];
+};
+/** Pending proposals, best-first, each with its score and the reasons behind it. */
+export declare function triagePending(store: MemoryStore, limit?: number): TriagedProposal[];

package/dist/capture/triage.js

@@ -0,0 +1,108 @@
+/**
+ * Proposal triage — keeps the review queue from becoming homework.
+ *
+ * Scores every pending proposal 0–1 from cheap, local signals:
+ *   + machine-checkable evidence attached (falsifiable on arrival)
+ *   + trusted source (human-stated context > knowledge docs > miners)
+ *   + concrete scope (paths/symbols)
+ *   − similarity to previously REJECTED claims (the correction loop:
+ *     what you drop teaches the queue what not to surface first)
+ *   − similarity to existing ACTIVE memory (likely duplicate knowledge)
+ *
+ * `dim review` walks the queue best-first and shows the score;
+ * `dim review approve all --min-score <s>` batch-approves above a bar.
+ */
+const STOPWORDS = new Set([
+    "the", "a", "an", "is", "are", "was", "were", "in", "on", "of", "to", "and",
+    "or", "for", "with", "that", "this", "it", "be", "as", "at", "by", "from",
+    "not", "no", "all", "any", "into", "through", "must", "should", "never",
+    "always", "made", "make", "makes", "was", "were",
+]);
+export function tokenize(text) {
+    return new Set(text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s/._-]/g, " ")
+        .split(/\s+/)
+        .filter((t) => t.length > 2 && !STOPWORDS.has(t)));
+}
+/** Jaccard similarity over content tokens — cheap, offline, good enough for triage. */
+export function claimSimilarity(a, b) {
+    const ta = tokenize(a);
+    const tb = tokenize(b);
+    if (ta.size === 0 || tb.size === 0)
+        return 0;
+    let inter = 0;
+    for (const t of ta)
+        if (tb.has(t))
+            inter++;
+    return inter / (ta.size + tb.size - inter);
+}
+const SOURCE_TRUST = [
+    { prefix: "context:", boost: 0.25, label: "user-stated in chat" },
+    { prefix: "harvest:", boost: 0.2, label: "user-typed (harvested)" },
+    { prefix: "knowledge:", boost: 0.15, label: "from curated doc" },
+    { prefix: "bootstrap", boost: 0.1, label: "repo survey" },
+    { prefix: "session:", boost: 0.1, label: "agent session" },
+    { prefix: "verify:stale", boost: 0.15, label: "stale-memory follow-up" },
+    { prefix: "pr-miner", boost: 0.15, label: "from PR review threads" },
+    { prefix: "commit-miner", boost: 0.05, label: "mined from commits" },
+];
+const SIMILARITY_THRESHOLD = 0.55;
+export function scoreProposal(p, rejectedClaims, activeClaims) {
+    let score = 0.4; // base
+    const reasons = [];
+    const machineEvidence = p.evidence.filter((e) => e.type === "STATIC_CHECK" || e.type === "TEST_RESULT" || e.type === "EXEC_TRACE");
+    if (machineEvidence.length) {
+        score += 0.2;
+        reasons.push("machine-checkable evidence");
+    }
+    else if (p.evidence.some((e) => e.type === "COMMIT_REF")) {
+        score += 0.08;
+        reasons.push("commit-anchored");
+    }
+    if (p.evidence.some((e) => e.type === "HUMAN_ATTESTED")) {
+        score += 0.08;
+        reasons.push("human-attested");
+    }
+    const trust = SOURCE_TRUST.find((s) => p.source.startsWith(s.prefix));
+    if (trust) {
+        score += trust.boost;
+        reasons.push(trust.label);
+    }
+    if (p.paths.length || p.symbols.length) {
+        score += 0.07;
+        reasons.push("concretely scoped");
+    }
+    // correction loop: proposals resembling past rejections start at the back
+    let maxRejected = 0;
+    for (const r of rejectedClaims)
+        maxRejected = Math.max(maxRejected, claimSimilarity(p.claim, r));
+    if (maxRejected >= SIMILARITY_THRESHOLD) {
+        score -= 0.35;
+        reasons.push(`similar to a claim you rejected (${(maxRejected * 100).toFixed(0)}%)`);
+    }
+    // near-duplicate of active memory → low urgency
+    let maxActive = 0;
+    for (const a of activeClaims)
+        maxActive = Math.max(maxActive, claimSimilarity(p.claim, a));
+    if (maxActive >= SIMILARITY_THRESHOLD) {
+        score -= 0.25;
+        reasons.push(`similar to existing memory (${(maxActive * 100).toFixed(0)}%)`);
+    }
+    return { score: Math.max(0, Math.min(1, score)), reasons };
+}
+/** Pending proposals, best-first, each with its score and the reasons behind it. */
+export function triagePending(store, limit = 1000) {
+    const pending = store.listProposals("PENDING", limit);
+    if (!pending.length)
+        return [];
+    const rejectedClaims = store.listRejectedClaims(500);
+    const activeClaims = store
+        .list(1000)
+        .filter((m) => m.status !== "REFUTED")
+        .map((m) => m.claim);
+    return pending
+        .map((proposal) => ({ proposal, ...scoreProposal(proposal, rejectedClaims, activeClaims) }))
+        .sort((a, b) => b.score - a.score);
+}
+//# sourceMappingURL=triage.js.map

package/dist/cli/commands/capture.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Capture & review commands: mine (commits/PRs), bootstrap, harvest, review.
+ */
+import type { Command } from "commander";
+export declare function registerCaptureCommands(program: Command): void;