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
feat: Project History Suite - git history memory, ADR mining, architecture notes, query telemetry (#71)
Sol Aitken7733f20ea30e
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex 42aaee40..87c594f2 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "0.39.0",+ "version": "0.40.0","description": "Plugin-first second brain package for AI agents and humans.","author": {"name": "Open Second Brain contributors"diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.jsonindex dc593c1d..e94ba581 100644--- a/.codex-plugin/plugin.json+++ b/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "0.39.0",+ "version": "0.40.0","description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.","skills": "./skills","hooks": "./hooks/hooks.json",diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 851eb114..e34201be 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,70 @@ All notable changes to this project will be documented in this file.The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).+## [0.40.0] - 2026-06-04++Project History Suite: a linked project's git history and code+structure become queryable Second Brain memory. A sanitized read-only+git reader ingests commits, tags, and release ranges into a per-repo+record store inside the vault with a watermark for duplicate-free+incremental runs, a deterministic digest note makes each repo's+history FTS-discoverable, decision-shaped commits surface as draft+ADR candidates that operator curation owns from the moment they+exist, a stdlib-only scanner maintains regeneration-safe architecture+notes through sentinel regions, and `brain_query` - the one recall+surface v0.39.0 left without telemetry - joins the observability+contract. Everything deterministic, no LLM anywhere; the MCP contract+stays at 65 tools.++### Added++- **Git history memory** (`o2b brain git ingest <repo-path>`).+ Commits, tags, and release ranges from a worktree land as+ structured records in `Brain/projects/git/<repo-key>/commits.jsonl`+ (typed edges as fields: touched files, author, carrying release via+ chronological tag-range attribution). Incremental re-runs walk+ `<watermark>..HEAD` only; a force-pushed or tampered watermark+ degrades to a reported full re-scan and store dedup keeps that+ duplicate-free; a bounded walk announces truncated older history.+ The reader shells out with fixed argv and validates every+ caller-supplied sha against the full-40-hex grammar before it can+ reach git.+- **Git history query** (`o2b brain git find [text] [--file F]+ [--author A] [--since/--until] [--repo K]`, `o2b brain git+ status`). Answers "why and when did this file change" and "which+ release carried it" purely from the store - no live git on the+ query path, so the answers survive checkout deletion. A+ deterministic per-repo digest note (releases, recent commits, hot+ files) anchors the history in full-text search.+- **Commit-decision miner** (`o2b brain git mine`). Deterministic+ heuristics (conventional breaking markers, BREAKING CHANGE footers,+ word-boundary decision keywords, revert shape) turn decision-shaped+ commits into draft ADR candidate notes under+ `Brain/decisions/candidates/` with matched-signal provenance and+ sha-stable identity: re-runs never duplicate, an existing candidate+ is never touched.+- **Sentinel-region merge engine** (`src/core/brain/regions.ts`).+ Paired `<!-- o2b:begin <id> -->` / `<!-- o2b:end <id> -->` markers+ delimit generated note content; merging replaces only generated+ bodies, preserves operator bytes outside regions verbatim, appends+ new regions, and fails closed (no partial rewrite) on unbalanced,+ duplicate, nested, or mismatched sentinels.+- **Architecture docs generator** (`o2b brain architect+ <project-path>`). A deterministic stdlib-only scanner (module+ layout, language mix, entry points, manifest, test layout - no LLM,+ no network) renders an overview plus per-module notes under+ `Brain/projects/arch/<repo-key>/` through the region engine:+ re-scans refresh facts, operator prose survives byte-for-byte, an+ unchanged tree regenerates byte-identically.+- **`brain_query` recall telemetry.** Per-call opt-in arguments+ (`telemetry`, `telemetry_host`, `session_id`, `turn_id`) mirroring+ `brain_search`; mode `query` joins the `RecallTelemetryMode` union;+ emission goes through the lazy gated kernel on both success and+ error paths. The payload records the query kind+ (preference|topic|since) and counts only - the supplied preference+ id, topic slug, or timestamp value never lands in a continuity+ record.+## [0.39.0] - 2026-06-03Memory Observability Suite: the continuity store becomes a documented,@@ -4335,6 +4399,7 @@ plugin config (vault field)`, and exits with a clear- Sandbox vault and plugin manifest fixtures for tests.- GitHub release workflow for tag-based and manually dispatched releases.+[0.40.0]: https://github.com/itechmeat/open-second-brain/compare/v0.39.0...v0.40.0[0.39.0]: https://github.com/itechmeat/open-second-brain/compare/v0.38.0...v0.39.0[0.38.0]: https://github.com/itechmeat/open-second-brain/compare/v0.37.0...v0.38.0[0.37.0]: https://github.com/itechmeat/open-second-brain/compare/v0.36.0...v0.37.0diff --git a/README.md b/README.mdindex 2e76776d..169b6d17 100644--- a/README.md+++ b/README.md@@ -114,7 +114,7 @@ The capabilities you actually feel day to day:These are the headline capabilities. The full surface also includes: importing Claude Code memory directories, daily logging-discipline cron with a complexity-to-thinking warning, cross-project pointers for shared vaults, transient pinned session context through `brain_pinned_context` / `Brain/pinned.md`, source-agent query and comparison (`brain_agent_query`, `brain_agent_diff`, `o2b brain agent-query`, `o2b brain agent-diff`), the codegraph partner skill, vault hygiene lints, per-MOC coverage audit, concept synthesis, an operator dashboard, configurable Markdown-link presentation output, MCP output-contract checks for core agent-facing tools, private-region stripping with `<private>...</private>`, the v0.12.0 Brain Integrity Suite (content-hash drift detection, durable workrun checkpoints, destructive-from-confirmed retire gate, and the `brain_review_candidates` MCP tool that previews what the next dream pass would do without writing anything), the v0.13.0 Hybrid Search and Recall Quality suite (explainable recall, MMR diversity, link-graph traversal, entity-boosted retrieval, header-anchored chunking), the v0.14.0 Semantic Brain Health and Self-Maintenance suite (cross-preference contradiction detection, concept-gap and stale-claim surfacing, per-preference edit-history, a clean/watch/investigate reconciliation verdict via `brain_health`, and dependency-ordered `doctor --remediate`), the v0.17.0 Brain Lifecycle Review Suite (`intent-review`, `retention`, `monthly`, lifecycle schemas, and discipline complexity ratio), and the v0.18.0 MCP context economy (a per-tool preview budget that returns a bounded inline preview and parks the full payload in a vault-local artifact the agent fetches on demand with `brain_artifact_get`, plus a `recall_hint` one-liner on search results), and the v0.19.0 typed graph semantics (typed frontmatter relationships - `related` / `extends` / `contradicts` / `superseded_by` - that surface inline on search results, a `visibility:` scoping axis for `brain_search`, and a `brain_mcp_landscape` view of the Model Context Protocol servers configured across the vault), and the v0.20.0 Recall and Ranking Quality suite (a configurable Weibull recency-decay curve, structural query-intent classification that re-weights ranking by query shape, language-agnostic synonym expansion via local co-occurrence, per-memory and total recall character budgets for `brain_context_pack`, a persistent query cache that self-invalidates on a corpus-generation change, and a `brain_pre_compress_pack` tool that returns a budgeted top-preferences addendum for a host runtime to inject before context compression), and the v0.21.0 Brain Lifecycle Suite (a per-preference mutation audit trail keyed by preference id - create / promote / update / retire / merge with revision + content-hash before/after, via `o2b brain audit` and `brain_audit`; a multi-phase `dream` pipeline that names its close / reconcile / synthesize / heal / log seams and reports a structured per-phase summary without rewriting the proven internals; deterministic reconcile-phase domain classification that buckets contradictions into claims / entity / decisions / source-freshness, auto-resolves only the decisive source-freshness case, and surfaces the rest as open questions instead of forcing a merge; a budgeted `o2b brain morning-brief` / `brain_morning_brief` session-start summary of top preferences, recent open questions, and recent notes; language-agnostic ISO-8601 temporal extraction that fills preference validity windows from signal text; and opt-in heal-phase vault enrichment that links exact title mentions across user pages), and the v0.22.0 Vault portability + session economy suite (a deterministic lossless session codec - `expand(compress(x)) === x` for all input, opt-in on the signal store and exposed as `o2b brain codec`; an `o2b brain sources` / `brain_sources` read-only dashboard of signals by agent and source type; vault-map `{{role}}` tokens resolved via an optional `Brain/_vault-map.yaml` and wired into scan-inline read paths and graph import; named multi-vault profiles with `o2b vault profile` + a `brain_switch_vault` tool, activated by a pointer in config; and `o2b brain graph-export` / `graph-import` for moving a vault's knowledge graph between layouts with skip/overwrite/merge conflict modes). Browse [`docs/cli-reference.md`](docs/cli-reference.md) for every verb and [`docs/how-it-works.md`](docs/how-it-works.md) for the mental model.-The v0.26.0 surface adds audited schema mutation/admin tools, real-time lifecycle capture hooks for prompt markers and `brain_feedback` tool calls, CJK-aware FTS recall, and `brain_watchdog` / `o2b brain watchdog` recovery probes. The v0.27.0 surface adds recall-control and trust tools: structured search query documents, session focus, MCP `brain_recall_gate`, polarity-aware context lanes, and opt-in evidence packs for CLI/MCP search. The v0.28.0 surface adds a deterministic prompt-injection guard for automatically surfaced Brain context, agent-blind `$secret:NAME` references, and preview foundations for source-scoped forget, privacy-scanned knowledge packs, and oversized payload externalization. The v0.29.0 surface adds opt-in context receipts and recall telemetry, read-only context budget presets, pre-compaction extraction, and a continuity-backed session recall DAG. The v0.33.0 surface adds the Recall Trust Suite: relation-aware recall polarity for typed memory edges, an explicit retrieval feedback loop with bounded learned weights (`o2b search feedback` / `weights`, MCP `brain_recall_feedback`), time-aware recall (`--since` / `--until` with natural-language ranges), verified multi-record recall (per-token union records, IDF-weighted coverage, rare-term abstention), and a search-completeness verdict with a false-absence guard. The v0.34.0 surface adds the Token Diet: a budgeted SessionStart injection of `Brain/active.md` (default 8,000 chars, `active.inject_budget_chars`) with the post-compaction path moved to the supported SessionStart `compact` matcher, a once-per-session post-write reminder cadence, frontmatter escape-amplification fixed at the parser with a one-shot `o2b brain upgrade --apply` repair for already-corrupted preference files, three consolidated read tools (`brain_brief`, `brain_analytics`, `schema_inspect`) with 18 hidden deprecated aliases, registry description caps with a contract guard, preview budgets by default, and a `scripts/measure-token-surface.ts` report. The v0.35.0 surface adds the Memory Integrity Suite: a canonical entity registry under `Brain/entities/` (one Markdown entity per `(category, name)` with alias resolution, archive/restore, typed relations, `o2b brain entity` CLI verbs, a read-only `brain_entity` MCP tool, doctor duplicate/relation lints, and alias-aware search boost with `entity_canonical` explanations), per-device Brain log shards (`Brain/log/<date>.<deviceId>.jsonl` + `.md` keyed by a device-local id, merged reads through `readLogDay`/`listLogDates`, no more Syncthing write conflicts, legacy days untouched), capture boundaries (a `sessions:` block with ignored/stateless session globs and message suppression regexes, applied before any extraction at both live-hook and import seams, counted but never stored raw; keep suppression regexes simple - they run on every message, and a catastrophic-backtracking pattern slows capture), and deterministic regex fact extraction (seven precision-first families over user turns, `source_type: extracted` signals with family-scoped dedup and canonical entity anchors). The v0.36.0 surface adds the Embedding Provider Suite: an offline `local` embedding provider (deterministic feature hashing, no cloud, no key, no model download - set `embedding_provider: local` for a privacy-first recall path), a CLI provider registry (`o2b search provider add | list | show | remove`, persisted to `Brain/search/embedding-providers.json` storing only environment-variable names, resolved after the built-ins so a configured key is never shadowed), an embedding cost gate (`embedding_cost_gate_usd`, default 0 = off; refuses an over-budget run unless `o2b search index --force-cost`) with the active `<provider>:<model>:<dimension>` signature and a refresh-cost estimate in `o2b search status`, and an opt-in Reciprocal Rank Fusion mode (`search_fusion_mode: rrf`, `search_rrf_k` default 60) that fuses the keyword and semantic lanes by rank position instead of weighted magnitude while the default `linear` mode stays bit-identical and storage remains SQLite + sqlite-vec + FTS5. The v0.37.0 surface adds the Agent Surface Suite: skills as callable MCP tools (`list_skills` / `get_skill` over the shipped `skills/` plus vault-local `Brain/skills/`), two-pass tool catalog hydration (a compact `catalog` scope where `tool_hydrate` returns the sorted catalog and per-name full schemas while every tool stays callable), five named tool-surface profiles with fail-open fallback (`mcp_tool_profile` / `o2b mcp --tool-profile`), deterministic BM25-style skill auto-attach (`skills_attach`, gated by `skill_auto_attach`), config-level capture role filtering (`session_capture_roles`), session-scoped search focus with SessionEnd auto-clear and gated context-pack promotion (`--session`, `focus_session`, `search_focus_context_pack`), operator-readable handoff notes (`o2b brain handoff`, gated SessionEnd generation via `session_handoff`), and scoped current-intention chains with a move-to-history lifecycle (`o2b brain intention`, MCP `brain_intention`). The v0.38.0 surface adds the Workspace Insight Suite: project vault pointers (`o2b brain project link | list | remove | status` writes a `.o2b-vault.json` into any project directory and `resolveVault` honours it from anywhere under that tree), read-only recall sources (`o2b brain source add | list | remove` with self/duplicate/circular validation and BROKEN flagging), cross-vault union search (`o2b search <query> --global`, `brain_search { global: true }` - origin-labelled results, external vaults never written to), a configurable wikilink path format (`wiki_link_format`: preserve/full/short plus `o2b brain links normalize`), a shell-native surface (`o2b brain profile` materializes `Brain/profile.md` + a `.o2bfs` root marker; `o2b brain sgrep` is grep-shaped semantic search), a grounded trigger queue with an anti-nag lifecycle (`o2b brain trigger scan | list | ack | dismiss | act | history`, MCP `brain_trigger`, cooldown-key dedup, morning-brief delivery once per `trigger_cooldown_days`), deep vault synthesis (`o2b brain deep-synthesis <topic>`, MCP `brain_deep_synthesis` - a deterministic dossier of agreements, contradictions, stale claims, and knowledge gaps), idea discovery (`o2b brain ideas`, MCP `brain_idea_discovery`), and opt-in recall-gate telemetry (`recall_gate_telemetry`, hashed prompts only, gate_list / gate_summary operations). The v0.39.0 surface adds the Memory Observability Suite: a contract-wide continuity schema version (`o2b.continuity.v1`, legacy records read as v1, dedup ids unchanged), a lazy gated telemetry emit kernel with structural no-consumer and fail-open guarantees across every gated surface, a continuity read-model with private-record masking shared by all read-side consumers, ATOF/ATIF trajectory export (`o2b brain continuity export --format atof|atif` - read-only, redaction honoured), a deterministic memory quality benchmark (`o2b brain bench memory` with checkpoint/resume and separate quality/latency/context-cost reporting), and the `docs/observability.md` contract enumerating every event kind, gate, and safety rule.+The v0.26.0 surface adds audited schema mutation/admin tools, real-time lifecycle capture hooks for prompt markers and `brain_feedback` tool calls, CJK-aware FTS recall, and `brain_watchdog` / `o2b brain watchdog` recovery probes. The v0.27.0 surface adds recall-control and trust tools: structured search query documents, session focus, MCP `brain_recall_gate`, polarity-aware context lanes, and opt-in evidence packs for CLI/MCP search. The v0.28.0 surface adds a deterministic prompt-injection guard for automatically surfaced Brain context, agent-blind `$secret:NAME` references, and preview foundations for source-scoped forget, privacy-scanned knowledge packs, and oversized payload externalization. The v0.29.0 surface adds opt-in context receipts and recall telemetry, read-only context budget presets, pre-compaction extraction, and a continuity-backed session recall DAG. The v0.33.0 surface adds the Recall Trust Suite: relation-aware recall polarity for typed memory edges, an explicit retrieval feedback loop with bounded learned weights (`o2b search feedback` / `weights`, MCP `brain_recall_feedback`), time-aware recall (`--since` / `--until` with natural-language ranges), verified multi-record recall (per-token union records, IDF-weighted coverage, rare-term abstention), and a search-completeness verdict with a false-absence guard. The v0.34.0 surface adds the Token Diet: a budgeted SessionStart injection of `Brain/active.md` (default 8,000 chars, `active.inject_budget_chars`) with the post-compaction path moved to the supported SessionStart `compact` matcher, a once-per-session post-write reminder cadence, frontmatter escape-amplification fixed at the parser with a one-shot `o2b brain upgrade --apply` repair for already-corrupted preference files, three consolidated read tools (`brain_brief`, `brain_analytics`, `schema_inspect`) with 18 hidden deprecated aliases, registry description caps with a contract guard, preview budgets by default, and a `scripts/measure-token-surface.ts` report. The v0.35.0 surface adds the Memory Integrity Suite: a canonical entity registry under `Brain/entities/` (one Markdown entity per `(category, name)` with alias resolution, archive/restore, typed relations, `o2b brain entity` CLI verbs, a read-only `brain_entity` MCP tool, doctor duplicate/relation lints, and alias-aware search boost with `entity_canonical` explanations), per-device Brain log shards (`Brain/log/<date>.<deviceId>.jsonl` + `.md` keyed by a device-local id, merged reads through `readLogDay`/`listLogDates`, no more Syncthing write conflicts, legacy days untouched), capture boundaries (a `sessions:` block with ignored/stateless session globs and message suppression regexes, applied before any extraction at both live-hook and import seams, counted but never stored raw; keep suppression regexes simple - they run on every message, and a catastrophic-backtracking pattern slows capture), and deterministic regex fact extraction (seven precision-first families over user turns, `source_type: extracted` signals with family-scoped dedup and canonical entity anchors). The v0.36.0 surface adds the Embedding Provider Suite: an offline `local` embedding provider (deterministic feature hashing, no cloud, no key, no model download - set `embedding_provider: local` for a privacy-first recall path), a CLI provider registry (`o2b search provider add | list | show | remove`, persisted to `Brain/search/embedding-providers.json` storing only environment-variable names, resolved after the built-ins so a configured key is never shadowed), an embedding cost gate (`embedding_cost_gate_usd`, default 0 = off; refuses an over-budget run unless `o2b search index --force-cost`) with the active `<provider>:<model>:<dimension>` signature and a refresh-cost estimate in `o2b search status`, and an opt-in Reciprocal Rank Fusion mode (`search_fusion_mode: rrf`, `search_rrf_k` default 60) that fuses the keyword and semantic lanes by rank position instead of weighted magnitude while the default `linear` mode stays bit-identical and storage remains SQLite + sqlite-vec + FTS5. The v0.37.0 surface adds the Agent Surface Suite: skills as callable MCP tools (`list_skills` / `get_skill` over the shipped `skills/` plus vault-local `Brain/skills/`), two-pass tool catalog hydration (a compact `catalog` scope where `tool_hydrate` returns the sorted catalog and per-name full schemas while every tool stays callable), five named tool-surface profiles with fail-open fallback (`mcp_tool_profile` / `o2b mcp --tool-profile`), deterministic BM25-style skill auto-attach (`skills_attach`, gated by `skill_auto_attach`), config-level capture role filtering (`session_capture_roles`), session-scoped search focus with SessionEnd auto-clear and gated context-pack promotion (`--session`, `focus_session`, `search_focus_context_pack`), operator-readable handoff notes (`o2b brain handoff`, gated SessionEnd generation via `session_handoff`), and scoped current-intention chains with a move-to-history lifecycle (`o2b brain intention`, MCP `brain_intention`). The v0.38.0 surface adds the Workspace Insight Suite: project vault pointers (`o2b brain project link | list | remove | status` writes a `.o2b-vault.json` into any project directory and `resolveVault` honours it from anywhere under that tree), read-only recall sources (`o2b brain source add | list | remove` with self/duplicate/circular validation and BROKEN flagging), cross-vault union search (`o2b search <query> --global`, `brain_search { global: true }` - origin-labelled results, external vaults never written to), a configurable wikilink path format (`wiki_link_format`: preserve/full/short plus `o2b brain links normalize`), a shell-native surface (`o2b brain profile` materializes `Brain/profile.md` + a `.o2bfs` root marker; `o2b brain sgrep` is grep-shaped semantic search), a grounded trigger queue with an anti-nag lifecycle (`o2b brain trigger scan | list | ack | dismiss | act | history`, MCP `brain_trigger`, cooldown-key dedup, morning-brief delivery once per `trigger_cooldown_days`), deep vault synthesis (`o2b brain deep-synthesis <topic>`, MCP `brain_deep_synthesis` - a deterministic dossier of agreements, contradictions, stale claims, and knowledge gaps), idea discovery (`o2b brain ideas`, MCP `brain_idea_discovery`), and opt-in recall-gate telemetry (`recall_gate_telemetry`, hashed prompts only, gate_list / gate_summary operations). The v0.39.0 surface adds the Memory Observability Suite: a contract-wide continuity schema version (`o2b.continuity.v1`, legacy records read as v1, dedup ids unchanged), a lazy gated telemetry emit kernel with structural no-consumer and fail-open guarantees across every gated surface, a continuity read-model with private-record masking shared by all read-side consumers, ATOF/ATIF trajectory export (`o2b brain continuity export --format atof|atif` - read-only, redaction honoured), a deterministic memory quality benchmark (`o2b brain bench memory` with checkpoint/resume and separate quality/latency/context-cost reporting), and the `docs/observability.md` contract enumerating every event kind, gate, and safety rule. The v0.40.0 surface adds the Project History Suite: git history as project memory (`o2b brain git ingest | status | find | mine` - a sanitized read-only reader lands commits, tags, and release ranges in a per-repo record store under `Brain/projects/git/<repo-key>/` with watermarked duplicate-free incremental runs, a deterministic FTS-discoverable digest note, store-only history queries that survive checkout deletion, and decision-shaped commits mined into draft ADR candidates under `Brain/decisions/candidates/` with sha-stable skip-existing identity), regeneration-safe architecture notes (`o2b brain architect <project-path>` - a stdlib-only deterministic scanner renders overview and per-module notes through paired `o2b:begin`/`o2b:end` sentinel regions, so operator prose survives every re-scan byte-for-byte and corrupted markers fail closed), and `brain_query` recall telemetry (per-call opt-in mirroring `brain_search`, kind-only payload - the supplied preference id, topic, or timestamp never lands in a continuity record).## CLIdiff --git a/docs/brainstorm/project-history-suite/cli-output/claude.md b/docs/brainstorm/project-history-suite/cli-output/claude.mdnew file mode 100644index 00000000..7a7fc70e--- /dev/null+++ b/docs/brainstorm/project-history-suite/cli-output/claude.md@@ -0,0 +1,38 @@+### Variant 1: Markdown-native (one note per commit, wikilink edges)+- **Approach**: Every ingested commit becomes a markdown note under `Brain/git/<repo>/commits/<sha>.md` with YAML frontmatter and a body; tags/releases/authors get their own notes; all edges are `[[wikilinks]]` resolved by the existing backlink index and surfaced through FTS5 and context packs with no new query path. The watermark is a small per-repo state note (or frontmatter on a repo index note); the miner reads commit notes back via FTS keyword scan and writes ADR candidates as sibling notes under `Brain/decisions/candidates/`; arch-docs reuses the same note renderer with an HTML-comment region-merge layer on top.+- **Trade-offs**:+ - Pro: zero new query infrastructure β everything is searchable, backlinkable, and context-pack-eligible the day it lands.+ - Pro: edges are first-class graph primitives (wikilinks), matching the existing typed-link/backlink model exactly.+ - Pro: incremental ingest dedup is trivial (note exists at deterministic path = already ingested).+ - Con: thousands of tiny files per active repo bloats the vault, reindex time, and backlink index; FTS noise drowns user notes.+ - Con: file-touch edges (commitβfile) explode wikilink fan-out; a 500-file commit writes 500 links.+ - Con: no compact analytical query (fan-in/out, author rollups) without scanning many notes.+- **Complexity**: medium+- **Risk**: high++### Variant 2: Sidecar store (JSONL/SQLite source of truth, structured edges, thin digest notes)+- **Approach**: Commits, tags, releases, authors, and all edges live as structured records in a per-repo append-only JSONL store (mirroring `Brain/log/` shard conventions), with edges as typed structured fields inside records rather than wikilinks; a dedicated `brain git-history` query path reads the store, and only a thin per-repo digest/summary note is written into the vault so FTS and context packs have a discoverable anchor. The watermark lives in the store header; the miner consumes JSONL records directly (not notes) and emits ADR candidate notes keyed by SHA; arch-docs uses the same scannerβfactsβrenderer kernel but its facts come from a directory scan rather than git.+- **Trade-offs**:+ - Pro: compact, fast, no vault bloat; analytical queries (fan-in/out, author/release rollups) are cheap and deterministic.+ - Pro: structured edges avoid wikilink explosion and keep the backlink index clean.+ - Pro: clean per-task reuse β one git reader, one record store, one renderer.+ - Con: needs and must maintain a new query surface; commit-level "why did this file change" answers depend on that path, not raw FTS.+ - Con: digest-only notes mean fine-grained commit text is not individually FTS-searchable unless the query path is wired into context packs explicitly.+ - Con: two storage idioms (JSONL records + markdown notes) for operators to understand.+- **Complexity**: medium+- **Risk**: medium++### Variant 3: Hybrid kernel (JSONL source of truth + per-repo digest notes + selective decision notes)+- **Approach**: A JSONL/SQLite per-repo store is the canonical source of truth for commits and edges (structured fields), and a shared kernel β sanitized git reader, record store, and fact-to-markdown renderer β is built once and consumed by all of Tasks 1β3; the vault gets per-repo digest notes (FTS-discoverable, context-pack-eligible) plus selective per-commit notes only where a record is promoted (a mined ADR candidate links back to its source commit record). Edges are dual-represented: structured in JSONL for query, and rendered as wikilinks in the digest/candidate notes for graph traversal. Arch-docs and ADR candidates both flow through the shared renderer plus a single region-merge engine using `<!-- @generated:id -->`/`<!-- @user -->` sentinels with stable region ids and preserve-on-conflict behavior. Task 4 stays independent β it only adds a `"query"` mode to the existing telemetry gate.+- **Trade-offs**:+ - Pro: compact storage and cheap analytics from the store, plus FTS/graph discoverability from rendered notes β captures both prior variants' upsides.+ - Pro: maximizes shared infrastructure (one reader, one store, one renderer, one region engine) per the "design shared infra once" constraint; selective promotion avoids file explosion.+ - Pro: ADR candidates and arch-docs naturally inherit the region-merge and renderer, so re-run idempotency and edit preservation are solved once.+ - Con: dual edge representation risks drift between JSONL fields and rendered wikilinks if not generated from one source.+ - Con: largest surface area to build and test in a single PR; most moving parts.+ - Con: still introduces a query path (smaller than Variant 2's, since digests carry common cases).+- **Complexity**: large+- **Risk**: medium++### Recommended: Variant 3+**Rationale**: The four tasks explicitly ship as one PR with shared infrastructure designed once, and a hybrid kernel is the only variant where the git reader, record store, fact renderer, and region-merge engine are built a single time and reused across ingest, arch-docs, and the decision miner. It avoids Variant 1's vault/FTS bloat (thousands of commit files, wikilink fan-out) while still answering "why/when a file changed" through FTS-discoverable digests and context packs, and it keeps storage compact and analytics deterministic like Variant 2 β with the dual-edge drift risk contained by always rendering wikilinks from the canonical JSONL records.diff --git a/docs/brainstorm/project-history-suite/cli-output/prompt.md b/docs/brainstorm/project-history-suite/cli-output/prompt.mdnew file mode 100644index 00000000..d269b18f--- /dev/null+++ b/docs/brainstorm/project-history-suite/cli-output/prompt.md@@ -0,0 +1,114 @@+You are brainstorming architectural variants for the following task. Do not write code. Do not write a final design. Only produce variants and a recommendation.++# Task++One PR ships the "Project History Suite" for Open Second Brain - four related kanban tasks that turn a linked project's git history and code structure into queryable Second Brain memory:++## Task 1 (t_c812752c, priority 2): Git history memory with commit, file, author, and release edges++Add optional Git history ingestion for linked project worktrees. It should create local Brain records for commits, tags, and releases, link commits to files and authors, and update incrementally from a per-repository watermark.++Suggested design from the upstream study (Keep):+- Use a sanitized non-interactive `git log --name-only` reader with bounded commit limits and strict SHA validation for watermarks.+- Store commit records with message, author, timestamp, repo identity, full SHA, touched files, and source path.+- Add typed edges from files to latest commit and from commits to touched files, authors, tags, and releases.+- Integrate with project/worktree registry and optional watches so new commits are indexed after branch switches or checkouts.+- Provide scoped search/report commands such as `brain git-history find` or include commit results in existing context packs when project scope matches.++Acceptance criteria:+- OSB can ingest commits from a linked Git repository without modifying the repository or Git index.+- Incremental re-runs use a validated watermark and do not duplicate commits.+- Commit, file, author, tag, and release relationships are represented as typed Brain edges.+- Search/context pack output can answer why/when a file changed using commit records.+- Tests cover initial ingest, incremental ingest, malformed watermark handling, branch/HEAD movement, and missing Git fallback.++## Task 2 (t_929da8a2, priority 2): Auto-generate architecture docs for code projects with sentinel markers++A command points at a software project and auto-generates a maintained set of architecture notes in the vault: an overview, one note per core module, and a key-decisions note. Sentinel markers (`<!-- @generated -->` / `<!-- @user -->`) ensure re-runs only update generated content without clobbering manual edits. A deterministic stdlib-only scanner produces facts.++IMPORTANT project constraint: Open Second Brain core NEVER calls an LLM internally. The upstream feature uses an LLM for prose synthesis; our version must be fully deterministic - the scanner produces structured facts (module inventory, dependency fan-in/out, entry points, file counts, languages), and the generated notes render those facts as structured markdown. LLM prose, if any, is the CALLING agent's job and would live in the @user regions or via future write surfaces.++Acceptance criteria (adapted):+- A CLI verb scans a project directory deterministically (no network, no LLM) and writes/updates architecture notes in the vault.+- Sentinel-marker regions: re-running regeneration replaces only @generated regions, preserves @user regions byte-for-byte.+- Re-run on an unchanged project is idempotent (no diff).+- Tests cover first generation, regeneration with user edits preserved, module add/remove, marker corruption handling.++## Task 3 (t_93d299bb, priority 1): Commit-decision miner - surface decision-shaped commits as ADR candidates++Scan commit messages (from the records Task 1 ingested) for decision-making language and propose them as draft ADR (Architecture Decision Record) candidate notes pending operator review. Deterministic heuristics only (conventional-commit markers, decision keywords/patterns), no LLM classification.++Acceptance criteria (adapted):+- A miner pass over ingested commit records produces draft decision-candidate notes in a dedicated vault area, each linking back to its source commit record.+- Deterministic scoring/matching: same input always yields the same candidates.+- Re-runs do not duplicate candidates (stable candidate identity derived from commit SHA).+- Tests cover marker-based detection, keyword detection, dedup on re-run, and empty-history behavior.++## Task 4 (t_405b8053 delta, priority 0): Close the query telemetry gap for brain_query++Open Second Brain v0.39.0 already ships recall telemetry for brain_search, context packs, pre-compress, and the recall gate, all routed through a lazy gated emit kernel (`emitGatedTelemetry`) into continuity records (`Brain/log/continuity/YYYY-MM.jsonl`). The one remaining query surface without telemetry is the `brain_query` MCP tool (preference/topic/log-since aggregations). Extend the existing `RecallTelemetryMode` union with a `"query"` mode and wire the brain_query handler through the same gate (`resolveRecallGateTelemetry`), mirroring the brain_search pattern (success and error paths, no raw query text persisted).++Acceptance criteria:+- With telemetry gate off (default): zero continuity writes, payload thunk never invoked.+- With gate on: brain_query emits one recall_telemetry record with mode "query", duration, result count, status.+- Raw query arguments (preference ids, topics) are hashed or summarized, never stored verbatim if they could contain private text - follow whatever brain_search does today.+- Tests: no-consumer regression test plus gated-emission test.++# Project context++Open Second Brain - TypeScript on Bun, an agent memory layer over Obsidian-compatible Markdown vaults. CLI (`o2b`) + MCP server. 3619 tests, strict tsc, oxlint.++Recent commits:+8e8c0bc feat: Memory Observability Suite - versioned continuity contract, lazy telemetry, ATOF/ATIF export, recall benchmark (#70)+eb56c9f feat: Workspace Insight Suite - project pointers, cross-vault recall, trigger queue, proactive synthesis (#69)+707197a feat: Agent Surface Suite - skills over MCP, two-pass tool catalog, surface profiles, session lifecycle (#68)+eda202d feat: Embedding Provider Suite - local embedder, provider registry, cost gate, RRF fusion (#67)+dee5ab7 feat: Memory Integrity Suite - canonical entities, conflict-free log shards, capture boundaries, fact extraction (#66)++Related existing infrastructure:+- Project/worktree registry (v0.38): `.o2b-vault.json` pointer files + `projects.json` registry beside config; `src/core/brain/portability/pointer.ts` (writeVaultPointer, findVaultPointer, registerLinkedProject, listLinkedProjects); CLI `o2b brain project link|list|remove|status`.+- Existing git-reading code: `src/core/discipline/activity-git.ts` - `gitActivity()` shells out to `git log --since --until --no-merges --numstat`, fail-soft null on error. Pattern to follow for a sanitized non-interactive git reader.+- Inline markers: `src/core/brain/inline.ts` parses `@osb` feedback markers (inline + fenced block forms) with originText preservation - a related but different mechanism from HTML-comment sentinel regions; the arch-docs generator needs its own region merge engine.+- Note writing: notes are plain markdown with YAML frontmatter; `Brain/preferences/pref-<slug>.md` pattern; atomic writes via fs-atomic helpers; markdown Brain log + JSONL sidecar per day in `Brain/log/`.+- Typed links: schema packs expose `link_types` (e.g. contradicts, supersedes) configured in the vault schema; wikilinks `[[target]]` are the graph edge primitive, backlink index parses them.+- Search: SQLite FTS5 over vault markdown (tokens implicit-AND), plus optional vector index. New markdown notes under any Brain/ path are picked up by reindex; context packs (`brain_context_pack`) assemble budgeted evidence.+- Telemetry: `emitGatedTelemetry(gate, build)` kernel in `src/core/brain/continuity/emit.ts`; recall telemetry records in monthly continuity shards; config gate `resolveRecallGateTelemetry` (env `OPEN_SECOND_BRAIN_RECALL_GATE_TELEMETRY` || config key, default off).+- CLI verb registration: `src/cli/brain/verbs/index.ts` (export), `src/cli/brain.ts` (import+dispatch), `src/cli/brain/verbs/help-text.ts` (BRAIN_HELP + VERB_HELP), `src/cli/command-manifest.ts` (name+summary).++Conventions:+- Core logic in `src/core/brain/<area>/`, CLI wrappers in `src/cli/brain/verbs/`, MCP wrappers in `src/mcp/*-tools.ts`.+- Fail-fast for primary writes, fail-soft/fail-open for telemetry and external resources (git, pointers).+- Readonly types, pure functions where possible, domain errors with `code` property.+- MCP tool count is a watched contract (65 advertised tools in v0.39.0); CLI-only surfaces are preferred for operator/batch workflows; MCP additions need strong justification.++Constraints:+- No new external dependencies (no nodegit, no PDF libs - shell out to `git` binary like activity-git.ts does).+- Open Second Brain core never calls an LLM internally; everything in this PR must be deterministic.+- Do not change existing public APIs; additive only.+- Never modify the scanned repository or its git index; read-only `git log` / `git tag` style commands with strict argument sanitization (no user-controlled flags, validated SHAs, `--` separators).+- Private-region and visibility rules apply to anything that lands in vault notes or continuity records.+- The four tasks ship as ONE PR with atomic per-task commits; shared infrastructure should be designed once, not duplicated.++Key open design questions you should take a position on in each variant:+1. Where do commit records live: (a) one markdown note per commit in the vault (searchable via existing FTS, but potentially thousands of files), (b) a JSONL/SQLite sidecar store with a thin markdown summary layer (compact, but needs its own query path), or (c) hybrid - JSONL store as source of truth + per-repo digest notes that FTS can find?+2. How are typed edges represented: wikilinks in markdown, structured fields in JSONL records, or both?+3. How does the commit-decision miner consume Task 1's records, and where do ADR candidates live?+4. How does the arch-docs generator's region merge engine work (HTML comment sentinels, region ids, conflict behavior)?+5. What is the shared kernel across tasks 1-3 (git reader, record store, note renderer) and what stays per-feature?++# Required output format++Produce exactly 3 distinct architectural variants. For each variant:++### Variant N: <short name>+- **Approach**: 2-3 sentences describing the variant.+- **Trade-offs**: bullet list of pros and cons.+- **Complexity**: small | medium | large+- **Risk**: low | medium | high++After the three variants, add exactly one recommendation:++### Recommended: Variant N+**Rationale**: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.++Output nothing outside of these sections.diff --git a/docs/brainstorm/project-history-suite/design.md b/docs/brainstorm/project-history-suite/design.mdnew file mode 100644index 00000000..e40c7fa1--- /dev/null+++ b/docs/brainstorm/project-history-suite/design.md@@ -0,0 +1,62 @@+# Project History Suite - git history as Second Brain memory++**Status:** accepted+**Author:** claude-dev-agent (via feature-release-playbook)+**Audience:** implementation+**Kanban:** epic t_41c34987; children t_c812752c (git history memory, p2), t_929da8a2 (arch docs generator, p2), t_93d299bb (commit-decision miner, p1), t_405b8053 delta (brain_query telemetry, p0)++## Problem statement++A linked project's git history is the largest source of durable project memory, yet none of it is visible to the Brain: an agent cannot answer "why did this file change", "which release carried that change", or "which commits were decisions". Separately, code projects have no vault-native architecture documentation that survives regeneration, and `brain_query` is the one remaining recall surface without telemetry after the v0.39.0 observability contract.++## Scope++- **Git history ingest** (`o2b brain git ingest`): sanitized read-only `git log` reader over a project worktree; commit, tag, and release-range records appended to a per-repo JSONL store inside the vault; incremental re-runs via a SHA-validated watermark; per-repo digest note rendered into the vault so FTS and context packs can discover history.+- **Git history query** (`o2b brain git find` / `o2b brain git status`): deterministic query path over the JSONL store - by free text, touched file, author, or time range; status reports per-repo watermark and record counts.+- **Region merge engine** (`src/core/brain/regions.ts`): HTML-comment sentinel regions (`<!-- o2b:begin <id> -->` / `<!-- o2b:end <id> -->`); regeneration replaces only generated region bodies, preserves everything else byte-for-byte, appends new regions, fails closed on corrupted markers.+- **Architecture docs generator** (`o2b brain architect <path>`): deterministic stdlib-only project scanner (module inventory, language mix, entry points, manifest summary, test layout) rendering an overview note plus one note per core module into the vault through the region engine; idempotent re-runs.+- **Commit-decision miner** (`o2b brain git mine`): deterministic heuristics over ingested commit records (conventional-commit markers, breaking-change footers, decision keywords, revert shape) producing draft ADR candidate notes with stable SHA-derived identity; re-runs never duplicate and never clobber operator edits.+- **brain_query telemetry**: extend `RecallTelemetryMode` with `"query"`; wire the `brain_query` MCP handler through `emitGatedTelemetry` with per-call opt-in args mirroring `brain_search` (success and error paths); query argument values are never persisted - only the query kind.++## Out of scope++- No new MCP tools: every new surface is CLI-only; the MCP contract stays at 65 advertised tools. The only MCP change is additive - `brain_query` gains optional telemetry arguments mirroring `brain_search` (operator/batch workflows, same rationale as `bench` and `continuity export` in v0.39.0).+- No daemon watches / filesystem watchers: incremental ingest is invoked explicitly (operator, cron, or agent); the upstream "watch" concept reduces to cheap idempotent re-runs.+- No LLM anywhere: no commit-message classification by model, no prose synthesis in arch docs. Generated notes carry deterministic facts; agent- or operator-authored prose lives outside generated regions.+- No import-graph analysis in the scanner (per-language parsing is a later task); module facts come from directory structure, file extensions, and manifests.+- No per-commit vault notes: selective promotion only (ADR candidates). The JSONL store is the only per-commit representation.+- No cross-repo analytics or author identity resolution beyond the recorded name/email string.++## Chosen approach++Consultant Variant 3 (hybrid kernel), accepted as recommended. A per-repo JSONL store inside the vault is the canonical source of truth for commits, tags, and release ranges, with structured fields as the edge representation. The vault sees only rendered markdown: one digest note per repo (FTS-discoverable anchor with hot files, recent commits, releases) and selectively promoted ADR candidate notes. One shared kernel serves all three code-facing tasks: the sanitized git reader (modelled on `activity-git.ts`), the JSONL record store with watermark, and the region merge engine that both the arch-docs generator and the ADR candidate renderer use for regeneration safety. Wikilinks in rendered notes are always derived from store records, never hand-maintained, which contains the dual-representation drift risk the consultant flagged. Task 4 stays independent and additive on the v0.39.0 telemetry seam.++## Design decisions++- **Store location `Brain/projects/git/<repo-key>/`** (`commits.jsonl`, `state.json`, `digest.md`): inside the vault so multi-device sync carries project memory with the Brain, unlike the device-local `projects.json` registry. FTS indexes only the `.md` digest; JSONL stays machine-facing. Namespace verified unused.+- **Repo key = `<sanitized-basename>-<8-hex of sha256(absolute path)>`**: human-readable, collision-safe across same-named repos, stable for a given checkout location.+- **Git reader uses `execFileSync` with fixed argv** (no shell, no user-controlled flags, `--` separators, `-C <path>`): the proven `activity-git.ts` pattern. Commit fields parsed from `git log` with NUL field separators (`%x00`) and a unique record sentinel; `--name-only` for touched files. Bounded by `--max-count` (default 1000 per run, flag-overridable).+- **Watermark = `state.json` with `last_sha` (40-hex validated) + `last_ingested_at`**: re-run ingests `<last_sha>..HEAD` only. A watermark SHA that no longer resolves (`git cat-file -e`, e.g. after force-push) triggers a clean full re-scan; store dedup by SHA keeps that idempotent.+- **Release attribution via tag ranges**: for chronologically ordered tags, `git rev-list <prev>..<tag>` assigns each commit its carrying release in one git call per tag - the standard changelog attribution, no per-commit ancestry walks.+- **Typed edges as structured record fields** (`files`, `author`, `release`, tag records with `target_sha`): queryable without graph scans; wikilink rendering happens only in digest/candidate notes and is always regenerated from records.+- **Region engine fails closed**: unbalanced or duplicated sentinels abort the write with a domain error naming the offending region; a corrupted file is never partially rewritten. Operator text outside regions and the exact bytes of `@user` content are preserved verbatim.+- **ADR candidate identity = commit SHA** (`Brain/decisions/candidates/adr-<shortsha>-<slug>.md`): re-runs skip existing candidate files entirely (strongest no-clobber guarantee for operator-curated drafts); frontmatter carries `status: candidate`, repo key, full SHA, matched signals.+- **Decision heuristics are transparent**: each candidate records which deterministic signals matched (conventional `feat!`/`BREAKING CHANGE`, keyword set: decide/decision/adopt/switch to/migrate to/instead of/ADR/rationale, revert shape). Same input, same candidates, same order.+- **Arch-docs notes live at `Brain/projects/arch/<repo-key>/`** (`overview.md`, `modules/<module>.md`): same repo-key namespace as git history, so one project's memory clusters under one prefix.+- **brain_query telemetry is per-call opt-in** (`telemetry: true` + `telemetry_host`/`session_id`/`turn_id`), exactly like `brain_search` - not config-gated, because the caller owns the session correlation. Payload stores the query kind (`preference`/`topic`/`since`), duration, result count, status; never the supplied preference id, topic slug, or timestamp value.++## File changes++New core: `src/core/brain/git/{identity,reader,store,ingest,digest,decisions}.ts`, `src/core/brain/regions.ts`, `src/core/brain/architect/{scan,generate}.ts`.+New CLI: `src/cli/brain/verbs/git.ts` (ingest/status/find/mine subcommands), `src/cli/brain/verbs/architect.ts`; registration in `verbs/index.ts`, `brain.ts`, `help-text.ts`, `command-manifest.ts`.+Modified: `src/core/brain/recall-telemetry.ts` (mode union + guard), `src/mcp/brain-tools.ts` (brain_query schema + handler telemetry).+New tests: `tests/core/brain/git/{reader,store,ingest,decisions}.test.ts`, `tests/core/brain/{regions,architect}.test.ts`, `tests/cli/{brain-git,brain-architect}.test.ts`, `tests/mcp/brain-query-telemetry.test.ts`, `tests/e2e/project-history.integration.test.ts`.+Docs: `README.md`, `CHANGELOG.md`, `docs/cli-reference.md`, `docs/how-it-works.md`, `docs/observability.md` (mode list), this brainstorm directory.++## Risks and open questions++- Git output parsing must survive commit messages containing the field sentinel; mitigated by NUL separators plus a low-collision record sentinel and tests with adversarial messages.+- Large repos: first ingest bounded by `--max-count` default; digest renders only bounded sections (recent N commits, top N hot files) so note size stays flat.+- Tag ranges assume tags are reachable from HEAD's history; commits outside any range simply carry no release field (correct for unreleased work).+- Module detection heuristics (src/ vs packages/ vs flat layouts) need a fixture matrix; the scanner must degrade to "one module: project root" rather than guessing.+- The region engine is new shared infrastructure consumed by two features in the same PR; it lands first with exhaustive tests before either consumer.diff --git a/docs/brainstorm/project-history-suite/plan.md b/docs/brainstorm/project-history-suite/plan.mdnew file mode 100644index 00000000..5424f361--- /dev/null+++ b/docs/brainstorm/project-history-suite/plan.md@@ -0,0 +1,50 @@+# Project History Suite - implementation plan++One PR, atomic per-task commits on `feat/project-history-suite`. Formatter + linter green before every commit. TDD: each task starts with failing tests.++## Tasks++### Task 1: Git kernel - repo identity and sanitized reader+- **Files**: `src/core/brain/git/identity.ts` (repo key derivation), `src/core/brain/git/reader.ts` (readCommits with NUL-separated fields + name-only files, readTags, revListRange, shaExists; execFileSync fixed-argv, fail-soft null on git errors, SHA validation helpers); `tests/core/brain/git/reader.test.ts` against real temp git repos (init/commit/tag fixtures), including adversarial commit messages and missing-git-dir fallback.+- **Acceptance**: reader returns structured commits (sha, author name/email, ISO date, subject, body, files) and tags from a fixture repo; bounded by maxCount; never modifies the repo; malformed/absent repos return null.+- **Depends on**: none++### Task 2: Git record store with watermark+- **Files**: `src/core/brain/git/store.ts` (per-repo dir `Brain/projects/git/<repo-key>/`, append commit/tag records to `commits.jsonl` with SHA dedup, `state.json` watermark read/write with 40-hex validation, list/filter API: by file, author, since/until, free-text over subject+body); `tests/core/brain/git/store.test.ts`.+- **Acceptance**: appends are idempotent by SHA; malformed watermark is rejected and reported; filters return deterministic ordered results.+- **Depends on**: Task 1 (record shapes)++### Task 3: Ingest orchestration, release attribution, digest note, CLI `o2b brain git`+- **Files**: `src/core/brain/git/ingest.ts` (full + incremental ingest, watermark advance, tag-range release attribution via revListRange, force-push fallback to full re-scan), `src/core/brain/git/digest.ts` (digest.md renderer: repo header, releases, recent commits, hot files - rendered from records only; wikilinks appear solely for vault-resident promoted notes such as ADR candidates, repo file paths stay plain text); `src/cli/brain/verbs/git.ts` (subcommands ingest/status/find, --json), registration in `verbs/index.ts`, `src/cli/brain.ts`, `help-text.ts`, `command-manifest.ts`; `tests/core/brain/git/ingest.test.ts`, `tests/cli/brain-git.test.ts`.+- **Acceptance**: initial ingest + incremental ingest (no duplicates) + release edges on a fixture repo with tags; `git find --file <f>` answers "when/why did this file change"; digest note discoverable by search after reindex; status shows watermark.+- **Depends on**: Tasks 1, 2++### Task 4: Region merge engine+- **Files**: `src/core/brain/regions.ts` (parseRegions, mergeRegions: replace generated bodies by region id, preserve non-region text byte-for-byte, append new regions, fail-closed domain error on unbalanced/duplicate sentinels); `tests/core/brain/regions.test.ts`.+- **Acceptance**: regeneration over an operator-edited file changes only generated regions; corrupted markers abort without writing; idempotent merge produces zero diff.+- **Depends on**: none++### Task 5: Architecture docs generator + CLI `o2b brain architect`+- **Files**: `src/core/brain/architect/scan.ts` (deterministic project facts: modules from src/packages/flat layouts, language mix by extension, entry points from manifests, test layout, file counts), `src/core/brain/architect/generate.ts` (overview + per-module notes under `Brain/projects/arch/<repo-key>/` through the region engine), `src/cli/brain/verbs/architect.ts` + 4 registration points; `tests/core/brain/architect.test.ts`, `tests/cli/brain-architect.test.ts`.+- **Acceptance**: first run creates overview + module notes; re-run after operator edits preserves user text; module add/remove reflected on regen; unchanged project regen is byte-identical.+- **Depends on**: Task 4++### Task 6: Commit-decision miner + CLI `o2b brain git mine`+- **Files**: `src/core/brain/git/decisions.ts` (deterministic signal matchers + candidate note renderer to `Brain/decisions/candidates/adr-<shortsha>-<slug>.md`, skip-existing semantics), `mine` subcommand in `src/cli/brain/verbs/git.ts`; `tests/core/brain/git/decisions.test.ts`, CLI case in `tests/cli/brain-git.test.ts`.+- **Acceptance**: decision-shaped fixtures produce candidates with matched-signal provenance; non-decision commits produce nothing; re-run duplicates nothing and preserves operator-edited candidates (skip-existing, no region merge - orchestrator decision 3); empty history is a clean no-op.+- **Depends on**: Tasks 2, 3 (records)++### Task 7: brain_query telemetry+- **Files**: `src/core/brain/recall-telemetry.ts` (mode union + `isRecallTelemetryMode`), `src/mcp/brain-tools.ts` (brain_query input schema: telemetry/telemetry_host/session_id/turn_id; handler wiring through emitGatedTelemetry on success and error paths, kind-only payload); `tests/mcp/brain-query-telemetry.test.ts` (no-consumer regression + gated emission + no-raw-values assertion against persisted continuity files).+- **Acceptance**: telemetry off (default) writes zero continuity records and never runs the payload thunk; on, one record with mode "query", correct status/duration/result_count; persisted files never contain the supplied preference/topic/since values.+- **Depends on**: none++### Task 8: End-to-end integration test+- **Files**: `tests/e2e/project-history.integration.test.ts` (temp git repo + temp vault: ingest β find β mine β architect β re-run idempotency in one flow).+- **Acceptance**: full flow green in one process; re-runs of all three generators produce no duplicates and no clobbered edits.+- **Depends on**: Tasks 1-6++### Task 9: Docs+- **Files**: `README.md`, `CHANGELOG.md` (one new version), `docs/cli-reference.md`, `docs/how-it-works.md`, `docs/observability.md` (telemetry mode list + brain_query row).+- **Acceptance**: docs match shipped behavior; CHANGELOG bullets per feature.+- **Depends on**: Tasks 1-8diff --git a/docs/brainstorm/project-history-suite/variants.md b/docs/brainstorm/project-history-suite/variants.mdnew file mode 100644index 00000000..819e5c39--- /dev/null+++ b/docs/brainstorm/project-history-suite/variants.md@@ -0,0 +1,56 @@+# Project History Suite - variants audit trail++Consultant: Claude Code (`claude -p`), prompt in `cli-output/prompt.md`, raw output in `cli-output/claude.md`. Fallback consultant not needed (primary returned 3 parseable variants, exit 0).++## Variant 1: Markdown-native (one note per commit, wikilink edges)++- **Approach**: Every ingested commit becomes a markdown note under `Brain/git/<repo>/commits/<sha>.md` with YAML frontmatter and a body; tags/releases/authors get their own notes; all edges are `[[wikilinks]]` resolved by the existing backlink index and surfaced through FTS5 and context packs with no new query path. The watermark is a small per-repo state note (or frontmatter on a repo index note); the miner reads commit notes back via FTS keyword scan and writes ADR candidates as sibling notes under `Brain/decisions/candidates/`; arch-docs reuses the same note renderer with an HTML-comment region-merge layer on top.+- **Trade-offs**:+ - Pro: zero new query infrastructure - everything is searchable, backlinkable, and context-pack-eligible the day it lands.+ - Pro: edges are first-class graph primitives (wikilinks), matching the existing typed-link/backlink model exactly.+ - Pro: incremental ingest dedup is trivial (note exists at deterministic path = already ingested).+ - Con: thousands of tiny files per active repo bloats the vault, reindex time, and backlink index; FTS noise drowns user notes.+ - Con: file-touch edges (commit-file) explode wikilink fan-out; a 500-file commit writes 500 links.+ - Con: no compact analytical query (fan-in/out, author rollups) without scanning many notes.+- **Complexity**: medium+- **Risk**: high++## Variant 2: Sidecar store (JSONL/SQLite source of truth, structured edges, thin digest notes)++- **Approach**: Commits, tags, releases, authors, and all edges live as structured records in a per-repo append-only JSONL store (mirroring `Brain/log/` shard conventions), with edges as typed structured fields inside records rather than wikilinks; a dedicated `brain git-history` query path reads the store, and only a thin per-repo digest/summary note is written into the vault so FTS and context packs have a discoverable anchor. The watermark lives in the store header; the miner consumes JSONL records directly (not notes) and emits ADR candidate notes keyed by SHA; arch-docs uses the same scanner-facts-renderer kernel but its facts come from a directory scan rather than git.+- **Trade-offs**:+ - Pro: compact, fast, no vault bloat; analytical queries (fan-in/out, author/release rollups) are cheap and deterministic.+ - Pro: structured edges avoid wikilink explosion and keep the backlink index clean.+ - Pro: clean per-task reuse - one git reader, one record store, one renderer.+ - Con: needs and must maintain a new query surface; commit-level "why did this file change" answers depend on that path, not raw FTS.+ - Con: digest-only notes mean fine-grained commit text is not individually FTS-searchable unless the query path is wired into context packs explicitly.+ - Con: two storage idioms (JSONL records + markdown notes) for operators to understand.+- **Complexity**: medium+- **Risk**: medium++## Variant 3: Hybrid kernel (JSONL source of truth + per-repo digest notes + selective decision notes)++- **Approach**: A JSONL/SQLite per-repo store is the canonical source of truth for commits and edges (structured fields), and a shared kernel - sanitized git reader, record store, and fact-to-markdown renderer - is built once and consumed by all of Tasks 1-3; the vault gets per-repo digest notes (FTS-discoverable, context-pack-eligible) plus selective per-commit notes only where a record is promoted (a mined ADR candidate links back to its source commit record). Edges are dual-represented: structured in JSONL for query, and rendered as wikilinks in the digest/candidate notes for graph traversal. Arch-docs and ADR candidates both flow through the shared renderer plus a single region-merge engine using `<!-- @generated:id -->`/`<!-- @user -->` sentinels with stable region ids and preserve-on-conflict behavior. Task 4 stays independent - it only adds a `"query"` mode to the existing telemetry gate.+- **Trade-offs**:+ - Pro: compact storage and cheap analytics from the store, plus FTS/graph discoverability from rendered notes - captures both prior variants' upsides.+ - Pro: maximizes shared infrastructure (one reader, one store, one renderer, one region engine) per the "design shared infra once" constraint; selective promotion avoids file explosion.+ - Pro: ADR candidates and arch-docs naturally inherit the region-merge and renderer, so re-run idempotency and edit preservation are solved once.+ - Con: dual edge representation risks drift between JSONL fields and rendered wikilinks if not generated from one source.+ - Con: largest surface area to build and test in a single PR; most moving parts.+ - Con: still introduces a query path (smaller than Variant 2's, since digests carry common cases).+- **Complexity**: large+- **Risk**: medium++## Consultant recommendation++Variant 3. "The four tasks explicitly ship as one PR with shared infrastructure designed once, and a hybrid kernel is the only variant where the git reader, record store, fact renderer, and region-merge engine are built a single time and reused across ingest, arch-docs, and the decision miner. It avoids Variant 1's vault/FTS bloat (thousands of commit files, wikilink fan-out) while still answering 'why/when a file changed' through FTS-discoverable digests and context packs, and it keeps storage compact and analytics deterministic like Variant 2 - with the dual-edge drift risk contained by always rendering wikilinks from the canonical JSONL records."++## Orchestrator decision++Variant 3 accepted, with three containment refinements:++1. **Plain JSONL, no SQLite, for the store** - the per-repo record volume (bounded ingest, default 1000 commits per run) does not justify a second SQLite schema next to the search index; the existing `Brain/log/` JSONL conventions cover append, dedup, and tolerant reads. KISS.+2. **Sentinel grammar `o2b:begin <id>` / `o2b:end <id>`** instead of the consultant's `@generated:id`/`@user` pair - explicit paired ids make fail-closed validation (unbalanced/duplicate detection) unambiguous, and everything outside regions is implicitly operator-owned, so no second marker kind is needed.+3. **ADR candidates use skip-existing, not region merge** - a candidate is an operator-curated draft; once it exists, regeneration never touches it. Region merge is reserved for the arch-docs notes whose generated facts must refresh on re-scan.++These narrow Variant 3's main con (surface area) without giving up the shared kernel.diff --git a/docs/cli-reference.md b/docs/cli-reference.mdindex 2b1d43de..b574a0b4 100644--- a/docs/cli-reference.md+++ b/docs/cli-reference.md@@ -145,6 +145,18 @@ o2b brain bench memory --fixture <name|path> [--resume <run-id>] [The benchmark never touches the configured vault - the fixture materializes into `<runs-dir>/<run-id>/vault` (default runs dir `.open-second-brain/bench-runs/`, gitignored). The optional `bench_judge_cmd` config key (env `OPEN_SECOND_BRAIN_BENCH_JUDGE_CMD`) arms an advisory external judge; absent means the judge phase is skipped. The full observability contract (event kinds, gates, correlation ids, payload safety, schema version) lives in `docs/observability.md`.+### Project history (since v0.40.0)++```text+o2b brain git ingest <repo-path> [--max-count N] - read-only walk of a worktree; commit/tag/release records + digest note land under Brain/projects/git/<repo-key>/; incremental via SHA-validated watermark, full re-scan with a reported warning on force-push or tampered state+ status - per-repo watermarks and record counts+ find [text] [--repo K] [--file F] [--author A] [--since S] [--until U] [--limit N] - query ingested history newest-first; no live git on the query path+ mine [--repo K] - surface decision-shaped commits as draft ADR candidate notes under Brain/decisions/candidates/ (sha-stable identity, skip-existing)+o2b brain architect <project-path> - deterministic stdlib-only project scan rendered as architecture notes under Brain/projects/arch/<repo-key>/; generated content lives in o2b:begin/o2b:end sentinel regions, operator prose outside regions survives every re-scan byte-for-byte+```++All flags accept `--vault V` and `--json`. The ingest never modifies the scanned repository; every caller-supplied sha is validated against the full-40-hex grammar before it can reach a git argument.+## Vault scopeSingle exclusion policy for every vault walker.diff --git a/docs/how-it-works.md b/docs/how-it-works.mdindex 6ad64ce6..6eacb468 100644--- a/docs/how-it-works.md+++ b/docs/how-it-works.md@@ -893,6 +893,46 @@ change cannot hide a token-cost regression behind a quality win. Thefull contract - every event kind, its gate, correlation ids, payloadsafety, fail-open rules - lives in `docs/observability.md`.+## Project history as memory (since v0.40.0)++A linked project's git history is durable project memory, and the+Project History Suite makes it queryable without the repository+present. `o2b brain git ingest <repo-path>` walks a worktree with a+sanitized read-only reader (fixed argv, full-40-hex sha validation on+everything a caller could supply) and lands commits, tags, and+release ranges as structured records in+`Brain/projects/git/<repo-key>/commits.jsonl`. Typed edges are record+fields - touched files, author, the carrying release attributed by+chronological tag ranges - and a watermark bounds every later run to+`<last>..HEAD`, so incremental ingest is duplicate-free by+construction. A force-pushed or tampered watermark degrades to a+reported full re-scan, never to silent loss. Each repo gets one+deterministic digest note (releases, recent commits, hot files), so+full-text search can discover the history, while `o2b brain git find`+answers "why and when did this file change" from the store alone.++Decision-shaped commits become first-class memory through `o2b brain+git mine`: deterministic heuristics (conventional breaking markers,+BREAKING CHANGE footers, word-boundary decision keywords, revert+shape) surface draft ADR candidates under+`Brain/decisions/candidates/` with matched-signal provenance. A+candidate's identity is its commit sha: re-runs never duplicate, and+an existing file is never touched, so operator curation owns the+draft from the moment it exists.++Architecture knowledge gets the same treatment via `o2b brain+architect <project-path>`: a stdlib-only scanner derives structural+facts (module layout, language mix, entry points, manifests, test+layout - no LLM, no network) and renders an overview plus per-module+notes under `Brain/projects/arch/<repo-key>/`. Generated content+lives between paired `<!-- o2b:begin <id> -->` / `<!-- o2b:end <id>+-->` sentinels: regeneration replaces only generated bodies, operator+prose outside regions survives byte-for-byte, and corrupted markers+fail closed before any write. The same release also closes the+observability gap v0.39.0 left open: `brain_query` now emits opt-in+recall telemetry with a kind-only payload, so the supplied preference+id, topic, or timestamp never lands in a continuity record.+## Safety propertiesThese are invariants of the system, not configuration to enable.diff --git a/docs/observability.md b/docs/observability.mdindex 2da4ca2c..b944df8c 100644--- a/docs/observability.md+++ b/docs/observability.md@@ -30,7 +30,7 @@ Every continuity record shares one envelope: `schema`, `id`, `kind`, `createdAt`| Kind | Gate | Emitted by ||---|---|---|-| `recall_telemetry` | opt-in per call (`telemetry` option/param) | `packContext` (`mode: context_pack`), `buildPreCompressPack` (`mode: pre_compress`), `brain_search` MCP handler (`mode: search`) |+| `recall_telemetry` | opt-in per call (`telemetry` option/param) | `packContext` (`mode: context_pack`), `buildPreCompressPack` (`mode: pre_compress`), `brain_search` MCP handler (`mode: search`), `brain_query` MCP handler (`mode: query`, since v0.40.0 - payload carries the query kind only, never the supplied preference id / topic / timestamp) || `context_receipt` | opt-in per call (`receipt` option/param) | `packContext`, `buildPreCompressPack` || `gate_telemetry` | config key `recall_gate_telemetry` (default off) | `brain_recall_gate` MCP handler || `session_turn`, `session_summary_node` | always-on within its operation | session-recall import (`src/core/brain/session-recall.ts`) - the write IS the operation |diff --git a/openclaw.plugin.json b/openclaw.plugin.jsonindex 264d44bf..863fc2c6 100644--- a/openclaw.plugin.json+++ b/openclaw.plugin.json@@ -2,7 +2,7 @@"id": "open-second-brain","name": "Open Second Brain","description": "Second brain for AI agents using Obsidian-compatible Markdown vaults.",- "version": "0.39.0",+ "version": "0.40.0","activation": { "onStartup": true },"skills": ["./skills"],"contracts": {diff --git a/package.json b/package.jsonindex 73db8335..138d2f0f 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "0.39.0",+ "version": "0.40.0","private": false,"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.","keywords": [diff --git a/plugin.yaml b/plugin.yamlindex ce9d4de7..ebe52026 100644--- a/plugin.yaml+++ b/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "0.39.0"+version: "0.40.0"description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."author: "Open Second Brain contributors"memory_provider: truediff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.jsonindex f5839eea..5479908c 100644--- a/plugins/codex/.codex-plugin/plugin.json+++ b/plugins/codex/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "0.39.0",+ "version": "0.40.0","description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.","author": {"name": "Open Second Brain contributors",diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yamlindex ce9d4de7..ebe52026 100644--- a/plugins/hermes/plugin.yaml+++ b/plugins/hermes/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "0.39.0"+version: "0.40.0"description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."author: "Open Second Brain contributors"memory_provider: truediff --git a/pyproject.toml b/pyproject.tomlindex ce000456..c843eec2 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -10,7 +10,7 @@ build-backend = "setuptools.build_meta"# CLI entry points (those moved to `package.json` `bin`).[project]name = "open-second-brain"-version = "0.39.0"+version = "0.40.0"description = "Hermes Python shim for Open Second Brain. Most of the project (CLI, MCP server, OpenClaw plugin) is TypeScript on Bun; see package.json."readme = "README.md"requires-python = ">=3.11"diff --git a/src/cli/brain.ts b/src/cli/brain.tsindex 6269fc4b..c2b6afff 100644--- a/src/cli/brain.ts+++ b/src/cli/brain.ts@@ -59,6 +59,8 @@ import {cmdBrainSgrep,cmdBrainContinuity,cmdBrainBench,+ cmdBrainGit,+ cmdBrainArchitect,cmdBrainTrigger,cmdBrainDeepSynthesis,cmdBrainIdeas,@@ -202,6 +204,10 @@ export async function handleBrainSubcommand(argv: ReadonlyArray<string>): Promisreturn await cmdBrainContinuity(rest);case "bench":return await cmdBrainBench(rest);+ case "git":+ return await cmdBrainGit(rest);+ case "architect":+ return await cmdBrainArchitect(rest);case "trigger":return await cmdBrainTrigger(rest);case "deep-synthesis":diff --git a/src/cli/brain/help-text.ts b/src/cli/brain/help-text.tsindex 7beb512c..1bb0c7d9 100644--- a/src/cli/brain/help-text.ts+++ b/src/cli/brain/help-text.ts@@ -90,6 +90,8 @@ Brain verbs (observing memory):ideas Ranked next-direction candidates from open loops (--triggers to enqueue)continuity Export continuity records as ATOF/ATIF trajectories (read-only)bench Memory quality benchmark over a disposable fixture vault+ git Git history as project memory: ingest, status, find, mine+ architect Deterministic architecture notes for a code projectCommon flags:--vault <path> Override the configured vault@@ -544,6 +546,21 @@ export const VERB_HELP: Record<string, string> = {"Read-only trajectory export of the continuity store. atof renders one\n" +"JSONL event stream; atif renders one trajectory document per session.\n" +"Records flagged private are dropped; redacted text stays masked.\n",+ architect:+ "usage: o2b brain architect <project-path> [--vault V] [--json]\n" ++ "Scan a project tree deterministically (stdlib-only, no LLM) and\n" ++ "write architecture notes under Brain/projects/arch/<repo-key>/.\n" ++ "Generated content lives in sentinel regions; operator prose\n" ++ "outside regions survives every re-scan byte-for-byte.",+ git:+ "usage: o2b brain git <ingest|status|find|mine> [args] [--vault V] [--json]\n" ++ "ingest <repo-path> [--max-count N] walk a worktree read-only, store\n" ++ "commit/tag records + digest note under Brain/projects/git/<repo-key>/.\n" ++ "status per-repo watermarks and record counts.\n" ++ "find [text] [--repo K] [--file F] [--author A] [--since S] [--until U]\n" ++ "[--limit N] query ingested history newest-first.\n" ++ "mine [--repo K] surface decision-shaped commits as draft ADR\n" ++ "candidate notes under Brain/decisions/candidates/ (skip-existing).",bench:"usage: o2b brain bench memory --fixture <name|path> [--resume <run-id>] [--runs-dir <dir>] [--json]\n" +"Memory quality benchmark over a disposable fixture vault under the\n" +diff --git a/src/cli/brain/verbs/architect.ts b/src/cli/brain/verbs/architect.tsnew file mode 100644index 00000000..a07b4253--- /dev/null+++ b/src/cli/brain/verbs/architect.ts@@ -0,0 +1,52 @@+/**+ * `o2b brain architect <project-path>` (Project History Suite,+ * t_929da8a2): deterministic architecture notes for a code project,+ * generated into the vault through the sentinel-region engine so+ * operator edits survive every re-scan.+ */++import { defaultConfigPath } from "../../../core/config.ts";+import { generateArchDocs } from "../../../core/brain/architect/generate.ts";+import { RegionError } from "../../../core/brain/regions.ts";+import { fail, ok, okJson, parse, resolveBrainVault } from "../helpers.ts";++export async function cmdBrainArchitect(argv: string[]): Promise<number> {+ const { flags, positional } = parse(argv, {+ vault: { type: "string" },+ json: { type: "boolean" },+ });+ const target = positional[0];+ if (!target) {+ return fail("usage: o2b brain architect <project-path> [--vault V] [--json]");+ }+ try {+ const vault = resolveBrainVault(flags["vault"] as string | undefined, defaultConfigPath());+ const res = generateArchDocs(vault, target);+ if (flags["json"] === true) {+ okJson({+ ok: true,+ repo_key: res.repoKey,+ dir: res.dir,+ overview_path: res.overviewPath,+ module_paths: res.modulePaths,+ created: res.created,+ updated: res.updated,+ unchanged: res.unchanged,+ });+ return 0;+ }+ ok(+ `architecture notes for ${res.repoKey}: ${res.created} created, ` ++ `${res.updated} updated, ${res.unchanged} unchanged`,+ );+ ok(`overview: ${res.overviewPath}`);+ return 0;+ } catch (err) {+ if (err instanceof RegionError) {+ return fail(+ `${err.message} - repair the sentinel markers (or delete the note to regenerate it)`,+ );+ }+ return fail(err instanceof Error ? err.message : String(err));+ }+}diff --git a/src/cli/brain/verbs/git.ts b/src/cli/brain/verbs/git.tsnew file mode 100644index 00000000..06edd205--- /dev/null+++ b/src/cli/brain/verbs/git.ts@@ -0,0 +1,244 @@+/**+ * `o2b brain git <ingest|status|find>` (Project History Suite,+ * t_c812752c): git history as Second Brain memory. `ingest` walks a+ * worktree read-only and lands records + digest in the vault, `status`+ * reports per-repo watermarks, `find` answers "why/when did this+ * change" from the store - no live git calls on the query path, so the+ * answers work even when the repo is gone.+ */++import { defaultConfigPath } from "../../../core/config.ts";+import { mineCommitDecisions } from "../../../core/brain/git/decisions.ts";+import { GitIngestError, ingestGitHistory } from "../../../core/brain/git/ingest.ts";+import { listGitCommits, listGitRepos, listGitTags } from "../../../core/brain/git/store.ts";+import type { GitCommitFilter, GitCommitRecord } from "../../../core/brain/git/store.ts";+import { fail, ok, okJson, parse, resolveBrainVault } from "../helpers.ts";++const USAGE = "usage: o2b brain git <ingest|status|find|mine> [args] [--vault V] [--json]";++const FIND_DEFAULT_LIMIT = 20;++export async function cmdBrainGit(argv: string[]): Promise<number> {+ const action = argv[0];+ if (action === "ingest") return cmdIngest(argv.slice(1));+ if (action === "status") return cmdStatus(argv.slice(1));+ if (action === "find") return cmdFind(argv.slice(1));+ if (action === "mine") return cmdMine(argv.slice(1));+ return fail(USAGE);+}++async function cmdMine(argv: string[]): Promise<number> {+ const { flags } = parse(argv, {+ vault: { type: "string" },+ json: { type: "boolean" },+ repo: { type: "string" },+ });+ try {+ const vault = resolveBrainVault(flags["vault"] as string | undefined, defaultConfigPath());+ const repoFilter = flags["repo"] as string | undefined;+ const repos = listGitRepos(vault).filter(+ (entry) => repoFilter === undefined || entry.key === repoFilter,+ );+ if (repoFilter !== undefined && repos.length === 0) {+ return fail(`no ingested git history for repo key: ${repoFilter}`);+ }+ const results = repos.map((entry) => mineCommitDecisions(vault, entry.key));+ if (flags["json"] === true) {+ okJson({+ ok: true,+ repos: results.map((res) => ({+ repo_key: res.repoKey,+ scanned: res.scanned,+ candidates: res.candidates,+ created: res.created,+ skipped_existing: res.skippedExisting,+ notes: res.notes,+ })),+ });+ return 0;+ }+ if (results.length === 0) {+ ok("no git history ingested yet (run: o2b brain git ingest <repo-path>)");+ return 0;+ }+ for (const res of results) {+ ok(+ `${res.repoKey}: ${res.scanned} commit(s) scanned, ${res.created} new ` ++ `candidate(s), ${res.skippedExisting} already curated`,+ );+ }+ return 0;+ } catch (err) {+ return fail(err instanceof Error ? err.message : String(err));+ }+}++async function cmdIngest(argv: string[]): Promise<number> {+ const { flags, positional } = parse(argv, {+ vault: { type: "string" },+ json: { type: "boolean" },+ "max-count": { type: "string" },+ });+ const target = positional[0];+ if (!target) return fail("brain git ingest requires a repository path");+ let maxCount: number | undefined;+ if (flags["max-count"] !== undefined) {+ maxCount = Number.parseInt(flags["max-count"] as string, 10);+ if (!Number.isInteger(maxCount) || maxCount < 1) {+ return fail("--max-count must be a positive integer");+ }+ }+ try {+ const vault = resolveBrainVault(flags["vault"] as string | undefined, defaultConfigPath());+ const res = ingestGitHistory(vault, target, maxCount !== undefined ? { maxCount } : {});+ if (flags["json"] === true) {+ okJson({+ ok: true,+ repo_key: res.repoKey,+ repo_path: res.repoPath,+ mode: res.mode,+ new_commits: res.newCommits,+ skipped_records: res.skippedCommits,+ new_tags: res.newTags,+ watermark: res.watermark,+ digest_path: res.digestPath,+ warning: res.warning,+ });+ return 0;+ }+ ok(+ `${res.mode} ingest of ${res.repoKey}: ${res.newCommits} new commit(s), ` ++ `${res.newTags} new tag(s)`,+ );+ if (res.warning !== null) ok(`warning: ${res.warning}`);+ ok(`digest: ${res.digestPath}`);+ return 0;+ } catch (err) {+ if (err instanceof GitIngestError) return fail(err.message);+ return fail(err instanceof Error ? err.message : String(err));+ }+}++async function cmdStatus(argv: string[]): Promise<number> {+ const { flags } = parse(argv, {+ vault: { type: "string" },+ json: { type: "boolean" },+ });+ try {+ const vault = resolveBrainVault(flags["vault"] as string | undefined, defaultConfigPath());+ const repos = listGitRepos(vault).map((entry) => ({+ key: entry.key,+ repo_path: entry.state?.repoPath ?? null,+ last_sha: entry.state?.lastSha ?? null,+ last_ingested_at: entry.state?.lastIngestedAt ?? null,+ state_error: entry.stateError,+ commits: listGitCommits(vault, entry.key).length,+ tags: listGitTags(vault, entry.key).length,+ }));+ if (flags["json"] === true) {+ okJson({ ok: true, repos });+ return 0;+ }+ if (repos.length === 0) {+ ok("no git history ingested yet (run: o2b brain git ingest <repo-path>)");+ return 0;+ }+ for (const repo of repos) {+ const mark = repo.last_sha === null ? "no watermark" : repo.last_sha.slice(0, 7);+ const err = repo.state_error === null ? "" : ` [state error: ${repo.state_error}]`;+ ok(`${repo.key}: ${repo.commits} commit(s), ${repo.tags} tag(s), watermark ${mark}${err}`);+ }+ return 0;+ } catch (err) {+ return fail(err instanceof Error ? err.message : String(err));+ }+}++async function cmdFind(argv: string[]): Promise<number> {+ const { flags, positional } = parse(argv, {+ vault: { type: "string" },+ json: { type: "boolean" },+ repo: { type: "string" },+ file: { type: "string" },+ author: { type: "string" },+ since: { type: "string" },+ until: { type: "string" },+ limit: { type: "string" },+ });+ const text = positional[0];+ if (+ text === undefined &&+ flags["file"] === undefined &&+ flags["author"] === undefined &&+ flags["since"] === undefined &&+ flags["until"] === undefined+ ) {+ return fail(+ "brain git find requires a query: free text and/or --file/--author/--since/--until",+ );+ }+ let limit = FIND_DEFAULT_LIMIT;+ if (flags["limit"] !== undefined) {+ limit = Number.parseInt(flags["limit"] as string, 10);+ if (!Number.isInteger(limit) || limit < 1) return fail("--limit must be a positive integer");+ }+ try {+ const vault = resolveBrainVault(flags["vault"] as string | undefined, defaultConfigPath());+ const filter: GitCommitFilter = {+ ...(text !== undefined ? { text } : {}),+ ...(flags["file"] !== undefined ? { file: flags["file"] as string } : {}),+ ...(flags["author"] !== undefined ? { author: flags["author"] as string } : {}),+ ...(flags["since"] !== undefined ? { since: flags["since"] as string } : {}),+ ...(flags["until"] !== undefined ? { until: flags["until"] as string } : {}),+ };+ const repoFilter = flags["repo"] as string | undefined;+ const repos = listGitRepos(vault).filter(+ (entry) => repoFilter === undefined || entry.key === repoFilter,+ );+ const matches: Array<{ repoKey: string; commit: GitCommitRecord }> = [];+ for (const entry of repos) {+ for (const commit of listGitCommits(vault, entry.key, filter)) {+ matches.push({ repoKey: entry.key, commit });+ }+ }+ matches.sort(+ (a, b) =>+ Date.parse(b.commit.committedAt) - Date.parse(a.commit.committedAt) ||+ a.commit.sha.localeCompare(b.commit.sha),+ );+ const limited = matches.slice(0, limit);+ if (flags["json"] === true) {+ okJson({+ ok: true,+ total: matches.length,+ commits: limited.map((m) => ({+ repo_key: m.repoKey,+ sha: m.commit.sha,+ committed_at: m.commit.committedAt,+ author: m.commit.authorName,+ subject: m.commit.subject,+ release: m.commit.release,+ files: m.commit.files,+ })),+ });+ return 0;+ }+ if (matches.length === 0) {+ ok("no matching commits");+ return 0;+ }+ for (const m of limited) {+ const release = m.commit.release === null ? "" : ` [${m.commit.release}]`;+ ok(+ `${m.commit.committedAt.slice(0, 10)} ${m.commit.sha.slice(0, 7)} ` ++ `(${m.repoKey}) ${m.commit.subject}${release}`,+ );+ }+ if (matches.length > limited.length) {+ ok(`... ${matches.length - limited.length} more (raise --limit)`);+ }+ return 0;+ } catch (err) {+ return fail(err instanceof Error ? err.message : String(err));+ }+}diff --git a/src/cli/brain/verbs/index.ts b/src/cli/brain/verbs/index.tsindex 0358671c..0a513769 100644--- a/src/cli/brain/verbs/index.ts+++ b/src/cli/brain/verbs/index.ts@@ -45,6 +45,8 @@ export { cmdBrainProfile } from "./profile.ts";export { cmdBrainSgrep } from "./sgrep.ts";export { cmdBrainContinuity } from "./continuity.ts";export { cmdBrainBench } from "./bench.ts";+export { cmdBrainGit } from "./git.ts";+export { cmdBrainArchitect } from "./architect.ts";export { cmdBrainTrigger } from "./trigger.ts";export { cmdBrainDeepSynthesis } from "./deep-synthesis.ts";export { cmdBrainIdeas } from "./ideas.ts";diff --git a/src/cli/command-manifest.ts b/src/cli/command-manifest.tsindex 553cd1bc..2e328eba 100644--- a/src/cli/command-manifest.ts+++ b/src/cli/command-manifest.ts@@ -159,6 +159,8 @@ export const CLI_COMMAND_MANIFEST: CliRootManifest = Object.freeze({command("sgrep", "Grep-shaped semantic Brain search (path:line: output)"),command("continuity", "Export continuity records as ATOF/ATIF trajectories"),command("bench", "Memory quality benchmark over a disposable fixture vault"),+ command("git", "Git history as project memory: ingest, status, find, mine"),+ command("architect", "Deterministic architecture notes for a code project"),command("trigger", "Grounded proactive trigger queue (scan/list/ack/dismiss/act/history)"),command("deep-synthesis", "Topic dossier: agreements, contradictions, stale claims, gaps"),command("ideas", "Ranked next-direction candidates from open loops"),diff --git a/src/core/brain/architect/generate.ts b/src/core/brain/architect/generate.tsnew file mode 100644index 00000000..fa001f14--- /dev/null+++ b/src/core/brain/architect/generate.ts@@ -0,0 +1,176 @@+/**+ * Architecture docs generator (Project History Suite, t_929da8a2).+ *+ * Renders scanProject facts into vault notes under+ * `Brain/projects/arch/<repo-key>/`: one overview plus one note per+ * detected module, all generated content inside sentinel regions.+ * Regeneration goes through mergeRegions, so operator prose outside+ * regions survives byte-for-byte, and an unchanged project regenerates+ * byte-identically (the scanner is deterministic and the renderer adds+ * no timestamps).+ *+ * Frontmatter is written ONCE at file creation and never rewritten -+ * it carries static identity (kind, repo key, path), while every fact+ * that can change between scans lives inside a region.+ *+ * Module REMOVAL keeps the old module note on disk (the operator may+ * have annotated it); the overview's module region reflects only the+ * current scan, so stale notes become unlinked rather than deleted.+ */++import { existsSync, mkdirSync, readFileSync } from "node:fs";+import { join } from "node:path";++import { atomicWriteFileSync } from "../../fs-atomic.ts";+import { repoKey as deriveRepoKey } from "../git/identity.ts";+import { buildRegionDocument, mergeRegions } from "../regions.ts";+import type { Region } from "../regions.ts";+import { scanProject } from "./scan.ts";+import type { ModuleFact, ProjectFacts } from "./scan.ts";++export interface GenerateArchDocsResult {+ readonly repoKey: string;+ readonly dir: string;+ readonly overviewPath: string;+ readonly modulePaths: ReadonlyArray<string>;+ readonly created: number;+ readonly updated: number;+ readonly unchanged: number;+}++function languagesLine(languages: Readonly<Record<string, number>>): string {+ const entries = Object.entries(languages).toSorted(+ (a, b) => b[1] - a[1] || a[0].localeCompare(b[0]),+ );+ if (entries.length === 0) return "none detected";+ return entries+ .slice(0, 8)+ .map(([ext, count]) => `${ext} (${count})`)+ .join(", ");+}++function overviewRegions(facts: ProjectFacts, key: string): ReadonlyArray<Region> {+ const summary = [+ `Project: ${facts.name}`,+ ...(facts.manifest?.version != null ? [`Version: ${facts.manifest.version}`] : []),+ ...(facts.manifest?.description != null ? [`Description: ${facts.manifest.description}`] : []),+ `Files: ${facts.totalFiles}`,+ `Languages: ${languagesLine(facts.languages)}`,+ ...(facts.testLayout !== null ? [`Test layout: ${facts.testLayout}/`] : []),+ ].join("\n");++ const modules = facts.modules+ .map(+ (module) =>+ `- [[Brain/projects/arch/${key}/modules/${module.name}|${module.name}]] ` ++ `(${module.path}, ${module.files} file(s))`,+ )+ .join("\n");++ const entryPoints =+ facts.entryPoints.length === 0+ ? "none detected"+ : facts.entryPoints.map((entry) => `- \`${entry}\``).join("\n");++ const dependencies =+ facts.manifest === null || facts.manifest.dependencies.length === 0+ ? "none declared"+ : facts.manifest.dependencies.map((dep) => `- ${dep}`).join("\n");++ return [+ { id: "summary", body: summary },+ { id: "modules", body: modules },+ { id: "entry-points", body: entryPoints },+ { id: "dependencies", body: dependencies },+ ];+}++function moduleRegions(module: ModuleFact): ReadonlyArray<Region> {+ const facts = [+ `Path: ${module.path}`,+ `Files: ${module.files}`,+ `Languages: ${languagesLine(module.languages)}`,+ ].join("\n");+ const files =+ module.topFiles.length === 0+ ? "empty module"+ : module.topFiles.map((file) => `- \`${file}\``).join("\n");+ return [+ { id: "facts", body: facts },+ { id: "files", body: files },+ ];+}++function frontmatter(kind: string, key: string, extra: ReadonlyArray<string>): string {+ return ["---", `kind: ${kind}`, `repo_key: ${key}`, ...extra, "---", ""].join("\n");+}++/**+ * Write or refresh one region-bearing note. Returns its disposition.+ * Throws RegionError (fail-closed) when the existing file's sentinels+ * are corrupted - the file is never partially rewritten.+ */+function upsertNote(+ path: string,+ head: string,+ regions: ReadonlyArray<Region>,+): "created" | "updated" | "unchanged" {+ if (!existsSync(path)) {+ atomicWriteFileSync(path, `${head}\n${buildRegionDocument(regions)}`);+ return "created";+ }+ const existing = readFileSync(path, "utf8");+ const merged = mergeRegions(existing, regions);+ if (merged === existing) return "unchanged";+ atomicWriteFileSync(path, merged);+ return "updated";+}++/** Generate or refresh architecture notes for one project tree. */+export function generateArchDocs(vault: string, projectRoot: string): GenerateArchDocsResult {+ const facts = scanProject(projectRoot);+ const key = deriveRepoKey(facts.root);+ const dir = join(vault, "Brain", "projects", "arch", key);+ mkdirSync(join(dir, "modules"), { recursive: true });++ let created = 0;+ let updated = 0;+ let unchanged = 0;+ const tally = (outcome: "created" | "updated" | "unchanged"): void => {+ if (outcome === "created") created += 1;+ else if (outcome === "updated") updated += 1;+ else unchanged += 1;+ };++ const overviewPath = join(dir, "overview.md");+ tally(+ upsertNote(+ overviewPath,+ frontmatter("arch-overview", key, [`repo_path: ${facts.root}`]),+ overviewRegions(facts, key),+ ),+ );++ const modulePaths: string[] = [];+ for (const module of facts.modules) {+ const path = join(dir, "modules", `${module.name}.md`);+ modulePaths.push(path);+ tally(+ upsertNote(+ path,+ frontmatter("arch-module", key, [`module: ${module.name}`]),+ moduleRegions(module),+ ),+ );+ }++ return Object.freeze({+ repoKey: key,+ dir,+ overviewPath,+ modulePaths: Object.freeze(modulePaths),+ created,+ updated,+ unchanged,+ });+}diff --git a/src/core/brain/architect/scan.ts b/src/core/brain/architect/scan.tsnew file mode 100644index 00000000..1d5da3dd--- /dev/null+++ b/src/core/brain/architect/scan.ts@@ -0,0 +1,229 @@+/**+ * Deterministic project scanner (Project History Suite, t_929da8a2).+ *+ * Stdlib-only structural facts: no network, no LLM, no per-language+ * parsing - directory layout, file extensions, and manifests are the+ * whole input, so the same tree always produces the same facts (the+ * generator's idempotency rests on this). Import-graph analysis is+ * explicitly out of scope (design doc).+ *+ * Module detection prefers `src/<dir>` children, then `packages/<dir>`,+ * and degrades to a single `root` module on flat layouts rather than+ * guessing.+ */++import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";+import { basename, extname, join, resolve } from "node:path";++const SKIP_DIRS = new Set([+ ".git",+ "node_modules",+ "dist",+ "build",+ "out",+ "coverage",+ "vendor",+ "target",+ ".venv",+ "venv",+ "__pycache__",+ ".next",+ ".cache",+]);++const ENTRY_CANDIDATES = [+ "src/index.ts",+ "src/index.js",+ "src/main.ts",+ "src/main.py",+ "index.ts",+ "index.js",+ "main.py",+ "main.go",+ "src/main.rs",+];++const TEST_LAYOUTS = ["tests", "test", "__tests__", "spec"];++export interface ModuleFact {+ readonly name: string;+ /** Project-relative POSIX path. */+ readonly path: string;+ readonly files: number;+ readonly languages: Readonly<Record<string, number>>;+ /** Module-relative file paths, sorted, capped for note rendering. */+ readonly topFiles: ReadonlyArray<string>;+}++export interface ManifestFact {+ readonly name: string | null;+ readonly version: string | null;+ readonly description: string | null;+ readonly dependencies: ReadonlyArray<string>;+}++export interface ProjectFacts {+ readonly root: string;+ readonly name: string;+ readonly manifest: ManifestFact | null;+ readonly entryPoints: ReadonlyArray<string>;+ readonly modules: ReadonlyArray<ModuleFact>;+ readonly testLayout: string | null;+ readonly totalFiles: number;+ readonly languages: Readonly<Record<string, number>>;+}++const TOP_FILES_CAP = 20;++interface WalkStats {+ files: number;+ languages: Record<string, number>;+ paths: string[];+}++function walk(dir: string, stats: WalkStats, prefix: string): void {+ let entries: string[];+ try {+ entries = readdirSync(dir);+ } catch {+ return;+ }+ for (const entry of entries.toSorted()) {+ if (SKIP_DIRS.has(entry)) continue;+ const abs = join(dir, entry);+ const rel = prefix === "" ? entry : `${prefix}/${entry}`;+ let stat;+ try {+ // lstat: a symlinked directory must not pull the walk outside the+ // project tree or into a cycle - symlinks are skipped entirely.+ stat = lstatSync(abs);+ } catch {+ continue;+ }+ if (stat.isSymbolicLink()) continue;+ if (stat.isDirectory()) {+ walk(abs, stats, rel);+ continue;+ }+ stats.files += 1;+ stats.paths.push(rel);+ const ext = extname(entry).toLowerCase();+ if (ext !== "") stats.languages[ext] = (stats.languages[ext] ?? 0) + 1;+ }+}++function statsFor(dir: string): WalkStats {+ const stats: WalkStats = { files: 0, languages: {}, paths: [] };+ walk(dir, stats, "");+ return stats;+}++function listDirs(dir: string): ReadonlyArray<string> {+ let entries: string[];+ try {+ entries = readdirSync(dir);+ } catch {+ return [];+ }+ return entries+ .toSorted()+ .filter((entry) => !SKIP_DIRS.has(entry))+ .filter((entry) => {+ try {+ const stat = lstatSync(join(dir, entry));+ return !stat.isSymbolicLink() && stat.isDirectory();+ } catch {+ return false;+ }+ });+}++function readManifest(root: string): ManifestFact | null {+ const path = join(root, "package.json");+ if (!existsSync(path)) return null;+ try {+ const raw = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;+ const deps =+ typeof raw["dependencies"] === "object" && raw["dependencies"] !== null+ ? Object.keys(raw["dependencies"] as Record<string, unknown>).toSorted()+ : [];+ return Object.freeze({+ name: typeof raw["name"] === "string" ? raw["name"] : null,+ version: typeof raw["version"] === "string" ? raw["version"] : null,+ description: typeof raw["description"] === "string" ? raw["description"] : null,+ dependencies: Object.freeze(deps),+ });+ } catch {+ return null;+ }+}++function detectModules(root: string): ReadonlyArray<ModuleFact> {+ for (const base of ["src", "packages"]) {+ const baseDir = join(root, base);+ if (!existsSync(baseDir)) continue;+ const dirs = listDirs(baseDir);+ if (dirs.length === 0) continue;+ return Object.freeze(+ dirs.map((name) => {+ const stats = statsFor(join(baseDir, name));+ return Object.freeze({+ name,+ path: `${base}/${name}`,+ files: stats.files,+ languages: Object.freeze(stats.languages),+ topFiles: Object.freeze(stats.paths.toSorted().slice(0, TOP_FILES_CAP)),+ });+ }),+ );+ }+ // Flat layout: the project root is the single module.+ const stats = statsFor(root);+ return Object.freeze([+ Object.freeze({+ name: "root",+ path: ".",+ files: stats.files,+ languages: stats.languages,+ topFiles: Object.freeze(stats.paths.toSorted().slice(0, TOP_FILES_CAP)),+ }),+ ]);+}++function detectEntryPoints(root: string, manifest: ManifestFact | null): ReadonlyArray<string> {+ const points = new Set<string>();+ if (manifest !== null) {+ const raw = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as Record<+ string,+ unknown+ >;+ if (typeof raw["main"] === "string") points.add(raw["main"]);+ if (typeof raw["bin"] === "object" && raw["bin"] !== null) {+ for (const value of Object.values(raw["bin"] as Record<string, unknown>)) {+ if (typeof value === "string") points.add(value.replace(/^\.\//, ""));+ }+ }+ }+ for (const candidate of ENTRY_CANDIDATES) {+ if (existsSync(join(root, candidate))) points.add(candidate);+ }+ return Object.freeze([...points].toSorted());+}++/** Scan one project tree into deterministic structural facts. */+export function scanProject(projectRoot: string): ProjectFacts {+ const root = resolve(projectRoot);+ const manifest = readManifest(root);+ const total = statsFor(root);+ const testLayout = TEST_LAYOUTS.find((layout) => existsSync(join(root, layout))) ?? null;+ return Object.freeze({+ root,+ name: manifest?.name ?? basename(root),+ manifest,+ entryPoints: detectEntryPoints(root, manifest),+ modules: detectModules(root),+ testLayout,+ totalFiles: total.files,+ languages: Object.freeze(total.languages),+ });+}diff --git a/src/core/brain/git/decisions.ts b/src/core/brain/git/decisions.tsnew file mode 100644index 00000000..c0b02e74--- /dev/null+++ b/src/core/brain/git/decisions.ts@@ -0,0 +1,155 @@+/**+ * Commit-decision miner (Project History Suite, t_93d299bb).+ *+ * Deterministic heuristics over INGESTED commit records (never live+ * git): conventional breaking markers, BREAKING CHANGE footers, a+ * word-boundary decision keyword set, and revert shape. 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 { existsSync, mkdirSync } from "node:fs";+import { join } from "node:path";++import { atomicWriteFileSync } from "../../fs-atomic.ts";+import { listGitCommits } from "./store.ts";+import type { GitCommitRecord } from "./store.ts";++/** Phrases that mark a commit message as decision-shaped. */+const DECISION_KEYWORDS = [+ "decide",+ "decided",+ "decision",+ "adopt",+ "adopted",+ "switch to",+ "migrate to",+ "instead of",+ "adr",+ "rationale",+] as const;++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> {+ 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");+ const haystack = `${subject}\n${body}`.toLowerCase();+ for (const keyword of DECISION_KEYWORDS) {+ // Word-boundary match: 'adopt' must not fire inside 'adoption'.+ const re = new RegExp(`\\b${keyword.replace(/ /g, "\\s+")}\\b`);+ if (re.test(haystack)) signals.push(`decision_keyword:${keyword}`);+ }+ 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 {+ 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 (existsSync(path)) {+ // Operator-curated drafts are sacrosanct: identity by sha means+ // this is the same decision, already on its review journey.+ skippedExisting += 1;+ continue;+ }+ mkdirSync(dir, { recursive: true });+ atomicWriteFileSync(path, renderCandidate(repoKey, commit, signals));+ created += 1;+ }+ return Object.freeze({+ repoKey,+ scanned: commits.length,+ candidates: notes.length,+ created,+ skippedExisting,+ notes: Object.freeze(notes),+ });+}diff --git a/src/core/brain/git/digest.ts b/src/core/brain/git/digest.tsnew file mode 100644index 00000000..d2db4235--- /dev/null+++ b/src/core/brain/git/digest.ts@@ -0,0 +1,116 @@+/**+ * Per-repo digest note renderer (Project History Suite, t_c812752c).+ *+ * The digest is the FTS-discoverable anchor for a repo's ingested+ * history: one regenerated markdown note per repo, rendered ONLY from+ * store records (never hand-edited - the JSONL store is the source of+ * truth, the note is a projection). Deterministic by construction: no+ * timestamps, no environment - same records, same bytes, so an idle+ * re-ingest produces a zero diff.+ *+ * Repo file paths render as plain text, never wikilinks - they are not+ * vault notes. Only vault-resident promoted artifacts (ADR candidates)+ * are wikilinked, and those links are derived from records too.+ */++import type { GitCommitRecord, GitTagRecord } from "./store.ts";++const RECENT_COMMITS = 30;+const HOT_FILES = 15;++export interface GitDigestInput {+ readonly repoKey: string;+ readonly repoPath: string;+ readonly commits: ReadonlyArray<GitCommitRecord>;+ readonly tags: ReadonlyArray<GitTagRecord>;+ /** Vault-relative paths of promoted ADR candidate notes, per commit sha. */+ readonly promoted?: ReadonlyMap<string, string>;+}++function shortSha(sha: string): string {+ return sha.slice(0, 7);+}++function day(iso: string): string {+ return iso.slice(0, 10);+}++/** Render the digest note body (frontmatter + sections). */+export function renderGitDigest(input: GitDigestInput): string {+ const { commits, tags } = input;+ const lines: string[] = [+ "---",+ "kind: git-digest",+ `repo_key: ${input.repoKey}`,+ `repo_path: ${input.repoPath}`,+ `commits: ${commits.length}`,+ `tags: ${tags.length}`,+ "---",+ "",+ `# Git history digest: ${input.repoKey}`,+ "",+ "Generated from the per-repo git record store. Do not edit - regenerated on every ingest.",+ "",+ ];++ // ββ Releases ββ+ lines.push("## Releases", "");+ if (tags.length === 0) {+ lines.push("No tags ingested.", "");+ } else {+ const countByRelease = new Map<string, number>();+ for (const commit of commits) {+ if (commit.release === null) continue;+ countByRelease.set(commit.release, (countByRelease.get(commit.release) ?? 0) + 1);+ }+ for (const tag of tags) {+ const date = tag.createdAt === null ? "unknown date" : day(tag.createdAt);+ const count = countByRelease.get(tag.name) ?? 0;+ lines.push(`- ${tag.name} (${date}, ${shortSha(tag.targetSha)}): ${count} commit(s)`);+ }+ lines.push("");+ }++ // ββ Recent commits ββ+ lines.push("## Recent commits", "");+ if (commits.length === 0) {+ lines.push("No commits ingested.", "");+ } else {+ for (const commit of commits.slice(-RECENT_COMMITS).toReversed()) {+ const release = commit.release === null ? "" : ` [${commit.release}]`;+ const promoted = input.promoted?.get(commit.sha);+ const link = promoted === undefined ? "" : ` -> [[${promoted}]]`;+ lines.push(+ `- ${day(commit.committedAt)} ${shortSha(commit.sha)} ${commit.subject}${release}${link}`,+ );+ }+ lines.push("");+ }++ // ββ Hot files ββ+ lines.push("## Hot files", "");+ const touches = new Map<string, { count: number; lastSubject: string }>();+ for (const commit of commits) {+ for (const file of commit.files) {+ const entry = touches.get(file);+ if (entry === undefined) touches.set(file, { count: 1, lastSubject: commit.subject });+ else {+ entry.count += 1;+ entry.lastSubject = commit.subject;+ }+ }+ }+ if (touches.size === 0) {+ lines.push("No file activity ingested.", "");+ } else {+ const hot = [...touches.entries()]+ .toSorted((a, b) => b[1].count - a[1].count || a[0].localeCompare(b[0]))+ .slice(0, HOT_FILES);+ for (const [file, info] of hot) {+ lines.push(`- \`${file}\` - ${info.count} touch(es); last: ${info.lastSubject}`);+ }+ lines.push("");+ }++ return lines.join("\n");+}diff --git a/src/core/brain/git/identity.ts b/src/core/brain/git/identity.tsnew file mode 100644index 00000000..4f3472b4--- /dev/null+++ b/src/core/brain/git/identity.ts@@ -0,0 +1,29 @@+/**+ * Repo identity for the git history store (Project History Suite,+ * t_c812752c).+ *+ * `repoKey` names the per-repo directory under `Brain/projects/git/` and+ * `Brain/projects/arch/`. The key is human-readable (sanitized basename)+ * yet collision-safe across same-named checkouts (8-hex digest of the+ * absolute path), and stable for a given checkout location - the same+ * properties `profiles.json` keys rely on, applied to project paths.+ */++import { createHash } from "node:crypto";+import { basename, resolve } from "node:path";++/** Lowercase, collapse anything outside [a-z0-9] to single hyphens. */+function sanitizeBasename(name: string): string {+ const slug = name+ .toLowerCase()+ .replace(/[^a-z0-9]+/g, "-")+ .replace(/^-+|-+$/g, "");+ return slug === "" ? "repo" : slug;+}++/** Deterministic per-checkout key: `<sanitized-basename>-<8-hex>`. */+export function repoKey(repoPath: string): string {+ const abs = resolve(repoPath);+ const digest = createHash("sha256").update(abs).digest("hex").slice(0, 8);+ return `${sanitizeBasename(basename(abs))}-${digest}`;+}diff --git a/src/core/brain/git/ingest.ts b/src/core/brain/git/ingest.tsnew file mode 100644index 00000000..33da3796--- /dev/null+++ b/src/core/brain/git/ingest.ts@@ -0,0 +1,217 @@+/**+ * Git history ingest orchestration (Project History Suite, t_c812752c).+ *+ * One run = read new commits + tags from a worktree, attribute carrying+ * releases via tag ranges, append records (store dedups), advance the+ * watermark, regenerate the digest note. Incremental by default: the+ * watermark sha bounds the walk to `<last>..HEAD`. Two degraded paths+ * both fall back to a FULL re-scan with a reported warning instead of+ * failing or duplicating:+ *+ * - watermark sha no longer resolves in the repo (force-push,+ * history rewrite) -> `mode: "rescan"`, store dedup absorbs overlap;+ * - state.json malformed / tampered -> same, with the probe error+ * surfaced as the warning.+ *+ * Release attribution uses the standard changelog rule: tags sorted by+ * creation date; `rev-list <prev>..<tag>` is exactly the commit set the+ * tag carried (one git call per tag, no per-commit ancestry walks).+ * Commits outside every range carry `release: null` - unreleased work.+ *+ * The ingest never modifies the repository: the reader is read-only by+ * construction, and the only writes land inside the vault.+ */++import { rmSync } from "node:fs";+import { join, resolve } from "node:path";++import { atomicWriteFileSync } from "../../fs-atomic.ts";+import { renderGitDigest } from "./digest.ts";+import { repoKey as deriveRepoKey } from "./identity.ts";+import { readCommits, readTags, revListRange, shaExists } from "./reader.ts";+import type { GitCommit, GitTag } from "./reader.ts";+import {+ appendGitRecords,+ gitStoreDir,+ listGitCommits,+ listGitTags,+ readGitState,+ writeGitState,+} from "./store.ts";+import type { GitCommitRecord, GitRecord, GitTagRecord } from "./store.ts";++export const DEFAULT_MAX_COUNT = 1000;++export type GitIngestMode = "initial" | "incremental" | "rescan";++export class GitIngestError extends Error {+ readonly code: "NOT_A_REPO";++ constructor(message: string) {+ super(message);+ this.name = "GitIngestError";+ this.code = "NOT_A_REPO";+ }+}++export interface IngestGitHistoryOptions {+ /** Bound the walk; git keeps the NEWEST commits. Default 1000. */+ readonly maxCount?: number;+ readonly now?: Date;+}++export interface IngestGitHistoryResult {+ readonly repoKey: string;+ readonly repoPath: string;+ readonly mode: GitIngestMode;+ readonly newCommits: number;+ readonly skippedCommits: number;+ readonly newTags: number;+ /** New watermark sha, or null when the repo has no commits. */+ readonly watermark: string | null;+ /** Absolute path of the regenerated digest note. */+ readonly digestPath: string;+ /** Degradation reason (re-scan cause), or null on a clean run. */+ readonly warning: string | null;+}++/**+ * Build sha -> carrying release name from chronologically ordered tag+ * ranges. First (oldest) containing tag wins, matching changelog+ * attribution.+ */+function attributeReleases(+ repoPath: string,+ tags: ReadonlyArray<GitTag>,+): ReadonlyMap<string, string> {+ const ordered = tags.toSorted((a, b) => {+ if (a.createdAt === null && b.createdAt === null) return a.name.localeCompare(b.name);+ if (a.createdAt === null) return 1;+ if (b.createdAt === null) return -1;+ return Date.parse(a.createdAt) - Date.parse(b.createdAt) || a.name.localeCompare(b.name);+ });+ const bySha = new Map<string, string>();+ let prev: string | null = null;+ for (const tag of ordered) {+ const range = revListRange(repoPath, prev, tag.targetSha);+ if (range !== null) {+ for (const sha of range) {+ if (!bySha.has(sha)) bySha.set(sha, tag.name);+ }+ }+ prev = tag.targetSha;+ }+ return bySha;+}++/** Ingest one repo's history into the vault store + digest note. */+export function ingestGitHistory(+ vault: string,+ repoPath: string,+ opts: IngestGitHistoryOptions = {},+): IngestGitHistoryResult {+ const repo = resolve(repoPath);+ const key = deriveRepoKey(repo);+ const maxCount = opts.maxCount ?? DEFAULT_MAX_COUNT;+ const now = (opts.now ?? new Date()).toISOString();++ // Watermark probe decides the walk mode; degraded probes re-scan.+ const probe = readGitState(vault, key);+ let mode: GitIngestMode;+ let sinceSha: string | undefined;+ let warning: string | null = null;+ if (probe.error !== null) {+ mode = "rescan";+ warning = `watermark unreadable, falling back to full re-scan: ${probe.error}`;+ } else if (probe.state === null) {+ mode = "initial";+ } else if (!shaExists(repo, probe.state.lastSha)) {+ mode = "rescan";+ warning =+ `watermark ${probe.state.lastSha.slice(0, 7)} no longer resolves ` ++ "(history rewritten?), falling back to full re-scan";+ } else {+ mode = "incremental";+ sinceSha = probe.state.lastSha;+ }++ const commits = readCommits(repo, {+ maxCount,+ ...(sinceSha !== undefined ? { sinceSha } : {}),+ });+ if (commits === null) {+ throw new GitIngestError(`not a git repository (or git unavailable): ${repo}`);+ }+ if (commits.length >= maxCount && mode !== "incremental") {+ // A bounded initial/rescan walk kept only the NEWEST maxCount+ // commits; older history is outside the watermark and will not+ // arrive on later incremental runs. Surface that instead of letting+ // the digest silently under-represent deep history.+ warning =+ (warning === null ? "" : `${warning}; `) ++ `walk bounded at ${maxCount} commit(s) - older history not ingested ` ++ "(re-run with a higher --max-count to backfill)";+ }+ const tags = readTags(repo) ?? [];++ // Attribute releases only when there is anything new to attribute.+ const releaseBySha =+ commits.length > 0 ? attributeReleases(repo, tags) : new Map<string, string>();++ const newTagRecords: GitTagRecord[] = tags.map((tag) => ({+ kind: "tag" as const,+ name: tag.name,+ targetSha: tag.targetSha,+ createdAt: tag.createdAt,+ }));+ const newCommitRecords: GitCommitRecord[] = commits.map((commit: GitCommit) => ({+ kind: "commit" as const,+ sha: commit.sha,+ authorName: commit.authorName,+ authorEmail: commit.authorEmail,+ committedAt: commit.committedAt,+ subject: commit.subject,+ body: commit.body,+ files: commit.files,+ release: releaseBySha.get(commit.sha) ?? null,+ }));++ const batch: GitRecord[] = [...newTagRecords, ...newCommitRecords];+ const appendResult = appendGitRecords(vault, key, batch);++ // Advance the watermark to the newest commit we saw this run. On an+ // INCREMENTAL run with no new commits the previous watermark still+ // holds; on a re-scan the prior watermark is the very sha that failed+ // to resolve, so writing it back would loop the repo through rescan+ // warnings forever - clear the state instead and let the next run+ // start clean as an initial walk.+ const newest =+ commits.at(-1)?.sha ?? (mode === "incremental" ? (probe.state?.lastSha ?? null) : null);+ if (newest !== null) {+ writeGitState(vault, key, { repoPath: repo, lastSha: newest, lastIngestedAt: now });+ } else if (mode === "rescan") {+ rmSync(join(gitStoreDir(vault, key), "state.json"), { force: true });+ }++ // Regenerate the digest projection from the FULL store.+ const digestPath = join(gitStoreDir(vault, key), "digest.md");+ const digest = renderGitDigest({+ repoKey: key,+ repoPath: repo,+ commits: listGitCommits(vault, key),+ tags: listGitTags(vault, key),+ });+ atomicWriteFileSync(digestPath, digest);++ return Object.freeze({+ repoKey: key,+ repoPath: repo,+ mode,+ newCommits: appendResult.appendedCommits,+ skippedCommits: appendResult.skipped,+ newTags: appendResult.appendedTags,+ watermark: newest,+ digestPath,+ warning,+ });+}diff --git a/src/core/brain/git/reader.ts b/src/core/brain/git/reader.tsnew file mode 100644index 00000000..e7c8e610--- /dev/null+++ b/src/core/brain/git/reader.ts@@ -0,0 +1,210 @@+/**+ * Sanitized read-only git reader (Project History Suite, t_c812752c).+ *+ * Every entry point shells out to the `git` binary with a FIXED argv via+ * `execFileSync` - no shell, no user-controlled flags, `--` separators+ * where paths could be ambiguous - following the proven+ * `src/core/discipline/activity-git.ts` pattern. The reader never+ * modifies the repository or its index.+ *+ * Caller-supplied SHAs are validated against the full-40-hex grammar+ * BEFORE they reach argv (`isFullSha`); anything else throws, so an+ * injection-shaped watermark can never become a git argument.+ *+ * Fail-soft contract: a missing repo, a non-repo directory, or a git+ * failure returns `null` (callers report "no history available"); an+ * EMPTY repository returns `[]` - "git works, zero commits" is a real+ * state the ingest watermark logic must distinguish from breakage.+ *+ * Commit records are parsed from `git log` with control-character field+ * separators: %x01 starts a record, %x00 separates fields, %x02 ends the+ * body. Control bytes cannot survive into commit metadata via normal git+ * usage, and a hand-crafted collision degrades to a skipped record, not+ * a corrupted neighbour.+ */++import { existsSync, statSync } from "node:fs";+import { execFileSync } from "node:child_process";+import { join, resolve } from "node:path";++export interface GitCommit {+ readonly sha: string;+ readonly authorName: string;+ readonly authorEmail: string;+ /** Author date, ISO-8601 strict. */+ readonly committedAt: string;+ readonly subject: string;+ readonly body: string;+ /** Repo-relative touched paths; empty for merge commits. */+ readonly files: ReadonlyArray<string>;+}++export interface GitTag {+ readonly name: string;+ /** Peeled commit sha (annotated tags resolve through the tag object). */+ readonly targetSha: string;+ /** Tag creation date, ISO-8601 strict; null when git reports none. */+ readonly createdAt: string | null;+}++export interface ReadCommitsOptions {+ /** Only commits AFTER this sha (exclusive), i.e. `<sha>..HEAD`. */+ readonly sinceSha?: string;+ /** Bound the walk; git keeps the NEWEST `maxCount` commits. */+ readonly maxCount?: number;+}++// Output-side separators. argv strings cannot carry raw NUL bytes+// (Node rejects them), so the FORMAT strings below spell these as+// git-side hex escapes (`%x00` in pretty formats, `%00` in+// for-each-ref formats) and git emits the raw bytes in its OUTPUT,+// where they are safe to split on.+const RECORD_START = "\x01";+const FIELD_SEP = "\x00";+const BODY_END = "\x02";++/** Exactly 40 lowercase hex characters - a full git object sha. */+export function isFullSha(value: unknown): value is string {+ return typeof value === "string" && /^[0-9a-f]{40}$/.test(value);+}++function isGitRepo(repoPath: string): boolean {+ try {+ if (!statSync(repoPath).isDirectory()) return false;+ } catch {+ return false;+ }+ return existsSync(join(resolve(repoPath), ".git"));+}++function runGit(repoPath: string, args: ReadonlyArray<string>): string | null {+ try {+ return execFileSync("git", ["-C", resolve(repoPath), ...args], {+ encoding: "utf8",+ maxBuffer: 64 * 1024 * 1024,+ });+ } catch {+ // Fail-soft: a broken repo / missing git binary reads as "no+ // history", mirroring activity-git.ts. Callers that need to+ // distinguish breakage from emptiness check isGitRepo first.+ return null;+ }+}++/**+ * Read commits oldest-first. `null` when the directory is not a git+ * repo or git fails; `[]` for a repo with no commits (yet).+ */+export function readCommits(+ repoPath: string,+ opts: ReadCommitsOptions,+): ReadonlyArray<GitCommit> | null {+ if (!isGitRepo(repoPath)) return null;+ if (opts.sinceSha !== undefined && !isFullSha(opts.sinceSha)) {+ throw new Error(`sinceSha must be a full 40-hex git sha, got: ${String(opts.sinceSha)}`);+ }+ const args = [+ "log",+ "--name-only",+ "--pretty=format:%x01%H%x00%an%x00%ae%x00%aI%x00%s%x00%b%x02",+ ];+ if (opts.maxCount !== undefined) {+ args.push(`--max-count=${Math.max(1, Math.floor(opts.maxCount))}`);+ }+ if (opts.sinceSha !== undefined) args.push(`${opts.sinceSha}..HEAD`);+ const raw = runGit(repoPath, args);+ if (raw === null) {+ // `git log` exits non-zero on a repo with zero commits; report that+ // as empty history rather than breakage when the repo itself is fine.+ return emptyRepoOrNull(repoPath);+ }+ const commits: GitCommit[] = [];+ for (const record of raw.split(RECORD_START)) {+ if (record.trim() === "") continue;+ const bodyEnd = record.indexOf(BODY_END);+ if (bodyEnd === -1) continue; // collision-degraded record: skip+ const fields = record.slice(0, bodyEnd).split(FIELD_SEP);+ if (fields.length !== 6) continue;+ const [sha, authorName, authorEmail, committedAt, subject, body] = fields;+ if (!isFullSha(sha)) continue;+ const files = record+ .slice(bodyEnd + 1)+ .split("\n")+ .map((line) => line.trim())+ .filter((line) => line !== "");+ commits.push(+ Object.freeze({+ sha,+ authorName: authorName ?? "",+ authorEmail: authorEmail ?? "",+ committedAt: committedAt ?? "",+ subject: subject ?? "",+ body: (body ?? "").trim(),+ files: Object.freeze(files),+ }),+ );+ }+ return Object.freeze(commits.toReversed());+}++function emptyRepoOrNull(repoPath: string): ReadonlyArray<GitCommit> | null {+ const probe = runGit(repoPath, ["rev-parse", "--git-dir"]);+ return probe === null ? null : Object.freeze([]);+}++/**+ * List tags with peeled commit shas. `null` on non-repos / git failure,+ * `[]` on tagless repos.+ */+export function readTags(repoPath: string): ReadonlyArray<GitTag> | null {+ if (!isGitRepo(repoPath)) return null;+ const format =+ "%(refname:short)%00" ++ "%(if)%(*objectname)%(then)%(*objectname)%(else)%(objectname)%(end)%00" ++ "%(creatordate:iso-strict)";+ const raw = runGit(repoPath, ["tag", "--list", `--format=${format}`]);+ if (raw === null) return null;+ const tags: GitTag[] = [];+ for (const line of raw.split("\n")) {+ if (line.trim() === "") continue;+ const [name, targetSha, createdAt] = line.split(FIELD_SEP);+ if (name === undefined || name === "" || !isFullSha(targetSha)) continue;+ tags.push(+ Object.freeze({+ name,+ targetSha,+ createdAt: createdAt !== undefined && createdAt !== "" ? createdAt : null,+ }),+ );+ }+ return Object.freeze(tags);+}++/**+ * Shas reachable from `to` but not from `from`, oldest-first - the+ * standard changelog range. `from === null` means "everything up to+ * `to`" (the first tag's range).+ */+export function revListRange(+ repoPath: string,+ from: string | null,+ to: string,+): ReadonlyArray<string> | null {+ if (!isGitRepo(repoPath)) return null;+ if (from !== null && !isFullSha(from)) {+ throw new Error(`revListRange 'from' must be a full 40-hex git sha, got: ${String(from)}`);+ }+ if (!isFullSha(to)) {+ throw new Error(`revListRange 'to' must be a full 40-hex git sha, got: ${String(to)}`);+ }+ const raw = runGit(repoPath, ["rev-list", "--reverse", from === null ? to : `${from}..${to}`]);+ if (raw === null) return null;+ return Object.freeze(raw.split("\n").filter((line) => isFullSha(line.trim())));+}++/** True when the (validated) sha resolves to a commit in this repo. */+export function shaExists(repoPath: string, sha: string): boolean {+ if (!isFullSha(sha)) return false;+ if (!isGitRepo(repoPath)) return false;+ return runGit(repoPath, ["cat-file", "-e", `${sha}^{commit}`]) !== null;+}diff --git a/src/core/brain/git/store.ts b/src/core/brain/git/store.tsnew file mode 100644index 00000000..e7a37a10--- /dev/null+++ b/src/core/brain/git/store.ts@@ -0,0 +1,348 @@+/**+ * Per-repo git record store (Project History Suite, t_c812752c).+ *+ * Canonical source of truth for ingested history. Each linked repo owns+ * `Brain/projects/git/<repo-key>/` with two files:+ *+ * - `commits.jsonl` - append-only mixed-kind records (`commit` | `tag`),+ * snake_case on disk like the continuity shards, deduplicated by+ * commit sha / tag name on append. Typed edges (touched files,+ * author, carrying release) are STRUCTURED FIELDS here; wikilinks in+ * rendered notes are always derived from these records, never+ * hand-maintained (design decision: contain dual-representation drift).+ * - `state.json` - the ingest watermark. The sha is validated against+ * the full-40-hex grammar on BOTH write and read, so a tampered+ * watermark surfaces as a probe error long before it could reach a+ * git argv (the reader re-validates anyway - defense in depth).+ *+ * The store lives INSIDE the vault (unlike the device-local+ * `projects.json` registry): project memory syncs with the Brain.+ * Tolerant reads: malformed JSONL lines are skipped, a malformed state+ * file reads as an error probe - mirroring `Brain/log/` conventions.+ */++import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";+import { appendFileSync } from "node:fs";+import { join } from "node:path";++import { atomicWriteFileSync } from "../../fs-atomic.ts";+import { isFullSha } from "./reader.ts";++export interface GitCommitRecord {+ readonly kind: "commit";+ readonly sha: string;+ readonly authorName: string;+ readonly authorEmail: string;+ readonly committedAt: string;+ readonly subject: string;+ readonly body: string;+ readonly files: ReadonlyArray<string>;+ /** Carrying release (tag name) assigned by range attribution, or null. */+ readonly release: string | null;+}++export interface GitTagRecord {+ readonly kind: "tag";+ readonly name: string;+ readonly targetSha: string;+ readonly createdAt: string | null;+}++export type GitRecord = GitCommitRecord | GitTagRecord;++export interface GitState {+ readonly repoPath: string;+ readonly lastSha: string;+ readonly lastIngestedAt: string;+}++export interface GitStateProbe {+ readonly state: GitState | null;+ readonly error: string | null;+}++export interface GitCommitFilter {+ /** Exact repo-relative touched path. */+ readonly file?: string;+ /** Case-insensitive substring over author name + email. */+ readonly author?: string;+ /** Case-insensitive substring over subject + body. */+ readonly text?: string;+ /** ISO bound on committedAt (inclusive). */+ readonly since?: string;+ readonly until?: string;+ /** Keep the NEWEST n matches (order stays oldest-first). */+ readonly limit?: number;+}++export interface AppendGitRecordsResult {+ readonly appended: number;+ readonly appendedCommits: number;+ readonly appendedTags: number;+ readonly skipped: number;+}++/** Per-repo store directory inside the vault. */+export function gitStoreDir(vault: string, repoKey: string): string {+ return join(vault, "Brain", "projects", "git", repoKey);+}++function commitsPath(vault: string, repoKey: string): string {+ return join(gitStoreDir(vault, repoKey), "commits.jsonl");+}++function statePath(vault: string, repoKey: string): string {+ return join(gitStoreDir(vault, repoKey), "state.json");+}++function serializeRecord(record: GitRecord): string {+ if (record.kind === "commit") {+ return JSON.stringify({+ kind: "commit",+ sha: record.sha,+ author_name: record.authorName,+ author_email: record.authorEmail,+ committed_at: record.committedAt,+ subject: record.subject,+ body: record.body,+ files: record.files,+ release: record.release,+ });+ }+ return JSON.stringify({+ kind: "tag",+ name: record.name,+ target_sha: record.targetSha,+ created_at: record.createdAt,+ });+}++function parseRecord(line: string): GitRecord | null {+ let raw: unknown;+ try {+ raw = JSON.parse(line);+ } catch {+ return null;+ }+ if (typeof raw !== "object" || raw === null) return null;+ const rec = raw as Record<string, unknown>;+ if (rec["kind"] === "commit") {+ if (!isFullSha(rec["sha"])) return null;+ return Object.freeze({+ kind: "commit" as const,+ sha: rec["sha"],+ authorName: typeof rec["author_name"] === "string" ? rec["author_name"] : "",+ authorEmail: typeof rec["author_email"] === "string" ? rec["author_email"] : "",+ committedAt: typeof rec["committed_at"] === "string" ? rec["committed_at"] : "",+ subject: typeof rec["subject"] === "string" ? rec["subject"] : "",+ body: typeof rec["body"] === "string" ? rec["body"] : "",+ files: Object.freeze(+ Array.isArray(rec["files"])+ ? rec["files"].filter((f): f is string => typeof f === "string")+ : [],+ ),+ release: typeof rec["release"] === "string" ? rec["release"] : null,+ });+ }+ if (rec["kind"] === "tag") {+ if (typeof rec["name"] !== "string" || rec["name"] === "") return null;+ if (!isFullSha(rec["target_sha"])) return null;+ return Object.freeze({+ kind: "tag" as const,+ name: rec["name"],+ targetSha: rec["target_sha"],+ createdAt: typeof rec["created_at"] === "string" ? rec["created_at"] : null,+ });+ }+ return null;+}++function readRecords(vault: string, repoKey: string): ReadonlyArray<GitRecord> {+ const path = commitsPath(vault, repoKey);+ if (!existsSync(path)) return [];+ const records: GitRecord[] = [];+ for (const line of readFileSync(path, "utf8").split("\n")) {+ if (line.trim() === "") continue;+ const record = parseRecord(line);+ if (record !== null) records.push(record);+ }+ return records;+}++/**+ * Append records, deduplicating commits by sha and tags by+ * (name, target) against everything already on disk AND earlier+ * entries of the same batch.+ */+export function appendGitRecords(+ vault: string,+ repoKey: string,+ records: ReadonlyArray<GitRecord>,+): AppendGitRecordsResult {+ const existing = readRecords(vault, repoKey);+ const seenShas = new Set<string>();+ // Tag identity is (name, target): a RETARGETED tag (same name, new+ // commit after a force-move) appends a fresh record instead of being+ // silently dropped; listGitTags surfaces the latest record per name.+ const seenTags = new Set<string>();+ for (const record of existing) {+ if (record.kind === "commit") seenShas.add(record.sha);+ else seenTags.add(`${record.name}\x00${record.targetSha}`);+ }+ const lines: string[] = [];+ let skipped = 0;+ let appendedCommits = 0;+ let appendedTags = 0;+ for (const record of records) {+ const key = record.kind === "commit" ? record.sha : `${record.name}\x00${record.targetSha}`;+ const seen = record.kind === "commit" ? seenShas : seenTags;+ if (seen.has(key)) {+ skipped += 1;+ continue;+ }+ seen.add(key);+ if (record.kind === "commit") appendedCommits += 1;+ else appendedTags += 1;+ lines.push(serializeRecord(record) + "\n");+ }+ if (lines.length > 0) {+ mkdirSync(gitStoreDir(vault, repoKey), { recursive: true });+ appendFileSync(commitsPath(vault, repoKey), lines.join(""));+ }+ return { appended: lines.length, appendedCommits, appendedTags, skipped };+}++/** Commits oldest-first (file order), optionally filtered. */+export function listGitCommits(+ vault: string,+ repoKey: string,+ filter: GitCommitFilter = {},+): ReadonlyArray<GitCommitRecord> {+ let commits = readRecords(vault, repoKey).filter(+ (record): record is GitCommitRecord => record.kind === "commit",+ );+ if (filter.file !== undefined) {+ const file = filter.file;+ commits = commits.filter((c) => c.files.includes(file));+ }+ if (filter.author !== undefined) {+ const needle = filter.author.toLowerCase();+ commits = commits.filter((c) =>+ `${c.authorName} ${c.authorEmail}`.toLowerCase().includes(needle),+ );+ }+ if (filter.text !== undefined) {+ const needle = filter.text.toLowerCase();+ commits = commits.filter((c) => `${c.subject}\n${c.body}`.toLowerCase().includes(needle));+ }+ if (filter.since !== undefined) {+ const since = Date.parse(filter.since);+ if (Number.isNaN(since)) {+ throw new Error(`invalid 'since' datetime: ${filter.since}`);+ }+ commits = commits.filter((c) => Date.parse(c.committedAt) >= since);+ }+ if (filter.until !== undefined) {+ const until = Date.parse(filter.until);+ if (Number.isNaN(until)) {+ throw new Error(`invalid 'until' datetime: ${filter.until}`);+ }+ commits = commits.filter((c) => Date.parse(c.committedAt) <= until);+ }+ if (filter.limit !== undefined && filter.limit >= 0) {+ commits = commits.slice(Math.max(0, commits.length - Math.floor(filter.limit)));+ }+ return Object.freeze(commits);+}++/**+ * Tags in first-seen order, latest record per name - a retargeted tag+ * (appended as a fresh (name, target) record) replaces its predecessor+ * in this view.+ */+export function listGitTags(vault: string, repoKey: string): ReadonlyArray<GitTagRecord> {+ const byName = new Map<string, GitTagRecord>();+ for (const record of readRecords(vault, repoKey)) {+ if (record.kind === "tag") byName.set(record.name, record);+ }+ return Object.freeze([...byName.values()]);+}++/** Watermark write; the sha grammar is enforced before anything lands. */+export function writeGitState(vault: string, repoKey: string, state: GitState): void {+ if (!isFullSha(state.lastSha)) {+ throw new Error(`git state lastSha must be a full 40-hex git sha, got: ${state.lastSha}`);+ }+ mkdirSync(gitStoreDir(vault, repoKey), { recursive: true });+ atomicWriteFileSync(+ statePath(vault, repoKey),+ JSON.stringify(+ {+ repo_path: state.repoPath,+ last_sha: state.lastSha,+ last_ingested_at: state.lastIngestedAt,+ },+ null,+ 2,+ ) + "\n",+ );+}++/**+ * Watermark probe. Missing file: `{ state: null, error: null }` (fresh+ * repo). Malformed JSON or an invalid sha: `{ state: null, error }` so+ * ingest can fall back to a full re-scan and REPORT why.+ */+export function readGitState(vault: string, repoKey: string): GitStateProbe {+ const path = statePath(vault, repoKey);+ if (!existsSync(path)) return Object.freeze({ state: null, error: null });+ let raw: unknown;+ try {+ raw = JSON.parse(readFileSync(path, "utf8"));+ } catch (exc) {+ return Object.freeze({+ state: null,+ error: `git state is not valid JSON: ${(exc as Error).message}`,+ });+ }+ const rec = (raw ?? {}) as Record<string, unknown>;+ const lastSha = rec["last_sha"];+ if (!isFullSha(lastSha)) {+ return Object.freeze({+ state: null,+ error: `git state last_sha must be a full 40-hex git sha, got: ${String(lastSha)}`,+ });+ }+ return Object.freeze({+ state: Object.freeze({+ repoPath: typeof rec["repo_path"] === "string" ? rec["repo_path"] : "",+ lastSha,+ lastIngestedAt: typeof rec["last_ingested_at"] === "string" ? rec["last_ingested_at"] : "",+ }),+ error: null,+ });+}++export interface GitRepoEntry {+ readonly key: string;+ readonly state: GitState | null;+ readonly stateError: string | null;+}++/** Every per-repo store under Brain/projects/git/, sorted by key. */+export function listGitRepos(vault: string): ReadonlyArray<GitRepoEntry> {+ const root = join(vault, "Brain", "projects", "git");+ if (!existsSync(root)) return [];+ const entries: GitRepoEntry[] = [];+ for (const name of readdirSync(root).toSorted()) {+ const dir = join(root, name);+ try {+ if (!statSync(dir).isDirectory()) continue;+ } catch {+ continue;+ }+ const probe = readGitState(vault, name);+ entries.push(Object.freeze({ key: name, state: probe.state, stateError: probe.error }));+ }+ return Object.freeze(entries);+}diff --git a/src/core/brain/recall-telemetry.ts b/src/core/brain/recall-telemetry.tsindex e0a66bd5..09b8813d 100644--- a/src/core/brain/recall-telemetry.ts+++ b/src/core/brain/recall-telemetry.ts@@ -1,7 +1,7 @@import { appendContinuityRecord, listContinuityRecords } from "./continuity/store.ts";import type { ContinuityRecord } from "./continuity/types.ts";-export type RecallTelemetryMode = "search" | "context_pack" | "pre_compress";+export type RecallTelemetryMode = "search" | "context_pack" | "pre_compress" | "query";export type RecallTelemetryStatus = "ok" | "empty" | "error" | "timeout";export interface RecallTelemetryArtifactInput {@@ -135,7 +135,9 @@ export function summarizeRecallTelemetry(}export function isRecallTelemetryMode(value: unknown): value is RecallTelemetryMode {- return value === "search" || value === "context_pack" || value === "pre_compress";+ return (+ value === "search" || value === "context_pack" || value === "pre_compress" || value === "query"+ );}export function isRecallTelemetryStatus(value: unknown): value is RecallTelemetryStatus {diff --git a/src/core/brain/regions.ts b/src/core/brain/regions.tsnew file mode 100644index 00000000..693638d4--- /dev/null+++ b/src/core/brain/regions.ts@@ -0,0 +1,149 @@+/**+ * Sentinel-region merge engine (Project History Suite, t_929da8a2).+ *+ * Generated note content lives between paired HTML-comment sentinels:+ *+ * <!-- o2b:begin <region-id> -->+ * ...generated body...+ * <!-- o2b:end <region-id> -->+ *+ * Everything OUTSIDE regions is operator-owned and survives every+ * regeneration byte-for-byte; explicit paired ids make fail-closed+ * validation unambiguous, so no second marker kind ("@user") is needed+ * (variants.md, orchestrator refinement 2).+ *+ * Fail-closed contract: an unbalanced, duplicated, nested, or+ * mismatched sentinel raises {@link RegionError} naming the offending+ * region BEFORE any write - a corrupted file is never partially+ * rewritten. Consumers (arch-docs generator) catch this and tell the+ * operator which file to repair.+ *+ * Merge semantics:+ * - region in document AND update -> body replaced;+ * - region only in update -> appended at document end;+ * - region only in document -> left untouched (stable ids let+ * generators keep emitting the same set; an id they stop emitting+ * stays as the operator last saw it rather than silently vanishing).+ */++// Trailing \r tolerated so CRLF files keep their regions visible -+// otherwise mergeRegions would append duplicates instead of updating+// in place.+const BEGIN_RE = /^<!-- o2b:begin ([A-Za-z0-9_-]+) -->\r?$/;+const END_RE = /^<!-- o2b:end ([A-Za-z0-9_-]+) -->\r?$/;++export class RegionError extends Error {+ readonly code: "UNBALANCED" | "DUPLICATE" | "NESTED" | "MISMATCHED";++ constructor(code: RegionError["code"], message: string) {+ super(message);+ this.name = "RegionError";+ this.code = code;+ }+}++export interface Region {+ readonly id: string;+ /** Body WITHOUT the sentinel lines and without trailing newline. */+ readonly body: string;+}++/**+ * Extract `id -> body` for every region. Throws {@link RegionError} on+ * any sentinel corruption (fail-closed).+ */+export function parseRegions(text: string): ReadonlyMap<string, string> {+ const regions = new Map<string, string>();+ let open: string | null = null;+ let bodyLines: string[] = [];+ for (const line of text.split("\n")) {+ const begin = BEGIN_RE.exec(line);+ if (begin !== null) {+ const id = begin[1]!;+ if (open !== null) {+ throw new RegionError(+ "NESTED",+ `nested sentinel: region '${id}' opens inside still-open region '${open}'`,+ );+ }+ if (regions.has(id)) {+ throw new RegionError("DUPLICATE", `duplicate region id '${id}'`);+ }+ open = id;+ bodyLines = [];+ continue;+ }+ const end = END_RE.exec(line);+ if (end !== null) {+ const id = end[1]!;+ if (open === null) {+ throw new RegionError("UNBALANCED", `region '${id}' ends without a matching begin`);+ }+ if (open !== id) {+ throw new RegionError(+ "MISMATCHED",+ `region '${open}' is closed by mismatched end sentinel '${id}'`,+ );+ }+ regions.set(id, bodyLines.join("\n"));+ open = null;+ continue;+ }+ if (open !== null) bodyLines.push(line);+ }+ if (open !== null) {+ throw new RegionError("UNBALANCED", `region '${open}' is never closed`);+ }+ return regions;+}++function renderRegion(region: Region): string {+ return `<!-- o2b:begin ${region.id} -->\n${region.body}\n<!-- o2b:end ${region.id} -->`;+}++/** Render a fresh all-generated document from regions. */+export function buildRegionDocument(regions: ReadonlyArray<Region>): string {+ return `${regions.map(renderRegion).join("\n\n")}\n`;+}++/**+ * Replace generated region bodies inside `existing`, preserving every+ * byte outside the regions. Unknown-to-the-update regions stay; regions+ * new to the update are appended. Validates `existing` first and throws+ * {@link RegionError} instead of touching a corrupted document.+ */+export function mergeRegions(existing: string, update: ReadonlyArray<Region>): string {+ parseRegions(existing); // fail-closed validation before any rewrite+ const byId = new Map(update.map((region) => [region.id, region]));+ const out: string[] = [];+ let open: string | null = null;+ let replaced: Region | undefined;+ for (const line of existing.split("\n")) {+ const begin = BEGIN_RE.exec(line);+ if (begin !== null) {+ open = begin[1]!;+ replaced = byId.get(open);+ byId.delete(open);+ out.push(line);+ if (replaced !== undefined) out.push(replaced.body);+ continue;+ }+ const end = END_RE.exec(line);+ if (end !== null) {+ open = null;+ replaced = undefined;+ out.push(line);+ continue;+ }+ // Inside a replaced region the old body is dropped; outside (or in+ // an untouched region) every byte passes through.+ if (open !== null && replaced !== undefined) continue;+ out.push(line);+ }+ let merged = out.join("\n");+ if (byId.size > 0) {+ const appended = [...byId.values()].map(renderRegion).join("\n\n");+ merged = `${merged.replace(/\n+$/, "\n")}\n${appended}\n`;+ }+ return merged;+}diff --git a/src/mcp/brain-tools.ts b/src/mcp/brain-tools.tsindex fa0840d7..2bc6f741 100644--- a/src/mcp/brain-tools.ts+++ b/src/mcp/brain-tools.ts@@ -200,10 +200,14 @@ import {coerceStr,coerceStrList,coerceBool,+ coerceBoolOptional,coerceIsoDate,coerceFormat,coerceInt,+ coerceStringOptional,} from "./coerce.ts";+import { emitGatedTelemetry } from "../core/brain/continuity/emit.ts";+import { emitRecallTelemetry } from "../core/brain/recall-telemetry.ts";// ----- brain_feedback ------------------------------------------------------@@ -828,40 +832,77 @@ async function toolBrainQuery();}- if (preference !== null) {- try {- const res = queryByPreference(ctx.vault, preference);+ // Recall telemetry (t_405b8053): per-call opt-in mirroring+ // brain_search. The payload carries the query KIND only - never the+ // supplied preference id / topic slug / timestamp value.+ const telemetry = coerceBoolOptional(args, "telemetry") ?? false;+ const telemetryHost = coerceStringOptional(args, "telemetry_host", 200) ?? "mcp";+ const telemetrySessionId = coerceStringOptional(args, "session_id", 512);+ const telemetryTurnId = coerceStringOptional(args, "turn_id", 512);+ const queryKind = preference !== null ? "preference" : topic !== null ? "topic" : "since";+ const startedAtMs = Date.now();+ const emitQueryTelemetry = (status: "ok" | "empty" | "error", resultCount: number): void => {+ // Lazy emit kernel (t_5d7aa7c5): gate off = thunk never runs; a+ // throwing continuity write can never fail the query itself.+ emitGatedTelemetry(telemetry || undefined, () =>+ emitRecallTelemetry(ctx.vault, {+ host: telemetryHost,+ ...(telemetrySessionId !== undefined ? { sessionId: telemetrySessionId } : {}),+ ...(telemetryTurnId !== undefined ? { turnId: telemetryTurnId } : {}),+ mode: "query",+ status,+ durationMs: Date.now() - startedAtMs,+ resultCount,+ gaps:+ status === "error" ? ["query_error"] : status === "empty" ? ["no_matching_context"] : [],+ metadata: { query_kind: queryKind },+ }),+ );+ };++ try {+ if (preference !== null) {+ try {+ const res = queryByPreference(ctx.vault, preference);+ emitQueryTelemetry(res.evidence.length > 0 ? "ok" : "empty", res.evidence.length);+ return {+ mode: "preference",+ preference: serializePreference(res.preference),+ evidence: res.evidence.map(serializeLogEntry),+ };+ } catch (exc) {+ if (exc instanceof BrainNotFoundError) {+ throw new Error(exc.message, { cause: exc });+ }+ throw exc;+ }+ }++ if (topic !== null) {+ const res = queryByTopic(ctx.vault, topic);+ const resultCount = res.signals.length + res.all_log_events.length;+ emitQueryTelemetry(resultCount > 0 ? "ok" : "empty", resultCount);return {- mode: "preference",- preference: serializePreference(res.preference),- evidence: res.evidence.map(serializeLogEntry),+ mode: "topic",+ topic,+ signals: res.signals.map(serializeSignal),+ preference: res.preference ? serializePreference(res.preference) : null,+ all_log_events: res.all_log_events.map(serializeLogEntry),};- } catch (exc) {- if (exc instanceof BrainNotFoundError) {- throw new Error(exc.message, { cause: exc });- }- throw exc;}- }- if (topic !== null) {- const res = queryByTopic(ctx.vault, topic);+ // since+ const res = queryByLogSince(ctx.vault, since!);+ emitQueryTelemetry(res.length > 0 ? "ok" : "empty", res.length);return {- mode: "topic",- topic,- signals: res.signals.map(serializeSignal),- preference: res.preference ? serializePreference(res.preference) : null,- all_log_events: res.all_log_events.map(serializeLogEntry),+ mode: "since",+ since: since!.toISOString(),+ events: res.map(serializeLogEntry),};+ } catch (exc) {+ emitQueryTelemetry("error", 0);+ throw exc;}-- // since- const res = queryByLogSince(ctx.vault, since!);- return {- mode: "since",- since: since!.toISOString(),- events: res.map(serializeLogEntry),- };}// ----- brain_agent_query / brain_agent_diff --------------------------------@@ -3273,6 +3314,14 @@ export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([description:"Reserved for forward-compat; the structured response is the same regardless.",},+ telemetry: {+ type: "boolean",+ description:+ "Opt-in recall telemetry: emit one continuity record (mode 'query', kind-only payload) for this call.",+ },+ telemetry_host: { type: "string", maxLength: 200 },+ session_id: { type: "string", maxLength: 512 },+ turn_id: { type: "string", maxLength: 512 },},additionalProperties: false,},diff --git a/tests/cli/brain-architect.test.ts b/tests/cli/brain-architect.test.tsnew file mode 100644index 00000000..c04651db--- /dev/null+++ b/tests/cli/brain-architect.test.ts@@ -0,0 +1,65 @@+/**+ * `o2b brain architect` CLI surface (Project History Suite, t_929da8a2).+ */++import { afterEach, beforeEach, expect, test } from "bun:test";+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { runCli } from "../helpers/run-cli.ts";++let tmp: string;+let project: string;+let vault: string;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-cli-architect-"));+ project = join(tmp, "demo-app");+ mkdirSync(join(project, "src", "core"), { recursive: true });+ writeFileSync(join(project, "package.json"), JSON.stringify({ name: "demo-app" }));+ writeFileSync(join(project, "src", "core", "engine.ts"), "// x\n");+ vault = join(tmp, "vault");+ mkdirSync(join(vault, "Brain"), { recursive: true });+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++test("architect generates and refreshes vault notes idempotently", async () => {+ const first = await runCli(["brain", "architect", project, "--vault", vault, "--json"]);+ expect(first.returncode).toBe(0);+ const created = JSON.parse(first.stdout) as {+ ok: boolean;+ overview_path: string;+ created: number;+ unchanged: number;+ };+ expect(created.ok).toBe(true);+ expect(created.created).toBeGreaterThanOrEqual(2);+ expect(readFileSync(created.overview_path, "utf8")).toContain("demo-app");++ const second = await runCli(["brain", "architect", project, "--vault", vault, "--json"]);+ const rerun = JSON.parse(second.stdout) as { created: number; unchanged: number };+ expect(rerun.created).toBe(0);+ expect(rerun.unchanged).toBeGreaterThanOrEqual(2);+});++test("corrupted sentinels fail closed with a repair hint", async () => {+ const first = await runCli(["brain", "architect", project, "--vault", vault, "--json"]);+ const overviewPath = (JSON.parse(first.stdout) as { overview_path: string }).overview_path;+ writeFileSync(+ overviewPath,+ readFileSync(overviewPath, "utf8").replace("<!-- o2b:end summary -->", ""),+ );+ const res = await runCli(["brain", "architect", project, "--vault", vault]);+ expect(res.returncode).toBe(1);+ expect(res.stderr).toContain("repair the sentinel markers");+});++test("missing path argument prints usage", async () => {+ const res = await runCli(["brain", "architect", "--vault", vault]);+ expect(res.returncode).toBe(1);+ expect(res.stderr).toContain("usage: o2b brain architect");+});diff --git a/tests/cli/brain-git.test.ts b/tests/cli/brain-git.test.tsnew file mode 100644index 00000000..85bd1671--- /dev/null+++ b/tests/cli/brain-git.test.ts@@ -0,0 +1,184 @@+/**+ * `o2b brain git <ingest|status|find|mine>` CLI surface+ * (Project History Suite, t_c812752c + t_93d299bb).+ */++import { afterEach, beforeEach, expect, test } from "bun:test";+import { execFileSync } from "node:child_process";+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { runCli } from "../helpers/run-cli.ts";++let tmp: string;+let repo: string;+let vault: string;++function git(...args: string[]): string {+ return execFileSync(+ "git",+ [+ "-C",+ repo,+ "-c",+ "user.name=Fixture Author",+ "-c",+ "[email protected]",+ "-c",+ "commit.gpgsign=false",+ "-c",+ "tag.gpgsign=false",+ ...args,+ ],+ { encoding: "utf8", env: { ...process.env, GIT_CONFIG_GLOBAL: "/dev/null" } },+ ).trim();+}++function commitFile(relPath: string, content: string, message: string): string {+ const abs = join(repo, relPath);+ mkdirSync(join(abs, ".."), { recursive: true });+ writeFileSync(abs, content);+ git("add", "--", relPath);+ git("commit", "-q", "-m", message);+ return git("rev-parse", "HEAD");+}++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-cli-git-"));+ repo = join(tmp, "fixture-repo");+ mkdirSync(repo, { recursive: true });+ git("init", "-q", "-b", "main");+ vault = join(tmp, "vault");+ mkdirSync(join(vault, "Brain"), { recursive: true });+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++test("ingest + status + find round-trip over a real repo", async () => {+ commitFile("src/a.ts", "1", "feat: add alpha module");+ git("tag", "v1.0.0");+ commitFile("src/b.ts", "2", "fix: beta hotfix");++ const ingest = await runCli(["brain", "git", "ingest", repo, "--vault", vault, "--json"]);+ expect(ingest.returncode).toBe(0);+ const ingested = JSON.parse(ingest.stdout) as {+ ok: boolean;+ repo_key: string;+ mode: string;+ new_commits: number;+ new_tags: number;+ digest_path: string;+ };+ expect(ingested.ok).toBe(true);+ expect(ingested.mode).toBe("initial");+ expect(ingested.new_commits).toBe(2);+ expect(ingested.new_tags).toBe(1);+ expect(existsSync(ingested.digest_path)).toBe(true);++ const status = await runCli(["brain", "git", "status", "--vault", vault, "--json"]);+ expect(status.returncode).toBe(0);+ const parsed = JSON.parse(status.stdout) as {+ repos: Array<{ key: string; commits: number; tags: number; last_sha: string | null }>;+ };+ expect(parsed.repos).toHaveLength(1);+ expect(parsed.repos[0]!.key).toBe(ingested.repo_key);+ expect(parsed.repos[0]!.commits).toBe(2);++ const find = await runCli(["brain", "git", "find", "alpha", "--vault", vault, "--json"]);+ expect(find.returncode).toBe(0);+ const found = JSON.parse(find.stdout) as {+ total: number;+ commits: Array<{ sha: string; subject: string; release: string | null; repo_key: string }>;+ };+ expect(found.total).toBe(1);+ expect(found.commits[0]!.subject).toBe("feat: add alpha module");+ expect(found.commits[0]!.release).toBe("v1.0.0");++ const byFile = await runCli([+ "brain",+ "git",+ "find",+ "--file",+ "src/b.ts",+ "--vault",+ vault,+ "--json",+ ]);+ const fileHits = JSON.parse(byFile.stdout) as {+ total: number;+ commits: Array<{ subject: string }>;+ };+ expect(fileHits.total).toBe(1);+ expect(fileHits.commits[0]!.subject).toBe("fix: beta hotfix");+});++test("find requires some filter and reports empty results cleanly", async () => {+ const bare = await runCli(["brain", "git", "find", "--vault", vault, "--json"]);+ expect(bare.returncode).toBe(1);+ expect(bare.stderr).toContain("requires a query");++ commitFile("a.txt", "1", "one");+ await runCli(["brain", "git", "ingest", repo, "--vault", vault]);+ const miss = await runCli([+ "brain",+ "git",+ "find",+ "nothing-matches",+ "--vault",+ vault,+ "--json",+ ]);+ expect(miss.returncode).toBe(0);+ expect((JSON.parse(miss.stdout) as { total: number }).total).toBe(0);+});++test("ingest of a non-repo fails with exit 1 and a clear message", async () => {+ const plain = join(tmp, "plain");+ mkdirSync(plain);+ const res = await runCli(["brain", "git", "ingest", plain, "--vault", vault]);+ expect(res.returncode).toBe(1);+ expect(res.stderr).toContain("not a git repository");+});++test("mine surfaces decision-shaped commits as ADR candidates, skip-existing on re-run", async () => {+ commitFile("src/a.ts", "1", "feat!: drop legacy index format");+ commitFile("src/b.ts", "2", "fix: typo");+ await runCli(["brain", "git", "ingest", repo, "--vault", vault]);++ const first = await runCli(["brain", "git", "mine", "--vault", vault, "--json"]);+ expect(first.returncode).toBe(0);+ const mined = JSON.parse(first.stdout) as {+ repos: Array<{ scanned: number; created: number; notes: string[] }>;+ };+ expect(mined.repos[0]!.scanned).toBe(2);+ expect(mined.repos[0]!.created).toBe(1);+ expect(existsSync(mined.repos[0]!.notes[0]!)).toBe(true);++ const second = await runCli(["brain", "git", "mine", "--vault", vault, "--json"]);+ const rerun = JSON.parse(second.stdout) as {+ repos: Array<{ created: number; skipped_existing: number }>;+ };+ expect(rerun.repos[0]!.created).toBe(0);+ expect(rerun.repos[0]!.skipped_existing).toBe(1);++ const missing = await runCli([+ "brain",+ "git",+ "mine",+ "--repo",+ "nope-00000000",+ "--vault",+ vault,+ ]);+ expect(missing.returncode).toBe(1);+ expect(missing.stderr).toContain("no ingested git history");+});++test("usage line on unknown subcommand", async () => {+ const res = await runCli(["brain", "git", "frobnicate", "--vault", vault]);+ expect(res.returncode).toBe(1);+ expect(res.stderr).toContain("usage: o2b brain git");+});diff --git a/tests/core/brain/architect.test.ts b/tests/core/brain/architect.test.tsnew file mode 100644index 00000000..bde3015a--- /dev/null+++ b/tests/core/brain/architect.test.ts@@ -0,0 +1,124 @@+/**+ * Deterministic architecture docs generator+ * (Project History Suite, t_929da8a2).+ */++import { afterEach, beforeEach, expect, test } from "bun:test";+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { generateArchDocs } from "../../../src/core/brain/architect/generate.ts";+import { scanProject } from "../../../src/core/brain/architect/scan.ts";++let tmp: string;+let project: string;+let vault: string;++function seed(relPath: string, content = "// x\n"): void {+ const abs = join(project, relPath);+ mkdirSync(join(abs, ".."), { recursive: true });+ writeFileSync(abs, content);+}++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-architect-"));+ project = join(tmp, "demo-app");+ mkdirSync(project, { recursive: true });+ vault = join(tmp, "vault");+ mkdirSync(join(vault, "Brain"), { recursive: true });++ writeFileSync(+ join(project, "package.json"),+ JSON.stringify({+ name: "demo-app",+ version: "1.2.3",+ description: "Fixture project",+ main: "src/index.ts",+ dependencies: { "left-pad": "^1.0.0" },+ }),+ );+ seed("src/index.ts");+ seed("src/core/engine.ts");+ seed("src/core/util.ts");+ seed("src/cli/main.ts");+ seed("tests/engine.test.ts");+ seed("README.md", "# Demo App\n");+ // Noise that must be ignored:+ seed("node_modules/dep/index.js");+ seed(".git/HEAD", "ref: refs/heads/main\n");+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++test("scanProject produces deterministic structural facts", () => {+ const facts = scanProject(project);+ expect(facts.name).toBe("demo-app");+ expect(facts.manifest!.version).toBe("1.2.3");+ expect(facts.manifest!.dependencies).toEqual(["left-pad"]);+ expect(facts.modules.map((m) => m.name)).toEqual(["cli", "core"]);+ expect(facts.modules.find((m) => m.name === "core")!.files).toBe(2);+ expect(facts.entryPoints).toContain("src/index.ts");+ expect(facts.testLayout).toBe("tests");+ // node_modules and .git are invisible.+ expect(facts.languages[".js"]).toBeUndefined();+ expect(facts.languages[".ts"]).toBe(5);+ // Determinism: scanning twice gives deep-equal results.+ expect(scanProject(project)).toEqual(facts);+});++test("scanProject skips symlinks instead of following them", () => {+ // A symlink cycle inside the tree must not hang or overflow the scan,+ // and symlinked content outside the module must not be counted.+ symlinkSync(project, join(project, "src", "core", "loop"), "dir");+ const facts = scanProject(project);+ expect(facts.modules.find((m) => m.name === "core")!.files).toBe(2);+});++test("scanProject degrades to a single root module on flat layouts", () => {+ const flat = join(tmp, "flat-proj");+ mkdirSync(flat, { recursive: true });+ writeFileSync(join(flat, "main.py"), "print('x')\n");+ const facts = scanProject(flat);+ expect(facts.modules.map((m) => m.name)).toEqual(["root"]);+ expect(facts.manifest).toBeNull();+ expect(facts.languages[".py"]).toBe(1);+});++test("first generation creates overview + per-module notes under Brain/projects/arch", () => {+ const res = generateArchDocs(vault, project);+ expect(res.created).toBeGreaterThanOrEqual(3); // overview + 2 modules+ expect(res.updated).toBe(0);+ const overview = readFileSync(res.overviewPath, "utf8");+ expect(overview).toContain("kind: arch-overview");+ expect(overview).toContain("<!-- o2b:begin summary -->");+ expect(overview).toContain("demo-app");+ expect(overview).toContain("core");+ const moduleNote = readFileSync(res.modulePaths.find((p) => p.endsWith("core.md"))!, "utf8");+ expect(moduleNote).toContain("kind: arch-module");+ expect(moduleNote).toContain("engine.ts");+});++test("regeneration preserves operator edits outside regions and refreshes facts inside", () => {+ const first = generateArchDocs(vault, project);+ const operatorNote = "\nOperator: core owns the scheduling invariants.\n";+ writeFileSync(first.overviewPath, readFileSync(first.overviewPath, "utf8") + operatorNote);++ seed("src/api/server.ts"); // new module appears+ const second = generateArchDocs(vault, project);+ const overview = readFileSync(second.overviewPath, "utf8");+ expect(overview).toContain("Operator: core owns the scheduling invariants.");+ expect(overview).toContain("api");+ expect(second.updated).toBeGreaterThanOrEqual(1);+});++test("unchanged project regenerates byte-identically", () => {+ const first = generateArchDocs(vault, project);+ const before = readFileSync(first.overviewPath, "utf8");+ const second = generateArchDocs(vault, project);+ expect(readFileSync(second.overviewPath, "utf8")).toBe(before);+ expect(second.created).toBe(0);+ expect(second.unchanged).toBeGreaterThanOrEqual(3);+});diff --git a/tests/core/brain/git/decisions.test.ts b/tests/core/brain/git/decisions.test.tsnew file mode 100644index 00000000..c5a9d909--- /dev/null+++ b/tests/core/brain/git/decisions.test.ts@@ -0,0 +1,125 @@+/**+ * Commit-decision miner: decision-shaped commits become ADR candidate+ * notes (Project History Suite, t_93d299bb).+ */++import { afterEach, beforeEach, expect, test } from "bun:test";+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import {+ detectDecisionSignals,+ mineCommitDecisions,+} from "../../../../src/core/brain/git/decisions.ts";+import { appendGitRecords } from "../../../../src/core/brain/git/store.ts";+import type { GitCommitRecord } from "../../../../src/core/brain/git/store.ts";++let tmp: string;+let vault: string;++const KEY = "fixture-repo-abcd1234";++function commit(sha: string, subject: string, body = ""): GitCommitRecord {+ return {+ kind: "commit",+ sha,+ authorName: "Fixture Author",+ authorEmail: "[email protected]",+ committedAt: "2026-06-01T10:00:00+00:00",+ subject,+ body,+ files: ["src/a.ts"],+ release: null,+ };+}++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-git-decisions-"));+ vault = join(tmp, "vault");+ mkdirSync(join(vault, "Brain"), { recursive: true });+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++// ββ signal detection ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ++test("detectDecisionSignals matches deterministic decision shapes", () => {+ expect(detectDecisionSignals("feat!: drop legacy index format", "")).toContain(+ "conventional_breaking",+ );+ expect(detectDecisionSignals("feat(core)!: switch storage", "")).toContain(+ "conventional_breaking",+ );+ expect(detectDecisionSignals("feat: new api", "BREAKING CHANGE: payload renamed")).toContain(+ "breaking_change_footer",+ );+ expect(detectDecisionSignals("chore: migrate to bun test runner", "")).toContain(+ "decision_keyword:migrate to",+ );+ expect(+ detectDecisionSignals("docs: explain choice", "We decided to adopt JSONL instead of SQLite."),+ ).toEqual(expect.arrayContaining(["decision_keyword:decided", "decision_keyword:adopt"]));+ expect(detectDecisionSignals('Revert "feat: bad idea"', "")).toContain("revert");+ // Plain work is NOT decision-shaped.+ expect(detectDecisionSignals("fix: off-by-one in pager", "small fix")).toEqual([]);+ // Substrings inside words do not match (no false 'adopt' in 'adoption-rate.ts').+ expect(detectDecisionSignals("chore: update adoption-rate metrics", "")).toEqual([]);+});++// ββ mining ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ++test("mineCommitDecisions writes candidates for decision commits only, with provenance", () => {+ appendGitRecords(vault, KEY, [+ commit("a".repeat(40), "feat!: drop legacy index format", "BREAKING CHANGE: rebuild needed"),+ commit("b".repeat(40), "fix: typo"),+ commit("c".repeat(40), "chore: migrate to bun test runner"),+ ]);+ const res = mineCommitDecisions(vault, KEY);+ expect(res.scanned).toBe(3);+ expect(res.created).toBe(2);+ expect(res.skippedExisting).toBe(0);+ expect(res.notes).toHaveLength(2);++ const first = res.notes.find((n) => n.includes("aaaaaaa"))!;+ expect(existsSync(first)).toBe(true);+ const content = readFileSync(first, "utf8");+ expect(content).toContain("kind: adr-candidate");+ expect(content).toContain("status: candidate");+ expect(content).toContain(`sha: ${"a".repeat(40)}`);+ expect(content).toContain("conventional_breaking");+ expect(content).toContain("feat!: drop legacy index format");+ expect(content).toContain(`repo_key: ${KEY}`);+});++test("re-runs never duplicate and never clobber operator-edited candidates", () => {+ appendGitRecords(vault, KEY, [commit("a".repeat(40), "feat!: drop legacy index format")]);+ const first = mineCommitDecisions(vault, KEY);+ expect(first.created).toBe(1);+ const note = first.notes[0]!;+ writeFileSync(note, readFileSync(note, "utf8") + "\nOperator: accepted, see ADR-7.\n");++ const second = mineCommitDecisions(vault, KEY);+ expect(second.created).toBe(0);+ expect(second.skippedExisting).toBe(1);+ expect(readFileSync(note, "utf8")).toContain("Operator: accepted, see ADR-7.");+});++test("empty history is a clean no-op", () => {+ const res = mineCommitDecisions(vault, KEY);+ expect(res.scanned).toBe(0);+ expect(res.created).toBe(0);+ expect(res.notes).toEqual([]);+});++test("candidate paths are stable, 12-hex-prefixed, and slugged from the subject", () => {+ appendGitRecords(vault, KEY, [+ commit("d".repeat(40), "feat!: Switch to Postgres (was: SQLite)!!"),+ ]);+ const res = mineCommitDecisions(vault, KEY);+ expect(res.notes[0]).toContain(join("Brain", "decisions", "candidates"));+ // 12 hex chars of sha (git's large-repo abbreviation length), then slug.+ expect(res.notes[0]).toMatch(/adr-d{12}-feat-switch-to-postgres[a-z-]*\.md$/);+});diff --git a/tests/core/brain/git/ingest.test.ts b/tests/core/brain/git/ingest.test.tsnew file mode 100644index 00000000..7d1c13db--- /dev/null+++ b/tests/core/brain/git/ingest.test.ts@@ -0,0 +1,195 @@+/**+ * Git history ingest orchestration: full + incremental runs, release+ * attribution, watermark advance, digest rendering+ * (Project History Suite, t_c812752c).+ */++import { afterEach, beforeEach, expect, test } from "bun:test";+import { execFileSync } from "node:child_process";+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { repoKey } from "../../../../src/core/brain/git/identity.ts";+import { GitIngestError, ingestGitHistory } from "../../../../src/core/brain/git/ingest.ts";+import {+ gitStoreDir,+ listGitCommits,+ listGitTags,+ readGitState,+ writeGitState,+} from "../../../../src/core/brain/git/store.ts";++let tmp: string;+let repo: string;+let vault: string;++function git(...args: string[]): string {+ return execFileSync(+ "git",+ [+ "-C",+ repo,+ "-c",+ "user.name=Fixture Author",+ "-c",+ "[email protected]",+ "-c",+ "commit.gpgsign=false",+ "-c",+ "tag.gpgsign=false",+ ...args,+ ],+ { encoding: "utf8", env: { ...process.env, GIT_CONFIG_GLOBAL: "/dev/null" } },+ ).trim();+}++function commitFile(relPath: string, content: string, message: string): string {+ const abs = join(repo, relPath);+ mkdirSync(join(abs, ".."), { recursive: true });+ writeFileSync(abs, content);+ git("add", "--", relPath);+ git("commit", "-q", "-m", message);+ return git("rev-parse", "HEAD");+}++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-git-ingest-"));+ repo = join(tmp, "fixture-repo");+ mkdirSync(repo, { recursive: true });+ git("init", "-q", "-b", "main");+ vault = join(tmp, "vault");+ mkdirSync(join(vault, "Brain"), { recursive: true });+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++test("initial ingest stores commits, tags, release edges, watermark, and digest", () => {+ commitFile("src/a.ts", "1", "feat: first");+ const second = commitFile("src/b.ts", "2", "fix: second");+ git("tag", "v1.0.0");+ const third = commitFile("src/a.ts", "3", "feat: post-release work");++ const res = ingestGitHistory(vault, repo);+ expect(res.mode).toBe("initial");+ expect(res.newCommits).toBe(3);+ expect(res.newTags).toBe(1);+ expect(res.warning).toBeNull();+ expect(res.repoKey).toBe(repoKey(repo));++ const key = res.repoKey;+ const commits = listGitCommits(vault, key);+ expect(commits).toHaveLength(3);+ // Release attribution: commits up to the tag carry v1.0.0, later ones null.+ expect(commits[0]!.release).toBe("v1.0.0");+ expect(commits[1]!.release).toBe("v1.0.0");+ expect(commits[2]!.release).toBeNull();+ expect(commits[1]!.sha).toBe(second);+ expect(listGitTags(vault, key)).toHaveLength(1);++ const state = readGitState(vault, key);+ expect(state.state!.lastSha).toBe(third);+ expect(state.state!.repoPath).toBe(repo);++ const digest = readFileSync(join(gitStoreDir(vault, key), "digest.md"), "utf8");+ expect(digest).toContain("kind: git-digest");+ expect(digest).toContain("v1.0.0");+ expect(digest).toContain("feat: post-release work");+ expect(digest).toContain("src/a.ts");+});++test("incremental ingest appends only new commits and advances the watermark", () => {+ commitFile("a.txt", "1", "one");+ const first = ingestGitHistory(vault, repo);+ expect(first.newCommits).toBe(1);++ const second = commitFile("b.txt", "2", "two");+ git("tag", "v0.2.0");+ const res = ingestGitHistory(vault, repo);+ expect(res.mode).toBe("incremental");+ expect(res.newCommits).toBe(1);+ expect(res.newTags).toBe(1);+ expect(readGitState(vault, res.repoKey).state!.lastSha).toBe(second);+ expect(listGitCommits(vault, res.repoKey)).toHaveLength(2);++ // No-change re-run: zero new records, watermark untouched, no duplicates.+ const idle = ingestGitHistory(vault, repo);+ expect(idle.mode).toBe("incremental");+ expect(idle.newCommits).toBe(0);+ expect(listGitCommits(vault, idle.repoKey)).toHaveLength(2);+});++test("a watermark that no longer resolves triggers a clean full re-scan", () => {+ commitFile("a.txt", "1", "one");+ ingestGitHistory(vault, repo);+ // Simulate force-push: watermark sha not in object store anymore.+ writeGitState(vault, repoKey(repo), {+ repoPath: repo,+ lastSha: "0".repeat(40),+ lastIngestedAt: "2026-06-04T00:00:00Z",+ });+ commitFile("b.txt", "2", "two");+ const res = ingestGitHistory(vault, repo);+ expect(res.mode).toBe("rescan");+ expect(res.warning).toMatch(/watermark/i);+ // Dedup keeps the store duplicate-free across the re-scan.+ expect(listGitCommits(vault, res.repoKey)).toHaveLength(2);+});++test("a malformed watermark file triggers a re-scan with the probe error surfaced", () => {+ commitFile("a.txt", "1", "one");+ ingestGitHistory(vault, repo);+ writeFileSync(join(gitStoreDir(vault, repoKey(repo)), "state.json"), "{broken");+ const res = ingestGitHistory(vault, repo);+ expect(res.mode).toBe("rescan");+ expect(res.warning).toMatch(/not valid JSON/);+ expect(listGitCommits(vault, res.repoKey)).toHaveLength(1);+});++test("a zero-commit re-scan clears the stale watermark instead of looping", () => {+ // Watermark points at a sha that never existed; the repo has no+ // commits at all (orphaned after a force-push). Writing the stale sha+ // back would re-trigger rescan warnings on every later run.+ writeGitState(vault, repoKey(repo), {+ repoPath: repo,+ lastSha: "0".repeat(40),+ lastIngestedAt: "2026-06-04T00:00:00Z",+ });+ const res = ingestGitHistory(vault, repo);+ expect(res.mode).toBe("rescan");+ expect(res.watermark).toBeNull();+ // State cleared: the next run starts clean as an initial walk.+ expect(readGitState(vault, repoKey(repo))).toEqual({ state: null, error: null });+ expect(ingestGitHistory(vault, repo).mode).toBe("initial");+});++test("maxCount bounds the initial walk and surfaces the truncation", () => {+ for (let i = 0; i < 5; i += 1) commitFile(`f${i}.txt`, String(i), `commit ${i}`);+ const res = ingestGitHistory(vault, repo, { maxCount: 2 });+ expect(res.newCommits).toBe(2);+ const commits = listGitCommits(vault, res.repoKey);+ expect(commits.map((c) => c.subject)).toEqual(["commit 3", "commit 4"]);+ // A bounded initial walk must SAY it skipped older history.+ expect(res.warning).toMatch(/older history not ingested/);+});++test("non-repo paths raise a domain error; empty repos ingest cleanly", () => {+ const plain = join(tmp, "plain");+ mkdirSync(plain);+ expect(() => ingestGitHistory(vault, plain)).toThrow(GitIngestError);+ const res = ingestGitHistory(vault, repo); // zero commits yet+ expect(res.newCommits).toBe(0);+ expect(res.watermark).toBeNull();+});++test("digest is deterministic: same store, same bytes", () => {+ commitFile("src/a.ts", "1", "feat: first");+ git("tag", "v1.0.0");+ ingestGitHistory(vault, repo);+ const path = join(gitStoreDir(vault, repoKey(repo)), "digest.md");+ const first = readFileSync(path, "utf8");+ ingestGitHistory(vault, repo);+ expect(readFileSync(path, "utf8")).toBe(first);+});diff --git a/tests/core/brain/git/reader.test.ts b/tests/core/brain/git/reader.test.tsnew file mode 100644index 00000000..522f9a84--- /dev/null+++ b/tests/core/brain/git/reader.test.ts@@ -0,0 +1,207 @@+/**+ * Git kernel: repo identity + sanitized read-only git reader+ * (Project History Suite, t_c812752c).+ */++import { afterEach, beforeEach, expect, test } from "bun:test";+import { execFileSync } from "node:child_process";+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { repoKey } from "../../../../src/core/brain/git/identity.ts";+import {+ isFullSha,+ readCommits,+ readTags,+ revListRange,+ shaExists,+} from "../../../../src/core/brain/git/reader.ts";++let tmp: string;+let repo: string;++function git(...args: string[]): string {+ return execFileSync(+ "git",+ [+ "-C",+ repo,+ "-c",+ "user.name=Fixture Author",+ "-c",+ "[email protected]",+ "-c",+ "commit.gpgsign=false",+ "-c",+ "tag.gpgsign=false",+ ...args,+ ],+ { encoding: "utf8", env: { ...process.env, GIT_CONFIG_GLOBAL: "/dev/null" } },+ ).trim();+}++function commitFile(relPath: string, content: string, message: string): string {+ const abs = join(repo, relPath);+ mkdirSync(join(abs, ".."), { recursive: true });+ writeFileSync(abs, content);+ git("add", "--", relPath);+ git("commit", "-q", "-m", message);+ return git("rev-parse", "HEAD");+}++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-git-reader-"));+ repo = join(tmp, "fixture-repo");+ mkdirSync(repo, { recursive: true });+ git("init", "-q", "-b", "main");+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++// ββ identity ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ++test("repoKey is deterministic, human-prefixed, and path-scoped", () => {+ const a = repoKey(repo);+ expect(a).toBe(repoKey(repo));+ expect(a.startsWith("fixture-repo-")).toBe(true);+ expect(a).toMatch(/^[a-z0-9-]+-[0-9a-f]{8}$/);+ const sibling = join(tmp, "fixture-repo-2");+ mkdirSync(sibling);+ expect(repoKey(sibling)).not.toBe(a);+});++test("repoKey sanitizes hostile basenames", () => {+ const weird = join(tmp, "My Repo (v2)!");+ mkdirSync(weird);+ const key = repoKey(weird);+ expect(key).toMatch(/^[a-z0-9-]+-[0-9a-f]{8}$/);+ expect(key.startsWith("my-repo-v2-")).toBe(true);+});++// ββ sha validation ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ++test("isFullSha accepts exactly 40 lowercase hex chars", () => {+ expect(isFullSha("a".repeat(40))).toBe(true);+ expect(isFullSha("A".repeat(40))).toBe(false);+ expect(isFullSha("a".repeat(39))).toBe(false);+ expect(isFullSha("a".repeat(41))).toBe(false);+ expect(isFullSha("--max-count=1; rm -rf /")).toBe(false);+ expect(isFullSha(42)).toBe(false);+ expect(isFullSha(null)).toBe(false);+});++// ββ readCommits βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ++test("readCommits returns structured commits oldest-first with touched files", () => {+ const first = commitFile("src/a.ts", "export const a = 1;\n", "feat: add a");+ const second = commitFile("src/b.ts", "export const b = 2;\n", "fix: add b\n\nlonger body here");+ const commits = readCommits(repo, {});+ expect(commits).not.toBeNull();+ expect(commits!).toHaveLength(2);+ expect(commits![0]!.sha).toBe(first);+ expect(commits![1]!.sha).toBe(second);+ expect(commits![0]!.subject).toBe("feat: add a");+ expect(commits![0]!.files).toEqual(["src/a.ts"]);+ expect(commits![1]!.body).toBe("longer body here");+ expect(commits![1]!.authorName).toBe("Fixture Author");+ expect(commits![1]!.authorEmail).toBe("[email protected]");+ expect(commits![1]!.committedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);+});++test("readCommits survives adversarial commit messages", () => {+ commitFile("a.txt", "x", 'subject with "quotes" \\x01 and %x00 percent-codes');+ commitFile(+ "b.txt",+ "y",+ "multi\n\nbody with\nnewlines, NUL-words, __COMMIT__ sentinels and unicode β",+ );+ const commits = readCommits(repo, {});+ expect(commits).not.toBeNull();+ expect(commits!).toHaveLength(2);+ expect(commits![0]!.subject).toContain("quotes");+ expect(commits![1]!.body).toContain("__COMMIT__ sentinels and unicode β");+ expect(commits![1]!.files).toEqual(["b.txt"]);+});++test("readCommits honours maxCount and range", () => {+ const first = commitFile("a.txt", "1", "one");+ commitFile("b.txt", "2", "two");+ const third = commitFile("c.txt", "3", "three");+ const bounded = readCommits(repo, { maxCount: 2 });+ expect(bounded!).toHaveLength(2);+ // maxCount keeps the NEWEST commits (git log semantics), still oldest-first.+ expect(bounded![1]!.sha).toBe(third);+ const ranged = readCommits(repo, { sinceSha: first });+ expect(ranged!).toHaveLength(2);+ expect(ranged!.map((c) => c.subject)).toEqual(["two", "three"]);+});++test("readCommits rejects an invalid range sha instead of passing it to git", () => {+ commitFile("a.txt", "1", "one");+ expect(() => readCommits(repo, { sinceSha: "HEAD~1; touch /tmp/pwned" })).toThrow(+ /sinceSha must be a full 40-hex/,+ );+});++test("readCommits includes merge commits with empty file list", () => {+ commitFile("a.txt", "1", "base");+ git("checkout", "-q", "-b", "feature");+ commitFile("f.txt", "f", "feature work");+ git("checkout", "-q", "main");+ commitFile("m.txt", "m", "main work");+ git("merge", "--no-ff", "-q", "-m", "merge: feature into main", "feature");+ const commits = readCommits(repo, {});+ const merge = commits!.find((c) => c.subject.startsWith("merge:"));+ expect(merge).toBeDefined();+ expect(merge!.files).toEqual([]);+});++test("readCommits is fail-soft on non-repos and empty repos", () => {+ const notRepo = join(tmp, "plain-dir");+ mkdirSync(notRepo);+ expect(readCommits(notRepo, {})).toBeNull();+ expect(readCommits(join(tmp, "missing"), {})).toBeNull();+ // Freshly-initialised repo with zero commits: empty array, not null.+ expect(readCommits(repo, {})).toEqual([]);+});++// ββ readTags / revListRange / shaExists βββββββββββββββββββββββββββββββββββββ++test("readTags returns lightweight and annotated tags peeled to commit shas", () => {+ const first = commitFile("a.txt", "1", "one");+ git("tag", "v0.1.0");+ const second = commitFile("b.txt", "2", "two");+ git("tag", "-a", "v0.2.0", "-m", "release v0.2.0");+ const tags = readTags(repo);+ expect(tags).not.toBeNull();+ expect(tags!).toHaveLength(2);+ const byName = new Map(tags!.map((t) => [t.name, t]));+ expect(byName.get("v0.1.0")!.targetSha).toBe(first);+ expect(byName.get("v0.2.0")!.targetSha).toBe(second);+});++test("readTags is empty on tagless repos and null on non-repos", () => {+ commitFile("a.txt", "1", "one");+ expect(readTags(repo)).toEqual([]);+ expect(readTags(join(tmp, "missing"))).toBeNull();+});++test("revListRange lists shas between two points, oldest-first", () => {+ const first = commitFile("a.txt", "1", "one");+ const second = commitFile("b.txt", "2", "two");+ const third = commitFile("c.txt", "3", "three");+ expect(revListRange(repo, first, third)).toEqual([second, third]);+ expect(revListRange(repo, null, first)).toEqual([first]);+ expect(() => revListRange(repo, "junk", third)).toThrow(/full 40-hex/);+ expect(() => revListRange(repo, first, "junk")).toThrow(/full 40-hex/);+});++test("shaExists validates input and probes the object store", () => {+ const sha = commitFile("a.txt", "1", "one");+ expect(shaExists(repo, sha)).toBe(true);+ expect(shaExists(repo, "0".repeat(40))).toBe(false);+ expect(shaExists(repo, "not-a-sha")).toBe(false);+});diff --git a/tests/core/brain/git/store.test.ts b/tests/core/brain/git/store.test.tsnew file mode 100644index 00000000..f032f1f0--- /dev/null+++ b/tests/core/brain/git/store.test.ts@@ -0,0 +1,196 @@+/**+ * Per-repo git record store with watermark+ * (Project History Suite, t_c812752c).+ */++import { afterEach, beforeEach, expect, test } from "bun:test";+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import {+ appendGitRecords,+ gitStoreDir,+ listGitCommits,+ listGitRepos,+ listGitTags,+ readGitState,+ writeGitState,+} from "../../../../src/core/brain/git/store.ts";+import type { GitCommitRecord, GitTagRecord } from "../../../../src/core/brain/git/store.ts";++let tmp: string;+let vault: string;++const KEY = "fixture-repo-abcd1234";++function commit(sha: string, over: Partial<GitCommitRecord> = {}): GitCommitRecord {+ return {+ kind: "commit",+ sha,+ authorName: "Fixture Author",+ authorEmail: "[email protected]",+ committedAt: "2026-06-01T10:00:00+00:00",+ subject: "feat: default subject",+ body: "",+ files: ["src/a.ts"],+ release: null,+ ...over,+ };+}++function tag(name: string, targetSha: string): GitTagRecord {+ return { kind: "tag", name, targetSha, createdAt: "2026-06-02T10:00:00+00:00" };+}++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-git-store-"));+ vault = join(tmp, "vault");+ mkdirSync(join(vault, "Brain"), { recursive: true });+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++test("gitStoreDir nests under Brain/projects/git/<repo-key>", () => {+ expect(gitStoreDir(vault, KEY)).toBe(join(vault, "Brain", "projects", "git", KEY));+});++test("append + list round-trips commits and tags, oldest-first", () => {+ const a = commit("a".repeat(40), { subject: "feat: first" });+ const b = commit("b".repeat(40), { subject: "fix: second", files: ["src/b.ts", "docs/x.md"] });+ const res = appendGitRecords(vault, KEY, [a, tag("v1.0.0", "b".repeat(40)), b]);+ expect(res.appended).toBe(3);+ expect(res.skipped).toBe(0);+ const commits = listGitCommits(vault, KEY);+ expect(commits.map((c) => c.subject)).toEqual(["feat: first", "fix: second"]);+ expect(commits[1]!.files).toEqual(["src/b.ts", "docs/x.md"]);+ const tags = listGitTags(vault, KEY);+ expect(tags).toHaveLength(1);+ expect(tags[0]!.name).toBe("v1.0.0");+});++test("append dedups commits by sha and tags by name across calls", () => {+ appendGitRecords(vault, KEY, [commit("a".repeat(40)), tag("v1.0.0", "a".repeat(40))]);+ const res = appendGitRecords(vault, KEY, [+ commit("a".repeat(40), { subject: "changed subject must not re-append" }),+ tag("v1.0.0", "a".repeat(40)),+ commit("c".repeat(40)),+ ]);+ expect(res.appended).toBe(1);+ expect(res.skipped).toBe(2);+ const commits = listGitCommits(vault, KEY);+ expect(commits).toHaveLength(2);+ expect(commits[0]!.subject).toBe("feat: default subject");+});++test("listGitCommits filters by file, author, text, time range, and limit keeps newest", () => {+ appendGitRecords(vault, KEY, [+ commit("a".repeat(40), {+ subject: "feat: alpha",+ files: ["src/a.ts"],+ committedAt: "2026-06-01T10:00:00+00:00",+ }),+ commit("b".repeat(40), {+ subject: "fix: beta touches a",+ files: ["src/a.ts", "src/b.ts"],+ committedAt: "2026-06-02T10:00:00+00:00",+ authorName: "Other Author",+ }),+ commit("c".repeat(40), {+ subject: "docs: gamma",+ body: "explains the alpha decision",+ files: ["docs/g.md"],+ committedAt: "2026-06-03T10:00:00+00:00",+ }),+ ]);+ expect(listGitCommits(vault, KEY, { file: "src/a.ts" })).toHaveLength(2);+ expect(listGitCommits(vault, KEY, { author: "other" })).toHaveLength(1);+ // text matches subject AND body, case-insensitive+ expect(listGitCommits(vault, KEY, { text: "ALPHA" }).map((c) => c.subject)).toEqual([+ "feat: alpha",+ "docs: gamma",+ ]);+ expect(listGitCommits(vault, KEY, { since: "2026-06-02T00:00:00Z" })).toHaveLength(2);+ expect(listGitCommits(vault, KEY, { until: "2026-06-01T23:59:59Z" })).toHaveLength(1);+ const limited = listGitCommits(vault, KEY, { limit: 2 });+ expect(limited.map((c) => c.subject)).toEqual(["fix: beta touches a", "docs: gamma"]);+});++test("a retargeted tag appends a fresh record and wins in listGitTags", () => {+ appendGitRecords(vault, KEY, [tag("v1.0.0", "a".repeat(40))]);+ // Same (name, target): dedup. New target for the same name: append.+ const res = appendGitRecords(vault, KEY, [+ tag("v1.0.0", "a".repeat(40)),+ tag("v1.0.0", "b".repeat(40)),+ ]);+ expect(res.skipped).toBe(1);+ expect(res.appendedTags).toBe(1);+ const tags = listGitTags(vault, KEY);+ expect(tags).toHaveLength(1);+ expect(tags[0]!.targetSha).toBe("b".repeat(40));+});++test("invalid since/until datetimes are rejected, not silently empty", () => {+ appendGitRecords(vault, KEY, [commit("a".repeat(40))]);+ expect(() => listGitCommits(vault, KEY, { since: "not-a-date" })).toThrow(/invalid 'since'/);+ expect(() => listGitCommits(vault, KEY, { until: "garbage" })).toThrow(/invalid 'until'/);+});++test("malformed JSONL lines are skipped, not fatal", () => {+ appendGitRecords(vault, KEY, [commit("a".repeat(40))]);+ const path = join(gitStoreDir(vault, KEY), "commits.jsonl");+ writeFileSync(path, `${readFileSync(path, "utf8")}not json\n{"kind":"junk"}\n`);+ appendGitRecords(vault, KEY, [commit("b".repeat(40))]);+ expect(listGitCommits(vault, KEY)).toHaveLength(2);+});++test("git state round-trips and validates the watermark sha", () => {+ expect(readGitState(vault, KEY)).toEqual({ state: null, error: null });+ writeGitState(vault, KEY, {+ repoPath: "/work/fixture-repo",+ lastSha: "d".repeat(40),+ lastIngestedAt: "2026-06-04T08:00:00Z",+ });+ const probe = readGitState(vault, KEY);+ expect(probe.error).toBeNull();+ expect(probe.state!.lastSha).toBe("d".repeat(40));+ expect(probe.state!.repoPath).toBe("/work/fixture-repo");+ expect(() =>+ writeGitState(vault, KEY, {+ repoPath: "/work/fixture-repo",+ lastSha: "HEAD",+ lastIngestedAt: "2026-06-04T08:00:00Z",+ }),+ ).toThrow(/full 40-hex/);+});++test("a corrupted state file reads as an error probe, never throws", () => {+ mkdirSync(gitStoreDir(vault, KEY), { recursive: true });+ writeFileSync(join(gitStoreDir(vault, KEY), "state.json"), "{broken");+ const probe = readGitState(vault, KEY);+ expect(probe.state).toBeNull();+ expect(probe.error).toMatch(/not valid JSON/);+ // Tampered watermark sha is rejected on read too.+ writeFileSync(+ join(gitStoreDir(vault, KEY), "state.json"),+ JSON.stringify({ repo_path: "/x", last_sha: "HEAD~1; evil", last_ingested_at: "t" }),+ );+ expect(readGitState(vault, KEY).error).toMatch(/full 40-hex/);+});++test("listGitRepos enumerates per-repo stores with their states", () => {+ expect(listGitRepos(vault)).toEqual([]);+ appendGitRecords(vault, KEY, [commit("a".repeat(40))]);+ writeGitState(vault, "other-repo-00000000", {+ repoPath: "/work/other",+ lastSha: "e".repeat(40),+ lastIngestedAt: "2026-06-04T08:00:00Z",+ });+ const repos = listGitRepos(vault);+ expect(repos.map((r) => r.key)).toEqual([KEY, "other-repo-00000000"]);+ expect(repos[0]!.state).toBeNull();+ expect(repos[1]!.state!.repoPath).toBe("/work/other");+ expect(existsSync(join(vault, "Brain", "projects", "git", KEY, "commits.jsonl"))).toBe(true);+});diff --git a/tests/core/brain/regions.test.ts b/tests/core/brain/regions.test.tsnew file mode 100644index 00000000..7d1251ab--- /dev/null+++ b/tests/core/brain/regions.test.ts@@ -0,0 +1,123 @@+/**+ * Sentinel-region merge engine (Project History Suite, t_929da8a2).+ * Generated regions refresh; everything else is operator-owned and+ * survives regeneration byte-for-byte.+ */++import { expect, test } from "bun:test";++import {+ buildRegionDocument,+ mergeRegions,+ parseRegions,+ RegionError,+} from "../../../src/core/brain/regions.ts";++const DOC = [+ "---",+ "kind: arch-overview",+ "---",+ "",+ "<!-- o2b:begin summary -->",+ "Generated summary v1.",+ "<!-- o2b:end summary -->",+ "",+ "Operator prose between regions stays untouched.",+ "",+ "<!-- o2b:begin modules -->",+ "- module a",+ "<!-- o2b:end modules -->",+ "",+ "Trailing operator notes.",+].join("\n");++test("parseRegions extracts region ids and bodies", () => {+ const regions = parseRegions(DOC);+ expect([...regions.keys()]).toEqual(["summary", "modules"]);+ expect(regions.get("summary")).toBe("Generated summary v1.");+ expect(regions.get("modules")).toBe("- module a");+});++test("mergeRegions replaces only generated bodies, preserving everything else byte-for-byte", () => {+ const merged = mergeRegions(DOC, [+ { id: "summary", body: "Generated summary v2." },+ { id: "modules", body: "- module a\n- module b" },+ ]);+ expect(merged).toContain("Generated summary v2.");+ expect(merged).toContain("- module b");+ expect(merged).toContain("Operator prose between regions stays untouched.");+ expect(merged).toContain("Trailing operator notes.");+ expect(merged).toContain("kind: arch-overview");+ // Idempotency: merging the same regions again changes nothing.+ expect(+ mergeRegions(merged, [+ { id: "summary", body: "Generated summary v2." },+ { id: "modules", body: "- module a\n- module b" },+ ]),+ ).toBe(merged);+});++test("regions missing from the document are appended at the end", () => {+ const merged = mergeRegions(DOC, [+ { id: "summary", body: "Generated summary v1." },+ { id: "decisions", body: "- new decisions section" },+ ]);+ expect(merged).toContain("<!-- o2b:begin decisions -->");+ expect(merged).toContain("- new decisions section");+ // Appended AFTER the operator's trailing notes.+ expect(merged.indexOf("Trailing operator notes.")).toBeLessThan(+ merged.indexOf("o2b:begin decisions"),+ );+});++test("regions present in the document but absent from the update stay untouched", () => {+ const merged = mergeRegions(DOC, [{ id: "summary", body: "v3" }]);+ expect(merged).toContain("- module a");+ expect(parseRegions(merged).get("modules")).toBe("- module a");+});++test("fail-closed: unbalanced, duplicate, and nested sentinels raise RegionError", () => {+ expect(() => parseRegions("<!-- o2b:begin a -->\nno end")).toThrow(RegionError);+ expect(() => parseRegions("<!-- o2b:end a -->")).toThrow(RegionError);+ expect(() =>+ parseRegions(+ "<!-- o2b:begin a -->\nx\n<!-- o2b:end a -->\n<!-- o2b:begin a -->\ny\n<!-- o2b:end a -->",+ ),+ ).toThrow(/duplicate/i);+ expect(() =>+ parseRegions(+ "<!-- o2b:begin a -->\n<!-- o2b:begin b -->\n<!-- o2b:end b -->\n<!-- o2b:end a -->",+ ),+ ).toThrow(/nested/i);+ // Mismatched end id.+ expect(() => parseRegions("<!-- o2b:begin a -->\nx\n<!-- o2b:end b -->")).toThrow(RegionError);+ // mergeRegions refuses to touch a corrupted document.+ expect(() => mergeRegions("<!-- o2b:begin a -->\nbroken", [{ id: "a", body: "x" }])).toThrow(+ RegionError,+ );+});++test("CRLF documents keep their regions visible (no duplicate appends)", () => {+ const crlf = ["<!-- o2b:begin a -->", "old body", "<!-- o2b:end a -->", ""].join("\r\n");+ expect(parseRegions(crlf).has("a")).toBe(true);+ const merged = mergeRegions(crlf, [{ id: "a", body: "new body" }]);+ expect(merged).toContain("new body");+ // Updated in place - not appended as a second region block.+ expect(merged.match(/o2b:begin a/g)).toHaveLength(1);+});++test("buildRegionDocument renders regions for a fresh file", () => {+ const doc = buildRegionDocument([+ { id: "summary", body: "First summary." },+ { id: "modules", body: "- m1" },+ ]);+ expect(parseRegions(doc).get("summary")).toBe("First summary.");+ expect(parseRegions(doc).get("modules")).toBe("- m1");+ // Round-trip: merging identical regions into a fresh document is identity.+ expect(+ mergeRegions(doc, [+ { id: "summary", body: "First summary." },+ { id: "modules", body: "- m1" },+ ]),+ ).toBe(doc);+});diff --git a/tests/e2e/project-history.integration.test.ts b/tests/e2e/project-history.integration.test.tsnew file mode 100644index 00000000..6c34db88--- /dev/null+++ b/tests/e2e/project-history.integration.test.ts@@ -0,0 +1,137 @@+/**+ * End-to-end flow of the Project History Suite (epic t_41c34987):+ * one real repo + one vault, driven through ingest -> find -> mine ->+ * architect, then re-run everything and prove idempotency and operator+ * edit survival.+ */++import { afterEach, beforeEach, expect, test } from "bun:test";+import { execFileSync } from "node:child_process";+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { generateArchDocs } from "../../src/core/brain/architect/generate.ts";+import { mineCommitDecisions } from "../../src/core/brain/git/decisions.ts";+import { ingestGitHistory } from "../../src/core/brain/git/ingest.ts";+import { gitStoreDir, listGitCommits } from "../../src/core/brain/git/store.ts";++let tmp: string;+let repo: string;+let vault: string;++function git(...args: string[]): string {+ return execFileSync(+ "git",+ [+ "-C",+ repo,+ "-c",+ "user.name=Fixture Author",+ "-c",+ "[email protected]",+ "-c",+ "commit.gpgsign=false",+ "-c",+ "tag.gpgsign=false",+ ...args,+ ],+ { encoding: "utf8", env: { ...process.env, GIT_CONFIG_GLOBAL: "/dev/null" } },+ ).trim();+}++function commitFile(relPath: string, content: string, message: string): string {+ const abs = join(repo, relPath);+ mkdirSync(join(abs, ".."), { recursive: true });+ writeFileSync(abs, content);+ git("add", "--", relPath);+ git("commit", "-q", "-m", message);+ return git("rev-parse", "HEAD");+}++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-e2e-history-"));+ repo = join(tmp, "demo-service");+ mkdirSync(repo, { recursive: true });+ git("init", "-q", "-b", "main");+ vault = join(tmp, "vault");+ mkdirSync(join(vault, "Brain"), { recursive: true });+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++test("ingest -> find -> mine -> architect -> re-run: one coherent project memory", () => {+ // ββ A project with structure, releases, and one decision commit ββ+ writeFileSync(join(repo, "package.json"), JSON.stringify({ name: "demo-service" }));+ commitFile("src/api/server.ts", "// api\n", "feat: bootstrap api server");+ commitFile("src/store/db.ts", "// db v1\n", "feat: sqlite-backed store");+ git("tag", "v1.0.0");+ commitFile(+ "src/store/db.ts",+ "// db v2\n",+ "feat!: migrate to jsonl store\n\nBREAKING CHANGE: sqlite file no longer read. " ++ "We decided to adopt JSONL instead of SQLite for portability.",+ );++ // ββ Ingest ββ+ const ingest = ingestGitHistory(vault, repo);+ expect(ingest.mode).toBe("initial");+ expect(ingest.newCommits).toBe(3);+ expect(ingest.newTags).toBe(1);++ // ββ Find: why did db.ts change? Store-only, no live git. ββ+ const dbHistory = listGitCommits(vault, ingest.repoKey, { file: "src/store/db.ts" });+ expect(dbHistory).toHaveLength(2);+ expect(dbHistory[0]!.release).toBe("v1.0.0");+ expect(dbHistory[1]!.release).toBeNull();+ expect(dbHistory[1]!.subject).toBe("feat!: migrate to jsonl store");++ // ββ Mine: the breaking migration surfaces as an ADR candidate. ββ+ const mined = mineCommitDecisions(vault, ingest.repoKey);+ expect(mined.created).toBe(1);+ const candidate = readFileSync(mined.notes[0]!, "utf8");+ expect(candidate).toContain("conventional_breaking");+ expect(candidate).toContain("decision_keyword:adopt");+ expect(candidate).toContain("migrate to jsonl store");++ // ββ Architect: structural notes for the same project. ββ+ const arch = generateArchDocs(vault, repo);+ expect(arch.repoKey).toBe(ingest.repoKey); // one repo-key namespace+ const overview = readFileSync(arch.overviewPath, "utf8");+ expect(overview).toContain("api");+ expect(overview).toContain("store");++ // ββ Operator curates: edits the candidate and annotates the overview. ββ+ writeFileSync(mined.notes[0]!, candidate + "\nOperator: accepted as ADR-1.\n");+ writeFileSync(arch.overviewPath, overview + "\nOperator: api owns all ingress.\n");++ // ββ New work lands; everything re-runs. ββ+ commitFile("src/api/routes.ts", "// routes\n", "feat: route table");+ const second = ingestGitHistory(vault, repo);+ expect(second.mode).toBe("incremental");+ expect(second.newCommits).toBe(1);+ expect(listGitCommits(vault, ingest.repoKey)).toHaveLength(4); // no duplicates++ const remined = mineCommitDecisions(vault, ingest.repoKey);+ expect(remined.created).toBe(0);+ expect(remined.skippedExisting).toBe(1);+ expect(readFileSync(mined.notes[0]!, "utf8")).toContain("Operator: accepted as ADR-1.");++ const rearch = generateArchDocs(vault, repo);+ const refreshed = readFileSync(rearch.overviewPath, "utf8");+ expect(refreshed).toContain("Operator: api owns all ingress.");++ // ββ The digest reflects the full store after the second ingest. ββ+ const digest = readFileSync(join(gitStoreDir(vault, ingest.repoKey), "digest.md"), "utf8");+ expect(digest).toContain("feat: route table");+ expect(digest).toContain("v1.0.0");++ // ββ Idle re-runs are no-ops. ββ+ const idle = ingestGitHistory(vault, repo);+ expect(idle.newCommits).toBe(0);+ const idleArch = generateArchDocs(vault, repo);+ expect(idleArch.created).toBe(0);+ expect(idleArch.updated).toBe(0);+});diff --git a/tests/mcp/brain-query-telemetry.test.ts b/tests/mcp/brain-query-telemetry.test.tsnew file mode 100644index 00000000..5313cf80--- /dev/null+++ b/tests/mcp/brain-query-telemetry.test.ts@@ -0,0 +1,99 @@+/**+ * `brain_query` recall telemetry (Project History Suite, t_405b8053+ * delta): the one query surface v0.39.0 left without telemetry now+ * mirrors the brain_search pattern - per-call opt-in, lazy gated emit,+ * kind-only payload, fail-open.+ */++import { afterEach, beforeEach, expect, test } from "bun:test";+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { listRecallTelemetry } from "../../src/core/brain/recall-telemetry.ts";+import { buildToolTable, findTool, type ServerContext } from "../../src/mcp/tools.ts";++let tmp: string;+let vault: string;+let configPath: string;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-query-telemetry-"));+ vault = join(tmp, "vault");+ mkdirSync(join(vault, "Brain"), { recursive: true });+ configPath = join(tmp, "config.yaml");+ writeFileSync(configPath, `vault: "${vault}"\n`);+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++function ctx(): ServerContext {+ return { vault, configPath, repoRoot: null };+}++function tool(name: string) {+ return findTool(buildToolTable("full"), name);+}++test("default off: brain_query emits zero continuity records", async () => {+ await tool("brain_query").handler(ctx(), { since: "2026-06-01T00:00:00Z" });+ expect(listRecallTelemetry(vault)).toHaveLength(0);+});++test("opt-in: one record with mode query, kind-only payload, no raw values persisted", async () => {+ const res = (await tool("brain_query").handler(ctx(), {+ topic: "secret-topic-value",+ telemetry: true,+ telemetry_host: "hermes",+ session_id: "sess-q1",+ })) as Record<string, unknown>;+ expect(res["mode"]).toBe("topic");++ const records = listRecallTelemetry(vault, { mode: "query" });+ expect(records).toHaveLength(1);+ const payload = records[0]!.payload;+ expect(payload["mode"]).toBe("query");+ expect(payload["host"]).toBe("hermes");+ expect(payload["session_id"]).toBe("sess-q1");+ expect(payload["status"]).toBe("empty");+ expect(typeof payload["duration_ms"]).toBe("number");+ const metadata = payload["metadata"] as Record<string, unknown>;+ expect(metadata["query_kind"]).toBe("topic");+ // The supplied topic value never lands anywhere - payload or disk.+ expect(JSON.stringify(payload)).not.toContain("secret-topic-value");+ const continuityDir = join(vault, "Brain", "log", "continuity");+ for (const name of readdirSync(continuityDir, { recursive: true }) as string[]) {+ let content: string;+ try {+ content = readFileSync(join(continuityDir, name), "utf8");+ } catch {+ continue; // directories+ }+ expect(content).not.toContain("secret-topic-value");+ }+});++test("error path: a failing preference lookup still emits, then rethrows", async () => {+ await expect(+ tool("brain_query").handler(ctx(), {+ preference: "pref-does-not-exist",+ telemetry: true,+ }),+ ).rejects.toThrow();+ const records = listRecallTelemetry(vault, { mode: "query" });+ expect(records).toHaveLength(1);+ expect(records[0]!.payload["status"]).toBe("error");+ expect(JSON.stringify(records[0]!.payload)).not.toContain("pref-does-not-exist");+});++test("fail-open: a broken continuity store never breaks the query result", async () => {+ mkdirSync(join(vault, "Brain", "log"), { recursive: true });+ writeFileSync(join(vault, "Brain", "log", "continuity"), "not a directory");+ const res = (await tool("brain_query").handler(ctx(), {+ since: "2026-06-01T00:00:00Z",+ telemetry: true,+ })) as Record<string, unknown>;+ expect(res["mode"]).toBe("since");+});