Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
5.0 KB
Raw Blame
/**
 * Commit-decision miner (Project History Suite, t_93d299bb).
 *
 * Deterministic heuristics over INGESTED commit records (never live
 * git): conventional breaking markers, BREAKING CHANGE footers, and
 * revert shape - all fixed commit-protocol tokens, language-agnostic.
 * Same store, same candidates, same order - no LLM classification
 * anywhere.
 *
 * Each decision-shaped commit becomes one draft ADR candidate note at
 * `Brain/decisions/candidates/adr-<shortsha>-<slug>.md` with the
 * matched signals as provenance. Candidate identity is the commit sha,
 * so re-runs are duplicate-free; an EXISTING candidate file is never
 * touched (skip-existing, variants.md orchestrator refinement 3) - once
 * an operator starts curating a draft, regeneration cannot clobber it.
 */

import { join } from "node:path";

import { listGitCommits } from "./store.ts";
import type { GitCommitRecord } from "./store.ts";
import { assertLaneWrite, lanePageExists, writeLaneText } from "../../store/lane-pages.ts";

const CONVENTIONAL_BREAKING_RE = /^[a-z]+(\([^)]*\))?!:/;
const REVERT_RE = /^revert\b/i;
const SLUG_MAX = 40;
// 12 hex chars: git's own "unambiguous in large repos" abbreviation
// length. Identity must not collide - a collision here would silently
// skip a real decision via the skip-existing rule.
const CANDIDATE_SHA_LEN = 12;

/**
 * Matched signal ids for one commit message, deterministic order.
 * Empty array = not decision-shaped.
 */
export function detectDecisionSignals(subject: string, body: string): ReadonlyArray<string> {
  // Language-agnostic by construction: only structural commit-protocol
  // markers count as decision signals. The old English keyword set
  // ("decide", "adopt", ...) never fired on a commit history written in
  // any other language; conventional-commit and git-native markers
  // (`type!:`, the `BREAKING CHANGE:` footer, the `Revert` prefix) are
  // fixed protocol tokens git/tooling emit, not free prose.
  const signals: string[] = [];
  if (CONVENTIONAL_BREAKING_RE.test(subject)) signals.push("conventional_breaking");
  if (/^BREAKING CHANGE\b/m.test(body)) signals.push("breaking_change_footer");
  if (REVERT_RE.test(subject)) signals.push("revert");
  return Object.freeze(signals);
}

function slugFromSubject(subject: string): string {
  const slug = subject
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, "-")
    .replace(/^-+|-+$/g, "")
    .slice(0, SLUG_MAX)
    .replace(/-+$/, "");
  return slug === "" ? "decision" : slug;
}

function renderCandidate(
  repoKey: string,
  commit: GitCommitRecord,
  signals: ReadonlyArray<string>,
): string {
  const lines: string[] = [
    "---",
    "kind: adr-candidate",
    "status: candidate",
    `repo_key: ${repoKey}`,
    `sha: ${commit.sha}`,
    `committed_at: ${commit.committedAt}`,
    `signals: [${signals.join(", ")}]`,
    "---",
    "",
    `# ADR candidate: ${commit.subject}`,
    "",
    `Mined from commit ${commit.sha.slice(0, 7)} in [[Brain/projects/git/${repoKey}/digest|${repoKey}]].`,
    "",
    "## Source commit",
    "",
    `- sha: \`${commit.sha}\``,
    `- author: ${commit.authorName}`,
    `- date: ${commit.committedAt}`,
    ...(commit.release !== null ? [`- release: ${commit.release}`] : []),
    `- matched signals: ${signals.join(", ")}`,
    "",
    "> " + commit.subject,
    ...(commit.body === "" ? [] : [">", ...commit.body.split("\n").map((line) => `> ${line}`)]),
    "",
    "## Decision",
    "",
    "Draft pending operator review: capture context, options considered, and the final call here.",
    "",
  ];
  return lines.join("\n");
}

export interface MineCommitDecisionsResult {
  readonly repoKey: string;
  readonly scanned: number;
  readonly candidates: number;
  readonly created: number;
  readonly skippedExisting: number;
  /** Absolute paths of all candidate notes for this repo (new + prior). */
  readonly notes: ReadonlyArray<string>;
}

/** Mine one repo's ingested commits into ADR candidate notes. */
export function mineCommitDecisions(vault: string, repoKey: string): MineCommitDecisionsResult {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertLaneWrite(vault);
  const commits = listGitCommits(vault, repoKey);
  const dir = join(vault, "Brain", "decisions", "candidates");
  let created = 0;
  let skippedExisting = 0;
  const notes: string[] = [];
  for (const commit of commits) {
    const signals = detectDecisionSignals(commit.subject, commit.body);
    if (signals.length === 0) continue;
    const path = join(
      dir,
      `adr-${commit.sha.slice(0, CANDIDATE_SHA_LEN)}-${slugFromSubject(commit.subject)}.md`,
    );
    notes.push(path);
    if (lanePageExists(vault, path)) {
      // Operator-curated drafts are sacrosanct: identity by sha means
      // this is the same decision, already on its review journey.
      skippedExisting += 1;
      continue;
    }
    writeLaneText(vault, path, renderCandidate(repoKey, commit, signals));
    created += 1;
  }
  return Object.freeze({
    repoKey,
    scanned: commits.length,
    candidates: notes.length,
    created,
    skippedExisting,
    notes: Object.freeze(notes),
  });
}