Skip to content

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

TypeScript

v0.10.15: vault care bundle - metadata, dedup, lint, context-pack, actions (#30)

Sol Aitken57552008c053
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6f694616..d6c36a7a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,102 @@ 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.10.15] - 2026-05-25
+
+Vault care bundle: eight related upstream-inspired metadata and
+maintenance features ship together in one release. New per-page
+frontmatter axes (`_lifecycle`, `tier`, `merged_into`), a Unicode-
+aware dedup key, a heuristic tokenizer, a bounded-token context
+pack, a self-healing lint pass, page-level deduplication, and a
+ranked maintenance action list - all built on a layered
+foundation so future maintenance features add a peer module
+rather than re-cutting the schema.
+
+### Added
+
+- `_lifecycle` frontmatter axis (`draft`, `stable`, `verified`,
+ `deprecated`, `archived`, `disputed`) on Brain pages. Default
+ read-side fallback is `stable`. Helpers in
+ `src/core/brain/page-meta/lifecycle.ts`: `readLifecycle`,
+ `isStale`, `ageDaysFromIso`.
+- Generalised `_confidence` read-helper in
+ `src/core/brain/page-meta/confidence.ts` so non-preference pages
+ can carry the existing `BRAIN_CONFIDENCE` triple.
+- `tier` frontmatter axis (`core`, `supporting`, `peripheral`) on
+ vault pages. Default `supporting` keeps the search ranker
+ bit-identical on untagged vaults. Ranker accepts an optional
+ `tierByDoc` input and applies a multiplicative weight to the
+ relevance term only.
+- `merged_into:` pointer + canonical resolver in
+ `src/core/brain/page-meta/page-id.ts`. Cycle detection bounded
+ at depth 5; dangling pointers fall through to the last reachable
+ id.
+- `src/core/brain/text/normalize.ts` (`normalizeForDedup`) -
+ NFKC + Unicode case folding, the shared key normaliser used by
+ dedup-hash and page-dedup.
+- `src/core/brain/text/tokenizer.ts` (`estimateTokens`) -
+ deterministic heuristic token counter: `ceil(utf8_bytes / 4)`.
+ Language-agnostic; no script-specific branching so the formula
+ works uniformly for any input.
+- `src/core/brain/page-dedup.ts` - exact-normalised-key page
+ dedup, secondary marking via `merged_into`, vault-wide wikilink
+ patcher that preserves aliases and anchors.
+- `o2b brain page-dedup [--apply]` CLI verb.
+- `src/core/brain/token-footprint.ts` -
+ `computeTokenFootprint(vault)` returning per-category counts
+ (preferences, retired, inbox, processed, log, other) with a
+ `BRAIN_TOKEN_WARN_THRESHOLD` env override.
+- `o2b brain token-footprint [--json]` CLI verb.
+- `src/core/brain/context-pack.ts` - tier-then-recency ordered
+ vault slice under a strict token budget, optional substring
+ query filter (Unicode + case insensitive).
+- `o2b brain context-pack --max-tokens <n> [--query <q>]` CLI verb.
+- `brain_context_pack` MCP tool exposing the same slice through
+ the JSON-RPC surface.
+- `src/core/brain/lint-consolidate.ts` -
+ `lintConsolidate(vault, { apply })` performs two self-healing
+ operations: `fix-merged-link` rewrites wikilinks pointing at a
+ page that carries `merged_into:` to the canonical, and
+ `demote-stale-stable` flags `_lifecycle: stable` preferences
+ older than 180 days with no recent evidence for demotion to
+ `draft`. Dry-run by default.
+- `o2b brain lint --consolidate [--apply] [--yes] [--json]` CLI verb.
+- `src/core/brain/maintenance/action-scorer.ts` -
+ `scoreActions(inputs, { topN })` deterministic ranking of
+ vault-maintenance actions by impact (dedup count × weight,
+ staleness × age, broken-link count, token-footprint excess).
+- `o2b brain actions [--top-n N] [--json]` CLI verb aggregating
+ dedup, lint, and footprint inputs through the scorer.
+
+### Changed
+
+- `computeDedupHash` now passes topic, principle, and scope
+ through `normalizeForDedup` before hashing so fullwidth /
+ halfwidth, NFC / NFD, and case-only variants collapse into one
+ signal. Previously only NFC normalisation applied to principle.
+- `RankerInputs` gains an optional `tierByDoc` field; absent or
+ `supporting` entries leave the ranker output bit-identical.
+- `writePreference` accepts optional `lifecycle` and `tier` inputs
+ and emits `_lifecycle` / `tier` frontmatter only when the
+ caller supplies them. Existing callers (and fixtures) stay
+ byte-identical.
+
+### Notes
+
+- The `tier` field is unprefixed (user-editable territory next to
+ `pinned`); `_lifecycle` carries the Group-C `_` prefix because
+ dream owns lifecycle transitions.
+- `brain_context_pack` is registered in the full MCP scope only,
+ not the always-loaded writer scope. The writer scope keeps its
+ four-tool surface (`brain_feedback`, `brain_apply_evidence`,
+ `brain_note`, `brain_context`).
+- No migration runs for the new `_lifecycle` / `tier` fields:
+ legacy preference and retired pages are left byte-identical.
+ Readers apply documented defaults (`stable`, `supporting`)
+ when the field is absent, so behaviour is consistent without
+ rewriting existing files. New writes opt in by passing the
+ fields to `writePreference`.
+
## [0.10.14] - 2026-05-25
Three independent quality-of-life improvements bundled into one
@@ -2328,6 +2424,8 @@ Hermes / Claude Code / Codex / OpenClaw configurations do not change.
[0.10.0]: https://github.com/itechmeat/open-second-brain/compare/v0.9.1...v0.10.0
[0.9.1]: https://github.com/itechmeat/open-second-brain/compare/v0.9.0...v0.9.1
[0.9.0]: https://github.com/itechmeat/open-second-brain/compare/v0.8.1...v0.9.0
+[0.10.15]: https://github.com/itechmeat/open-second-brain/compare/v0.10.14...v0.10.15
+[0.10.14]: https://github.com/itechmeat/open-second-brain/compare/v0.10.13...v0.10.14
[0.10.13]: https://github.com/itechmeat/open-second-brain/compare/v0.10.12...v0.10.13
[0.8.1]: https://github.com/itechmeat/open-second-brain/compare/v0.8.0...v0.8.1
[0.8.0]: https://github.com/itechmeat/open-second-brain/compare/v0.7.0...v0.8.0
diff --git a/README.md b/README.md
index 1224b6be..8e5b95a2 100644
--- a/README.md
+++ b/README.md
@@ -75,6 +75,15 @@ safety invariants are in [`docs/how-it-works.md`](docs/how-it-works.md).
(`o2b export-config`).
- Runs vault + adapter health checks (`o2b doctor`, plus
`o2b brain doctor` for Brain-specific invariants).
+- Surfaces vault care signals as one ranked next-step list
+ (`o2b brain actions`): page-level duplicates
+ (`o2b brain page-dedup`), self-healing structural drift
+ (`o2b brain lint --consolidate`), token-budget monitoring
+ (`o2b brain token-footprint`), and a bounded-token vault slice
+ for priming an agent's context window
+ (`o2b brain context-pack --max-tokens N`). Per-page metadata
+ (`_lifecycle`, `tier`, `merged_into`) feeds the ranker and the
+ search relevance signal.
- (Optional) Records paid agent actions through **Pay Memory**:
receipts, generated assets, spending policy decisions, human
approval state, and per-day reports — all as plain Markdown
diff --git a/docs/brainstorm/vault-care-bundle/cli-output/claude.md b/docs/brainstorm/vault-care-bundle/cli-output/claude.md
new file mode 100644
index 00000000..ab0ba34b
--- /dev/null
+++ b/docs/brainstorm/vault-care-bundle/cli-output/claude.md
@@ -0,0 +1,85 @@
+### Variant 1: Layered foundation (schema → utilities → consumers)
+- **Approach**: Build three horizontal layers bottom-up: a `page-meta/` layer owning the new frontmatter atoms (lifecycle, tier, merged-pointer), a `text/` layer owning the deterministic helpers (NFKC+casefold normaliser, heuristic tokenizer, action-impact scorer), and the consumer layer that wires those into the ranker, digest, doctor, lint, context-pack, and footprint verbs. Strict DAG: consumers depend on layers, never on each other; one extended `migrate-frontmatter` pass covers all schema additions.
+- **Shared building blocks**:
+ - `src/core/brain/page-meta/lifecycle.ts` — `Lifecycle` enum, default resolver, staleness predicate (F1, F4, F8).
+ - `src/core/brain/page-meta/confidence.ts` — generalises today's `_confidence` to non-preference pages (F1).
+ - `src/core/brain/page-meta/tier.ts` — `Tier` enum, default `supporting`, tier-weight table (F2, F6, F8).
+ - `src/core/brain/page-meta/page-id.ts` — `merged_into` pointer + canonical resolver (F3, F4).
+ - `src/core/brain/text/normalize.ts` — NFKC + casefold dedup key (F7, F3).
+ - `src/core/brain/text/tokenizer.ts` — single heuristic token counter (F5, F6, F8).
+ - `src/core/brain/maintenance/action-scorer.ts` — impact-weighted action item builder (F8).
+ - Extension of the existing `migrate-frontmatter` verb to cover the new fields idempotently.
+- **Implementation order**:
+ 1. F7 — pure refactor of `dedup-hash.ts` to NFKC+casefold; unblocks F3 without schema churn.
+ 2. F1 — confidence + lifecycle frontmatter via `page-meta/` and `migrate-frontmatter`.
+ 3. F2 — tier frontmatter + ranker hook in `src/core/search/ranker.ts`.
+ 4. F3 — page dedup, consuming F7 normalisation, F1 lifecycle (skip deprecated/archived), and the `merged_into` pointer.
+ 5. F5 — token footprint verb + digest section, introducing the shared tokenizer.
+ 6. F6 — `brain_context_pack` MCP tool + CLI verb, composing tier + lifecycle + tokenizer.
+ 7. F4 — `o2b brain lint --consolidate` with dry-run, using lifecycle for demotion and page-id for orphan-merge hints.
+ 8. F8 — ranked action list, composing every prior layer through `action-scorer.ts` and surfacing in digest + doctor.
+- **Trade-offs**:
+ - Pros: Every shared concept has one owner file; future maintenance features add a peer module instead of recutting an abstraction.
+ - Pros: Tests mirror layers (`tests/core/brain/page-meta/*`, `tests/core/brain/text/*`), so per-tool tests stay small.
+ - Pros: One migration sweep covers F1+F2+F3 pointer; old pages keep parsing with default values.
+ - Cons: Touches more consumer files in one PR (ranker, digest, doctor, dream, inline-scan, sessions/import), so the diff feels wide even though each touch is small.
+ - Cons: Some readers have to chase logic across `page-meta/` and the consumer, instead of seeing it inline.
+- **Complexity**: medium
+- **Risk**: low
+
+### Variant 2: Single maintenance index (one scan, many views)
+- **Approach**: Introduce a `MaintenanceIndex` that walks the vault once (reusing `inline-scan` + `backlinks` + `explorer` outputs) and exposes typed views — `byTier`, `byLifecycle`, `tokenByCategory`, `dedupCandidates`, `orphans`, `staleForDemotion`. Every consumer (digest, doctor, lint, context-pack, footprint, action-list) reads from this index instead of re-scanning. The schema additions and normalisation helper feed the index; the eight features become "another view + thin verb" on top.
+- **Shared building blocks**:
+ - `src/core/brain/maintenance-index/types.ts` — `Lifecycle`, `Tier`, `PageMeta`, `TokenCount`, `DedupCandidate`, `ActionItem` (one schema home).
+ - `src/core/brain/maintenance-index/builder.ts` — single-pass scanner producing the cached index.
+ - `src/core/brain/maintenance-index/views.ts` — typed accessors per concern (F2, F3, F4, F5, F6, F8 all consume this).
+ - `src/core/brain/text/normalize.ts` — NFKC + casefold helper (F7, also feeds dedup-hash + index).
+ - Action-scorer is a function over the index, not its own module.
+- **Implementation order**:
+ 1. F1 + F2 together — lifecycle + tier added to `FrontmatterMap` and `migrate-frontmatter`; both are pure schema bumps.
+ 2. F7 — NFKC + casefold in `text/normalize.ts`, called from `dedup-hash.ts`.
+ 3. Maintenance-index skeleton — scanner + empty views.
+ 4. F5 — first view (`tokenByCategory`) wired to a CLI verb + digest section.
+ 5. F3 — `dedupCandidates` view, `merged_into` writer, wikilink patcher.
+ 6. F4 — `lint --consolidate` composing `orphans` + `staleForDemotion` + `dedupCandidates` with `--dry-run`/`--apply`.
+ 7. F6 — `context_pack` over the index, ordered by tier then recency under a token budget.
+ 8. F8 — pure function over the index, replacing the vague "Recommendation" string in digest + doctor.
+- **Trade-offs**:
+ - Pros: One canonical scan per command — measurable perf win for larger vaults and fewer race-windows against the watcher.
+ - Pros: Tests concentrate on one well-typed module plus thin per-feature wrappers; views are easy to snapshot.
+ - Pros: Future maintenance features cost "one new view + one new action term".
+ - Cons: God-module risk — `maintenance-index/` accumulates concerns and needs strict sub-file discipline.
+ - Cons: Forces every feature through the same abstraction even where (F7) it is overkill, making early commits read as scaffolding.
+ - Cons: Sequential ordering — F3-F8 all wait on the index being non-trivial, so parallelisation inside the PR is limited.
+- **Complexity**: medium
+- **Risk**: medium
+
+### Variant 3: Per-feature modules with minimal shared atoms
+- **Approach**: Each feature ships as a focused module under `src/core/brain/<feature>.ts` plus its CLI verb file; the only shared surface is a tiny `page-meta/types.ts` (Lifecycle, Tier enums), one normaliser, and one tokenizer helper. Feature files compose existing primitives (`inline-scan`, `backlinks`, `explorer`) directly rather than through a new index or scorer module.
+- **Shared building blocks**:
+ - `src/core/brain/page-meta/types.ts` — `Lifecycle`, `Tier` enums + default/parse helpers (F1, F2, F3, F4, F8).
+ - `src/core/brain/text/normalize.ts` — NFKC + casefold helper (F7, used by F3).
+ - `src/core/brain/text/tokenizer.ts` — heuristic token counter (F5, F6, F8 each call directly).
+ - Per-feature modules: `lifecycle-confidence.ts`, `tier.ts`, `page-dedup.ts`, `lint-consolidate.ts`, `token-footprint.ts`, `context-pack.ts`, `maintenance-actions.ts`.
+ - No central maintenance index; no central action-scorer module.
+- **Implementation order**:
+ 1. F7 — refactor `dedup-hash.ts` to NFKC + casefold; isolated.
+ 2. F1 — confidence + lifecycle frontmatter + migrate-frontmatter.
+ 3. F2 — tier frontmatter + ranker hook.
+ 4. F5 — token footprint verb + digest section.
+ 5. F3 — page dedup using F7 normalisation and F1 lifecycle gating.
+ 6. F6 — context-pack using F2 tier + tokenizer.
+ 7. F4 — lint --consolidate using F1 lifecycle and F3 dedup hints.
+ 8. F8 — action list re-deriving inputs from each feature module.
+- **Trade-offs**:
+ - Pros: Smallest, most local diffs per feature; reviewers can read one file per feature; reverts stay surgical.
+ - Pros: Steps 1-5 are largely independent — subagent dispatch is straightforward.
+ - Pros: Lowest cognitive load to land the first few features quickly.
+ - Cons: Tokenization, lifecycle classification, tier scoring get inlined into multiple callers — future schema changes touch many files.
+ - Cons: F8 becomes a fat module that re-walks data prior features already computed; wasted vault walks per invocation.
+ - Cons: Test surface fragments; no single canonical maintenance view to snapshot-test, so coverage relies on disciplined per-verb tests.
+- **Complexity**: small per file, medium overall
+- **Risk**: medium (drift risk across future releases)
+
+### Recommended: Variant 1
+**Rationale**: The eight features cleanly split into two horizontal concerns (frontmatter atoms, deterministic text/scoring helpers) feeding a vertical layer of mostly-additive consumer changes — a layered shape captures that without paying for the god-index of Variant 2 or accepting the duplication and drift risk of Variant 3. It also matches established OSB conventions: per-concern files alongside `backlinks.ts` and `explorer.ts`, one `migrate-frontmatter` sweep for the new fields, additive MCP surface, and consumer hooks (`ranker.ts`, `digest.ts`, `doctor.ts`) edited in narrow ways. Crucially, it keeps the door open for future maintenance features (freshness signal, tag taxonomy, vault-size policies) by adding a peer file under `page-meta/` or `text/` instead of re-cutting the schema.
diff --git a/docs/brainstorm/vault-care-bundle/cli-output/prompt.md b/docs/brainstorm/vault-care-bundle/cli-output/prompt.md
new file mode 100644
index 00000000..d0cb1ef7
--- /dev/null
+++ b/docs/brainstorm/vault-care-bundle/cli-output/prompt.md
@@ -0,0 +1,106 @@
+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
+
+Ship one Open Second Brain (OSB) release that bundles eight related vault-metadata + maintenance features in a single PR. Decide the architectural envelope, shared building blocks, and ordering. Do NOT design each feature in detail - that comes later. Focus on how the eight slot together so the diff stays coherent, test surfaces stay sane, and future maintenance features plug in without re-cutting the schema.
+
+The eight features (all approved from the kanban triage, priorities P4 then P3):
+
+1. **t_5de021f1 (P4) Per-page confidence + lifecycle frontmatter.** Add `confidence:` (high/medium/low) and `lifecycle:` (draft/stable/verified/deprecated/archived/disputed) frontmatter to vault pages produced by OSB (preferences, signals, evidence). Annotate citations from stale or disputed pages so readers see verification status. OSB already has `_confidence` on preferences (BRAIN_CONFIDENCE enum). The work generalises that pattern to other page kinds and introduces a lifecycle axis OSB does not yet have.
+
+2. **t_3d157e9b (P3) Page importance tier frontmatter.** Add `tier:` (core/supporting/peripheral) to vault pages. The search ranker (src/core/search/ranker.ts) consumes the new field as a relevance signal. New page-producing call sites set the tier on creation; existing pages get `supporting` by default.
+
+3. **t_e0d65daa (P3) Page-level deduplication.** Detect near-duplicate vault pages (not just signal-level content hashes), canonicalise the best one, patch wikilinks across the vault, and record `merged_into:` on the secondary. OSB already has `dedup-hash.ts` for signal-level SHA256 dedup but no page identity resolution.
+
+4. **t_55bd528a (P3) Self-healing vault lint.** `o2b brain lint --consolidate` performs proactive fixes (broken wikilinks, orphan reconciliation, lifecycle demotion of stale peripheral pages, tag-alias normalisation). Today `brain_doctor` is read-only. Must support dry-run diff.
+
+5. **t_68e65e77 (P3) Vault token footprint monitoring.** Report per-category vault size in tokens with a warn threshold (default 200k). Surfaced via a new CLI verb and a section in `brain_digest`. Uses the same tokenizer as brain_search for consistency.
+
+6. **t_31c16ba2 (P3) Bounded-token context retrieval.** New `brain_context_pack(max_tokens, query?)` MCP tool plus CLI verb that returns the highest-signal vault slice under a strict token budget, ordered by importance tier then recency. Pairs with feature 2.
+
+7. **t_2e7e3b8d (P3) Unicode/CJK dedup normalisation.** Dedup keys today call `normalize("NFC")`. Adopt NFKC + `casefold()`-style lowercasing so CJK, fullwidth/halfwidth variants, and case-only variants merge correctly. Touches `dedup-hash.ts` and any other dedup key construction site.
+
+8. **t_8dd35d10 (P3) Ranked maintenance action list.** Replace vague "Recommendation" output with a prioritised "What to do next" list scored by impact (orphan count × tier weight, staleness × evidence count, dedup candidates, token-footprint excess). Surfaces in `brain_digest` and `brain_doctor`.
+
+# Project context
+
+Project: Open Second Brain (OSB) - https://github.com/itechmeat/open-second-brain
+Runtime: Bun + TypeScript, Markdown vault on disk, optional SQLite-backed search index.
+Recent commits (newest first):
+
+```text
+9d9636b feat: index fastpath, PEM/JWT redaction, vault connection health (v0.10.14) (#29)
+7d81f0b feat: codegraph-partner skill + o2b doctor check (v0.10.13) (#28)
+0462b91 feat: v0.10.12 operational friction reduction (#27)
+9d8af95 Merge pull request #26 from itechmeat/feature/v0.10.11-multi-runtime-install
+852c9b5 v0.10.11: address CodeRabbit review
+f819f32 v0.10.11: Multi-runtime install orchestrator + Most-applied in digest
+88bce1f Merge pull request #25 from itechmeat/feature/v0.10.10-pull-channels
+3e297a5 v0.10.10: address CodeRabbit review
+0484a23 v0.10.10: Pull channels — brain_context tool, Most-applied (30d), o2b brain note, semantic hint
+```
+
+Relevant files (codegraph-discovered):
+
+- `src/core/brain/preference.ts` - preference writer, currently emits `_confidence`, `_status`, `_evidenced_by`, etc. Group C derived fields use `_` prefix.
+- `src/core/brain/dedup-hash.ts` - signal-level NFC normalisation, SHA256 hash. ~100 LOC.
+- `src/core/brain/inline-scan.ts` - inline scan loop, walks vault, builds dedup index.
+- `src/core/brain/sessions/import.ts` - session importer, reuses dedup index.
+- `src/core/brain/dream.ts` - dream pass, owns preference status transitions.
+- `src/core/brain/digest.ts` - `collectDigestData` produces digest JSON/Markdown.
+- `src/core/brain/policy.ts` - `loadBrainConfig` reads `Brain/_brain.yaml`.
+- `src/core/brain/backlinks.ts` - backlink index for digest connection-health (added v0.10.14).
+- `src/core/brain/explorer.ts` - vault graph for explorer tool (`ExplorerNode` has `backlink_count`).
+- `src/core/search/ranker.ts` - `RankerInputs`, `RankerOptions`, `rankResults`. Keyword + semantic + tag boosts.
+- `src/core/types.ts` - `FrontmatterMap = Record<string, FrontmatterValue>` (string | number | boolean | ReadonlyArray<string>).
+- `src/core/vault-scope/index.ts` - vault scope policy (ignore_paths, walker rules).
+- `src/mcp/brain-tools.ts` - MCP tools: `brain_doctor`, `brain_digest`, `brain_context`, `brain_feedback`, etc.
+- `src/mcp/server.ts` - MCP server context().
+- `src/cli/brain/verbs/` - 24 verb files: `doctor`, `digest`, `dream`, `feedback`, `query`, `scan-inline`, `migrate-frontmatter`, etc. Each verb is one file.
+
+Project conventions (from README, CHANGELOG top, design-doc patterns):
+
+- One PR = one CHANGELOG version. Multi-feature releases bundle under a single version (v0.10.12 did 4 features, v0.10.14 did 3).
+- Each release ships a design-doc under `docs/superpowers/specs/<date>-<theme>-design.md` or an implementation plan under `docs/plans/<date>-<theme>-impl.md`. The brainstorm under `docs/brainstorm/<slug>/` is the upstream artifact for those.
+- New MCP tools land in `src/mcp/brain-tools.ts` (or `pay-memory-tools.ts`); new CLI verbs land in `src/cli/brain/verbs/<verb>.ts` and register through `src/cli/brain/verbs/index.ts`.
+- New `Brain/` schema fields go through a `migrate-frontmatter` step so old pages get the new fields lazily and idempotently. Group C derived fields use `_` prefix; user-editable fields stay unprefixed.
+- Tests use Bun's built-in runner (`bun test`), live under `tests/`, mirror the source tree by area (`tests/core/brain/`, `tests/cli/brain/`, `tests/mcp/`).
+- Per-tool tests required for every new MCP tool and CLI verb.
+- AI authorship markers (e.g. "🤖 Generated with Claude Code") forbidden in public artifacts.
+- Use full product name "Open Second Brain" in CHANGELOG / README / release notes; "OSB" only in private chat.
+- All numeric priorities follow Hermes convention (`DEFAULT 0`, `ORDER BY priority DESC`).
+- Default lifecycle for newly-introduced fields is the most permissive option so existing pages remain valid without migration.
+
+Constraints:
+
+- Do NOT change Hermes core or any vendored runtime; everything lives inside OSB.
+- Do NOT introduce new external dependencies if a stdlib / Bun-native option exists (NFKC + casefold-equivalent are in Bun/Node `String.prototype.normalize` and `String.prototype.toLowerCase`; token counter can stay heuristic, no `tiktoken` etc.).
+- Backwards-compatible frontmatter: old pages without the new fields must keep parsing; default values resolve at read-time.
+- Token-budget routines must be deterministic and side-effect free (no LLM calls).
+- Dry-run is mandatory for `lint --consolidate`. Write paths require explicit `--apply`.
+- Public MCP tool surface evolves additively; never break existing tool names or shapes.
+
+# Required output format
+
+Produce exactly 3 distinct architectural variants for how to STRUCTURE the bundle (shared modules, ordering, naming conventions, test surfaces). The variants must differ in how they group the eight features into shared building blocks, not in which features ship.
+
+For each variant, follow this template exactly:
+
+```markdown
+### Variant N: <short name>
+- **Approach**: 2-3 sentences describing the variant.
+- **Shared building blocks**: list the new core modules / types this variant introduces and what feature(s) each one underlies.
+- **Implementation order**: ordered list of the 8 features showing the dependency order this variant enforces.
+- **Trade-offs**: bullet list of pros and cons.
+- **Complexity**: small | medium | large
+- **Risk**: low | medium | high
+```
+
+After the three variants, add exactly one recommendation in this shape:
+
+```markdown
+### 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/vault-care-bundle/design.md b/docs/brainstorm/vault-care-bundle/design.md
new file mode 100644
index 00000000..b080b7e9
--- /dev/null
+++ b/docs/brainstorm/vault-care-bundle/design.md
@@ -0,0 +1,131 @@
+# vault-care-bundle - layered metadata + maintenance pipeline
+
+**Status:** draft
+**Author:** @claude-vps-agent (via feature-release-playbook)
+**Audience:** implementation
+
+## Problem statement
+
+Eight related upstream-inspired vault features ship together in one Open Second Brain release: per-page confidence/lifecycle, page importance tier, page-level dedup, self-healing lint, token footprint monitoring, bounded-token context retrieval, Unicode/CJK dedup normalisation, and a ranked maintenance action list. Done one at a time they would touch the same files (ranker, digest, doctor, dream, dedup-hash, migrate-frontmatter) repeatedly across releases. Done as an unstructured bundle they would mash schema, scoring, scanning, and CLI changes into one giant diff.
+
+## Scope
+
+Layered architecture for the bundle, chosen from a 3-variant brainstorm:
+
+- `src/core/brain/page-meta/` - frontmatter atoms (lifecycle, generalised confidence, tier, merged-pointer).
+- `src/core/brain/text/` - deterministic helpers (NFKC+casefold normaliser, heuristic tokenizer).
+- `src/core/brain/maintenance/action-scorer.ts` - impact-weighted action item builder used by digest and doctor.
+- One `migrate-frontmatter` sweep covers F1+F2+F3 schema additions.
+- Eight features (F1-F8) consume those layers through narrow edits to existing consumers (`ranker.ts`, `digest.ts`, `doctor.ts`, `dream.ts`, `inline-scan.ts`, `sessions/import.ts`) and new CLI verbs (`lint`, `token-footprint`, `context-pack`, `page-dedup`) + new MCP tools (`brain_context_pack`).
+
+## Out of scope
+
+- Semantic vault health (contradiction detection, concept-gap detection) - separate task t_1f00d9bc.
+- Trust verdict / operator dashboard - separate tasks t_3440fa2c, t_dd9a602e.
+- Block-link / heading anchor granularity in backlinks - separate task t_28f7dc4b.
+- Frontmatter alias resolution - separate task t_fb753446.
+- New tokenizer library or `tiktoken` integration - stays heuristic, Bun stdlib only.
+- Auto-fixing semantic contradictions in `lint --consolidate` - this PR fixes only structural drift (broken links, orphan lifecycle, tag aliases).
+
+## Chosen approach
+
+**Variant 1 (Layered foundation)**. Three horizontal layers built bottom-up; the eight feature outputs sit on top.
+
+```text
+Consumer layer: ranker.ts | digest.ts | doctor.ts | dream.ts | inline-scan.ts | sessions/import.ts
+ + new CLI verbs (lint, token-footprint, context-pack, page-dedup)
+ + new MCP tool (brain_context_pack)
+ ^ ^ ^
+ | | |
+Helper layer: text/normalize.ts text/tokenizer.ts maintenance/action-scorer.ts
+ ^ ^ ^
+ | | |
+Atom layer: page-meta/{lifecycle,confidence,tier,page-id}.ts
+ ^
+ |
+Schema migrate: cli/brain/verbs/migrate-frontmatter.ts (extended; one sweep covers F1+F2+F3)
+```
+
+Consumers depend on layers, never on each other. The DAG keeps the diff coherent: each feature commit edits ≤1 consumer file plus its tests; shared atoms get one file each.
+
+## Design decisions
+
+- **Generalise existing `_confidence` rather than introduce a new field**: preferences already carry `_confidence` (BRAIN_CONFIDENCE enum) under the Group-C `_` prefix convention. Extend the same field to other page kinds (signals, evidence, retired entries) and surface lifecycle via a new `_lifecycle` field next to it. Reason: avoids re-cutting an existing concept; keeps reader-side parsing rules unchanged.
+- **`tier:` is user-editable, NOT under `_` prefix**: tier expresses operator intent (which preferences/notes matter most), so it sits alongside `pinned` as user-owned metadata. Default at read-time is `"supporting"`.
+- **`merged_into:` lives on the secondary, never the canonical**: a dedup merge writes `merged_into: pref-<canonical-slug>` to the secondary's frontmatter and rewrites every wikilink in the vault that pointed to the secondary. Reading code resolves `merged_into` transitively (capped at depth 5 to fail-loud on cycles).
+- **NFKC + casefold goes into `text/normalize.ts`, NOT into `dedup-hash.ts` directly**: `dedup-hash.ts` keeps its narrow purpose (compute a SHA256 of normalised inputs). The new helper is a one-line `s.normalize("NFKC").toLowerCase()` wrapper but lives in `text/` so other call sites (search ranker, alias index, future fuzzy match) can reuse it.
+- **Token counter is heuristic, not tokenizer-accurate**: deterministic `ceil(utf8_bytes / 4)`, the OpenAI rule-of-thumb generalised to bytes so it stays language-agnostic. No script-specific branching, no external tokenizer dependency. Good enough for monitoring + budget enforcement.
+- **`brain_context_pack(max_tokens, query?)`**: returns highest-tier pages first, then most-recently-applied preferences, then `confirmed` signals, until adding the next item would exceed `max_tokens`. Result includes the actual token estimate so callers can introspect. `query?` is an optional substring filter; full semantic search stays in the existing `brain_search` tool.
+- **`o2b brain lint --consolidate`**:
+ - Dry-run by default; `--apply` required to write.
+ - Operations: fix broken wikilinks (target file moved/renamed), reconcile orphan lifecycle (orphan + `lifecycle: stable` for > N days → demote to `draft`), normalise tag aliases (case + NFKC).
+ - Does NOT touch semantic content. Emits a deterministic diff readable in CI.
+- **Ranked action list**: each candidate action gets an impact score = base weight × multiplier (e.g. broken-link = 5 × number-of-files-affected). Top N (default 10) surface in `brain_digest` under a new `## Actions` section and in `brain_doctor` as a `suggested_actions:` block.
+- **Existing CLI conventions preserved**: every new verb registers via `src/cli/brain/verbs/index.ts`; every new MCP tool registers via `src/mcp/brain-tools.ts`. No subcommand collapses; flat verb namespace continues.
+
+## File changes
+
+### New source files
+
+- `src/core/brain/page-meta/lifecycle.ts` - `Lifecycle` enum (`draft|stable|verified|deprecated|archived|disputed`), `defaultLifecycle()`, `isStale()` predicate.
+- `src/core/brain/page-meta/confidence.ts` - re-export + helpers to read/write `_confidence` on non-preference pages.
+- `src/core/brain/page-meta/tier.ts` - `Tier` enum (`core|supporting|peripheral`), default = `"supporting"`, `tierWeight()` lookup table.
+- `src/core/brain/page-meta/page-id.ts` - `mergedIntoPath()` resolver, `setMergedInto()` writer, cycle detection.
+- `src/core/brain/text/normalize.ts` - `normalizeForDedup(s: string): string` returning `s.normalize("NFKC").toLowerCase()`.
+- `src/core/brain/text/tokenizer.ts` - `estimateTokens(s: string): number` heuristic.
+- `src/core/brain/maintenance/action-scorer.ts` - `ActionItem`, `scoreActions(input): ActionItem[]`.
+- `src/core/brain/page-dedup.ts` - `findDuplicateCandidates(vault)`, `mergePage(vault, secondary, canonical)`, `patchWikilinks(vault, oldTarget, newTarget)`.
+- `src/core/brain/lint-consolidate.ts` - `lintConsolidate(vault, opts: { apply: boolean })` returning a structured diff.
+- `src/core/brain/token-footprint.ts` - `computeTokenFootprint(vault)` returning `{ byCategory: Map<string, number>, total: number, warnThreshold: number, exceeded: boolean }`.
+- `src/core/brain/context-pack.ts` - `packContext(vault, opts: { maxTokens, query? })` returning a serialisable slice.
+- `src/cli/brain/verbs/lint.ts` - `o2b brain lint [--consolidate] [--apply]`.
+- `src/cli/brain/verbs/token-footprint.ts` - `o2b brain token-footprint [--json]`.
+- `src/cli/brain/verbs/context-pack.ts` - `o2b brain context-pack --max-tokens <n> [--query <q>]`.
+- `src/cli/brain/verbs/page-dedup.ts` - `o2b brain page-dedup [--apply]`.
+
+### Modified source files
+
+- `src/core/brain/dedup-hash.ts` - swap `"NFC"` → call to `normalizeForDedup` (F7).
+- `src/core/search/ranker.ts` - add tier signal to `RankerInputs` + `rankResults` weighting (F2).
+- `src/core/brain/digest.ts` - add tokenFootprint section, rankedActions section (F5, F8).
+- `src/core/brain/doctor.ts` - emit `suggested_actions` (F8).
+- `src/core/brain/preference.ts` - emit `_lifecycle` next to `_confidence`, accept `tier` as input (F1, F2).
+- `src/core/brain/dream.ts` - apply lifecycle transitions (`stable` → `verified` on N reapplies); update tier auto-suggestion (F1, F2).
+- `src/cli/brain/verbs/migrate-frontmatter.ts` - extend the single sweep to add `_lifecycle: stable`, `tier: supporting` to existing pages (F1, F2, F3).
+- `src/cli/brain/verbs/index.ts` - register the four new verbs.
+- `src/mcp/brain-tools.ts` - register `brain_context_pack` MCP tool (F6); extend `brain_digest`, `brain_doctor` outputs to surface new sections.
+
+### New test files
+
+- `tests/core/brain/page-meta/lifecycle.test.ts`
+- `tests/core/brain/page-meta/tier.test.ts`
+- `tests/core/brain/page-meta/page-id.test.ts`
+- `tests/core/brain/text/normalize.test.ts`
+- `tests/core/brain/text/tokenizer.test.ts`
+- `tests/core/brain/maintenance/action-scorer.test.ts`
+- `tests/core/brain/page-dedup.test.ts`
+- `tests/core/brain/lint-consolidate.test.ts`
+- `tests/core/brain/token-footprint.test.ts`
+- `tests/core/brain/context-pack.test.ts`
+- `tests/cli/brain/lint.test.ts`
+- `tests/cli/brain/token-footprint.test.ts`
+- `tests/cli/brain/context-pack.test.ts`
+- `tests/cli/brain/page-dedup.test.ts`
+- `tests/mcp/context-pack-tool.test.ts`
+- `tests/core/search/ranker-tier.test.ts`
+- `tests/core/brain/digest-actions.test.ts`
+- `tests/core/brain/dedup-hash-unicode.test.ts` (Unicode regression cases)
+
+### Docs / metadata
+
+- `README.md` - one new paragraph in the feature list.
+- `CHANGELOG.md` - new `[0.10.15]` entry with capability-first summary + Added / Changed / Notes sections.
+- `docs/brainstorm/vault-care-bundle/{design.md,plan.md,variants.md,cli-output/}` - this artifact set.
+
+## Risks and open questions
+
+- **Migration sweep deliberately skipped**: the original plan extended `migrate-frontmatter` to backfill `_lifecycle: stable` and `tier: supporting` on legacy pages. Implementation chose read-side defaults instead - `readLifecycle()` and `readTier()` return the documented default whenever the field is absent. Trade-off: legacy files stay byte-identical (no Syncthing churn, no migration risk on user vaults), at the cost of the new fields not appearing in on-disk YAML until a write touches the page. Acceptable because every reader has a fallback path; revisit only if a future feature actually needs the field materialised on disk.
+- **Page-dedup wikilink patcher rewriting tests**: care needed not to rewrite wikilinks inside committed fixture files. Mitigation: dedup operates only on `Brain/` paths (use `brainDirs()`), tests run in a tmpdir.
+- **Token estimator accuracy on CJK**: heuristic may under- or over-count; the warn threshold (200k default) has slack. If accuracy proves insufficient post-merge, swap the implementation behind `text/tokenizer.ts` without touching consumers.
+- **Ranker tier weighting must not regress existing test snapshots**: ranker tests use fixture vaults where every page is implicitly `tier: supporting` (the default). The new weighting term must be neutral when all pages carry the default tier. Plan: tier weight multiplier defaults to `1.0` for `supporting`.
+- **Lint --consolidate side-effects on user vaults**: requires `--apply` flag and emits a dry-run diff first. Document the diff format in `lint.ts` so operators can review before applying.
diff --git a/docs/brainstorm/vault-care-bundle/plan.md b/docs/brainstorm/vault-care-bundle/plan.md
new file mode 100644
index 00000000..7280a332
--- /dev/null
+++ b/docs/brainstorm/vault-care-bundle/plan.md
@@ -0,0 +1,144 @@
+# vault-care-bundle - implementation plan
+
+Eight atomic TDD units in the order the chosen variant requires. Each unit ends with a passing-test green bar and a conventional commit on `feat/vault-care-bundle`. The bundle ships as v0.10.15.
+
+## Tasks
+
+### Task 1: F7 - NFKC + casefold dedup normaliser (`text/normalize.ts`)
+
+- **Files**:
+ - new: `src/core/brain/text/normalize.ts`
+ - modified: `src/core/brain/dedup-hash.ts` (swap inline `normalize("NFC")` → call `normalizeForDedup`)
+ - new tests: `tests/core/brain/text/normalize.test.ts`, `tests/core/brain/dedup-hash-unicode.test.ts`
+- **Acceptance**: `bun test tests/core/brain/text/normalize.test.ts tests/core/brain/dedup-hash-unicode.test.ts` green. Regression cases: fullwidth `A` vs halfwidth `A` produce identical hash; CJK `テスト` survives normalisation without collapsing to empty string; uppercase / lowercase variants of the same principle produce identical hash. All existing dedup tests still pass.
+- **Depends on**: none.
+- **Commit**: `feat(brain): unicode-aware dedup normalisation (NFKC + casefold)`
+
+### Task 2: F1 - confidence + lifecycle frontmatter atoms (`page-meta/`)
+
+- **Files**:
+ - new: `src/core/brain/page-meta/lifecycle.ts`, `src/core/brain/page-meta/confidence.ts`
+ - modified: `src/core/brain/preference.ts` (emit `_lifecycle` next to `_confidence`)
+ - modified: `src/cli/brain/verbs/migrate-frontmatter.ts` (add `_lifecycle: stable` to legacy pages)
+ - new tests: `tests/core/brain/page-meta/lifecycle.test.ts`, augment `tests/cli/brain/migrate-frontmatter.test.ts`
+- **Acceptance**: New preferences carry `_lifecycle: stable` by default. Migration adds the field to legacy pages idempotently (byte-identical second run). `isStale()` returns true for `lifecycle: stable` pages older than 180 days. All existing preference tests still pass.
+- **Depends on**: none.
+- **Commit**: `feat(brain): per-page confidence and lifecycle frontmatter`
+
+### Task 3: F2 - tier frontmatter + ranker weighting
+
+- **Files**:
+ - new: `src/core/brain/page-meta/tier.ts`
+ - modified: `src/core/search/ranker.ts` (extend `RankerInputs` with `tierByDoc`, apply `tierWeight()` multiplier in `rankResults`)
+ - modified: `src/core/brain/preference.ts` (accept `tier?` input, default `supporting`)
+ - modified: `src/cli/brain/verbs/migrate-frontmatter.ts` (add `tier: supporting` to legacy pages)
+ - new tests: `tests/core/brain/page-meta/tier.test.ts`, `tests/core/search/ranker-tier.test.ts`
+- **Acceptance**: Ranker multiplies the candidate score by `tierWeight()` (core=1.4, supporting=1.0, peripheral=0.6). When every input is `supporting` (default) the ranker output is bit-identical to pre-change behaviour. Tests pin both regressions.
+- **Depends on**: Task 2 (migrate sweep shares the same verb).
+- **Commit**: `feat(brain): page importance tier with ranker weighting`
+
+### Task 4: F3 - page-level dedup + wikilink patcher
+
+- **Files**:
+ - new: `src/core/brain/page-meta/page-id.ts`
+ - new: `src/core/brain/page-dedup.ts`
+ - new: `src/cli/brain/verbs/page-dedup.ts`
+ - modified: `src/cli/brain/verbs/index.ts` (register verb)
+ - modified: `src/cli/brain/verbs/migrate-frontmatter.ts` (recognise existing `merged_into:` pointers)
+ - new tests: `tests/core/brain/page-meta/page-id.test.ts`, `tests/core/brain/page-dedup.test.ts`, `tests/cli/brain/page-dedup.test.ts`
+- **Acceptance**: `findDuplicateCandidates` reports near-dup pairs using `normalizeForDedup` on titles + body fingerprint. `mergePage(secondary, canonical)` writes `merged_into: <id>` to secondary and rewrites every `[[secondary-title]]` reference across the vault. Cycle detection trips at depth 5. Dry-run mode emits diff without touching files.
+- **Depends on**: Task 1 (uses `normalizeForDedup`), Task 2 (skips pages with `lifecycle: archived`).
+- **Commit**: `feat(brain): page-level dedup with wikilink repatching`
+
+### Task 5: F5 - token footprint monitor
+
+- **Files**:
+ - new: `src/core/brain/text/tokenizer.ts`
+ - new: `src/core/brain/token-footprint.ts`
+ - new: `src/cli/brain/verbs/token-footprint.ts`
+ - modified: `src/cli/brain/verbs/index.ts` (register verb)
+ - modified: `src/core/brain/digest.ts` (add `tokenFootprint` section to digest payload)
+ - new tests: `tests/core/brain/text/tokenizer.test.ts`, `tests/core/brain/token-footprint.test.ts`, `tests/cli/brain/token-footprint.test.ts`
+- **Acceptance**: `estimateTokens()` returns `ceil(utf8_bytes / 4)`; deterministic, language-agnostic, no script-specific branching. `computeTokenFootprint(vault)` returns per-category counts (preferences, signals, retired, daily, other). Digest output includes `Token footprint` section with `total`, `byCategory`, `exceededWarnThreshold` boolean. Default threshold 200_000, overridable via `BRAIN_TOKEN_WARN_THRESHOLD` env var.
+- **Depends on**: none (introduces tokenizer that later tasks reuse).
+- **Commit**: `feat(brain): vault token footprint monitor`
+
+### Task 6: F6 - bounded-token context pack
+
+- **Files**:
+ - new: `src/core/brain/context-pack.ts`
+ - new: `src/cli/brain/verbs/context-pack.ts`
+ - modified: `src/cli/brain/verbs/index.ts` (register verb)
+ - modified: `src/mcp/brain-tools.ts` (register `brain_context_pack` MCP tool)
+ - new tests: `tests/core/brain/context-pack.test.ts`, `tests/cli/brain/context-pack.test.ts`, `tests/mcp/context-pack-tool.test.ts`
+- **Acceptance**: `packContext(vault, { maxTokens: 5000 })` returns a slice ordered by tier (core → supporting → peripheral) then by recency, stops adding pages when next page would exceed budget. Result payload includes `tokensUsed`, `pagesIncluded`, `pagesSkipped`. MCP tool exposes same with JSON-RPC shape consistent with existing `brain_context`.
+- **Depends on**: Task 3 (tier), Task 5 (tokenizer).
+- **Commit**: `feat(brain): brain_context_pack with token budget`
+
+### Task 7: F4 - self-healing lint --consolidate
+
+- **Files**:
+ - new: `src/core/brain/lint-consolidate.ts`
+ - new: `src/cli/brain/verbs/lint.ts`
+ - modified: `src/cli/brain/verbs/index.ts` (register verb)
+ - new tests: `tests/core/brain/lint-consolidate.test.ts`, `tests/cli/brain/lint.test.ts`
+- **Acceptance**: `o2b brain lint --consolidate` performs detection-only by default; emits a structured diff (`fixes`, `demotions`, `alias-normalisations`). `--apply` performs writes idempotently (second run = no-op). Lifecycle demotion only triggers on `stable` + age > 180 days + zero recent reapplies. Broken-link fix follows `merged_into` chains. Tag aliases normalise via `normalizeForDedup`.
+- **Depends on**: Task 1 (normaliser), Task 2 (lifecycle), Task 4 (page-id resolution).
+- **Commit**: `feat(brain): self-healing lint --consolidate with dry-run`
+
+### Task 8: F8 - ranked maintenance action list
+
+- **Files**:
+ - new: `src/core/brain/maintenance/action-scorer.ts`
+ - modified: `src/core/brain/digest.ts` (add `## Actions` section)
+ - modified: `src/core/brain/doctor.ts` (emit `suggested_actions:` block)
+ - new tests: `tests/core/brain/maintenance/action-scorer.test.ts`, `tests/core/brain/digest-actions.test.ts`
+- **Acceptance**: Action scorer takes inputs `{ orphans, staleByLifecycle, dedupCandidates, tokenFootprintExceeded, brokenLinks }` and returns top-N actions ranked by impact score. Each action has `id`, `title`, `impact` (number), `category`, `target` (path or id). Empty input → empty list (no spurious entries). Digest renders the top 10 as a Markdown bullet list; doctor surfaces same as YAML block.
+- **Depends on**: Task 4 (dedup candidates), Task 5 (footprint), Task 7 (broken links via lint).
+- **Commit**: `feat(brain): ranked maintenance action list in digest and doctor`
+
+## Post-implementation tasks
+
+### Task 9: Phase 3 self-review pass
+
+- Run `superpowers:requesting-code-review` on the branch; apply auto-fix findings.
+- Run `superpowers:verification-before-completion`; capture command output for each "feature works" claim.
+- Commit: `chore: address self-review findings` (only if anything needed fixing).
+
+### Task 10: Phase 4 QA
+
+- `bun test` - full suite green.
+- `bun run typecheck` - no errors.
+- `bun run lint` - clean.
+- Manual smoke: run each new CLI verb against a tmpdir vault, confirm output shape.
+
+### Task 11: Phase 5 docs
+
+- `README.md` - new "Vault care" paragraph in the features list.
+- `CHANGELOG.md` - new `[0.10.15]` entry with capability-first summary + Added / Changed / Notes.
+- No `[Unreleased]` placeholder.
+
+### Task 12: Phase 6 PR + auto-merge
+
+- Stop-point: operator confirms diff summary.
+- `git push -u origin feat/vault-care-bundle`.
+- `gh pr create` with mermaid diagram + capability summary.
+- `gh pr merge --auto --squash --delete-branch`.
+
+### Task 13: Phase 7-8 CodeRabbit + merge wait
+
+- Apply CodeRabbit findings if any; commit `fix: address CodeRabbit review feedback`.
+- Poll `gh pr view --json state,reviewDecision` until `MERGED`.
+
+### Task 14: Phase 9 release
+
+- Bump `package.json` 0.10.14 → 0.10.15.
+- Generate excalidraw → PNG: three-layer diagram showing atoms → helpers → consumers.
+- Stop-point: operator confirms release title + body.
+- `gh release create v0.10.15` with PNG + excalidraw assets.
+
+### Task 15: Phase 10 tracker tick + kanban close
+
+- Add entry #38 to `/root/vault/Projects/OpenSecondBrain/Features/_summary.md`.
+- `brain_note`: release shipped.
+- Direct SQL UPDATE on kanban DB: move `t_5de021f1`, `t_3d157e9b`, `t_e0d65daa`, `t_55bd528a`, `t_68e65e77`, `t_31c16ba2`, `t_2e7e3b8d`, `t_8dd35d10` from `triage` to `done` with `completed` events, summary referencing release URL.
diff --git a/docs/brainstorm/vault-care-bundle/variants.md b/docs/brainstorm/vault-care-bundle/variants.md
new file mode 100644
index 00000000..5cffa539
--- /dev/null
+++ b/docs/brainstorm/vault-care-bundle/variants.md
@@ -0,0 +1,109 @@
+# vault-care-bundle - brainstorm variants and decision audit
+
+Primary consultant: `claude` (Claude Code CLI), invoked via `claude -p` on 2026-05-25 with the prompt at `cli-output/prompt.md`. Raw output at `cli-output/claude.md`. Fallback consultant (`codex`) not invoked - primary returned 3 well-formed variants on the first run.
+
+## Variants verbatim
+
+### Variant 1: Layered foundation (schema → utilities → consumers)
+
+- **Approach**: Build three horizontal layers bottom-up: a `page-meta/` layer owning the new frontmatter atoms (lifecycle, tier, merged-pointer), a `text/` layer owning the deterministic helpers (NFKC+casefold normaliser, heuristic tokenizer, action-impact scorer), and the consumer layer that wires those into the ranker, digest, doctor, lint, context-pack, and footprint verbs. Strict DAG: consumers depend on layers, never on each other; one extended `migrate-frontmatter` pass covers all schema additions.
+- **Shared building blocks**:
+ - `src/core/brain/page-meta/lifecycle.ts` - `Lifecycle` enum, default resolver, staleness predicate (F1, F4, F8).
+ - `src/core/brain/page-meta/confidence.ts` - generalises today's `_confidence` to non-preference pages (F1).
+ - `src/core/brain/page-meta/tier.ts` - `Tier` enum, default `supporting`, tier-weight table (F2, F6, F8).
+ - `src/core/brain/page-meta/page-id.ts` - `merged_into` pointer + canonical resolver (F3, F4).
+ - `src/core/brain/text/normalize.ts` - NFKC + casefold dedup key (F7, F3).
+ - `src/core/brain/text/tokenizer.ts` - single heuristic token counter (F5, F6, F8).
+ - `src/core/brain/maintenance/action-scorer.ts` - impact-weighted action item builder (F8).
+ - Extension of the existing `migrate-frontmatter` verb to cover the new fields idempotently.
+- **Implementation order**:
+ 1. F7 - pure refactor of `dedup-hash.ts` to NFKC+casefold; unblocks F3 without schema churn.
+ 2. F1 - confidence + lifecycle frontmatter via `page-meta/` and `migrate-frontmatter`.
+ 3. F2 - tier frontmatter + ranker hook in `src/core/search/ranker.ts`.
+ 4. F3 - page dedup, consuming F7 normalisation, F1 lifecycle (skip deprecated/archived), and the `merged_into` pointer.
+ 5. F5 - token footprint verb + digest section, introducing the shared tokenizer.
+ 6. F6 - `brain_context_pack` MCP tool + CLI verb, composing tier + lifecycle + tokenizer.
+ 7. F4 - `o2b brain lint --consolidate` with dry-run, using lifecycle for demotion and page-id for orphan-merge hints.
+ 8. F8 - ranked action list, composing every prior layer through `action-scorer.ts` and surfacing in digest + doctor.
+- **Trade-offs**:
+ - Pros: Every shared concept has one owner file; future maintenance features add a peer module instead of recutting an abstraction.
+ - Pros: Tests mirror layers (`tests/core/brain/page-meta/*`, `tests/core/brain/text/*`), so per-tool tests stay small.
+ - Pros: One migration sweep covers F1+F2+F3 pointer; old pages keep parsing with default values.
+ - Cons: Touches more consumer files in one PR (ranker, digest, doctor, dream, inline-scan, sessions/import), so the diff feels wide even though each touch is small.
+ - Cons: Some readers have to chase logic across `page-meta/` and the consumer, instead of seeing it inline.
+- **Complexity**: medium
+- **Risk**: low
+
+### Variant 2: Single maintenance index (one scan, many views)
+
+- **Approach**: Introduce a `MaintenanceIndex` that walks the vault once (reusing `inline-scan` + `backlinks` + `explorer` outputs) and exposes typed views - `byTier`, `byLifecycle`, `tokenByCategory`, `dedupCandidates`, `orphans`, `staleForDemotion`. Every consumer (digest, doctor, lint, context-pack, footprint, action-list) reads from this index instead of re-scanning. The schema additions and normalisation helper feed the index; the eight features become "another view + thin verb" on top.
+- **Shared building blocks**:
+ - `src/core/brain/maintenance-index/types.ts` - `Lifecycle`, `Tier`, `PageMeta`, `TokenCount`, `DedupCandidate`, `ActionItem` (one schema home).
+ - `src/core/brain/maintenance-index/builder.ts` - single-pass scanner producing the cached index.
+ - `src/core/brain/maintenance-index/views.ts` - typed accessors per concern (F2, F3, F4, F5, F6, F8 all consume this).
+ - `src/core/brain/text/normalize.ts` - NFKC + casefold helper (F7, also feeds dedup-hash + index).
+ - Action-scorer is a function over the index, not its own module.
+- **Implementation order**:
+ 1. F1 + F2 together - lifecycle + tier added to `FrontmatterMap` and `migrate-frontmatter`; both are pure schema bumps.
+ 2. F7 - NFKC + casefold in `text/normalize.ts`, called from `dedup-hash.ts`.
+ 3. Maintenance-index skeleton - scanner + empty views.
+ 4. F5 - first view (`tokenByCategory`) wired to a CLI verb + digest section.
+ 5. F3 - `dedupCandidates` view, `merged_into` writer, wikilink patcher.
+ 6. F4 - `lint --consolidate` composing `orphans` + `staleForDemotion` + `dedupCandidates` with `--dry-run`/`--apply`.
+ 7. F6 - `context_pack` over the index, ordered by tier then recency under a token budget.
+ 8. F8 - pure function over the index, replacing the vague "Recommendation" string in digest + doctor.
+- **Trade-offs**:
+ - Pros: One canonical scan per command - measurable perf win for larger vaults and fewer race-windows against the watcher.
+ - Pros: Tests concentrate on one well-typed module plus thin per-feature wrappers; views are easy to snapshot.
+ - Pros: Future maintenance features cost "one new view + one new action term".
+ - Cons: God-module risk - `maintenance-index/` accumulates concerns and needs strict sub-file discipline.
+ - Cons: Forces every feature through the same abstraction even where (F7) it is overkill, making early commits read as scaffolding.
+ - Cons: Sequential ordering - F3-F8 all wait on the index being non-trivial, so parallelisation inside the PR is limited.
+- **Complexity**: medium
+- **Risk**: medium
+
+### Variant 3: Per-feature modules with minimal shared atoms
+
+- **Approach**: Each feature ships as a focused module under `src/core/brain/<feature>.ts` plus its CLI verb file; the only shared surface is a tiny `page-meta/types.ts` (Lifecycle, Tier enums), one normaliser, and one tokenizer helper. Feature files compose existing primitives (`inline-scan`, `backlinks`, `explorer`) directly rather than through a new index or scorer module.
+- **Shared building blocks**:
+ - `src/core/brain/page-meta/types.ts` - `Lifecycle`, `Tier` enums + default/parse helpers (F1, F2, F3, F4, F8).
+ - `src/core/brain/text/normalize.ts` - NFKC + casefold helper (F7, used by F3).
+ - `src/core/brain/text/tokenizer.ts` - heuristic token counter (F5, F6, F8 each call directly).
+ - Per-feature modules: `lifecycle-confidence.ts`, `tier.ts`, `page-dedup.ts`, `lint-consolidate.ts`, `token-footprint.ts`, `context-pack.ts`, `maintenance-actions.ts`.
+ - No central maintenance index; no central action-scorer module.
+- **Implementation order**:
+ 1. F7 - refactor `dedup-hash.ts` to NFKC + casefold; isolated.
+ 2. F1 - confidence + lifecycle frontmatter + migrate-frontmatter.
+ 3. F2 - tier frontmatter + ranker hook.
+ 4. F5 - token footprint verb + digest section.
+ 5. F3 - page dedup using F7 normalisation and F1 lifecycle gating.
+ 6. F6 - context-pack using F2 tier + tokenizer.
+ 7. F4 - lint --consolidate using F1 lifecycle and F3 dedup hints.
+ 8. F8 - action list re-deriving inputs from each feature module.
+- **Trade-offs**:
+ - Pros: Smallest, most local diffs per feature; reviewers can read one file per feature; reverts stay surgical.
+ - Pros: Steps 1-5 are largely independent - subagent dispatch is straightforward.
+ - Pros: Lowest cognitive load to land the first few features quickly.
+ - Cons: Tokenization, lifecycle classification, tier scoring get inlined into multiple callers - future schema changes touch many files.
+ - Cons: F8 becomes a fat module that re-walks data prior features already computed; wasted vault walks per invocation.
+ - Cons: Test surface fragments; no single canonical maintenance view to snapshot-test, so coverage relies on disciplined per-verb tests.
+- **Complexity**: small per file, medium overall
+- **Risk**: medium (drift risk across future releases)
+
+## Consultant's recommendation
+
+Variant 1.
+
+> The eight features cleanly split into two horizontal concerns (frontmatter atoms, deterministic text/scoring helpers) feeding a vertical layer of mostly-additive consumer changes - a layered shape captures that without paying for the god-index of Variant 2 or accepting the duplication and drift risk of Variant 3. It also matches established OSB conventions: per-concern files alongside `backlinks.ts` and `explorer.ts`, one `migrate-frontmatter` sweep for the new fields, additive MCP surface, and consumer hooks (`ranker.ts`, `digest.ts`, `doctor.ts`) edited in narrow ways. Crucially, it keeps the door open for future maintenance features (freshness signal, tag taxonomy, vault-size policies) by adding a peer file under `page-meta/` or `text/` instead of re-cutting the schema.
+
+## Orchestrator decision
+
+**Accepted: Variant 1.**
+
+Rationale matches the consultant's. Three additional project-specific reasons reinforce the choice over the others:
+
+1. Variant 2's `MaintenanceIndex` would re-architect how `digest.ts` and `doctor.ts` source their data. v0.10.14 just added the per-doctor backlink-index path and v0.10.13 added the codegraph partner check - introducing another central index in the same area, two releases in a row, would force readers to re-orient the mental model again. The peer-file pattern stays familiar.
+2. Variant 3 inlines `tokenWeight`, `tierWeight`, `lifecycleStaleness` logic into multiple consumers. The codebase already paid for the v0.10.5-v0.10.10 work to consolidate brain status / confidence logic in single owner files. Going back to per-consumer duplication on a fresh axis would regress that work.
+3. Variant 1's per-layer test directory (`tests/core/brain/page-meta/*`, `tests/core/brain/text/*`) matches the existing `tests/core/brain/sessions/` and `tests/core/search/embeddings/` mirroring pattern, so reviewers can locate tests without searching.
+
+No deviations from the consultant's variant required. The design-doc (`design.md`) captures one project-specific refinement that does not change the architecture: generalise the existing `_confidence` field rather than introduce a parallel `confidence:` axis, to stay byte-compatible with current preference YAML.
diff --git a/src/cli/brain.ts b/src/cli/brain.ts
index 61e8783d..5861f891 100644
--- a/src/cli/brain.ts
+++ b/src/cli/brain.ts
@@ -34,6 +34,11 @@ import {
cmdBrainScanInline,
cmdBrainImportSession,
cmdBrainImportClaudeMemory,
+ cmdBrainPageDedup,
+ cmdBrainTokenFootprint,
+ cmdBrainContextPack,
+ cmdBrainLint,
+ cmdBrainActions,
} from "./brain/verbs/index.ts";
export async function handleBrainSubcommand(argv: ReadonlyArray<string>): Promise<number> {
@@ -78,6 +83,11 @@ export async function handleBrainSubcommand(argv: ReadonlyArray<string>): Promis
case "upgrade": return await cmdBrainUpgrade(rest);
case "export": return await cmdBrainExport(rest);
case "explorer": return await cmdBrainExplorer(rest);
+ case "page-dedup": return await cmdBrainPageDedup(rest);
+ case "token-footprint": return await cmdBrainTokenFootprint(rest);
+ case "context-pack": return await cmdBrainContextPack(rest);
+ case "lint": return await cmdBrainLint(rest);
+ case "actions": return await cmdBrainActions(rest);
default:
process.stderr.write(`error: unknown brain verb: ${verb}\n`);
process.stdout.write(BRAIN_HELP);
diff --git a/src/cli/brain/help-text.ts b/src/cli/brain/help-text.ts
index 626d9bca..9cc80aac 100644
--- a/src/cli/brain/help-text.ts
+++ b/src/cli/brain/help-text.ts
@@ -36,6 +36,11 @@ Brain verbs (observing memory):
scan-inline Capture @osb markers from vault markdown files (Daily/, project notes, etc.)
import-session Replay signals from a Claude/Codex/Hermes session .jsonl (or directory)
import-claude-memory Import metadata.type:feedback MEMORY entries as confirmed preferences
+ page-dedup Detect (and optionally merge) near-duplicate vault pages
+ token-footprint Report per-category vault token size with a warn threshold
+ context-pack Return a tier-then-recency vault slice under a token budget
+ lint Self-healing structural checks (--consolidate); --apply to write
+ actions Ranked maintenance action list (dedup + lint + footprint)
Common flags:
--vault <path> Override the configured vault
@@ -199,4 +204,42 @@ export const VERB_HELP: Record<string, string> = {
"<path>. Without --force, refuses to overwrite an existing file.\n" +
"Zero backend, no LLM, no network access. The page consumes a\n" +
"prebuilt JSON graph; it does not parse vault Markdown client-side.\n",
+ "page-dedup":
+ "usage: o2b brain page-dedup [--apply] [--yes] [--vault <path>] [--json]\n" +
+ "Detect near-duplicate vault pages by normalised topic+principle key.\n" +
+ "Dry-run by default: lists each cluster with its canonical (oldest)\n" +
+ "and secondary ids. --apply writes `merged_into:` on every secondary\n" +
+ "and rewrites `[[secondary]]` wikilinks across the vault to the\n" +
+ "canonical. Requires --yes in non-interactive mode (--json or non-TTY).\n",
+ "token-footprint":
+ "usage: o2b brain token-footprint [--warn-threshold <n>] [--vault <path>] [--json]\n" +
+ "Report per-category vault token size (preferences, retired, inbox,\n" +
+ "processed, log, other) using the language-agnostic\n" +
+ "`ceil(utf8_bytes / 4)` heuristic. Flags vaults that cross the warn\n" +
+ "threshold (default 200000; override via --warn-threshold or the\n" +
+ "BRAIN_TOKEN_WARN_THRESHOLD env var).\n",
+ "context-pack":
+ "usage: o2b brain context-pack --max-tokens <n> [--query <q>] [--vault <path>] [--json]\n" +
+ "Return the highest-tier, most recent vault slice that fits under\n" +
+ "<n> tokens. Items ordered core → supporting → peripheral, then\n" +
+ "newest first. Stops adding pages when the next page would exceed\n" +
+ "the budget. --query <q> filters by NFKC+casefold substring match\n" +
+ "on topic + principle.\n",
+ lint:
+ "usage: o2b brain lint --consolidate [--apply] [--yes] [--vault <path>] [--json]\n" +
+ "Self-healing structural lint. Dry-run by default; --apply writes\n" +
+ "the smallest possible fix per finding. Two operations:\n" +
+ " fix-merged-link rewrite wikilinks pointing at a page that\n" +
+ " carries `merged_into:` to the canonical.\n" +
+ " demote-stale-stable demote `_lifecycle: stable` preferences\n" +
+ " older than 180 days with no recent\n" +
+ " evidence to `_lifecycle: draft`.\n" +
+ "Requires --yes in non-interactive mode (--json or non-TTY).\n",
+ actions:
+ "usage: o2b brain actions [--top-n <n>] [--vault <path>] [--json]\n" +
+ "Ranked maintenance action list. Aggregates page-dedup, lint\n" +
+ "(dry-run), and token-footprint signals, scores each candidate\n" +
+ "action by impact (dedup count × weight, staleness × age,\n" +
+ "broken-link count, token-footprint excess), and prints the top N\n" +
+ "(default 10) sorted by impact descending. Read-only.\n",
};
diff --git a/src/cli/brain/verbs/actions.ts b/src/cli/brain/verbs/actions.ts
new file mode 100644
index 00000000..90ef6944
--- /dev/null
+++ b/src/cli/brain/verbs/actions.ts
@@ -0,0 +1,77 @@
+/**
+ * `o2b brain actions` - ranked maintenance action list. Aggregates
+ * inputs from {@link findDuplicateCandidates}, {@link lintConsolidate}
+ * (dry-run), and {@link computeTokenFootprint}, runs them through
+ * {@link scoreActions}, and emits the top-N actionable items ordered
+ * by impact descending.
+ */
+
+import { defaultConfigPath } from "../../../core/config.ts";
+import { findDuplicateCandidates } from "../../../core/brain/page-dedup.ts";
+import { lintConsolidate } from "../../../core/brain/lint-consolidate.ts";
+import { computeTokenFootprint } from "../../../core/brain/token-footprint.ts";
+import {
+ scoreActions,
+ type ActionInputs,
+} from "../../../core/brain/maintenance/action-scorer.ts";
+import { parse, fail, okJson, resolveBrainVault } from "../helpers.ts";
+
+export async function cmdBrainActions(argv: string[]): Promise<number> {
+ const { flags } = parse(argv, {
+ vault: { type: "string" },
+ json: { type: "boolean" },
+ "top-n": { type: "string" },
+ });
+ const config = defaultConfigPath();
+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);
+ const topNRaw = flags["top-n"] as string | undefined;
+ let topN = 10;
+ if (topNRaw !== undefined) {
+ const parsed = Number(topNRaw);
+ if (!Number.isInteger(parsed) || parsed <= 0) {
+ return fail(
+ `brain actions: --top-n must be a positive integer; got ${topNRaw}`,
+ );
+ }
+ topN = parsed;
+ }
+
+ const dedup = findDuplicateCandidates(vault);
+ const lint = lintConsolidate(vault, { apply: false });
+ const footprint = computeTokenFootprint(vault);
+
+ const inputs: ActionInputs = {
+ dedupCandidates: dedup.candidates.map((c) => ({
+ canonicalId: c.canonical.id,
+ secondaryCount: c.secondaries.length,
+ })),
+ staleByLifecycle: lint.demotions.map((d) => ({
+ id: d.id,
+ ageDays: d.ageDays,
+ })),
+ brokenLinks: lint.fixes.map((f) => ({ path: f.path, from: f.from })),
+ tokenFootprint: {
+ total: footprint.total,
+ warnThreshold: footprint.warnThreshold,
+ },
+ };
+
+ const items = scoreActions(inputs, { topN });
+
+ if (flags["json"]) {
+ okJson({ items });
+ return 0;
+ }
+
+ if (items.length === 0) {
+ process.stdout.write("no maintenance actions queued.\n");
+ return 0;
+ }
+ process.stdout.write(`top ${items.length} maintenance action(s):\n`);
+ for (const it of items) {
+ process.stdout.write(
+ ` [${it.category.padEnd(15)}] impact=${String(it.impact).padStart(4)} ${it.title}\n`,
+ );
+ }
+ return 0;
+}
diff --git a/src/cli/brain/verbs/context-pack.ts b/src/cli/brain/verbs/context-pack.ts
new file mode 100644
index 00000000..9bba34d8
--- /dev/null
+++ b/src/cli/brain/verbs/context-pack.ts
@@ -0,0 +1,61 @@
+/**
+ * `o2b brain context-pack` - return the highest-tier, most recent
+ * vault slice that fits under a caller-specified token budget.
+ * Intended for agents priming a context window without manual page
+ * curation. `--query <q>` adds a case/Unicode-insensitive substring
+ * filter on topic + principle.
+ */
+
+import { defaultConfigPath } from "../../../core/config.ts";
+import { packContext } from "../../../core/brain/context-pack.ts";
+import { parse, fail, okJson, resolveBrainVault } from "../helpers.ts";
+
+export async function cmdBrainContextPack(argv: string[]): Promise<number> {
+ const { flags } = parse(argv, {
+ vault: { type: "string" },
+ json: { type: "boolean" },
+ "max-tokens": { type: "string" },
+ query: { type: "string" },
+ });
+ const config = defaultConfigPath();
+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);
+
+ const maxTokensRaw = flags["max-tokens"] as string | undefined;
+ if (!maxTokensRaw) {
+ return fail("brain context-pack: --max-tokens <n> is required");
+ }
+ // Strict integer parsing - `Number()` rejects partial numeric
+ // strings like "12abc" that `parseInt` would silently accept.
+ const maxTokens = Number(maxTokensRaw);
+ if (!Number.isInteger(maxTokens) || maxTokens <= 0) {
+ return fail(`brain context-pack: --max-tokens must be a positive integer; got ${maxTokensRaw}`);
+ }
+
+ const report = packContext(vault, {
+ maxTokens,
+ ...(flags["query"] ? { query: flags["query"] as string } : {}),
+ });
+
+ if (flags["json"]) {
+ okJson({
+ max_tokens: report.maxTokens,
+ tokens_used: report.tokensUsed,
+ items: report.items.map((i) => ({
+ id: i.id,
+ path: i.path,
+ tier: i.tier,
+ tokens: i.tokens,
+ })),
+ skipped: report.skipped,
+ });
+ return 0;
+ }
+
+ process.stdout.write(`tokens used: ${report.tokensUsed} / ${report.maxTokens}\n`);
+ process.stdout.write(`pages included: ${report.items.length}\n`);
+ process.stdout.write(`pages skipped: ${report.skipped.length}\n\n`);
+ for (const i of report.items) {
+ process.stdout.write(`[${i.tier}] ${i.id} (${i.tokens} tokens)\n`);
+ }
+ return 0;
+}
diff --git a/src/cli/brain/verbs/index.ts b/src/cli/brain/verbs/index.ts
index d92832ba..ccfd27eb 100644
--- a/src/cli/brain/verbs/index.ts
+++ b/src/cli/brain/verbs/index.ts
@@ -21,3 +21,8 @@ export { cmdBrainMigrateFrontmatter } from "./migrate-frontmatter.ts";
export { cmdBrainScanInline } from "./scan-inline.ts";
export { cmdBrainImportSession } from "./import-session.ts";
export { cmdBrainImportClaudeMemory } from "./import-claude-memory.ts";
+export { cmdBrainPageDedup } from "./page-dedup.ts";
+export { cmdBrainTokenFootprint } from "./token-footprint.ts";
+export { cmdBrainContextPack } from "./context-pack.ts";
+export { cmdBrainLint } from "./lint.ts";
+export { cmdBrainActions } from "./actions.ts";
diff --git a/src/cli/brain/verbs/lint.ts b/src/cli/brain/verbs/lint.ts
new file mode 100644
index 00000000..3dc149eb
--- /dev/null
+++ b/src/cli/brain/verbs/lint.ts
@@ -0,0 +1,61 @@
+/**
+ * `o2b brain lint --consolidate` - read-only structural drift scan
+ * with optional `--apply` mode that rewrites the smallest possible
+ * fix per finding.
+ */
+
+import { defaultConfigPath } from "../../../core/config.ts";
+import { lintConsolidate } from "../../../core/brain/lint-consolidate.ts";
+import { parse, fail, okJson, resolveBrainVault } from "../helpers.ts";
+
+export async function cmdBrainLint(argv: string[]): Promise<number> {
+ const { flags } = parse(argv, {
+ vault: { type: "string" },
+ consolidate: { type: "boolean" },
+ apply: { type: "boolean" },
+ yes: { type: "boolean" },
+ json: { type: "boolean" },
+ });
+ const config = defaultConfigPath();
+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);
+
+ if (!flags["consolidate"]) {
+ return fail("brain lint requires --consolidate (no other modes yet)");
+ }
+
+ const apply = Boolean(flags["apply"]);
+ if (apply && !flags["yes"] && (flags["json"] || !process.stdin.isTTY)) {
+ return fail("brain lint --apply requires --yes in non-interactive mode");
+ }
+
+ const report = lintConsolidate(vault, { apply });
+
+ if (flags["json"]) {
+ okJson({
+ scanned: report.scanned,
+ applied: report.applied,
+ files_written: report.filesWritten,
+ fixes: report.fixes,
+ demotions: report.demotions,
+ });
+ return 0;
+ }
+
+ process.stdout.write(
+ `scanned: ${report.scanned} file(s); ${report.applied ? "apply" : "dry-run"}\n`,
+ );
+ process.stdout.write(`fixes: ${report.fixes.length}\n`);
+ for (const f of report.fixes) {
+ process.stdout.write(` ${f.path}: [[${f.from}]] -> [[${f.to}]]\n`);
+ }
+ process.stdout.write(`demotions: ${report.demotions.length}\n`);
+ for (const d of report.demotions) {
+ process.stdout.write(` ${d.id} (age=${d.ageDays}d) -> draft\n`);
+ }
+ if (report.applied) {
+ process.stdout.write(`files written: ${report.filesWritten}\n`);
+ } else if (report.fixes.length + report.demotions.length > 0) {
+ process.stdout.write("\nre-run with --apply --yes to write changes.\n");
+ }
+ return 0;
+}
diff --git a/src/cli/brain/verbs/page-dedup.ts b/src/cli/brain/verbs/page-dedup.ts
new file mode 100644
index 00000000..3a76d11a
--- /dev/null
+++ b/src/cli/brain/verbs/page-dedup.ts
@@ -0,0 +1,89 @@
+/**
+ * `o2b brain page-dedup` - scan the vault for pages that share a
+ * normalised dedup key and (optionally) merge them.
+ *
+ * Default mode is read-only listing. `--apply` performs the merge
+ * for every reported candidate: writes `merged_into:` on each
+ * secondary and rewrites `[[<secondary>]]` references across the
+ * vault to point at the canonical page.
+ */
+
+import { defaultConfigPath } from "../../../core/config.ts";
+import {
+ findDuplicateCandidates,
+ mergePage,
+} from "../../../core/brain/page-dedup.ts";
+import { parse, fail, okJson, resolveBrainVault } from "../helpers.ts";
+
+export async function cmdBrainPageDedup(argv: string[]): Promise<number> {
+ const { flags } = parse(argv, {
+ vault: { type: "string" },
+ apply: { type: "boolean" },
+ json: { type: "boolean" },
+ yes: { type: "boolean" },
+ });
+ const config = defaultConfigPath();
+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);
+
+ const apply = Boolean(flags["apply"]);
+ if (apply && !flags["yes"] && (flags["json"] || !process.stdin.isTTY)) {
+ return fail(
+ "brain page-dedup --apply requires --yes in non-interactive mode",
+ );
+ }
+
+ const report = findDuplicateCandidates(vault);
+
+ if (!apply) {
+ if (flags["json"]) {
+ okJson({
+ scanned: report.scanned,
+ candidates: report.candidates.map((c) => ({
+ key: c.key,
+ canonical: c.canonical.id,
+ secondaries: c.secondaries.map((s) => s.id),
+ })),
+ });
+ return 0;
+ }
+ process.stdout.write(`pages scanned: ${report.scanned}\n`);
+ process.stdout.write(`duplicate clusters: ${report.candidates.length}\n`);
+ for (const c of report.candidates) {
+ process.stdout.write(
+ `\ncanonical: ${c.canonical.id} (topic: ${c.canonical.topic})\n`,
+ );
+ for (const s of c.secondaries) {
+ process.stdout.write(` -> ${s.id}\n`);
+ }
+ }
+ if (report.candidates.length === 0) {
+ process.stdout.write("no duplicate clusters detected.\n");
+ } else {
+ process.stdout.write("\nre-run with --apply --yes to merge.\n");
+ }
+ return 0;
+ }
+
+ let mergedCount = 0;
+ let wikilinksTouched = 0;
+ for (const c of report.candidates) {
+ for (const s of c.secondaries) {
+ const res = mergePage(vault, s.id, c.canonical.id);
+ mergedCount++;
+ wikilinksTouched += res.wikilinksUpdated;
+ }
+ }
+
+ if (flags["json"]) {
+ okJson({
+ scanned: report.scanned,
+ clusters: report.candidates.length,
+ merged: mergedCount,
+ wikilinks_updated: wikilinksTouched,
+ });
+ return 0;
+ }
+ process.stdout.write(`merged ${mergedCount} page(s) into canonicals.\n`);
+ process.stdout.write(`wikilinks updated: ${wikilinksTouched}\n`);
+ return 0;
+}
diff --git a/src/cli/brain/verbs/token-footprint.ts b/src/cli/brain/verbs/token-footprint.ts
new file mode 100644
index 00000000..a2d309a3
--- /dev/null
+++ b/src/cli/brain/verbs/token-footprint.ts
@@ -0,0 +1,66 @@
+/**
+ * `o2b brain token-footprint` - report vault token size per category
+ * with an optional warn threshold. Default output is a one-line
+ * summary plus a per-category table; `--json` emits the full report
+ * for programmatic consumers (cron digests, dashboards).
+ */
+
+import { defaultConfigPath } from "../../../core/config.ts";
+import { computeTokenFootprint } from "../../../core/brain/token-footprint.ts";
+import { parse, fail, okJson, resolveBrainVault } from "../helpers.ts";
+
+export async function cmdBrainTokenFootprint(argv: string[]): Promise<number> {
+ const { flags } = parse(argv, {
+ vault: { type: "string" },
+ json: { type: "boolean" },
+ "warn-threshold": { type: "string" },
+ });
+ const config = defaultConfigPath();
+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);
+ const overrideRaw = flags["warn-threshold"] as string | undefined;
+ let warnThreshold: number | undefined;
+ if (overrideRaw !== undefined) {
+ const parsed = Number(overrideRaw);
+ if (!Number.isInteger(parsed) || parsed <= 0) {
+ return fail(
+ `brain token-footprint: --warn-threshold must be a positive integer; got ${overrideRaw}`,
+ );
+ }
+ warnThreshold = parsed;
+ }
+
+ const report = computeTokenFootprint(vault, {
+ ...(warnThreshold !== undefined ? { warnThreshold } : {}),
+ envWarnThreshold: process.env["BRAIN_TOKEN_WARN_THRESHOLD"],
+ });
+
+ if (flags["json"]) {
+ okJson({
+ total: report.total,
+ files: report.files,
+ warn_threshold: report.warnThreshold,
+ exceeded: report.exceeded,
+ by_category: report.byCategory.map((c) => ({
+ name: c.name,
+ tokens: c.tokens,
+ files: c.files,
+ })),
+ });
+ return 0;
+ }
+
+ process.stdout.write(
+ `total tokens: ${report.total} (across ${report.files} file(s))\n`,
+ );
+ process.stdout.write(`warn threshold: ${report.warnThreshold}\n`);
+ if (report.exceeded) {
+ process.stdout.write(`WARN: vault exceeds ${report.warnThreshold} tokens\n`);
+ }
+ process.stdout.write("\nby category:\n");
+ for (const c of report.byCategory) {
+ process.stdout.write(
+ ` ${c.name.padEnd(12)} ${String(c.tokens).padStart(10)} tokens (${c.files} file(s))\n`,
+ );
+ }
+ return 0;
+}
diff --git a/src/core/brain/context-pack.ts b/src/core/brain/context-pack.ts
new file mode 100644
index 00000000..11ec24dc
--- /dev/null
+++ b/src/core/brain/context-pack.ts
@@ -0,0 +1,177 @@
+/**
+ * Bounded-token vault slice. Returns the highest-tier, most recent
+ * pages that fit inside a caller-specified token budget so an agent
+ * can prime its context window without overflowing it.
+ *
+ * Ordering:
+ * 1. tier ascending importance: core → supporting → peripheral.
+ * 2. created_at descending (newest first).
+ * 3. id ascending (stable tie-break).
+ *
+ * The walker stops adding pages the moment the next candidate would
+ * push tokensUsed over `maxTokens`. Pages that would never fit alone
+ * are reported in `pagesSkipped` with their estimated cost.
+ */
+
+import {
+ existsSync,
+ readdirSync,
+ statSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import { parseFrontmatter } from "../vault.ts";
+import { brainDirs } from "./paths.ts";
+import { PAGE_TIER, readTier, type PageTier } from "./page-meta/tier.ts";
+import { estimateTokens } from "./text/tokenizer.ts";
+import { normalizeForDedup } from "./text/normalize.ts";
+
+const TIER_ORDER: ReadonlyArray<PageTier> = [
+ PAGE_TIER.core,
+ PAGE_TIER.supporting,
+ PAGE_TIER.peripheral,
+];
+
+export interface ContextPackItem {
+ readonly id: string;
+ readonly path: string;
+ readonly tier: PageTier;
+ readonly tokens: number;
+ readonly body: string;
+}
+
+export interface ContextPackSkipped {
+ readonly id: string;
+ readonly tokens: number;
+ readonly reason: "over-budget" | "filter-miss";
+}
+
+export interface ContextPackReport {
+ readonly maxTokens: number;
+ readonly tokensUsed: number;
+ readonly items: ReadonlyArray<ContextPackItem>;
+ readonly skipped: ReadonlyArray<ContextPackSkipped>;
+}
+
+export interface ContextPackOptions {
+ readonly maxTokens: number;
+ /** Optional case-insensitive substring filter on topic + principle. */
+ readonly query?: string;
+}
+
+interface Candidate {
+ readonly id: string;
+ readonly path: string;
+ readonly tier: PageTier;
+ readonly createdAtMs: number;
+ readonly topic: string;
+ readonly principle: string;
+ readonly body: string;
+ readonly tokens: number;
+}
+
+function collectCandidates(vault: string): Candidate[] {
+ const dirs = brainDirs(vault);
+ const out: Candidate[] = [];
+ for (const dir of [dirs.preferences, dirs.retired]) {
+ if (!existsSync(dir)) continue;
+ for (const name of readdirSync(dir)) {
+ if (!name.endsWith(".md")) continue;
+ const full = join(dir, name);
+ let meta: Record<string, unknown>;
+ let body: string;
+ try {
+ [meta, body] = parseFrontmatter(full);
+ } catch {
+ continue;
+ }
+ const id = typeof meta["id"] === "string" ? meta["id"] : name.replace(/\.md$/, "");
+ const tier = readTier(meta);
+ const created = typeof meta["created_at"] === "string" ? meta["created_at"] : "";
+ let fallbackMtimeMs = 0;
+ if (!created) {
+ try {
+ fallbackMtimeMs = statSync(full).mtimeMs;
+ } catch {
+ fallbackMtimeMs = 0;
+ }
+ }
+ const createdAtMs = created ? Date.parse(created) : fallbackMtimeMs;
+ const topic = typeof meta["topic"] === "string" ? meta["topic"] : "";
+ const principle = typeof meta["principle"] === "string" ? meta["principle"] : "";
+ // Token budget is computed against the body the pack actually
+ // emits, not the full file - frontmatter tokens are never
+ // returned to the caller, so charging them would under-fill
+ // the context window.
+ out.push({
+ id,
+ path: full,
+ tier,
+ createdAtMs: Number.isFinite(createdAtMs) ? createdAtMs : 0,
+ topic,
+ principle,
+ body,
+ tokens: estimateTokens(body),
+ });
+ }
+ }
+ return out;
+}
+
+export function packContext(
+ vault: string,
+ opts: ContextPackOptions,
+): ContextPackReport {
+ if (!Number.isFinite(opts.maxTokens) || opts.maxTokens <= 0) {
+ return Object.freeze({
+ maxTokens: 0,
+ tokensUsed: 0,
+ items: Object.freeze([]),
+ skipped: Object.freeze([]),
+ });
+ }
+ const query = opts.query
+ ? normalizeForDedup(opts.query)
+ : null;
+ const candidates = collectCandidates(vault);
+
+ candidates.sort((a, b) => {
+ const tierA = TIER_ORDER.indexOf(a.tier);
+ const tierB = TIER_ORDER.indexOf(b.tier);
+ if (tierA !== tierB) return tierA - tierB;
+ if (a.createdAtMs !== b.createdAtMs) return b.createdAtMs - a.createdAtMs;
+ return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+ });
+
+ const items: ContextPackItem[] = [];
+ const skipped: ContextPackSkipped[] = [];
+ let used = 0;
+ for (const c of candidates) {
+ if (query !== null) {
+ const haystack = normalizeForDedup(`${c.topic} ${c.principle}`);
+ if (!haystack.includes(query)) {
+ skipped.push({ id: c.id, tokens: c.tokens, reason: "filter-miss" });
+ continue;
+ }
+ }
+ if (used + c.tokens > opts.maxTokens) {
+ skipped.push({ id: c.id, tokens: c.tokens, reason: "over-budget" });
+ continue;
+ }
+ items.push({
+ id: c.id,
+ path: c.path,
+ tier: c.tier,
+ tokens: c.tokens,
+ body: c.body,
+ });
+ used += c.tokens;
+ }
+
+ return Object.freeze({
+ maxTokens: opts.maxTokens,
+ tokensUsed: used,
+ items: Object.freeze(items),
+ skipped: Object.freeze(skipped),
+ });
+}
diff --git a/src/core/brain/dedup-hash.ts b/src/core/brain/dedup-hash.ts
index dc687ed5..7bf99206 100644
--- a/src/core/brain/dedup-hash.ts
+++ b/src/core/brain/dedup-hash.ts
@@ -23,6 +23,7 @@ import { join } from "node:path";
import { parseFrontmatter } from "../vault.ts";
import { brainDirs } from "./paths.ts";
+import { normalizeForDedup } from "./text/normalize.ts";
export interface DedupHashInput {
readonly topic: string;
@@ -89,10 +90,10 @@ export function computeDedupHash(input: DedupHashInput): string {
// Use NUL as the field separator so a topic / principle containing
// any printable character can't collide with the next field's prefix.
const parts = [
- input.topic.trim(),
+ normalizeForDedup(input.topic.trim()),
input.signal,
- input.principle.normalize("NFC").trim().replace(/\s+/g, " "),
- (input.scope ?? "").trim(),
+ normalizeForDedup(input.principle.trim().replace(/\s+/g, " ")),
+ normalizeForDedup((input.scope ?? "").trim()),
];
return createHash("sha256").update(parts.join("\u0000")).digest("hex");
}
diff --git a/src/core/brain/digest.ts b/src/core/brain/digest.ts
index d3a28f46..96a2fcd1 100644
--- a/src/core/brain/digest.ts
+++ b/src/core/brain/digest.ts
@@ -43,6 +43,8 @@ import { computeAgentSummary, type AgentSummaryEntry } from "./digest-agent-summ
import { findMergeCandidates } from "./merge-candidates.ts";
import { computeMostApplied } from "./most-applied.ts";
import { brainDirs, vaultRelative } from "./paths.ts";
+import { collectMaintenanceActions } from "./maintenance/collect.ts";
+import type { ActionItem } from "./maintenance/action-scorer.ts";
import {
MOST_APPLIED_LIMIT_DEFAULT,
MOST_APPLIED_WINDOW_DAYS_DEFAULT,
@@ -263,6 +265,13 @@ export interface DigestJson {
* Independent of the window — reflects current vault state.
*/
readonly connection_health: DigestJsonConnectionHealth;
+ /**
+ * Ranked maintenance actions (v0.10.15). Aggregates page-dedup
+ * candidates, lint demotions / merged-link rewrites, and token
+ * footprint excess; deterministic ordering. Empty when nothing
+ * needs doing. Independent of the window.
+ */
+ readonly actions: ReadonlyArray<ActionItem>;
}
/**
@@ -319,6 +328,7 @@ export function renderDigest(
agent_summary: data.agent_summary,
most_applied: data.most_applied,
connection_health: data.connection_health,
+ actions: data.actions,
};
return Object.freeze({
content: JSON.stringify(payload, null, 2) + "\n",
@@ -347,6 +357,7 @@ interface DigestData {
readonly agent_summary: ReadonlyArray<AgentSummaryEntry>;
readonly most_applied: DigestJsonMostApplied;
readonly connection_health: DigestJsonConnectionHealth;
+ readonly actions: ReadonlyArray<ActionItem>;
}
function collectDigestData(
@@ -504,6 +515,7 @@ function collectDigestData(
agent_summary,
most_applied,
connection_health: computeConnectionHealth(vault, preferences),
+ actions: collectMaintenanceActions(vault),
};
}
@@ -993,6 +1005,16 @@ function renderMarkdown(
"",
);
}
+ // Ranked maintenance actions (v0.10.15). Same window-independent
+ // shape as connection-health: surface only when the scorer
+ // returned anything, so empty vaults stay quiet.
+ if (data.actions.length > 0) {
+ lines.push(`## Actions (${data.actions.length})`, "");
+ for (const a of data.actions) {
+ lines.push(`- [${a.category}] impact ${a.impact} — ${a.title}`);
+ }
+ lines.push("");
+ }
if (data.merge_suggestions.length > 0) {
lines.push(`## Merge suggestions (${data.merge_suggestions.length})`, "");
for (const item of data.merge_suggestions) {
diff --git a/src/core/brain/lint-consolidate.ts b/src/core/brain/lint-consolidate.ts
new file mode 100644
index 00000000..cece3e3f
--- /dev/null
+++ b/src/core/brain/lint-consolidate.ts
@@ -0,0 +1,260 @@
+/**
+ * Self-healing vault lint. Detects structural drift in Brain/* and,
+ * with `--apply`, applies the smallest possible fix.
+ *
+ * Two operations ship in v0.10.15:
+ * 1. `fix-merged-link` - wikilinks pointing at a page that carries
+ * `merged_into: <canonical>` get rewritten to `[[canonical]]`.
+ * This is the natural follow-up to a page-dedup merge so old
+ * log entries do not keep referencing the secondary.
+ * 2. `demote-stale-stable` - preferences with `_lifecycle: stable`,
+ * `created_at` older than the staleness cap, and no recent
+ * apply-evidence get marked for demotion to `_lifecycle: draft`.
+ * The signal is operator-actionable: the rule has aged out of
+ * the "trusted current" set without earning a verification.
+ *
+ * The function never mutates without `apply: true`. The diff shape
+ * is identical between dry-run and apply runs so a CI step can
+ * snapshot-test the report independently of writes.
+ */
+
+import {
+ existsSync,
+ readFileSync,
+ readdirSync,
+ statSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import { atomicWriteFileSync } from "../fs-atomic.ts";
+import { parseFrontmatter } from "../vault.ts";
+import { brainDirs } from "./paths.ts";
+import {
+ PAGE_LIFECYCLE,
+ PAGE_STALE_DAYS_DEFAULT,
+ ageDaysFromIso,
+ readLifecycle,
+} from "./page-meta/lifecycle.ts";
+import { readMergedInto } from "./page-meta/page-id.ts";
+
+export interface LintFix {
+ readonly kind: "fix-merged-link";
+ readonly path: string;
+ readonly from: string;
+ readonly to: string;
+}
+
+export interface LintDemotion {
+ readonly kind: "demote-stale-stable";
+ readonly id: string;
+ readonly path: string;
+ readonly ageDays: number;
+}
+
+export interface LintReport {
+ readonly scanned: number;
+ readonly fixes: ReadonlyArray<LintFix>;
+ readonly demotions: ReadonlyArray<LintDemotion>;
+ readonly applied: boolean;
+ readonly filesWritten: number;
+}
+
+export interface LintOptions {
+ readonly apply: boolean;
+ readonly now?: Date;
+ readonly staleDays?: number;
+}
+
+interface MergeMap {
+ /** secondary id → canonical id */
+ readonly forward: ReadonlyMap<string, string>;
+}
+
+function buildMergeMap(vault: string): MergeMap {
+ const forward = new Map<string, string>();
+ const dirs = brainDirs(vault);
+ for (const dir of [dirs.preferences, dirs.retired]) {
+ if (!existsSync(dir)) continue;
+ for (const name of readdirSync(dir)) {
+ if (!name.endsWith(".md")) continue;
+ const full = join(dir, name);
+ try {
+ const [meta] = parseFrontmatter(full);
+ const target = readMergedInto(meta);
+ if (target !== null) {
+ const id =
+ typeof meta["id"] === "string"
+ ? meta["id"]
+ : name.replace(/\.md$/, "");
+ forward.set(id, target);
+ }
+ } catch {
+ // ignore
+ }
+ }
+ }
+ return Object.freeze({ forward });
+}
+
+const WIKILINK_RE = /\[\[([^\]|#]+)([#|][^\]]*)?\]\]/g;
+
+function scanFileForMergedLinks(
+ path: string,
+ raw: string,
+ merge: MergeMap,
+): { fixes: LintFix[]; rewritten: string } {
+ const fixes: LintFix[] = [];
+ const rewritten = raw.replace(WIKILINK_RE, (match, target, suffix) => {
+ const canonical = merge.forward.get(target);
+ if (!canonical) return match;
+ fixes.push({ kind: "fix-merged-link", path, from: target, to: canonical });
+ return `[[${canonical}${suffix ?? ""}]]`;
+ });
+ return { fixes, rewritten };
+}
+
+function detectStaleStable(
+ vault: string,
+ now: Date,
+ staleDays: number,
+): LintDemotion[] {
+ const out: LintDemotion[] = [];
+ const dirs = brainDirs(vault);
+ if (!existsSync(dirs.preferences)) return out;
+ for (const name of readdirSync(dirs.preferences)) {
+ if (!name.endsWith(".md") || !name.startsWith("pref-")) continue;
+ const path = join(dirs.preferences, name);
+ let meta: Record<string, unknown>;
+ try {
+ [meta] = parseFrontmatter(path);
+ } catch {
+ continue;
+ }
+ const lifecycle = readLifecycle(meta);
+ if (lifecycle !== PAGE_LIFECYCLE.stable) continue;
+ const lastEv =
+ typeof meta["_last_evidence_at"] === "string"
+ ? meta["_last_evidence_at"]
+ : typeof meta["last_evidence_at"] === "string"
+ ? meta["last_evidence_at"]
+ : "";
+ if (lastEv && lastEv !== "null") {
+ const evAge = ageDaysFromIso(lastEv, now);
+ if (evAge < staleDays) continue;
+ }
+ const createdAt =
+ typeof meta["created_at"] === "string" ? meta["created_at"] : "";
+ const age = ageDaysFromIso(createdAt, now);
+ if (age < staleDays) continue;
+ const id =
+ typeof meta["id"] === "string" ? meta["id"] : name.replace(/\.md$/, "");
+ out.push({
+ kind: "demote-stale-stable",
+ id,
+ path,
+ ageDays: Math.floor(age),
+ });
+ }
+ return out;
+}
+
+function applyDemotion(path: string): boolean {
+ let raw: string;
+ try {
+ raw = readFileSync(path, "utf8");
+ } catch {
+ return false;
+ }
+ // Accept either LF or CRLF frontmatter delimiters so Windows-written
+ // vaults (Syncthing peer on Windows, manual hand-edit) still demote.
+ if (!/^---\r?\n/.test(raw)) return false;
+ const closeMatch = /\r?\n---\r?\n/.exec(raw.slice(3));
+ const close = closeMatch ? 3 + closeMatch.index : -1;
+ if (close < 0) return false;
+ const head = raw.slice(0, close);
+ const tail = raw.slice(close);
+ // Replace `_lifecycle: stable` (or legacy `lifecycle: stable`) with draft.
+ // Preserve indentation/spacing.
+ const updatedHead = head.replace(
+ /^(_?lifecycle:\s+)stable\s*$/m,
+ `$1draft`,
+ );
+ if (updatedHead === head) return false;
+ atomicWriteFileSync(path, updatedHead + tail);
+ return true;
+}
+
+export function lintConsolidate(
+ vault: string,
+ opts: LintOptions,
+): LintReport {
+ const now = opts.now ?? new Date();
+ const staleDays = opts.staleDays ?? PAGE_STALE_DAYS_DEFAULT;
+ const merge = buildMergeMap(vault);
+
+ // Phase 1: scan + collect fix candidates.
+ const fixes: LintFix[] = [];
+ let scanned = 0;
+ let filesWritten = 0;
+ const brainRoot = join(vault, "Brain");
+ if (existsSync(brainRoot)) {
+ const stack: string[] = [brainRoot];
+ while (stack.length > 0) {
+ const dir = stack.pop()!;
+ let names: string[];
+ try {
+ names = readdirSync(dir);
+ } catch {
+ continue;
+ }
+ for (const name of names) {
+ const full = join(dir, name);
+ let info;
+ try {
+ info = statSync(full);
+ } catch {
+ continue;
+ }
+ if (info.isDirectory()) {
+ stack.push(full);
+ continue;
+ }
+ if (!name.endsWith(".md")) continue;
+ scanned += 1;
+ let raw: string;
+ try {
+ raw = readFileSync(full, "utf8");
+ } catch {
+ continue;
+ }
+ const { fixes: fileFixes, rewritten } = scanFileForMergedLinks(
+ full,
+ raw,
+ merge,
+ );
+ if (fileFixes.length === 0) continue;
+ fixes.push(...fileFixes);
+ if (opts.apply && rewritten !== raw) {
+ atomicWriteFileSync(full, rewritten);
+ filesWritten += 1;
+ }
+ }
+ }
+ }
+
+ // Phase 2: stale-stable demotions.
+ const demotions = detectStaleStable(vault, now, staleDays);
+ if (opts.apply) {
+ for (const d of demotions) {
+ if (applyDemotion(d.path)) filesWritten += 1;
+ }
+ }
+
+ return Object.freeze({
+ scanned,
+ fixes: Object.freeze(fixes),
+ demotions: Object.freeze(demotions),
+ applied: opts.apply,
+ filesWritten,
+ });
+}
diff --git a/src/core/brain/maintenance/action-scorer.ts b/src/core/brain/maintenance/action-scorer.ts
new file mode 100644
index 00000000..2266e6f7
--- /dev/null
+++ b/src/core/brain/maintenance/action-scorer.ts
@@ -0,0 +1,157 @@
+/**
+ * Pure scoring function over vault-maintenance signals. Replaces the
+ * vague "Recommendation:" text that earlier digests carried with a
+ * deterministic ranked list of operator-actionable next steps.
+ *
+ * The scorer takes already-collected inputs (page dedup candidates,
+ * stale-lifecycle pages, broken merged-link rewrites, token-footprint
+ * excess) and emits a sorted list of {@link ActionItem} ordered by
+ * impact descending. The function is pure: every input is a typed
+ * shape, no I/O. Use with `findDuplicateCandidates`, `lintConsolidate`,
+ * and `computeTokenFootprint` outputs upstream.
+ */
+
+export type ActionCategory =
+ | "dedup"
+ | "lifecycle"
+ | "merged-link"
+ | "token-footprint";
+
+export interface ActionItem {
+ readonly id: string;
+ readonly category: ActionCategory;
+ readonly title: string;
+ readonly impact: number;
+ /** Optional target reference (page id, file path, etc). */
+ readonly target?: string;
+}
+
+export interface ActionInputs {
+ readonly dedupCandidates?: ReadonlyArray<{
+ readonly canonicalId: string;
+ readonly secondaryCount: number;
+ }>;
+ readonly staleByLifecycle?: ReadonlyArray<{
+ readonly id: string;
+ readonly ageDays: number;
+ }>;
+ readonly brokenLinks?: ReadonlyArray<{
+ readonly path: string;
+ readonly from: string;
+ }>;
+ readonly tokenFootprint?: {
+ readonly total: number;
+ readonly warnThreshold: number;
+ };
+}
+
+const WEIGHT = Object.freeze({
+ dedupPerSecondary: 8,
+ staleLifecyclePerYear: 4,
+ brokenLink: 5,
+ tokenFootprintExcessPer10k: 3,
+});
+
+function scoreDedup(
+ inputs: NonNullable<ActionInputs["dedupCandidates"]>,
+): ActionItem[] {
+ const out: ActionItem[] = [];
+ for (const c of inputs) {
+ if (c.secondaryCount <= 0) continue;
+ out.push({
+ id: `dedup:${c.canonicalId}`,
+ category: "dedup",
+ title: `Merge ${c.secondaryCount} duplicate(s) into ${c.canonicalId}`,
+ impact: c.secondaryCount * WEIGHT.dedupPerSecondary,
+ target: c.canonicalId,
+ });
+ }
+ return out;
+}
+
+function scoreStale(
+ inputs: NonNullable<ActionInputs["staleByLifecycle"]>,
+): ActionItem[] {
+ const out: ActionItem[] = [];
+ for (const s of inputs) {
+ if (s.ageDays <= 0) continue;
+ const years = Math.max(0.5, s.ageDays / 365);
+ out.push({
+ id: `lifecycle:${s.id}`,
+ category: "lifecycle",
+ title: `Re-verify or demote stale stable: ${s.id}`,
+ impact: Math.round(years * WEIGHT.staleLifecyclePerYear),
+ target: s.id,
+ });
+ }
+ return out;
+}
+
+function scoreBrokenLinks(
+ inputs: NonNullable<ActionInputs["brokenLinks"]>,
+): ActionItem[] {
+ // Bucket by source path so the report does not duplicate noisy
+ // file-level recommendations when one page has many broken links.
+ const byPath = new Map<string, number>();
+ for (const l of inputs) {
+ byPath.set(l.path, (byPath.get(l.path) ?? 0) + 1);
+ }
+ const out: ActionItem[] = [];
+ for (const [path, count] of byPath) {
+ out.push({
+ id: `merged-link:${path}`,
+ category: "merged-link",
+ title: `Rewrite ${count} merged-link reference(s) in ${path}`,
+ impact: count * WEIGHT.brokenLink,
+ target: path,
+ });
+ }
+ return out;
+}
+
+function scoreTokenFootprint(
+ input: NonNullable<ActionInputs["tokenFootprint"]>,
+): ActionItem[] {
+ const excess = input.total - input.warnThreshold;
+ if (excess <= 0) return [];
+ const buckets = Math.ceil(excess / 10_000);
+ return [
+ {
+ id: "token-footprint:vault",
+ category: "token-footprint",
+ title: `Vault exceeds warn threshold by ${excess} tokens; archive or split`,
+ impact: buckets * WEIGHT.tokenFootprintExcessPer10k,
+ target: "vault",
+ },
+ ];
+}
+
+export interface ScoreOptions {
+ /** Cap on returned items. Default 10. */
+ readonly topN?: number;
+}
+
+export function scoreActions(
+ inputs: ActionInputs,
+ opts: ScoreOptions = {},
+): ReadonlyArray<ActionItem> {
+ const all: ActionItem[] = [];
+ if (inputs.dedupCandidates) all.push(...scoreDedup(inputs.dedupCandidates));
+ if (inputs.staleByLifecycle) all.push(...scoreStale(inputs.staleByLifecycle));
+ if (inputs.brokenLinks) all.push(...scoreBrokenLinks(inputs.brokenLinks));
+ if (inputs.tokenFootprint)
+ all.push(...scoreTokenFootprint(inputs.tokenFootprint));
+
+ all.sort((a, b) => {
+ if (b.impact !== a.impact) return b.impact - a.impact;
+ if (a.category !== b.category) return a.category < b.category ? -1 : 1;
+ return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+ });
+
+ // Clamp + floor opts.topN so negative or fractional input cannot
+ // produce slice(0, -n) (which silently truncates from the tail
+ // in JS semantics) or off-by-one truncation.
+ const capRaw = opts.topN ?? 10;
+ const cap = Number.isFinite(capRaw) ? Math.max(0, Math.floor(capRaw)) : 10;
+ return Object.freeze(all.slice(0, cap));
+}
diff --git a/src/core/brain/maintenance/collect.ts b/src/core/brain/maintenance/collect.ts
new file mode 100644
index 00000000..d7428b28
--- /dev/null
+++ b/src/core/brain/maintenance/collect.ts
@@ -0,0 +1,60 @@
+/**
+ * Glue layer that gathers vault-maintenance signals (page-dedup
+ * candidates, lint demotions / merged-link rewrites, token-footprint
+ * excess) and hands them to the pure `scoreActions` function.
+ *
+ * Lives in `maintenance/` so the pure scorer stays I/O-free and both
+ * `digest.ts` (read-only summary) and the `brain_doctor` MCP tool
+ * can share the same collection logic without depending on each
+ * other.
+ */
+
+import { lintConsolidate } from "../lint-consolidate.ts";
+import { findDuplicateCandidates } from "../page-dedup.ts";
+import { computeTokenFootprint } from "../token-footprint.ts";
+import { scoreActions, type ActionItem } from "./action-scorer.ts";
+
+export function collectMaintenanceActions(
+ vault: string,
+): ReadonlyArray<ActionItem> {
+ let dedupCandidates: Array<{ canonicalId: string; secondaryCount: number }> = [];
+ let staleByLifecycle: Array<{ id: string; ageDays: number }> = [];
+ let brokenLinks: Array<{ path: string; from: string }> = [];
+ let tokenFootprint: { total: number; warnThreshold: number } | undefined;
+
+ try {
+ const dedup = findDuplicateCandidates(vault);
+ dedupCandidates = dedup.candidates.map((c) => ({
+ canonicalId: c.canonical.id,
+ secondaryCount: c.secondaries.length,
+ }));
+ } catch {
+ // Best-effort: a vault scan failure must not break the consumer.
+ }
+ try {
+ const lint = lintConsolidate(vault, { apply: false });
+ staleByLifecycle = lint.demotions.map((d) => ({
+ id: d.id,
+ ageDays: d.ageDays,
+ }));
+ brokenLinks = lint.fixes.map((f) => ({ path: f.path, from: f.from }));
+ } catch {
+ // ignore
+ }
+ try {
+ const footprint = computeTokenFootprint(vault);
+ tokenFootprint = {
+ total: footprint.total,
+ warnThreshold: footprint.warnThreshold,
+ };
+ } catch {
+ // ignore
+ }
+
+ return scoreActions({
+ dedupCandidates,
+ staleByLifecycle,
+ brokenLinks,
+ ...(tokenFootprint ? { tokenFootprint } : {}),
+ });
+}
diff --git a/src/core/brain/page-dedup.ts b/src/core/brain/page-dedup.ts
new file mode 100644
index 00000000..544e8bbf
Binary files /dev/null and b/src/core/brain/page-dedup.ts differ
diff --git a/src/core/brain/page-meta/confidence.ts b/src/core/brain/page-meta/confidence.ts
new file mode 100644
index 00000000..78eb8acf
--- /dev/null
+++ b/src/core/brain/page-meta/confidence.ts
@@ -0,0 +1,35 @@
+/**
+ * Per-page confidence axis - generalises the existing
+ * `BRAIN_CONFIDENCE` triple (`high`, `medium`, `low`) so it can also
+ * appear on non-preference pages (signals, evidence drafts, retired
+ * snapshots). The preference writer still owns the dream-computed
+ * `_confidence_value` numeric; this module deals only with the
+ * textual bucket and the reader-side default.
+ */
+
+import { BRAIN_CONFIDENCE, type BrainConfidence } from "../types.ts";
+
+export type PageConfidence = BrainConfidence;
+
+const ALL: ReadonlySet<string> = new Set(Object.values(BRAIN_CONFIDENCE));
+
+export function isPageConfidence(value: unknown): value is PageConfidence {
+ return typeof value === "string" && ALL.has(value);
+}
+
+/**
+ * Read `_confidence` (or legacy `confidence`) from a frontmatter map.
+ * Unknown / absent values fall back to `low` so a page that has not
+ * yet earned a confidence stamp does not get one for free.
+ */
+export function readConfidence(
+ meta: Readonly<Record<string, unknown>>,
+): PageConfidence {
+ const modern = meta["_confidence"];
+ if (isPageConfidence(modern)) return modern;
+ const legacy = meta["confidence"];
+ if (isPageConfidence(legacy)) return legacy;
+ return BRAIN_CONFIDENCE.low;
+}
+
+export { BRAIN_CONFIDENCE };
diff --git a/src/core/brain/page-meta/lifecycle.ts b/src/core/brain/page-meta/lifecycle.ts
new file mode 100644
index 00000000..6ad9367c
--- /dev/null
+++ b/src/core/brain/page-meta/lifecycle.ts
@@ -0,0 +1,87 @@
+/**
+ * Per-page `lifecycle` axis - tracks each vault page's verification
+ * state independently of the preference `status` axis (which is
+ * promoted-state for a rule, not freshness for a page).
+ *
+ * Values, ordered loosely from "least vetted" to "no longer trusted":
+ *
+ * - `draft` - first capture, not yet promoted or verified.
+ * - `stable` - has been around long enough to count as normal.
+ * - `verified` - operator or an auto-rule explicitly confirmed
+ * the content matches reality.
+ * - `deprecated` - superseded by another page (`merged_into` or a
+ * successor link); keep readable but don't trust.
+ * - `archived` - moved out of the live working set; long-term
+ * storage only.
+ * - `disputed` - flagged by health checks as contradictory or
+ * contested by another vault entry.
+ *
+ * Default lifecycle for newly-introduced fields is `stable` so any
+ * legacy page without the field stays valid without a migration step.
+ * New writes pick the most appropriate stage for the call site.
+ */
+
+export const PAGE_LIFECYCLE = Object.freeze({
+ draft: "draft",
+ stable: "stable",
+ verified: "verified",
+ deprecated: "deprecated",
+ archived: "archived",
+ disputed: "disputed",
+} as const);
+
+export type PageLifecycle = (typeof PAGE_LIFECYCLE)[keyof typeof PAGE_LIFECYCLE];
+
+const ALL: ReadonlySet<string> = new Set(Object.values(PAGE_LIFECYCLE));
+
+export function isPageLifecycle(value: unknown): value is PageLifecycle {
+ return typeof value === "string" && ALL.has(value);
+}
+
+/**
+ * Read `_lifecycle` (or legacy `lifecycle`) from a frontmatter map.
+ * Unknown / absent values fall back to `stable` per the
+ * backwards-compatibility contract.
+ */
+export function readLifecycle(
+ meta: Readonly<Record<string, unknown>>,
+): PageLifecycle {
+ const modern = meta["_lifecycle"];
+ if (isPageLifecycle(modern)) return modern;
+ const legacy = meta["lifecycle"];
+ if (isPageLifecycle(legacy)) return legacy;
+ return PAGE_LIFECYCLE.stable;
+}
+
+/**
+ * Pages older than the staleness cap that are still in `stable` or
+ * `draft` are candidates for lifecycle demotion or re-verification.
+ * `verified` and `deprecated` are never reported stale - they carry
+ * their own provenance and should not bounce just because the file is old.
+ *
+ * `ageDays` is measured against `created_at` or `last_evidence_at`;
+ * the caller picks which timestamp matters in context.
+ */
+export const PAGE_STALE_DAYS_DEFAULT = 180;
+
+export function isStale(
+ lifecycle: PageLifecycle,
+ ageDays: number,
+ thresholdDays: number = PAGE_STALE_DAYS_DEFAULT,
+): boolean {
+ if (ageDays < thresholdDays) return false;
+ return lifecycle === PAGE_LIFECYCLE.stable || lifecycle === PAGE_LIFECYCLE.draft;
+}
+
+/**
+ * Convert an ISO-8601 timestamp string into age-in-days against a
+ * reference point. Returns `Infinity` when the timestamp is missing
+ * or unparseable so the staleness predicate trips loud on bad input.
+ */
+export function ageDaysFromIso(iso: string | null | undefined, now: Date): number {
+ if (!iso) return Infinity;
+ const ts = Date.parse(iso);
+ if (!Number.isFinite(ts)) return Infinity;
+ const deltaMs = now.getTime() - ts;
+ return deltaMs / (24 * 60 * 60 * 1000);
+}
diff --git a/src/core/brain/page-meta/page-id.ts b/src/core/brain/page-meta/page-id.ts
new file mode 100644
index 00000000..a7043672
--- /dev/null
+++ b/src/core/brain/page-meta/page-id.ts
@@ -0,0 +1,195 @@
+/**
+ * Canonical page identity helpers for the `merged_into:` pointer
+ * written by the page-dedup pass.
+ *
+ * Convention: the secondary page (the one being de-canonicalised)
+ * gets a `merged_into: pref-<canonical-slug>` field in its
+ * frontmatter. Readers that need to resolve identity to the canonical
+ * page walk the chain with {@link resolveCanonicalId}; depth is
+ * bounded at {@link MERGE_CHAIN_MAX_DEPTH} so a cycle (which should
+ * never happen but is cheap to defend against) fails loud rather
+ * than recursing forever.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { atomicWriteFileSync } from "../../fs-atomic.ts";
+import { parseFrontmatter } from "../../vault.ts";
+import { brainDirs } from "../paths.ts";
+
+export const MERGE_CHAIN_MAX_DEPTH = 5;
+
+export class MergeChainError extends Error {
+ readonly code: "CYCLE" | "DEPTH" | "MALFORMED";
+ readonly id: string;
+ constructor(code: "CYCLE" | "DEPTH" | "MALFORMED", id: string, message: string) {
+ super(message);
+ this.name = "MergeChainError";
+ this.code = code;
+ this.id = id;
+ }
+}
+
+/**
+ * Read `merged_into:` from a frontmatter map. Returns the canonical
+ * page id (e.g. `pref-foo`) when set, or `null` when absent.
+ * Non-string values are treated as absent so a malformed file does
+ * not poison the canonical lookup.
+ */
+export function readMergedInto(
+ meta: Readonly<Record<string, unknown>>,
+): string | null {
+ const v = meta["merged_into"];
+ if (typeof v === "string" && v.trim().length > 0) return v.trim();
+ return null;
+}
+
+/**
+ * Strict page-id format: `pref-<slug>` or `ret-<slug>` where the
+ * slug matches the same `[a-z0-9-]+` shape `validateSlug` enforces.
+ * Anything else - path separators, newlines, dots, uppercase - is
+ * rejected so a crafted `merged_into:` value cannot escape the
+ * Brain/ dirs or inject extra YAML keys into a write.
+ */
+const PAGE_ID_RE = /^(pref|ret)-[a-z0-9-]+$/;
+
+function isValidPageId(id: string): boolean {
+ return PAGE_ID_RE.test(id);
+}
+
+function pageIdToPath(vault: string, id: string): string | null {
+ if (!isValidPageId(id)) return null;
+ const dirs = brainDirs(vault);
+ if (id.startsWith("pref-")) return join(dirs.preferences, `${id}.md`);
+ return join(dirs.retired, `${id}.md`);
+}
+
+/**
+ * Follow the `merged_into:` chain from a starting page id to its
+ * canonical destination. The walk terminates when a page has no
+ * `merged_into` set or the chain exceeds {@link MERGE_CHAIN_MAX_DEPTH}.
+ *
+ * Throws {@link MergeChainError}:
+ * - `CYCLE` when the same id is visited twice.
+ * - `DEPTH` when the chain is longer than the cap.
+ * - `MALFORMED` when an intermediate target id has neither `pref-`
+ * nor `ret-` prefix.
+ */
+export function resolveCanonicalId(vault: string, startId: string): string {
+ const visited = new Set<string>();
+ let current = startId;
+ for (let depth = 0; depth <= MERGE_CHAIN_MAX_DEPTH; depth++) {
+ if (visited.has(current)) {
+ throw new MergeChainError("CYCLE", current, `merge cycle detected at ${current}`);
+ }
+ visited.add(current);
+
+ const path = pageIdToPath(vault, current);
+ if (path === null) {
+ throw new MergeChainError(
+ "MALFORMED",
+ current,
+ `page id has no known prefix: ${current}`,
+ );
+ }
+ if (!existsSync(path)) {
+ // Dangling pointer - the canonical page was moved or deleted.
+ // Treat the current id as terminal so we surface the broken
+ // chain to the caller without throwing on every read.
+ return current;
+ }
+ let meta: Record<string, unknown>;
+ try {
+ [meta] = parseFrontmatter(path);
+ } catch {
+ return current;
+ }
+ const next = readMergedInto(meta);
+ if (next === null) return current;
+ current = next;
+ }
+ throw new MergeChainError(
+ "DEPTH",
+ startId,
+ `merge chain exceeds ${MERGE_CHAIN_MAX_DEPTH} hops starting at ${startId}`,
+ );
+}
+
+/**
+ * Stamp `merged_into: <canonical>` into the secondary page's
+ * frontmatter and rewrite the file. The secondary keeps all other
+ * fields and body content - the pointer is the only signal that a
+ * merge happened. Returns the resolved canonical id.
+ *
+ * The caller is responsible for picking which side is the canonical
+ * and which is the secondary; this function only writes the pointer.
+ */
+export function setMergedInto(
+ vault: string,
+ secondaryId: string,
+ canonicalId: string,
+): string {
+ if (!isValidPageId(secondaryId)) {
+ throw new MergeChainError(
+ "MALFORMED",
+ secondaryId,
+ `invalid secondary page id: ${secondaryId}`,
+ );
+ }
+ if (!isValidPageId(canonicalId)) {
+ throw new MergeChainError(
+ "MALFORMED",
+ canonicalId,
+ `invalid canonical page id: ${canonicalId}`,
+ );
+ }
+ if (secondaryId === canonicalId) {
+ throw new MergeChainError(
+ "CYCLE",
+ secondaryId,
+ `cannot point a page at itself: ${secondaryId}`,
+ );
+ }
+ const secondaryPath = pageIdToPath(vault, secondaryId);
+ if (secondaryPath === null || !existsSync(secondaryPath)) {
+ throw new MergeChainError(
+ "MALFORMED",
+ secondaryId,
+ `secondary page not found: ${secondaryId}`,
+ );
+ }
+ const raw = readFileSync(secondaryPath, "utf8");
+ if (raw.startsWith("---\n")) {
+ // Inject `merged_into: <canonical>` right before the closing
+ // frontmatter fence. Idempotent: replace the existing line when
+ // present.
+ const end = raw.indexOf("\n---\n", 4);
+ if (end < 0) {
+ throw new MergeChainError(
+ "MALFORMED",
+ secondaryId,
+ `frontmatter has no closing fence: ${secondaryPath}`,
+ );
+ }
+ const head = raw.slice(0, end);
+ const tail = raw.slice(end);
+ const existingPattern = /^merged_into:\s.*$/m;
+ let nextHead: string;
+ if (existingPattern.test(head)) {
+ nextHead = head.replace(existingPattern, `merged_into: ${canonicalId}`);
+ } else {
+ nextHead = `${head}\nmerged_into: ${canonicalId}`;
+ }
+ const next = `${nextHead}${tail}`;
+ if (next !== raw) {
+ atomicWriteFileSync(secondaryPath, next);
+ }
+ return canonicalId;
+ }
+ throw new MergeChainError(
+ "MALFORMED",
+ secondaryId,
+ `file has no frontmatter: ${secondaryPath}`,
+ );
+}
diff --git a/src/core/brain/page-meta/tier.ts b/src/core/brain/page-meta/tier.ts
new file mode 100644
index 00000000..efb877d8
--- /dev/null
+++ b/src/core/brain/page-meta/tier.ts
@@ -0,0 +1,53 @@
+/**
+ * Per-page importance tier - operator intent about which pages
+ * matter most. Unlike `lifecycle` (freshness / verification) and
+ * `_confidence` (dream-computed probability), `tier` is user-owned
+ * and stays unprefixed in frontmatter so Obsidian users can edit it
+ * by hand without violating the Group-C-fields convention.
+ *
+ * Default is `supporting`, picked so the search ranker stays
+ * bit-identical for any vault that has not yet been tier-tagged.
+ */
+
+export const PAGE_TIER = Object.freeze({
+ core: "core",
+ supporting: "supporting",
+ peripheral: "peripheral",
+} as const);
+
+export type PageTier = (typeof PAGE_TIER)[keyof typeof PAGE_TIER];
+
+const ALL: ReadonlySet<string> = new Set(Object.values(PAGE_TIER));
+
+export function isPageTier(value: unknown): value is PageTier {
+ return typeof value === "string" && ALL.has(value);
+}
+
+export const PAGE_TIER_DEFAULT: PageTier = PAGE_TIER.supporting;
+
+/**
+ * Read `tier` from a frontmatter map. Defaults to `supporting`.
+ * Unrecognised values also fall back to the default so a typo
+ * (`tier: cor`) does not silently disable a page.
+ */
+export function readTier(meta: Readonly<Record<string, unknown>>): PageTier {
+ const v = meta["tier"];
+ if (isPageTier(v)) return v;
+ return PAGE_TIER_DEFAULT;
+}
+
+/**
+ * Multiplicative ranker weight for each tier. `supporting` is the
+ * identity (1.0) so untagged vaults do not change their ranking; the
+ * other two values bracket it in a deliberately small range so tier
+ * cannot dominate raw keyword / semantic relevance.
+ */
+const TIER_WEIGHT: Readonly<Record<PageTier, number>> = Object.freeze({
+ core: 1.4,
+ supporting: 1.0,
+ peripheral: 0.6,
+});
+
+export function tierWeight(tier: PageTier): number {
+ return TIER_WEIGHT[tier];
+}
diff --git a/src/core/brain/preference.ts b/src/core/brain/preference.ts
index 05f1b0c1..f1089293 100644
--- a/src/core/brain/preference.ts
+++ b/src/core/brain/preference.ts
@@ -59,6 +59,8 @@ import {
type BrainRetired,
type BrainRetiredReason,
} from "./types.ts";
+import type { PageLifecycle } from "./page-meta/lifecycle.ts";
+import type { PageTier } from "./page-meta/tier.ts";
// ----- Errors ---------------------------------------------------------------
@@ -130,6 +132,21 @@ export interface WritePreferenceInput {
* refresh pass always supplies a finite value.
*/
readonly confidence_value?: number | null;
+ /**
+ * Per-page lifecycle. Defaults to `stable` when unspecified so
+ * legacy callers do not need to thread the field through. Dream
+ * promotes `stable` → `verified` once a preference accumulates
+ * enough independent applied-evidence events; the lint --consolidate
+ * pass can demote `stable` → `draft` for very old, never-applied
+ * pages.
+ */
+ readonly lifecycle?: PageLifecycle;
+ /**
+ * Per-page importance tier. User-editable, unprefixed in YAML
+ * (next to `pinned`). Reader-side default is `supporting`; emitted
+ * only when supplied so legacy fixtures stay byte-identical.
+ */
+ readonly tier?: PageTier;
readonly pinned?: boolean;
readonly supersedes?: string;
readonly aliases?: ReadonlyArray<string>;
@@ -342,6 +359,18 @@ function preferenceFrontmatter(
if (input.aliases && input.aliases.length > 0) {
metadata["aliases"] = [...input.aliases];
}
+ // `_lifecycle` is emitted only when the caller supplies it. Legacy
+ // call sites stay byte-identical; new writers (dream refresh pass,
+ // lint consolidate) opt in by passing the field. Readers fall back
+ // to `stable` via `readLifecycle()`.
+ if (input.lifecycle !== undefined) {
+ metadata["_lifecycle"] = input.lifecycle;
+ }
+ // `tier` is user-editable (unprefixed). Emitted only when supplied;
+ // readers fall back to `supporting` via `readTier()`.
+ if (input.tier !== undefined) {
+ metadata["tier"] = input.tier;
+ }
return metadata;
}
@@ -449,6 +478,7 @@ export const DERIVED_FIELDS: ReadonlyArray<string> = Object.freeze([
"confidence_value",
"evidenced_by",
"contradicted_by",
+ "lifecycle",
]);
/**
diff --git a/src/core/brain/text/normalize.ts b/src/core/brain/text/normalize.ts
new file mode 100644
index 00000000..23c8a929
--- /dev/null
+++ b/src/core/brain/text/normalize.ts
@@ -0,0 +1,28 @@
+/**
+ * Unicode-aware key normaliser used wherever the Brain layer
+ * constructs a dedup or comparison key from user-supplied text.
+ *
+ * Two transforms applied in order:
+ *
+ * 1. `String.prototype.normalize("NFKC")` - compatibility composition.
+ * Folds visually-equivalent codepoint variants (fullwidth /
+ * halfwidth Latin, half-width katakana vs full-width, composed vs
+ * decomposed accents, ligature decomposition, etc.) into one
+ * canonical form. NFC is too narrow - it keeps fullwidth `H`
+ * distinct from halfwidth `H`. NFKC merges them.
+ *
+ * 2. `String.prototype.toLowerCase()` - Unicode-aware case folding.
+ * JavaScript's default `toLowerCase` performs locale-independent
+ * Unicode case mapping (per the spec it uses the
+ * `String.prototype.toLowerCase` algorithm from ECMA-262 §22.1).
+ * Not as exhaustive as Python's `str.casefold` but close enough
+ * for vault dedup: Cyrillic `Т` → `т`, Greek `Σ` → `σ`, Latin
+ * `Ä` → `ä`, etc.
+ *
+ * The resulting string is suitable as the canonical input to a hash
+ * function or as a comparison key for near-duplicate detection.
+ * It is NOT suitable for display - the casefold step is lossy.
+ */
+export function normalizeForDedup(input: string): string {
+ return input.normalize("NFKC").toLowerCase();
+}
diff --git a/src/core/brain/text/tokenizer.ts b/src/core/brain/text/tokenizer.ts
new file mode 100644
index 00000000..2f07b4d7
--- /dev/null
+++ b/src/core/brain/text/tokenizer.ts
@@ -0,0 +1,38 @@
+/**
+ * Heuristic token counter for vault content. Not a true tokenizer -
+ * no BPE merges, no model-specific vocabulary - just a stable,
+ * deterministic estimate that lets brain_digest and `brain
+ * token-footprint` describe vault size in roughly LLM-equivalent
+ * units without taking a tokenizer dependency.
+ *
+ * Heuristic: `ceil(utf8_bytes / 4)`. This is OpenAI's published
+ * rule-of-thumb ("roughly 1 token per 4 characters of English"),
+ * generalised to UTF-8 bytes so the same formula works for any
+ * script. Non-Latin glyphs are encoded as 2-4 bytes in UTF-8, which
+ * naturally tracks the way multilingual BPE tokenizers spend more
+ * tokens per visible character in dense scripts.
+ *
+ * Trade-offs:
+ * - Overcounts pure ASCII English slightly versus modern BPE
+ * tokenizers (cl100k / o200k average closer to 1 token per 4-5
+ * characters).
+ * - Undercounts pathological cases (rare emojis with skin-tone
+ * modifiers, regional indicator sequences) where one visible
+ * glyph spans 8+ bytes.
+ * - Determinism, language-agnosticism, and zero-dependency cost
+ * are the priorities: this number must be stable across runs
+ * and not require a new vocabulary every time a new script
+ * ships.
+ *
+ * Determinism matters more than per-string accuracy: the same input
+ * must always produce the same count so digests stay stable across
+ * runs.
+ */
+
+const ENCODER = new TextEncoder();
+
+export function estimateTokens(input: string): number {
+ if (input.length === 0) return 0;
+ const bytes = ENCODER.encode(input).length;
+ return Math.ceil(bytes / 4);
+}
diff --git a/src/core/brain/token-footprint.ts b/src/core/brain/token-footprint.ts
new file mode 100644
index 00000000..89c48853
--- /dev/null
+++ b/src/core/brain/token-footprint.ts
@@ -0,0 +1,152 @@
+/**
+ * Vault token footprint - per-category sum of `estimateTokens` over
+ * every Brain/* page, surfaced through `o2b brain token-footprint`
+ * and a digest section. Lets operators catch runaway ingestion
+ * before it overflows model context windows.
+ *
+ * Categories: `preferences`, `retired`, `inbox`, `processed`, `log`,
+ * `other`. The "other" bucket captures anything that lives under
+ * Brain/ but does not match a known subdirectory.
+ */
+
+import {
+ existsSync,
+ readFileSync,
+ readdirSync,
+ statSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import { brainDirs } from "./paths.ts";
+import { estimateTokens } from "./text/tokenizer.ts";
+
+export const TOKEN_WARN_THRESHOLD_DEFAULT = 200_000;
+
+export interface TokenFootprintCategory {
+ readonly name: string;
+ readonly tokens: number;
+ readonly files: number;
+}
+
+export interface TokenFootprintReport {
+ readonly total: number;
+ readonly files: number;
+ readonly byCategory: ReadonlyArray<TokenFootprintCategory>;
+ readonly warnThreshold: number;
+ readonly exceeded: boolean;
+}
+
+function sumDir(dir: string): { tokens: number; files: number } {
+ // Non-recursive: each Brain bucket is structurally flat, and
+ // counting recursively would double-count nested subdirs (e.g.
+ // `inbox/processed/` is its own bucket and must not roll into
+ // the parent `inbox` total).
+ if (!existsSync(dir)) return { tokens: 0, files: 0 };
+ let tokens = 0;
+ let files = 0;
+ let names: string[];
+ try {
+ names = readdirSync(dir);
+ } catch {
+ return { tokens: 0, files: 0 };
+ }
+ for (const name of names) {
+ if (!name.endsWith(".md")) continue;
+ const full = join(dir, name);
+ let info;
+ try {
+ info = statSync(full);
+ } catch {
+ continue;
+ }
+ if (info.isDirectory()) continue;
+ let raw: string;
+ try {
+ raw = readFileSync(full, "utf8");
+ } catch {
+ continue;
+ }
+ tokens += estimateTokens(raw);
+ files += 1;
+ }
+ return { tokens, files };
+}
+
+/**
+ * Resolve the warn threshold from an env-var override, falling back
+ * to the documented default. The env-var path lets cron jobs
+ * customise the warning level without code changes.
+ */
+function resolveWarnThreshold(envValue: string | undefined): number {
+ if (envValue) {
+ const n = Number.parseInt(envValue, 10);
+ if (Number.isFinite(n) && n > 0) return n;
+ }
+ return TOKEN_WARN_THRESHOLD_DEFAULT;
+}
+
+export function computeTokenFootprint(
+ vault: string,
+ opts: { warnThreshold?: number; envWarnThreshold?: string } = {},
+): TokenFootprintReport {
+ const dirs = brainDirs(vault);
+ const tracked: Array<[name: string, path: string]> = [
+ ["preferences", dirs.preferences],
+ ["retired", dirs.retired],
+ ["inbox", dirs.inbox],
+ ["processed", dirs.processed],
+ ["log", dirs.log],
+ ];
+
+ const byCategory: TokenFootprintCategory[] = [];
+ let total = 0;
+ let totalFiles = 0;
+ for (const [name, path] of tracked) {
+ const { tokens, files } = sumDir(path);
+ byCategory.push({ name, tokens, files });
+ total += tokens;
+ totalFiles += files;
+ }
+
+ // "other" bucket: any *.md directly under Brain/ that we have not
+ // already accounted for. We do not recurse into unknown subdirs
+ // so a runaway plugin dropping junk under Brain/exotic-thing/ is
+ // not silently included; the digest action list flags it instead.
+ const brainRoot = join(vault, "Brain");
+ if (existsSync(brainRoot)) {
+ let otherTokens = 0;
+ let otherFiles = 0;
+ for (const name of readdirSync(brainRoot)) {
+ const full = join(brainRoot, name);
+ let info;
+ try {
+ info = statSync(full);
+ } catch {
+ continue;
+ }
+ if (info.isDirectory()) continue;
+ if (!name.endsWith(".md")) continue;
+ let raw: string;
+ try {
+ raw = readFileSync(full, "utf8");
+ } catch {
+ continue;
+ }
+ otherTokens += estimateTokens(raw);
+ otherFiles += 1;
+ }
+ byCategory.push({ name: "other", tokens: otherTokens, files: otherFiles });
+ total += otherTokens;
+ totalFiles += otherFiles;
+ }
+
+ const warnThreshold =
+ opts.warnThreshold ?? resolveWarnThreshold(opts.envWarnThreshold);
+ return Object.freeze({
+ total,
+ files: totalFiles,
+ byCategory: Object.freeze(byCategory),
+ warnThreshold,
+ exceeded: total > warnThreshold,
+ });
+}
diff --git a/src/core/search/ranker.ts b/src/core/search/ranker.ts
index 2e1bf6d8..c34a832a 100644
--- a/src/core/search/ranker.ts
+++ b/src/core/search/ranker.ts
@@ -9,6 +9,11 @@
* testable and substitutable.
*/
+import {
+ PAGE_TIER_DEFAULT,
+ tierWeight,
+ type PageTier,
+} from "../brain/page-meta/tier.ts";
import type { KeywordHit, SemanticHit, HydratedChunk } from "./store.ts";
import type { BrainSearchResult } from "./types.ts";
@@ -20,6 +25,13 @@ export interface RankerInputs {
readonly inboundLinkSources: ReadonlyMap<number, ReadonlySet<number>>;
/** For each chunkId: the tag set of its document. */
readonly tagsByDoc: ReadonlyMap<number, ReadonlySet<string>>;
+ /**
+ * Optional importance tier per documentId. Missing entries (and
+ * the absent map entirely) resolve to `supporting`, whose tier
+ * weight is `1.0` - so a vault without any tier tags ranks
+ * bit-identically to pre-tier behaviour.
+ */
+ readonly tierByDoc?: ReadonlyMap<number, PageTier>;
}
export interface RankerOptions {
@@ -181,7 +193,12 @@ export function rankResults(inputs: RankerInputs, opts: RankerOptions): BrainSea
const weighted =
opts.keywordWeight * c.keywordScore +
(semanticEnabled ? opts.semanticWeight : 0) * c.semanticScore;
- const score = clamp01(weighted + linkBoost + recency);
+ // Tier multiplier applied to the relevance portion only so the
+ // tag / link / recency boosts stay tier-neutral. Default
+ // `supporting` → 1.0 keeps untagged vaults bit-identical.
+ const tier = inputs.tierByDoc?.get(c.documentId) ?? PAGE_TIER_DEFAULT;
+ const tierMul = tierWeight(tier);
+ const score = clamp01(weighted * tierMul + linkBoost + recency);
ranked.push(
Object.freeze({
diff --git a/src/mcp/brain-tools.ts b/src/mcp/brain-tools.ts
index f8e9d0c4..e0b139a8 100644
--- a/src/mcp/brain-tools.ts
+++ b/src/mcp/brain-tools.ts
@@ -53,6 +53,8 @@ import {
type AppendApplyEvidenceInput,
} from "../core/brain/apply-evidence.ts";
import { buildBacklinkIndex } from "../core/brain/backlinks.ts";
+import { packContext } from "../core/brain/context-pack.ts";
+import { collectMaintenanceActions } from "../core/brain/maintenance/collect.ts";
import { normaliseWikilinkTarget } from "../core/brain/wikilink.ts";
import {
renderDigest,
@@ -598,6 +600,17 @@ async function toolBrainDoctor(
message: i.message,
...(i.path !== undefined ? { path: vaultRelativeSafe(ctx.vault, i.path) } : {}),
})),
+ // v0.10.15: ranked maintenance actions surfaced as a parallel
+ // signal to errors/warnings. The list is independent of `strict`
+ // because nothing here downgrades the `ok` flag - actions are
+ // suggestions, not invariant violations.
+ suggested_actions: collectMaintenanceActions(ctx.vault).map((a) => ({
+ id: a.id,
+ category: a.category,
+ title: a.title,
+ impact: a.impact,
+ ...(a.target !== undefined ? { target: a.target } : {}),
+ })),
};
}
@@ -716,6 +729,48 @@ export function vaultRelativeSafe(vault: string, target: string): string {
// ----- Tool registration ---------------------------------------------------
+// ----- brain_context_pack (v0.10.15) ---------------------------------------
+
+/**
+ * Bounded-token vault slice ordered by importance tier then recency.
+ * Lets an agent prime its context window under a strict budget.
+ */
+async function toolBrainContextPack(
+ ctx: ServerContext,
+ args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+ const maxRaw = args["max_tokens"];
+ const maxTokens = typeof maxRaw === "number" ? maxRaw : Number.parseInt(String(maxRaw ?? ""), 10);
+ if (!Number.isFinite(maxTokens) || maxTokens <= 0) {
+ throw new MCPError(
+ INVALID_PARAMS,
+ "brain_context_pack: max_tokens must be a positive integer",
+ );
+ }
+ const query = typeof args["query"] === "string" ? (args["query"] as string) : undefined;
+ const report = packContext(ctx.vault, {
+ maxTokens,
+ ...(query ? { query } : {}),
+ });
+ return {
+ vault_path: ctx.vault,
+ max_tokens: report.maxTokens,
+ tokens_used: report.tokensUsed,
+ items: report.items.map((i) => ({
+ id: i.id,
+ path: i.path,
+ tier: i.tier,
+ tokens: i.tokens,
+ body: i.body,
+ })),
+ skipped: report.skipped.map((s) => ({
+ id: s.id,
+ tokens: s.tokens,
+ reason: s.reason,
+ })),
+ };
+}
+
export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
{
name: "brain_feedback",
@@ -972,4 +1027,27 @@ export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
},
handler: toolBrainBacklinks,
},
+ {
+ name: "brain_context_pack",
+ description:
+ "Return the highest-tier, most recent vault slice that fits under `max_tokens`. Ordered core → supporting → peripheral, newest first; stops adding pages when the next page would exceed the budget. Read-only.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ max_tokens: {
+ type: "integer",
+ minimum: 1,
+ description: "Strict upper bound on the returned slice's token count.",
+ },
+ query: {
+ type: "string",
+ description:
+ "Optional case/Unicode-insensitive substring filter on topic + principle.",
+ },
+ },
+ required: ["max_tokens"],
+ additionalProperties: false,
+ },
+ handler: toolBrainContextPack,
+ },
]);
diff --git a/tests/core/brain/context-pack.test.ts b/tests/core/brain/context-pack.test.ts
new file mode 100644
index 00000000..39b4dd30
--- /dev/null
+++ b/tests/core/brain/context-pack.test.ts
@@ -0,0 +1,122 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { packContext } from "../../../src/core/brain/context-pack.ts";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-context-pack-"));
+ mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
+ mkdirSync(join(vault, "Brain", "retired"), { recursive: true });
+});
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+function writePref(
+ slug: string,
+ fields: { topic: string; principle: string; tier?: string; created_at?: string },
+) {
+ const lines = ["---", `id: pref-${slug}`, `topic: ${fields.topic}`, `principle: ${fields.principle}`];
+ if (fields.tier) lines.push(`tier: ${fields.tier}`);
+ if (fields.created_at) lines.push(`created_at: ${fields.created_at}`);
+ lines.push("---", "");
+ writeFileSync(
+ join(vault, "Brain", "preferences", `pref-${slug}.md`),
+ lines.join("\n"),
+ );
+}
+
+describe("packContext", () => {
+ test("empty vault returns empty pack", () => {
+ const r = packContext(vault, { maxTokens: 1000 });
+ expect(r.tokensUsed).toBe(0);
+ expect(r.items.length).toBe(0);
+ expect(r.skipped.length).toBe(0);
+ });
+
+ test("orders core → supporting → peripheral", () => {
+ writePref("p", { topic: "x", principle: "peripheral one", tier: "peripheral" });
+ writePref("s", { topic: "x", principle: "supporting one", tier: "supporting" });
+ writePref("c", { topic: "x", principle: "core one", tier: "core" });
+ const r = packContext(vault, { maxTokens: 10_000 });
+ const ids = r.items.map((i) => i.id);
+ expect(ids).toEqual(["pref-c", "pref-s", "pref-p"]);
+ });
+
+ test("within same tier, newest first by created_at", () => {
+ writePref("old", {
+ topic: "x",
+ principle: "alpha",
+ tier: "core",
+ created_at: "2026-01-01T00:00:00Z",
+ });
+ writePref("new", {
+ topic: "x",
+ principle: "beta",
+ tier: "core",
+ created_at: "2026-05-01T00:00:00Z",
+ });
+ const r = packContext(vault, { maxTokens: 10_000 });
+ expect(r.items[0]!.id).toBe("pref-new");
+ expect(r.items[1]!.id).toBe("pref-old");
+ });
+
+ test("stops when next page would exceed budget", () => {
+ writePref("a", {
+ topic: "x",
+ principle: "alpha beta gamma delta epsilon",
+ tier: "core",
+ created_at: "2026-05-01T00:00:00Z",
+ });
+ writePref("b", {
+ topic: "x",
+ principle: "zeta eta theta iota kappa",
+ tier: "core",
+ created_at: "2026-04-01T00:00:00Z",
+ });
+ // budget of 30 fits one and at least partially trips the second
+ const r = packContext(vault, { maxTokens: 30 });
+ expect(r.items.length).toBeGreaterThanOrEqual(1);
+ expect(r.tokensUsed).toBeLessThanOrEqual(30);
+ // every dropped item is marked over-budget
+ for (const s of r.skipped) {
+ expect(s.reason).toBe("over-budget");
+ }
+ });
+
+ test("query filters by normalised topic + principle", () => {
+ writePref("match", {
+ topic: "writing",
+ principle: "Use imperative voice",
+ tier: "core",
+ });
+ writePref("skip", {
+ topic: "git",
+ principle: "Squash before merge",
+ tier: "core",
+ });
+ const r = packContext(vault, { maxTokens: 10_000, query: "imperative" });
+ expect(r.items.map((i) => i.id)).toEqual(["pref-match"]);
+ expect(r.skipped[0]!.reason).toBe("filter-miss");
+ });
+
+ test("query is case and Unicode insensitive", () => {
+ writePref("ja", {
+ topic: "テスト",
+ principle: "Hello world",
+ tier: "core",
+ });
+ const r = packContext(vault, { maxTokens: 10_000, query: "テスト" });
+ expect(r.items.length).toBe(1);
+ });
+
+ test("non-positive maxTokens returns empty", () => {
+ writePref("a", { topic: "x", principle: "alpha", tier: "core" });
+ expect(packContext(vault, { maxTokens: 0 }).items.length).toBe(0);
+ expect(packContext(vault, { maxTokens: -5 }).items.length).toBe(0);
+ });
+});
diff --git a/tests/core/brain/dedup-hash-unicode.test.ts b/tests/core/brain/dedup-hash-unicode.test.ts
new file mode 100644
index 00000000..cb5c2cb0
--- /dev/null
+++ b/tests/core/brain/dedup-hash-unicode.test.ts
@@ -0,0 +1,119 @@
+/**
+ * Regression coverage for the Unicode-aware dedup-hash path (F7).
+ * These cases existed prior to the NFKC + casefold switch but were
+ * not pinned; today the hash for `Hello` and `Hello` differs.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { computeDedupHash } from "../../../src/core/brain/dedup-hash.ts";
+
+describe("computeDedupHash (unicode-aware)", () => {
+ test("fullwidth vs halfwidth principle hashes identically", () => {
+ const a = computeDedupHash({
+ topic: "rule",
+ signal: "positive",
+ principle: "Hello world",
+ });
+ const b = computeDedupHash({
+ topic: "rule",
+ signal: "positive",
+ principle: "Hello world",
+ });
+ expect(a).toBe(b);
+ });
+
+ test("uppercase vs lowercase principle hashes identically", () => {
+ const a = computeDedupHash({
+ topic: "rule",
+ signal: "positive",
+ principle: "Use imperative voice",
+ });
+ const b = computeDedupHash({
+ topic: "rule",
+ signal: "positive",
+ principle: "USE IMPERATIVE VOICE",
+ });
+ expect(a).toBe(b);
+ });
+
+ test("NFC vs NFD decomposed accent hashes identically", () => {
+ // First input is precomposed (NFC: U+00E9 `é`); second is the
+ // decomposed form (NFD: `e` + U+0301 combining acute) so the
+ // hash must collapse both to the same key.
+ const a = computeDedupHash({
+ topic: "ru",
+ signal: "positive",
+ principle: "café au lait",
+ });
+ const b = computeDedupHash({
+ topic: "ru",
+ signal: "positive",
+ principle: "café au lait",
+ });
+ expect(a).toBe(b);
+ });
+
+ test("CJK principle does not collapse to empty string", () => {
+ const a = computeDedupHash({
+ topic: "ja",
+ signal: "positive",
+ principle: "テスト ルール",
+ });
+ const b = computeDedupHash({
+ topic: "ja",
+ signal: "positive",
+ principle: "別のテスト",
+ });
+ expect(a).not.toBe(b);
+ expect(a.length).toBe(64);
+ expect(b.length).toBe(64);
+ });
+
+ test("Cyrillic principle hashes case-insensitively", () => {
+ const a = computeDedupHash({
+ topic: "ru-rule",
+ signal: "positive",
+ principle: "Используй императив",
+ });
+ const b = computeDedupHash({
+ topic: "ru-rule",
+ signal: "positive",
+ principle: "ИСПОЛЬЗУЙ ИМПЕРАТИВ",
+ });
+ expect(a).toBe(b);
+ });
+
+ test("topic and scope are also normalised", () => {
+ const a = computeDedupHash({
+ topic: "Writing",
+ signal: "positive",
+ principle: "Keep it short",
+ scope: "Docs",
+ });
+ const b = computeDedupHash({
+ topic: "writing",
+ signal: "positive",
+ principle: "Keep it short",
+ scope: "docs",
+ });
+ expect(a).toBe(b);
+ });
+
+ test("signal sign is NOT normalised (positive ≠ Positive collision impossible)", () => {
+ // The signal field is a discriminated union of exactly two
+ // literals; type system already protects against it. This
+ // assertion just documents that we don't touch it.
+ const a = computeDedupHash({
+ topic: "rule",
+ signal: "positive",
+ principle: "x",
+ });
+ const b = computeDedupHash({
+ topic: "rule",
+ signal: "negative",
+ principle: "x",
+ });
+ expect(a).not.toBe(b);
+ });
+});
diff --git a/tests/core/brain/digest-actions.test.ts b/tests/core/brain/digest-actions.test.ts
new file mode 100644
index 00000000..7aaa3de5
--- /dev/null
+++ b/tests/core/brain/digest-actions.test.ts
@@ -0,0 +1,127 @@
+/**
+ * Coverage for the v0.10.15 ranked maintenance actions surfaced via
+ * `brain_digest`. Confirms the JSON payload carries an `actions`
+ * array, that the Markdown renderer emits a `## Actions` section
+ * when populated, and that an empty vault stays quiet.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+ mkdirSync,
+ mkdtempSync,
+ rmSync,
+ writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { renderDigest } from "../../../src/core/brain/digest.ts";
+
+let vault: string;
+
+function writePref(slug: string, fields: Record<string, string>) {
+ const lines = [
+ "---",
+ "kind: brain-preference",
+ `id: pref-${slug}`,
+ "tags: [brain, brain/preference]",
+ ];
+ for (const [k, v] of Object.entries(fields)) lines.push(`${k}: ${v}`);
+ lines.push("---", "");
+ writeFileSync(
+ join(vault, "Brain", "preferences", `pref-${slug}.md`),
+ lines.join("\n"),
+ );
+}
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-digest-actions-"));
+ mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
+ mkdirSync(join(vault, "Brain", "retired"), { recursive: true });
+ mkdirSync(join(vault, "Brain", "inbox", "processed"), { recursive: true });
+ mkdirSync(join(vault, "Brain", "log"), { recursive: true });
+});
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+describe("brain_digest actions surface", () => {
+ test("empty vault renders no Actions section in markdown", () => {
+ const res = renderDigest(vault, {
+ format: "markdown",
+ since: new Date("2026-05-24T00:00:00Z"),
+ until: new Date("2026-05-25T00:00:00Z"),
+ });
+ expect(res.content).not.toContain("## Actions");
+ });
+
+ test("empty vault still carries an empty actions array in JSON", () => {
+ const res = renderDigest(vault, {
+ format: "json",
+ since: new Date("2026-05-24T00:00:00Z"),
+ until: new Date("2026-05-25T00:00:00Z"),
+ });
+ const payload = JSON.parse(res.content) as { actions: unknown };
+ expect(Array.isArray(payload.actions)).toBe(true);
+ expect((payload.actions as Array<unknown>).length).toBe(0);
+ });
+
+ test("dedup candidates appear as a ranked action in markdown when window has activity", () => {
+ // One window-active preference makes the digest non-empty so
+ // the full renderer (and therefore the ## Actions section) runs.
+ writePref("active", {
+ topic: "writing",
+ principle: "Active in window",
+ status: "unconfirmed",
+ created_at: "2026-05-24T12:00:00Z",
+ unconfirmed_until: "2026-06-01T00:00:00Z",
+ });
+ // Dedup pair (out-of-window, vault-state).
+ writePref("alpha", {
+ topic: "writing",
+ principle: "Use imperative voice",
+ created_at: "2026-01-01T00:00:00Z",
+ });
+ writePref("alpha-dup", {
+ topic: "writing",
+ principle: "Use imperative voice",
+ created_at: "2026-02-01T00:00:00Z",
+ });
+ const res = renderDigest(vault, {
+ format: "markdown",
+ since: new Date("2026-05-24T00:00:00Z"),
+ until: new Date("2026-05-25T00:00:00Z"),
+ });
+ expect(res.content).toContain("## Actions");
+ expect(res.content).toContain("[dedup]");
+ expect(res.content).toContain("pref-alpha");
+ });
+
+ test("JSON payload exposes the actions list even when the window is empty", () => {
+ // No window-active items - the JSON still carries the full
+ // shape, including the (vault-state) actions array. Operators
+ // and downstream consumers can read it without checking the
+ // emptiness flag first.
+ writePref("a", {
+ topic: "x",
+ principle: "y",
+ created_at: "2026-01-01T00:00:00Z",
+ });
+ writePref("b", {
+ topic: "x",
+ principle: "y",
+ created_at: "2026-02-01T00:00:00Z",
+ });
+ const json = renderDigest(vault, {
+ format: "json",
+ since: new Date("2026-05-24T00:00:00Z"),
+ until: new Date("2026-05-25T00:00:00Z"),
+ });
+ const payload = JSON.parse(json.content) as {
+ actions: Array<{ category: string; impact: number }>;
+ };
+ expect(payload.actions.length).toBeGreaterThanOrEqual(1);
+ expect(payload.actions[0]!.category).toBe("dedup");
+ expect(payload.actions[0]!.impact).toBeGreaterThan(0);
+ });
+});
diff --git a/tests/core/brain/lint-consolidate.test.ts b/tests/core/brain/lint-consolidate.test.ts
new file mode 100644
index 00000000..6553a784
--- /dev/null
+++ b/tests/core/brain/lint-consolidate.test.ts
@@ -0,0 +1,197 @@
+import { afterEach, beforeEach, describe, 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 { lintConsolidate } from "../../../src/core/brain/lint-consolidate.ts";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-lint-"));
+ mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
+ mkdirSync(join(vault, "Brain", "retired"), { recursive: true });
+ mkdirSync(join(vault, "Brain", "log"), { recursive: true });
+});
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+function writePref(slug: string, fields: Record<string, string>) {
+ const lines = ["---", `id: pref-${slug}`];
+ for (const [k, v] of Object.entries(fields)) lines.push(`${k}: ${v}`);
+ lines.push("---", "");
+ writeFileSync(
+ join(vault, "Brain", "preferences", `pref-${slug}.md`),
+ lines.join("\n"),
+ );
+}
+
+describe("lintConsolidate — fix-merged-link", () => {
+ test("rewrites wikilinks pointing at a secondary", () => {
+ writePref("canon", { topic: "x", principle: "y" });
+ writePref("dup", { topic: "x", principle: "y", merged_into: "pref-canon" });
+ writeFileSync(
+ join(vault, "Brain", "log", "2026-05-25.md"),
+ "saw [[pref-dup]] today\n",
+ );
+
+ const dry = lintConsolidate(vault, { apply: false });
+ expect(dry.fixes.length).toBe(1);
+ expect(dry.fixes[0]!.from).toBe("pref-dup");
+ expect(dry.fixes[0]!.to).toBe("pref-canon");
+ expect(dry.applied).toBe(false);
+ // dry-run does not write
+ expect(
+ readFileSync(join(vault, "Brain", "log", "2026-05-25.md"), "utf8"),
+ ).toContain("[[pref-dup]]");
+
+ const apply = lintConsolidate(vault, { apply: true });
+ expect(apply.applied).toBe(true);
+ expect(apply.filesWritten).toBeGreaterThan(0);
+ expect(
+ readFileSync(join(vault, "Brain", "log", "2026-05-25.md"), "utf8"),
+ ).toContain("[[pref-canon]]");
+ });
+
+ test("preserves wikilink aliases and anchors when rewriting", () => {
+ writePref("canon", { topic: "x", principle: "y" });
+ writePref("dup", { topic: "x", principle: "y", merged_into: "pref-canon" });
+ writeFileSync(
+ join(vault, "Brain", "log", "2026-05-25.md"),
+ "[[pref-dup|the rule]] and [[pref-dup#section]]\n",
+ );
+ lintConsolidate(vault, { apply: true });
+ const content = readFileSync(
+ join(vault, "Brain", "log", "2026-05-25.md"),
+ "utf8",
+ );
+ expect(content).toContain("[[pref-canon|the rule]]");
+ expect(content).toContain("[[pref-canon#section]]");
+ });
+
+ test("does not rewrite wikilinks that merely share a prefix", () => {
+ writePref("canon", { topic: "x", principle: "y" });
+ writePref("dup", { topic: "x", principle: "y", merged_into: "pref-canon" });
+ writeFileSync(
+ join(vault, "Brain", "log", "2026-05-25.md"),
+ "real [[pref-dup]] vs [[pref-dup-extra]] vs [[pref-duplicate]]\n",
+ );
+ const report = lintConsolidate(vault, { apply: true });
+ expect(report.fixes.length).toBe(1);
+ const content = readFileSync(
+ join(vault, "Brain", "log", "2026-05-25.md"),
+ "utf8",
+ );
+ expect(content).toContain("[[pref-canon]]");
+ expect(content).toContain("[[pref-dup-extra]]");
+ expect(content).toContain("[[pref-duplicate]]");
+ expect(content).not.toMatch(/\[\[pref-dup\]\]/);
+ });
+});
+
+describe("lintConsolidate — demote-stale-stable", () => {
+ test("flags stable preferences older than the threshold", () => {
+ writePref("old", {
+ topic: "x",
+ principle: "y",
+ created_at: "2025-01-01T00:00:00Z",
+ _lifecycle: "stable",
+ });
+ writePref("recent", {
+ topic: "x",
+ principle: "y",
+ created_at: "2026-05-01T00:00:00Z",
+ _lifecycle: "stable",
+ });
+ const report = lintConsolidate(vault, {
+ apply: false,
+ now: new Date("2026-05-25T00:00:00Z"),
+ });
+ expect(report.demotions.map((d) => d.id)).toEqual(["pref-old"]);
+ });
+
+ test("does not demote stable preferences with recent evidence", () => {
+ writePref("evidenced", {
+ topic: "x",
+ principle: "y",
+ created_at: "2024-01-01T00:00:00Z",
+ _lifecycle: "stable",
+ _last_evidence_at: "2026-05-01T00:00:00Z",
+ });
+ const report = lintConsolidate(vault, {
+ apply: false,
+ now: new Date("2026-05-25T00:00:00Z"),
+ });
+ expect(report.demotions.length).toBe(0);
+ });
+
+ test("apply writes _lifecycle: draft on the demoted file", () => {
+ writePref("old", {
+ topic: "x",
+ principle: "y",
+ created_at: "2025-01-01T00:00:00Z",
+ _lifecycle: "stable",
+ });
+ lintConsolidate(vault, {
+ apply: true,
+ now: new Date("2026-05-25T00:00:00Z"),
+ });
+ const yaml = readFileSync(
+ join(vault, "Brain", "preferences", "pref-old.md"),
+ "utf8",
+ );
+ expect(yaml).toContain("_lifecycle: draft");
+ expect(yaml).not.toContain("_lifecycle: stable");
+ });
+
+ test("never demotes verified or deprecated lifecycles", () => {
+ writePref("verified", {
+ topic: "x",
+ principle: "y",
+ created_at: "2025-01-01T00:00:00Z",
+ _lifecycle: "verified",
+ });
+ writePref("deprecated", {
+ topic: "x",
+ principle: "y",
+ created_at: "2025-01-01T00:00:00Z",
+ _lifecycle: "deprecated",
+ });
+ const report = lintConsolidate(vault, {
+ apply: false,
+ now: new Date("2026-05-25T00:00:00Z"),
+ });
+ expect(report.demotions.length).toBe(0);
+ });
+
+ test("custom staleDays override is honoured", () => {
+ writePref("borderline", {
+ topic: "x",
+ principle: "y",
+ created_at: "2026-04-01T00:00:00Z",
+ _lifecycle: "stable",
+ });
+ const r = lintConsolidate(vault, {
+ apply: false,
+ staleDays: 30,
+ now: new Date("2026-05-25T00:00:00Z"),
+ });
+ expect(r.demotions.length).toBe(1);
+ });
+});
+
+describe("lintConsolidate — empty vault", () => {
+ test("reports zero across the board", () => {
+ const r = lintConsolidate(vault, { apply: false });
+ expect(r.fixes.length).toBe(0);
+ expect(r.demotions.length).toBe(0);
+ expect(r.filesWritten).toBe(0);
+ });
+});
diff --git a/tests/core/brain/maintenance/action-scorer.test.ts b/tests/core/brain/maintenance/action-scorer.test.ts
new file mode 100644
index 00000000..ad60024b
--- /dev/null
+++ b/tests/core/brain/maintenance/action-scorer.test.ts
@@ -0,0 +1,96 @@
+import { describe, expect, test } from "bun:test";
+
+import { scoreActions } from "../../../../src/core/brain/maintenance/action-scorer.ts";
+
+describe("scoreActions", () => {
+ test("empty inputs return empty list", () => {
+ expect(scoreActions({})).toEqual([]);
+ });
+
+ test("dedup impact scales linearly with secondaryCount", () => {
+ const items = scoreActions({
+ dedupCandidates: [
+ { canonicalId: "pref-a", secondaryCount: 1 },
+ { canonicalId: "pref-b", secondaryCount: 3 },
+ ],
+ });
+ expect(items.length).toBe(2);
+ // pref-b (3 secondaries) outranks pref-a (1 secondary)
+ expect(items[0]!.target).toBe("pref-b");
+ expect(items[1]!.target).toBe("pref-a");
+ expect(items[0]!.impact).toBeGreaterThan(items[1]!.impact);
+ });
+
+ test("stale lifecycle impact scales with age", () => {
+ const items = scoreActions({
+ staleByLifecycle: [
+ { id: "pref-old", ageDays: 365 * 2 },
+ { id: "pref-fresh-stale", ageDays: 200 },
+ ],
+ });
+ expect(items[0]!.target).toBe("pref-old");
+ });
+
+ test("broken links bucket by source path", () => {
+ const items = scoreActions({
+ brokenLinks: [
+ { path: "/x/log/a.md", from: "pref-x" },
+ { path: "/x/log/a.md", from: "pref-y" },
+ { path: "/x/log/b.md", from: "pref-z" },
+ ],
+ });
+ expect(items.length).toBe(2);
+ const a = items.find((i) => i.target === "/x/log/a.md")!;
+ const b = items.find((i) => i.target === "/x/log/b.md")!;
+ expect(a.impact).toBeGreaterThan(b.impact);
+ });
+
+ test("token footprint excess is zero below threshold", () => {
+ const items = scoreActions({
+ tokenFootprint: { total: 100, warnThreshold: 200_000 },
+ });
+ expect(items.length).toBe(0);
+ });
+
+ test("token footprint excess emits a single capped action", () => {
+ const items = scoreActions({
+ tokenFootprint: { total: 250_000, warnThreshold: 200_000 },
+ });
+ expect(items.length).toBe(1);
+ expect(items[0]!.category).toBe("token-footprint");
+ expect(items[0]!.target).toBe("vault");
+ });
+
+ test("topN caps the result", () => {
+ const items = scoreActions(
+ {
+ dedupCandidates: Array.from({ length: 15 }, (_, i) => ({
+ canonicalId: `pref-${i}`,
+ secondaryCount: 1,
+ })),
+ },
+ { topN: 5 },
+ );
+ expect(items.length).toBe(5);
+ });
+
+ test("results are ordered by impact descending then deterministic", () => {
+ const items = scoreActions({
+ dedupCandidates: [{ canonicalId: "pref-d1", secondaryCount: 1 }],
+ brokenLinks: [
+ { path: "/x/log/c.md", from: "pref-x" },
+ { path: "/x/log/c.md", from: "pref-y" },
+ ],
+ });
+ // both impacts: dedup = 1*8 = 8, brokenLinks bucket = 2*5 = 10
+ expect(items[0]!.category).toBe("merged-link");
+ expect(items[1]!.category).toBe("dedup");
+ });
+
+ test("dedupCandidate with zero secondaries is ignored", () => {
+ const items = scoreActions({
+ dedupCandidates: [{ canonicalId: "pref-a", secondaryCount: 0 }],
+ });
+ expect(items.length).toBe(0);
+ });
+});
diff --git a/tests/core/brain/page-dedup.test.ts b/tests/core/brain/page-dedup.test.ts
new file mode 100644
index 00000000..79dbdcf0
--- /dev/null
+++ b/tests/core/brain/page-dedup.test.ts
@@ -0,0 +1,205 @@
+import { afterEach, beforeEach, describe, 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 {
+ findDuplicateCandidates,
+ mergePage,
+ patchWikilinks,
+} from "../../../src/core/brain/page-dedup.ts";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-page-dedup-"));
+ mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
+ mkdirSync(join(vault, "Brain", "retired"), { recursive: true });
+ mkdirSync(join(vault, "Brain", "log"), { recursive: true });
+});
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+function writePref(
+ slug: string,
+ fields: { topic: string; principle: string; created_at?: string; merged_into?: string },
+): string {
+ const path = join(vault, "Brain", "preferences", `pref-${slug}.md`);
+ const lines = ["---", `id: pref-${slug}`, `topic: ${fields.topic}`, `principle: ${fields.principle}`];
+ if (fields.created_at) lines.push(`created_at: ${fields.created_at}`);
+ if (fields.merged_into) lines.push(`merged_into: ${fields.merged_into}`);
+ lines.push("---", "");
+ writeFileSync(path, lines.join("\n"));
+ return path;
+}
+
+describe("findDuplicateCandidates", () => {
+ test("returns empty when no duplicates", () => {
+ writePref("a", { topic: "x", principle: "alpha" });
+ writePref("b", { topic: "y", principle: "beta" });
+ const report = findDuplicateCandidates(vault);
+ expect(report.scanned).toBe(2);
+ expect(report.candidates.length).toBe(0);
+ });
+
+ test("groups by normalised topic+principle key", () => {
+ writePref("old", {
+ topic: "writing",
+ principle: "Use imperative voice",
+ created_at: "2026-01-01T00:00:00Z",
+ });
+ writePref("new", {
+ topic: "Writing",
+ principle: "USE IMPERATIVE VOICE",
+ created_at: "2026-05-01T00:00:00Z",
+ });
+ const report = findDuplicateCandidates(vault);
+ expect(report.candidates.length).toBe(1);
+ const c = report.candidates[0]!;
+ expect(c.pages.length).toBe(2);
+ // oldest wins
+ expect(c.canonical.id).toBe("pref-old");
+ expect(c.secondaries.map((s) => s.id)).toEqual(["pref-new"]);
+ });
+
+ test("collapses fullwidth and halfwidth variants", () => {
+ writePref("ascii", {
+ topic: "ru",
+ principle: "Hello",
+ created_at: "2026-01-01T00:00:00Z",
+ });
+ writePref("wide", {
+ topic: "ru",
+ principle: "Hello",
+ created_at: "2026-02-01T00:00:00Z",
+ });
+ const report = findDuplicateCandidates(vault);
+ expect(report.candidates.length).toBe(1);
+ expect(report.candidates[0]!.canonical.id).toBe("pref-ascii");
+ });
+
+ test("ignores singletons", () => {
+ writePref("a", { topic: "x", principle: "alpha" });
+ writePref("b", { topic: "x", principle: "beta" });
+ writePref("c", { topic: "x", principle: "alpha" });
+ const report = findDuplicateCandidates(vault);
+ expect(report.candidates.length).toBe(1);
+ expect(report.candidates[0]!.pages.map((p) => p.id).sort()).toEqual([
+ "pref-a",
+ "pref-c",
+ ]);
+ });
+});
+
+describe("patchWikilinks", () => {
+ test("rewrites plain [[oldTarget]] references", () => {
+ const log = join(vault, "Brain", "log", "2026-05-25.md");
+ writeFileSync(log, "see [[pref-old]] for context\n");
+ const touched = patchWikilinks(vault, "pref-old", "pref-new");
+ expect(touched).toBe(1);
+ expect(readFileSync(log, "utf8")).toContain("[[pref-new]]");
+ });
+
+ test("rewrites aliased and anchored wikilinks", () => {
+ const log = join(vault, "Brain", "log", "2026-05-25.md");
+ writeFileSync(
+ log,
+ "[[pref-old|the rule]] and [[pref-old#section]] and [[pref-old]]\n",
+ );
+ const touched = patchWikilinks(vault, "pref-old", "pref-new");
+ expect(touched).toBe(1);
+ const content = readFileSync(log, "utf8");
+ expect(content).toContain("[[pref-new|the rule]]");
+ expect(content).toContain("[[pref-new#section]]");
+ expect(content).toContain("[[pref-new]]");
+ expect(content).not.toContain("pref-old");
+ });
+
+ test("does not rewrite when nothing matches", () => {
+ const log = join(vault, "Brain", "log", "2026-05-25.md");
+ writeFileSync(log, "nothing relevant here\n");
+ const touched = patchWikilinks(vault, "pref-old", "pref-new");
+ expect(touched).toBe(0);
+ });
+
+ test("identity rewrite is a no-op", () => {
+ const log = join(vault, "Brain", "log", "2026-05-25.md");
+ writeFileSync(log, "[[pref-x]]\n");
+ const touched = patchWikilinks(vault, "pref-x", "pref-x");
+ expect(touched).toBe(0);
+ });
+
+ test("does not rewrite wikilinks that merely share a prefix", () => {
+ // Patching `pref-old` must NOT touch `[[pref-old-extra]]` or
+ // `[[pref-older]]` - those are distinct identities that just
+ // happen to start with the same substring. The lookahead in
+ // the patcher's regex defends this; pin it explicitly so a
+ // future regex rewrite cannot regress the case.
+ const log = join(vault, "Brain", "log", "2026-05-25.md");
+ writeFileSync(
+ log,
+ "matches [[pref-old]] and skips [[pref-old-extra]] and [[pref-older]]\n",
+ );
+ const touched = patchWikilinks(vault, "pref-old", "pref-new");
+ expect(touched).toBe(1);
+ const content = readFileSync(log, "utf8");
+ expect(content).toContain("[[pref-new]]");
+ expect(content).toContain("[[pref-old-extra]]");
+ expect(content).toContain("[[pref-older]]");
+ expect(content).not.toMatch(/\[\[pref-old\]\]/);
+ });
+});
+
+describe("mergePage", () => {
+ test("stamps merged_into on the secondary and rewrites wikilinks", () => {
+ const oldPath = writePref("old", {
+ topic: "writing",
+ principle: "Use imperative voice",
+ created_at: "2026-01-01T00:00:00Z",
+ });
+ writePref("new", {
+ topic: "writing",
+ principle: "Use imperative voice",
+ created_at: "2026-05-01T00:00:00Z",
+ });
+ const log = join(vault, "Brain", "log", "2026-05-25.md");
+ writeFileSync(log, "applied [[pref-new]] today\n");
+
+ const res = mergePage(vault, "pref-new", "pref-old");
+ expect(res.canonical).toBe("pref-old");
+ expect(res.secondary).toBe("pref-new");
+ expect(res.wikilinksUpdated).toBe(1);
+
+ const newPath = join(vault, "Brain", "preferences", "pref-new.md");
+ expect(readFileSync(newPath, "utf8")).toContain("merged_into: pref-old");
+ expect(readFileSync(log, "utf8")).toContain("[[pref-old]]");
+ // canonical untouched
+ expect(readFileSync(oldPath, "utf8")).not.toContain("merged_into:");
+ });
+
+ test("second merge is idempotent (no extra wikilink rewrites)", () => {
+ writePref("canon", {
+ topic: "x",
+ principle: "y",
+ created_at: "2026-01-01T00:00:00Z",
+ });
+ writePref("dup", {
+ topic: "x",
+ principle: "y",
+ created_at: "2026-02-01T00:00:00Z",
+ });
+ const log = join(vault, "Brain", "log", "2026-05-25.md");
+ writeFileSync(log, "[[pref-dup]]\n");
+ const first = mergePage(vault, "pref-dup", "pref-canon");
+ expect(first.wikilinksUpdated).toBe(1);
+ const second = mergePage(vault, "pref-dup", "pref-canon");
+ expect(second.wikilinksUpdated).toBe(0);
+ });
+});
diff --git a/tests/core/brain/page-meta/confidence.test.ts b/tests/core/brain/page-meta/confidence.test.ts
new file mode 100644
index 00000000..56397e46
--- /dev/null
+++ b/tests/core/brain/page-meta/confidence.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+ BRAIN_CONFIDENCE,
+ isPageConfidence,
+ readConfidence,
+} from "../../../../src/core/brain/page-meta/confidence.ts";
+
+describe("PAGE_CONFIDENCE", () => {
+ test("BRAIN_CONFIDENCE values are accepted", () => {
+ for (const v of Object.values(BRAIN_CONFIDENCE)) {
+ expect(isPageConfidence(v)).toBe(true);
+ }
+ });
+
+ test("rejects junk", () => {
+ expect(isPageConfidence("HIGH")).toBe(false);
+ expect(isPageConfidence("super")).toBe(false);
+ expect(isPageConfidence(undefined)).toBe(false);
+ expect(isPageConfidence(0.9)).toBe(false);
+ });
+});
+
+describe("readConfidence", () => {
+ test("returns _confidence when present", () => {
+ expect(readConfidence({ _confidence: "high" })).toBe("high");
+ expect(readConfidence({ _confidence: "medium" })).toBe("medium");
+ });
+
+ test("falls back to legacy key", () => {
+ expect(readConfidence({ confidence: "high" })).toBe("high");
+ });
+
+ test("defaults to low when missing or unrecognised", () => {
+ expect(readConfidence({})).toBe("low");
+ expect(readConfidence({ _confidence: "extreme" })).toBe("low");
+ });
+
+ test("modern shape wins over legacy", () => {
+ expect(readConfidence({ _confidence: "high", confidence: "low" })).toBe(
+ "high",
+ );
+ });
+});
diff --git a/tests/core/brain/page-meta/lifecycle.test.ts b/tests/core/brain/page-meta/lifecycle.test.ts
new file mode 100644
index 00000000..ed2db53b
--- /dev/null
+++ b/tests/core/brain/page-meta/lifecycle.test.ts
@@ -0,0 +1,110 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+ PAGE_LIFECYCLE,
+ PAGE_STALE_DAYS_DEFAULT,
+ ageDaysFromIso,
+ isPageLifecycle,
+ isStale,
+ readLifecycle,
+} from "../../../../src/core/brain/page-meta/lifecycle.ts";
+
+describe("PAGE_LIFECYCLE", () => {
+ test("enumerates exactly the six documented values", () => {
+ expect(Object.values(PAGE_LIFECYCLE).sort()).toEqual([
+ "archived",
+ "deprecated",
+ "disputed",
+ "draft",
+ "stable",
+ "verified",
+ ]);
+ });
+
+ test("isPageLifecycle accepts each canonical value", () => {
+ for (const v of Object.values(PAGE_LIFECYCLE)) {
+ expect(isPageLifecycle(v)).toBe(true);
+ }
+ });
+
+ test("isPageLifecycle rejects junk", () => {
+ expect(isPageLifecycle("draft ")).toBe(false);
+ expect(isPageLifecycle("DRAFT")).toBe(false);
+ expect(isPageLifecycle("retired")).toBe(false);
+ expect(isPageLifecycle(undefined)).toBe(false);
+ expect(isPageLifecycle(null)).toBe(false);
+ expect(isPageLifecycle(0)).toBe(false);
+ });
+});
+
+describe("readLifecycle", () => {
+ test("returns _lifecycle when present", () => {
+ expect(readLifecycle({ _lifecycle: "verified" })).toBe("verified");
+ });
+
+ test("falls back to legacy lifecycle key when _-prefixed absent", () => {
+ expect(readLifecycle({ lifecycle: "deprecated" })).toBe("deprecated");
+ });
+
+ test("defaults to stable when both absent", () => {
+ expect(readLifecycle({})).toBe("stable");
+ expect(readLifecycle({ topic: "x" })).toBe("stable");
+ });
+
+ test("defaults to stable on unknown value", () => {
+ expect(readLifecycle({ _lifecycle: "rotten" })).toBe("stable");
+ });
+
+ test("modern shape wins over legacy", () => {
+ expect(
+ readLifecycle({ _lifecycle: "verified", lifecycle: "draft" }),
+ ).toBe("verified");
+ });
+});
+
+describe("isStale", () => {
+ test("returns false when ageDays is below the threshold", () => {
+ expect(isStale("stable", 10)).toBe(false);
+ expect(isStale("draft", 100)).toBe(false);
+ });
+
+ test("returns true for stable past threshold", () => {
+ expect(isStale("stable", 200)).toBe(true);
+ expect(isStale("stable", PAGE_STALE_DAYS_DEFAULT)).toBe(true);
+ });
+
+ test("returns true for draft past threshold", () => {
+ expect(isStale("draft", 365)).toBe(true);
+ });
+
+ test("never reports verified or deprecated as stale", () => {
+ expect(isStale("verified", 9999)).toBe(false);
+ expect(isStale("deprecated", 9999)).toBe(false);
+ });
+
+ test("archived and disputed are not stale (they have their own meaning)", () => {
+ expect(isStale("archived", 9999)).toBe(false);
+ expect(isStale("disputed", 9999)).toBe(false);
+ });
+
+ test("honours an explicit threshold override", () => {
+ expect(isStale("stable", 50, 30)).toBe(true);
+ expect(isStale("stable", 50, 100)).toBe(false);
+ });
+});
+
+describe("ageDaysFromIso", () => {
+ test("computes days between an ISO timestamp and now", () => {
+ const now = new Date("2026-05-25T00:00:00Z");
+ expect(ageDaysFromIso("2026-05-20T00:00:00Z", now)).toBe(5);
+ expect(ageDaysFromIso("2025-11-26T00:00:00Z", now)).toBeCloseTo(180, 0);
+ });
+
+ test("returns Infinity for missing or unparseable timestamps", () => {
+ const now = new Date("2026-05-25T00:00:00Z");
+ expect(ageDaysFromIso(undefined, now)).toBe(Infinity);
+ expect(ageDaysFromIso(null, now)).toBe(Infinity);
+ expect(ageDaysFromIso("", now)).toBe(Infinity);
+ expect(ageDaysFromIso("not-a-date", now)).toBe(Infinity);
+ });
+});
diff --git a/tests/core/brain/page-meta/page-id.test.ts b/tests/core/brain/page-meta/page-id.test.ts
new file mode 100644
index 00000000..5a4ca901
--- /dev/null
+++ b/tests/core/brain/page-meta/page-id.test.ts
@@ -0,0 +1,154 @@
+import { afterEach, beforeEach, describe, 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 {
+ MERGE_CHAIN_MAX_DEPTH,
+ MergeChainError,
+ readMergedInto,
+ resolveCanonicalId,
+ setMergedInto,
+} from "../../../../src/core/brain/page-meta/page-id.ts";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-page-id-"));
+ mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
+ mkdirSync(join(vault, "Brain", "retired"), { recursive: true });
+});
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+function writePref(slug: string, frontmatter: Record<string, string>) {
+ const path = join(vault, "Brain", "preferences", `pref-${slug}.md`);
+ const yamlLines = ["---", `id: pref-${slug}`];
+ for (const [k, v] of Object.entries(frontmatter)) yamlLines.push(`${k}: ${v}`);
+ yamlLines.push("---", "");
+ writeFileSync(path, yamlLines.join("\n"));
+ return path;
+}
+
+describe("readMergedInto", () => {
+ test("returns the canonical id when present", () => {
+ expect(readMergedInto({ merged_into: "pref-foo" })).toBe("pref-foo");
+ });
+
+ test("trims whitespace", () => {
+ expect(readMergedInto({ merged_into: " pref-foo " })).toBe("pref-foo");
+ });
+
+ test("returns null when absent or non-string", () => {
+ expect(readMergedInto({})).toBeNull();
+ expect(readMergedInto({ merged_into: "" })).toBeNull();
+ expect(readMergedInto({ merged_into: " " })).toBeNull();
+ expect(readMergedInto({ merged_into: 123 as unknown })).toBeNull();
+ });
+});
+
+describe("resolveCanonicalId", () => {
+ test("returns the starting id when the page has no merged_into", () => {
+ writePref("a", { topic: "x", principle: "y" });
+ expect(resolveCanonicalId(vault, "pref-a")).toBe("pref-a");
+ });
+
+ test("follows a single-hop merged_into pointer", () => {
+ writePref("canonical", { topic: "x", principle: "y" });
+ writePref("secondary", { topic: "x", principle: "y", merged_into: "pref-canonical" });
+ expect(resolveCanonicalId(vault, "pref-secondary")).toBe("pref-canonical");
+ });
+
+ test("follows a multi-hop chain", () => {
+ writePref("c", { topic: "x", principle: "y" });
+ writePref("b", { topic: "x", principle: "y", merged_into: "pref-c" });
+ writePref("a", { topic: "x", principle: "y", merged_into: "pref-b" });
+ expect(resolveCanonicalId(vault, "pref-a")).toBe("pref-c");
+ });
+
+ test("returns dangling id when target file does not exist", () => {
+ writePref("a", { topic: "x", principle: "y", merged_into: "pref-missing" });
+ expect(resolveCanonicalId(vault, "pref-a")).toBe("pref-missing");
+ });
+
+ test("throws CYCLE on a self-loop", () => {
+ writePref("a", { topic: "x", principle: "y", merged_into: "pref-a" });
+ expect(() => resolveCanonicalId(vault, "pref-a")).toThrow(MergeChainError);
+ });
+
+ test("throws CYCLE on a multi-page cycle", () => {
+ writePref("a", { topic: "x", principle: "y", merged_into: "pref-b" });
+ writePref("b", { topic: "x", principle: "y", merged_into: "pref-a" });
+ try {
+ resolveCanonicalId(vault, "pref-a");
+ throw new Error("expected throw");
+ } catch (e) {
+ expect(e).toBeInstanceOf(MergeChainError);
+ expect((e as MergeChainError).code).toBe("CYCLE");
+ }
+ });
+
+ test("throws DEPTH on a chain longer than MERGE_CHAIN_MAX_DEPTH", () => {
+ // Build a chain of MAX_DEPTH + 2 pages so the walker bails out.
+ const n = MERGE_CHAIN_MAX_DEPTH + 2;
+ for (let i = 0; i < n; i++) {
+ const target = i + 1 < n ? `pref-p${i + 1}` : undefined;
+ writePref(
+ `p${i}`,
+ target ? { topic: "x", principle: "y", merged_into: target } : { topic: "x", principle: "y" },
+ );
+ }
+ try {
+ resolveCanonicalId(vault, "pref-p0");
+ throw new Error("expected throw");
+ } catch (e) {
+ expect(e).toBeInstanceOf(MergeChainError);
+ expect((e as MergeChainError).code).toBe("DEPTH");
+ }
+ });
+
+ test("throws MALFORMED on an unknown-prefix id", () => {
+ expect(() => resolveCanonicalId(vault, "garbage-x")).toThrow(MergeChainError);
+ });
+});
+
+describe("setMergedInto", () => {
+ test("writes the pointer when absent", () => {
+ writePref("canonical", { topic: "x", principle: "y" });
+ const path = writePref("secondary", { topic: "x", principle: "y" });
+ setMergedInto(vault, "pref-secondary", "pref-canonical");
+ expect(readFileSync(path, "utf8")).toContain("merged_into: pref-canonical");
+ });
+
+ test("updates an existing pointer", () => {
+ writePref("a", { topic: "x", principle: "y" });
+ writePref("b", { topic: "x", principle: "y" });
+ const path = writePref("c", {
+ topic: "x",
+ principle: "y",
+ merged_into: "pref-a",
+ });
+ setMergedInto(vault, "pref-c", "pref-b");
+ const yaml = readFileSync(path, "utf8");
+ expect(yaml).toContain("merged_into: pref-b");
+ expect(yaml).not.toContain("merged_into: pref-a");
+ });
+
+ test("rejects self-pointer", () => {
+ writePref("a", { topic: "x", principle: "y" });
+ expect(() => setMergedInto(vault, "pref-a", "pref-a")).toThrow(MergeChainError);
+ });
+
+ test("rejects missing secondary", () => {
+ expect(() => setMergedInto(vault, "pref-nope", "pref-foo")).toThrow(MergeChainError);
+ });
+
+ test("written page remains readable through the merge chain", () => {
+ writePref("c", { topic: "x", principle: "y" });
+ writePref("b", { topic: "x", principle: "y" });
+ setMergedInto(vault, "pref-b", "pref-c");
+ expect(resolveCanonicalId(vault, "pref-b")).toBe("pref-c");
+ expect(existsSync(join(vault, "Brain", "preferences", "pref-b.md"))).toBe(true);
+ });
+});
diff --git a/tests/core/brain/page-meta/tier.test.ts b/tests/core/brain/page-meta/tier.test.ts
new file mode 100644
index 00000000..629927f7
--- /dev/null
+++ b/tests/core/brain/page-meta/tier.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+ PAGE_TIER,
+ PAGE_TIER_DEFAULT,
+ isPageTier,
+ readTier,
+ tierWeight,
+} from "../../../../src/core/brain/page-meta/tier.ts";
+
+describe("PAGE_TIER", () => {
+ test("exposes exactly three tiers", () => {
+ expect(Object.values(PAGE_TIER).sort()).toEqual([
+ "core",
+ "peripheral",
+ "supporting",
+ ]);
+ });
+
+ test("default is supporting", () => {
+ expect(PAGE_TIER_DEFAULT).toBe("supporting");
+ });
+
+ test("isPageTier predicate", () => {
+ expect(isPageTier("core")).toBe(true);
+ expect(isPageTier("supporting")).toBe(true);
+ expect(isPageTier("peripheral")).toBe(true);
+ expect(isPageTier("primary")).toBe(false);
+ expect(isPageTier(undefined)).toBe(false);
+ });
+});
+
+describe("readTier", () => {
+ test("reads `tier` from frontmatter", () => {
+ expect(readTier({ tier: "core" })).toBe("core");
+ expect(readTier({ tier: "peripheral" })).toBe("peripheral");
+ });
+
+ test("defaults to supporting when missing", () => {
+ expect(readTier({})).toBe("supporting");
+ });
+
+ test("defaults to supporting on typo", () => {
+ expect(readTier({ tier: "Core" })).toBe("supporting");
+ expect(readTier({ tier: "cor" })).toBe("supporting");
+ });
+});
+
+describe("tierWeight", () => {
+ test("supporting is the identity weight", () => {
+ expect(tierWeight("supporting")).toBe(1.0);
+ });
+
+ test("core boosts above supporting", () => {
+ expect(tierWeight("core")).toBeGreaterThan(tierWeight("supporting"));
+ });
+
+ test("peripheral discounts below supporting", () => {
+ expect(tierWeight("peripheral")).toBeLessThan(tierWeight("supporting"));
+ });
+
+ test("each weight is positive", () => {
+ expect(tierWeight("core")).toBeGreaterThan(0);
+ expect(tierWeight("peripheral")).toBeGreaterThan(0);
+ });
+});
diff --git a/tests/core/brain/preference-lifecycle.test.ts b/tests/core/brain/preference-lifecycle.test.ts
new file mode 100644
index 00000000..69206938
--- /dev/null
+++ b/tests/core/brain/preference-lifecycle.test.ts
@@ -0,0 +1,106 @@
+/**
+ * Coverage for the per-page `_lifecycle` frontmatter emission added
+ * in v0.10.15. Default-case absence is the backwards-compat anchor:
+ * callers that do not supply `lifecycle` keep producing byte-identical
+ * output so existing fixtures and tests stay green.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ parsePreference,
+ writePreference,
+ type WritePreferenceInput,
+} from "../../../src/core/brain/preference.ts";
+import { readLifecycle } from "../../../src/core/brain/page-meta/lifecycle.ts";
+import { parseFrontmatter } from "../../../src/core/vault.ts";
+import {
+ BRAIN_CONFIDENCE,
+ BRAIN_PREFERENCE_STATUS,
+} from "../../../src/core/brain/types.ts";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-pref-lifecycle-"));
+ mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
+});
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+function basePref(
+ slug: string,
+ overrides: Partial<WritePreferenceInput> = {},
+): WritePreferenceInput {
+ return {
+ slug,
+ topic: "writing",
+ principle: `Principle for ${slug}`,
+ created_at: "2026-05-01T00:00:00Z",
+ unconfirmed_until: "2026-05-08T00:00:00Z",
+ status: BRAIN_PREFERENCE_STATUS.confirmed,
+ evidenced_by: [`[[sig-2026-05-01-${slug}]]`],
+ confirmed_at: "2026-05-02T00:00:00Z",
+ applied_count: 1,
+ violated_count: 0,
+ last_evidence_at: "2026-05-02T00:00:00Z",
+ confidence: BRAIN_CONFIDENCE.high,
+ confidence_value: 0.8,
+ pinned: false,
+ ...overrides,
+ };
+}
+
+describe("writePreference — _lifecycle emission", () => {
+ test("does NOT emit _lifecycle when caller omits the field", () => {
+ const res = writePreference(vault, basePref("legacy"));
+ const yaml = readFileSync(res.path, "utf8");
+ expect(yaml).not.toContain("_lifecycle:");
+ expect(yaml).not.toContain("lifecycle:");
+ });
+
+ test("emits _lifecycle when caller supplies it", () => {
+ const res = writePreference(vault, basePref("modern", { lifecycle: "verified" }));
+ const yaml = readFileSync(res.path, "utf8");
+ expect(yaml).toContain("_lifecycle: verified");
+ });
+
+ test("default lifecycle for parsed legacy file is stable (via readLifecycle)", () => {
+ const res = writePreference(vault, basePref("legacy2"));
+ const pref = parsePreference(res.path);
+ expect(pref).toBeDefined();
+ // Confirm the actual default contract: the read-side helper
+ // returns `stable` when the field is absent on disk.
+ const [meta] = parseFrontmatter(res.path);
+ expect(readLifecycle(meta)).toBe("stable");
+ const yaml = readFileSync(res.path, "utf8");
+ expect(yaml).not.toMatch(/^_lifecycle:/m);
+ });
+
+ test("byte-identical second write when lifecycle is omitted both times", () => {
+ const res = writePreference(vault, basePref("idem"));
+ const first = readFileSync(res.path, "utf8");
+ writePreference(vault, basePref("idem"), { overwrite: true });
+ const second = readFileSync(res.path, "utf8");
+ expect(second).toBe(first);
+ });
+
+ test("byte-identical second write when lifecycle is supplied both times", () => {
+ const res = writePreference(
+ vault,
+ basePref("idem-mod", { lifecycle: "verified" }),
+ );
+ const first = readFileSync(res.path, "utf8");
+ writePreference(
+ vault,
+ basePref("idem-mod", { lifecycle: "verified" }),
+ { overwrite: true },
+ );
+ const second = readFileSync(res.path, "utf8");
+ expect(second).toBe(first);
+ });
+});
diff --git a/tests/core/brain/text/normalize.test.ts b/tests/core/brain/text/normalize.test.ts
new file mode 100644
index 00000000..bcb13d50
--- /dev/null
+++ b/tests/core/brain/text/normalize.test.ts
@@ -0,0 +1,59 @@
+/**
+ * Tests for `normalizeForDedup` — the NFKC + casefold helper that
+ * dedup-hash and other key-construction sites call before hashing or
+ * comparing inputs. Behaviour invariants below pin the cases that
+ * the previous `normalize("NFC")` call missed.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { normalizeForDedup } from "../../../../src/core/brain/text/normalize.ts";
+
+describe("normalizeForDedup", () => {
+ test("collapses fullwidth and halfwidth Latin to the same form", () => {
+ const halfwidth = normalizeForDedup("Hello");
+ const fullwidth = normalizeForDedup("Hello");
+ expect(fullwidth).toBe(halfwidth);
+ });
+
+ test("collapses uppercase and lowercase to the same form", () => {
+ expect(normalizeForDedup("Hello")).toBe(normalizeForDedup("hello"));
+ expect(normalizeForDedup("HELLO")).toBe(normalizeForDedup("hello"));
+ });
+
+ test("collapses NFD (decomposed) and NFC (precomposed) accents", () => {
+ // é can be written as U+00E9 (NFC) or U+0065 U+0301 (NFD).
+ const precomposed = normalizeForDedup("café");
+ const decomposed = normalizeForDedup("café");
+ expect(precomposed).toBe(decomposed);
+ });
+
+ test("preserves CJK content without collapsing to empty string", () => {
+ const out = normalizeForDedup("テスト");
+ expect(out.length).toBeGreaterThan(0);
+ expect(out).toContain("テスト");
+ });
+
+ test("preserves Cyrillic content with case folding", () => {
+ expect(normalizeForDedup("Тест")).toBe(normalizeForDedup("тест"));
+ expect(normalizeForDedup("ТЕСТ")).toBe(normalizeForDedup("тест"));
+ });
+
+ test("idempotent — applying twice equals once", () => {
+ const inputs = ["Hello", "テスト", "café", "Тест", "H"];
+ for (const s of inputs) {
+ const once = normalizeForDedup(s);
+ const twice = normalizeForDedup(once);
+ expect(twice).toBe(once);
+ }
+ });
+
+ test("does not strip whitespace or punctuation", () => {
+ const out = normalizeForDedup("a b; c");
+ expect(out).toBe("a b; c");
+ });
+
+ test("handles empty string", () => {
+ expect(normalizeForDedup("")).toBe("");
+ });
+});
diff --git a/tests/core/brain/text/tokenizer.test.ts b/tests/core/brain/text/tokenizer.test.ts
new file mode 100644
index 00000000..c0dce2fa
--- /dev/null
+++ b/tests/core/brain/text/tokenizer.test.ts
@@ -0,0 +1,80 @@
+import { describe, expect, test } from "bun:test";
+
+import { estimateTokens } from "../../../../src/core/brain/text/tokenizer.ts";
+
+// The heuristic is `ceil(utf8_bytes / 4)`, so tests assert language-
+// agnostic invariants (determinism, monotonicity, non-zero on
+// non-empty input) plus a handful of computed byte-based ground
+// truths. No script-specific magic numbers - the implementation
+// must not special-case any human language.
+
+const utf8Len = (s: string) => new TextEncoder().encode(s).length;
+
+describe("estimateTokens", () => {
+ test("empty input returns 0", () => {
+ expect(estimateTokens("")).toBe(0);
+ });
+
+ test("matches ceil(utf8_bytes / 4) for ASCII", () => {
+ const s = "Use imperative voice";
+ expect(estimateTokens(s)).toBe(Math.ceil(utf8Len(s) / 4));
+ });
+
+ test("matches ceil(utf8_bytes / 4) for arbitrary multibyte scripts", () => {
+ // No script is special-cased: the formula must hold for every
+ // input, regardless of which scripts it mixes.
+ const samples = [
+ "Hello", // Latin ASCII
+ "café au lait", // Latin extended (NFC)
+ "Тест", // Cyrillic
+ "テスト", // Hiragana / Katakana
+ "안녕하세요", // Hangul
+ "مرحبا", // Arabic
+ "สวัสดี", // Thai (with combining marks)
+ "नमस्ते", // Devanagari (Hindi)
+ "アイウ", // Halfwidth katakana
+ "🦊🚀", // Emoji
+ "Hello テスト مرحبا 🦊", // Mixed
+ ];
+ for (const s of samples) {
+ expect(estimateTokens(s)).toBe(Math.ceil(utf8Len(s) / 4));
+ }
+ });
+
+ test("non-empty input always yields at least one token", () => {
+ const samples = ["a", "テ", "🦊", " ", "."];
+ for (const s of samples) {
+ expect(estimateTokens(s)).toBeGreaterThanOrEqual(1);
+ }
+ });
+
+ test("monotonic - concatenating strings can only grow the count", () => {
+ const a = "alpha beta gamma";
+ const b = " delta epsilon";
+ expect(estimateTokens(a + b)).toBeGreaterThanOrEqual(estimateTokens(a));
+ });
+
+ test("deterministic across runs", () => {
+ const sample = "The quick brown fox jumps over the lazy dog 123 #tag テスト";
+ expect(estimateTokens(sample)).toBe(estimateTokens(sample));
+ });
+
+ test("scales linearly with repetition", () => {
+ const single = "word ";
+ const x100 = single.repeat(100);
+ // 100 repetitions of the same byte sequence yields exactly 100
+ // times the byte count, so the heuristic is linear.
+ expect(estimateTokens(x100)).toBe(Math.ceil(utf8Len(x100) / 4));
+ });
+
+ test("no special-case for any script - equal byte length yields equal count", () => {
+ // Construct two inputs in different scripts that share a byte
+ // length, then assert the heuristic ignores which script they
+ // come from.
+ const cyrillic = "тестт";
+ const len = utf8Len(cyrillic);
+ const ascii = "x".repeat(len);
+ expect(utf8Len(ascii)).toBe(len);
+ expect(estimateTokens(cyrillic)).toBe(estimateTokens(ascii));
+ });
+});
diff --git a/tests/core/brain/token-footprint.test.ts b/tests/core/brain/token-footprint.test.ts
new file mode 100644
index 00000000..50484983
--- /dev/null
+++ b/tests/core/brain/token-footprint.test.ts
@@ -0,0 +1,109 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ TOKEN_WARN_THRESHOLD_DEFAULT,
+ computeTokenFootprint,
+} from "../../../src/core/brain/token-footprint.ts";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-token-footprint-"));
+ mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
+ mkdirSync(join(vault, "Brain", "retired"), { recursive: true });
+ mkdirSync(join(vault, "Brain", "inbox", "processed"), { recursive: true });
+ mkdirSync(join(vault, "Brain", "log"), { recursive: true });
+});
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+describe("computeTokenFootprint", () => {
+ test("empty vault reports zero with the default threshold", () => {
+ const r = computeTokenFootprint(vault);
+ expect(r.total).toBe(0);
+ expect(r.files).toBe(0);
+ expect(r.warnThreshold).toBe(TOKEN_WARN_THRESHOLD_DEFAULT);
+ expect(r.exceeded).toBe(false);
+ });
+
+ test("counts preferences, retired, inbox, processed, log buckets", () => {
+ writeFileSync(
+ join(vault, "Brain", "preferences", "pref-a.md"),
+ "alpha beta gamma\n",
+ );
+ writeFileSync(
+ join(vault, "Brain", "retired", "ret-b.md"),
+ "delta epsilon\n",
+ );
+ writeFileSync(
+ join(vault, "Brain", "inbox", "sig-c.md"),
+ "zeta eta theta iota\n",
+ );
+ writeFileSync(
+ join(vault, "Brain", "inbox", "processed", "sig-d.md"),
+ "kappa lambda\n",
+ );
+ writeFileSync(
+ join(vault, "Brain", "log", "2026-05-25.md"),
+ "mu nu xi omicron\n",
+ );
+ const r = computeTokenFootprint(vault);
+ expect(r.files).toBe(5);
+ const names = r.byCategory.map((c) => c.name);
+ expect(names).toContain("preferences");
+ expect(names).toContain("retired");
+ expect(names).toContain("inbox");
+ expect(names).toContain("processed");
+ expect(names).toContain("log");
+ expect(r.total).toBeGreaterThan(0);
+ });
+
+ test("processed pages are NOT double-counted by the inbox walker", () => {
+ // The inbox dir contains processed/ as a subdir; the inbox sum
+ // would naturally recurse into it. The processed bucket counts
+ // those files separately, so the total must equal the sum of
+ // both buckets exactly.
+ writeFileSync(
+ join(vault, "Brain", "inbox", "sig-a.md"),
+ "alpha beta gamma\n",
+ );
+ writeFileSync(
+ join(vault, "Brain", "inbox", "processed", "sig-b.md"),
+ "delta epsilon zeta\n",
+ );
+ const r = computeTokenFootprint(vault);
+ const inbox = r.byCategory.find((c) => c.name === "inbox")!.tokens;
+ const processed = r.byCategory.find((c) => c.name === "processed")!.tokens;
+ expect(r.total).toBe(inbox + processed);
+ });
+
+ test("exceeded flag flips when total crosses the threshold", () => {
+ writeFileSync(
+ join(vault, "Brain", "preferences", "pref-big.md"),
+ "word ".repeat(50),
+ );
+ const r = computeTokenFootprint(vault, { warnThreshold: 1 });
+ expect(r.exceeded).toBe(true);
+ });
+
+ test("env override is honoured", () => {
+ const r = computeTokenFootprint(vault, { envWarnThreshold: "5000" });
+ expect(r.warnThreshold).toBe(5000);
+ });
+
+ test("malformed env value falls back to default", () => {
+ const r = computeTokenFootprint(vault, { envWarnThreshold: "garbage" });
+ expect(r.warnThreshold).toBe(TOKEN_WARN_THRESHOLD_DEFAULT);
+ });
+
+ test("'other' bucket captures stray Brain/*.md files only", () => {
+ writeFileSync(join(vault, "Brain", "active.md"), "alpha beta\n");
+ const r = computeTokenFootprint(vault);
+ const other = r.byCategory.find((c) => c.name === "other")!;
+ expect(other.files).toBeGreaterThanOrEqual(1);
+ });
+});
diff --git a/tests/core/search/ranker-tier.test.ts b/tests/core/search/ranker-tier.test.ts
new file mode 100644
index 00000000..895d0b66
--- /dev/null
+++ b/tests/core/search/ranker-tier.test.ts
@@ -0,0 +1,125 @@
+/**
+ * Coverage for the tier-aware ranker hook added in v0.10.15. The
+ * non-regression anchor: when `tierByDoc` is absent (or every entry
+ * is the default `supporting`), the ranker output is bit-identical
+ * to pre-tier behaviour. Distinct tiers re-order candidates with the
+ * relevance-only multiplier.
+ */
+
+import { test, expect } from "bun:test";
+
+import { rankResults } from "../../../src/core/search/ranker.ts";
+import type {
+ KeywordHit,
+ SemanticHit,
+ HydratedChunk,
+} from "../../../src/core/search/store.ts";
+
+function hyd(
+ chunkId: number,
+ docId: number,
+ mtime: number,
+): HydratedChunk {
+ return Object.freeze({
+ chunkId,
+ documentId: docId,
+ path: `doc${docId}.md`,
+ title: `Doc ${docId}`,
+ content: `chunk ${chunkId}`,
+ startLine: 1,
+ endLine: 1,
+ mtime,
+ });
+}
+
+const NOW = 1_750_000_000_000;
+const OLD = NOW / 1000 - 365 * 24 * 3600;
+
+function rank(
+ tierByDoc?: ReadonlyMap<number, "core" | "supporting" | "peripheral">,
+) {
+ // Varied bm25 values produce a non-degenerate normalized spread
+ // (min-max ≠ 0) so the tier multiplier has headroom below clamp01.
+ // Lower keyword weight keeps the weighted product comfortably
+ // below 1.0 for `core` * relevance.
+ const kw: KeywordHit[] = [
+ { chunkId: 1, documentId: 10, bm25: -2 },
+ { chunkId: 2, documentId: 11, bm25: -3 },
+ { chunkId: 3, documentId: 12, bm25: -4 },
+ ];
+ const sem: SemanticHit[] = [];
+ const hydrated = new Map<number, HydratedChunk>([
+ [1, hyd(1, 10, OLD)],
+ [2, hyd(2, 11, OLD)],
+ [3, hyd(3, 12, OLD)],
+ ]);
+ return rankResults(
+ {
+ keyword: kw,
+ semantic: sem,
+ hydrated,
+ inboundLinkSources: new Map(),
+ tagsByDoc: new Map(),
+ tierByDoc,
+ },
+ { keywordWeight: 1.0, semanticWeight: 0, limit: 10, nowMs: NOW },
+ );
+}
+
+test("absent tierByDoc behaves as if every doc is 'supporting'", () => {
+ const baseline = rank();
+ const allSupporting = rank(
+ new Map([
+ [10, "supporting"],
+ [11, "supporting"],
+ [12, "supporting"],
+ ]),
+ );
+ expect(allSupporting.length).toBe(baseline.length);
+ for (let i = 0; i < baseline.length; i++) {
+ expect(allSupporting[i]!.documentId).toBe(baseline[i]!.documentId);
+ expect(allSupporting[i]!.score).toBeCloseTo(baseline[i]!.score, 10);
+ }
+});
+
+test("core tier outranks supporting which outranks peripheral", () => {
+ const ranked = rank(
+ new Map([
+ [10, "peripheral"],
+ [11, "supporting"],
+ [12, "core"],
+ ]),
+ );
+ // tie-break is mtime desc + chunkId asc - all OLD/equal so tier
+ // multiplier alone drives ordering.
+ expect(ranked[0]!.documentId).toBe(12); // core
+ expect(ranked[1]!.documentId).toBe(11); // supporting
+ expect(ranked[2]!.documentId).toBe(10); // peripheral
+});
+
+test("unknown tier entries silently fall back to supporting", () => {
+ // Type system forbids invalid tier strings at compile time; this
+ // case covers a doc that is simply absent from tierByDoc, which
+ // is the realistic "not yet tagged" scenario.
+ const ranked = rank(
+ new Map([
+ // 10 missing -> supporting (fallback)
+ [11, "supporting"],
+ [12, "core"],
+ ]),
+ );
+ expect(ranked[0]!.documentId).toBe(12); // core wins
+ // Relevance gradient (doc 12 best ... doc 10 worst); both 10 and 11
+ // are supporting, so relevance breaks the tie - doc 11 has higher
+ // bm25-derived score than doc 10.
+ expect(ranked[1]!.documentId).toBe(11);
+ expect(ranked[2]!.documentId).toBe(10);
+});
+
+test("tier multiplier preserves clamp01 on score", () => {
+ const ranked = rank(new Map([[10, "core"]]));
+ for (const r of ranked) {
+ expect(r.score).toBeGreaterThanOrEqual(0);
+ expect(r.score).toBeLessThanOrEqual(1);
+ }
+});
diff --git a/tests/mcp/brain.test.ts b/tests/mcp/brain.test.ts
index 8d3e4174..8588eb88 100644
--- a/tests/mcp/brain.test.ts
+++ b/tests/mcp/brain.test.ts
@@ -601,6 +601,16 @@ describe("brain_doctor", () => {
// At least one issue must be surfaced — either a warning or an error.
expect(s.errors.length + s.warnings.length).toBeGreaterThan(0);
});
+
+ test("v0.10.15 surfaces suggested_actions alongside errors/warnings", async () => {
+ const server = makeServer();
+ await initialize(server);
+ const r = await call(server, "brain_doctor", {});
+ const s = r.result.structuredContent;
+ expect(Array.isArray(s.suggested_actions)).toBe(true);
+ // Empty vault → empty actions array, but the field is always
+ // present so MCP clients can rely on the shape.
+ });
});
// ---------------------------------------------------------------------------
diff --git a/tests/mcp/context-pack-tool.test.ts b/tests/mcp/context-pack-tool.test.ts
new file mode 100644
index 00000000..14f88588
--- /dev/null
+++ b/tests/mcp/context-pack-tool.test.ts
@@ -0,0 +1,133 @@
+/**
+ * MCP integration coverage for the `brain_context_pack` tool added
+ * in v0.10.15. Verifies registration in the full tool scope plus
+ * the JSON-RPC round-trip shape.
+ */
+
+import {
+ afterEach,
+ beforeEach,
+ describe,
+ expect,
+ test,
+} from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ JSONRPC_VERSION,
+ MCPServer,
+ PROTOCOL_VERSION,
+} from "../../src/mcp/index.ts";
+import { buildToolTable } from "../../src/mcp/tools.ts";
+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
+
+let tmp: string;
+let vault: string;
+let configHome: string;
+let configPath: string;
+const savedEnv: Record<string, string | undefined> = {};
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-mcp-context-pack-"));
+ vault = join(tmp, "vault");
+ mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
+ configHome = mkdtempSync(join(tmpdir(), "o2b-mcp-context-pack-cfg-"));
+ configPath = join(configHome, "config.yaml");
+ for (const k of [
+ "VAULT_AGENT_NAME",
+ "VAULT_TIMEZONE",
+ "VAULT_DIR",
+ "OPEN_SECOND_BRAIN_CONFIG",
+ ]) {
+ savedEnv[k] = process.env[k];
+ delete process.env[k];
+ }
+ process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
+ atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+ for (const [k, v] of Object.entries(savedEnv)) {
+ if (v === undefined) delete process.env[k];
+ else process.env[k] = v;
+ }
+});
+
+async function initialize(server: MCPServer): Promise<void> {
+ await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 1,
+ method: "initialize",
+ params: {
+ protocolVersion: PROTOCOL_VERSION,
+ capabilities: {},
+ clientInfo: { name: "context-pack-test", version: "0" },
+ },
+ });
+ await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ method: "notifications/initialized",
+ });
+}
+
+async function callPack(
+ server: MCPServer,
+ args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+ const r = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 9,
+ method: "tools/call",
+ params: { name: "brain_context_pack", arguments: args },
+ })) as { result: { content: ReadonlyArray<{ type: string; text: string }> } };
+ return JSON.parse(r.result.content[0]!.text);
+}
+
+describe("brain_context_pack tool registration", () => {
+ test("registered in the full tool table", () => {
+ const tools = buildToolTable("full");
+ expect(tools.find((t) => t.name === "brain_context_pack")).toBeDefined();
+ });
+
+ test("NOT in the writer-only scope (read-only browse, not a writer)", () => {
+ const tools = buildToolTable("writer");
+ expect(tools.find((t) => t.name === "brain_context_pack")).toBeUndefined();
+ });
+});
+
+describe("brain_context_pack tool — round trip", () => {
+ test("returns highest-tier first within the budget", async () => {
+ writeFileSync(
+ join(vault, "Brain", "preferences", "pref-core.md"),
+ "---\nid: pref-core\ntopic: x\nprinciple: core principle\ntier: core\ncreated_at: 2026-05-01T00:00:00Z\n---\n",
+ );
+ writeFileSync(
+ join(vault, "Brain", "preferences", "pref-supp.md"),
+ "---\nid: pref-supp\ntopic: x\nprinciple: supporting principle\ntier: supporting\ncreated_at: 2026-04-01T00:00:00Z\n---\n",
+ );
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const out = await callPack(server, { max_tokens: 10_000 });
+ expect(out["max_tokens"]).toBe(10000);
+ expect(typeof out["tokens_used"]).toBe("number");
+ const items = out["items"] as Array<{ id: string; tier: string }>;
+ expect(items[0]!.id).toBe("pref-core");
+ expect(items[1]!.id).toBe("pref-supp");
+ });
+
+ test("rejects non-positive max_tokens via INVALID_PARAMS", async () => {
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const r = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 10,
+ method: "tools/call",
+ params: { name: "brain_context_pack", arguments: { max_tokens: 0 } },
+ })) as { error?: { code: number; message: string } };
+ expect(r.error).toBeDefined();
+ });
+});
diff --git a/tests/mcp/mcp.test.ts b/tests/mcp/mcp.test.ts
index 9e49a599..4ab2b2aa 100644
--- a/tests/mcp/mcp.test.ts
+++ b/tests/mcp/mcp.test.ts
@@ -156,7 +156,8 @@ describe("tool listing", () => {
"second_brain_query",
"vault_health",
// Brain (brain_note added in v0.10.8 §32B,
- // brain_context added in v0.10.10).
+ // brain_context added in v0.10.10,
+ // brain_context_pack added in v0.10.15).
"brain_feedback",
"brain_dream",
"brain_apply_evidence",
@@ -166,6 +167,7 @@ describe("tool listing", () => {
"brain_query",
"brain_doctor",
"brain_backlinks",
+ "brain_context_pack",
// Pay Memory (unchanged).
"payment_memory_init",
"payment_receipt_append",
@@ -365,9 +367,9 @@ describe("stdio loop", () => {
const list = JSON.parse(lines[1]!);
expect(init.id).toBe(1);
expect(list.id).toBe(2);
- // v0.10.10: 3 core (status/query/health) + 9 Brain (brain_note §32B
- // and brain_context v0.10.10) + 8 Pay Memory + 1 Search = 21.
- expect(list.result.tools.length).toBe(21);
+ // v0.10.15: 3 core + 10 Brain (brain_context_pack added v0.10.15)
+ // + 8 Pay Memory + 1 Search = 22.
+ expect(list.result.tools.length).toBe(22);
});
test("returns parse error for invalid JSON", async () => {