Local-first π§ memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly π΄ dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
feat: signals that survive (v1.41.0) (#152)
Sol Aitken5ac866eb3b6e
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex d5308b78..250ab83e 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "1.40.0",+ "version": "1.41.0","description": "Plugin-first second brain package for AI agents and humans.","author": {"name": "Open Second Brain contributors"diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.jsonindex 99488f6a..0b001b1a 100644--- a/.codex-plugin/plugin.json+++ b/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "1.40.0",+ "version": "1.41.0","description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.","skills": "./skills","hooks": "./hooks/hooks.json",diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 181de64c..1ef0458c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,46 @@ 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).+## [1.41.0] - 2026-07-27++A signals-that-survive wave: eight units that carry a signal the kernel already computes the last few metres, to the decision it should have changed. A repository declared which files it considers noise and the ingest planner ignored the declaration, while the hygiene scan beside it had honoured git for releases. A recall attempt was graded weak and the grade evaporated when the call returned, so nothing could tell that the same question had come back insufficient four times. A query named a period and the ranker went on applying a freshness prior pointing the other way. A parse error carried its file path in prose and as a field, so the doctor printed it twice. Three write paths accepted model-authored payloads and parsed them loosely, straight into the vault.++A ninth unit was written, reviewed, and then reverted rather than shipped, and that is worth stating plainly: a tie-break layer for the write router turned out to be unable to fire at all. Proving it byte-identical when its gate is absent also proved its reach β only a rival claiming a captured span in full can enter its margin, and the three pattern families this router chooses between cannot do that, because a complete match of one carries a character the others do not admit. The routing ambiguity the task describes is real, but it lives on a different write surface; this router chooses between structurally disjoint families and has nothing to disambiguate. Shipping the mechanism would have shipped a decision layer that never decides and a telemetry record that is never written.++Reconnaissance against the code invalidated a premise in four of the nine scoped tasks before a line was written. Two more were falsified during the release itself: one recorded during scoping and corrected in the design document rather than quietly dropped, and the one above. Independent review of the finished branch β reviewers given the diff and the claims, with no knowledge of how the work was done β found fourteen further defects that the implementing agents' own passing tests had not, most of them in error paths and option branches those tests did not model. Every one is fixed in this release and named below. The kernel still calls no model, no natural-language word list was added in any language, and every new flag and configuration key is byte-identical when absent.++### Added++- Git-aware ingest source discovery. The batch planner honours the repository's own root and nested `.gitignore`, `.git/info/exclude`, and submodule boundaries, through a discovery module extracted from the hygiene scan so both paths compose one implementation and the submodule predicate - the only net-new piece - exists once rather than in two twins that drift. The layers stack repository-declared first and the operator `--exclude` layer last, re-stacked at every directory so it wins at any depth; a submodule boundary is a boundary rather than an ignore rule, and `--exclude` cannot re-include it. A malformed pattern in a repository's own ignore file is returned as a structured warning and surfaced on both operator surfaces - carrying source, line, pattern and reason as fields - rather than printed from the kernel or failing the plan; a malformed operator `--exclude` still throws. Under `--subpath` the directories between the source and the walk root were never visited, so their `.gitignore` files were silently skipped; they are now layered. A tree with no ignore files produces the same plan identifier it produced before.+- A routing hint on an unroutable capture. A feedback signal recorded with no scope now names `scope` as the missing routing signal and lists the scope slugs the vault actually contains, ranked by document frequency over confirmed preferences and the unconsumed inbox - so recency is structural rather than clocked, and candidates come from frontmatter rather than from a word list. A vault with no scope corpus returns nothing rather than empty prose. The forward pointer resolves a registered diagnostic code through the advisory rail, resolved at module scope so registry drift fails at import instead of silently printing nothing, and the hint is recorded under its own log event kind - a hint nobody counts cannot show whether unrouted captures fell. The write always lands; no configuration key was added.+- Query-side temporal intent. A query that declares a window - from ISO tokens or `since:` / `until:` field tokens, never a natural-language phrase in any language - biases ranking toward that window through a capped additive layer over the existing proximity function, and damps the freshness prior when the window is historical. Field values accept only language-neutral forms, checked by shape rather than by a second parser, so the word grammar the explicit parameter has kept for releases is not exposed to free query text. A bare token that merely looks like a date but does not resolve declares nothing and stays in the query as content, rather than failing the search. Freshness and temporal intent stay separate entries in the reasons and in the score breakdown, so a ranking change is attributable to one of them. A tie-break rung sits above the freshness rungs and above the keyword-score rung, because that score is already a component of the total and re-applying it on an exact tie double-counts a signal the temporal contribution cannot outweigh once clamped. Detection runs on the raw query before expansion or any other lexical restructuring, and the directive is stripped from the text lanes before matching: the full-text builder joins tokens by implicit AND, so a directive left in the query is a required term no document carries and the search returns nothing. A query that declares a window and no terms is an input error naming what is missing.+- Weak recall becomes tracked work. The recall-adequacy verdict, already computed deterministically from numeric scores at two sites, is stamped onto the demand record under the bucket key the demand log already derives from document frequency, with its existing redaction and caps. The knowledge-gap loop gains that as a second signal source beside its structural one; the two are never summed, the task key is namespaced by source, and the agenda labels which is which, so a coarse telemetry bucket and a fine term bucket stay distinguishable. Promotion is capped per run and a skip costs no budget, so an established backlog cannot starve a new gap.+- `fact` and `skill` marker kinds on the existing inline grammar, so plain text can seed all three destinations rather than only a taste signal. No second grammar and no new entry point: fence-awareness, the consumed sentinel and the rewrite machinery apply unchanged. A fact lands as an unconfirmed preference through the existing derive path with premise validation still fail-closed; a skill lands in the pending proposal store, never in accepted. A declared skill deliberately bypasses the mining verifier rather than satisfying it - that gate demands three distinct pieces of structural evidence and a confidence floor, which a single declaration can never meet, so running it would reject every marker and ship the feature inert. For the same reason the declared frontmatter writes no confidence key: an absent claim already reads as zero self-reported support, and writing a number would fabricate a statistic.+- Response-shape validation on the three model-authored write paths. Each ingress checks its payload against a frozen descriptor before any field is read; a violation raises a named error carrying code, path and message as fields, nothing is coerced, and a batch whose third item is malformed writes none of the first two. Validation is unconditional - a validator that can be switched off is one the write path cannot rely on, and a strict path shipped inert behind a permissive default would be exactly the silent no-op this project forbids. The validator is not new: the JSON-subset checker in the Model Context Protocol output contract was promoted to core and both sides consume one definition, replacing the hand-rolled coercion checks that had been duplicated between each command-line verb and its tool.+- Durable work identity above the timing crutch. A session may declare a work id and a lane, and a rung above the fifteen-minute window links two entries sharing a work id on identity alone - no freshness bound, no working-directory or branch predicate - so resumed work re-attaches after a model, account, branch or worktree switch. Identity is declared, never derived, through three rungs where the first to declare either field supplies both; deriving it from remote and merge-base into a union registry was rejected because that places mutable, effectively irreversible state inside a peer-replicated vault with no arbiter. A declared lane mismatch excludes a candidate at both rungs rather than only at the identity rung - a separator one rung ignores is not a separator - and the refusal is a named outcome reported ahead of predicates a candidate merely fell short of. The abstention layer from 1.39.0 is consumed rather than re-implemented.++### Changed++- A parse-error finding names its file once. The path moved out of the message and into a field on a typed error that composes its message from a bare detail plus that path, so every caller surfacing the message directly receives the same string it received before and none needed editing. Both branches were duplicating, not one: the status-folder-mismatch error was documented as already path-free and was not - its constructor appended the path to its own message. That error carries its location in the middle of its historical sentence rather than at the end, so it composes its own message through a single declared seam instead of having its layout rearranged.+- Four optional-field helpers in the preference parser threw with no path at all, so a malformed list-valued field named no file on any surface. They now carry the location they never had.+- Repeated keys inside a marker fence silently last-won, and one kind carried a bespoke duplicate guard to compensate. Both marker shapes now funnel through one collector with per-field arity, so a repeated single-valued field is refused as ambiguous for every kind and a repeated multi-valued field keeps all its values.+- A malformed value in an explicit `since:` / `until:` search field is an input error rather than being matched as literal text, which is how the equivalent parameter already behaved. A bare date-shaped token in ordinary query text is not a declaration and is left alone.+- The ranking boost caps were unnamed literals with no single place to compare them, so the new temporal cap had nothing to be proportioned against. They are extracted as named constants and the proportion is asserted against those rather than re-hardcoded.++### Fixed++- A `--src-subpath` walked past exclusions and boundaries the unscoped walk honoured. Pruning only ran on directories reached as a directory entry, so a subpath starting below an ignored directory re-entered it, and one starting below a nested repository crossed into it - the same tree answering differently depending on how it was addressed, which also forked its plan identifier. The ignored case is refused and reported with the override that opens it; the boundary case is refused outright, because continuing would attribute another repository's files to this plan and an empty plan would be indistinguishable from nothing to do.+- An unreadable repository ignore file was swallowed by a catch that returned without touching the warnings array in its own signature, so a file the repository declared excluded was queued for ingest with no signal on any surface. Only a genuine absence stays quiet now; every other failure names its reason, and only the error code is reported so no host path reaches a payload. The same code was inherited verbatim by the hygiene scan and is fixed in both. A symlinked ignore file is refused rather than followed, and the read is size-capped.+- A declared search window was silently voided under query expansion, and the search returned nothing. Detection read the text after expansion, whose tokenizer destroys the field grammar, while stripping still ran on the original - so the window vanished and its fragments became required terms. The expansion path had no test at all, which is why it shipped.+- A scan preview hid every routed marker. The whole routed branch sat behind the write guard and the counters only counted the older kind, so `--dry-run` reported zero pending work while writes were queued and the next real run performed them. Preview and write now share one planner, and a test runs both over the same fixtures and compares refusals so they cannot drift apart on what is acceptable.+- A skill re-declared under a name a human had already rejected or accepted vanished: nothing counted, nothing reported, and the marker was consumed with its pointer aimed at a file whose body differed from the one just declared. The outcome is named and reported, and the marker is not consumed - the queue stored nothing, so the marker is the operator's only copy of that body.+- A repeated single-valued optional field in a marker was silently discarded while a required one was correctly refused, so a signal declaring a scope twice was written unscoped and unroutable. Both are refused as ambiguous now; the inline shape had the same drop before this release and is fixed too.+- An inherited work identity never expired, so every later session in a directory chained onto the previous one and lineage depth grew without bound. The bound applies to the inherited rung only: an explicit declaration by something live still re-attaches after a month, and the marker directory is capped in the same idiom the lineage ledger already uses.+- The response-shape descriptor for research reports accepted blank strings the parser it replaced had rejected, writing a report whose citations rendered as empty links. Descriptors can now require a non-blank string, with the replaced parser's own wording.+- The gap-task directory had no bound: its topic space used to be a fixed set of telemetry codes and the new source makes it arbitrary normalised query text. Closed tasks past a retention window are pruned and minting past a cap is refused, both reported.+- Two different opt-ins gated one feature - a configuration flag on one surface and a per-call argument on the other, so the demand log wrote when it should not and stayed silent when it should not. One key now gates both.+- The rolling-cap test in the demand log took five seconds against a five-second limit and would have flaked under parallel load. Its cost was append count rather than bytes, so it reaches the same byte-budget branch with 890 appends instead of 20,000 - and it now asserts that compaction actually ran, which it never did.+## [1.40.0] - 2026-07-27A no-dead-ends wave: eleven units that make the system say what to do next, do it where the fix is provably mechanical, and refuse by name where it is not. Reconnaissance against the code invalidated at least one premise in eight of the ten scoped sources before a line was written, so most of this release is not new machinery but delivery of machinery that already existed and did not reach the caller. A registry of structural next commands had twenty entries and two consumers; the notice channel carried its command inside an English sentence; three repair pipelines each decided privately what they could fix; a repair planner shared a vocabulary with the detector while re-scanning the vault independently; the dream journal marked phases complete before their work began; the command manifest omitted a third of the real verb surface that shell completions are generated from; and two advisories stated things that were not true, one of them contradicting the same screen it printed on. The kernel still calls no LLM, and every new flag, argument, and configuration key is byte-identical when absent.@@ -6715,6 +6755,7 @@ plugin config (vault field)`, and exits with a clear- Sandbox vault and plugin manifest fixtures for tests.- GitHub release workflow for tag-based and manually dispatched releases.+[1.41.0]: https://github.com/itechmeat/open-second-brain/compare/v1.40.0...v1.41.0[1.40.0]: https://github.com/itechmeat/open-second-brain/compare/v1.39.0...v1.40.0[1.39.0]: https://github.com/itechmeat/open-second-brain/compare/v1.38.0...v1.39.0[1.38.0]: https://github.com/itechmeat/open-second-brain/compare/v1.37.0...v1.38.0diff --git a/README.md b/README.mdindex c60b9a9f..6d771eb5 100644--- a/README.md+++ b/README.md@@ -8,9 +8,9 @@ Open Second Brain plugs into [Hermes Agent](https://github.com/NousResearch/herm## What is new-Open Second Brain 1.40.0 is a no-dead-ends wave: eleven units that make the system say what to do next, do it where the fix is provably mechanical, and refuse by name where it is not. Every issue `o2b brain doctor` reports now carries the exact command that acts on it, on the human surface and as a field over MCP - and where no single command resolves a class, the doctor gives the reason rather than falling silent, so an operator can tell "there is no command for this" from "the system forgot". Terminal states that used to exit zero without a word now name their next move through one rail that a ratchet keeps singular. `o2b brain dream` gained a single-step run and a one-run gate override, so a targeted pass no longer means editing `_brain.yaml` and remembering to revert it; a step that cannot run alone is refused with the coupling named. The dream journal marks a phase complete where its writes actually land instead of before they begin, `_brain.yaml` is generated from the resolver's own defaults so sixteen silently-defaulted keys are visible, and the repair planner consumes the doctor's findings instead of re-scanning behind it. Most of this release is not new machinery: reconnaissance invalidated at least one premise in eight of the ten scoped sources, and what shipped is the delivery of mechanisms that already existed and did not reach the caller.+Open Second Brain 1.41.0 is a signals-that-survive wave: eight units that carry a signal the system already computes the last few metres, to the decision it should have changed. Ingest now honours the repository's own `.gitignore`, nested ignore files, `.git/info/exclude` and submodule boundaries, through the same discovery module the hygiene scan uses - so a repo path stops pulling in the build artifacts it already declares as noise. A recall graded weak no longer evaporates when the call returns: repeated weak recall on the same question becomes a tracked, self-closing gap task. A query that names a period is ranked for that period instead of against it, detected from ISO and `since:`/`until:` tokens only so it behaves the same in every language. A scope-less capture says which routing signal it was missing and which scopes the vault actually has. Model-authored payloads are checked against a declared shape before they become knowledge, unconditionally - a validator that can be switched off is one the write path cannot rely on. Plain text can now seed a fact or a skill, not only a taste signal. And resumed work is recognised by a declared identity rather than by a fifteen-minute clock, so a branch or worktree switch stops breaking the chain. A ninth unit was built, reviewed, and reverted rather than shipped, because proving it inert was easier than pretending it was not - the [CHANGELOG](CHANGELOG.md) says why.-Previous release, 1.39.0, was a context-integrity wave: owner scoping reached every content-returning surface, context packs gained a provenance stamp and an expiry, session continuation learned to abstain by name, and a frontmatter line the parser cannot read is reported instead of dropped. Details live in the [CHANGELOG](CHANGELOG.md).+Previous release, 1.40.0, was a no-dead-ends wave: every issue `o2b brain doctor` reports carries the exact command that acts on it, terminal states name their next move through one rail a ratchet keeps singular, and where no command resolves a class the doctor gives the reason rather than falling silent. Details live in the [CHANGELOG](CHANGELOG.md).## Whydiff --git a/docs/brainstorm/signals-that-survive/cli-output/claude-doctor-path-duplication.md b/docs/brainstorm/signals-that-survive/cli-output/claude-doctor-path-duplication.mdnew file mode 100644index 00000000..319ec089--- /dev/null+++ b/docs/brainstorm/signals-that-survive/cli-output/claude-doctor-path-duplication.md@@ -0,0 +1,37 @@+### Variant 1: Strip the path at the throw sites+- **Approach**: Delete the ` (${path})` tail from the ~15 `throw new Error(...)` sites in `src/core/brain/preference.ts` (`requireField`, `requireString`, `requireStringArray`, the `kind`/`retired_reason` enum checks, and the confidence/schema helpers), leaving the message as pure prose about the field. The doctor's existing `path` field then becomes the single source of the location, and the renderer's tail is untouched. Callers that today rely on the message carrying the path (`dream`, `query`, `export`, `merge`, `apply-evidence`, `pin`, `preference-txn`) must each be audited and given the path from the call site they already know.+- **Trade-offs**:+ - Pro: smallest conceptual change; matches the stated fix direction literally β the message stops embedding the path.+ - Pro: no new type, no new indirection; DRY holds because the path was always duplicated for the doctor.+ - Con: the path is *only* recoverable from the message today for every non-doctor caller that surfaces `(exc as Error).message` bare β stripping it there loses operator context unless each of ~10 caller modules is fixed in the same change, which is exactly the "silently does nothing" failure mode the constraints forbid.+ - Con: blast radius is wide for a cosmetic priority-3 item; every test asserting the current message text (parse-error fixtures, doctor fixtures, dream/query error paths) has to move together.+ - Con: nothing structurally prevents the next `throw` from re-adding `(${path})`.+- **Complexity**: medium+- **Risk**: medium++### Variant 2: Typed parse error carrying `path` as a field+- **Approach**: Introduce a `BrainParseError` (path + bare message) modelled directly on the `BrainStatusFolderMismatchError` that `classifyParseError` already special-cases in `src/core/brain/doctor.ts` β that class carries `path` structurally and its `message` contains no path, so the doctor already emits it correctly. The preference/retired parsers throw `BrainParseError` instead of bare `Error`; the doctor reads `err.path`/`err.message` as fields, and non-structured callers format location through one shared helper rather than string concatenation at 15 sites.+- **Trade-offs**:+ - Pro: the path is never lost β it moves from prose into a field that every caller can read, which is the same move v1.40.0 made for findings.+ - Pro: follows an in-repo precedent living in the exact function being fixed, so the two parse-error branches of `classifyParseError` stop being asymmetric.+ - Pro: makes regression structural β a future throw site cannot embed the path without going around the typed error.+ - Pro: the `parseErrorCode` regex classification (`/missing field/`, `/ISO-8601/i`) keeps working on the bare message and becomes less coupled to incidental path text.+ - Con: largest of the three; a new exported error type plus migration of every throw site and its `instanceof`-blind catch sites.+ - Con: overshoots the reported defect β most of the work buys structure, not the missing byte.+ - Con: callers doing `catch (exc) { fail(exc.message) }` need a decision per site about whether to append the path, so the change is not mechanical.+- **Complexity**: medium+- **Risk**: low++### Variant 3: Normalize at the doctor boundary+- **Approach**: Leave `preference.ts` untouched and fix it where the two representations meet: `classifyParseError` in `src/core/brain/doctor.ts` builds the issue from a message with its own trailing ` (<path>)` suffix removed, keyed off the `path` it is already passing into the issue. The renderer at `doctor.ts:49` and every non-doctor caller of the parsers keep byte-identical behaviour.+- **Trade-offs**:+ - Pro: one function, one change, no cross-module audit; all four parse-error kinds (`preference-missing-field`, `preference-invalid`, `retired-missing-field`, `retired-invalid`, plus `iso-invalid` routed through the same push) are fixed at once because they share this single construction point.+ - Pro: zero risk to any other surface β dream, query, export, MCP errors are unaffected.+ - Con: it is prose parsing to undo prose formatting β the doctor now depends on the parser's exact suffix spelling, which is a second, quieter coupling replacing the first.+ - Con: fixes the symptom in one consumer; the same duplication reappears anywhere else that pairs these errors with a structured path field.+ - Con: sits awkwardly against the "findings carry data as fields, not prose" convention β the message still carries the data, it is just trimmed on the way out.+- **Complexity**: small+- **Risk**: low++### Recommended: Variant 2+**Rationale**: The path only lives in prose today, so Variant 1 deletes operator context from every non-doctor caller unless the same change fixes all of them, and Variant 3 trades one prose coupling for another that the next consumer will hit again. Variant 2 does what the fix direction asks β the message stops embedding the path β while keeping the data as a field, and it does so by extending a pattern (`BrainStatusFolderMismatchError`) that already exists in the very function being changed, so the two branches of `classifyParseError` end up consistent instead of one being the exception. If the cosmetic priority argues against the full migration, the typed error can land scoped to `parsePreference`/`parseRetired` only, with the remaining throw sites converted as they are touched.diff --git a/docs/brainstorm/signals-that-survive/cli-output/claude-durable-work-identity.md b/docs/brainstorm/signals-that-survive/cli-output/claude-durable-work-identity.mdnew file mode 100644index 00000000..c4d1a1ae--- /dev/null+++ b/docs/brainstorm/signals-that-survive/cli-output/claude-durable-work-identity.md@@ -0,0 +1,42 @@+### Variant 1: Declared work identity as a precedence rung above the crutch++- **Approach**: Add an optional durable pair β `workId` and `laneId` β sourced at the capture boundary in strict precedence (host payload field, then an environment/config key, then a per-worktree marker recorded in `Brain/.state/`), and persist both as new optional `wid`/`lane` fields on `LedgerLine`. `resolveSessionLineageDetailed` gains a rung between `payload` and `crutch`: when this session and exactly one predecessor share a `wid`, the link is made on identity alone with no freshness bound and no `cwd`/branch/commit predicate, so a resumed work item re-attaches after a model, account, branch or worktree switch. Lanes are a hard separator rather than a tiebreaker β two entries sharing a `wid` but carrying different `laneId` values can never link, and two same-lane survivors abstain through the existing ambiguity path with new named reasons (`lane-conflict`, `work-ambiguous`).+- **Trade-offs**:+ - Exact/external identity always wins, and nothing is inferred; the kernel stays deterministic and no natural-language signal is consulted.+ - Absent `wid`/`lane` the resolver is the current one line-for-line, so the byte-identical-when-absent rule holds without a compatibility shim.+ - The ledger already hashes line bodies by removal of chain fields and compacts verbatim, so new optional fields ride the existing integrity chain untouched.+ - `CRUTCH_LINK_WINDOW_MS` survives as the fallback bound rather than being deleted; the crutch is demoted, not removed, which leaves two resolution rules to reason about.+ - Value depends on something actually declaring the id β an unwired host gets no benefit, so the feature is only as good as its capture-boundary adapters.+ - A stale or copied marker file in a cloned worktree would assert a false identity; the lane separator contains it but does not detect it.+- **Complexity**: medium+- **Risk**: low++### Variant 2: Derived work fingerprint with an attestation-union registry++- **Approach**: Derive the work identity structurally instead of declaring it β a content-addressed fingerprint over canonical remote, upstream/merge-base ref, and worktree gitdir identity β and maintain a union registry in `Brain/.state/` that binds fingerprints observed together by one session into a single work identity, so a branch or worktree switch inside one session teaches the registry that both fingerprints name the same work. The lane is derived from the gitdir identity, keeping parallel worktrees separate by construction. Resolution keys on registry membership, and a union that would join two already-distinct works abstains rather than merging.+- **Trade-offs**:+ - Requires no host cooperation and no operator action; every existing session gains identity immediately.+ - Lane separation falls out of the same derivation as identity, so there is no second thing to wire or forget.+ - The property that must survive β branch and worktree change β is precisely what the fingerprint encodes, so identity only survives through a learned union, and the very first switch cannot be recognized until after the fact.+ - Unions are cumulative and effectively irreversible; one bad attestation permanently welds two work items, which inverts the fail-closed contract that v1.39.0 established.+ - Merge-base and upstream probes are unbounded git work at a fail-soft lifecycle boundary, and their absence in a detached or non-git tree silently collapses the fingerprint space.+ - The registry is mutable shared state inside a Syncthing-replicated tree, where two peers can produce conflicting unions with no arbiter.+- **Complexity**: large+- **Risk**: high++### Variant 3: Lane lease ledger replacing the freshness window outright++- **Approach**: Make the execution lane the primary durable object: each session opens a lease on a work id at `SessionStart` and releases or hands it off at the compression boundary, recorded as explicit open/handoff/close lines in the existing append-only ledger. Continuation becomes lease re-acquisition β a new session links only to a predecessor whose lease is in handed-off state and unclaimed β so `CRUTCH_LINK_WINDOW_MS` is deleted rather than demoted, and concurrency is refused because a live lease is already held rather than because two candidates tied.+- **Trade-offs**:+ - The timing crutch disappears entirely; freshness stops being a proxy for anything.+ - Concurrent lanes are structurally impossible to collapse, not merely detected and abstained on.+ - The lease lifecycle is observable and auditable in the same chained ledger, and a handoff is an explicit fact rather than an inference.+ - A crashed or SIGKILLed session leaks an open lease forever; reclaiming it needs a staleness age, which reintroduces a time window at exactly the point the variant claims to remove one.+ - Lease semantics assume a single authority over the state file, which a Syncthing-replicated vault does not provide; two peers can each believe they hold the same lease.+ - Deleting the window is an incompatible change to a resolution path that currently degrades to `flat` gracefully, and every hook must now emit a close event or continuity quietly stops working.+- **Complexity**: large+- **Risk**: medium++### Recommended: Variant 1++**Rationale**: The upstream contract's substantive claim is that exact and external identifiers always win while inference stays advisory, and Variant 1 is the only one that implements that literally β identity is declared, never derived, so the kernel adds no new inference and the ambiguity layer shipped in v1.39.0 is reused rather than re-litigated. It fits the scoping note by extending the lineage/crutch layer with two optional ledger fields and one precedence rung instead of standing up a registry subsystem, and it keeps behaviour byte-identical when the fields are absent. Variants 2 and 3 both place mutable, authority-assuming state inside a peer-replicated vault and both reintroduce the failure they set out to remove β an irreversible silent union in one case, a time-based lease reclamation in the other.diff --git a/docs/brainstorm/signals-that-survive/cli-output/claude-git-aware-ingest-discovery.md b/docs/brainstorm/signals-that-survive/cli-output/claude-git-aware-ingest-discovery.mdnew file mode 100644index 00000000..a474de3c--- /dev/null+++ b/docs/brainstorm/signals-that-survive/cli-output/claude-git-aware-ingest-discovery.md@@ -0,0 +1,42 @@+### Variant 1: Inline mirror inside `batch-plan.ts`++- **Approach**: Copy the hygiene scan's layering shape directly into the ingest planner: a private `buildGitScope(dirAbs)` that reads `.git/info/exclude` then the root `.gitignore`, and a per-directory `.gitignore` extension inside `collectIngestible`, stacked *under* the operator `--exclude` layer so `--exclude` always wins. Submodules are skipped by testing each candidate directory for a `.git` entry (gitlink file or directory) before recursing. Nothing outside `src/core/brain/ingest/` changes.+- **Trade-offs**:+ - Smallest blast radius: hygiene's `listScanTargets` and its golden tests are untouched, so the 910-test suite risk is confined to ingest.+ - Byte-identical no-git path falls out naturally β with no ignore files present every added layer is empty and `IgnoreScope.isEmpty` holds, so `planId` does not shift.+ - Resolves the vault-relative/root-relative base-dir mismatch locally: layers are based at `dirRel` (or the nested dir's vault-relative path), which is exactly what `IgnoreLayer.baseDir` already models.+ - Direct DRY violation against an explicit repo constraint: two near-identical `extendWithIgnoreFile` + walk implementations that must be kept in step forever, and the submodule rule then exists in only one of them.+ - Malformed-pattern warnings need a second, ingest-shaped disposition (`buildExcludeScope` throws for `--exclude`; a repo's own broken `.gitignore` line must not fail an ingest plan), so the warning policy gets invented twice.+ - Repo-root discovery is ad hoc: if `sourceDir` points at a subtree of a checked-out repo, an inline implementation either ignores the ancestor `.gitignore` files or grows its own upward walk.+- **Complexity**: small+- **Risk**: low++### Variant 2: Extract a shared git-aware discovery module under `src/core/fs/`++- **Approach**: Promote the layering logic out of `scan-repo.ts` into a sibling of `ignore.ts` β a module owning "given a repo root, produce the base `IgnoreScope`" and "given a directory, extend a scope with its `.gitignore`", plus a submodule/non-working-tree predicate, with malformed-pattern warnings returned as structured `IgnoreWarning[]` rather than printed. `scan-repo.ts` keeps its `hygiene:` stderr sink by consuming those warnings itself; `collectIngestible` consumes the same module and chooses its own disposition (structured field on the plan, or advisory-rail code). Submodule skipping lands once and both discovery paths inherit it.+- **Trade-offs**:+ - Satisfies the DRY/SOLID constraint the repo states outright, and puts the git-metadata reader next to the matcher engine it composes with, where the next consumer will look for it.+ - Submodule handling β the one net-new piece β is written, tested, and reviewed once instead of diverging between hygiene and ingest.+ - Warnings become data rather than a side effect, which fits "findings carry their data as structured fields" and lets the plan surface a broken repo `.gitignore` without printing from the kernel.+ - Touches a currently-green subsystem: hygiene's scan is behaviour-pinned by tests, so the refactor must be provably inert there before the ingest wiring is even visible.+ - Larger review surface for a change whose user-visible payoff is entirely in ingest; the hygiene diff is pure motion.+ - Forces an early decision on the base-dir contract (repo-root-relative vs. vault-relative) that both callers must agree on, rather than deferring it.+- **Complexity**: medium+- **Risk**: medium++### Variant 3: Delegate discovery to `git` itself++- **Approach**: When `isGitRepo(dirAbs)` holds, obtain the candidate file set from `git ls-files --cached --others --exclude-standard` through the existing `runGit` helper in `src/core/brain/git/reader.ts`, then filter by extension and apply the operator `--exclude` scope on top; otherwise walk as today. Git's own answer covers nested `.gitignore`, `.git/info/exclude`, `core.excludesFile`, and submodule boundaries with no reimplementation.+- **Trade-offs**:+ - Exact parity with git semantics, including the corners `ignore.ts` explicitly disclaims (it documents a subset, not `git check-ignore` parity) β no drift between what the operator sees in `git status` and what ingest picks up.+ - Submodules, sparse checkouts, and assume-unchanged entries come free; no new matcher code at all.+ - Makes a core deterministic planner depend on an external `git` binary and on user-global config (`core.excludesFile`, `~/.config/git/ignore`), so the same vault on two machines can produce different `planId`s β directly against the deterministic-kernel and no-hidden-runtime-dependency constraints.+ - A missing or failing `git` cannot silently fall back to the dot-entry walk (that is the forbidden silent-no-op), so it must surface as an explicit error, which makes ingest newly fragile on machines without git.+ - Sits awkwardly against the repo's stance that the replicated vault carries no git; a source dir under the vault that is a real checkout is an edge the current code does not otherwise assume.+ - Process-spawn cost per plan, and output parsing/quoting (`core.quotePath`) becomes a new correctness surface.+- **Complexity**: medium+- **Risk**: high++### Recommended: Variant 2++**Rationale**: The task's own framing is that both halves already exist and the work is composition β which makes duplicating the hygiene walk (Variant 1) a self-inflicted maintenance seam right where the repo's DRY constraint is loudest, especially since submodule handling is net-new and would otherwise be implemented in only one of two twins. Variant 3 buys exact git parity at the price of an external binary and user-global config inside a planner whose `planId` must be reproducible, which the deterministic-kernel constraint rules out. Variant 2 keeps discovery pure, in-process, and byte-identical when a source carries no ignore files, and the hygiene refactor it requires is inert motion pinned by existing tests rather than new behaviour.diff --git a/docs/brainstorm/signals-that-survive/cli-output/claude-llm-response-shape.md b/docs/brainstorm/signals-that-survive/cli-output/claude-llm-response-shape.mdnew file mode 100644index 00000000..ea0df992--- /dev/null+++ b/docs/brainstorm/signals-that-survive/cli-output/claude-llm-response-shape.md@@ -0,0 +1,39 @@+### Variant 1: Ingress shape gate β one shared validator, static shape table++- **Approach**: Promote the existing JSON-Schema-subset validator in `src/mcp/output-contract.ts` (`OutputSchema` / `validateOutputContract`) into a core module β named for *response shape*, not "schema", to stay clear of `schema-contracts.ts` / `schema-pack.ts` / `schema-admin.ts` β and declare one frozen shape descriptor per model-authored write path (distill claims, derived facts, dream/synthesis payloads). Each consumer site validates the agent-supplied payload against its descriptor before any normalization, replacing scattered ad-hoc coercion with a single fail-closed check that emits structured `{code, path, message}` findings. The descriptors stay deliberately shallow β required keys, primitive types, array-of-object items β so extraction recall is not squeezed by over-constraint.+- **Trade-offs**:+ - Reuses a validator that already exists and is already tested; no new dependency, no zod.+ - Removes loose parsing from three write paths in one pass, with findings carried as structured fields rather than prose.+ - Enforcement is at the boundary only β the model still generates free-form and a mismatch costs a full round trip that Open Second Brain cannot itself initiate.+ - Tightening validation can reject payloads today's callers get away with, so it needs a config key defaulting to the current tolerance to keep behaviour byte-identical when absent β which means the strict path ships dormant until an operator opts in.+ - The subset validator is intentionally small; a shape needing conditionals or unions has nowhere to go without growing it.+- **Complexity**: small+- **Risk**: low++### Variant 2: Generalize the write-session contract loop to every model-authored payload++- **Approach**: `src/core/brain/write-session/` already implements the full pattern the upstream PR is reaching for β a session holding a declared target and `schemaType`, fail-closed validation, machine-readable errors, and a correction prompt derived from the error list so the agent resubmits the whole artifact. Extract that open β submit β validate β correct β commit engine into a payload-shape-agnostic primitive and route distillation, fact derivation, and dream synthesis through it, each registering its own shape descriptor and reserved-target policy. A bad response then becomes a *retryable session state* with an operator-visible attempt record, not a silent parse degradation.+- **Trade-offs**:+ - Highest fidelity to the goal: a malformed response is caught, named, and given an explicit exit, which matches the no-dead-ends and no-silent-fallback conventions directly.+ - Reuses an engine already proven on the riskiest write path rather than inventing a parallel mechanism β strong DRY win, and one correction-prompt derivation instead of three.+ - Turns three currently stateless single-shot calls into stateful multi-step ones: session records, TTLs, abandonment, idempotency, and the audit trail all multiply.+ - Changes the shape of existing CLI and MCP surfaces for `brain_distill_source` / `brain_derive_fact` / `brain_dream`; keeping them compatible means running both the direct and session forms, which is duplicated surface, not less.+ - Largest test surface: the session engine's failure matrix has to be re-verified per new consumer.+- **Complexity**: large+- **Risk**: medium++### Variant 3: Two-sided contract β publish shape descriptors outward, verify on return++- **Approach**: Keep the kernel model-free and instead make each write path's expected response shape a *first-class published artifact*: exposed in MCP tool metadata and capabilities, printable from the command line, and stable enough for the calling harness (Claude, Hermes routing) to feed straight into its own native structured-output mechanism. Open Second Brain then runs a thin ingress verification of the same descriptor on the returned payload, so constrained generation happens where the model actually lives and validation happens where the vault write happens.+- **Trade-offs**:+ - The only variant that gets genuine *constrained generation* rather than post-hoc rejection, without the kernel ever issuing a model call.+ - Descriptors become versioned public contract, which is exactly what makes the auto-memory extraction follow-on (`t_1dace26d`) cheap to add β it registers a descriptor instead of a parser.+ - Effectiveness is contingent on caller cooperation; a harness that ignores the published descriptor gets no benefit beyond Variant 1's rejection, so the win is unevenly distributed across clients.+ - Publishing descriptors on MCP tool metadata expands a surface that is already covered by `registry-guard.ts` and the preview-budget rules β schema growth there has token cost on every session.+ - Two enforcement points can drift; the descriptor must have exactly one definition with both the published form and the validator derived from it.+- **Complexity**: medium+- **Risk**: medium++### Recommended: Variant 1++**Rationale**: The kernel issues no model calls, so the real defect here is loose parsing at the ingress of agent-supplied payloads, and Variant 1 fixes exactly that with a validator the repository already owns β no new dependency, no zod, no surface change, and a config key that keeps behaviour byte-identical when absent. Variant 2's session loop is the correct end state but pays large structural cost up front for three call sites that are single-shot today, and Variant 3's outward publication is only worth the versioned-contract burden once the descriptors have proven stable in practice. Variant 1 is also the strict prerequisite that makes the other two cheap later: it establishes the single shape-descriptor definition and the distinct naming (response *shape*, never *schema*) that both would build on.diff --git a/docs/brainstorm/signals-that-survive/cli-output/claude-marker-kinds-fact-skill.md b/docs/brainstorm/signals-that-survive/cli-output/claude-marker-kinds-fact-skill.mdnew file mode 100644index 00000000..74d883be--- /dev/null+++ b/docs/brainstorm/signals-that-survive/cli-output/claude-marker-kinds-fact-skill.md@@ -0,0 +1,42 @@+### Variant 1: Two kinds on the existing grammar, existing entry points only++- **Approach**: Extend `MarkerKind` with `fact` and `skill`, add their rows to `KNOWN_KINDS` and `REQUIRED_FIELDS` (`fact`: topic + principle + premises; `skill`: name + trigger + procedure), and add two narrowing type guards beside `isFeedbackMarker`. Routing reuses stores that already carry a review gate: a `fact` marker lands as an unconfirmed preference via the `derive-fact` path (premise validation stays fail-closed, so an unresolvable premise is an explicit error, not a silent drop), a `skill` marker lands in the **pending** skill-proposal store with a marker-sourced pattern kind, never in accepted. Answer to the open question is "no": `o2b brain scan-inline --path <dir>` already lets an operator point the scan at a chosen subtree, and the source bundle stays inside the vault.+- **Trade-offs**:+ - Pro: no second grammar, no new entry point, no new trust boundary β the fence-awareness, sentinel idempotence, dedup-hash and rewrite machinery apply to the new kinds for free.+ - Pro: absent markers, behaviour is byte-identical; the two kinds are purely additive to a table.+ - Pro: reviewability comes from the destination stores (unconfirmed preference, pending proposal), not from new gating code.+ - Pro: `skill` proposals seeded by marker need a `SkillProposalPatternKind` value; adding a marker-provenance kind touches the verifier's assumptions about pattern evidence.+ - Con: does not satisfy the article's literal "arbitrary source bundle" β plain text living outside the vault must first be copied in.+ - Con: `fact` and `skill` payloads are richer than `topic=β¦`-style scalars; multi-line procedures effectively force the block shape, so the inline shape is second-class for `skill`.+- **Complexity**: small+- **Risk**: low++### Variant 2: Two kinds plus a read-only external source-bundle verb++- **Approach**: Variant 1, plus a new deterministic verb (`o2b brain scan-source <file>`) that runs `discoverMarkersDetailed` over an operator-supplied path outside the vault and reports every marker with its parse verdict. Default is report-only: no signal write, no source rewrite, because the file is outside the replicated tree and `ensureInsideVault` cannot cover it; an explicit `--import` flag copies the discovered markers into `Brain/inbox/` while leaving the external file untouched (idempotence then rests on the dedup hash alone, not on the consumed sentinel).+- **Trade-offs**:+ - Pro: matches the article's workflow exactly β a bundle authored by another tool is exercised end to end with zero model calls.+ - Pro: strong fixture and demo surface: one file, one command, structured per-marker verdicts suitable for golden tests.+ - Pro: gives cross-tool authoring a real seam without a Model Context Protocol round trip.+ - Con: introduces the first read path outside the vault root, which is a genuine new trust boundary against the path-safety invariant, and needs its own size/symlink/encoding limits.+ - Con: without in-file rewrite, re-running `--import` over the same bundle relies entirely on dedup hashing; any hash-relevant field change silently re-imports as new.+ - Con: a new verb means a new registered diagnostic code family for its failures and a new command-line surface to keep stable.+- **Complexity**: medium+- **Risk**: medium++### Variant 3: New kinds route into the staged dream proposal bundle++- **Approach**: Add the two kinds as in Variant 1, but do not let them write to their final stores. Marker discovery becomes an input to `dream stage`: `fact` and `skill` markers flatten into `proposals.jsonl` as new proposal types (`create_derived_fact`, `create_skill_proposal`) alongside the existing `create_preference` rows, and are only materialised when the operator applies the bundle. The staged report renders them in their own sections, and discard drops them with the rest of the bundle.+- **Trade-offs**:+ - Pro: closest to the article's actual thesis β reviewable self-improvement, with a single uniform review point rather than one per destination store.+ - Pro: one place to validate premises and skill shape, so the skill verifier is never handed a marker-seeded candidate it has no pattern evidence for.+ - Pro: the persisted bundle is already the deterministic artifact tests assert against, so fixtures get stronger with no new file format.+ - Con: widens `planToProposals` and the plan type beyond preference/signal lifecycle, which is the largest conceptual change of the three.+ - Con: markers now have two different fates depending on kind (feedback writes a signal immediately, fact/skill waits for an apply), which is a real asymmetry operators must learn.+ - Con: plan-drift detection between stage and apply must be extended to cover the new rows, or a bundle can be applied against source files that have since changed.+- **Complexity**: medium to large+- **Risk**: medium++### Recommended: Variant 1++**Rationale**: The open question resolves to "no" β `scan-inline --path` and `apply-markers --path` already give an operator marker discovery over a chosen subtree, and reading source files outside the vault would breach the path-safety invariant for a convenience the operator can get by placing the bundle in the vault, so Variant 2's cost buys little. Variant 3 solves a review problem that is already solved by the destination stores: a marker-seeded fact becomes an *unconfirmed* preference that the dream pass gates, and a marker-seeded skill lands in the *pending* proposal store that already has accept/reject, so routing them through the stage bundle duplicates gating rather than adding it. Variant 1 keeps the change to two rows in `REQUIRED_FIELDS`, two type guards and their routing, which is byte-identical when the markers are absent and is exactly the narrow delta the re-verification identified.diff --git a/docs/brainstorm/signals-that-survive/cli-output/claude-query-temporal-intent.md b/docs/brainstorm/signals-that-survive/cli-output/claude-query-temporal-intent.mdnew file mode 100644index 00000000..d4874508--- /dev/null+++ b/docs/brainstorm/signals-that-survive/cli-output/claude-query-temporal-intent.md@@ -0,0 +1,38 @@+### Variant 1: Temporal intent at the query-plan seam, modulating `recencyMul` only+- **Approach**: Extend `src/core/search/query-plan.ts` with a new structural `temporal` intent, detected only from signals that survive the language-agnostic invariant β ISO tokens in the query text (reusing `extractTemporalConstraints`) and the existing `<field>:<value>` grammar (`since:`/`until:`). The plan resolves a target window and, when that window's midpoint is materially older than `now`, emits a `WeightProfile` with `recencyMul` below 1 (down to 0 for an explicitly historical query); a near-now window amplifies it. Nothing in `ranker.ts` changes β `recency * recMul` at ranker.ts:416 is already the modulation point.+- **Trade-offs**:+ - Smallest possible diff: one detector, one profile row, zero new scoring layers, zero new `ScoreBreakdown` fields, no MCP surface change.+ - `planHash` already feeds the query cache, so cache correctness comes for free.+ - Bounded by construction β the existing `[0.7, 1.4]` profile discipline means a misdetection can only re-weight, never float an unrelated document.+ - Only suppresses or amplifies; it cannot *promote* documents inside the target window, so "what did I decide back in spring?" stops being actively hurt but is not actively helped.+ - Overloads a single scalar with two distinct meanings (freshness prior strength vs. temporal-intent direction), which makes the `reasons` output harder to read: a suppressed recency layer just silently disappears.+ - `WeightProfile` is currently a per-intent constant table; a window-derived continuous `recencyMul` breaks that table's "fixed structural-feature β profile" property.+- **Complexity**: small+- **Risk**: low++### Variant 2: Anchor-shifted Weibull β recency measured from the query window, not from `now`+- **Approach**: Keep one recency layer but make its reference instant query-derived: the plan resolves a target window and `search.ts` threads an optional `recencyAnchorMs` (or the resolved window) into `RankerOptions`, so `recencyBoost` computes age as distance from the *window edge* rather than from `now`. Absent an anchor the age is `now - mtime` exactly as today, so ranking stays byte-identical; with an anchor, the same Weibull curve becomes a soft two-sided band centred on the queried period.+- **Trade-offs**:+ - Conceptually the most faithful reading of "window-shift the recency layer": one curve, one tuning surface, `recencyShape`/`recencyScale`/`recencyAmplitude` keep their meaning, and `recencyAmplitude: 0` remains the documented global off switch.+ - No new score component, no new breakdown field, no growth in the explain payload.+ - Changes the semantics of `weibullDecay`'s only input from "age" to "distance", which currently has a documented one-sided contract (`ageDays <= 0`, including future timestamps, returns full amplitude). Making it two-sided touches the most-depended-upon and most-tested primitive in the ranking stack.+ - The `recency: 0.041` reason string silently changes meaning per query, and downstream consumers (`feedback.ts`, MCP `explain`, tuning/eval gates, the semantic-health baseline watermark) compare recency across queries β a shifted anchor makes those series non-comparable without a marker field.+ - Fights the existing tie-break, which sorts by `mtime` descending: an older in-window document can win on score and then lose the tie-break to a newer out-of-window one.+- **Complexity**: medium+- **Risk**: high++### Variant 3: Detection at the plan seam + a separate capped `temporal_match` layer+- **Approach**: Same detection front half as Variant 1 (ISO tokens plus structured field tokens, resolved through `time-range.ts` into a `ResolvedTimeRange`), but the ranker consumes it as its own bounded additive layer rather than as a recency multiplier: reuse the already-pure `temporalProximity` from `temporal-bridge.ts` over a per-candidate event time (validity start, else `mtime`) to produce a capped boost, alongside a modest `recencyMul` damping when the window is historical. It follows the exact shape every other layer in `rankResults` uses β optional input map, absent map contributes zero, one `reasons` entry, one `ScoreBreakdown` field.+- **Trade-offs**:+ - Handles both halves of the problem: suppresses the wrong-direction freshness prior *and* promotes documents that actually sit in the queried window, which is the whole point of the upstream signal.+ - Reuses two already-written, already-tested pure functions (`temporalProximity`, `parseTimePoint`) and the existing event-time resolver `search.ts` already builds for the temporal bridge β very little genuinely new math.+ - Freshness prior and temporal intent stay separately observable in `reasons`/`breakdown`, so tuning, eval gates, and the `explain` projection can attribute a ranking change to the right layer.+ - Soft window match complements β rather than duplicates β the existing hard `since`/`until` filter: a query-text-derived window biases without excluding, which is the safer default for an inferred signal.+ - Widest blast radius of the three: a new `ScoreBreakdown` key (additive, but it is an MCP-visible shape), new plumbing through `search.ts`, and a new capped constant that must be calibrated against the link/entity/activation/reuse caps so the layers stay in proportion.+ - Requires an event-time map for the full candidate pool, not just link expansions β more store work per query than either alternative.+ - Two knobs move at once (new boost plus recency damping), so an A/B on retrieval quality needs both isolated.+- **Complexity**: medium+- **Risk**: medium++### Recommended: Variant 3+**Rationale**: It is the only variant that delivers the actual upstream capability β biasing *toward* the queried window β rather than merely stopping the freshness prior from hurting, and it does so in the exact idiom the ranker already uses (optional input map, capped additive boost, absent map β byte-identical ranking), so the "every new key leaves behaviour byte-identical when absent" constraint is satisfied structurally rather than by care. Variant 2 buys elegance by mutating `weibullDecay`'s contract and silently redefining the `recency` component that tuning, feedback, and eval gates already track across queries, which is a disproportionate regression surface for an enhancement-priority item. Variant 1 is the cheapest and is a legitimate fallback if scope must shrink, but it leaves the motivating "what did I decide back in spring?" case only half-served; note that under this repo's language-agnostic rule, *all three* variants must detect intent from ISO tokens and structured field tokens only β the "last week"/"recently" natural-language detection Signet performs is not portable here and should not be attempted.diff --git a/docs/brainstorm/signals-that-survive/cli-output/claude-recurring-weak-recall-obligation.md b/docs/brainstorm/signals-that-survive/cli-output/claude-recurring-weak-recall-obligation.mdnew file mode 100644index 00000000..a724652c--- /dev/null+++ b/docs/brainstorm/signals-that-survive/cli-output/claude-recurring-weak-recall-obligation.md@@ -0,0 +1,40 @@+### Variant 1: Verdict-stamped demand log, dream-phase minting into obligations+- **Approach**: Solve question identity by reusing the bucket key `query-demand.ts` already owns β sorted significant terms (`normalizeQueryTerms`, IDF-derived, redacted, capped), never a word list β by adding an optional `adequacy` level to `QueryDemandRecord` and stamping it from the two existing verdict sites (`brain_recall_gate`, `brain_context_pack`). A new dream phase aggregates buckets whose weak/insufficient count clears a demand threshold, ranks by the existing `demandScore`, and mints at most top-N obligations via `addObligation` with a slug hashed from the bucket key and a re-check cadence, deduped through `obligationExists`. Session-start renders open obligations of that kind as the agenda, and the dream phase completes an obligation once the same bucket recalls `sufficient`.+- **Trade-offs**:+ - Pro: no new store, no new key concept β compaction, byte caps, secret-shaped-term dropping, and `[since, until]` filtering are inherited, not rebuilt.+ - Pro: minting is off the recall hot path; the dream pass is where the project already puts gated batch promotion, and caps are naturally per-run rather than per-attempt.+ - Pro: matches the brief's explicit "mint an obligation, not a board item" scoping without touching `agenda.ts`.+ - Con: couples two features β a demand record now also carries a retrieval verdict, so `query-demand.ts` stops being purely about coverage.+ - Con: obligations are cadence-bearing by construction; a one-shot "write coverage for this topic" is an awkward fit, and the re-check cadence is a semantic stretch that needs justifying.+ - Con: nothing happens until dream runs β the loop closes on a schedule the operator may not run, and a never-dreaming vault silently accumulates nothing.+ - Con: `demandScore` was tuned for coverage-driven ranking; reusing it as the mint trigger imports a threshold that was never validated for this purpose.+- **Complexity**: medium+- **Risk**: medium++### Variant 2: Second signal source into the existing gap loop, gap-task as the durable item+- **Approach**: Emit each adequacy verdict as a gated continuity record through `emitGatedTelemetry`, carrying the bucket key computed by the shared `normalizeQueryTerms` pure function so no new identity logic is invented. Generalize `gaps/gap-loop.ts` `detectRecurringGaps` to aggregate over both its current structural `gap_counts` source and the new verdict records, leaving promotion (`promoteGapsToTasks`, exclusive-create dedupe on `gapTaskKey`), the session-start agenda (`renderGapAgenda`), and auto-close (`autoCloseRecalledGaps`, with the self-close guard) exactly as built. Wire the currently dormant module into the session-start/session-end hooks behind the existing `gap_loop_enabled` / `gap_loop_threshold` keys.+- **Trade-offs**:+ - Pro: the promotion β agenda β auto-close half is already implemented and tested; this variant adds a signal source and hook wiring rather than a second copy of the same machinery.+ - Pro: auto-close is what makes the item *bounded* β a minted item that resolves itself when coverage appears is the difference between a tracked obligation and vault litter; only gap-loop has it today.+ - Pro: telemetry rides the continuity rail as convention requires (config-gated, fail-open, redaction-passing), and the agenda surface is one that was purpose-built for recall gaps.+ - Con: deviates from the brief's stated target β obligations get no use, and the vault gains recall-driven items in `Brain/gap-tasks/` instead of `Brain/obligations/`.+ - Con: scope grows beyond the feature: this variant must also wire a dormant module, so a bug there surfaces as a regression in this release.+ - Con: mixing a coarse structural code bucket (`no_matching_context`) and a fine term bucket in one aggregate makes `occurrences` mean two different things across rows in the same agenda.+ - Con: leaves the repo with two candidate durable-item kinds; if obligations later become the convention, this needs a migration.+- **Complexity**: medium+- **Risk**: low++### Variant 3: Structural retrieval-neighborhood fingerprint, no query text at all+- **Approach**: Define question identity with zero natural-language input β hash the ordered top-artifact id set from the `recall_telemetry` `top_artifacts` payload into a "weak neighborhood" fingerprint, falling back to the registered structural gap code when the attempt returned nothing. Aggregate directly over `recall_telemetry` continuity records already on disk, so the feature works retroactively over existing history with no new store and no new emitted field, and mint one obligation per neighborhood that clears both an occurrence and an escalation threshold.+- **Trade-offs**:+ - Pro: the strictest possible reading of the language-agnostic rule β the key never touches prompt text, so it cannot be argued into a word list later.+ - Pro: no new persistence, no new write path, and no change to the two verdict call sites; retroactive over telemetry already captured.+ - Con: the fingerprint is unstable β one different artifact in top-k forks the bucket, so demand fragments across near-identical questions and the threshold rarely clears at all.+ - Con: the zero-result case is the one that matters most and has no artifacts, so it collapses onto a handful of coarse gap codes and over-aggregates unrelated questions into a single obligation.+ - Con: making it work needs quantization or set-similarity tuning β a new knob class the project deliberately avoids, and one that cannot be validated without a corpus.+ - Con: builds a third recurrence-key concept alongside the two the repo already has, with no reuse of the redaction and cap work.+- **Complexity**: large+- **Risk**: high++### Recommended: Variant 2+**Rationale**: The genuinely missing piece is only the aggregation link β `query-demand.ts` already solved deterministic, language-agnostic question identity and `gaps/gap-loop.ts` already implements promotion, the session-start agenda, and the auto-close that makes a minted item bounded rather than permanent litter, so this variant adds a signal source and hook wiring instead of a second copy of that machinery. It also gives the caps their teeth: an item that closes itself when recall recovers is a stronger guard against one bad afternoon than any mint threshold. The one deliberate deviation is the durable target β this mints a gap-task, not an obligation; that still satisfies the actual constraint the validator was protecting (stay internal, never write to an external board), but it contradicts the brief's literal instruction and should be confirmed before implementation, since Variant 1 is the ready alternative if obligations must be the artifact.diff --git a/docs/brainstorm/signals-that-survive/cli-output/claude-route-discriminator.md b/docs/brainstorm/signals-that-survive/cli-output/claude-route-discriminator.mdnew file mode 100644index 00000000..29c33b37--- /dev/null+++ b/docs/brainstorm/signals-that-survive/cli-output/claude-route-discriminator.md@@ -0,0 +1,43 @@+### Variant 1: In-router discriminator ladder on a candidate-score table++- **Approach**: Keep `routeExtractedFacts` as the single write router, but split its decision into two explicit pure functions: `scoreRouteCandidates(fact, ctx)` returning a frozen, deterministically-ordered `{ route, score }[]` built from the structural features already available (family-pattern match length, span coverage of the line, overlap with a URL range, entity-anchor count, durability signal set, dedup history for the hash), and `discriminate(candidates)` which fires only when `top.score - second.score <= MARGIN`. The discriminator is a fixed, ordered ladder of registered rules, each a pure structural predicate with a stable id (`overlap-containment`, `anchor-majority`, `span-coverage`, `family-table-order` as the terminal always-decides rule); the first rule that separates the tied candidates wins and its id is recorded. Every discrimination emits one `route_discrimination` continuity record through `emitGatedTelemetry` behind a new config key, carrying the candidate set, scores, margin, winning route, and the rule id β never the fact text.+- **Trade-offs**:+ - Pro: touches one call site; the existing dedup β durability β staging β write chain is unchanged, and with the gate key absent behaviour is byte-identical because the terminal rule reproduces today's family-table order.+ - Pro: fully deterministic and word-list-free β every feature is a count, an offset, or a set membership, so it behaves identically across scripts.+ - Pro: rule ids make tie-breaks auditable and tunable; `MARGIN` is one named constant, and misroute rates become measurable per rule.+ - Pro: no new public CLI/MCP surface required to ship the mechanism; the reader can follow later.+ - Con: the score table is bespoke to the extracted-facts router; a second write path (preference vs note vs pinned) would need its own copy unless it is generalised later.+ - Con: score weights are a tuning surface with no ground truth on day one β early records will mostly confirm the terminal rule fires, which looks like low value until data accumulates.+ - Con: adds a second decision point to a hot capture path, so the ladder must stay allocation-cheap.+- **Complexity**: medium+- **Risk**: low++### Variant 2: Extracted two-stage routing kernel shared by all write surfaces++- **Approach**: Introduce `src/core/brain/routing/` holding a route-agnostic kernel β a `RouteCandidate` type, a `CandidateScorer` interface, a `Discriminator` registry keyed by stable id, and a `resolveRoute()` driver that runs primary scoring, detects near-equality, applies the registry in registration order, and emits the gated `route_discrimination` record once for every write surface. `routeExtractedFacts` becomes the first consumer by supplying a fact-specific scorer; the signal/preference/note/pinned writer entry points become subsequent consumers with their own scorers over the same kernel, so the tie-break record shape is identical regardless of which write path produced it.+- **Trade-offs**:+ - Pro: DRY across the whole write surface β the misfiled-write problem the task names is not confined to extracted facts, and this is the only variant that addresses signal-vs-obligation and note-vs-decision ambiguity in the same mechanism.+ - Pro: one telemetry schema, one config gate, one advisory-rail code family for every routed write; `dream` gets a uniform reconciliation input.+ - Pro: the registry makes the discriminator set inspectable and testable independently of any router.+ - Con: largest blast radius β it re-plumbs write paths that currently have no ambiguity problem proven against them, and the writer MCP tools are an existing public surface that must stay compatible.+ - Con: the abstraction is being designed from exactly one concrete consumer, so the scorer interface risks being shaped wrong and rewritten at the second adopter.+ - Con: significant test surface across many existing writer tests before any behaviour improves.+- **Complexity**: large+- **Risk**: medium++### Variant 3: Ambiguity as its own route β quarantine plus a registered advisory exit++- **Approach**: Compute the same candidate score table, but when the top candidates are within the margin, do not pick a winner: route the fact to an explicit ambiguous lane (reusing the existing `Brain/pending/` staging machinery already wired through `writeApprovalEnabled` and `brainDirsForWrite`), record the full candidate set on the staged item, and surface a registered advisory-rail code so the operator or `dream` resolves it. The tie-break rules exist only as ranking hints presented alongside the candidates, never as an autonomous decision, and the gated `route_discrimination` record captures both the candidate set and the eventual resolution when it lands.+- **Trade-offs**:+ - Pro: strictly honest β an ambiguous write is never silently guessed, and it fits the v1.40.0 "every diagnosis names its exit" precedent directly, since ambiguity is exactly a state that needs a named exit.+ - Pro: reuses `Brain/pending/` rather than inventing a lane; the resolution events become ground-truth training data for the score table a later variant would need.+ - Pro: zero risk of a wrong automated tie-break, since there is no automated tie-break.+ - Con: does not actually cut the misfiled-write rate β it converts misfiles into operator queue depth, moving the cost rather than removing it, and the task's stated value is reducing what `dream` must reconcile.+ - Con: a low margin threshold floods the pending lane; a high one makes the whole stage inert, and there is no data yet to pick between them.+ - Con: requires a resolution surface (CLI or MCP) to drain the lane, or the quarantine is a leak.+- **Complexity**: medium+- **Risk**: medium++### Recommended: Variant 1++**Rationale**: It delivers the actual deliverable β a deterministic, auditable tie-break with its own gated emission β against the one router the corrected hints anchor to, without re-plumbing write paths whose ambiguity is still hypothetical, and the terminal `family-table-order` rule guarantees byte-identical behaviour when the gate key is absent as the conventions require. Variant 2 designs a cross-surface abstraction from a single consumer and would very likely be rewritten at the second one; the kernel is the right eventual shape, but only after Variant 1's records show what the scorer interface actually needs. Variant 3 answers a different question (who resolves ambiguity) rather than the one asked (how routing disambiguates), and its quarantine lane is best added later as a bounded escalation when Variant 1's telemetry shows a margin band the ladder genuinely cannot separate.diff --git a/docs/brainstorm/signals-that-survive/cli-output/claude-unroutable-capture-hint.md b/docs/brainstorm/signals-that-survive/cli-output/claude-unroutable-capture-hint.mdnew file mode 100644index 00000000..c95ddd57--- /dev/null+++ b/docs/brainstorm/signals-that-survive/cli-output/claude-unroutable-capture-hint.md@@ -0,0 +1,39 @@+### Variant 1: Extend the existing write-advisory seam with a scope-routing hint+- **Approach**: Add a sibling of `adviseIncomingFeedback` in `src/core/brain/write-advisory.ts` that runs on the same operator-facing feedback path (CLI `o2b brain feedback` and MCP `brain_feedback`), after the write has landed. When the effective scope resolves to `undefined` (no `--scope`, no `feedback.default_scope`), it returns a structured `routing_hint` naming the missing signal (`scope`) plus the eligible scope slugs observed in the vault β the distinct `scope` values on confirmed preferences and recent signals, ranked by document frequency. An empty candidate set yields `null` (the absent case, exactly like the conflict advisory), so a fresh personal vault stays silent; the human path prints its forward pointer through `emitNextStep` against one newly registered `DIAGNOSTIC_SIGNALS` code.+- **Trade-offs**:+ - Reuses a proven, tested precedent for "non-blocking, computed around the write, surfaced as a structured field and logged" β the shape the triage note asked for, with no new mechanism.+ - No new configuration key, so the "byte-identical when absent" rule is satisfied by construction: an unscoped write on a vault with no scope corpus behaves exactly as today.+ - Eligible scopes come from vault frontmatter and frequency, not from any word list, so the language-agnostic rule holds.+ - Touches only two call sites that already thread `effectiveScope`; `routeExtractedFacts` is untouched, preserving the existing "advisory never double-fires on the extracted-fact path" invariant.+ - Covers only the feedback surface. Anchor-less extracted facts and note captures remain unhinted, so the "unrouted note" problem is addressed for one write family, not all of them.+ - Inferring eligibility from corpus frequency means the candidate list drifts with vault contents and can surface a scope the operator considers retired.+ - Needs one registered diagnostic code whose `nextCommand` must be a structural string; the honest exit is re-recording with `--scope` or setting `feedback.default_scope`, so the registry entry has to name a real command rather than a paraphrase.+- **Complexity**: small+- **Risk**: low++### Variant 2: Declared scope registry in Brain config+- **Approach**: Widen the existing `feedback:` config block from a single `default_scope` into a declared registry of eligible scopes (each with the slug it routes to), mirroring upstream's "covers-declaring scopes are registered" model. A scope-less write consults the registry and returns a hint naming the missing routing signal and the registered scopes it could have carried; with no registry declared, the hint never fires and the path stays byte-identical. Validation lives in `policy.ts` beside the existing `feedback.default_scope` rules, sharing the same slug constraints.+- **Trade-offs**:+ - Highest fidelity to the upstream feature: eligibility is declared by the operator rather than guessed, so the hint never names a stale or accidental scope.+ - Silent by default on personal installs, which matches upstream behaviour and satisfies the additive-configuration rule cleanly.+ - Gives the vault an explicit routing vocabulary that later surfaces (hygiene, dream, active-pack scoping) could reuse, so the investment is not single-purpose.+ - Requires the operator to configure something before the feature does anything, which is the opposite of the "reduce unrouted notes" goal for the users most likely to have them β the ones who never configured scopes.+ - Adds config schema, validation, template, and documentation surface for a hint, which is a large ratio of mechanism to payoff.+ - Two sources of truth for what a valid scope is (declared registry versus scopes already on disk) invites drift and a new doctor check to reconcile them.+- **Complexity**: medium+- **Risk**: medium++### Variant 3: Cross-surface capture-routability seam+- **Approach**: Introduce one routability module that every capture write funnels through, modelling "missing routing signal" as a small closed set of families: a scope-less feedback signal, an extracted fact that resolved no canonical entity anchor, and a captured note with no anchor or scope. Each family declares its missing-signal token and its candidate resolver, each maps to its own registered diagnostic code, and the aggregate is emitted through `emitGatedTelemetry` so unrouted-capture rates become observable alongside the existing route metrics.+- **Trade-offs**:+ - Addresses the actual retrieval-noise problem end to end: anchor-less extracted facts are the larger unrouted population, and they are exactly what Variant 1 leaves out.+ - One model for "unroutable capture" instead of a per-surface advisory, which is the DRY answer if more capture surfaces arrive later.+ - Telemetry makes the effect measurable rather than asserted, matching how this codebase already treats recall and route quality.+ - `routeExtractedFacts` runs per fact inside the capture hot path; adding a candidate-resolution step there risks turning a bounded loop into a per-fact vault read unless results are hoisted, and that path is already carefully budgeted.+ - Breaks the documented invariant that the advisory fires only on the operator-facing feedback path, so the double-fire question has to be re-answered rather than inherited.+ - Largest blast radius across capture, MCP, CLI, and telemetry for a feature whose user-visible output is one hint line; several hundred existing capture tests sit downstream of these seams.+- **Complexity**: large+- **Risk**: medium++### Recommended: Variant 1+**Rationale**: The transferable half of the upstream feature is the shape β a non-blocking hint that names the missing routing signal β and `write-advisory.ts` already implements that shape on the same path, with the same fail-soft, never-blocks-the-write contract and the same structured-field-plus-log surfacing, so the work is an extension rather than a new mechanism. It needs no new configuration key and no change to the extracted-fact hot path, which keeps the "byte-identical when absent" and capture-performance constraints trivially satisfied, and it resolves its forward pointer through the registered advisory rail as the v1.40.0 convention requires. Variant 2 asks the operator to configure their way into the benefit they lack, and Variant 3 spends a large refactor across the hottest capture seam before the smaller version has demonstrated that the hint changes behaviour.diff --git a/docs/brainstorm/signals-that-survive/cli-output/prompt-doctor-path-duplication.md b/docs/brainstorm/signals-that-survive/cli-output/prompt-doctor-path-duplication.mdnew file mode 100644index 00000000..51b98e4b--- /dev/null+++ b/docs/brainstorm/signals-that-survive/cli-output/prompt-doctor-path-duplication.md@@ -0,0 +1,85 @@+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++## brain doctor prints the file path twice on parse-error findings++Found while capturing real command output for the v1.40.0 release cover.++`o2b brain doctor` renders a parse-error finding as:++ [ERROR] preference-missing-field: preference missing field: created_at (/vault/Brain/preferences/pref-x.md) (/vault/Brain/preferences/pref-x.md)++The path appears twice: once inside the message text, and once appended by the renderer's `${issue.path ? ` (${issue.path})` : ""}` tail.++NOT a v1.40.0 regression - verified: the render template in src/cli/brain/verbs/doctor.ts is byte-identical to the one at f91a698b (v1.39.0), and the v1.40.0 wave changed only how the parse-error CODE is derived, not the message text. The duplication comes from the doctor wrapping the parse error with the path in the message while also setting the structured `path` field.++Fix direction: the structured field is the one to keep - v1.40.0 established that findings should carry their data as fields rather than in prose, so the message should stop embedding the path rather than the renderer stop appending it. Check the other parse-error kinds (retired-*, and the invalid variants) for the same shape before changing one.++Cosmetic only; no behaviour or exit code is affected.++--- validator comment [claude-dev-agent]:+claude-dev-agent @ 2026-07-27: triage validation pass (operator-directed: link + priority actualization; internal work ranks above external-product integration)+- priority: 2 -> 3.+- verified this run: the duplication is live at src/cli/brain/verbs/doctor.ts:49 - the renderer appends ${issue.path ? ` (${issue.path})` : ""} while the doctor also embeds the path inside issue.message.+- rank rationale: fully specified, anchored, internal, zero external dependency, and the fix direction is already written down. Cosmetic, so not 4 - but nothing on the board is more ready to start.++# Project context++Project: Open Second Brain - a TypeScript/Bun command-line tool plus Model Context Protocol server over an Obsidian-compatible Markdown vault.+Runtime: Bun. Tests: `bun test` via `bash scripts/test` (910 *.test.ts files). Typecheck: `tsc --noEmit`. Lint: oxlint. Format: oxfmt.++Recent commits (newest first):+0963ef0a feat: no dead ends - every diagnosis names its exit (v1.40.0) (#151)+f91a698b feat: context integrity gates (v1.39.0) (#150)+c31a2574 feat: semantic-health baseline watermark (v1.38.0) (#148)+b0c37977 feat: retrieval quality and context delivery (v1.37.0) (#146)+842d690f feat: knowledge intake and consolidation (v1.36.0) (#145)+95dc8577 feat: trusted recall and memory write surface (v1.35.0) (#144)+426d06f8 fix(vault): parse block-style YAML lists in frontmatter (not just inline arrays) (#142)+4b8100ca feat: source pipeline integrity and operator tooling (v1.34.0) (#143)+77513f2b feat: belief lifecycle and decision memory (v1.33.0) (#141)+61e93d24 fix(config): derive vault store reference from a keyed installation secret (#140)+9a649dd6 feat: memory write-path integrity and store safety wave (v1.32.0) (#139)+f2a037eb feat: today operator surface - dashboard, open loops, marker write-back (v1.31.0) (#138)+13bde6c3 refactor: remove all import cycles, decompose search.ts (v1.30.1) (#137)+fd5661f9 feat: governance visibility - vitals scorecard + batch-inflation lint (v1.30.0) (#136)+a99b0e71 feat(brain): add o2b brain vitals scorecard + batch-concept-inflation lint (#135)+70fb36e1 feat: operability, safety & first-run experience (v1.29.0) (#134)+ac26a675 feat: retrieval & ranking quality (v1.28.0) (#133)+5cd52e70 fix(hermes): resolve o2b when memory provider PATH is tiny (v1.27.1) (#131)+99adb65f feat: ingestion & import robustness (v1.27.0) (#132)+fb474acc test(hermes): verify OSB surface against core normalize/validate-before-wrap and in_place compaction (1.26.1) (#129)++Conventions:+- The kernel is deterministic. It issues no model calls. Anything that must classify, rank, or gate does so from structural signals or numeric scores.+- Search, classification, ranking and extraction must be language-agnostic. Hardcoded natural-language word lists (stop-words, greetings, keywords, negations) are forbidden in EVERY language.+- Every new flag, argument or configuration key must leave behaviour byte-identical when absent.+- A forward pointer printed to the operator resolves a REGISTERED diagnostic code through the advisory rail (src/cli/advisory-rail.ts, src/core/brain/next-step.ts). Caller-supplied prose is rejected by a build ratchet.+- Findings carry their data as structured fields, not embedded in prose messages.+- The vault is plain Markdown replicated peer-to-peer by Syncthing. There is NO git transport for the vault, and nothing may place a .git directory inside the replicated tree.+- Continuity telemetry is emitted through emitGatedTelemetry (src/core/brain/continuity/emit.ts): gated by a configuration key, fail-open, redaction-passing.++Constraints:+- No fallback that silently does nothing. An error must surface explicitly as an error.+- No stubs, no placeholders, no dead code paths.+- SOLID, KISS, DRY. Anything extractable belongs in a named constant or local.+- Do not add an external service dependency, and do not introduce a new runtime dependency without saying so explicitly as a trade-off.+- Do not change existing public command-line or Model Context Protocol surfaces incompatibly.++# Required output format++Produce exactly 3 distinct architectural variants. For each variant:++### Variant N: <short name>+- **Approach**: 2-3 sentences describing the variant.+- **Trade-offs**: bullet list of pros and cons.+- **Complexity**: small | medium | large+- **Risk**: low | medium | high++After the three variants, add exactly one recommendation:++### Recommended: Variant N+**Rationale**: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.++Output nothing outside of these sections.diff --git a/docs/brainstorm/signals-that-survive/cli-output/prompt-durable-work-identity.md b/docs/brainstorm/signals-that-survive/cli-output/prompt-durable-work-identity.mdnew file mode 100644index 00000000..ed7f000b--- /dev/null+++ b/docs/brainstorm/signals-that-survive/cli-output/prompt-durable-work-identity.md@@ -0,0 +1,91 @@+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++## [upstream:contextlattice] Durable cross-session work identity with explicit execution lanes, replacing the timing crutch++**Source**: https://github.com/sheawinkler/contextlattice/releases/tag/v3.18.0+**Repo**: sheawinkler/contextlattice (61β )+**Released**: v3.18.0 (2026-07-15T15:36:08Z)++## What+A stable work/task identity that survives agent, account, model, session, branch, and worktree changes, with execution "lanes" kept explicit so parallel work cannot be collapsed into one process. Exact/external task IDs always win; semantic matching stays advisory and abstains on ambiguity.++## Why useful for OSB+OSB currently only has session lineage (parent/root/depth) and resolves "continuation vs parallel work" with a timing-based crutch (`CRUTCH_LINK_WINDOW_MS = 900_000`). A durable work identity would let the crutch resolver key on a stable ID instead of a 15-minute window, correctly re-attaching resumed work after a model/branch/worktree switch and refusing to merge concurrent lanes.++## Status in OSB+- **Verdict**: not_in_osb_useful+- **Codegraph hints**: No durable cross-session task-identity concept found. Session lineage only: `src/core/brain/lineage/ledger.ts:74` (`LedgerLine`), `:42` (`LEDGER_FILE`), `:34` (`CRUTCH_LINK_WINDOW_MS`=900_000). Timing-crutch resolver: `crutch.ts` (CRUTCH t_1459706f). Idea stage transitions (`src/core/brain/idea-lineage.ts:296` `transitionStage`) are the nearest analog but scope ideas/prefs, not work items with lanes.++## Notes+The explicit-lane / abstain-on-ambiguity contract is the substantive part β it directly targets the failure mode the timing crutch has (two parallel sessions inside the same window getting linked). Scope as an enhancement to the lineage/crutch layer, not a new subsystem.++--- validator comment [osb-triage-validator]:+osb-triage-validator @ 2026-07-18T08:30:00Z:+- sanity: clean+- cluster: parent of t_232fcf70 (existing link, unchanged)+- priority: set to 2: not_in_osb_useful, architectural (durable cross-session work identity + explicit execution lanes replacing CRUTCH_LINK_WINDOW_MS timing crutch) - needs ADR++--- validator comment [claude-dev-agent]:+SCOPE NARROWED by v1.39.0 (https://github.com/itechmeat/open-second-brain/releases/tag/v1.39.0, PR #150). This task's body says the substantive part is the explicit-lane / abstain-on-ambiguity contract, because it targets the failure mode where two parallel sessions inside the same window get linked. THAT FAILURE MODE IS NOW FIXED: t_580bb87c shipped the abstention layer - resolveCrutchLineage returns a discriminated outcome (linked, or an abstention naming no-candidate / self-known / no-workspace / ambiguous / stale / evidence-missing), two surviving candidates abstain instead of resolving by most-recent-wins, and repo/branch/commit joined cwd as required-match predicates. A dropped ledger observation is also recorded as a named gap and excluded from matching, so a lost write cannot invert the rule into a false stitch. What REMAINS in scope here: a durable work identity that survives agent, account, model, session, branch and worktree changes, so the resolver can key on a stable id instead of CRUTCH_LINK_WINDOW_MS = 900_000, which is still the freshness bound. Do not re-implement the ambiguity handling - it is in main.++# Project context++Project: Open Second Brain - a TypeScript/Bun command-line tool plus Model Context Protocol server over an Obsidian-compatible Markdown vault.+Runtime: Bun. Tests: `bun test` via `bash scripts/test` (910 *.test.ts files). Typecheck: `tsc --noEmit`. Lint: oxlint. Format: oxfmt.++Recent commits (newest first):+0963ef0a feat: no dead ends - every diagnosis names its exit (v1.40.0) (#151)+f91a698b feat: context integrity gates (v1.39.0) (#150)+c31a2574 feat: semantic-health baseline watermark (v1.38.0) (#148)+b0c37977 feat: retrieval quality and context delivery (v1.37.0) (#146)+842d690f feat: knowledge intake and consolidation (v1.36.0) (#145)+95dc8577 feat: trusted recall and memory write surface (v1.35.0) (#144)+426d06f8 fix(vault): parse block-style YAML lists in frontmatter (not just inline arrays) (#142)+4b8100ca feat: source pipeline integrity and operator tooling (v1.34.0) (#143)+77513f2b feat: belief lifecycle and decision memory (v1.33.0) (#141)+61e93d24 fix(config): derive vault store reference from a keyed installation secret (#140)+9a649dd6 feat: memory write-path integrity and store safety wave (v1.32.0) (#139)+f2a037eb feat: today operator surface - dashboard, open loops, marker write-back (v1.31.0) (#138)+13bde6c3 refactor: remove all import cycles, decompose search.ts (v1.30.1) (#137)+fd5661f9 feat: governance visibility - vitals scorecard + batch-inflation lint (v1.30.0) (#136)+a99b0e71 feat(brain): add o2b brain vitals scorecard + batch-concept-inflation lint (#135)+70fb36e1 feat: operability, safety & first-run experience (v1.29.0) (#134)+ac26a675 feat: retrieval & ranking quality (v1.28.0) (#133)+5cd52e70 fix(hermes): resolve o2b when memory provider PATH is tiny (v1.27.1) (#131)+99adb65f feat: ingestion & import robustness (v1.27.0) (#132)+fb474acc test(hermes): verify OSB surface against core normalize/validate-before-wrap and in_place compaction (1.26.1) (#129)++Conventions:+- The kernel is deterministic. It issues no model calls. Anything that must classify, rank, or gate does so from structural signals or numeric scores.+- Search, classification, ranking and extraction must be language-agnostic. Hardcoded natural-language word lists (stop-words, greetings, keywords, negations) are forbidden in EVERY language.+- Every new flag, argument or configuration key must leave behaviour byte-identical when absent.+- A forward pointer printed to the operator resolves a REGISTERED diagnostic code through the advisory rail (src/cli/advisory-rail.ts, src/core/brain/next-step.ts). Caller-supplied prose is rejected by a build ratchet.+- Findings carry their data as structured fields, not embedded in prose messages.+- The vault is plain Markdown replicated peer-to-peer by Syncthing. There is NO git transport for the vault, and nothing may place a .git directory inside the replicated tree.+- Continuity telemetry is emitted through emitGatedTelemetry (src/core/brain/continuity/emit.ts): gated by a configuration key, fail-open, redaction-passing.++Constraints:+- No fallback that silently does nothing. An error must surface explicitly as an error.+- No stubs, no placeholders, no dead code paths.+- SOLID, KISS, DRY. Anything extractable belongs in a named constant or local.+- Do not add an external service dependency, and do not introduce a new runtime dependency without saying so explicitly as a trade-off.+- Do not change existing public command-line or Model Context Protocol surfaces incompatibly.++# Required output format++Produce exactly 3 distinct architectural variants. For each variant:++### Variant N: <short name>+- **Approach**: 2-3 sentences describing the variant.+- **Trade-offs**: bullet list of pros and cons.+- **Complexity**: small | medium | large+- **Risk**: low | medium | high++After the three variants, add exactly one recommendation:++### Recommended: Variant N+**Rationale**: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.++Output nothing outside of these sections.diff --git a/docs/brainstorm/signals-that-survive/cli-output/prompt-git-aware-ingest-discovery.md b/docs/brainstorm/signals-that-survive/cli-output/prompt-git-aware-ingest-discovery.mdnew file mode 100644index 00000000..4db95998--- /dev/null+++ b/docs/brainstorm/signals-that-survive/cli-output/prompt-git-aware-ingest-discovery.md@@ -0,0 +1,95 @@+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++## [upstream:obsidian-wiki] Make ingest source discovery git-aware by honoring on-disk .gitignore, .git/info/exclude, and submodules++**Source**: https://github.com/Ar9av/obsidian-wiki/releases/tag/v2026.07.10+**Repo**: Ar9av/obsidian-wiki (977β )+**Released**: v2026.07.10 (2026-07-26T05:29:26Z)++## What+Make the ingest batch planner's file discovery honor git's own view of a repository: layer the repo's on-disk `.gitignore` (root and per-directory nested), `.git/info/exclude`, and skip submodule/non-working-tree files β rather than only skipping dot-entries and applying operator-supplied `--exclude` patterns.++## Why useful for Open Second Brain+When ingesting a git repository as a source, the current planner pulls in build artifacts, vendored trees, and generated files the repo already declares ignored, wasting ingest budget and polluting `Brain/sources`. The hygiene scan already discovers files git-aware; making ingest match gives operators the discovery behavior they expect from a repo path with no extra flags.++## Status in OSB+- **Verdict**: present_weaker+- **Codegraph hints**:+ - Ingest discovery gap: `src/core/brain/ingest/batch-plan.ts:298-317` (`collectIngestible`) skips dot-entries only; its `IgnoreScope` comes solely from operator `--exclude` patterns via `buildExcludeScope` (`batch-plan.ts:283-291`). It does NOT read the repo's `.gitignore`, nested `.gitignore`, or `.git/info/exclude`; no submodule handling.+ - The git-aware pattern already exists to reuse: `src/core/hygiene/scan-repo.ts:129-181` (`buildBaseScope` layers `.git/info/exclude` + root `.gitignore`; `collectFiles` layers per-directory `.gitignore`) and `scan-repo.ts:205-229` (`listScanTargets`).+ - Shared engine both paths already import: `src/core/fs/ignore.ts` (`IgnoreScope`, `parseIgnorePatterns`, `isIgnored`).+ - Git-repo detection available if discovery should branch on it: `src/core/brain/git/reader.ts:77` (`isGitRepo`).++## Notes+- The bulk of the machinery exists; the work is mostly wiring the hygiene scan's base-scope + per-directory layering into `collectIngestible`, keeping the no-git-files path byte-identical (empty scope) so existing plans/`planId`s do not shift.+- Submodule handling is net-new for both paths and is the one piece not already solved elsewhere β scope it explicitly or defer it.+- Not related to sync task t_c5e54902 (that is a GitHub-sync command surface); this is purely local file-discovery.++--- validator comment [claude-dev-agent]:+claude-dev-agent @ 2026-07-27: triage validation pass (operator-directed: link + priority actualization; internal work ranks above external-product integration)+- priority: 0 -> 4. Was untriaged (created 2026-07-26, no validator pass).+- verified this run, every anchor holds: the gap at src/core/brain/ingest/batch-plan.ts collectIngestible:298 / buildExcludeScope:283 (operator --exclude patterns only, dot-entry skip, no git awareness); the machinery to reuse at src/core/hygiene/scan-repo.ts buildBaseScope:129 / collectFiles:148 / listScanTargets:205; the shared engine both import at src/core/fs/ignore.ts (parseIgnoreLayer:162, parseIgnorePatterns:189, class IgnoreScope:209).+- rank rationale: top of the board. Purely internal (git metadata on disk is not an external product), present_weaker rather than net-new, and both halves of the wiring already exist - the work is composition, not design. No other task combines a real capability gap with this little unknown.+- cluster: no link. It shares the ignore engine with the hygiene scan but depends on no open task.++# Project context++Project: Open Second Brain - a TypeScript/Bun command-line tool plus Model Context Protocol server over an Obsidian-compatible Markdown vault.+Runtime: Bun. Tests: `bun test` via `bash scripts/test` (910 *.test.ts files). Typecheck: `tsc --noEmit`. Lint: oxlint. Format: oxfmt.++Recent commits (newest first):+0963ef0a feat: no dead ends - every diagnosis names its exit (v1.40.0) (#151)+f91a698b feat: context integrity gates (v1.39.0) (#150)+c31a2574 feat: semantic-health baseline watermark (v1.38.0) (#148)+b0c37977 feat: retrieval quality and context delivery (v1.37.0) (#146)+842d690f feat: knowledge intake and consolidation (v1.36.0) (#145)+95dc8577 feat: trusted recall and memory write surface (v1.35.0) (#144)+426d06f8 fix(vault): parse block-style YAML lists in frontmatter (not just inline arrays) (#142)+4b8100ca feat: source pipeline integrity and operator tooling (v1.34.0) (#143)+77513f2b feat: belief lifecycle and decision memory (v1.33.0) (#141)+61e93d24 fix(config): derive vault store reference from a keyed installation secret (#140)+9a649dd6 feat: memory write-path integrity and store safety wave (v1.32.0) (#139)+f2a037eb feat: today operator surface - dashboard, open loops, marker write-back (v1.31.0) (#138)+13bde6c3 refactor: remove all import cycles, decompose search.ts (v1.30.1) (#137)+fd5661f9 feat: governance visibility - vitals scorecard + batch-inflation lint (v1.30.0) (#136)+a99b0e71 feat(brain): add o2b brain vitals scorecard + batch-concept-inflation lint (#135)+70fb36e1 feat: operability, safety & first-run experience (v1.29.0) (#134)+ac26a675 feat: retrieval & ranking quality (v1.28.0) (#133)+5cd52e70 fix(hermes): resolve o2b when memory provider PATH is tiny (v1.27.1) (#131)+99adb65f feat: ingestion & import robustness (v1.27.0) (#132)+fb474acc test(hermes): verify OSB surface against core normalize/validate-before-wrap and in_place compaction (1.26.1) (#129)++Conventions:+- The kernel is deterministic. It issues no model calls. Anything that must classify, rank, or gate does so from structural signals or numeric scores.+- Search, classification, ranking and extraction must be language-agnostic. Hardcoded natural-language word lists (stop-words, greetings, keywords, negations) are forbidden in EVERY language.+- Every new flag, argument or configuration key must leave behaviour byte-identical when absent.+- A forward pointer printed to the operator resolves a REGISTERED diagnostic code through the advisory rail (src/cli/advisory-rail.ts, src/core/brain/next-step.ts). Caller-supplied prose is rejected by a build ratchet.+- Findings carry their data as structured fields, not embedded in prose messages.+- The vault is plain Markdown replicated peer-to-peer by Syncthing. There is NO git transport for the vault, and nothing may place a .git directory inside the replicated tree.+- Continuity telemetry is emitted through emitGatedTelemetry (src/core/brain/continuity/emit.ts): gated by a configuration key, fail-open, redaction-passing.++Constraints:+- No fallback that silently does nothing. An error must surface explicitly as an error.+- No stubs, no placeholders, no dead code paths.+- SOLID, KISS, DRY. Anything extractable belongs in a named constant or local.+- Do not add an external service dependency, and do not introduce a new runtime dependency without saying so explicitly as a trade-off.+- Do not change existing public command-line or Model Context Protocol surfaces incompatibly.++# Required output format++Produce exactly 3 distinct architectural variants. For each variant:++### Variant N: <short name>+- **Approach**: 2-3 sentences describing the variant.+- **Trade-offs**: bullet list of pros and cons.+- **Complexity**: small | medium | large+- **Risk**: low | medium | high++After the three variants, add exactly one recommendation:++### Recommended: Variant N+**Rationale**: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.++Output nothing outside of these sections.diff --git a/docs/brainstorm/signals-that-survive/cli-output/prompt-llm-response-shape.md b/docs/brainstorm/signals-that-survive/cli-output/prompt-llm-response-shape.mdnew file mode 100644index 00000000..8346a650--- /dev/null+++ b/docs/brainstorm/signals-that-survive/cli-output/prompt-llm-response-shape.md@@ -0,0 +1,94 @@+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++## [upstream:honcho] Schema-constrained structured outputs for OSB's own LLM calls (fact-extract, distill, dream)++**Source**: https://github.com/plastic-labs/honcho/pull/896+**Repo**: plastic-labs/honcho (4753β )+**PR**: #896 feat(dialectic): optional structured outputs with limited schema for Dialectic calls (2026-07-20)++## What+Add an optional, deliberately narrow response-schema layer for the LLM calls OSB issues itself β fact extraction, source distillation, and dream/synthesis β so the model returns validated typed objects instead of free-form text that OSB parses loosely.++## Why useful for OSB+These calls write directly into the vault, so a malformed or drifting response becomes corrupted knowledge rather than a visible error. Schema-constrained generation turns silent parse degradation into a hard, catchable validation failure and removes ad-hoc parsing from the brain write path.++## Status in OSB+- **Verdict**: not_in_osb_useful+- **Codegraph hints**: no LLM response-schema mechanism β "zod" and "responseSchema" return no results; "dialectic" returns no results. `structuredKeywordQuery` (src/core/search/structured-lanes.ts:10) is search-query structuring, not typed generation. Existing "schema" symbols are brain knowledge-vocabulary only: `interface SchemaNode` (src/core/brain/schema-contracts.ts:3), `SchemaPack` (src/core/brain/schema-pack.ts:15), `SchemaStats` (src/core/brain/schema-admin.ts:26). Consumer site: src/core/brain/fact-extract.ts.++## Notes+Keep the schema "limited" as upstream does β over-constraining extraction prompts degrades recall. Naming caution: OSB already uses "schema" for the knowledge vocabulary (src/core/brain/schema-contracts.ts), so this layer needs a distinct term to avoid collision. Routing stays with Hermes; this is response shaping at OSB's call sites only.++--- validator comment [osb-triage-validator]:+osb-triage-validator @ 2026-07-25T22:53:39Z:+- sanity: clean+- cluster: no cluster+- priority: set to 2: not_in_osb_useful but schema-constrained structured outputs for OSB's own LLM calls is an architectural response-shaping layer; needs design (naming collision, over-constraint risk)++--- validator comment [claude-dev-agent]:+claude-dev-agent @ 2026-07-27: triage validation pass (operator-directed: link + priority actualization; internal work ranks above external-product integration)+- link ADDED: this task is now the parent of t_1dace26d (auto-memory capture via semantic extraction from the conversation stream).+- reason, and it is a real ordering constraint rather than a grouping: t_1dace26d introduces an LLM extraction pass whose output writes into the vault. This task is the layer that turns a malformed or drifting model response into a hard, catchable validation failure instead of corrupted knowledge. Building the extraction pass first would add a SECOND loosely-parsed write path that this layer then has to retrofit - the opposite of the order that removes the risk.+- priority kept at 2 on both. The naming caution in the Notes stands: OSB already uses "schema" for the knowledge vocabulary (src/core/brain/schema-contracts.ts, schema-pack.ts, schema-admin.ts), so this layer needs a distinct term.++# Project context++Project: Open Second Brain - a TypeScript/Bun command-line tool plus Model Context Protocol server over an Obsidian-compatible Markdown vault.+Runtime: Bun. Tests: `bun test` via `bash scripts/test` (910 *.test.ts files). Typecheck: `tsc --noEmit`. Lint: oxlint. Format: oxfmt.++Recent commits (newest first):+0963ef0a feat: no dead ends - every diagnosis names its exit (v1.40.0) (#151)+f91a698b feat: context integrity gates (v1.39.0) (#150)+c31a2574 feat: semantic-health baseline watermark (v1.38.0) (#148)+b0c37977 feat: retrieval quality and context delivery (v1.37.0) (#146)+842d690f feat: knowledge intake and consolidation (v1.36.0) (#145)+95dc8577 feat: trusted recall and memory write surface (v1.35.0) (#144)+426d06f8 fix(vault): parse block-style YAML lists in frontmatter (not just inline arrays) (#142)+4b8100ca feat: source pipeline integrity and operator tooling (v1.34.0) (#143)+77513f2b feat: belief lifecycle and decision memory (v1.33.0) (#141)+61e93d24 fix(config): derive vault store reference from a keyed installation secret (#140)+9a649dd6 feat: memory write-path integrity and store safety wave (v1.32.0) (#139)+f2a037eb feat: today operator surface - dashboard, open loops, marker write-back (v1.31.0) (#138)+13bde6c3 refactor: remove all import cycles, decompose search.ts (v1.30.1) (#137)+fd5661f9 feat: governance visibility - vitals scorecard + batch-inflation lint (v1.30.0) (#136)+a99b0e71 feat(brain): add o2b brain vitals scorecard + batch-concept-inflation lint (#135)+70fb36e1 feat: operability, safety & first-run experience (v1.29.0) (#134)+ac26a675 feat: retrieval & ranking quality (v1.28.0) (#133)+5cd52e70 fix(hermes): resolve o2b when memory provider PATH is tiny (v1.27.1) (#131)+99adb65f feat: ingestion & import robustness (v1.27.0) (#132)+fb474acc test(hermes): verify OSB surface against core normalize/validate-before-wrap and in_place compaction (1.26.1) (#129)++Conventions:+- The kernel is deterministic. It issues no model calls. Anything that must classify, rank, or gate does so from structural signals or numeric scores.+- Search, classification, ranking and extraction must be language-agnostic. Hardcoded natural-language word lists (stop-words, greetings, keywords, negations) are forbidden in EVERY language.+- Every new flag, argument or configuration key must leave behaviour byte-identical when absent.+- A forward pointer printed to the operator resolves a REGISTERED diagnostic code through the advisory rail (src/cli/advisory-rail.ts, src/core/brain/next-step.ts). Caller-supplied prose is rejected by a build ratchet.+- Findings carry their data as structured fields, not embedded in prose messages.+- The vault is plain Markdown replicated peer-to-peer by Syncthing. There is NO git transport for the vault, and nothing may place a .git directory inside the replicated tree.+- Continuity telemetry is emitted through emitGatedTelemetry (src/core/brain/continuity/emit.ts): gated by a configuration key, fail-open, redaction-passing.++Constraints:+- No fallback that silently does nothing. An error must surface explicitly as an error.+- No stubs, no placeholders, no dead code paths.+- SOLID, KISS, DRY. Anything extractable belongs in a named constant or local.+- Do not add an external service dependency, and do not introduce a new runtime dependency without saying so explicitly as a trade-off.+- Do not change existing public command-line or Model Context Protocol surfaces incompatibly.++# Required output format++Produce exactly 3 distinct architectural variants. For each variant:++### Variant N: <short name>+- **Approach**: 2-3 sentences describing the variant.+- **Trade-offs**: bullet list of pros and cons.+- **Complexity**: small | medium | large+- **Risk**: low | medium | high++After the three variants, add exactly one recommendation:++### Recommended: Variant N+**Rationale**: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.++Output nothing outside of these sections.diff --git a/docs/brainstorm/signals-that-survive/cli-output/prompt-marker-kinds-fact-skill.md b/docs/brainstorm/signals-that-survive/cli-output/prompt-marker-kinds-fact-skill.mdnew file mode 100644index 00000000..ffe30edc--- /dev/null+++ b/docs/brainstorm/signals-that-survive/cli-output/prompt-marker-kinds-fact-skill.md@@ -0,0 +1,112 @@+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++## [article] Offline DREAM marker parsing for provider-free proposal seeding++**Source**: [[Articles/Introducing Hermes Dreaming- Reviewable Self-Improvement for Hermes Agent]]+**Article excerpt**: "The offline marker workflow looks for explicit DREAM: lines in the source bundle. ... DREAM: fact: {"type": "preference", "key": "tone", "value": "casual"}"++## What+An offline source-marker convention (explicit lines tagging memory/user/fact/skill proposals in plain text) so the self-improvement loop can be exercised deterministically without any model call.++## Why useful for OSB+A marker grammar lets operators or other agents seed proposals into the dream pipeline from plain text in a fully testable, provider-independent way β useful for fixtures, demos, and cross-tool authoring without going through a tool call.++## Status in OSB+- **Verdict**: present_weaker (was `unverified`; resolved against source 2026-07-27)+- **Codegraph hints** (re-verified 2026-07-27; the earlier hint "dream input is logged signals, not inline markers" was MISLEADING β the markers are what produce those signals):+ - A full inline + block marker grammar already ships: `src/core/brain/inline.ts` β `parseInlineMarker` (:201), `parseBlockMarker` (:401), `discoverMarkersDetailed` (:557), `discoverMarkers` (:616), fence-aware and consumed-sentinel-skipping so re-runs are idempotent.+ - Three marker kinds exist (`MarkerKind = "feedback" | "loop" | "set"`, inline.ts:51) with per-kind required fields (inline.ts:46-49): `feedback` requires topic + principle, `set` requires note + field + value. `loop` is validated structurally by the close-form decision table.+ - Consumers are wired: `src/core/brain/session-lifecycle.ts:530`, `src/core/brain/inline-scan.ts:33`, `src/core/brain/open-loops.ts:177`, `src/core/brain/inline-rewrite.ts`.+ - Net: provider-free, plain-text seeding of preference signals into `Brain/inbox/` ALREADY works and is already deterministic and testable.++## Notes+- Do NOT build a second marker grammar. The remaining delta is narrow and must land as kinds on the existing one:+ 1. The article's convention also tags **fact** and **skill** proposals; OSB's grammar has no kind for either.+ 2. OSB's markers are discovered on the session-import / inline-scan path. The article's workflow reads an arbitrary "source bundle", so the open question is whether a marker scan should be invocable over an operator-supplied file outside a session.+- Verify (2) before sizing: if the answer is "no", this task collapses to adding two kinds to `REQUIRED_FIELDS` plus their routing, which is small.+- The parent (t_ae8a8ec0, staged dream pipeline with a persisted proposal bundle) is now **done**, so the original reason this task sat at priority 1 β "value depends on the parent pipeline existing first" β has expired.++--- validator comment [osb-triage-validator]:+osb-triage-validator @ 2026-06-04T13:31:04Z:+- sanity: clean+- cluster: child of t_ae8a8ec0+- priority: set to 1: verdict unverified; value depends on t_ae8a8ec0 pipeline existing first++--- validator comment [osb-triage-validator]:+osb-triage-validator @ 2026-06-05T12:37Z:+- re-validated: priority=1 correct (verdict unverified; value depends on parent t_ae8a8ec0 pipeline existing first); parent t_ae8a8ec0 already linked; no changes needed++--- validator comment [osb-triage-validator]:+osb-triage-validator @ 2026-06-17T14:04:06Z:+- sanity: inserted missing Notes section with TODO placeholder+- cluster: child of t_ae8a8ec0 (existing link, no new link)+- priority: kept at 1 (validator-set, no priority mutation this run)++--- validator comment [claude-dev-agent]:+claude-dev-agent @ 2026-07-27: triage validation pass (operator-directed: link + priority actualization; internal work ranks above external-product integration)+- priority: 1 -> 2. The stated reason for 1 has expired: the parent t_ae8a8ec0 (staged dream pipeline with a persisted proposal bundle) is DONE.+- verdict resolved unverified -> present_weaker, and the old hint corrected. "dream input is logged signals, not inline markers" was misleading - the markers are what PRODUCE those signals. A full grammar already ships at src/core/brain/inline.ts: parseInlineMarker:201, parseBlockMarker:401, discoverMarkersDetailed:557, discoverMarkers:616, fence-aware and consumed-sentinel-skipping so re-runs are idempotent. Three kinds exist (MarkerKind:51 - feedback | loop | set) with per-kind required fields (:46-49). Consumers wired at session-lifecycle.ts:530, inline-scan.ts:33, open-loops.ts:177, inline-rewrite.ts.+- so provider-free plain-text seeding of preference signals ALREADY works. Do not build a second grammar.+- the remaining delta, now recorded in the body: the article convention also tags fact and skill proposals (no kind for either), and OSB discovers markers on the session-import path rather than over an arbitrary operator-supplied source bundle. If the latter is out of scope this collapses to adding two kinds plus routing - small.++# Project context++Project: Open Second Brain - a TypeScript/Bun command-line tool plus Model Context Protocol server over an Obsidian-compatible Markdown vault.+Runtime: Bun. Tests: `bun test` via `bash scripts/test` (910 *.test.ts files). Typecheck: `tsc --noEmit`. Lint: oxlint. Format: oxfmt.++Recent commits (newest first):+0963ef0a feat: no dead ends - every diagnosis names its exit (v1.40.0) (#151)+f91a698b feat: context integrity gates (v1.39.0) (#150)+c31a2574 feat: semantic-health baseline watermark (v1.38.0) (#148)+b0c37977 feat: retrieval quality and context delivery (v1.37.0) (#146)+842d690f feat: knowledge intake and consolidation (v1.36.0) (#145)+95dc8577 feat: trusted recall and memory write surface (v1.35.0) (#144)+426d06f8 fix(vault): parse block-style YAML lists in frontmatter (not just inline arrays) (#142)+4b8100ca feat: source pipeline integrity and operator tooling (v1.34.0) (#143)+77513f2b feat: belief lifecycle and decision memory (v1.33.0) (#141)+61e93d24 fix(config): derive vault store reference from a keyed installation secret (#140)+9a649dd6 feat: memory write-path integrity and store safety wave (v1.32.0) (#139)+f2a037eb feat: today operator surface - dashboard, open loops, marker write-back (v1.31.0) (#138)+13bde6c3 refactor: remove all import cycles, decompose search.ts (v1.30.1) (#137)+fd5661f9 feat: governance visibility - vitals scorecard + batch-inflation lint (v1.30.0) (#136)+a99b0e71 feat(brain): add o2b brain vitals scorecard + batch-concept-inflation lint (#135)+70fb36e1 feat: operability, safety & first-run experience (v1.29.0) (#134)+ac26a675 feat: retrieval & ranking quality (v1.28.0) (#133)+5cd52e70 fix(hermes): resolve o2b when memory provider PATH is tiny (v1.27.1) (#131)+99adb65f feat: ingestion & import robustness (v1.27.0) (#132)+fb474acc test(hermes): verify OSB surface against core normalize/validate-before-wrap and in_place compaction (1.26.1) (#129)++Conventions:+- The kernel is deterministic. It issues no model calls. Anything that must classify, rank, or gate does so from structural signals or numeric scores.+- Search, classification, ranking and extraction must be language-agnostic. Hardcoded natural-language word lists (stop-words, greetings, keywords, negations) are forbidden in EVERY language.+- Every new flag, argument or configuration key must leave behaviour byte-identical when absent.+- A forward pointer printed to the operator resolves a REGISTERED diagnostic code through the advisory rail (src/cli/advisory-rail.ts, src/core/brain/next-step.ts). Caller-supplied prose is rejected by a build ratchet.+- Findings carry their data as structured fields, not embedded in prose messages.+- The vault is plain Markdown replicated peer-to-peer by Syncthing. There is NO git transport for the vault, and nothing may place a .git directory inside the replicated tree.+- Continuity telemetry is emitted through emitGatedTelemetry (src/core/brain/continuity/emit.ts): gated by a configuration key, fail-open, redaction-passing.++Constraints:+- No fallback that silently does nothing. An error must surface explicitly as an error.+- No stubs, no placeholders, no dead code paths.+- SOLID, KISS, DRY. Anything extractable belongs in a named constant or local.+- Do not add an external service dependency, and do not introduce a new runtime dependency without saying so explicitly as a trade-off.+- Do not change existing public command-line or Model Context Protocol surfaces incompatibly.++# Required output format++Produce exactly 3 distinct architectural variants. For each variant:++### Variant N: <short name>+- **Approach**: 2-3 sentences describing the variant.+- **Trade-offs**: bullet list of pros and cons.+- **Complexity**: small | medium | large+- **Risk**: low | medium | high++After the three variants, add exactly one recommendation:++### Recommended: Variant N+**Rationale**: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.++Output nothing outside of these sections.diff --git a/docs/brainstorm/signals-that-survive/cli-output/prompt-query-temporal-intent.md b/docs/brainstorm/signals-that-survive/cli-output/prompt-query-temporal-intent.mdnew file mode 100644index 00000000..c4afb378--- /dev/null+++ b/docs/brainstorm/signals-that-survive/cli-output/prompt-query-temporal-intent.md@@ -0,0 +1,94 @@+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++## [upstream:signetai] Query-side temporal-intent detection for hybrid recall re-ranking++**Source**: https://github.com/Signet-AI/signetai/releases+**Repo**: Signet-AI/signetai (183β )+**Released**: v0.148.2 (2026-07-22T21:17:14Z)++## What+Signet's recall engine now adds a temporal-intent signal to hybrid recall scoring: it detects time intent in the query itself (e.g. "last week", "recently", "before X") and biases ranking toward memories matching that window. This is distinct from a static freshness prior, which boosts recent items regardless of what the query asks.++## Why useful for OSB+OSB's Weibull recency boost is query-independent: it always favors recent notes, even when the query explicitly targets an older period ("what did I decide back in spring?"), where it actively hurts ranking. A query-side temporal-intent detector would modulate (amplify, suppress, or window-shift) the existing recency layer per query β a genuinely uncovered dimension, and cheap to prototype since OSB already has a temporal-expression extractor on the write path that could be reused for query parsing.++## Status in OSB+- **Verdict**: present_weaker+- **Codegraph hints**: Freshness-prior half is present: src/core/search/recency.ts:4-8 (configurable Weibull recency boost; recencyShape/recencyScale/recencyAmplitude at src/core/search/types.ts:905-908), fused in src/core/search/ranker.ts:1-5 and orchestrated in src/core/search/search.ts:1-4. Query-side temporal-intent half not found β extractTemporalConstraints (src/core/brain/temporal-extract.ts) runs only on the WRITE path (bi-temporal validity in dream.ts:1415-1419, dream-plan.ts:134-137); no query-time temporal parsing feeds the ranker or fusion (src/core/search/fusion.ts:1-3).++## Notes+Conservative scope: this is an enhancement, not a gap-critical fix β plain recency boost covers the common "recent stuff" case. Suggested minimal shape: parse query for temporal expressions (reusing temporal-extract), map to a target time window, and adjust recency parameters or apply a window-match multiplier in the ranker; amplitude-0 style opt-out should be preserved. Do not import Signet's implementation β only the idea; scoring internals differ (OSB uses min-max-normalized BM25+semantic fusion with link/tier boosts).++--- validator comment [osb-triage-validator]:+osb-triage-validator @ 2026-07-25T22:53:39Z:+- sanity: clean+- cluster: no cluster+- priority: set to 2: present_weaker but query-side temporal-intent is an enhancement to the recency/fusion layer; needs design on per-query Weibull modulation++--- validator comment [claude-dev-agent]:+claude-dev-agent @ 2026-07-27: triage validation pass (operator-directed: link + priority actualization; internal work ranks above external-product integration)+- priority: 2 -> 3.+- verified this run: the premise holds exactly. extractTemporalConstraints (src/core/brain/temporal-extract.ts:45) is imported by src/core/brain/dream.ts only (:52, :1501) - write path, never the query path. src/core/search/recency.ts, ranker.ts and fusion.ts exist as described.+- rank rationale: purely internal search-quality work, no external product anywhere in scope, and the extractor it needs is already written and tested. The remaining design question (how a query-side signal modulates the Weibull layer) is bounded, not architectural.++# Project context++Project: Open Second Brain - a TypeScript/Bun command-line tool plus Model Context Protocol server over an Obsidian-compatible Markdown vault.+Runtime: Bun. Tests: `bun test` via `bash scripts/test` (910 *.test.ts files). Typecheck: `tsc --noEmit`. Lint: oxlint. Format: oxfmt.++Recent commits (newest first):+0963ef0a feat: no dead ends - every diagnosis names its exit (v1.40.0) (#151)+f91a698b feat: context integrity gates (v1.39.0) (#150)+c31a2574 feat: semantic-health baseline watermark (v1.38.0) (#148)+b0c37977 feat: retrieval quality and context delivery (v1.37.0) (#146)+842d690f feat: knowledge intake and consolidation (v1.36.0) (#145)+95dc8577 feat: trusted recall and memory write surface (v1.35.0) (#144)+426d06f8 fix(vault): parse block-style YAML lists in frontmatter (not just inline arrays) (#142)+4b8100ca feat: source pipeline integrity and operator tooling (v1.34.0) (#143)+77513f2b feat: belief lifecycle and decision memory (v1.33.0) (#141)+61e93d24 fix(config): derive vault store reference from a keyed installation secret (#140)+9a649dd6 feat: memory write-path integrity and store safety wave (v1.32.0) (#139)+f2a037eb feat: today operator surface - dashboard, open loops, marker write-back (v1.31.0) (#138)+13bde6c3 refactor: remove all import cycles, decompose search.ts (v1.30.1) (#137)+fd5661f9 feat: governance visibility - vitals scorecard + batch-inflation lint (v1.30.0) (#136)+a99b0e71 feat(brain): add o2b brain vitals scorecard + batch-concept-inflation lint (#135)+70fb36e1 feat: operability, safety & first-run experience (v1.29.0) (#134)+ac26a675 feat: retrieval & ranking quality (v1.28.0) (#133)+5cd52e70 fix(hermes): resolve o2b when memory provider PATH is tiny (v1.27.1) (#131)+99adb65f feat: ingestion & import robustness (v1.27.0) (#132)+fb474acc test(hermes): verify OSB surface against core normalize/validate-before-wrap and in_place compaction (1.26.1) (#129)++Conventions:+- The kernel is deterministic. It issues no model calls. Anything that must classify, rank, or gate does so from structural signals or numeric scores.+- Search, classification, ranking and extraction must be language-agnostic. Hardcoded natural-language word lists (stop-words, greetings, keywords, negations) are forbidden in EVERY language.+- Every new flag, argument or configuration key must leave behaviour byte-identical when absent.+- A forward pointer printed to the operator resolves a REGISTERED diagnostic code through the advisory rail (src/cli/advisory-rail.ts, src/core/brain/next-step.ts). Caller-supplied prose is rejected by a build ratchet.+- Findings carry their data as structured fields, not embedded in prose messages.+- The vault is plain Markdown replicated peer-to-peer by Syncthing. There is NO git transport for the vault, and nothing may place a .git directory inside the replicated tree.+- Continuity telemetry is emitted through emitGatedTelemetry (src/core/brain/continuity/emit.ts): gated by a configuration key, fail-open, redaction-passing.++Constraints:+- No fallback that silently does nothing. An error must surface explicitly as an error.+- No stubs, no placeholders, no dead code paths.+- SOLID, KISS, DRY. Anything extractable belongs in a named constant or local.+- Do not add an external service dependency, and do not introduce a new runtime dependency without saying so explicitly as a trade-off.+- Do not change existing public command-line or Model Context Protocol surfaces incompatibly.++# Required output format++Produce exactly 3 distinct architectural variants. For each variant:++### Variant N: <short name>+- **Approach**: 2-3 sentences describing the variant.+- **Trade-offs**: bullet list of pros and cons.+- **Complexity**: small | medium | large+- **Risk**: low | medium | high++After the three variants, add exactly one recommendation:++### Recommended: Variant N+**Rationale**: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.++Output nothing outside of these sections.diff --git a/docs/brainstorm/signals-that-survive/cli-output/prompt-recurring-weak-recall-obligation.md b/docs/brainstorm/signals-that-survive/cli-output/prompt-recurring-weak-recall-obligation.mdnew file mode 100644index 00000000..afcc838c--- /dev/null+++ b/docs/brainstorm/signals-that-survive/cli-output/prompt-recurring-weak-recall-obligation.md@@ -0,0 +1,100 @@+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++## [upstream:yantrikdb-hermes-plugin] Auto-generate bounded follow-up tasks from recurring low-confidence recalls and surface a session-opening agenda by default++**Source**: https://github.com/yantrikos/yantrikdb-hermes-plugin/releases/tag/v0.10.0+**Repo**: yantrikos/yantrikdb-hermes-plugin (27β )+**Released**: v0.10.0 (2026-07-25T17:23:38Z)++## What+Memory watches for recurring low-confidence answers and, when the same weak recall recurs enough to clear a demand threshold, mints a bounded follow-up work item; a per-session agenda is surfaced at the start of the next session. Both behaviors default on, with caps and demand-aggregation so a single poor recall never spawns an item.++## Why useful for OSB+OSB already classifies a weak recall and already names the action to take, but the verdict is per-attempt and evaporates. Nothing aggregates "this same question has come back insufficient four times" into durable, bounded remediation work. Closing that loop turns a repeated retrieval failure into a tracked obligation instead of a silently repeated disappointment.++## Status in OSB+- **Verdict**: present_weaker (was `unverified`; resolved against source 2026-07-27)+- **Codegraph hints** (re-verified 2026-07-27):+ - The low-confidence DETECTOR already exists: `src/core/brain/recall-adequacy.ts` classifies a recall attempt as `sufficient -> proceed`, `weak -> re_recall`, `insufficient -> abstain`, reading only numeric top-k scores (deterministic and language-agnostic). This is the signal to aggregate β do not build a new one.+ - Adjacent surfaces present: `src/core/brain/recall-telemetry.ts`, `src/core/brain/gaps/`, `src/core/brain/anticipatory-cache.ts`, `src/core/brain/recall-budget.ts`, `src/core/brain/session-recall.ts`.+ - The natural durable target already exists: `src/core/brain/obligations.ts` β `addObligation` (:246), `completeObligation` (:279), `showObligation` (:304), `obligationExists` (:313), with cadence parsing (:105) and `nextDueDate` (:173).+ - What is MISSING: recurrence aggregation across recall attempts (nothing keys repeated weak verdicts to a stable question identity), and any automatic minting path from a verdict to a durable item.+- **CORRECTION to the original notes**: `brain_agenda` does NOT cover the "session-opening agenda" half. `src/core/brain/agenda.ts` is a CALENDAR agenda β its vocabulary is `AgendaEventInput`, `AgendaConflict`, `FocusBlock`, `ExternalOrganizer`. It is unrelated to recall gaps and must not be extended for this.++## Notes+- Scope this as INTERNAL. Mint an **obligation** in the vault, not a task on an external tracker β OSB owns obligations; it does not own a board, and writing to one would make this an external-product integration for no gain.+- The hard part is the recurrence key: what makes two weak recalls "the same question" must be deterministic and must not use natural-language word lists in any language. Decide this before implementation.+- Caps and demand aggregation are load-bearing, not polish: without them one bad afternoon fills the vault with obligations.+- v1.40.0 precedent: a detector that finds a population should name the exit through a REGISTERED diagnostic code (`src/core/brain/next-step.ts`, `src/cli/advisory-rail.ts`), never caller-supplied prose.+- "Defaults on" needs an explicit decision. OSB's convention is that a new flag or config key is byte-identical when absent; a behavior that mints vault content by default has to be justified against that.++--- validator comment [claude-dev-agent]:+claude-dev-agent @ 2026-07-27: triage validation pass (operator-directed: link + priority actualization; internal work ranks above external-product integration)+- priority: 0 -> 3. Was untriaged (created 2026-07-25, no validator pass).+- verdict resolved unverified -> present_weaker against source, and two premises corrected in the body:+ 1. The detector already exists. src/core/brain/recall-adequacy.ts classifies a recall attempt sufficient/weak/insufficient and names the action, deterministically from numeric scores. Do not build a second one.+ 2. brain_agenda does NOT cover the session-opening-agenda half. src/core/brain/agenda.ts is a CALENDAR agenda (AgendaEventInput, AgendaConflict, FocusBlock, ExternalOrganizer) and must not be extended for recall gaps.+- re-scoped to stay internal: mint an OBLIGATION (src/core/brain/obligations.ts addObligation:246, completeObligation:279, cadence:105, nextDueDate:173), not a task on an external tracker. OSB owns obligations; it does not own a board, and writing to one would turn an internal feature into an external-product integration for no gain.+- genuinely missing, and the only hard part: recurrence aggregation - nothing keys repeated weak verdicts to a stable question identity. That key must be deterministic and must not use natural-language word lists in any language.++# Project context++Project: Open Second Brain - a TypeScript/Bun command-line tool plus Model Context Protocol server over an Obsidian-compatible Markdown vault.+Runtime: Bun. Tests: `bun test` via `bash scripts/test` (910 *.test.ts files). Typecheck: `tsc --noEmit`. Lint: oxlint. Format: oxfmt.++Recent commits (newest first):+0963ef0a feat: no dead ends - every diagnosis names its exit (v1.40.0) (#151)+f91a698b feat: context integrity gates (v1.39.0) (#150)+c31a2574 feat: semantic-health baseline watermark (v1.38.0) (#148)+b0c37977 feat: retrieval quality and context delivery (v1.37.0) (#146)+842d690f feat: knowledge intake and consolidation (v1.36.0) (#145)+95dc8577 feat: trusted recall and memory write surface (v1.35.0) (#144)+426d06f8 fix(vault): parse block-style YAML lists in frontmatter (not just inline arrays) (#142)+4b8100ca feat: source pipeline integrity and operator tooling (v1.34.0) (#143)+77513f2b feat: belief lifecycle and decision memory (v1.33.0) (#141)+61e93d24 fix(config): derive vault store reference from a keyed installation secret (#140)+9a649dd6 feat: memory write-path integrity and store safety wave (v1.32.0) (#139)+f2a037eb feat: today operator surface - dashboard, open loops, marker write-back (v1.31.0) (#138)+13bde6c3 refactor: remove all import cycles, decompose search.ts (v1.30.1) (#137)+fd5661f9 feat: governance visibility - vitals scorecard + batch-inflation lint (v1.30.0) (#136)+a99b0e71 feat(brain): add o2b brain vitals scorecard + batch-concept-inflation lint (#135)+70fb36e1 feat: operability, safety & first-run experience (v1.29.0) (#134)+ac26a675 feat: retrieval & ranking quality (v1.28.0) (#133)+5cd52e70 fix(hermes): resolve o2b when memory provider PATH is tiny (v1.27.1) (#131)+99adb65f feat: ingestion & import robustness (v1.27.0) (#132)+fb474acc test(hermes): verify OSB surface against core normalize/validate-before-wrap and in_place compaction (1.26.1) (#129)++Conventions:+- The kernel is deterministic. It issues no model calls. Anything that must classify, rank, or gate does so from structural signals or numeric scores.+- Search, classification, ranking and extraction must be language-agnostic. Hardcoded natural-language word lists (stop-words, greetings, keywords, negations) are forbidden in EVERY language.+- Every new flag, argument or configuration key must leave behaviour byte-identical when absent.+- A forward pointer printed to the operator resolves a REGISTERED diagnostic code through the advisory rail (src/cli/advisory-rail.ts, src/core/brain/next-step.ts). Caller-supplied prose is rejected by a build ratchet.+- Findings carry their data as structured fields, not embedded in prose messages.+- The vault is plain Markdown replicated peer-to-peer by Syncthing. There is NO git transport for the vault, and nothing may place a .git directory inside the replicated tree.+- Continuity telemetry is emitted through emitGatedTelemetry (src/core/brain/continuity/emit.ts): gated by a configuration key, fail-open, redaction-passing.++Constraints:+- No fallback that silently does nothing. An error must surface explicitly as an error.+- No stubs, no placeholders, no dead code paths.+- SOLID, KISS, DRY. Anything extractable belongs in a named constant or local.+- Do not add an external service dependency, and do not introduce a new runtime dependency without saying so explicitly as a trade-off.+- Do not change existing public command-line or Model Context Protocol surfaces incompatibly.++# Required output format++Produce exactly 3 distinct architectural variants. For each variant:++### Variant N: <short name>+- **Approach**: 2-3 sentences describing the variant.+- **Trade-offs**: bullet list of pros and cons.+- **Complexity**: small | medium | large+- **Risk**: low | medium | high++After the three variants, add exactly one recommendation:++### Recommended: Variant N+**Rationale**: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.++Output nothing outside of these sections.diff --git a/docs/brainstorm/signals-that-survive/cli-output/prompt-route-discriminator.md b/docs/brainstorm/signals-that-survive/cli-output/prompt-route-discriminator.mdnew file mode 100644index 00000000..29a434bc--- /dev/null+++ b/docs/brainstorm/signals-that-survive/cli-output/prompt-route-discriminator.md@@ -0,0 +1,101 @@+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++## [upstream:obsidian-mind] Secondary discriminator stage on Brain routing signals++**Source**: https://github.com/breferrari/obsidian-mind/releases/tag/v7.0.0+**Repo**: breferrari/obsidian-mind (3073β )+**Released**: v7.0.0 (2026-07-19)++## What+A two-stage classifier for routing captured notes/signals: a primary hint picks a candidate route, then a secondary discriminator ("sub-hint") disambiguates among the routes the primary hint scores near-equally, instead of a single-shot winner-take-all decision.++## Why useful for OSB+OSB routes writes deterministically (signal -> Brain/inbox/sig-*, preference, note, pinned) and the same ambiguity exists: a taste signal that is also an obligation, a note that is really a decision. A deterministic tie-break layer keeps routing model-free while cutting the misfiled-write rate that dream later has to reconcile. Recording which discriminator fired also makes tie-break rules auditable and tunable rather than opaque.++## Status in OSB+- **Verdict**: present_weaker+- **Codegraph hints** (re-verified 2026-07-27):+ - The write router is `routeExtractedFacts` (src/core/brain/fact-extract.ts:307), with an operator durability denylist (fact-extract.ts:202) and a write-approval toggle (fact-extract.ts:209). Classification is single-stage; there is no tie-break layer and no record of near-equal candidates.+ - No grep match for "sub-hint" or "secondary discriminator".+ - Nearest prior art is brain_intake_entities / brain_labels, which classify CONTENT, not route.+- **CORRECTION to the original hints**: `brain_route_metrics` is NOT a write-routing histogram. It is route-level LATENCY telemetry for MCP tool calls (src/core/brain/mcp-route-metrics.ts; one `mcp_route_latency` continuity record per `tools/call`, gated on config key `mcp_route_metrics_enabled`, surfaced via src/mcp/brain/recall-tools.ts:319). It has nothing to do with where a captured write lands. Any claim that this task "gives brain_route_metrics something to report" is false and must not drive the design. `brain_recall_gate` and `brain_intent_review` are likewise different layers (retrieval gating and intent review), not write routing.++## Notes+- Must stay deterministic (rule/score table, not an LLM call) to preserve OSB's model-free guarantee, and language-agnostic β no natural-language word lists in the discriminator, on any language.+- The tie-break outcome needs its own emission surface. `emitGatedTelemetry` (src/core/brain/continuity/emit.ts) is the existing gated, fail-open, redaction-passing seam that `mcp-route-metrics.ts` already uses; model a new gated record on it rather than extending the latency record with an unrelated field.+- v1.40.0 precedent to follow: a diagnosis names its exit through a REGISTERED code, not caller-supplied prose (src/cli/advisory-rail.ts, src/core/brain/next-step.ts). If an ambiguous route surfaces anything to the operator, it should go through that rail with a registered code, not a bespoke sentence.++--- validator comment [osb-triage-validator]:+osb-triage-validator @ 2026-07-25T22:53:39Z:+- sanity: clean+- cluster: no cluster+- priority: set to 2: not_in_osb_useful, secondary discriminator stage on routing is an architectural routing-model change; needs design on the tie-break score table and metrics emission++--- validator comment [claude-dev-agent]:+claude-dev-agent @ 2026-07-27: triage validation pass (operator-directed: link + priority actualization; internal work ranks above external-product integration)+- priority: 2 -> 3.+- body CORRECTED (see the Status section): the original claimed this task "gives brain_route_metrics something to report beyond a flat route histogram". That is false. brain_route_metrics is route-level LATENCY telemetry for MCP tool calls (src/core/brain/mcp-route-metrics.ts, one mcp_route_latency continuity record per tools/call, gated on mcp_route_metrics_enabled, surfaced at src/mcp/brain/recall-tools.ts:319). It has nothing to do with where a captured write lands. Left uncorrected it would have sent an implementer to extend a latency record with an unrelated field.+- the real anchor is now recorded: the write router is routeExtractedFacts (src/core/brain/fact-extract.ts:307), single-stage, with a durability denylist (:202) and a write-approval toggle (:209).+- rank rationale: internal, deterministic by requirement, and it reduces misfiled writes that dream later has to reconcile. Verdict corrected not_in_osb_useful -> present_weaker.++# Project context++Project: Open Second Brain - a TypeScript/Bun command-line tool plus Model Context Protocol server over an Obsidian-compatible Markdown vault.+Runtime: Bun. Tests: `bun test` via `bash scripts/test` (910 *.test.ts files). Typecheck: `tsc --noEmit`. Lint: oxlint. Format: oxfmt.++Recent commits (newest first):+0963ef0a feat: no dead ends - every diagnosis names its exit (v1.40.0) (#151)+f91a698b feat: context integrity gates (v1.39.0) (#150)+c31a2574 feat: semantic-health baseline watermark (v1.38.0) (#148)+b0c37977 feat: retrieval quality and context delivery (v1.37.0) (#146)+842d690f feat: knowledge intake and consolidation (v1.36.0) (#145)+95dc8577 feat: trusted recall and memory write surface (v1.35.0) (#144)+426d06f8 fix(vault): parse block-style YAML lists in frontmatter (not just inline arrays) (#142)+4b8100ca feat: source pipeline integrity and operator tooling (v1.34.0) (#143)+77513f2b feat: belief lifecycle and decision memory (v1.33.0) (#141)+61e93d24 fix(config): derive vault store reference from a keyed installation secret (#140)+9a649dd6 feat: memory write-path integrity and store safety wave (v1.32.0) (#139)+f2a037eb feat: today operator surface - dashboard, open loops, marker write-back (v1.31.0) (#138)+13bde6c3 refactor: remove all import cycles, decompose search.ts (v1.30.1) (#137)+fd5661f9 feat: governance visibility - vitals scorecard + batch-inflation lint (v1.30.0) (#136)+a99b0e71 feat(brain): add o2b brain vitals scorecard + batch-concept-inflation lint (#135)+70fb36e1 feat: operability, safety & first-run experience (v1.29.0) (#134)+ac26a675 feat: retrieval & ranking quality (v1.28.0) (#133)+5cd52e70 fix(hermes): resolve o2b when memory provider PATH is tiny (v1.27.1) (#131)+99adb65f feat: ingestion & import robustness (v1.27.0) (#132)+fb474acc test(hermes): verify OSB surface against core normalize/validate-before-wrap and in_place compaction (1.26.1) (#129)++Conventions:+- The kernel is deterministic. It issues no model calls. Anything that must classify, rank, or gate does so from structural signals or numeric scores.+- Search, classification, ranking and extraction must be language-agnostic. Hardcoded natural-language word lists (stop-words, greetings, keywords, negations) are forbidden in EVERY language.+- Every new flag, argument or configuration key must leave behaviour byte-identical when absent.+- A forward pointer printed to the operator resolves a REGISTERED diagnostic code through the advisory rail (src/cli/advisory-rail.ts, src/core/brain/next-step.ts). Caller-supplied prose is rejected by a build ratchet.+- Findings carry their data as structured fields, not embedded in prose messages.+- The vault is plain Markdown replicated peer-to-peer by Syncthing. There is NO git transport for the vault, and nothing may place a .git directory inside the replicated tree.+- Continuity telemetry is emitted through emitGatedTelemetry (src/core/brain/continuity/emit.ts): gated by a configuration key, fail-open, redaction-passing.++Constraints:+- No fallback that silently does nothing. An error must surface explicitly as an error.+- No stubs, no placeholders, no dead code paths.+- SOLID, KISS, DRY. Anything extractable belongs in a named constant or local.+- Do not add an external service dependency, and do not introduce a new runtime dependency without saying so explicitly as a trade-off.+- Do not change existing public command-line or Model Context Protocol surfaces incompatibly.++# Required output format++Produce exactly 3 distinct architectural variants. For each variant:++### Variant N: <short name>+- **Approach**: 2-3 sentences describing the variant.+- **Trade-offs**: bullet list of pros and cons.+- **Complexity**: small | medium | large+- **Risk**: low | medium | high++After the three variants, add exactly one recommendation:++### Recommended: Variant N+**Rationale**: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.++Output nothing outside of these sections.diff --git a/docs/brainstorm/signals-that-survive/cli-output/prompt-unroutable-capture-hint.md b/docs/brainstorm/signals-that-survive/cli-output/prompt-unroutable-capture-hint.mdnew file mode 100644index 00000000..3f1e256e--- /dev/null+++ b/docs/brainstorm/signals-that-survive/cli-output/prompt-unroutable-capture-hint.md@@ -0,0 +1,95 @@+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++## [upstream:plur] Capture-time routing hint for unrouted memories++**Source**: https://github.com/plur-ai/plur/releases/tag/v0.15.0+**Repo**: plur-ai/plur (154β )+**Released**: v0.15.0 (2026-07-24T16:11:21Z)++## What+When a captured memory cannot be routed because the user omitted a domain/scope, return a non-blocking hint naming the missing routing signal and likely eligible scopes.++## Why useful for OSB+This would improve capture quality without rejecting user writes. It helps users and agents learn the minimum metadata needed for reliable routing, reducing unrouted notes and later retrieval noise.++## Status in OSB+- **Verdict**: unverified+- **Codegraph hints**: unverified β codegraph MCP tools were not exposed in this runtime; projectPath would be /srv/projects/open-second-brain. No codegraph query was possible, so this task needs verification during triage.++## Notes+Upstream evidence: plur v0.15.0 adds a `domain_hint` for domain-less, scope-less writes when covers-declaring scopes are registered; it is silent on personal installs with no eligible scopes and never blocks a write.++--- validator comment [osb-triage-validator]:+osb-triage-validator @ 2026-07-25T22:53:39Z:+- sanity: clean+- cluster: no cluster+- priority: set to 1: unverified (codegraph MCP unavailable; capture-time routing hint needs verification; also depends on OSB having scope-declaring routes)++--- validator comment [claude-dev-agent]:+claude-dev-agent @ 2026-07-27: triage validation pass (operator-directed: link + priority actualization; internal work ranks above external-product integration)+- priority: 1 -> 2.+- verdict resolved unverified against source. The write router is routeExtractedFacts (src/core/brain/fact-extract.ts:307). OSB has NO domain/scope concept on it, so the literal upstream feature - a domain_hint naming which of the registered covering scopes was missing - has nothing to hint ABOUT. The validator's caveat ("depends on OSB having scope-declaring routes") is confirmed correct.+- re-scoped rather than closed, because the transferable half is the SHAPE, not the domain model: a non-blocking hint that names the missing routing signal instead of silently accepting an unroutable write. That is exactly the v1.40.0 rail - resolve a REGISTERED code, never caller-supplied prose (src/core/brain/next-step.ts, src/cli/advisory-rail.ts).+- raised to 2 on that basis: internal, small, and it now has a native seam instead of needing a bespoke hint mechanism.++# Project context++Project: Open Second Brain - a TypeScript/Bun command-line tool plus Model Context Protocol server over an Obsidian-compatible Markdown vault.+Runtime: Bun. Tests: `bun test` via `bash scripts/test` (910 *.test.ts files). Typecheck: `tsc --noEmit`. Lint: oxlint. Format: oxfmt.++Recent commits (newest first):+0963ef0a feat: no dead ends - every diagnosis names its exit (v1.40.0) (#151)+f91a698b feat: context integrity gates (v1.39.0) (#150)+c31a2574 feat: semantic-health baseline watermark (v1.38.0) (#148)+b0c37977 feat: retrieval quality and context delivery (v1.37.0) (#146)+842d690f feat: knowledge intake and consolidation (v1.36.0) (#145)+95dc8577 feat: trusted recall and memory write surface (v1.35.0) (#144)+426d06f8 fix(vault): parse block-style YAML lists in frontmatter (not just inline arrays) (#142)+4b8100ca feat: source pipeline integrity and operator tooling (v1.34.0) (#143)+77513f2b feat: belief lifecycle and decision memory (v1.33.0) (#141)+61e93d24 fix(config): derive vault store reference from a keyed installation secret (#140)+9a649dd6 feat: memory write-path integrity and store safety wave (v1.32.0) (#139)+f2a037eb feat: today operator surface - dashboard, open loops, marker write-back (v1.31.0) (#138)+13bde6c3 refactor: remove all import cycles, decompose search.ts (v1.30.1) (#137)+fd5661f9 feat: governance visibility - vitals scorecard + batch-inflation lint (v1.30.0) (#136)+a99b0e71 feat(brain): add o2b brain vitals scorecard + batch-concept-inflation lint (#135)+70fb36e1 feat: operability, safety & first-run experience (v1.29.0) (#134)+ac26a675 feat: retrieval & ranking quality (v1.28.0) (#133)+5cd52e70 fix(hermes): resolve o2b when memory provider PATH is tiny (v1.27.1) (#131)+99adb65f feat: ingestion & import robustness (v1.27.0) (#132)+fb474acc test(hermes): verify OSB surface against core normalize/validate-before-wrap and in_place compaction (1.26.1) (#129)++Conventions:+- The kernel is deterministic. It issues no model calls. Anything that must classify, rank, or gate does so from structural signals or numeric scores.+- Search, classification, ranking and extraction must be language-agnostic. Hardcoded natural-language word lists (stop-words, greetings, keywords, negations) are forbidden in EVERY language.+- Every new flag, argument or configuration key must leave behaviour byte-identical when absent.+- A forward pointer printed to the operator resolves a REGISTERED diagnostic code through the advisory rail (src/cli/advisory-rail.ts, src/core/brain/next-step.ts). Caller-supplied prose is rejected by a build ratchet.+- Findings carry their data as structured fields, not embedded in prose messages.+- The vault is plain Markdown replicated peer-to-peer by Syncthing. There is NO git transport for the vault, and nothing may place a .git directory inside the replicated tree.+- Continuity telemetry is emitted through emitGatedTelemetry (src/core/brain/continuity/emit.ts): gated by a configuration key, fail-open, redaction-passing.++Constraints:+- No fallback that silently does nothing. An error must surface explicitly as an error.+- No stubs, no placeholders, no dead code paths.+- SOLID, KISS, DRY. Anything extractable belongs in a named constant or local.+- Do not add an external service dependency, and do not introduce a new runtime dependency without saying so explicitly as a trade-off.+- Do not change existing public command-line or Model Context Protocol surfaces incompatibly.++# Required output format++Produce exactly 3 distinct architectural variants. For each variant:++### Variant N: <short name>+- **Approach**: 2-3 sentences describing the variant.+- **Trade-offs**: bullet list of pros and cons.+- **Complexity**: small | medium | large+- **Risk**: low | medium | high++After the three variants, add exactly one recommendation:++### Recommended: Variant N+**Rationale**: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.++Output nothing outside of these sections.diff --git a/docs/brainstorm/signals-that-survive/design.md b/docs/brainstorm/signals-that-survive/design.mdnew file mode 100644index 00000000..0f45d453--- /dev/null+++ b/docs/brainstorm/signals-that-survive/design.md@@ -0,0 +1,231 @@+# Signals that survive - every signal the kernel already computes reaches the decision it should change++**Status:** draft+**Author:** claude-dev-agent (via feature-release-playbook)+**Audience:** implementation++## Problem statement++Open Second Brain computes more than it uses. A repository declares which files+it considers noise and the ingest planner ignores that declaration. A recall+attempt is graded weak and the grade evaporates when the call returns. A write+router picks between near-equal destinations and records neither the runner-up+nor the reason. A query names a time period and the ranker keeps applying a+freshness prior that points the other way. A knowledge-gap loop with promotion,+a session agenda and auto-close is fully implemented and has no caller.++Each of these is the same defect in a different subsystem: a signal exists, is+correct, and is dropped before it reaches the decision it could improve. This+wave carries nine of them the last few metres.++## Scope++Nine atomic units, in dependency-free order:++1. **Git-aware ingest discovery** (`t_4b2bd8f7`) - the ingest batch planner honours+ the repository's own `.gitignore`, nested `.gitignore`, `.git/info/exclude`,+ and submodule boundaries, through a discovery module extracted from the+ hygiene scan so both paths share one implementation.+2. **Typed parse errors** (`t_ceee3b4d`) - preference and retired-preference parse+ failures carry their path as a field instead of embedding it in the message,+ which removes the duplicated path from every `o2b brain doctor` parse-error line.+3. **Route discrimination** (`t_07ad3c42`) - **BUILT, REVIEWED, AND REVERTED. Not+ shipped.** The unit scored candidate routes and separated near-equal ones with a+ registered ladder, emitting a gated record. Independent review found the routed+ destination was not byte-identical with the gate absent, because the premise "a+ route captured for its own span always attains full coverage" is falsified by the+ extractor's 200-character cap. Fixing that produced a correctness proof, and the+ proof settled the unit: once the captured family is scored over the span it+ actually matched, a sub-reading always pays the containment penalty and falls at+ least 14 below it, outside the margin of 10. Only a rival claiming the span IN FULL+ can enter the band - and the three families this router chooses between cannot,+ because a complete `url` match carries `://`, a complete `email` match carries `@`,+ and `quantity` is a number bound to a unit sigil. The one overlap that does occur+ is already resolved by the extractor before routing. The ladder therefore never+ fires and the record is never written.++ The task premise is what was wrong. The ambiguity it describes - a taste signal+ that is also an obligation, a note that is really a decision - is real, but+ `routeExtractedFacts` chooses among structurally disjoint pattern families and has+ nothing to disambiguate. Anchoring the work there came from the task body and no+ reconnaissance caught it; the correctness proof did. Any future attempt must first+ name a write surface whose destinations can genuinely claim the same span.+4. **Unroutable-capture hint** (`t_75597bb9`) - a scope-less feedback write returns a+ non-blocking structured hint naming the missing routing signal and the scope+ slugs the vault actually contains, resolved through the advisory rail.+5. **Query-side temporal intent** (`t_58fc4720`) - a query carrying an explicit time+ window biases ranking toward that window through a capped additive layer, and+ damps the freshness prior when the window is historical.+6. **Recall-adequacy feeds the gap loop** (`t_3f96f87a`) - weak and insufficient+ recall verdicts become a second signal source for the already-built knowledge-gap+ loop, and that loop is wired into the session hooks it was written for.+7. **Fact and skill markers** (`t_9ba5c027`) - the inline marker grammar gains two+ kinds, routed into stores that already carry a review gate.+8. **Response-shape validation** (`t_80b01448`) - agent-supplied payloads on the three+ model-authored write paths are validated against a declared shape before any+ normalization, fail-closed.+9. **Durable work identity** (`t_e6be4f6b`) - an optional declared work id and lane id+ let session lineage re-attach resumed work across model, account, branch and+ worktree changes, ranked above the fifteen-minute timing window.++## Out of scope++- A local transformer embedding provider (`t_916f9953`). It requires a model+ artifact and an inference runtime - an external dependency the rest of this+ wave deliberately avoids.+- Auto-memory extraction from the conversation stream (`t_1dace26d`). It is the+ child of unit 8 and ships once the response-shape layer has settled in practice.+- Any integration with an external product. Obsidian compatibility is not an+ external integration; it is the vault format.+- Replacing `CRUTCH_LINK_WINDOW_MS`. Unit 9 demotes it to a fallback rung; deleting+ it would remove the only resolution path available when nothing declares an identity.+- Re-implementing the ambiguity abstention layer shipped in v1.39.0. Unit 9 consumes it.++## Chosen approach++Every unit takes the variant that reaches the decision point through machinery the+repository already owns, rather than standing up a parallel mechanism.++**Unit 1** extracts the hygiene scan's ignore-layering into a module beside+`src/core/fs/ignore.ts`, so `collectIngestible` and `listScanTargets` compose the+same reader. Submodule detection - the one net-new piece - is written once. Warnings+are returned as structured values rather than printed, so the kernel does not write+to a stream. Discovery stays in-process: shelling out to `git ls-files` would make a+reproducible `planId` depend on an external binary and on user-global git config.++**Unit 2** introduces a typed parse error carrying `path` structurally, modelled on+`BrainStatusFolderMismatchError`, which `classifyParseError` already special-cases.+The two branches of that function stop being asymmetric, and a future throw site+cannot re-embed the path without going around the type.++**Unit 3** splits the router decision into two pure functions - candidate scoring and+discrimination - with the discriminator a fixed ordered ladder of structural rules,+each with a stable id. The terminal rule reproduces today's family-table order, so+routing is byte-identical until a rule earlier in the ladder separates a genuine tie.++**Unit 4** extends `write-advisory.ts`, which already implements exactly the required+shape: computed around the write, never blocking it, surfaced as a structured field.+Eligible scopes are derived from document frequency over vault frontmatter, never from+a word list.++**Unit 5** detects temporal intent at the query-plan seam and consumes it in the ranker+as its own capped additive layer over `temporalProximity`, alongside a modest recency+damping when the window is historical. Freshness prior and temporal intent stay+separately attributable in `reasons` and `ScoreBreakdown`.++**Unit 6** stamps the adequacy verdict onto the demand record whose bucket key+`normalizeQueryTerms` already computes, generalises `detectRecurringGaps` to aggregate+over both its structural source and the verdict source, and wires the module into the+session hooks its own header comment says it was written for.++**Unit 7** adds two rows to the marker kind table and their routing. A `fact` marker+becomes an unconfirmed preference; a `skill` marker becomes a pending proposal. Both+destinations already have a review gate, so no new gating code is introduced.++**Unit 8** promotes the JSON-Schema-subset validator in `src/mcp/output-contract.ts`+into a core module named for response *shape*, and declares one frozen descriptor per+model-authored write path.++**Unit 9** adds optional `workId` and `laneId` to the ledger line and a precedence rung+above the crutch resolver. Identity is declared, never derived. A lane mismatch is a+hard separator, not a tiebreak.++## Design decisions++- **Two consultant recommendations were overridden.** Both are recorded in+ `variants.md` with the reasoning; the rest were adopted as returned.++ - *Unit 8, the dormant configuration key.* The consultant proposed gating strict+ validation behind a key defaulting to today's tolerance, so the strict path ships+ inert until an operator opts in. That is a validator that validates nothing, which+ is the silent-no-op this project forbids. Validation is unconditional and fail-closed.+ The byte-identical-when-absent rule governs new flags and configuration keys; this+ unit adds neither. A payload that would have degraded silently now raises a named error.++ - *Unit 6, the durable artifact.* The task brief instructs minting an **obligation**.+ The implementation mints a **gap task** instead. The constraint the brief was+ protecting - stay internal, never write to an external tracker - is fully satisfied:+ `Brain/gap-tasks/` is a plain vault directory and `gap-loop.ts` states in its own+ header that it never touches the kanban board. Obligations are cadence-bearing by+ construction and have no auto-close; gap tasks close themselves when the same topic+ later recalls with sufficient confidence, which is what makes a minted item bounded+ rather than permanent litter. Building a second promotion-agenda-autoclose pipeline+ against `obligations.ts` would duplicate a working one.++- **A finding recorded here during scoping was wrong, and is corrected rather than+ deleted.** This document originally claimed `src/core/brain/gaps/gap-loop.ts` was 274+ lines of fully implemented machinery with no callers, and framed unit 6 as mostly+ hook wiring. That was based on a grep scoped to `src/`, which does not contain the+ hooks. `hooks/gap-promote.ts` and `hooks/gap-agenda.ts` exist, are registered in+ `hooks/hooks.json` and in the install manifest, shipped in v1.35.0, and are covered by+ tests for both the flag-on and flag-off paths. The two configuration keys are genuinely+ resolved, not merely documented. The loop was already wired end to end.++ What unit 6 actually adds is therefore narrower and more honest: a second signal+ source. The structural telemetry source was the only thing that could ever promote a+ gap; a graded recall verdict could not, because nothing carried it past the call that+ produced it. The release note must not claim dead machinery was revived.++- **Recurrence identity is never natural language.** Unit 6 reuses `normalizeQueryTerms`,+ which derives its bucket from document frequency and drops secret-shaped tokens. Unit 5+ detects time intent only from ISO tokens and the existing `<field>:<value>` grammar.+ The natural-language phrase detection the upstream sources perform is not portable to a+ system that must behave identically in every language, and is not attempted.++- **Discrimination is recorded, not just performed.** Unit 3 emits through+ `emitGatedTelemetry`, carrying the candidate set, the scores, the margin and the winning+ rule id - never the fact text. A tie-break that cannot be audited is a tie-break that+ cannot be tuned.++- **Ambiguity is separated from resolution.** Unit 3 decides; it does not quarantine.+ A quarantine lane converts misfiled writes into operator queue depth, which moves the+ cost rather than removing it. If the emitted records later show a margin band the ladder+ genuinely cannot separate, quarantine is the bounded escalation to add then.++- **No new runtime dependency, in any unit.** Unit 8 reuses a validator the repository+ already owns rather than adding a schema library.++## File changes++New:++- `src/core/fs/git-discovery.ts` - repo-root base scope, per-directory extension, submodule predicate, structured warnings.+- `src/core/brain/parse-error.ts` - typed parse error carrying `path` as a field.+- `src/core/brain/routing/route-discriminator.ts` - candidate scoring, the rule ladder, the gated record.+- `src/core/search/temporal-intent.ts` - query-side temporal window detection at the plan seam.+- `src/core/brain/response-shape.ts` - shape descriptors and the fail-closed validator.++Modified:++- `src/core/brain/ingest/batch-plan.ts`, `src/core/hygiene/scan-repo.ts` - both consume the extracted discovery module.+- `src/core/brain/preference.ts`, `src/core/brain/doctor.ts`, `src/cli/brain/verbs/doctor.ts` - typed parse error.+- `src/core/brain/fact-extract.ts` - route discrimination at the single write router.+- `src/core/brain/write-advisory.ts` and its two call sites - the routing hint.+- `src/core/search/query-plan.ts`, `src/core/search/ranker.ts`, `src/core/search/search.ts`, `src/core/search/types.ts` - the temporal-intent layer.+- `src/core/brain/query-demand.ts`, `src/core/brain/gaps/gap-loop.ts`, the session hooks - the adequacy signal and the wiring.+- `src/core/brain/inline.ts` and the marker routing sites - the two new kinds.+- `src/core/brain/lineage/ledger.ts`, `src/core/brain/lineage/crutch.ts` - the identity rung.+- `src/core/brain/next-step.ts`, `src/cli/advisory-rail.ts` - the registered codes units 4 and 6 resolve.+- `CHANGELOG.md`, `README.md`, `package.json` and the mirrored manifests.++## Risks and open questions++- **Unit 1 touches a green subsystem.** The hygiene scan is behaviour-pinned by existing+ tests. The extraction must be provably inert there before the ingest wiring is written;+ the hygiene diff is motion, not behaviour.+- **Unit 5 adds a key to `ScoreBreakdown`,** which is visible over the Model Context+ Protocol. It is additive, and an absent temporal window contributes zero, but the new+ capped constant must be calibrated against the existing link, entity, activation and+ reuse caps so the layers stay in proportion.+- **Unit 3 has no ground truth on day one.** Early records will mostly show the terminal+ rule firing. That is the expected shape of a measurement surface before data accumulates,+ and is not a reason to guess weights.+- **Unit 6 changes what `occurrences` counts.** The structural gap source is a coarse code+ bucket and the verdict source is a fine term bucket. The two must remain distinguishable+ on the agenda rather than being summed into one number whose meaning varies by row.+- **Unit 9 depends on something declaring an identity.** An unwired host gets no benefit.+ This is accepted: the alternative - deriving identity structurally - places a mutable,+ effectively irreversible union registry inside a Syncthing-replicated tree with no arbiter.+- **Unit 2 is cosmetic in effect and structural in cost.** It is included because the+ duplication is a symptom of prose carrying data, which the previous release spent eleven+ units removing elsewhere.diff --git a/docs/brainstorm/signals-that-survive/plan.md b/docs/brainstorm/signals-that-survive/plan.mdnew file mode 100644index 00000000..d44ade09--- /dev/null+++ b/docs/brainstorm/signals-that-survive/plan.md@@ -0,0 +1,197 @@+# Signals that survive - implementation plan++Nine atomic units. Each lands as its own conventional commit on+`feat/signals-that-survive`, written test-first: the test is written and run and+must fail with the expected error before the implementation exists.++Unit numbers are the ones in `design.md`'s Scope list and are authoritative -+code comments referencing this wave use them. The nine units have no dependency+edges between them on the kanban board, so the sections below are laid out in+EXECUTION order rather than in unit order: units sharing a file must not run+concurrently, and the sequence here is what keeps them apart.++Execution order: 1, 2, 4, 7, 8, 9, then 3, then 5, then 6.++## Tasks++### Task 1: Shared git-aware discovery module++- **Kanban**: `t_4b2bd8f7`+- **Files**: new `src/core/fs/git-discovery.ts`; `src/core/hygiene/scan-repo.ts`+ (consume, behaviour unchanged); `src/core/brain/ingest/batch-plan.ts` (wire into+ `collectIngestible`); tests under `tests/`.+- **Acceptance**:+ - The hygiene scan's existing tests pass unmodified after the extraction - the+ refactor is provably inert.+ - An ingest plan over a directory containing a `.gitignore` excludes the declared+ paths; nested `.gitignore` files apply to their own subtree only.+ - `.git/info/exclude` is layered beneath the root `.gitignore`.+ - A submodule directory (gitlink file or nested `.git`) is not descended into.+ - Operator `--exclude` patterns still win over every repository-declared layer.+ - A directory with no ignore files produces the exact `planId` it produces today.+ - A malformed pattern in a repository's own `.gitignore` is returned as a+ structured warning on the plan, and does not fail the plan; a malformed operator+ `--exclude` still throws, as it does today.+- **Depends on**: none++### Task 2: Typed parse error carrying the path as a field++- **Kanban**: `t_ceee3b4d`+- **Files**: new `src/core/brain/parse-error.ts`; `src/core/brain/preference.ts`+ (throw the typed error from the preference and retired-preference parsers);+ `src/core/brain/doctor.ts` (`classifyParseError` reads the field);+ `src/cli/brain/verbs/doctor.ts` (renderer unchanged, verified by test); tests.+- **Acceptance**:+ - `o2b brain doctor` renders a parse-error finding with the path exactly once.+ - The finding's structured `path` field is unchanged.+ - All four parse-error kinds are covered, not only `preference-missing-field`.+ - The existing code classification still resolves from the bare message.+ - A caller that surfaces the error message directly still receives the path,+ through the shared location formatter rather than through string concatenation+ at the throw site.+- **Depends on**: none++### Task 3: Route discrimination on the extracted-fact router++- **Kanban**: `t_07ad3c42`+- **Files**: new `src/core/brain/routing/route-discriminator.ts`;+ `src/core/brain/fact-extract.ts` (`routeExtractedFacts` consumes it);+ `src/core/config.ts` (the gate key); tests.+- **Acceptance**:+ - `scoreRouteCandidates` is pure, returns a deterministically ordered frozen+ array, and every feature it reads is a count, an offset or a set membership -+ no natural-language token list, in any language.+ - `discriminate` fires only when the top two candidates are within the margin.+ - The terminal rule reproduces today's family-table order, so with no earlier rule+ separating the candidates the routed destination is identical to today's.+ - Each rule has a stable id, and the id that decided is recorded.+ - With the gate key absent, no telemetry record is written and behaviour is+ byte-identical.+ - With the gate key set, one `route_discrimination` record per discrimination+ carries the candidate set, scores, margin, winner and rule id, and carries no+ fact text.+- **Depends on**: none++### Task 4: Unroutable-capture routing hint++- **Kanban**: `t_75597bb9`+- **Files**: `src/core/brain/write-advisory.ts` (sibling of `adviseIncomingFeedback`);+ the CLI `feedback` verb and the `brain_feedback` tool (surface the structured field);+ `src/core/brain/next-step.ts` (one registered diagnostic code); tests.+- **Acceptance**:+ - A scope-less feedback write on a vault containing scoped preferences returns a+ hint naming `scope` as the missing signal plus the observed scope slugs, ranked+ by document frequency.+ - A vault with no scope corpus returns `null` - the hint is silent, not empty prose.+ - The write always lands; the hint never blocks or alters it.+ - The human surface prints the forward pointer through the advisory rail against a+ registered code; no sentence is assembled at the call site.+ - No new configuration key is introduced.+- **Depends on**: none++### Task 5: Fact and skill marker kinds++- **Kanban**: `t_9ba5c027`+- **Files**: `src/core/brain/inline.ts` (`MarkerKind`, `KNOWN_KINDS`,+ `REQUIRED_FIELDS`, two narrowing guards); the marker routing sites; tests.+- **Acceptance**:+ - A `fact` marker with all required fields routes to an unconfirmed preference; a+ missing required field is an explicit parse error naming the field.+ - A `skill` marker routes to the pending skill-proposal store, never to accepted.+ - Fence-awareness, the consumed sentinel and the dedup hash apply to both new kinds+ without new code - a re-run over the same file is idempotent.+ - Both the inline and the block shape parse for both kinds.+ - A file containing no markers of the new kinds behaves byte-identically.+- **Depends on**: none++### Task 6: Response-shape validation on model-authored write paths++- **Kanban**: `t_80b01448`+- **Files**: new `src/core/brain/response-shape.ts` (promoted from+ `src/mcp/output-contract.ts`, named for shape rather than schema);+ `src/mcp/output-contract.ts` (re-export or consume, one definition only);+ the distill, derive-fact and dream payload entry points; tests.+- **Acceptance**:+ - Each of the three write paths validates its payload against a frozen descriptor+ before any normalization.+ - A payload violating the descriptor raises a named error carrying `{code, path,+ message}` as fields; it is never coerced, never partially written, and never+ silently dropped.+ - Validation is unconditional - there is no key that turns it off, because a+ validator that can be disabled is a validator the write path cannot rely on.+ - Descriptors stay shallow: required keys, primitive types, arrays of objects.+ A test asserts no descriptor uses a construct the subset validator cannot express.+ - The word `schema` is not used for this layer anywhere in the public surface, so+ it cannot be confused with the knowledge vocabulary in `schema-contracts.ts`.+- **Depends on**: none++### Task 7: Query-side temporal intent++- **Kanban**: `t_58fc4720`+- **Files**: new `src/core/search/temporal-intent.ts`;+ `src/core/search/query-plan.ts` (detect, contribute to `planHash`);+ `src/core/search/ranker.ts` (capped additive layer over `temporalProximity`);+ `src/core/search/search.ts` (thread the event-time map);+ `src/core/search/types.ts` (one additive `ScoreBreakdown` key); tests.+- **Acceptance**:+ - Detection reads only ISO tokens and the existing `<field>:<value>` grammar. A+ test asserts that a query written in a non-Latin script with an ISO date is+ detected identically to the same query in English.+ - A query with no temporal window produces byte-identical ranking, an absent+ breakdown key and an unchanged `planHash`.+ - A query naming a historical window ranks an in-window note above an equally+ relevant recent one.+ - The freshness prior and the temporal layer appear as separate entries in+ `reasons`, so a ranking change is attributable to one of them.+ - The new cap is a named constant, and a test asserts it is in proportion to the+ existing link, entity, activation and reuse caps.+- **Depends on**: none++### Task 8: Recall adequacy feeds the knowledge-gap loop++- **Kanban**: `t_3f96f87a`+- **Files**: `src/core/brain/query-demand.ts` (optional adequacy level on the record);+ the two verdict sites (`src/mcp/search-tools.ts`, `src/mcp/brain/pack-tools.ts`);+ `src/core/brain/gaps/gap-loop.ts` (aggregate over both sources);+ the session-start and session-end hooks (wire the dormant module behind the+ existing `gap_loop_enabled` / `gap_loop_threshold` keys); tests.+- **Acceptance**:+ - A weak or insufficient verdict stamps the demand record whose bucket key comes+ from `normalizeQueryTerms` - no new identity concept is introduced.+ - A bucket recurring at or above the threshold with weak verdicts promotes to one+ gap task; below the threshold nothing is minted.+ - Promotion is capped per run, and the cap is a named constant.+ - Structural gap rows and verdict rows stay distinguishable on the agenda - a test+ asserts `occurrences` is never a sum across the two sources.+ - An existing open gap task for the same key is not duplicated.+ - A gap task auto-closes when its topic later recalls with sufficient confidence.+ - With `gap_loop_enabled` absent, no gap task is written and the session hooks+ behave byte-identically.+- **Depends on**: none. Shares no file with tasks 1 through 7.++### Task 9: Durable work identity above the timing crutch++- **Kanban**: `t_e6be4f6b`+- **Files**: `src/core/brain/lineage/ledger.ts` (optional `wid` / `lane` on+ `LedgerLine`); `src/core/brain/lineage/crutch.ts` (a precedence rung above the+ window); the capture boundary that sources the identity; tests.+- **Acceptance**:+ - Identity is sourced in strict declared precedence and is never inferred.+ - Two ledger entries sharing a work id link on identity alone, with no freshness+ bound and no `cwd`, branch or commit predicate - so a resumed session re-attaches+ after a branch or worktree switch.+ - Two entries sharing a work id but carrying different lane ids never link, and the+ refusal is a named outcome, not a silent non-link.+ - Two same-lane survivors abstain through the v1.39.0 ambiguity path with a named+ reason; the abstention layer is consumed, not re-implemented.+ - With both fields absent, `resolveSessionLineageDetailed` returns exactly what it+ returns today, and the ledger's integrity chain is unaffected.+- **Depends on**: none++### Task 10: Release surface++- **Files**: `CHANGELOG.md` (one `## [1.41.0]` entry plus its compare link),+ `README.md`, `package.json`, then `bun run scripts/sync-version.ts`.+- **Acceptance**: `bun run scripts/sync-version.ts --check` is clean; the CHANGELOG+ heading and `package.json` agree.+- **Depends on**: tasks 1 through 9diff --git a/docs/brainstorm/signals-that-survive/variants.md b/docs/brainstorm/signals-that-survive/variants.mdnew file mode 100644index 00000000..a4783697--- /dev/null+++ b/docs/brainstorm/signals-that-survive/variants.md@@ -0,0 +1,446 @@+# Signals that survive - variant audit trail++Nine atomic units, one consultant pass each. The primary consultant (Claude Code,+`claude -p`) returned three variants and one recommendation per unit; all nine runs+exited zero, so the Codex fallback was not invoked.++Every consultant claim about the codebase was re-checked against the source before+any decision was taken. One anchor was wrong: the consultant placed+`temporalProximity` in `src/core/brain/temporal-bridge.ts`; it lives in+`src/core/search/temporal-bridge.ts`. Everything else held, including the claim that+`src/core/brain/gaps/gap-loop.ts` is fully implemented and unreferenced - verified by+grep, whose only hit outside the module itself is a comment in `src/core/config.ts`.++## Orchestrator decisions++| Unit | Kanban | Consultant recommendation | Decision |+| --- | --- | --- | --- |+| Git-aware ingest discovery | `t_4b2bd8f7` | Variant 2 - extract a shared module | adopted |+| Doctor path duplication | `t_ceee3b4d` | Variant 2 - typed parse error | adopted |+| Route discriminator | `t_07ad3c42` | Variant 1 - in-router ladder | adopted |+| Unroutable-capture hint | `t_75597bb9` | Variant 1 - extend the write advisory | adopted |+| Query temporal intent | `t_58fc4720` | Variant 3 - capped additive layer | adopted |+| Recurring weak recall | `t_3f96f87a` | Variant 2 - feed the gap loop | adopted, overriding the task brief |+| Fact and skill markers | `t_9ba5c027` | Variant 1 - two kinds, existing entry points | adopted |+| Response shape | `t_80b01448` | Variant 1 - promote the subset validator | adopted with one modification |+| Durable work identity | `t_e6be4f6b` | Variant 1 - declared identity rung | adopted |++### Modification to the response-shape recommendation++The consultant's Variant 1 proposed a configuration key defaulting to today's+tolerance, so strict validation would ship dormant until an operator opted in. That+is rejected. A validator that is off by default validates nothing, and this project+forbids a path that appears to protect something and does not. Validation is+unconditional and fail-closed.++The byte-identical-when-absent convention is not violated by this: it governs the+behaviour of new flags and configuration keys, and this unit introduces neither. It+does change behaviour for a malformed payload - which is the entire point of the+task, whose stated value is turning silent parse degradation into a catchable failure.++### Override of the task brief on the recall-adequacy unit++`t_3f96f87a`'s validated body instructs minting an **obligation**. The implementation+mints a **gap task**. The constraint that instruction was protecting - stay internal,+never write to an external tracker - holds completely: `Brain/gap-tasks/` is a plain+vault directory, and `gap-loop.ts` states in its own header that it never touches the+kanban board.++The reason for the substitution is auto-close. An obligation is cadence-bearing and+has no mechanism to resolve itself; a gap task closes when its topic later recalls+with sufficient confidence. The brief itself names caps and bounding as load-bearing+rather than polish, and a self-closing item is a stronger bound than any mint+threshold. Reusing the existing promotion, agenda and auto-close pipeline also avoids+building a second copy of it against `obligations.ts`.++## Consultant output, verbatim++### Unit: doctor-path-duplication++### Variant 1: Strip the path at the throw sites+- **Approach**: Delete the ` (${path})` tail from the ~15 `throw new Error(...)` sites in `src/core/brain/preference.ts` (`requireField`, `requireString`, `requireStringArray`, the `kind`/`retired_reason` enum checks, and the confidence/schema helpers), leaving the message as pure prose about the field. The doctor's existing `path` field then becomes the single source of the location, and the renderer's tail is untouched. Callers that today rely on the message carrying the path (`dream`, `query`, `export`, `merge`, `apply-evidence`, `pin`, `preference-txn`) must each be audited and given the path from the call site they already know.+- **Trade-offs**:+ - Pro: smallest conceptual change; matches the stated fix direction literally β the message stops embedding the path.+ - Pro: no new type, no new indirection; DRY holds because the path was always duplicated for the doctor.+ - Con: the path is *only* recoverable from the message today for every non-doctor caller that surfaces `(exc as Error).message` bare β stripping it there loses operator context unless each of ~10 caller modules is fixed in the same change, which is exactly the "silently does nothing" failure mode the constraints forbid.+ - Con: blast radius is wide for a cosmetic priority-3 item; every test asserting the current message text (parse-error fixtures, doctor fixtures, dream/query error paths) has to move together.+ - Con: nothing structurally prevents the next `throw` from re-adding `(${path})`.+- **Complexity**: medium+- **Risk**: medium++### Variant 2: Typed parse error carrying `path` as a field+- **Approach**: Introduce a `BrainParseError` (path + bare message) modelled directly on the `BrainStatusFolderMismatchError` that `classifyParseError` already special-cases in `src/core/brain/doctor.ts` β that class carries `path` structurally and its `message` contains no path, so the doctor already emits it correctly. The preference/retired parsers throw `BrainParseError` instead of bare `Error`; the doctor reads `err.path`/`err.message` as fields, and non-structured callers format location through one shared helper rather than string concatenation at 15 sites.+- **Trade-offs**:+ - Pro: the path is never lost β it moves from prose into a field that every caller can read, which is the same move v1.40.0 made for findings.+ - Pro: follows an in-repo precedent living in the exact function being fixed, so the two parse-error branches of `classifyParseError` stop being asymmetric.+ - Pro: makes regression structural β a future throw site cannot embed the path without going around the typed error.+ - Pro: the `parseErrorCode` regex classification (`/missing field/`, `/ISO-8601/i`) keeps working on the bare message and becomes less coupled to incidental path text.+ - Con: largest of the three; a new exported error type plus migration of every throw site and its `instanceof`-blind catch sites.+ - Con: overshoots the reported defect β most of the work buys structure, not the missing byte.+ - Con: callers doing `catch (exc) { fail(exc.message) }` need a decision per site about whether to append the path, so the change is not mechanical.+- **Complexity**: medium+- **Risk**: low++### Variant 3: Normalize at the doctor boundary+- **Approach**: Leave `preference.ts` untouched and fix it where the two representations meet: `classifyParseError` in `src/core/brain/doctor.ts` builds the issue from a message with its own trailing ` (<path>)` suffix removed, keyed off the `path` it is already passing into the issue. The renderer at `doctor.ts:49` and every non-doctor caller of the parsers keep byte-identical behaviour.+- **Trade-offs**:+ - Pro: one function, one change, no cross-module audit; all four parse-error kinds (`preference-missing-field`, `preference-invalid`, `retired-missing-field`, `retired-invalid`, plus `iso-invalid` routed through the same push) are fixed at once because they share this single construction point.+ - Pro: zero risk to any other surface β dream, query, export, MCP errors are unaffected.+ - Con: it is prose parsing to undo prose formatting β the doctor now depends on the parser's exact suffix spelling, which is a second, quieter coupling replacing the first.+ - Con: fixes the symptom in one consumer; the same duplication reappears anywhere else that pairs these errors with a structured path field.+ - Con: sits awkwardly against the "findings carry data as fields, not prose" convention β the message still carries the data, it is just trimmed on the way out.+- **Complexity**: small+- **Risk**: low++### Recommended: Variant 2+**Rationale**: The path only lives in prose today, so Variant 1 deletes operator context from every non-doctor caller unless the same change fixes all of them, and Variant 3 trades one prose coupling for another that the next consumer will hit again. Variant 2 does what the fix direction asks β the message stops embedding the path β while keeping the data as a field, and it does so by extending a pattern (`BrainStatusFolderMismatchError`) that already exists in the very function being changed, so the two branches of `classifyParseError` end up consistent instead of one being the exception. If the cosmetic priority argues against the full migration, the typed error can land scoped to `parsePreference`/`parseRetired` only, with the remaining throw sites converted as they are touched.++### Unit: durable-work-identity++### Variant 1: Declared work identity as a precedence rung above the crutch++- **Approach**: Add an optional durable pair β `workId` and `laneId` β sourced at the capture boundary in strict precedence (host payload field, then an environment/config key, then a per-worktree marker recorded in `Brain/.state/`), and persist both as new optional `wid`/`lane` fields on `LedgerLine`. `resolveSessionLineageDetailed` gains a rung between `payload` and `crutch`: when this session and exactly one predecessor share a `wid`, the link is made on identity alone with no freshness bound and no `cwd`/branch/commit predicate, so a resumed work item re-attaches after a model, account, branch or worktree switch. Lanes are a hard separator rather than a tiebreaker β two entries sharing a `wid` but carrying different `laneId` values can never link, and two same-lane survivors abstain through the existing ambiguity path with new named reasons (`lane-conflict`, `work-ambiguous`).+- **Trade-offs**:+ - Exact/external identity always wins, and nothing is inferred; the kernel stays deterministic and no natural-language signal is consulted.+ - Absent `wid`/`lane` the resolver is the current one line-for-line, so the byte-identical-when-absent rule holds without a compatibility shim.+ - The ledger already hashes line bodies by removal of chain fields and compacts verbatim, so new optional fields ride the existing integrity chain untouched.+ - `CRUTCH_LINK_WINDOW_MS` survives as the fallback bound rather than being deleted; the crutch is demoted, not removed, which leaves two resolution rules to reason about.+ - Value depends on something actually declaring the id β an unwired host gets no benefit, so the feature is only as good as its capture-boundary adapters.+ - A stale or copied marker file in a cloned worktree would assert a false identity; the lane separator contains it but does not detect it.+- **Complexity**: medium+- **Risk**: low++### Variant 2: Derived work fingerprint with an attestation-union registry++- **Approach**: Derive the work identity structurally instead of declaring it β a content-addressed fingerprint over canonical remote, upstream/merge-base ref, and worktree gitdir identity β and maintain a union registry in `Brain/.state/` that binds fingerprints observed together by one session into a single work identity, so a branch or worktree switch inside one session teaches the registry that both fingerprints name the same work. The lane is derived from the gitdir identity, keeping parallel worktrees separate by construction. Resolution keys on registry membership, and a union that would join two already-distinct works abstains rather than merging.+- **Trade-offs**:+ - Requires no host cooperation and no operator action; every existing session gains identity immediately.+ - Lane separation falls out of the same derivation as identity, so there is no second thing to wire or forget.+ - The property that must survive β branch and worktree change β is precisely what the fingerprint encodes, so identity only survives through a learned union, and the very first switch cannot be recognized until after the fact.+ - Unions are cumulative and effectively irreversible; one bad attestation permanently welds two work items, which inverts the fail-closed contract that v1.39.0 established.+ - Merge-base and upstream probes are unbounded git work at a fail-soft lifecycle boundary, and their absence in a detached or non-git tree silently collapses the fingerprint space.+ - The registry is mutable shared state inside a Syncthing-replicated tree, where two peers can produce conflicting unions with no arbiter.+- **Complexity**: large+- **Risk**: high++### Variant 3: Lane lease ledger replacing the freshness window outright++- **Approach**: Make the execution lane the primary durable object: each session opens a lease on a work id at `SessionStart` and releases or hands it off at the compression boundary, recorded as explicit open/handoff/close lines in the existing append-only ledger. Continuation becomes lease re-acquisition β a new session links only to a predecessor whose lease is in handed-off state and unclaimed β so `CRUTCH_LINK_WINDOW_MS` is deleted rather than demoted, and concurrency is refused because a live lease is already held rather than because two candidates tied.+- **Trade-offs**:+ - The timing crutch disappears entirely; freshness stops being a proxy for anything.+ - Concurrent lanes are structurally impossible to collapse, not merely detected and abstained on.+ - The lease lifecycle is observable and auditable in the same chained ledger, and a handoff is an explicit fact rather than an inference.+ - A crashed or SIGKILLed session leaks an open lease forever; reclaiming it needs a staleness age, which reintroduces a time window at exactly the point the variant claims to remove one.+ - Lease semantics assume a single authority over the state file, which a Syncthing-replicated vault does not provide; two peers can each believe they hold the same lease.+ - Deleting the window is an incompatible change to a resolution path that currently degrades to `flat` gracefully, and every hook must now emit a close event or continuity quietly stops working.+- **Complexity**: large+- **Risk**: medium++### Recommended: Variant 1++**Rationale**: The upstream contract's substantive claim is that exact and external identifiers always win while inference stays advisory, and Variant 1 is the only one that implements that literally β identity is declared, never derived, so the kernel adds no new inference and the ambiguity layer shipped in v1.39.0 is reused rather than re-litigated. It fits the scoping note by extending the lineage/crutch layer with two optional ledger fields and one precedence rung instead of standing up a registry subsystem, and it keeps behaviour byte-identical when the fields are absent. Variants 2 and 3 both place mutable, authority-assuming state inside a peer-replicated vault and both reintroduce the failure they set out to remove β an irreversible silent union in one case, a time-based lease reclamation in the other.++### Unit: git-aware-ingest-discovery++### Variant 1: Inline mirror inside `batch-plan.ts`++- **Approach**: Copy the hygiene scan's layering shape directly into the ingest planner: a private `buildGitScope(dirAbs)` that reads `.git/info/exclude` then the root `.gitignore`, and a per-directory `.gitignore` extension inside `collectIngestible`, stacked *under* the operator `--exclude` layer so `--exclude` always wins. Submodules are skipped by testing each candidate directory for a `.git` entry (gitlink file or directory) before recursing. Nothing outside `src/core/brain/ingest/` changes.+- **Trade-offs**:+ - Smallest blast radius: hygiene's `listScanTargets` and its golden tests are untouched, so the 910-test suite risk is confined to ingest.+ - Byte-identical no-git path falls out naturally β with no ignore files present every added layer is empty and `IgnoreScope.isEmpty` holds, so `planId` does not shift.+ - Resolves the vault-relative/root-relative base-dir mismatch locally: layers are based at `dirRel` (or the nested dir's vault-relative path), which is exactly what `IgnoreLayer.baseDir` already models.+ - Direct DRY violation against an explicit repo constraint: two near-identical `extendWithIgnoreFile` + walk implementations that must be kept in step forever, and the submodule rule then exists in only one of them.+ - Malformed-pattern warnings need a second, ingest-shaped disposition (`buildExcludeScope` throws for `--exclude`; a repo's own broken `.gitignore` line must not fail an ingest plan), so the warning policy gets invented twice.+ - Repo-root discovery is ad hoc: if `sourceDir` points at a subtree of a checked-out repo, an inline implementation either ignores the ancestor `.gitignore` files or grows its own upward walk.+- **Complexity**: small+- **Risk**: low++### Variant 2: Extract a shared git-aware discovery module under `src/core/fs/`++- **Approach**: Promote the layering logic out of `scan-repo.ts` into a sibling of `ignore.ts` β a module owning "given a repo root, produce the base `IgnoreScope`" and "given a directory, extend a scope with its `.gitignore`", plus a submodule/non-working-tree predicate, with malformed-pattern warnings returned as structured `IgnoreWarning[]` rather than printed. `scan-repo.ts` keeps its `hygiene:` stderr sink by consuming those warnings itself; `collectIngestible` consumes the same module and chooses its own disposition (structured field on the plan, or advisory-rail code). Submodule skipping lands once and both discovery paths inherit it.+- **Trade-offs**:+ - Satisfies the DRY/SOLID constraint the repo states outright, and puts the git-metadata reader next to the matcher engine it composes with, where the next consumer will look for it.+ - Submodule handling β the one net-new piece β is written, tested, and reviewed once instead of diverging between hygiene and ingest.+ - Warnings become data rather than a side effect, which fits "findings carry their data as structured fields" and lets the plan surface a broken repo `.gitignore` without printing from the kernel.+ - Touches a currently-green subsystem: hygiene's scan is behaviour-pinned by tests, so the refactor must be provably inert there before the ingest wiring is even visible.+ - Larger review surface for a change whose user-visible payoff is entirely in ingest; the hygiene diff is pure motion.+ - Forces an early decision on the base-dir contract (repo-root-relative vs. vault-relative) that both callers must agree on, rather than deferring it.+- **Complexity**: medium+- **Risk**: medium++### Variant 3: Delegate discovery to `git` itself++- **Approach**: When `isGitRepo(dirAbs)` holds, obtain the candidate file set from `git ls-files --cached --others --exclude-standard` through the existing `runGit` helper in `src/core/brain/git/reader.ts`, then filter by extension and apply the operator `--exclude` scope on top; otherwise walk as today. Git's own answer covers nested `.gitignore`, `.git/info/exclude`, `core.excludesFile`, and submodule boundaries with no reimplementation.+- **Trade-offs**:+ - Exact parity with git semantics, including the corners `ignore.ts` explicitly disclaims (it documents a subset, not `git check-ignore` parity) β no drift between what the operator sees in `git status` and what ingest picks up.+ - Submodules, sparse checkouts, and assume-unchanged entries come free; no new matcher code at all.+ - Makes a core deterministic planner depend on an external `git` binary and on user-global config (`core.excludesFile`, `~/.config/git/ignore`), so the same vault on two machines can produce different `planId`s β directly against the deterministic-kernel and no-hidden-runtime-dependency constraints.+ - A missing or failing `git` cannot silently fall back to the dot-entry walk (that is the forbidden silent-no-op), so it must surface as an explicit error, which makes ingest newly fragile on machines without git.+ - Sits awkwardly against the repo's stance that the replicated vault carries no git; a source dir under the vault that is a real checkout is an edge the current code does not otherwise assume.+ - Process-spawn cost per plan, and output parsing/quoting (`core.quotePath`) becomes a new correctness surface.+- **Complexity**: medium+- **Risk**: high++### Recommended: Variant 2++**Rationale**: The task's own framing is that both halves already exist and the work is composition β which makes duplicating the hygiene walk (Variant 1) a self-inflicted maintenance seam right where the repo's DRY constraint is loudest, especially since submodule handling is net-new and would otherwise be implemented in only one of two twins. Variant 3 buys exact git parity at the price of an external binary and user-global config inside a planner whose `planId` must be reproducible, which the deterministic-kernel constraint rules out. Variant 2 keeps discovery pure, in-process, and byte-identical when a source carries no ignore files, and the hygiene refactor it requires is inert motion pinned by existing tests rather than new behaviour.++### Unit: llm-response-shape++### Variant 1: Ingress shape gate β one shared validator, static shape table++- **Approach**: Promote the existing JSON-Schema-subset validator in `src/mcp/output-contract.ts` (`OutputSchema` / `validateOutputContract`) into a core module β named for *response shape*, not "schema", to stay clear of `schema-contracts.ts` / `schema-pack.ts` / `schema-admin.ts` β and declare one frozen shape descriptor per model-authored write path (distill claims, derived facts, dream/synthesis payloads). Each consumer site validates the agent-supplied payload against its descriptor before any normalization, replacing scattered ad-hoc coercion with a single fail-closed check that emits structured `{code, path, message}` findings. The descriptors stay deliberately shallow β required keys, primitive types, array-of-object items β so extraction recall is not squeezed by over-constraint.+- **Trade-offs**:+ - Reuses a validator that already exists and is already tested; no new dependency, no zod.+ - Removes loose parsing from three write paths in one pass, with findings carried as structured fields rather than prose.+ - Enforcement is at the boundary only β the model still generates free-form and a mismatch costs a full round trip that Open Second Brain cannot itself initiate.+ - Tightening validation can reject payloads today's callers get away with, so it needs a config key defaulting to the current tolerance to keep behaviour byte-identical when absent β which means the strict path ships dormant until an operator opts in.+ - The subset validator is intentionally small; a shape needing conditionals or unions has nowhere to go without growing it.+- **Complexity**: small+- **Risk**: low++### Variant 2: Generalize the write-session contract loop to every model-authored payload++- **Approach**: `src/core/brain/write-session/` already implements the full pattern the upstream PR is reaching for β a session holding a declared target and `schemaType`, fail-closed validation, machine-readable errors, and a correction prompt derived from the error list so the agent resubmits the whole artifact. Extract that open β submit β validate β correct β commit engine into a payload-shape-agnostic primitive and route distillation, fact derivation, and dream synthesis through it, each registering its own shape descriptor and reserved-target policy. A bad response then becomes a *retryable session state* with an operator-visible attempt record, not a silent parse degradation.+- **Trade-offs**:+ - Highest fidelity to the goal: a malformed response is caught, named, and given an explicit exit, which matches the no-dead-ends and no-silent-fallback conventions directly.+ - Reuses an engine already proven on the riskiest write path rather than inventing a parallel mechanism β strong DRY win, and one correction-prompt derivation instead of three.+ - Turns three currently stateless single-shot calls into stateful multi-step ones: session records, TTLs, abandonment, idempotency, and the audit trail all multiply.+ - Changes the shape of existing CLI and MCP surfaces for `brain_distill_source` / `brain_derive_fact` / `brain_dream`; keeping them compatible means running both the direct and session forms, which is duplicated surface, not less.+ - Largest test surface: the session engine's failure matrix has to be re-verified per new consumer.+- **Complexity**: large+- **Risk**: medium++### Variant 3: Two-sided contract β publish shape descriptors outward, verify on return++- **Approach**: Keep the kernel model-free and instead make each write path's expected response shape a *first-class published artifact*: exposed in MCP tool metadata and capabilities, printable from the command line, and stable enough for the calling harness (Claude, Hermes routing) to feed straight into its own native structured-output mechanism. Open Second Brain then runs a thin ingress verification of the same descriptor on the returned payload, so constrained generation happens where the model actually lives and validation happens where the vault write happens.+- **Trade-offs**:+ - The only variant that gets genuine *constrained generation* rather than post-hoc rejection, without the kernel ever issuing a model call.+ - Descriptors become versioned public contract, which is exactly what makes the auto-memory extraction follow-on (`t_1dace26d`) cheap to add β it registers a descriptor instead of a parser.+ - Effectiveness is contingent on caller cooperation; a harness that ignores the published descriptor gets no benefit beyond Variant 1's rejection, so the win is unevenly distributed across clients.+ - Publishing descriptors on MCP tool metadata expands a surface that is already covered by `registry-guard.ts` and the preview-budget rules β schema growth there has token cost on every session.+ - Two enforcement points can drift; the descriptor must have exactly one definition with both the published form and the validator derived from it.+- **Complexity**: medium+- **Risk**: medium++### Recommended: Variant 1++**Rationale**: The kernel issues no model calls, so the real defect here is loose parsing at the ingress of agent-supplied payloads, and Variant 1 fixes exactly that with a validator the repository already owns β no new dependency, no zod, no surface change, and a config key that keeps behaviour byte-identical when absent. Variant 2's session loop is the correct end state but pays large structural cost up front for three call sites that are single-shot today, and Variant 3's outward publication is only worth the versioned-contract burden once the descriptors have proven stable in practice. Variant 1 is also the strict prerequisite that makes the other two cheap later: it establishes the single shape-descriptor definition and the distinct naming (response *shape*, never *schema*) that both would build on.++### Unit: marker-kinds-fact-skill++### Variant 1: Two kinds on the existing grammar, existing entry points only++- **Approach**: Extend `MarkerKind` with `fact` and `skill`, add their rows to `KNOWN_KINDS` and `REQUIRED_FIELDS` (`fact`: topic + principle + premises; `skill`: name + trigger + procedure), and add two narrowing type guards beside `isFeedbackMarker`. Routing reuses stores that already carry a review gate: a `fact` marker lands as an unconfirmed preference via the `derive-fact` path (premise validation stays fail-closed, so an unresolvable premise is an explicit error, not a silent drop), a `skill` marker lands in the **pending** skill-proposal store with a marker-sourced pattern kind, never in accepted. Answer to the open question is "no": `o2b brain scan-inline --path <dir>` already lets an operator point the scan at a chosen subtree, and the source bundle stays inside the vault.+- **Trade-offs**:+ - Pro: no second grammar, no new entry point, no new trust boundary β the fence-awareness, sentinel idempotence, dedup-hash and rewrite machinery apply to the new kinds for free.+ - Pro: absent markers, behaviour is byte-identical; the two kinds are purely additive to a table.+ - Pro: reviewability comes from the destination stores (unconfirmed preference, pending proposal), not from new gating code.+ - Pro: `skill` proposals seeded by marker need a `SkillProposalPatternKind` value; adding a marker-provenance kind touches the verifier's assumptions about pattern evidence.+ - Con: does not satisfy the article's literal "arbitrary source bundle" β plain text living outside the vault must first be copied in.+ - Con: `fact` and `skill` payloads are richer than `topic=β¦`-style scalars; multi-line procedures effectively force the block shape, so the inline shape is second-class for `skill`.+- **Complexity**: small+- **Risk**: low++### Variant 2: Two kinds plus a read-only external source-bundle verb++- **Approach**: Variant 1, plus a new deterministic verb (`o2b brain scan-source <file>`) that runs `discoverMarkersDetailed` over an operator-supplied path outside the vault and reports every marker with its parse verdict. Default is report-only: no signal write, no source rewrite, because the file is outside the replicated tree and `ensureInsideVault` cannot cover it; an explicit `--import` flag copies the discovered markers into `Brain/inbox/` while leaving the external file untouched (idempotence then rests on the dedup hash alone, not on the consumed sentinel).+- **Trade-offs**:+ - Pro: matches the article's workflow exactly β a bundle authored by another tool is exercised end to end with zero model calls.+ - Pro: strong fixture and demo surface: one file, one command, structured per-marker verdicts suitable for golden tests.+ - Pro: gives cross-tool authoring a real seam without a Model Context Protocol round trip.+ - Con: introduces the first read path outside the vault root, which is a genuine new trust boundary against the path-safety invariant, and needs its own size/symlink/encoding limits.+ - Con: without in-file rewrite, re-running `--import` over the same bundle relies entirely on dedup hashing; any hash-relevant field change silently re-imports as new.+ - Con: a new verb means a new registered diagnostic code family for its failures and a new command-line surface to keep stable.+- **Complexity**: medium+- **Risk**: medium++### Variant 3: New kinds route into the staged dream proposal bundle++- **Approach**: Add the two kinds as in Variant 1, but do not let them write to their final stores. Marker discovery becomes an input to `dream stage`: `fact` and `skill` markers flatten into `proposals.jsonl` as new proposal types (`create_derived_fact`, `create_skill_proposal`) alongside the existing `create_preference` rows, and are only materialised when the operator applies the bundle. The staged report renders them in their own sections, and discard drops them with the rest of the bundle.+- **Trade-offs**:+ - Pro: closest to the article's actual thesis β reviewable self-improvement, with a single uniform review point rather than one per destination store.+ - Pro: one place to validate premises and skill shape, so the skill verifier is never handed a marker-seeded candidate it has no pattern evidence for.+ - Pro: the persisted bundle is already the deterministic artifact tests assert against, so fixtures get stronger with no new file format.+ - Con: widens `planToProposals` and the plan type beyond preference/signal lifecycle, which is the largest conceptual change of the three.+ - Con: markers now have two different fates depending on kind (feedback writes a signal immediately, fact/skill waits for an apply), which is a real asymmetry operators must learn.+ - Con: plan-drift detection between stage and apply must be extended to cover the new rows, or a bundle can be applied against source files that have since changed.+- **Complexity**: medium to large+- **Risk**: medium++### Recommended: Variant 1++**Rationale**: The open question resolves to "no" β `scan-inline --path` and `apply-markers --path` already give an operator marker discovery over a chosen subtree, and reading source files outside the vault would breach the path-safety invariant for a convenience the operator can get by placing the bundle in the vault, so Variant 2's cost buys little. Variant 3 solves a review problem that is already solved by the destination stores: a marker-seeded fact becomes an *unconfirmed* preference that the dream pass gates, and a marker-seeded skill lands in the *pending* proposal store that already has accept/reject, so routing them through the stage bundle duplicates gating rather than adding it. Variant 1 keeps the change to two rows in `REQUIRED_FIELDS`, two type guards and their routing, which is byte-identical when the markers are absent and is exactly the narrow delta the re-verification identified.++### Unit: query-temporal-intent++### Variant 1: Temporal intent at the query-plan seam, modulating `recencyMul` only+- **Approach**: Extend `src/core/search/query-plan.ts` with a new structural `temporal` intent, detected only from signals that survive the language-agnostic invariant β ISO tokens in the query text (reusing `extractTemporalConstraints`) and the existing `<field>:<value>` grammar (`since:`/`until:`). The plan resolves a target window and, when that window's midpoint is materially older than `now`, emits a `WeightProfile` with `recencyMul` below 1 (down to 0 for an explicitly historical query); a near-now window amplifies it. Nothing in `ranker.ts` changes β `recency * recMul` at ranker.ts:416 is already the modulation point.+- **Trade-offs**:+ - Smallest possible diff: one detector, one profile row, zero new scoring layers, zero new `ScoreBreakdown` fields, no MCP surface change.+ - `planHash` already feeds the query cache, so cache correctness comes for free.+ - Bounded by construction β the existing `[0.7, 1.4]` profile discipline means a misdetection can only re-weight, never float an unrelated document.+ - Only suppresses or amplifies; it cannot *promote* documents inside the target window, so "what did I decide back in spring?" stops being actively hurt but is not actively helped.+ - Overloads a single scalar with two distinct meanings (freshness prior strength vs. temporal-intent direction), which makes the `reasons` output harder to read: a suppressed recency layer just silently disappears.+ - `WeightProfile` is currently a per-intent constant table; a window-derived continuous `recencyMul` breaks that table's "fixed structural-feature β profile" property.+- **Complexity**: small+- **Risk**: low++### Variant 2: Anchor-shifted Weibull β recency measured from the query window, not from `now`+- **Approach**: Keep one recency layer but make its reference instant query-derived: the plan resolves a target window and `search.ts` threads an optional `recencyAnchorMs` (or the resolved window) into `RankerOptions`, so `recencyBoost` computes age as distance from the *window edge* rather than from `now`. Absent an anchor the age is `now - mtime` exactly as today, so ranking stays byte-identical; with an anchor, the same Weibull curve becomes a soft two-sided band centred on the queried period.+- **Trade-offs**:+ - Conceptually the most faithful reading of "window-shift the recency layer": one curve, one tuning surface, `recencyShape`/`recencyScale`/`recencyAmplitude` keep their meaning, and `recencyAmplitude: 0` remains the documented global off switch.+ - No new score component, no new breakdown field, no growth in the explain payload.+ - Changes the semantics of `weibullDecay`'s only input from "age" to "distance", which currently has a documented one-sided contract (`ageDays <= 0`, including future timestamps, returns full amplitude). Making it two-sided touches the most-depended-upon and most-tested primitive in the ranking stack.+ - The `recency: 0.041` reason string silently changes meaning per query, and downstream consumers (`feedback.ts`, MCP `explain`, tuning/eval gates, the semantic-health baseline watermark) compare recency across queries β a shifted anchor makes those series non-comparable without a marker field.+ - Fights the existing tie-break, which sorts by `mtime` descending: an older in-window document can win on score and then lose the tie-break to a newer out-of-window one.+- **Complexity**: medium+- **Risk**: high++### Variant 3: Detection at the plan seam + a separate capped `temporal_match` layer+- **Approach**: Same detection front half as Variant 1 (ISO tokens plus structured field tokens, resolved through `time-range.ts` into a `ResolvedTimeRange`), but the ranker consumes it as its own bounded additive layer rather than as a recency multiplier: reuse the already-pure `temporalProximity` from `temporal-bridge.ts` over a per-candidate event time (validity start, else `mtime`) to produce a capped boost, alongside a modest `recencyMul` damping when the window is historical. It follows the exact shape every other layer in `rankResults` uses β optional input map, absent map contributes zero, one `reasons` entry, one `ScoreBreakdown` field.+- **Trade-offs**:+ - Handles both halves of the problem: suppresses the wrong-direction freshness prior *and* promotes documents that actually sit in the queried window, which is the whole point of the upstream signal.+ - Reuses two already-written, already-tested pure functions (`temporalProximity`, `parseTimePoint`) and the existing event-time resolver `search.ts` already builds for the temporal bridge β very little genuinely new math.+ - Freshness prior and temporal intent stay separately observable in `reasons`/`breakdown`, so tuning, eval gates, and the `explain` projection can attribute a ranking change to the right layer.+ - Soft window match complements β rather than duplicates β the existing hard `since`/`until` filter: a query-text-derived window biases without excluding, which is the safer default for an inferred signal.+ - Widest blast radius of the three: a new `ScoreBreakdown` key (additive, but it is an MCP-visible shape), new plumbing through `search.ts`, and a new capped constant that must be calibrated against the link/entity/activation/reuse caps so the layers stay in proportion.+ - Requires an event-time map for the full candidate pool, not just link expansions β more store work per query than either alternative.+ - Two knobs move at once (new boost plus recency damping), so an A/B on retrieval quality needs both isolated.+- **Complexity**: medium+- **Risk**: medium++### Recommended: Variant 3+**Rationale**: It is the only variant that delivers the actual upstream capability β biasing *toward* the queried window β rather than merely stopping the freshness prior from hurting, and it does so in the exact idiom the ranker already uses (optional input map, capped additive boost, absent map β byte-identical ranking), so the "every new key leaves behaviour byte-identical when absent" constraint is satisfied structurally rather than by care. Variant 2 buys elegance by mutating `weibullDecay`'s contract and silently redefining the `recency` component that tuning, feedback, and eval gates already track across queries, which is a disproportionate regression surface for an enhancement-priority item. Variant 1 is the cheapest and is a legitimate fallback if scope must shrink, but it leaves the motivating "what did I decide back in spring?" case only half-served; note that under this repo's language-agnostic rule, *all three* variants must detect intent from ISO tokens and structured field tokens only β the "last week"/"recently" natural-language detection Signet performs is not portable here and should not be attempted.++### Unit: recurring-weak-recall-obligation++### Variant 1: Verdict-stamped demand log, dream-phase minting into obligations+- **Approach**: Solve question identity by reusing the bucket key `query-demand.ts` already owns β sorted significant terms (`normalizeQueryTerms`, IDF-derived, redacted, capped), never a word list β by adding an optional `adequacy` level to `QueryDemandRecord` and stamping it from the two existing verdict sites (`brain_recall_gate`, `brain_context_pack`). A new dream phase aggregates buckets whose weak/insufficient count clears a demand threshold, ranks by the existing `demandScore`, and mints at most top-N obligations via `addObligation` with a slug hashed from the bucket key and a re-check cadence, deduped through `obligationExists`. Session-start renders open obligations of that kind as the agenda, and the dream phase completes an obligation once the same bucket recalls `sufficient`.+- **Trade-offs**:+ - Pro: no new store, no new key concept β compaction, byte caps, secret-shaped-term dropping, and `[since, until]` filtering are inherited, not rebuilt.+ - Pro: minting is off the recall hot path; the dream pass is where the project already puts gated batch promotion, and caps are naturally per-run rather than per-attempt.+ - Pro: matches the brief's explicit "mint an obligation, not a board item" scoping without touching `agenda.ts`.+ - Con: couples two features β a demand record now also carries a retrieval verdict, so `query-demand.ts` stops being purely about coverage.+ - Con: obligations are cadence-bearing by construction; a one-shot "write coverage for this topic" is an awkward fit, and the re-check cadence is a semantic stretch that needs justifying.+ - Con: nothing happens until dream runs β the loop closes on a schedule the operator may not run, and a never-dreaming vault silently accumulates nothing.+ - Con: `demandScore` was tuned for coverage-driven ranking; reusing it as the mint trigger imports a threshold that was never validated for this purpose.+- **Complexity**: medium+- **Risk**: medium++### Variant 2: Second signal source into the existing gap loop, gap-task as the durable item+- **Approach**: Emit each adequacy verdict as a gated continuity record through `emitGatedTelemetry`, carrying the bucket key computed by the shared `normalizeQueryTerms` pure function so no new identity logic is invented. Generalize `gaps/gap-loop.ts` `detectRecurringGaps` to aggregate over both its current structural `gap_counts` source and the new verdict records, leaving promotion (`promoteGapsToTasks`, exclusive-create dedupe on `gapTaskKey`), the session-start agenda (`renderGapAgenda`), and auto-close (`autoCloseRecalledGaps`, with the self-close guard) exactly as built. Wire the currently dormant module into the session-start/session-end hooks behind the existing `gap_loop_enabled` / `gap_loop_threshold` keys.+- **Trade-offs**:+ - Pro: the promotion β agenda β auto-close half is already implemented and tested; this variant adds a signal source and hook wiring rather than a second copy of the same machinery.+ - Pro: auto-close is what makes the item *bounded* β a minted item that resolves itself when coverage appears is the difference between a tracked obligation and vault litter; only gap-loop has it today.+ - Pro: telemetry rides the continuity rail as convention requires (config-gated, fail-open, redaction-passing), and the agenda surface is one that was purpose-built for recall gaps.+ - Con: deviates from the brief's stated target β obligations get no use, and the vault gains recall-driven items in `Brain/gap-tasks/` instead of `Brain/obligations/`.+ - Con: scope grows beyond the feature: this variant must also wire a dormant module, so a bug there surfaces as a regression in this release.+ - Con: mixing a coarse structural code bucket (`no_matching_context`) and a fine term bucket in one aggregate makes `occurrences` mean two different things across rows in the same agenda.+ - Con: leaves the repo with two candidate durable-item kinds; if obligations later become the convention, this needs a migration.+- **Complexity**: medium+- **Risk**: low++### Variant 3: Structural retrieval-neighborhood fingerprint, no query text at all+- **Approach**: Define question identity with zero natural-language input β hash the ordered top-artifact id set from the `recall_telemetry` `top_artifacts` payload into a "weak neighborhood" fingerprint, falling back to the registered structural gap code when the attempt returned nothing. Aggregate directly over `recall_telemetry` continuity records already on disk, so the feature works retroactively over existing history with no new store and no new emitted field, and mint one obligation per neighborhood that clears both an occurrence and an escalation threshold.+- **Trade-offs**:+ - Pro: the strictest possible reading of the language-agnostic rule β the key never touches prompt text, so it cannot be argued into a word list later.+ - Pro: no new persistence, no new write path, and no change to the two verdict call sites; retroactive over telemetry already captured.+ - Con: the fingerprint is unstable β one different artifact in top-k forks the bucket, so demand fragments across near-identical questions and the threshold rarely clears at all.+ - Con: the zero-result case is the one that matters most and has no artifacts, so it collapses onto a handful of coarse gap codes and over-aggregates unrelated questions into a single obligation.+ - Con: making it work needs quantization or set-similarity tuning β a new knob class the project deliberately avoids, and one that cannot be validated without a corpus.+ - Con: builds a third recurrence-key concept alongside the two the repo already has, with no reuse of the redaction and cap work.+- **Complexity**: large+- **Risk**: high++### Recommended: Variant 2+**Rationale**: The genuinely missing piece is only the aggregation link β `query-demand.ts` already solved deterministic, language-agnostic question identity and `gaps/gap-loop.ts` already implements promotion, the session-start agenda, and the auto-close that makes a minted item bounded rather than permanent litter, so this variant adds a signal source and hook wiring instead of a second copy of that machinery. It also gives the caps their teeth: an item that closes itself when recall recovers is a stronger guard against one bad afternoon than any mint threshold. The one deliberate deviation is the durable target β this mints a gap-task, not an obligation; that still satisfies the actual constraint the validator was protecting (stay internal, never write to an external board), but it contradicts the brief's literal instruction and should be confirmed before implementation, since Variant 1 is the ready alternative if obligations must be the artifact.++### Unit: route-discriminator++### Variant 1: In-router discriminator ladder on a candidate-score table++- **Approach**: Keep `routeExtractedFacts` as the single write router, but split its decision into two explicit pure functions: `scoreRouteCandidates(fact, ctx)` returning a frozen, deterministically-ordered `{ route, score }[]` built from the structural features already available (family-pattern match length, span coverage of the line, overlap with a URL range, entity-anchor count, durability signal set, dedup history for the hash), and `discriminate(candidates)` which fires only when `top.score - second.score <= MARGIN`. The discriminator is a fixed, ordered ladder of registered rules, each a pure structural predicate with a stable id (`overlap-containment`, `anchor-majority`, `span-coverage`, `family-table-order` as the terminal always-decides rule); the first rule that separates the tied candidates wins and its id is recorded. Every discrimination emits one `route_discrimination` continuity record through `emitGatedTelemetry` behind a new config key, carrying the candidate set, scores, margin, winning route, and the rule id β never the fact text.+- **Trade-offs**:+ - Pro: touches one call site; the existing dedup β durability β staging β write chain is unchanged, and with the gate key absent behaviour is byte-identical because the terminal rule reproduces today's family-table order.+ - Pro: fully deterministic and word-list-free β every feature is a count, an offset, or a set membership, so it behaves identically across scripts.+ - Pro: rule ids make tie-breaks auditable and tunable; `MARGIN` is one named constant, and misroute rates become measurable per rule.+ - Pro: no new public CLI/MCP surface required to ship the mechanism; the reader can follow later.+ - Con: the score table is bespoke to the extracted-facts router; a second write path (preference vs note vs pinned) would need its own copy unless it is generalised later.+ - Con: score weights are a tuning surface with no ground truth on day one β early records will mostly confirm the terminal rule fires, which looks like low value until data accumulates.+ - Con: adds a second decision point to a hot capture path, so the ladder must stay allocation-cheap.+- **Complexity**: medium+- **Risk**: low++### Variant 2: Extracted two-stage routing kernel shared by all write surfaces++- **Approach**: Introduce `src/core/brain/routing/` holding a route-agnostic kernel β a `RouteCandidate` type, a `CandidateScorer` interface, a `Discriminator` registry keyed by stable id, and a `resolveRoute()` driver that runs primary scoring, detects near-equality, applies the registry in registration order, and emits the gated `route_discrimination` record once for every write surface. `routeExtractedFacts` becomes the first consumer by supplying a fact-specific scorer; the signal/preference/note/pinned writer entry points become subsequent consumers with their own scorers over the same kernel, so the tie-break record shape is identical regardless of which write path produced it.+- **Trade-offs**:+ - Pro: DRY across the whole write surface β the misfiled-write problem the task names is not confined to extracted facts, and this is the only variant that addresses signal-vs-obligation and note-vs-decision ambiguity in the same mechanism.+ - Pro: one telemetry schema, one config gate, one advisory-rail code family for every routed write; `dream` gets a uniform reconciliation input.+ - Pro: the registry makes the discriminator set inspectable and testable independently of any router.+ - Con: largest blast radius β it re-plumbs write paths that currently have no ambiguity problem proven against them, and the writer MCP tools are an existing public surface that must stay compatible.+ - Con: the abstraction is being designed from exactly one concrete consumer, so the scorer interface risks being shaped wrong and rewritten at the second adopter.+ - Con: significant test surface across many existing writer tests before any behaviour improves.+- **Complexity**: large+- **Risk**: medium++### Variant 3: Ambiguity as its own route β quarantine plus a registered advisory exit++- **Approach**: Compute the same candidate score table, but when the top candidates are within the margin, do not pick a winner: route the fact to an explicit ambiguous lane (reusing the existing `Brain/pending/` staging machinery already wired through `writeApprovalEnabled` and `brainDirsForWrite`), record the full candidate set on the staged item, and surface a registered advisory-rail code so the operator or `dream` resolves it. The tie-break rules exist only as ranking hints presented alongside the candidates, never as an autonomous decision, and the gated `route_discrimination` record captures both the candidate set and the eventual resolution when it lands.+- **Trade-offs**:+ - Pro: strictly honest β an ambiguous write is never silently guessed, and it fits the v1.40.0 "every diagnosis names its exit" precedent directly, since ambiguity is exactly a state that needs a named exit.+ - Pro: reuses `Brain/pending/` rather than inventing a lane; the resolution events become ground-truth training data for the score table a later variant would need.+ - Pro: zero risk of a wrong automated tie-break, since there is no automated tie-break.+ - Con: does not actually cut the misfiled-write rate β it converts misfiles into operator queue depth, moving the cost rather than removing it, and the task's stated value is reducing what `dream` must reconcile.+ - Con: a low margin threshold floods the pending lane; a high one makes the whole stage inert, and there is no data yet to pick between them.+ - Con: requires a resolution surface (CLI or MCP) to drain the lane, or the quarantine is a leak.+- **Complexity**: medium+- **Risk**: medium++### Recommended: Variant 1++**Rationale**: It delivers the actual deliverable β a deterministic, auditable tie-break with its own gated emission β against the one router the corrected hints anchor to, without re-plumbing write paths whose ambiguity is still hypothetical, and the terminal `family-table-order` rule guarantees byte-identical behaviour when the gate key is absent as the conventions require. Variant 2 designs a cross-surface abstraction from a single consumer and would very likely be rewritten at the second one; the kernel is the right eventual shape, but only after Variant 1's records show what the scorer interface actually needs. Variant 3 answers a different question (who resolves ambiguity) rather than the one asked (how routing disambiguates), and its quarantine lane is best added later as a bounded escalation when Variant 1's telemetry shows a margin band the ladder genuinely cannot separate.++### Unit: unroutable-capture-hint++### Variant 1: Extend the existing write-advisory seam with a scope-routing hint+- **Approach**: Add a sibling of `adviseIncomingFeedback` in `src/core/brain/write-advisory.ts` that runs on the same operator-facing feedback path (CLI `o2b brain feedback` and MCP `brain_feedback`), after the write has landed. When the effective scope resolves to `undefined` (no `--scope`, no `feedback.default_scope`), it returns a structured `routing_hint` naming the missing signal (`scope`) plus the eligible scope slugs observed in the vault β the distinct `scope` values on confirmed preferences and recent signals, ranked by document frequency. An empty candidate set yields `null` (the absent case, exactly like the conflict advisory), so a fresh personal vault stays silent; the human path prints its forward pointer through `emitNextStep` against one newly registered `DIAGNOSTIC_SIGNALS` code.+- **Trade-offs**:+ - Reuses a proven, tested precedent for "non-blocking, computed around the write, surfaced as a structured field and logged" β the shape the triage note asked for, with no new mechanism.+ - No new configuration key, so the "byte-identical when absent" rule is satisfied by construction: an unscoped write on a vault with no scope corpus behaves exactly as today.+ - Eligible scopes come from vault frontmatter and frequency, not from any word list, so the language-agnostic rule holds.+ - Touches only two call sites that already thread `effectiveScope`; `routeExtractedFacts` is untouched, preserving the existing "advisory never double-fires on the extracted-fact path" invariant.+ - Covers only the feedback surface. Anchor-less extracted facts and note captures remain unhinted, so the "unrouted note" problem is addressed for one write family, not all of them.+ - Inferring eligibility from corpus frequency means the candidate list drifts with vault contents and can surface a scope the operator considers retired.+ - Needs one registered diagnostic code whose `nextCommand` must be a structural string; the honest exit is re-recording with `--scope` or setting `feedback.default_scope`, so the registry entry has to name a real command rather than a paraphrase.+- **Complexity**: small+- **Risk**: low++### Variant 2: Declared scope registry in Brain config+- **Approach**: Widen the existing `feedback:` config block from a single `default_scope` into a declared registry of eligible scopes (each with the slug it routes to), mirroring upstream's "covers-declaring scopes are registered" model. A scope-less write consults the registry and returns a hint naming the missing routing signal and the registered scopes it could have carried; with no registry declared, the hint never fires and the path stays byte-identical. Validation lives in `policy.ts` beside the existing `feedback.default_scope` rules, sharing the same slug constraints.+- **Trade-offs**:+ - Highest fidelity to the upstream feature: eligibility is declared by the operator rather than guessed, so the hint never names a stale or accidental scope.+ - Silent by default on personal installs, which matches upstream behaviour and satisfies the additive-configuration rule cleanly.+ - Gives the vault an explicit routing vocabulary that later surfaces (hygiene, dream, active-pack scoping) could reuse, so the investment is not single-purpose.+ - Requires the operator to configure something before the feature does anything, which is the opposite of the "reduce unrouted notes" goal for the users most likely to have them β the ones who never configured scopes.+ - Adds config schema, validation, template, and documentation surface for a hint, which is a large ratio of mechanism to payoff.+ - Two sources of truth for what a valid scope is (declared registry versus scopes already on disk) invites drift and a new doctor check to reconcile them.+- **Complexity**: medium+- **Risk**: medium++### Variant 3: Cross-surface capture-routability seam+- **Approach**: Introduce one routability module that every capture write funnels through, modelling "missing routing signal" as a small closed set of families: a scope-less feedback signal, an extracted fact that resolved no canonical entity anchor, and a captured note with no anchor or scope. Each family declares its missing-signal token and its candidate resolver, each maps to its own registered diagnostic code, and the aggregate is emitted through `emitGatedTelemetry` so unrouted-capture rates become observable alongside the existing route metrics.+- **Trade-offs**:+ - Addresses the actual retrieval-noise problem end to end: anchor-less extracted facts are the larger unrouted population, and they are exactly what Variant 1 leaves out.+ - One model for "unroutable capture" instead of a per-surface advisory, which is the DRY answer if more capture surfaces arrive later.+ - Telemetry makes the effect measurable rather than asserted, matching how this codebase already treats recall and route quality.+ - `routeExtractedFacts` runs per fact inside the capture hot path; adding a candidate-resolution step there risks turning a bounded loop into a per-fact vault read unless results are hoisted, and that path is already carefully budgeted.+ - Breaks the documented invariant that the advisory fires only on the operator-facing feedback path, so the double-fire question has to be re-answered rather than inherited.+ - Largest blast radius across capture, MCP, CLI, and telemetry for a feature whose user-visible output is one hint line; several hundred existing capture tests sit downstream of these seams.+- **Complexity**: large+- **Risk**: medium++### Recommended: Variant 1+**Rationale**: The transferable half of the upstream feature is the shape β a non-blocking hint that names the missing routing signal β and `write-advisory.ts` already implements that shape on the same path, with the same fail-soft, never-blocks-the-write contract and the same structured-field-plus-log surfacing, so the work is an extension rather than a new mechanism. It needs no new configuration key and no change to the extracted-fact hot path, which keeps the "byte-identical when absent" and capture-performance constraints trivially satisfied, and it resolves its forward pointer through the registered advisory rail as the v1.40.0 convention requires. Variant 2 asks the operator to configure their way into the benefit they lack, and Variant 3 spends a large refactor across the hottest capture seam before the smaller version has demonstrated that the hint changes behaviour.+diff --git a/docs/cli-reference.md b/docs/cli-reference.mdindex e2eb7e11..f38f80bf 100644--- a/docs/cli-reference.md+++ b/docs/cli-reference.md@@ -277,7 +277,7 @@ Supersession is now consumer-aware: context packs inject only the tip of a super### Source pipeline integrity and operator tooling (since v1.34.0)```text-o2b brain batch-plan gains --src-subpath <rel> (scope a monorepo ingest to one subtree; escaping the source root is a typed error), --exclude <pattern> (gitignore-style patterns through the shared ignore engine), and --reconcile (diff the plan's dispatched set against checkpoint completions and name every silently-lost source; a complete plan reports an explicit empty gap)+o2b brain batch-plan gains --src-subpath <rel> (scope a monorepo ingest to one subtree; escaping the source root is a typed error, and one crossing a submodule or nested checkout is refused outright; a subpath below a directory the repository itself ignores plans nothing and says so as an ignore warning), --exclude <pattern> (gitignore-style patterns through the shared ignore engine), and --reconcile (diff the plan's dispatched set against checkpoint completions and name every silently-lost source; a complete plan reports an explicit empty gap)o2b brain pre-extract <file> [--json] - deterministic no-LLM code-structure extraction (classes, functions, imports, inheritance edges as JSON entity/edge seeds) for TypeScript, JavaScript, and Python; unknown extensions report extracted:false with a reason, never an empty successo2b brain scan-citations [--strict] - promote structural [Source: <name>, YYYY-MM-DD] markers in note prose into dated source-citation events on the temporal timeline; dedup on normalized name + date, malformed markers are reported and skipped (--strict exits nonzero on them)o2b brain doctor gains --repair (preview targeted fixes for doctor-detected classes: dangling workrun checkpoints, dead evidence links; dry-run default) and --repair --apply (perform the fixes idempotently, one typed doctor-repair event each); unfixable classes are reported needs-review; plain doctor and --strict stay read-only@@ -295,6 +295,23 @@ reported with a reason (an empty allowlist changes nothing). Both `o2b` and`vault-log` treat an early-closed stdout pipe (`o2b ... | head`) as a cleanexit 0, while any other stdout error now fails loudly.+Ingest discovery applies the repository's own declarations to+`--src-subpath` as well: the planner descends from the source directory to+the subpath root and layers each intermediate directory's `.gitignore` on+the way, so a scoped plan answers the same about a tree as an unscoped one.+A subpath that starts below a directory the repository ignores is not+walked: the plan is empty and carries an ignore warning whose source is+`--src-subpath`, naming the ignored directory and pointing at the `--exclude`+`!` re-include that opens it. A subpath that crosses a submodule or nested+checkout is refused with an error naming the boundary directory instead:+those files belong to that repository, no `--exclude` pattern can re-open a+boundary, and the error says to plan against that repository directly.+Ignore warnings print beneath the plan on the human surface and travel as+the `ignore_warnings` array (`source`, `line`, `pattern`, `reason` per entry)+under `--json`; `line` is 0 for a warning about no single pattern line,+which covers both a `--src-subpath` warning and an ignore file that could+not be read.+### Trusted recall and memory write surface (since v1.35.0)```textdiff --git a/docs/mcp.md b/docs/mcp.mdindex 650cbce2..09b9e852 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -651,3 +651,24 @@ Both servers reuse the same backing CLI (`o2b mcp --scope writer` vs the default`ingest_dedup` continuity records into a trend. The counts are exact-hashdrops only; the semantic layers nominate candidates and never drop, sonothing in this view may be read as a semantic discard.+- Since v1.41.0 `brain_ingest_batch_plan` scopes `src_subpath` by the+ repository's own declarations, so a scoped plan answers the same about a+ tree as an unscoped one. Beyond the existing typed error for a value+ escaping the source root, two refusals are reachable. A `src_subpath` that+ crosses a submodule or nested checkout is refused with an error naming+ the boundary directory: those files belong to that repository, no `exclude`+ pattern can re-open a boundary, and the error says to plan against that+ repository directly. A `src_subpath` that starts below a directory the+ repository ignores is not walked: the plan returns no batches and carries+ an `ignore_warnings` entry whose `source` is `--src-subpath`, naming the+ ignored directory and the `exclude` `!` re-include that opens it.+- Since v1.41.0 a batch plan carries `ignore_warnings` whenever the walk+ could not apply something as declared: a malformed pattern in one of the+ repository's own ignore files, an ignore file that exists but could not be+ read, or the `--src-subpath` case above. Each entry carries `source`,+ `line`, `pattern`, and `reason`; `line` is 0 for a warning that concerns no+ single pattern line. The key is absent when there is nothing to report, so+ a tree that declares no ignore files serializes exactly as before. None of+ these warnings fails the plan - the repository is an input, not operator+ intent - while a malformed operator `exclude` pattern still fails the call,+ naming the pattern and the reason it would not compile.diff --git a/hooks/gap-promote.ts b/hooks/gap-promote.tsindex e7340290..88e88a6a 100644--- a/hooks/gap-promote.ts+++ b/hooks/gap-promote.ts@@ -76,6 +76,11 @@ async function main(): Promise<void> {auditRun(vault, {promoted: promotion.created.length,skipped: promotion.skipped.length,+ // Both bounds the run enforces are reported, never dropped: a pruned+ // count explains a shrinking directory, and a non-zero cap refusal is+ // the operator's only signal that gap tasks are being turned away.+ pruned: promotion.pruned.length,+ capped: promotion.capped,closed: closure.closed.length,kept: closure.kept.length,});diff --git a/openclaw.plugin.json b/openclaw.plugin.jsonindex 77a41a35..ec13315c 100644--- a/openclaw.plugin.json+++ b/openclaw.plugin.json@@ -2,7 +2,7 @@"id": "open-second-brain","name": "Open Second Brain","description": "Second brain for AI agents using Obsidian-compatible Markdown vaults.",- "version": "1.40.0",+ "version": "1.41.0","activation": { "onStartup": true },"skills": ["./skills"],"contracts": {diff --git a/package.json b/package.jsonindex ac57bdfd..29c4ac41 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "1.40.0",+ "version": "1.41.0","private": false,"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.","keywords": [diff --git a/plugin.yaml b/plugin.yamlindex 96e2411b..35e8e1b2 100644--- a/plugin.yaml+++ b/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "1.40.0"+version: "1.41.0"description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."author: "Open Second Brain contributors"memory_provider: truediff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.jsonindex d4fa3125..1c09daa6 100644--- a/plugins/codex/.codex-plugin/plugin.json+++ b/plugins/codex/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "1.40.0",+ "version": "1.41.0","description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.","author": {"name": "Open Second Brain contributors",diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yamlindex 96e2411b..35e8e1b2 100644--- a/plugins/hermes/plugin.yaml+++ b/plugins/hermes/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "1.40.0"+version: "1.41.0"description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."author: "Open Second Brain contributors"memory_provider: truediff --git a/pyproject.toml b/pyproject.tomlindex bd0ab564..bf2a716c 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -10,7 +10,7 @@ build-backend = "setuptools.build_meta"# CLI entry points (those moved to `package.json` `bin`).[project]name = "open-second-brain"-version = "1.40.0"+version = "1.41.0"description = "Hermes Python shim for Open Second Brain. Most of the project (CLI, MCP server, OpenClaw plugin) is TypeScript on Bun; see package.json."readme = "README.md"requires-python = ">=3.11"diff --git a/src/cli/brain/verbs/batch-plan.ts b/src/cli/brain/verbs/batch-plan.tsindex ccb396d7..41995e76 100644--- a/src/cli/brain/verbs/batch-plan.ts+++ b/src/cli/brain/verbs/batch-plan.ts@@ -12,6 +12,8 @@import { planBatches } from "../../../core/brain/ingest/batch-plan.ts";import { reconcilePlan } from "../../../core/brain/ingest/reconcile.ts";+import { formatIgnoreWarning } from "../../../core/fs/git-discovery.ts";+import { serializeBatchPlan } from "../../../mcp/brain/ingest-tools.ts";import { brainVerbContext, fail, info, ok, okJson, parse, usageError } from "../helpers.ts";/** Default caps, mirroring the MCP surface (1 MiB / 25 files per batch). */@@ -67,29 +69,9 @@ export async function cmdBrainBatchPlan(argv: string[]): Promise<number> {if (flags["json"]) {okJson({- source_dir: plan.sourceDir,- max_batch_bytes: plan.maxBatchBytes,- max_batch_files: plan.maxBatchFiles,- total_files: plan.totalFiles,- total_bytes: plan.totalBytes,- skipped: [...plan.skipped],- // Only present when the extractable gate skipped something, so the- // no-declaration output is byte-identical to before.- ...(plan.skippedNonExtractable.length > 0- ? {- skipped_non_extractable: plan.skippedNonExtractable.map((s) => ({- path: s.path,- reason: s.reason,- })),- }- : {}),- plan_id: plan.planId,- resumed_completed: plan.resumedCompleted,- batches: plan.batches.map((b) => ({- index: b.index,- total_bytes: b.totalBytes,- files: b.files.map((f) => ({ path: f.path, bytes: f.bytes, status: f.status })),- })),+ // One serializer feeds both machine surfaces (the MCP tool owns it), so+ // a field added to the plan can never reach one and miss the other.+ ...serializeBatchPlan(plan),// Only present with --reconcile, so the default output is unchanged....(report !== undefined? {@@ -123,6 +105,11 @@ export async function cmdBrainBatchPlan(argv: string[]): Promise<number> {info(` ${plan.skippedNonExtractable.length} non-extractable page(s) skipped:`);for (const s of plan.skippedNonExtractable) info(` - ${s.path} (${s.reason})`);}+ if (plan.ignoreWarnings.length > 0) {+ info(` ${plan.ignoreWarnings.length} ignore warning(s):`);+ // Same wording as the hygiene scan's stderr sink: one formatter.+ for (const w of plan.ignoreWarnings) info(` - ${formatIgnoreWarning(w)}`);+ }if (report !== undefined) {if (report.complete) {ok(` reconcile: all ${report.dispatched.length} dispatched source(s) ingested`);diff --git a/src/cli/brain/verbs/distill.ts b/src/cli/brain/verbs/distill.tsindex af7d40a5..14dea360 100644--- a/src/cli/brain/verbs/distill.ts+++ b/src/cli/brain/verbs/distill.ts@@ -15,15 +15,28 @@ import { readFileSync } from "node:fs";import {distillSource,DistillValidationError,- normalizeClaim,+ parseDistillClaims,type DistillClaim,} from "../../../core/brain/distill/distill-source.ts";+import { ResponseShapeError } from "../../../core/brain/response-shape.ts";import { brainVerbContext, fail, ok, okJson, parse, resolveBrainAgent } from "../helpers.ts";const USAGE ="usage: o2b brain distill <source> (--claims <json> | --claims-file <path>) [--vault <path>] [--json]";-/** Parse and structurally validate the claims JSON into DistillClaim[]. */+/** What `--claims` accepts, named in the operator's own terms. */+const CLAIMS_SHAPE_HINT = "claims must be a JSON array of { text, block? } objects";++/**+ * Unwrap the operator's JSON (a bare array, or an object with a `claims`+ * array) and hand it to the shared shape-checked ingress, so the CLI and the+ * MCP tool accept exactly the same payload under exactly the same rules.+ *+ * The unwrap failure is reported HERE rather than by the ingress: at this+ * point the operator's mistake is the wrapper they typed, and a path inside a+ * payload the CLI never found does not tell them what to type instead. Once a+ * list is in hand, the ingress owns every complaint about its items.+ */function parseClaims(raw: string): DistillClaim[] {let parsed: unknown;try {@@ -31,22 +44,12 @@ function parseClaims(raw: string): DistillClaim[] {} catch {throw new Error("claims must be valid JSON");}- const arr = Array.isArray(parsed)- ? parsed- : parsed !== null &&- typeof parsed === "object" &&- Array.isArray((parsed as { claims?: unknown }).claims)- ? (parsed as { claims: unknown[] }).claims- : null;- if (arr === null) {- throw new Error("claims must be a JSON array of { text, block? } objects");- }- return arr.map((item, i) => {- if (item === null || typeof item !== "object" || Array.isArray(item)) {- throw new Error(`claim ${i} must be an object with a text field`);- }- return normalizeClaim(item as Record<string, unknown>);- });+ const payload =+ !Array.isArray(parsed) && parsed !== null && typeof parsed === "object"+ ? (parsed as { claims?: unknown }).claims+ : parsed;+ if (!Array.isArray(payload)) throw new Error(CLAIMS_SHAPE_HINT);+ return parseDistillClaims(payload);}export async function cmdBrainDistill(argv: string[]): Promise<number> {@@ -97,7 +100,7 @@ export async function cmdBrainDistill(argv: string[]): Promise<number> {);return 0;} catch (err) {- if (err instanceof DistillValidationError) {+ if (err instanceof DistillValidationError || err instanceof ResponseShapeError) {return fail(`distill: ${err.message}`);}return fail(`distill failed: ${(err as Error).message ?? err}`);diff --git a/src/cli/brain/verbs/feedback.ts b/src/cli/brain/verbs/feedback.tsindex a776ecb0..33e61651 100644--- a/src/cli/brain/verbs/feedback.ts+++ b/src/cli/brain/verbs/feedback.ts@@ -1,7 +1,12 @@import { readFileSync } from "node:fs";import { mirrorSignal, resolveSharedNamespace } from "../../../core/brain/shared-namespace.ts";import { resolveEffectiveScope, writeSignal } from "../../../core/brain/signal.ts";-import { adviseIncomingFeedback } from "../../../core/brain/write-advisory.ts";+import {+ adviseIncomingFeedback,+ adviseUnroutableCapture,+ captureRoutingHintField,+} from "../../../core/brain/write-advisory.ts";+import { emitNextStep, type AdvisoryStream } from "../../advisory-rail.ts";import { loadFeedbackDefaultScopeSafe } from "../../../core/brain/policy.ts";import { appendLogEvent } from "../../../core/brain/log.ts";import { writePreference } from "../../../core/brain/preference.ts";@@ -119,6 +124,15 @@ export async function cmdBrainFeedback(argv: string[]): Promise<number> {now,});+ // Unroutable-capture routing hint (unit 4): the signal above landed+ // with no scope, so no scoped recall reaches it. Non-blocking, and+ // silent unless this vault already uses scopes to suggest.+ const routingHint = adviseUnroutableCapture(vault, {+ ...(effectiveScope !== undefined ? { scope: effectiveScope } : {}),+ agent,+ now,+ });+let prefResult: { path: string; id: string } | null = null;if (flags["force-confirmed"]) {try {@@ -172,6 +186,10 @@ export async function cmdBrainFeedback(argv: string[]): Promise<number> {signal_id: sigResult.id,...(mirror !== undefined ? { mirror } : {}),...(advisory !== null ? { advisory } : {}),+ // The machine stream carries the exit as a field, which is where a+ // forward pointer belongs on a payload the caller parses. The key+ // and the resolution come from the one composer both surfaces use.+ ...captureRoutingHintField(routingHint),...(prefResult ? { preference_path: prefResult.path, preference_id: prefResult.id } : {}),});return 0;@@ -190,6 +208,21 @@ export async function cmdBrainFeedback(argv: string[]): Promise<number> {ok(` - ${c.pref_id} (jaccard ${c.jaccard.toFixed(3)})`);}}+ if (routingHint !== null) {+ ok(`routing-hint: no ${routingHint.missing_signal} resolved for this signal`);+ ok(+ ` ${routingHint.missing_signal} values in this vault: ` ++ routingHint.candidates.map((c) => `${c.scope} (${c.documents})`).join(", "),+ );+ // The exit is resolved from the registry by the rail; this verb+ // never assembles a command of its own.+ const stream: AdvisoryStream = {+ command: "brain",+ argv,+ jsonRequested: Boolean(flags["json"]),+ };+ emitNextStep(routingHint.code, stream);+ }if (prefResult) {ok(`preference: ${prefResult.path}`);ok(`status: confirmed`);diff --git a/src/cli/brain/verbs/scan-inline.ts b/src/cli/brain/verbs/scan-inline.tsindex bcf4bd05..749f28a3 100644--- a/src/cli/brain/verbs/scan-inline.ts+++ b/src/cli/brain/verbs/scan-inline.ts@@ -41,6 +41,9 @@ export async function cmdBrainScanInline(argv: string[]): Promise<number> {created: String(result.created),deduped: String(result.deduped),malformed: String(result.malformed),+ facts: String(result.facts),+ skills: String(result.skills),+ suppressed: String(result.suppressed),errors: String(result.errors.length),},});@@ -56,6 +59,9 @@ export async function cmdBrainScanInline(argv: string[]): Promise<number> {created: result.created,deduped: result.deduped,malformed: result.malformed,+ facts: result.facts,+ skills: result.skills,+ suppressed: result.suppressed,errors: result.errors.map((e) => ({ path: e.path, message: e.message })),files_with_markers: result.filesWithMarkers.map((f) => ({path: f.path,@@ -68,8 +74,17 @@ export async function cmdBrainScanInline(argv: string[]): Promise<number> {ok(`created: ${result.created}`);ok(`deduped: ${result.deduped}`);if (result.malformed > 0) ok(`malformed: ${result.malformed}`);+ // Only when non-zero, matching the `malformed` line above: a vault+ // with no fact / skill markers prints exactly what it printed before.+ if (result.facts > 0) ok(`facts: ${result.facts}`);+ if (result.skills > 0) ok(`skills: ${result.skills}`);+ if (result.suppressed > 0) ok(`suppressed: ${result.suppressed}`);for (const e of result.errors) info(` error: ${e.path}: ${e.message}`);}- if (flags["strict"] && result.malformed > 0) return 2;+ // `--strict` means "a scan that could not process everything it found+ // is a failure". A marker its destination refused printed an error and+ // still exited 0 while `malformed` was the only gate: the refusal is+ // unprocessed work exactly as a malformed marker is.+ if (flags["strict"] && (result.malformed > 0 || result.errors.length > 0)) return 2;return 0;}diff --git a/src/core/brain/derived-fact.ts b/src/core/brain/derived-fact.tsindex ef1189bc..dda017b7 100644--- a/src/core/brain/derived-fact.ts+++ b/src/core/brain/derived-fact.ts@@ -19,6 +19,7 @@ import { existsSync } from "node:fs";import { loadBrainConfig, DEFAULT_BRAIN_CONFIG } from "./policy.ts";import { preferencePath } from "./paths.ts";import { writePreference } from "./preference.ts";+import { DERIVED_FACT_SHAPE, DERIVED_FACT_SURFACE, assertResponseShape } from "./response-shape.ts";import { isoSecond } from "./time.ts";import { asProvenanceLevel, type ProvenanceLevel } from "./provenance/provenance.ts";@@ -48,6 +49,39 @@ export class DeriveFactError extends Error {}}+/**+ * Narrow an agent-supplied level to a derivation level. Shared by the payload+ * ingress and {@link deriveFact} so the rejection reads identically wherever+ * an unusable level arrives.+ */+function requireDerivationLevel(raw: unknown): ProvenanceLevel {+ const level = asProvenanceLevel(raw);+ if (level === null || level === "stated") {+ throw new DeriveFactError(+ `a derived fact must be 'deduced' or 'inferred', not ${JSON.stringify(raw)}`,+ );+ }+ return level;+}++/**+ * Ingress of the agent-authored derived-fact payload. The payload is checked+ * against the frozen derived-fact shape BEFORE any field is read, so a+ * structurally wrong premise list is refused by path rather than silently+ * stringified. A violation throws `ResponseShapeError` and nothing is written.+ */+export function parseDeriveFactInput(payload: unknown): DeriveFactInput {+ assertResponseShape(DERIVED_FACT_SURFACE, DERIVED_FACT_SHAPE, payload);+ const rec = payload as Record<string, unknown>;+ return {+ slug: rec["slug"] as string,+ topic: rec["topic"] as string,+ principle: rec["principle"] as string,+ premises: Object.freeze([...(rec["premises"] as ReadonlyArray<string>)]),+ level: requireDerivationLevel(rec["level"]),+ };+}+/** Strip a leading `pref-` so a premise can be given as an id or a bare slug. */function premiseSlug(premise: string): string {const trimmed = premise.trim();@@ -79,12 +113,7 @@ export function deriveFact(input: DeriveFactInput,opts: DeriveFactOptions,): DeriveFactResult {- const level = asProvenanceLevel(input.level);- if (level === null || level === "stated") {- throw new DeriveFactError(- `a derived fact must be 'deduced' or 'inferred', not ${JSON.stringify(input.level)}`,- );- }+ const level = requireDerivationLevel(input.level);if (!input.slug.trim()) throw new DeriveFactError("derived fact missing slug");if (!input.topic.trim()) throw new DeriveFactError("derived fact missing topic");if (!input.principle.trim()) throw new DeriveFactError("derived fact missing principle");diff --git a/src/core/brain/diagnostics.ts b/src/core/brain/diagnostics.tsindex 9e6e8c7f..8091f869 100644--- a/src/core/brain/diagnostics.ts+++ b/src/core/brain/diagnostics.ts@@ -421,6 +421,21 @@ export const DIAGNOSTIC_SIGNALS: ReadonlyMap<string, DiagnosticSignal> = new MapnextCommand: "o2b search check",autoRepairable: false,},+ // --- Capture-routing states (signals-that-survive, unit 4) ---+ // A capture that resolved no scope is recorded and unroutable: it+ // is not a fault - the write is exactly what the operator asked+ // for - but it leaves the signal in the one bucket no scoped+ // recall reaches. The exit is to re-record the SAME capture with+ // the routing signal it lacked, which is why the command carries+ // `--scope`: without it this entry would be indistinguishable+ // from `brain-empty`'s.+ {+ code: "capture-scope-absent",+ issueClass: "capture recorded with no routing scope",+ nextCommand:+ "o2b brain feedback --topic <topic> --signal=positive --principle <principle> --scope <scope>",+ autoRepairable: false,+ },] satisfies ReadonlyArray<DiagnosticSignal>).map((s) => [s.code, Object.freeze(s)]),);diff --git a/src/core/brain/distill/distill-source.ts b/src/core/brain/distill/distill-source.tsindex e55c766e..0f41382a 100644--- a/src/core/brain/distill/distill-source.ts+++ b/src/core/brain/distill/distill-source.ts@@ -27,6 +27,11 @@ import { atomicWriteFileSync } from "../../fs-atomic.ts";import { canonicalNotePath } from "../../path-safety.ts";import { formatFrontmatter, parseFrontmatter, slugify } from "../../vault.ts";import { distillationPagePath } from "../paths.ts";+import {+ DISTILL_CLAIMS_SHAPE,+ DISTILL_CLAIMS_SURFACE,+ assertResponseShape,+} from "../response-shape.ts";import { assertVaultIdentityForWrite } from "../vault-identity.ts";import {renderProvenanceSection,@@ -64,6 +69,19 @@ export function normalizeClaim(rec: Record<string, unknown>): DistillClaim {return { text, ...(block !== undefined && block.length > 0 ? { block } : {}) };}+/**+ * Ingress of the agent-authored claims payload, shared by the CLI and MCP+ * surfaces. The payload is checked against the frozen distill shape BEFORE+ * {@link normalizeClaim} runs, so a non-string `text` is refused by name+ * instead of being normalized into an empty claim and rejected later for the+ * wrong reason. A violation throws `ResponseShapeError` and nothing is+ * written - the whole batch, not just the offending item.+ */+export function parseDistillClaims(payload: unknown): DistillClaim[] {+ assertResponseShape(DISTILL_CLAIMS_SURFACE, DISTILL_CLAIMS_SHAPE, payload);+ return (payload as ReadonlyArray<Record<string, unknown>>).map(normalizeClaim);+}+export interface DistillSourceInput {/** Source identity: a vault-relative path or a URL. Canonicalized on write. */readonly sourcePath: string;diff --git a/src/core/brain/doctor.ts b/src/core/brain/doctor.tsindex c91047c9..b510bdf9 100644--- a/src/core/brain/doctor.ts+++ b/src/core/brain/doctor.ts@@ -84,6 +84,7 @@ import {type VerificationDeltaSummaryCounts,} from "./trust/compute-verification-delta.ts";import { checkInstructionFileCeiling } from "./trust/instruction-file-ceiling.ts";+import { BrainParseError } from "./parse-error.ts";import { brainActivePath, brainConfigPath, brainDirs } from "./paths.ts";import { BrainStatusFolderMismatchError, parsePreference, parseRetired } from "./preference.ts";import {@@ -1131,6 +1132,24 @@ function parseErrorCode(kind: ParsedRecordKind, msg: string): string {* byte-identical copies of this regex-based classification - a change to* a parser's error wording would otherwise reclassify issues in one path* without the other noticing.+ *+ * A {@link BrainParseError} - which both parsers now raise, and which+ * `BrainStatusFolderMismatchError` extends - reports its location from+ * the `path` field and its prose from `detail`, which carries none. The+ * human renderer appends ` (<path>)` from the issue's own field, so a+ * message that embedded the path as well named the file twice on every+ * parse-error line: prose carrying data the record already holds. An+ * untyped throw (a frontmatter read, a vocabulary guard owned by another+ * module) keeps its message verbatim against the walked path - that+ * message is not ours to shorten.+ *+ * What changed for a caller that prints `(exc as Error).message` bare,+ * stated exactly: a throw site whose message already carried the path+ * composes the same sentence as before, the status-folder mismatch+ * included (it supplies its own composition, keeping the location inside+ * the `(path=β¦, status=β¦, folder=β¦)` group). The four optional-field+ * helpers in `preference.ts` carried no location at all and now do -+ * a gain, and the only wording change in the set.*/function classifyParseError(err: unknown,@@ -1142,16 +1161,17 @@ function classifyParseError(issues.push({severity: "warning",code: "status-folder-mismatch",- path,- message: err.message,+ path: err.path,+ message: err.detail,});return;}- const msg = (err as Error).message ?? String(err);+ const typed = err instanceof BrainParseError ? err : null;+ const msg = typed ? typed.detail : ((err as Error).message ?? String(err));issues.push({severity: "error",code: parseErrorCode(kindPrefix, msg),- path,+ path: typed ? typed.path : path,message: msg,});}diff --git a/src/core/brain/gaps/gap-loop.ts b/src/core/brain/gaps/gap-loop.tsindex 2970c601..691c8760 100644--- a/src/core/brain/gaps/gap-loop.ts+++ b/src/core/brain/gaps/gap-loop.ts@@ -7,10 +7,18 @@* confidence - mirroring the dream freshness auto-resolve precedent (a* recorded status flip in frontmatter, never a silent mutation).*- * Language-agnostic by construction: gap topics are telemetry keys taken- * verbatim from the recall-telemetry `gap_counts` aggregate, never words- * classified from prose. Task notes are PLAIN durable files under the Brain- * area (`Brain/gap-tasks/`); they never touch the Hermes kanban board.+ * Two independent recurrence sources feed it (signals-that-survive, unit+ * 6): the structural recall-telemetry `gap_counts` aggregate, whose topic+ * is a coarse telemetry code, and the recall-adequacy verdict stamped onto+ * the cross-query demand log, whose topic is a fine term bucket. They are+ * counted and keyed separately and NEVER summed - `occurrences` would+ * otherwise mean a different thing per row.+ *+ * Language-agnostic by construction: a structural topic is a telemetry key+ * taken verbatim, and a verdict topic is the IDF-derived bucket key+ * `normalizeQueryTerms` computes - never words classified from prose. Task+ * notes are PLAIN durable files under the Brain area (`Brain/gap-tasks/`);+ * they never touch the Hermes kanban board.** Deliberately I/O-scoped to the vault and free of any hook/config* concern, so recurrence, promotion, agenda, and auto-close are each@@ -19,11 +27,12 @@*/import { createHash } from "node:crypto";-import { existsSync, readdirSync, readFileSync } from "node:fs";+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";import { join } from "node:path";import { brainGapTasksDir, BRAIN_GAP_TASKS_REL } from "../paths.ts";import { assertVaultIdentityForWrite } from "../vault-identity.ts";+import { aggregateUnmetRecall } from "../query-demand.ts";import { summarizeRecallTelemetry } from "../recall-telemetry.ts";import { renderActivityTimeline, type ActivityItem } from "../render/activity-line.ts";import type { RecallRetriever } from "../recall-inject.ts";@@ -36,6 +45,58 @@ export const GAP_LOOP_RECURRENCE_THRESHOLD = 3;/** Default normalized-score floor a recall must clear to auto-close a task. */export const GAP_LOOP_AUTO_CLOSE_FLOOR = 0.5;+/**+ * Most gap tasks one promotion run may mint. The cap is load-bearing, not+ * polish: without it a single bad afternoon of empty recalls fills the+ * vault with notes. Rows above the cap are not dropped - detection is+ * ordered most-frequent first, so the remainder is minted by the next run.+ */+export const GAP_LOOP_MAX_PROMOTIONS_PER_RUN = 5;++/**+ * Most gap-task notes the directory may hold at once.+ *+ * The per-run mint cap bounds a BURST; this bounds the TOTAL. Both are+ * needed now that the adequacy source exists: the structural source drew+ * topics from a fixed set of telemetry codes, so the reachable file count+ * was small by construction, while a verdict topic is arbitrary+ * normalised query text and the reachable count became "however many+ * distinct questions the demand log still remembers". A backlog this size+ * is already past the point an operator can work through, so refusing to+ * mint past it costs nothing that was going to be read.+ */+export const GAP_TASKS_MAX_NOTES = 200;++/**+ * How long a CLOSED gap task is kept before the loop removes it.+ *+ * A closed task is a finished record, not a backlog item: it stops being+ * rendered, stops being auto-closed, and exists only so a re-promotion of+ * the same topic is deduped against it. One month is long enough for that+ * dedupe to be useful and short enough that closed work does not+ * accumulate for the life of the vault. An OPEN task is never removed by+ * age - deleting an operator's outstanding work would be the silent loss+ * this loop exists to prevent.+ */+export const GAP_TASK_CLOSED_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;++/** Recurrence source: the structural recall-telemetry `gap_counts` aggregate. */+export const GAP_SOURCE_TELEMETRY = "recall_telemetry";+/** Recurrence source: unmet recall-adequacy verdicts on the demand log. */+export const GAP_SOURCE_ADEQUACY = "recall_adequacy";++export const GAP_SOURCES = [GAP_SOURCE_TELEMETRY, GAP_SOURCE_ADEQUACY] as const;+export type GapSource = (typeof GAP_SOURCES)[number];++/**+ * Agenda and body wording per source, so a coarse telemetry code bucket+ * never reads as the same kind of row as a fine term bucket.+ */+const GAP_LABEL_BY_SOURCE: Readonly<Record<GapSource, string>> = Object.freeze({+ [GAP_SOURCE_TELEMETRY]: "recall gap",+ [GAP_SOURCE_ADEQUACY]: "weak recall",+});+export const GAP_TASK_KIND = "brain-gap-task";export const GAP_TASK_STATUS_OPEN = "open";export const GAP_TASK_STATUS_CLOSED = "closed";@@ -44,39 +105,85 @@ export const GAP_TASK_STATUS_CLOSED = "closed";export interface RecurringGap {readonly topic: string;readonly occurrences: number;+ /** Which recurrence source counted it; rows are never merged across sources. */+ readonly source: GapSource;}/**- * Recurring gaps from the recall-telemetry `gap_counts` aggregate, filtered- * to those recurring at least `threshold` times and ordered most-frequent- * first (topic as a stable tie-break). The gap topic is the telemetry key- * verbatim - no natural-language classification.+ * Recurring gaps from BOTH recurrence sources, filtered to those recurring+ * at least `threshold` times and ordered most-frequent first (source then+ * topic as stable tie-breaks).+ *+ * A topic that appears in both sources yields two rows, each carrying its+ * own count. Summing them would produce a number that means neither "this+ * telemetry code fired N times" nor "this question was asked N times".*/export function detectRecurringGaps(vault: string,opts: { threshold?: number } = {},): ReadonlyArray<RecurringGap> {const threshold = opts.threshold ?? GAP_LOOP_RECURRENCE_THRESHOLD;+ const rows = [...structuralGaps(vault), ...adequacyGaps(vault)].filter(+ (gap) => gap.occurrences >= threshold,+ );+ return Object.freeze(rows.toSorted(compareGaps));+}++/** The structural source: telemetry codes taken verbatim as topics. */+function structuralGaps(vault: string): ReadonlyArray<RecurringGap> {const { gap_counts } = summarizeRecallTelemetry(vault);- return Object.freeze(- Object.entries(gap_counts)- .filter(([, count]) => count >= threshold)- .map(([topic, count]) => Object.freeze({ topic, occurrences: count }))- .toSorted(- (a, b) =>- b.occurrences - a.occurrences || (a.topic < b.topic ? -1 : a.topic > b.topic ? 1 : 0),- ),+ return Object.entries(gap_counts).map(([topic, count]) =>+ Object.freeze({ topic, occurrences: count, source: GAP_SOURCE_TELEMETRY }),+ );+}++/** The verdict source: unmet-recall term buckets from the demand log. */+function adequacyGaps(vault: string): ReadonlyArray<RecurringGap> {+ return aggregateUnmetRecall(vault).map((bucket) =>+ Object.freeze({+ topic: bucket.key,+ occurrences: bucket.occurrences,+ source: GAP_SOURCE_ADEQUACY,+ }),+ );+}++function compareGaps(a: RecurringGap, b: RecurringGap): number {+ return (+ b.occurrences - a.occurrences ||+ compareStrings(a.source, b.source) ||+ compareStrings(a.topic, b.topic));}+function compareStrings(a: string, b: string): number {+ return a < b ? -1 : a > b ? 1 : 0;+}+/*** Stable, filesystem-safe, collision-free dedupe key for a gap topic: a- * short hash of the trimmed topic. Re-promotion of the same topic resolves- * to the same key (and thus the same note), so a gap can never fork into- * two competing task files.+ * short hash of the trimmed topic, namespaced by its recurrence source.+ * Re-promotion of the same topic from the same source resolves to the same+ * key (and thus the same note), so a gap can never fork into two competing+ * task files - while a topic that happens to be textually identical across+ * the two sources still gets one note each.+ *+ * BOTH sources are namespaced, and the source is LENGTH-PREFIXED so the+ * hashed material is an injective encoding of the (source, topic) pair.+ * Namespacing only one of them left the other's topic space able to spell+ * the namespace: a telemetry gap is caller-supplied text, so a code+ * literally spelled `recall_adequacy:<x>` hashed to the same key as the+ * adequacy topic `<x>` and the two rows fought over one note.+ *+ * A key minted before this encoding therefore differs from the one this+ * function now returns for the same telemetry topic. The consequence is+ * bounded and self-clearing: the old note is still listed, still+ * auto-closes, and is removed by the closed-task retention above, while a+ * topic that is still recurring mints one note under the new key.*/-export function gapTaskKey(topic: string): string {- return `gap-${createHash("sha256").update(topic.trim()).digest("hex").slice(0, 16)}`;+export function gapTaskKey(topic: string, source: GapSource = GAP_SOURCE_TELEMETRY): string {+ const material = `${source.length}:${source}:${topic.trim()}`;+ return `gap-${createHash("sha256").update(material).digest("hex").slice(0, 16)}`;}export interface GapPromotionResult {@@ -84,12 +191,29 @@ export interface GapPromotionResult {readonly created: ReadonlyArray<string>;/** Keys skipped because a task with that key already existed. */readonly skipped: ReadonlyArray<string>;+ /** Keys of closed tasks this run removed under the retention window. */+ readonly pruned: ReadonlyArray<string>;+ /**+ * Recurring gaps this run did NOT mint because the directory is at+ * {@link GAP_TASKS_MAX_NOTES}. Reported rather than silently dropped:+ * a full backlog is an operator condition, not a no-op.+ */+ readonly capped: number;}/*** Promote every recurring gap to exactly one durable gap-task note, deduped* on the stable gap key via an exclusive create - a topic already carrying* a task (open or closed) is skipped, never overwritten or forked.+ *+ * At most {@link GAP_LOOP_MAX_PROMOTIONS_PER_RUN} NEW notes are minted per+ * run. A skip costs no budget, so an established backlog never starves a+ * genuinely new gap.+ *+ * The run also enforces the directory's two bounds, in this order: closed+ * tasks past {@link GAP_TASK_CLOSED_RETENTION_MS} are removed first (so+ * the room they free is usable immediately), then minting stops at+ * {@link GAP_TASKS_MAX_NOTES} and the refusal is COUNTED on the result.*/export function promoteGapsToTasks(vault: string,@@ -100,19 +224,33 @@ export function promoteGapsToTasks(const dir = brainGapTasksDir(vault);const created: string[] = [];const skipped: string[] = [];+ const pruned = pruneExpiredGapTasks(vault, opts.now);+ let noteCount = listGapTasks(vault).length;+ let capped = 0;for (const gap of detectRecurringGaps(vault, { threshold: opts.threshold })) {- const key = gapTaskKey(gap.topic);+ if (created.length >= GAP_LOOP_MAX_PROMOTIONS_PER_RUN) break;+ const key = gapTaskKey(gap.topic, gap.source);const path = join(dir, `${key}.md`);+ if (noteCount >= GAP_TASKS_MAX_NOTES) {+ // A topic that already carries a note needs no new file, so the cap+ // did not refuse it - counting it as refused would report a backlog+ // pressure that is not there. The exclusive create below stays the+ // authority on skipping; this pre-check only keeps the count honest.+ if (existsSync(path)) skipped.push(key);+ else capped++;+ continue;+ }const metadata: FrontmatterMap = {kind: GAP_TASK_KIND,gap_key: key,gap_topic: gap.topic,+ gap_source: gap.source,status: GAP_TASK_STATUS_OPEN,occurrences: String(gap.occurrences),created_at: opts.now.toISOString(),};const body =- `Recurring recall gap detected ${gap.occurrences} times. ` ++ `Recurring ${GAP_LABEL_BY_SOURCE[gap.source]} detected ${gap.occurrences} times. ` +`Add vault coverage for this topic; the task auto-closes once the ` +`topic is recalled with sufficient confidence.`;try {@@ -121,6 +259,7 @@ export function promoteGapsToTasks(vaultForRelativePath: vault,});created.push(key);+ noteCount++;} catch (exc) {if (isAlreadyExists(exc)) {skipped.push(key);@@ -129,7 +268,32 @@ export function promoteGapsToTasks(throw exc;}}- return Object.freeze({ created: Object.freeze(created), skipped: Object.freeze(skipped) });+ return Object.freeze({+ created: Object.freeze(created),+ skipped: Object.freeze(skipped),+ pruned,+ capped,+ });+}++/**+ * Remove every CLOSED gap task whose `closed_at` is older than the+ * retention window, returning the keys removed. A task with no readable+ * `closed_at` is left alone: age that cannot be shown is not assumed, and+ * an unremoved note still counts against the cap, so the bound holds+ * either way.+ */+function pruneExpiredGapTasks(vault: string, now: Date): ReadonlyArray<string> {+ const cutoffMs = now.getTime() - GAP_TASK_CLOSED_RETENTION_MS;+ const removed: string[] = [];+ for (const task of listGapTasks(vault, { status: GAP_TASK_STATUS_CLOSED })) {+ const [fm] = parseFrontmatterText(readFileSync(task.path, "utf8"));+ const closedAtMs = Date.parse(stringField(fm["closed_at"]));+ if (!Number.isFinite(closedAtMs) || closedAtMs >= cutoffMs) continue;+ rmSync(task.path, { force: true });+ removed.push(task.key);+ }+ return Object.freeze(removed);}export interface GapTask {@@ -137,6 +301,8 @@ export interface GapTask {readonly topic: string;readonly status: string;readonly occurrences: number;+ /** Which recurrence source minted it (see {@link GAP_SOURCES}). */+ readonly source: GapSource;readonly createdAt: string;readonly path: string;}@@ -166,6 +332,7 @@ export function listGapTasks(topic: stringField(fm["gap_topic"]),status,occurrences: Number.parseInt(stringField(fm["occurrences"]) || "0", 10) || 0,+ source: coerceGapSource(fm["gap_source"]),createdAt: stringField(fm["created_at"]),path,}),@@ -173,25 +340,36 @@ export function listGapTasks(}return Object.freeze(tasks.toSorted(- (a, b) =>- b.createdAt.localeCompare(a.createdAt) ||- (a.topic < b.topic ? -1 : a.topic > b.topic ? 1 : 0),+ (a, b) => b.createdAt.localeCompare(a.createdAt) || compareStrings(a.topic, b.topic),),);}+/**+ * A note minted before the verdict source existed carries no `gap_source`;+ * it is structural by construction, so that is the only safe default+ * (signals-that-survive, unit 6).+ */+function coerceGapSource(value: unknown): GapSource {+ return GAP_SOURCES.includes(value as GapSource) ? (value as GapSource) : GAP_SOURCE_TELEMETRY;+}+/*** Render open gap tasks as a compact session-start agenda through the* shared activity helper (each task is an `openQuestion` item, so it carries* the fixed structural `open` marker and a relative-age label). Returns the* empty string when there is nothing open.+ *+ * Each row is labelled by its recurrence source, so a reader can tell a+ * coarse telemetry code bucket from a fine term bucket and never reads the+ * two counts as one number.*/export function renderGapAgenda(vault: string, now: Date): string {const open = listGapTasks(vault, { status: GAP_TASK_STATUS_OPEN });if (open.length === 0) return "";const items: ReadonlyArray<ActivityItem> = open.map((task) => ({kind: "openQuestion",- text: `${task.topic} (recall gap x${task.occurrences})`,+ text: `${task.topic} (${GAP_LABEL_BY_SOURCE[task.source]} x${task.occurrences})`,timestamp: task.createdAt,}));return `# Open recall-gap tasks\n${renderActivityTimeline(items, now)}`;diff --git a/src/core/brain/ingest/batch-plan.ts b/src/core/brain/ingest/batch-plan.tsindex cc8ab1c4..675afe95 100644--- a/src/core/brain/ingest/batch-plan.ts+++ b/src/core/brain/ingest/batch-plan.ts@@ -21,12 +21,43 @@* over natural-language content. Hidden files and dot-directories (`.git`,* `.open-second-brain`, ...) are skipped so machine artifacts never masquerade* as ingestible sources.+ *+ * Discovery is git-aware (t_4b2bd8f7) through the shared+ * {@link ../../fs/git-discovery.ts} module the hygiene repo scan also composes:+ * a source directory's own `.gitignore`, its nested `.gitignore` files and its+ * `.git/info/exclude` all narrow the walk, and a submodule or nested checkout+ * is not descended into - not as a `readdir` child, and not as a directory a+ * `--src-subpath` starts below either (that is refused outright, since those+ * files belong to another repository). An ignore file that exists but cannot be+ * honoured never passes silently: it comes back on+ * {@link BatchPlan.ignoreWarnings}. Layer precedence, lowest first: `.git/info/exclude`,+ * the source dir's `.gitignore`, each nested `.gitignore` by depth, then the+ * operator's `--exclude` - so an operator pattern always has the last word.+ * Discovery stays in-process: shelling out to `git ls-files` would make the+ * reproducible {@link BatchPlan.planId} depend on an external binary and on+ * user-global git configuration.+ *+ * Path space: layer base directories and the paths matched against them are+ * both VAULT-relative here, which is the base-dir contract git-discovery+ * documents. The hygiene scan chooses repo-root-relative instead; the shared+ * module assumes neither.*/import { existsSync, readdirSync, statSync } from "node:fs";import { join, posix, relative } from "node:path";-import { IgnoreScope, parseIgnorePatterns } from "../../fs/ignore.ts";+import {+ buildRepositoryBaseScope,+ extendWithDirectoryIgnore,+ IGNORE_WARNING_NO_LINE,+ isNestedRepositoryBoundary,+} from "../../fs/git-discovery.ts";+import {+ parseIgnorePatterns,+ type IgnoreLayer,+ type IgnoreScope,+ type IgnoreWarning,+} from "../../fs/ignore.ts";import { canonicalNotePath, ensureInsideVault } from "../../path-safety.ts";import { computePlanId, readCheckpoint } from "./checkpoint.ts";import { classifyPaths, readManifest } from "./content-manifest.ts";@@ -71,13 +102,19 @@ export interface BatchPlanOptions {/*** Scope discovery to a subtree of `sourceDir` (t_e82101a5), e.g. `pkg/a` in a* monorepo. Resolved relative to the source dir; a value escaping it throws.+ * Narrows the walk, never widens it: a subpath under a directory the+ * repository ignores plans nothing and reports why on+ * {@link BatchPlan.ignoreWarnings} (override it with an `exclude`+ * re-include), and a subpath under a submodule or nested checkout throws.* Absent β the whole source dir is walked (byte-identical to before).*/readonly srcSubpath?: string;/*** Gitignore-style patterns (t_e82101a5), matched by the shared* {@link parseIgnorePatterns} engine relative to `sourceDir`. Discovered- * paths matching any pattern are dropped. Absent/empty β no exclusion.+ * paths matching any pattern are dropped. Layered ABOVE every ignore file the+ * repository declares, so an operator pattern - including a `!` re-include -+ * overrides the repository. Absent/empty β no exclusion.*/readonly exclude?: readonly string[];}@@ -131,6 +168,18 @@ export interface BatchPlan {* recorded them completed. Zero on a fresh plan or when `resume` is off.*/readonly resumedCompleted: number;+ /**+ * Everything the walk could not apply as declared (t_4b2bd8f7), sorted by+ * source then line: a malformed pattern in the repository's OWN ignore files,+ * an ignore file that exists but could not be read (unreadable, a symlink,+ * oversized - `line` 0), and a `--src-subpath` that pointed inside a subtree+ * the repository ignores (`source` `--src-subpath`, `line` 0). None of these+ * fails the plan - the repository is an input, not operator intent - but none+ * of them passes silently either. A malformed operator `--exclude` still+ * throws, and so does a subpath crossing a repository boundary. Empty on a+ * tree whose ignore files all compile, and on a tree that declares none.+ */+ readonly ignoreWarnings: readonly IgnoreWarning[];}/**@@ -164,11 +213,13 @@ export function planBatches(vault: string, sourceDir: string, opts: BatchPlanOpt// Optional subtree scoping (t_e82101a5): resolve `srcSubpath` under the// source dir. ensureInsideVault throws a typed error if it escapes.+ const srcSubpath =+ opts.srcSubpath !== undefined && opts.srcSubpath.length > 0 ? opts.srcSubpath : null;let walkRoot = dirAbs;- if (opts.srcSubpath !== undefined && opts.srcSubpath.length > 0) {- walkRoot = ensureInsideVault(join(dirAbs, opts.srcSubpath), dirAbs);+ if (srcSubpath !== null) {+ walkRoot = ensureInsideVault(join(dirAbs, srcSubpath), dirAbs);if (!existsSync(walkRoot) || !statSync(walkRoot).isDirectory()) {- throw new Error(`planBatches: src subpath is not an existing directory: ${opts.srcSubpath}`);+ throw new Error(`planBatches: src subpath is not an existing directory: ${srcSubpath}`);}}@@ -176,11 +227,45 @@ export function planBatches(vault: string, sourceDir: string, opts: BatchPlanOpt// Optional exclusion (t_e82101a5): reuse the shared ignore engine so there is// no second matcher. Patterns are relative to the source dir. A malformed// pattern is a user error, surfaced loudly rather than silently ignored.- const excludeScope = buildExcludeScope(opts.exclude ?? [], dirRel);+ const excludeLayer = buildExcludeLayer(opts.exclude ?? [], dirRel);++ // What the repository declares about itself (t_4b2bd8f7), beneath the+ // operator's layer. The source dir is the repository root for this purpose; a+ // subpath-scoped walk starts from the declarations above it AND obeys them, so+ // naming a subpath can neither re-enter an ignored subtree nor cross into+ // another repository (both would make the same tree answer two ways).+ const ignoreWarnings: IgnoreWarning[] = [];+ const base = buildRepositoryBaseScope(dirAbs, dirRel);+ ignoreWarnings.push(...base.warnings);+ let walkScope = base.scope;+ let prunedWarning: IgnoreWarning | null = null;+ if (srcSubpath !== null) {+ const descent = descendToSubpathRoot({+ scope: base.scope,+ excludeLayer,+ sourceDirAbs: dirAbs,+ sourceDirRel: dirRel,+ subpath: srcSubpath,+ walkRoot,+ warnings: ignoreWarnings,+ });+ walkScope = descent.scope;+ prunedWarning = descent.prunedWarning;+ if (prunedWarning !== null) ignoreWarnings.push(prunedWarning);+ }- // Discover ingestible files as canonical vault-relative paths, sorted.+ // Discover ingestible files as canonical vault-relative paths, sorted. A walk+ // root inside an ignored subtree discovers nothing and says why on the plan.const discovered: string[] = [];- collectIngestible(walkRoot, vault, extensions, excludeScope, discovered);+ if (prunedWarning === null) {+ collectIngestible(walkRoot, walkScope, {+ vault,+ extensions,+ excludeLayer,+ out: discovered,+ warnings: ignoreWarnings,+ });+ }const discoveredRel = discovered.map((abs) => canonicalNotePath(toPosixRel(vault, abs))).toSorted();@@ -236,9 +321,18 @@ export function planBatches(vault: string, sourceDir: string, opts: BatchPlanOpttotalBytes: planned.reduce((sum, f) => sum + f.bytes, 0),planId,resumedCompleted,+ // Sorted so the plan is fully deterministic: the walk visits directories in+ // readdir order, which is not guaranteed stable across platforms.+ ignoreWarnings: ignoreWarnings.toSorted(compareIgnoreWarnings),};}+/** Order warnings by their ignore file, then by line within it. */+function compareIgnoreWarnings(a: IgnoreWarning, b: IgnoreWarning): number {+ if (a.source !== b.source) return a.source < b.source ? -1 : 1;+ return a.line - b.line;+}+/*** Greedily pack sorted files into batches. A file joins the current batch unless* doing so would breach the byte cap or the count cap, in which case the current@@ -275,43 +369,154 @@ function packBatches(}/**- * Build the exclusion scope from `--exclude` patterns, relative to the source- * dir. A malformed pattern is a user error and throws (never a silent skip). An- * empty pattern list yields an empty scope that ignores nothing, keeping the- * no-flag path byte-identical.+ * Compile the `--exclude` patterns into one layer, relative to the source dir.+ * A malformed pattern is a user error and throws (never a silent skip) - unlike+ * a malformed pattern in the repository's own ignore files, which the operator+ * did not write and which is reported on {@link BatchPlan.ignoreWarnings}. An+ * empty pattern list yields `null`, so the no-flag path stacks no layer at all+ * and stays byte-identical.*/-function buildExcludeScope(patterns: readonly string[], baseDir: string): IgnoreScope {- if (patterns.length === 0) return IgnoreScope.empty();+function buildExcludeLayer(patterns: readonly string[], baseDir: string): IgnoreLayer | null {+ if (patterns.length === 0) return null;const { layer, warnings } = parseIgnorePatterns(patterns, baseDir, "--exclude");if (warnings.length > 0) {const w = warnings[0]!;throw new Error(`planBatches: malformed --exclude pattern "${w.pattern}": ${w.reason}`);}- return IgnoreScope.empty().extend(layer);+ return layer;+}++/** Everything {@link descendToSubpathRoot} needs to reach a subpath walk root. */+interface SubpathDescentInput {+ /** Scope governing the source dir, before any intermediate directory is added. */+ readonly scope: IgnoreScope;+ /** Operator `--exclude`, stacked above every repository layer. Null when absent. */+ readonly excludeLayer: IgnoreLayer | null;+ readonly sourceDirAbs: string;+ readonly sourceDirRel: string;+ /** The operator's `--src-subpath` value, recorded on a prune warning. */+ readonly subpath: string;+ readonly walkRoot: string;+ /** Accumulates malformed patterns found on the way down. */+ readonly warnings: IgnoreWarning[];+}++/** The scope governing the walk root, or the reason it must not be walked. */+interface SubpathDescent {+ readonly scope: IgnoreScope;+ /**+ * Null when every directory on the way down is walkable. Non-null when one of+ * them is ignored: the requested subtree sits inside an ignored one, is NOT+ * walked, and this warning carries the explanation onto the plan.+ */+ readonly prunedWarning: IgnoreWarning | null;+}++/** Provenance recorded on a warning caused by the `--src-subpath` flag itself. */+const SRC_SUBPATH_WARNING_SOURCE = "--src-subpath";++/**+ * Walk from the source dir (exclusive) down to the subpath walk root+ * (inclusive), applying to every directory on the way the same two rules+ * {@link collectIngestible} applies to a directory it meets as a `readdir`+ * entry - a nested repository is a boundary, an ignored directory prunes its+ * subtree - and layering each directory's own `.gitignore` for what lies below+ * it. Without this a `--src-subpath` would re-enter a subtree the repository+ * declared off-limits, or a foreign repository, purely because the walk never+ * passed through the parent that would have stopped it.+ *+ * Throws when a directory on the way down is a submodule or nested checkout.+ */+function descendToSubpathRoot(input: SubpathDescentInput): SubpathDescent {+ let current = input.scope;+ let abs = input.sourceDirAbs;+ let rel = input.sourceDirRel;+ for (const segment of toPosixRel(input.sourceDirAbs, input.walkRoot).split(posix.sep)) {+ if (segment.length === 0) continue;+ abs = join(abs, segment);+ rel = posix.join(rel, segment);+ // A boundary, not an ignore rule: those files are another repository's, so+ // no operator flag can re-include them and the plan refuses outright rather+ // than attributing a foreign repository's files to this tree.+ if (isNestedRepositoryBoundary(abs)) {+ throw new Error(+ `planBatches: src subpath "${input.subpath}" crosses a nested repository ` ++ `boundary at "${rel}": those files belong to that repository - plan against ` ++ "it directly",+ );+ }+ // Ignored-ness is decided by the layers governing the PARENT plus the+ // operator's `--exclude`, exactly as it is for a readdir child, so an+ // `--exclude` re-include remains the one way to override the repository.+ const effective = input.excludeLayer === null ? current : current.extend(input.excludeLayer);+ if (effective.isIgnored(rel, true)) {+ return { scope: current, prunedWarning: subpathIgnoredWarning(input.subpath, rel) };+ }+ const extended = extendWithDirectoryIgnore(current, abs, rel);+ input.warnings.push(...extended.warnings);+ current = extended.scope;+ }+ return { scope: current, prunedWarning: null };+}++/**+ * The structured warning a subpath pointing into an ignored subtree produces.+ * The plan comes back empty on purpose - the same tree must answer the same way+ * however it is addressed - and this says so instead of leaving the operator+ * with a silent empty plan.+ */+function subpathIgnoredWarning(subpath: string, ignoredDir: string): IgnoreWarning {+ return {+ source: SRC_SUBPATH_WARNING_SOURCE,+ line: IGNORE_WARNING_NO_LINE,+ pattern: subpath,+ reason:+ `"${ignoredDir}" is ignored by the repository, so nothing under the requested ` ++ 'subpath was planned; override it with an --exclude "!" re-include',+ };+}++/** Everything the recursive walk needs beyond the current directory and scope. */+interface WalkContext {+ readonly vault: string;+ readonly extensions: ReadonlySet<string>;+ /** Operator `--exclude`, stacked above every repository layer. Null when absent. */+ readonly excludeLayer: IgnoreLayer | null;+ /** Accumulates discovered absolute file paths. */+ readonly out: string[];+ /** Accumulates malformed patterns found in the repository's own ignore files. */+ readonly warnings: IgnoreWarning[];}/*** Recursively collect ingestible regular-file absolute paths, skipping hidden- * entries and anything the exclusion scope matches (t_e82101a5). An excluded- * directory is pruned so its subtree is never walked.+ * entries and anything the composed ignore scope matches. An ignored directory+ * is pruned so its subtree is never walked.+ *+ * `scope` already carries the layers governing `dir`; a child directory's own+ * `.gitignore` is stacked before descending into it, so a deeper file scopes+ * only what it governs and a nearer `!` re-include wins. The operator's+ * `--exclude` is applied on top for every match, keeping it above the whole+ * repository-declared stack no matter how deep the walk goes.*/-function collectIngestible(- dir: string,- vault: string,- extensions: ReadonlySet<string>,- exclude: IgnoreScope,- out: string[],-): void {+function collectIngestible(dir: string, scope: IgnoreScope, ctx: WalkContext): void {+ const effective = ctx.excludeLayer === null ? scope : scope.extend(ctx.excludeLayer);for (const entry of readdirSync(dir, { withFileTypes: true })) {if (entry.name.startsWith(".")) continue; // hidden file or dot-directoryconst abs = join(dir, entry.name);- const rel = toPosixRel(vault, abs);+ const rel = toPosixRel(ctx.vault, abs);if (entry.isDirectory()) {- if (exclude.isIgnored(rel, true)) continue;- collectIngestible(abs, vault, extensions, exclude, out);- } else if (entry.isFile() && extensions.has(extname(entry.name).toLowerCase())) {- if (exclude.isIgnored(rel, false)) continue;- out.push(abs);+ // A submodule or nested checkout belongs to another repository's index.+ // This is a boundary, not an ignore rule, so `--exclude` cannot re-include+ // it - an operator wanting those files plans against that repository.+ if (isNestedRepositoryBoundary(abs)) continue;+ if (effective.isIgnored(rel, true)) continue;+ const child = extendWithDirectoryIgnore(scope, abs, rel);+ ctx.warnings.push(...child.warnings);+ collectIngestible(abs, child.scope, ctx);+ } else if (entry.isFile() && ctx.extensions.has(extname(entry.name).toLowerCase())) {+ if (effective.isIgnored(rel, false)) continue;+ ctx.out.push(abs);}}}diff --git a/src/core/brain/inline-scan.ts b/src/core/brain/inline-scan.tsindex 1d170f18..c3fb721c 100644--- a/src/core/brain/inline-scan.ts+++ b/src/core/brain/inline-scan.ts@@ -23,6 +23,22 @@* `Brain/inbox/processed/`. A marker whose hash already maps to an* existing signal triggers only a rewrite (annotate the source* file), not a new signal.+ *+ * Three marker kinds are routed here, each into a store that already+ * carries its own review gate: `feedback` into `Brain/inbox/`, `fact`+ * into the unconfirmed preferences, and `skill` into the pending+ * proposal queue (see `marker-routing.ts`). Every routed marker is+ * consumed through the same `@osbβ` sentinel, so a rescan is a no-op;+ * a marker whose destination REFUSED it, or declined it without storing+ * its content, is left live and reported, so the operator can fix the+ * marker and rescan. `loop` and `set` markers are not routed here -+ * loops are live-derived and set markers belong to the guarded+ * write-back verb.+ *+ * A dry run walks every one of those steps in preview and writes+ * nothing: the counters and the errors are what a real run would+ * produce, because a preview that reports nothing while work is queued+ * is not a preview.*/import { readFileSync } from "node:fs";@@ -32,6 +48,7 @@ import { emitIngestDedupReport, type IngestDedupSourceCount } from "./dedup-teleimport { buildDedupIndex, computeDedupHash, type DedupIndexEntry } from "./dedup-hash.ts";import { discoverMarkersDetailed, isFeedbackMarker } from "./inline.ts";import { rewriteMarkers, type RewriteOp } from "./inline-rewrite.ts";+import { previewCaptureMarker, routeCaptureMarker, ROUTED_MARKER_KINDS } from "./marker-routing.ts";import { buildNoteWalkRules, resolveNoteRoots, walkMarkdownFiles } from "./notes/note-walk.ts";import { writeSignal } from "./signal.ts";import { isoDate, isoSecond } from "./time.ts";@@ -64,10 +81,25 @@ export interface ScanInlineFileSummary {export interface ScanInlineResult {readonly scanned: number;+ /**+ * Markers this scan is responsible for: feedback plus the routed+ * kinds. A file whose only markers are `fact` / `skill` is work this+ * run does, so it counts here and in {@link filesWithMarkers}.+ */readonly found: number;readonly created: number;readonly deduped: number;readonly malformed: number;+ /** Fact markers committed as unconfirmed preferences by this run. */+ readonly facts: number;+ /** Skill markers drafted into the pending proposal queue by this run. */+ readonly skills: number;+ /**+ * Routed markers whose destination declined and stored nothing. Each+ * one also appears in {@link errors}, and each is left live in its+ * source file - see the routed-marker loop for why.+ */+ readonly suppressed: number;readonly errors: ReadonlyArray<ScanInlineErrorEntry>;readonly filesWithMarkers: ReadonlyArray<ScanInlineFileSummary>;}@@ -87,6 +119,9 @@ export async function scanInline(let created = 0;let deduped = 0;let malformed = 0; // reserved β not surfaced separately yet+ let facts = 0;+ let skills = 0;+ let suppressed = 0;// v0.11.0: explicit `opts.paths` always wins. When absent or empty,// fall back to `notes.read_paths` from `_brain.yaml`. An empty@@ -102,6 +137,9 @@ export async function scanInline(created: 0,deduped: 0,malformed: 0,+ facts: 0,+ skills: 0,+ suppressed: 0,errors: Object.freeze([]) as ReadonlyArray<ScanInlineErrorEntry>,filesWithMarkers: Object.freeze([]) as ReadonlyArray<ScanInlineFileSummary>,});@@ -142,15 +180,33 @@ export async function scanInline(}const discovery = discoverMarkersDetailed(content);malformed += discovery.malformed;- // Feedback markers only: loop markers are live-derived and never- // consumed, and set markers belong to the guarded write-back verb.- // Both must not be turned into signals or rewritten here.- const markers = discovery.markers.filter(isFeedbackMarker);- if (markers.length === 0) continue;- found += markers.length;- filesWithMarkers.push({ path: filePath, markers: markers.length });+ const vaultRelSource = relative(vault, filePath).split(sep).join("/");+ // A named-field rejection on a ROUTED kind is an operator mistake with+ // a destination behind it, so it is surfaced by name instead of only+ // counted. Rejections of the other kinds keep their historical+ // count-only treatment, which `--strict` already turns into an exit.+ for (const issue of discovery.issues) {+ if (!ROUTED_MARKER_KINDS.has(issue.kind)) continue;+ errors.push({ path: filePath, message: issue.message });+ }const rewriteOps: RewriteOp[] = [];++ // Feedback markers become inbox signals. Loop markers are live-derived+ // and never consumed; set markers belong to the guarded write-back+ // verb. Neither may be turned into a signal or rewritten here.+ const markers = discovery.markers.filter(isFeedbackMarker);+ const routedMarkers = discovery.markers.filter((marker) =>+ ROUTED_MARKER_KINDS.has(marker.kind),+ );+ // Every marker this run is responsible for, whichever store it lands+ // in: a file holding only fact / skill markers is work, and a report+ // that omitted it would name no file for the counters below.+ const handledMarkers = markers.length + routedMarkers.length;+ if (handledMarkers > 0) {+ found += handledMarkers;+ filesWithMarkers.push({ path: filePath, markers: handledMarkers });+ }let fileDeduped = 0;for (const marker of markers) {const hash = computeDedupHash({@@ -170,7 +226,6 @@ export async function scanInline(}if (opts.dryRun) continue;// Create the signal.- const vaultRelSource = relative(vault, filePath).split(sep).join("/");const sourceList = marker.source? [...marker.source, `[[${vaultRelSource}]]`]: [`[[${vaultRelSource}]]`];@@ -201,10 +256,48 @@ export async function scanInline(}if (fileDeduped > 0) {- dedupBySource.push({- ref: relative(vault, filePath).split(sep).join("/"),- exactDeduped: fileDeduped,- });+ dedupBySource.push({ ref: vaultRelSource, exactDeduped: fileDeduped });+ }++ // Fact and skill markers reach their own gated stores. Per-marker+ // isolation: a destination that refuses one marker leaves it live and+ // reports why, and the remaining markers in the file still run.+ //+ // A dry run walks the same markers through the same destinations in+ // preview: it counts what would be written and reports what would be+ // refused, and writes nothing. Reporting neither, while queueing the+ // writes for the next real run, would be a preview of nothing.+ const routeCtx = { sourceRef: `[[${vaultRelSource}]]`, now };+ for (const marker of routedMarkers) {+ try {+ const routed = opts.dryRun+ ? previewCaptureMarker(vault, marker, routeCtx)+ : routeCaptureMarker(vault, marker, routeCtx);+ if (routed.outcome === "suppressed") {+ // The destination stored nothing, so the marker is the only copy+ // of what the author declared: consuming it would destroy that+ // copy and point the sentinel at an artifact carrying different+ // content. It stays live, and the refusal is named.+ suppressed++;+ errors.push({+ path: filePath,+ message: `${marker.kind} marker at line ${marker.originLine} was not consumed: ${routed.reason}`,+ });+ continue;+ }+ if (routed.outcome === "created") {+ if (marker.kind === "fact") facts++;+ else skills++;+ }+ rewriteOps.push({ marker, signalId: routed.id });+ } catch (err) {+ errors.push({+ path: filePath,+ message: `${marker.kind} marker at line ${marker.originLine} was refused: ${+ (err as Error).message ?? String(err)+ }`,+ });+ }}if (rewriteOps.length > 0 && !opts.dryRun) {@@ -236,6 +329,9 @@ export async function scanInline(created,deduped,malformed,+ facts,+ skills,+ suppressed,errors: Object.freeze(errors),filesWithMarkers: Object.freeze(filesWithMarkers),});diff --git a/src/core/brain/inline.ts b/src/core/brain/inline.tsindex b8a66f20..5f67cd8b 100644--- a/src/core/brain/inline.ts+++ b/src/core/brain/inline.ts@@ -30,29 +30,93 @@* single-line / block parsers β the walker treats null as "this is* not a marker" and moves on. CLI `--strict` mode surfaces those* misses as warnings separately; the parser itself is silent.+ *+ * The one exception to that silence is a rejection attributable to a+ * NAMED field β a required field that is absent, or one given twice+ * where a single value is the only unambiguous reading. Those are also+ * reported as a {@link MarkerParseIssue} through the optional issue+ * sink both parsers accept, which is how a kind that routes into a+ * store (`fact`, `skill`) turns a marker an author clearly meant into+ * an explicit error naming the field instead of a silent drop.*/-const KNOWN_KINDS: ReadonlySet<string> = new Set(["feedback", "loop", "set"]);-const KNOWN_SIGNALS: ReadonlyArray<string> = ["positive", "negative"];+/**+ * The one kind whose validity is structural rather than a flat presence+ * check: a loop is resolved by the close-form decision table (see+ * {@link classifyLoop}), so it has no row in {@link REQUIRED_FIELDS}.+ */+const LOOP_KIND = "loop";++/** How many values a required field may carry before it turns ambiguous. */+type RequiredFieldArity = "single" | "repeatable";++/** Marker kinds validated by a flat required-field presence check. */+type RequiredFieldKind = "feedback" | "set" | "fact" | "skill";++/**+ * Required `key=value` fields per marker kind, and the arity each one+ * accepts. The single generalisation of the old feedback-specific+ * `topic` / `principle` hard-require, and the single source of the kind+ * vocabulary β {@link KNOWN_KINDS} is derived from these keys plus+ * {@link LOOP_KIND}, so a kind cannot be half-registered.+ *+ * The feedback row reproduces the historical requirement byte-for-byte;+ * the `set` row carries the write-back triple; the `fact` row carries+ * what `deriveFact` cannot default (a premise set and the derivation+ * level); the `skill` row carries what a reviewer needs in order to+ * judge a proposal (what the skill is called, and what it does).+ */+const REQUIRED_FIELDS: Record<RequiredFieldKind, Readonly<Record<string, RequiredFieldArity>>> = {+ feedback: { topic: "single", principle: "single" },+ set: { note: "single", field: "single", value: "single" },+ fact: { topic: "single", principle: "single", premise: "repeatable", level: "single" },+ skill: { name: "single", body: "single" },+};/**- * Required `key=value` fields per marker kind. The single generalisation- * of the old feedback-specific `topic` / `principle` hard-require. The- * feedback row reproduces the historical requirement byte-for-byte; the- * `set` row adds the write-back triple. `loop` is absent here because it- * is validated structurally by the close-form decision table, not by a- * flat presence check.+ * Optional `key=value` fields per marker kind, with the arity each one+ * accepts. Checked in the same pass as {@link REQUIRED_FIELDS} because a+ * field given twice where a single value is the only unambiguous reading+ * is ambiguous whether the field is required or not: `scope: coding`+ * followed by `scope: writing` names two destinations for one signal.+ * Refusing that on a required field while dropping it on an optional one+ * would write the signal unscoped and unroutable, which is the one+ * outcome the author cannot have meant.+ *+ * A key in neither row is collected and ignored, exactly as before - the+ * grammar has never rejected an unknown field.*/-const REQUIRED_FIELDS: Record<"feedback" | "set", ReadonlyArray<string>> = {- feedback: ["topic", "principle"],- set: ["note", "field", "value"],+const OPTIONAL_FIELDS: Record<RequiredFieldKind, Readonly<Record<string, RequiredFieldArity>>> = {+ feedback: { scope: "single", agent: "single", note: "single", source: "repeatable" },+ set: {},+ fact: {},+ skill: {},};-export type MarkerKind = "feedback" | "loop" | "set";+const KNOWN_KINDS: ReadonlySet<string> = new Set<string>([+ ...Object.keys(REQUIRED_FIELDS),+ LOOP_KIND,+]);+const KNOWN_SIGNALS: ReadonlyArray<string> = ["positive", "negative"];++export type MarkerKind = RequiredFieldKind | typeof LOOP_KIND;export type MarkerSignal = "positive" | "negative";export type MarkerShape = "inline" | "block";export type LoopForm = "open" | "close";+/** A `key=value`-only body kind: everything except `feedback` and `loop`. */+type FieldOnlyKind = Exclude<RequiredFieldKind, "feedback">;++/**+ * True for a known kind whose body carries no positional token, so the+ * whole remainder is a `key=value` collection. Derived from the kind+ * vocabulary rather than from a second list, so a new row in+ * {@link REQUIRED_FIELDS} is routed here without another edit.+ */+function isFieldOnlyKind(kind: string): kind is FieldOnlyKind {+ return KNOWN_KINDS.has(kind) && kind !== "feedback" && kind !== LOOP_KIND;+}+/*** One shape for every marker kind. Per-kind fields are optional and* additive so existing feedback consumers keep compiling unchanged; a@@ -62,10 +126,12 @@ export type LoopForm = "open" | "close";*/export interface ParsedMarker {readonly kind: MarkerKind;- // ββ feedback (kind === "feedback") ββ- readonly signal?: MarkerSignal;+ // ββ feedback (kind === "feedback") and fact (kind === "fact") ββ+ /** The rule's subject and text; both rule-bearing kinds carry them. */readonly topic?: string;readonly principle?: string;+ // ββ feedback (kind === "feedback") ββ+ readonly signal?: MarkerSignal;readonly scope?: string;readonly agent?: string;/** Feedback free-note, or the `set` target note (`note=` in both). */@@ -81,6 +147,16 @@ export interface ParsedMarker {// ββ set (kind === "set") ββreadonly field?: string;readonly value?: string;+ // ββ fact (kind === "fact") ββ+ /** Premise preference ids the conclusion derives from, in source order. */+ readonly premise?: ReadonlyArray<string>;+ /** Derivation trust level, verbatim; `deriveFact` owns that vocabulary. */+ readonly level?: string;+ // ββ skill (kind === "skill") ββ+ /** Human-facing name of the proposed skill; also its identity key. */+ readonly name?: string;+ /** What the skill does, carried verbatim into the proposal body. */+ readonly body?: string;// ββ common ββ/** 1-based line number where the marker starts in the source file. */readonly originLine: number;@@ -104,25 +180,222 @@ export type FeedbackMarker = ParsedMarker & {/*** Type guard: true only for feedback markers. Signal-emitting consumers* (`scanInline`, `captureMarkers`, `importSession`) filter on this so- * loop / set markers are never consumed, rewritten, or turned into- * signals β loops are live-derived and set markers belong to the- * guarded write-back verb.+ * markers of other kinds are never turned into signals β loops are+ * live-derived, set markers belong to the guarded write-back verb, and+ * fact / skill markers have their own destinations.*/export function isFeedbackMarker(marker: ParsedMarker): marker is FeedbackMarker {return marker.kind === "feedback";}-function requiredFieldsPresent(- kind: "feedback" | "set",- fields: Record<string, string | string[]>,-): boolean {- for (const key of REQUIRED_FIELDS[kind]) {+/**+ * A {@link ParsedMarker} narrowed to `kind === "fact"`. Routed through+ * the derive-fact path, which commits it as an unconfirmed preference.+ */+export type FactMarker = ParsedMarker & {+ readonly kind: "fact";+ readonly topic: string;+ readonly principle: string;+ readonly premise: ReadonlyArray<string>;+ readonly level: string;+};++/** Type guard: true only for fact markers. */+export function isFactMarker(marker: ParsedMarker): marker is FactMarker {+ return marker.kind === "fact";+}++/**+ * A {@link ParsedMarker} narrowed to `kind === "skill"`. Routed to the+ * pending skill-proposal queue, never to accepted.+ */+export type SkillMarker = ParsedMarker & {+ readonly kind: "skill";+ readonly name: string;+ readonly body: string;+};++/** Type guard: true only for skill markers. */+export function isSkillMarker(marker: ParsedMarker): marker is SkillMarker {+ return marker.kind === "skill";+}++/**+ * A rejection attributable to a named field, reported through the+ * optional issue sink both parsers accept. The rejection itself is+ * unchanged β the parsers still return null β so a kind that does not+ * route anywhere behaves exactly as before.+ */+export interface MarkerParseIssue {+ readonly kind: MarkerKind;+ readonly shape: MarkerShape;+ /** 1-based line the rejected marker starts on. */+ readonly originLine: number;+ /** Required fields that were absent or empty. */+ readonly missingFields: ReadonlyArray<string>;+ /**+ * Single-valued fields given more than once, which is ambiguous.+ * Required and optional alike: an optional field repeated is no more+ * readable than a required one repeated.+ */+ readonly duplicateFields: ReadonlyArray<string>;+ /** Operator-facing message naming every field in the two lists above. */+ readonly message: string;+}++/** Sink the parsers report a {@link MarkerParseIssue} to. */+export type MarkerIssueSink = (issue: MarkerParseIssue) => void;++/**+ * Check a collected field set against the kind's required and optional+ * field rows. Returns true when the marker may be built; otherwise+ * reports one issue naming every offending field and returns false.+ *+ * A `single` field must be exactly one non-empty value: an array means+ * the key was given twice and there is no unambiguous reading of that,+ * which is why a repeated `set` note / field / value has always been+ * rejected. A `repeatable` field must carry at least one non-empty+ * value. Only a required field can be missing; the ambiguity check runs+ * over both rows (see {@link OPTIONAL_FIELDS}).+ */+function fieldsUsable(input: {+ readonly kind: RequiredFieldKind;+ readonly fields: Record<string, string | string[]>;+ readonly originLine: number;+ readonly shape: MarkerShape;+ readonly onIssue?: MarkerIssueSink | undefined;+}): boolean {+ const { kind, fields, originLine, shape, onIssue } = input;+ const missingFields: string[] = [];+ const duplicateFields: string[] = [];+ for (const [key, arity] of Object.entries(REQUIRED_FIELDS[kind])) {const value = fields[key];- // Non-empty string only. An array (repeated key) or empty value- // fails - matching the historical `!topic || !principle` reject.- if (typeof value !== "string" || value.length === 0) return false;+ if (arity === "repeatable") {+ const values = toValueList(value);+ if (values.length === 0 || values.some((entry) => entry.length === 0))+ missingFields.push(key);+ continue;+ }+ if (Array.isArray(value)) {+ duplicateFields.push(key);+ continue;+ }+ if (typeof value !== "string" || value.length === 0) missingFields.push(key);+ }+ // An optional field is never missing. A repeat of a single-valued one+ // is exactly as unreadable as it is on a required field, so it lands in+ // the same list and produces the same named refusal.+ for (const [key, arity] of Object.entries(OPTIONAL_FIELDS[kind])) {+ if (arity === "repeatable") continue;+ if (Array.isArray(fields[key])) duplicateFields.push(key);}- return true;+ if (missingFields.length === 0 && duplicateFields.length === 0) return true;+ onIssue?.({+ kind,+ shape,+ originLine,+ missingFields: Object.freeze([...missingFields]),+ duplicateFields: Object.freeze([...duplicateFields]),+ message: fieldIssueMessage(kind, originLine, missingFields, duplicateFields),+ });+ return false;+}++function fieldIssueMessage(+ kind: RequiredFieldKind,+ originLine: number,+ missingFields: ReadonlyArray<string>,+ duplicateFields: ReadonlyArray<string>,+): string {+ const parts: string[] = [];+ if (missingFields.length > 0) {+ parts.push(`${plural("missing required field", missingFields)}: ${missingFields.join(", ")}`);+ }+ if (duplicateFields.length > 0) {+ parts.push(+ `${plural("repeated single-valued field", duplicateFields)}: ${duplicateFields.join(", ")}`,+ );+ }+ return `@osb ${kind} marker at line ${originLine} is not usable - ${parts.join("; ")}`;+}++function plural(label: string, fields: ReadonlyArray<string>): string {+ return fields.length === 1 ? label : `${label}s`;+}++/** Normalise a collected field value to the list of values it carries. */+function toValueList(value: string | string[] | undefined): ReadonlyArray<string> {+ if (Array.isArray(value)) return value;+ return typeof value === "string" ? [value] : [];+}++/**+ * Build the marker for a `key=value`-only kind. Shared by the inline+ * and block parsers so the two shapes cannot disagree about which field+ * lands where; the required-field check has already passed.+ */+function buildFieldMarker(input: {+ readonly kind: FieldOnlyKind;+ readonly fields: Record<string, string | string[]>;+ readonly originLine: number;+ readonly originText: string;+ readonly shape: MarkerShape;+}): ParsedMarker {+ const { kind, fields, originLine, originText, shape } = input;+ const common = { originLine, originText, shape };+ switch (kind) {+ case "set":+ return {+ kind,+ note: fields["note"] as string,+ field: fields["field"] as string,+ value: fields["value"] as string,+ ...common,+ };+ case "fact":+ return {+ kind,+ topic: fields["topic"] as string,+ principle: fields["principle"] as string,+ premise: Object.freeze([...toValueList(fields["premise"])]),+ level: fields["level"] as string,+ ...common,+ };+ case "skill":+ return {+ kind,+ name: fields["name"] as string,+ body: fields["body"] as string,+ ...common,+ };+ }+}++/**+ * Build a feedback marker from a validated signal token and field set.+ * Shared by both shapes for the same reason as {@link buildFieldMarker}.+ */+function buildFeedbackMarker(input: {+ readonly signal: string;+ readonly fields: Record<string, string | string[]>;+ readonly originLine: number;+ readonly originText: string;+ readonly shape: MarkerShape;+}): ParsedMarker {+ const { signal, fields, originLine, originText, shape } = input;+ return {+ kind: "feedback",+ signal: signal as MarkerSignal,+ topic: fields["topic"] as string,+ principle: fields["principle"] as string,+ ...(typeof fields["scope"] === "string" ? { scope: fields["scope"] } : {}),+ ...(typeof fields["agent"] === "string" ? { agent: fields["agent"] } : {}),+ ...(typeof fields["note"] === "string" ? { note: fields["note"] } : {}),+ ...(fields["source"] !== undefined ? { source: [...toValueList(fields["source"])] } : {}),+ originLine,+ originText,+ shape,+ };}/**@@ -149,7 +422,7 @@ function classifyLoop(input: {if (idCount === 1 && (idValue === null || idValue.length === 0)) return null;if (words.length >= 1 && words[0] === "close" && idCount >= 1) {if (words.length === 1 && idCount === 1 && idValue !== null) {- return { kind: "loop", loop: "close", id: idValue, originLine, originText, shape };+ return { kind: LOOP_KIND, loop: "close", id: idValue, originLine, originText, shape };}// `close` with extra free text or more than one id - ambiguous.return null;@@ -159,7 +432,7 @@ function classifyLoop(input: {const text = words.join(" ").trim();if (text.length === 0) return null;return {- kind: "loop",+ kind: LOOP_KIND,loop: "open",text,...(idValue !== null && idCount === 1 ? { id: idValue } : {}),@@ -177,6 +450,13 @@ export interface MarkerDiscoveryResult {* "@osb feedback ..." with missing / invalid required fields is.*/readonly malformed: number;+ /**+ * The subset of those failures attributable to a named field, in+ * document order. A kind that routes into a store turns its own+ * issues into explicit operator-facing errors; `malformed` still+ * counts every failure, named or not.+ */+ readonly issues: ReadonlyArray<MarkerParseIssue>;}// ββ Inline parser βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ@@ -189,16 +469,22 @@ export interface MarkerDiscoveryResult {* - the remaining grammar per kind:* feedback -> positional `signal` (KNOWN_SIGNALS) then any number* of `key=value` pairs (topic + principle required);- * set -> `key=value` pairs (note + field + value required);* loop -> free text plus an optional `id=` pair, resolved by- * the close-form decision table (see classifyLoop).+ * the close-form decision table (see classifyLoop);+ * any other kind -> `key=value` pairs only, validated against its+ * {@link REQUIRED_FIELDS} row.* - a `value` is either unquoted (no whitespace) or `"..."` with `\"`* and `\\` escapes.** Returns null on any structural deviation - the walker treats null as- * "not a marker" and moves on.+ * "not a marker" and moves on. When the deviation is a named field,+ * `onIssue` additionally receives a {@link MarkerParseIssue}.*/-export function parseInlineMarker(line: string, lineNo: number): ParsedMarker | null {+export function parseInlineMarker(+ line: string,+ lineNo: number,+ onIssue?: MarkerIssueSink,+): ParsedMarker | null {const originText = line;let i = 0;const n = line.length;@@ -220,8 +506,8 @@ export function parseInlineMarker(line: string, lineNo: number): ParsedMarker |if (kindToken === null || !KNOWN_KINDS.has(kindToken)) return null;skipWs();- if (kindToken === "loop") return parseLoopBody();- if (kindToken === "set") return parseSetBody();+ if (kindToken === LOOP_KIND) return parseLoopBody();+ if (isFieldOnlyKind(kindToken)) return parseFieldBody(kindToken);// ----- feedback (positional signal + key=value pairs) -------------------const signalToken = readBareToken();@@ -230,43 +516,48 @@ export function parseInlineMarker(line: string, lineNo: number): ParsedMarker |const fields = collectFields();if (fields === null) return null;- if (!requiredFieldsPresent("feedback", fields)) return null;+ if (+ !fieldsUsable({+ kind: "feedback",+ fields,+ originLine: lineNo,+ shape: "inline",+ onIssue,+ })+ ) {+ return null;+ }- const out: ParsedMarker = {- kind: "feedback",- signal: signalToken as MarkerSignal,- topic: fields["topic"] as string,- principle: fields["principle"] as string,- ...(typeof fields["scope"] === "string" ? { scope: fields["scope"] } : {}),- ...(typeof fields["agent"] === "string" ? { agent: fields["agent"] } : {}),- ...(typeof fields["note"] === "string" ? { note: fields["note"] } : {}),- ...(fields["source"] !== undefined- ? {- source: Array.isArray(fields["source"])- ? [...(fields["source"] as string[])]- : [fields["source"] as string],- }- : {}),+ return buildFeedbackMarker({+ signal: signalToken,+ fields,originLine: lineNo,originText,shape: "inline",- };- return out;+ });// ----- per-kind bodies ---------------------------------------------------- function parseSetBody(): ParsedMarker | null {- const setFields = collectFields();- if (setFields === null) return null;- if (!requiredFieldsPresent("set", setFields)) return null;- return {- kind: "set",- note: setFields["note"] as string,- field: setFields["field"] as string,- value: setFields["value"] as string,+ function parseFieldBody(kind: FieldOnlyKind): ParsedMarker | null {+ const bodyFields = collectFields();+ if (bodyFields === null) return null;+ if (+ !fieldsUsable({+ kind,+ fields: bodyFields,+ originLine: lineNo,+ shape: "inline",+ onIssue,+ })+ ) {+ return null;+ }+ return buildFieldMarker({+ kind,+ fields: bodyFields,originLine: lineNo,originText,shape: "inline",- };+ });}function parseLoopBody(): ParsedMarker | null {@@ -311,14 +602,7 @@ export function parseInlineMarker(line: string, lineNo: number): ParsedMarker |i++; // consume '='const value = readValue();if (value === null) return null;- if (collected[key] === undefined) {- collected[key] = value;- } else {- // Second occurrence: promote to array. (Rare in inline form;- // mainly there so `source=a source=b` works.)- const prev = collected[key];- collected[key] = Array.isArray(prev) ? [...prev, value] : [prev, value];- }+ collectField(collected, key, value);skipWs();}return collected;@@ -386,25 +670,46 @@ export function parseInlineMarker(line: string, lineNo: number): ParsedMarker |}}+/**+ * Record one occurrence of `key`, promoting a repeat to an array. Both+ * shapes funnel through this, so `premise=a premise=b` and two+ * `premise:` lines collect identically, and a repeated single-valued+ * field is visible to {@link fieldsUsable} as ambiguity rather+ * than silently last-winning.+ */+function collectField(+ collected: Record<string, string | string[]>,+ key: string,+ value: string,+): void {+ const prev = collected[key];+ if (prev === undefined) {+ collected[key] = value;+ return;+ }+ collected[key] = Array.isArray(prev) ? [...prev, value] : [prev, value];+}+// ββ Block parser ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ/*** Parse the body of a fenced `osb` block (everything between the open* and close fences, exclusive). The body follows a very small subset* of YAML: `key: value` per line, optional `# comments`, optional- * blank lines. Multi-line `note: |` is supported for the `note` field- * specifically β the only field where multiple lines are common.+ * blank lines. A `key: |` block scalar carries a multi-line value β+ * used by the feedback `note` and by the `skill` body.** Returns null on the same conditions as inline parsing (unknown kind,- * missing required field, bad enum).+ * missing required field, bad enum), reporting named-field rejections+ * through `onIssue`.*/-export function parseBlockMarker(body: string, fenceStartLine: number): ParsedMarker | null {+export function parseBlockMarker(+ body: string,+ fenceStartLine: number,+ onIssue?: MarkerIssueSink,+): ParsedMarker | null {const lines = body.split("\n");const fields: Record<string, string | string[]> = {};- // Occurrence count per key. A structural key appearing twice is- // ambiguous (which value wins?), so we reject it before dispatch rather- // than let the last assignment silently overwrite the earlier one.- const keyCounts: Record<string, number> = {};let i = 0;while (i < lines.length) {const raw = lines[i]!;@@ -419,7 +724,7 @@ export function parseBlockMarker(body: string, fenceStartLine: number): ParsedMacontinue; // tolerate stray lines silently}const key = stripped.slice(0, eq).trim();- let value: string = stripped.slice(eq + 1).trim();+ const value: string = stripped.slice(eq + 1).trim();if (value === "|") {// Multi-line block scalar. Consume indented subsequent lines.const parts: string[] = [];@@ -440,19 +745,17 @@ export function parseBlockMarker(body: string, fenceStartLine: number): ParsedMa}// Strip trailing empty lines that bled from blank rows.while (parts.length > 0 && parts[parts.length - 1] === "") parts.pop();- fields[key] = parts.join("\n");- keyCounts[key] = (keyCounts[key] ?? 0) + 1;+ collectField(fields, key, parts.join("\n"));continue;}- fields[key] = stripQuotes(value);- keyCounts[key] = (keyCounts[key] ?? 0) + 1;+ collectField(fields, key, stripQuotes(value));i++;}const kind = typeof fields["kind"] === "string" ? fields["kind"] : null;if (kind === null || !KNOWN_KINDS.has(kind)) return null;- if (kind === "loop") {+ if (kind === LOOP_KIND) {// Loop block: a required `text:` free-text field plus an optional// `id:` field, run through the same close-form decision table as// the inline form (the id is a field here, not inline in the text).@@ -466,7 +769,7 @@ export function parseBlockMarker(body: string, fenceStartLine: number): ParsedMa// Presence-based (not non-empty-based): an empty `id:` still counts as// one occurrence so classifyLoop rejects it, and a duplicate `id:`// drives idCount > 1 so the ambiguous marker is rejected too.- const idCount = keyCounts["id"] ?? 0;+ const idCount = toValueList(fields["id"]).length;return classifyLoop({words,idValue: idCount === 1 ? idField : null,@@ -477,54 +780,44 @@ export function parseBlockMarker(body: string, fenceStartLine: number): ParsedMa});}- if (kind === "set") {- // Fail-closed on duplicate structural keys: a repeated note / field /- // value would silently last-win and could mutate the wrong note.- if (hasDuplicateKey(keyCounts, ["note", "field", "value"])) return null;- if (!requiredFieldsPresent("set", fields)) return null;- return {- kind: "set",- note: fields["note"] as string,- field: fields["field"] as string,- value: fields["value"] as string,+ if (isFieldOnlyKind(kind)) {+ // Fail-closed on a repeated single-valued required field: a repeated+ // `set` note / field / value would mutate the wrong note, and a+ // repeated `fact` topic would file the conclusion under the wrong rule.+ if (!fieldsUsable({ kind, fields, originLine: fenceStartLine, shape: "block", onIssue })) {+ return null;+ }+ return buildFieldMarker({+ kind,+ fields,originLine: fenceStartLine,originText: body,shape: "block",- };+ });}// Feedback.const signal = typeof fields["signal"] === "string" ? fields["signal"] : null;if (signal === null || !KNOWN_SIGNALS.includes(signal)) return null;- if (!requiredFieldsPresent("feedback", fields)) return null;+ if (+ !fieldsUsable({+ kind: "feedback",+ fields,+ originLine: fenceStartLine,+ shape: "block",+ onIssue,+ })+ ) {+ return null;+ }- return {- kind: "feedback",- signal: signal as MarkerSignal,- topic: fields["topic"] as string,- principle: fields["principle"] as string,- ...(typeof fields["scope"] === "string" ? { scope: fields["scope"] } : {}),- ...(typeof fields["agent"] === "string" ? { agent: fields["agent"] } : {}),- ...(typeof fields["note"] === "string" ? { note: fields["note"] } : {}),- ...(fields["source"] !== undefined- ? {- source: Array.isArray(fields["source"])- ? [...(fields["source"] as string[])]- : [fields["source"] as string],- }- : {}),+ return buildFeedbackMarker({+ signal,+ fields,originLine: fenceStartLine,originText: body,shape: "block",- };-}--/** True when any of `keys` occurred more than once in the block body. */-function hasDuplicateKey(counts: Record<string, number>, keys: ReadonlyArray<string>): boolean {- for (const key of keys) {- if ((counts[key] ?? 0) > 1) return true;- }- return false;+ });}function stripQuotes(s: string): string {@@ -557,6 +850,10 @@ const FENCE_RE = /^```([A-Za-z0-9_-]*)\s*$/;export function discoverMarkersDetailed(content: string): MarkerDiscoveryResult {const lines = content.split("\n");const out: ParsedMarker[] = [];+ const issues: MarkerParseIssue[] = [];+ const onIssue: MarkerIssueSink = (issue) => {+ issues.push(issue);+ };let malformed = 0;let i = 0;while (i < lines.length) {@@ -586,7 +883,7 @@ export function discoverMarkersDetailed(content: string): MarkerDiscoveryResultmalformed++;continue;}- const parsed = parseBlockMarker(bodyLines.join("\n"), fenceStartLineNumber);+ const parsed = parseBlockMarker(bodyLines.join("\n"), fenceStartLineNumber, onIssue);if (parsed) out.push(parsed);else malformed++;}@@ -601,7 +898,7 @@ export function discoverMarkersDetailed(content: string): MarkerDiscoveryResultcontinue;}if (trimmed.startsWith("@osb")) {- const parsed = parseInlineMarker(line, i + 1);+ const parsed = parseInlineMarker(line, i + 1, onIssue);if (parsed) out.push(parsed);else if (looksLikeInlineMarkerAttempt(trimmed)) malformed++;}@@ -610,6 +907,7 @@ export function discoverMarkersDetailed(content: string): MarkerDiscoveryResultreturn Object.freeze({markers: Object.freeze(out),malformed,+ issues: Object.freeze(issues),});}diff --git a/src/core/brain/lineage/crutch.ts b/src/core/brain/lineage/crutch.tsindex 76704719..91e1df6f 100644--- a/src/core/brain/lineage/crutch.ts+++ b/src/core/brain/lineage/crutch.ts@@ -7,16 +7,35 @@* native field but has not merged. Until it ships, this module infers* the parent of a brand-new session id from the lineage ledger.*- * The inference is deliberately conservative - a false stitch (two- * unrelated conversations merged) is strictly worse than a missed- * stitch (status quo). A link happens only when ALL hold:+ * ## Two rungs (signals-that-survive, Unit 9)+ *+ * Resolution here runs two rungs in strict order. The first is DURABLE+ * WORK IDENTITY: when this session and exactly one predecessor declared+ * the same work id, they are the same work item and the link is made on+ * that alone - no freshness bound, no `cwd`, branch or commit predicate,+ * which is precisely what lets resumed work re-attach after a model,+ * account, branch or worktree switch. The identity is DECLARED (see+ * `identity.ts`); nothing is inferred from structure. The second rung is+ * the timing crutch below, unchanged, and it still decides every session+ * that declares nothing.+ *+ * A LANE is a hard separator across both rungs: two entries carrying+ * different declared lane ids never link, whatever else they share, and+ * the refusal is the named `lane-conflict` outcome rather than a silent+ * non-link. It is never a tiebreak - a lane cannot make an otherwise+ * refused link happen, only prevent one.+ *+ * The crutch's own inference is deliberately conservative - a false+ * stitch (two unrelated conversations merged) is strictly worse than a+ * missed stitch (status quo). A link happens only when ALL hold:** 1. the new session has NO history of its own - neither a ledger* line NOR a recorded gap (a session seen before without a link is* a parallel session, and a dropped observation is still a session* that spoke);- * 2. a predecessor exists in the SAME cwd, and no other session has- * already continued from it;+ * 2. a predecessor exists in the SAME cwd, no other session has+ * already continued from it, and it declares no lane that+ * contradicts this session's;* 3. that predecessor's git working state - repo, branch, commit -* matches this session's, and both sides attested one;* 4. the predecessor's LATEST event evidences a compression@@ -51,10 +70,9 @@* abstention is a returned value, never a throw: this path is fail-soft* by contract and must not raise into a lifecycle hook.*- * The 900-second window stays as the freshness bound. Replacing the- * timing crutch with durable work identity is a separate architectural- * unit (kanban t_e6be4f6b); this makes its failures visible and abstains- * where it cannot tell, which is that replacement's prerequisite.+ * The 900-second window stays as the freshness bound for the second+ * rung, and is the ONLY resolution path available when nothing declares+ * an identity - which is why Unit 9 demoted it rather than deleting it.** Removal plan (kanban t_1459706f): once the upstream PR merges and the* deployed Hermes emits `parent_session_id`, delete this file and every@@ -89,6 +107,20 @@ export const CRUTCH_ABSTENTION = Object.freeze({stale: "stale",/** Candidates were fresh but showed no compression boundary, or their git state was unattested. */evidenceMissing: "evidence-missing",+ /**+ * A predecessor was available and carried a DIFFERENT declared lane.+ * The hard separator fired: this is a refusal, never a near miss, and+ * it is named so a lane typo is distinguishable from an absence of+ * history (Unit 9).+ */+ laneConflict: "lane-conflict",+ /**+ * Several predecessors declare THIS session's work id under the same+ * lane. The identity rung refuses for the same reason `ambiguous`+ * does - a shared id that names more than one predecessor cannot pick+ * one without guessing (Unit 9).+ */+ workAmbiguous: "work-ambiguous",} as const);export type CrutchAbstentionReason = (typeof CRUTCH_ABSTENTION)[keyof typeof CRUTCH_ABSTENTION];@@ -128,6 +160,14 @@ export interface CrutchResolveInput {* behaviour and the only reason the field is optional.*/readonly gapSessionIds?: ReadonlySet<string>;+ /**+ * DECLARED work id of THIS session (Unit 9), resolved at the capture+ * boundary. Absent means the identity rung has nothing to match on and+ * the window rung decides alone - which is the pre-Unit-9 behaviour.+ */+ readonly workId?: string;+ /** DECLARED lane of THIS session. The hard separator, at both rungs. */+ readonly laneId?: string;}/**@@ -140,11 +180,12 @@ export interface CrutchResolveInput {type AttestationMatch = "match" | "mismatch" | "unattested";/** Which predicate turned a candidate away. Ordered by how far it got. */-type RejectionKind = "claimed" | "workspace" | "stale" | "evidence";+type RejectionKind = "claimed" | "lane" | "workspace" | "stale" | "evidence";/**- * Infer lineage for a session from the ledger, or abstain with a named- * reason. CRUTCH(t_1459706f). Never throws.+ * Resolve lineage for a session from the ledger, or abstain with a named+ * reason. Runs the declared-identity rung first and the timing crutch+ * second. CRUTCH(t_1459706f). Never throws.*/export function resolveCrutchLineage(input: CrutchResolveInput): CrutchOutcome {const { sessionId, ledger, nowMs } = input;@@ -178,6 +219,17 @@ export function resolveCrutchLineage(input: CrutchResolveInput): CrutchOutcome {0,);}+ // A compaction boundary has exactly one successor, so a predecessor+ // another session already continued from is spoken for. Computed once+ // and shared by both rungs - the property is the same at each.+ const claimed = claimedPredecessors(ledger, sessionId);++ // RUNG 1 (Unit 9): durable declared identity. It returns null when it+ // has nothing to decide on, which is when the window rung below runs.+ const byIdentity = resolveDeclaredIdentity(input, claimed);+ if (byIdentity !== null) return byIdentity;++ // RUNG 2: the timing crutch. Unchanged apart from the lane separator.const cwd = input.cwd;if (cwd === undefined || cwd.length === 0) {return abstain(CRUTCH_ABSTENTION.noWorkspace, "the host reported no working directory", 0);@@ -186,12 +238,12 @@ export function resolveCrutchLineage(input: CrutchResolveInput): CrutchOutcome {const survivors: LineageLedgerEntry[] = [];const rejected: Record<RejectionKind, number> = {claimed: 0,+ lane: 0,workspace: 0,stale: 0,evidence: 0,};let considered = 0;- const claimed = claimedPredecessors(ledger, sessionId);for (const entry of ledger.values()) {if (entry.sessionId === sessionId) continue;@@ -200,8 +252,6 @@ export function resolveCrutchLineage(input: CrutchResolveInput): CrutchOutcome {if (entry.cwd !== cwd) continue;considered++;- // A compaction boundary has exactly one successor, so a- // predecessor another session already continued from is spoken for.// Without this, an A -> B -> C chain looks ambiguous from C: both A// and B are fresh, evidenced and in the same directory, and only B// is actually available.@@ -210,6 +260,15 @@ export function resolveCrutchLineage(input: CrutchResolveInput): CrutchOutcome {continue;}+ // The lane separator (Unit 9) applies to this rung too. Without it a+ // predecessor the identity rung just refused could be re-linked here+ // on nothing but a shared directory and a fresh timestamp, which+ // would make "never link across lanes" true of one rung only.+ if (lanesConflict(entry.laneId, input.laneId)) {+ rejected.lane++;+ continue;+ }+// Rule 3, part one: an attested disagreement about repo, branch or// commit is decisive - this is a different working state.const attestation = compareWorkspace(entry.workspace, input.workspace);@@ -249,7 +308,20 @@ export function resolveCrutchLineage(input: CrutchResolveInput): CrutchOutcome {if (predecessor === undefined) {return abstain(nearestMiss(rejected), summarize(considered, rejected), considered);}+ return linkTo(predecessor, CRUTCH_SOURCE);+}++/** Lineage source recorded by each of the two rungs. */+const IDENTITY_SOURCE = "identity" as const;+const CRUTCH_SOURCE = "crutch" as const;+/**+ * Continue a predecessor's conversation. Shared by both rungs so the+ * root/depth inheritance is written once: a predecessor that is itself+ * a continuation passes on its ROOT, not its own id, and its depth+ * count continues rather than restarting.+ */+function linkTo(predecessor: LineageLedgerEntry, source: SessionLineage["source"]): CrutchLinked {const parentLineage = predecessor.lineage;return Object.freeze({kind: "linked" as const,@@ -257,11 +329,89 @@ export function resolveCrutchLineage(input: CrutchResolveInput): CrutchOutcome {rootId: parentLineage !== undefined ? parentLineage.rootId : predecessor.sessionId,parentId: predecessor.sessionId,depth: (parentLineage !== undefined ? parentLineage.depth : 0) + 1,- source: "crutch" as const,+ source,}),});}+/**+ * RUNG 1: link on a DECLARED work id alone (Unit 9).+ *+ * Deliberately applies none of the crutch's predicates. Freshness, cwd,+ * repo, branch, commit and compression evidence are all proxies for "is+ * this the same work" that the declaration answers directly - so a+ * resumed item re-attaches after a switch that would fail every one of+ * them. What it does NOT relax: the lane separator, the spoken-for rule,+ * and the refusal to guess between several candidates.+ *+ * "Declared" is load-bearing and is enforced UPSTREAM, in `identity.ts`:+ * a payload or environment declaration reaches here unbounded, while an+ * identity merely INHERITED from a worktree marker stops being supplied+ * once the marker passes its staleness bound. Without that, this rung's+ * deliberate absence of a freshness predicate would let one directory's+ * first declaration chain every later conversation there onto it.+ *+ * Returns `null` when this rung has nothing to decide - the session+ * declared no work id, or no predecessor declared the same one - which+ * is the only path down to the window rung. Every other outcome is+ * terminal, including the two refusals: falling through after naming a+ * lane conflict would let the window rung silently re-link what the+ * separator just refused.+ */+function resolveDeclaredIdentity(+ input: CrutchResolveInput,+ claimed: ReadonlySet<string>,+): CrutchOutcome | null {+ const workId = input.workId;+ if (workId === undefined || workId.length === 0) return null;++ const survivors: LineageLedgerEntry[] = [];+ let considered = 0;+ let laneRejected = 0;+ for (const entry of input.ledger.values()) {+ if (entry.sessionId === input.sessionId) continue;+ if (entry.workId !== workId) continue;+ considered++;+ // Spoken for BEFORE lane, and the order is load-bearing: a+ // predecessor another session already continued from is not+ // available to anyone, so counting it as a lane refusal would raise+ // a TERMINAL `lane-conflict` abstention over a candidate that was+ // never a candidate - and that abstention hides the legitimate+ // window-rung link below it.+ if (claimed.has(entry.sessionId)) continue;+ if (lanesConflict(entry.laneId, input.laneId)) {+ laneRejected++;+ continue;+ }+ survivors.push(entry);+ }++ // Ambiguity abstains here for the same reason it does at the window+ // rung: a shared id naming two predecessors cannot pick one without+ // guessing, and a wrong-but-plausible resume is worse than none.+ if (survivors.length > 1) {+ return abstain(+ CRUTCH_ABSTENTION.workAmbiguous,+ `${survivors.length} predecessors declare work id ${workId} in this lane; ` ++ "refused rather than resolved by recency",+ considered,+ );+ }+ const predecessor = survivors[0];+ if (predecessor !== undefined) return linkTo(predecessor, IDENTITY_SOURCE);+ if (laneRejected > 0) {+ return abstain(+ CRUTCH_ABSTENTION.laneConflict,+ `${laneRejected} of ${considered} predecessors declaring work id ${workId} ` ++ "carry a different lane; lanes never link",+ considered,+ );+ }+ // Either nothing declared this work id, or every match was already+ // continued from. Both leave the window rung to decide and report.+ return null;+}+function abstain(reason: CrutchAbstentionReason,detail: string,@@ -277,21 +427,43 @@ function abstain(* furthest tells the operator what actually stood between two sessions.*/function nearestMiss(rejected: Record<RejectionKind, number>): CrutchAbstentionReason {+ // The lane separator outranks the near-miss ordering: it is a+ // DECLARED refusal rather than a predicate a candidate fell short of,+ // and reporting it as "no candidate" would hide the one cause an+ // operator can act on directly.+ if (rejected.lane > 0) return CRUTCH_ABSTENTION.laneConflict;if (rejected.evidence > 0) return CRUTCH_ABSTENTION.evidenceMissing;if (rejected.stale > 0) return CRUTCH_ABSTENTION.stale;return CRUTCH_ABSTENTION.noCandidate;}+/**+ * One English line stating the counts behind a refusal. The lane clause+ * appears only when a lane actually refused something: lanes are opt-in,+ * and reporting "0 in another lane" to a vault where nobody declares one+ * changes the operator-visible line for a feature that is not in use.+ */function summarize(considered: number, rejected: Record<RejectionKind, number>): string {if (considered === 0) return "no predecessor was recorded in this working directory";return (`no predecessor survived: ${considered} examined ` +- `(${rejected.claimed} already continued, ${rejected.workspace} in another working state, ` ++ `(${rejected.claimed} already continued, ` ++ (rejected.lane > 0 ? `${rejected.lane} in another lane, ` : "") ++ `${rejected.workspace} in another working state, ` +`${rejected.stale} outside the freshness window, ` +`${rejected.evidence} without usable evidence)`);}+/**+ * True when two DECLARED lanes disagree. One side silent is not a+ * conflict: a lane is a separator a caller opts into, so an undeclared+ * lane must leave resolution exactly as it was before lanes existed.+ */+function lanesConflict(candidate: string | undefined, session: string | undefined): boolean {+ return candidate !== undefined && session !== undefined && candidate !== session;+}+/*** Session ids that some OTHER ledger entry already names as its parent.* Membership means the compaction boundary out of that session has beendiff --git a/src/core/brain/lineage/identity.ts b/src/core/brain/lineage/identity.tsnew file mode 100644index 00000000..297a2082--- /dev/null+++ b/src/core/brain/lineage/identity.ts@@ -0,0 +1,439 @@+/**+ * Declared work identity (signals-that-survive, Unit 9; kanban+ * t_e6be4f6b).+ *+ * Session continuation had two durable signals - the lineage the host+ * declared on the payload, and a fifteen-minute freshness window+ * (`CRUTCH_LINK_WINDOW_MS`). Neither survives a resumption: a work item+ * picked up again after a model, account, branch or worktree switch is+ * outside the window and in a different working state, so the resolver+ * correctly refuses to link it and the continuity is lost. This module+ * supplies the third signal - a work id and a lane id - which the+ * resolver ranks ABOVE the window because it does not decay.+ *+ * ## Declared, never derived+ *+ * Every value here is something a host, an operator or an earlier+ * declaration WROTE DOWN. Nothing fingerprints a git remote, a+ * merge-base or a gitdir, and nothing accumulates a union of the+ * identities it has seen. The vault is Syncthing-replicated with no+ * arbiter: a cumulative registry would be effectively irreversible+ * there, and a structurally derived identity would silently redefine+ * which sessions are "the same work" whenever the structure moved.+ *+ * ## Three rungs, in strict precedence+ *+ * 1. the HOST PAYLOAD (`work_id` / `lane_id` on the lifecycle hook) -+ * the only rung that can distinguish two concurrent work items in+ * one directory, so it wins;+ * 2. the ENVIRONMENT (`OPEN_SECOND_BRAIN_WORK_ID` and the lane twin),+ * then the CONFIG KEY (`work_id` / `lane_id`) - one shell, one work+ * item, which is how an operator declares identity to a host that+ * does not;+ * 3. the per-worktree MARKER under the Brain state directory, which is+ * the last declaration this worktree saw, persisted verbatim.+ *+ * The first rung that declares EITHER field supplies BOTH - and the+ * environment and the config file are two SEPARATE rungs for exactly+ * that reason, never one rung with a per-field fallback. A lane taken+ * from one source and a work id from another would compose an identity+ * nobody declared, and because a lane is a hard separator that composite+ * could refuse a link both declarations agreed on.+ *+ * ## One marker file per worktree, bounded in time and in count+ *+ * The marker is keyed by the hash of the worktree path and holds what was+ * declared plus the INSTANT it was declared. One file per worktree rather+ * than one shared table: a replicated table has to be merged, and merging+ * declarations is exactly the union registry this unit refuses to build.+ * Two devices editing the same worktree's marker produce a Syncthing+ * conflict file beside it, which is visible and reversible.+ *+ * Two bounds apply to this rung, and only to this rung:+ *+ * - STALENESS. A marker older than {@link WORK_IDENTITY_MARKER_MAX_AGE_MS}+ * declares nothing. Rungs 1 and 2 stay unbounded: a payload or an+ * environment declaration is an explicit act by something that is+ * live right now, so it must still re-attach work resumed after a+ * month. The marker is not an act - it is what the directory last+ * saw, inherited by every later session there with no expiry - so+ * without a bound each unrelated conversation in that directory+ * chains onto the previous one and `depth` grows without end. This+ * module holds that a FALSE stitch is strictly worse than a missed+ * one, and an indefinite inherited stitch is the false kind.+ *+ * The instant is refreshed by a live declaration (see+ * {@link recordWorkIdentityMarker}), so continuous declared work+ * keeps inheriting; only a directory nothing has declared in for+ * longer than the bound goes quiet.+ *+ * - COUNT. The directory holds at most+ * {@link WORK_IDENTITY_MARKER_MAX_FILES} files, compacted in the+ * ledger's idiom (a cap that triggers, a retained remainder) so a CI+ * runner or a `git worktree` flow checking out to a fresh path per+ * job cannot leave one permanent file per job behind.+ *+ * ## Clearing a marker+ *+ * {@link clearWorkIdentityMarker} removes one worktree's marker, and the+ * file it removes is the one {@link workIdentityMarkerPath} names - so+ * deleting that path by hand (or the whole `work-identity` directory) is+ * an equally supported way to make the rung forget. Nothing else in the+ * system depends on a marker existing: the two rungs above it and the+ * timing crutch below are untouched by its absence.+ */++import { createHash } from "node:crypto";+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync } from "node:fs";+import { join } from "node:path";++import { discoverConfig } from "../../config.ts";+import { atomicWriteFileSync } from "../../fs-atomic.ts";+import { ensureInsideVault } from "../paths.ts";+import { assertVaultIdentityForWrite } from "../vault-identity.ts";+import { brainStateDirPath } from "./ledger.ts";++/** Where a declaration was read from. Ordered by precedence. */+export const WORK_IDENTITY_SOURCE = Object.freeze({+ /** The lifecycle hook payload named it. */+ payload: "payload",+ /** An environment variable or the plugin config key named it. */+ environment: "environment",+ /** The per-worktree marker recorded by an earlier declaration. */+ marker: "marker",+} as const);++export type WorkIdentitySource = (typeof WORK_IDENTITY_SOURCE)[keyof typeof WORK_IDENTITY_SOURCE];++/**+ * One resolved declaration. At least one of the two fields is present -+ * a result with neither is not a declaration and is returned as `null`,+ * so a caller can never mistake an empty identity for a declared one.+ */+export interface DeclaredWorkIdentity {+ readonly workId?: string;+ readonly laneId?: string;+ readonly source: WorkIdentitySource;+}++/** Injected clock, shared by every entry point that ages a marker. */+export interface WorkIdentityClockOptions {+ /** Epoch ms. Defaults to the wall clock. */+ readonly nowMs?: number;+}++export interface ResolveWorkIdentityInput extends WorkIdentityClockOptions {+ readonly vault: string;+ /** `work_id` as the lifecycle hook payload carried it. */+ readonly payloadWorkId?: string;+ /** `lane_id` as the lifecycle hook payload carried it. */+ readonly payloadLaneId?: string;+ /** Working directory of the session; the key of the marker rung. */+ readonly worktree?: string;+ /** Injected environment. Defaults to the process environment. */+ readonly env?: Readonly<Record<string, string | undefined>>;+ /** Plugin config file, threaded to `discoverConfig`. */+ readonly configPath?: string;+}++/** What a caller declares when it records a marker. */+export interface WorkIdentityDeclaration {+ readonly workId?: string;+ readonly laneId?: string;+}++/** Whether {@link recordWorkIdentityMarker} changed anything on disk. */+export const WORK_IDENTITY_MARKER_STATUS = Object.freeze({+ written: "written",+ unchanged: "unchanged",+} as const);++export type WorkIdentityMarkerStatus =+ (typeof WORK_IDENTITY_MARKER_STATUS)[keyof typeof WORK_IDENTITY_MARKER_STATUS];++const WORK_ID_ENV_KEY = "OPEN_SECOND_BRAIN_WORK_ID";+const LANE_ID_ENV_KEY = "OPEN_SECOND_BRAIN_LANE_ID";+const WORK_ID_CONFIG_KEY = "work_id";+const LANE_ID_CONFIG_KEY = "lane_id";++/** Directory holding one marker file per worktree. */+const MARKER_DIR = "work-identity";+const MARKER_FILE_SUFFIX = ".json";++/**+ * How long an INHERITED declaration keeps speaking for a worktree.+ *+ * Matched to the lineage gap sidecar's retention window: both bound how+ * long a point-in-time observation keeps being treated as current. A week+ * is long enough to carry work across a weekend or a switch of machine -+ * the resumption this rung exists for - and short enough that a directory+ * nobody has declared anything in stops adopting new conversations into+ * old work.+ */+export const WORK_IDENTITY_MARKER_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;++/**+ * How often a live, UNCHANGED declaration rewrites its marker.+ *+ * The instant has to move forward or continuous declared work would go+ * stale mid-flight, but rewriting on every lifecycle event would churn a+ * Syncthing-replicated file many times a minute for no new information.+ * One hour keeps the recorded instant accurate to within an hour of a+ * seven-day bound - three orders of magnitude of slack.+ */+export const WORK_IDENTITY_MARKER_REFRESH_MS = 60 * 60 * 1000;++/**+ * Marker files retained. The pair is the ledger's compaction idiom: the+ * cap is what TRIGGERS a sweep, the retained count is what survives one,+ * so the sweep is amortized rather than run on every write.+ */+export const WORK_IDENTITY_MARKER_MAX_FILES = 256;+const RETAIN_WORK_IDENTITY_MARKERS = 128;++/** On-disk marker shape. `worktree` is the key, restated so the file is legible. */+interface WorkIdentityMarkerFile {+ readonly worktree: string;+ readonly wid?: string;+ readonly lane?: string;+ /** ISO-8601 instant of the declaration this file records. */+ readonly at?: string;+}++/**+ * Resolve the declaration that applies to this session, or `null` when+ * no rung declares one. The rungs are tried in the order documented+ * above and the first that yields anything is taken whole.+ */+export function resolveWorkIdentity(input: ResolveWorkIdentityInput): DeclaredWorkIdentity | null {+ const payload = compose(input.payloadWorkId, input.payloadLaneId, WORK_IDENTITY_SOURCE.payload);+ if (payload !== null) return payload;++ // The shell and the config file are two rungs, tried in that order and+ // each taken WHOLE. A per-field fallback would let a work id from the+ // shell compose with a lane from the file - the composite identity+ // nobody declared that the rung boundary exists to prevent.+ const env = input.env ?? process.env;+ const declaredEnv = compose(+ env[WORK_ID_ENV_KEY],+ env[LANE_ID_ENV_KEY],+ WORK_IDENTITY_SOURCE.environment,+ );+ if (declaredEnv !== null) return declaredEnv;++ const config = discoverConfig(input.configPath).data;+ const declaredConfig = compose(+ config[WORK_ID_CONFIG_KEY],+ config[LANE_ID_CONFIG_KEY],+ WORK_IDENTITY_SOURCE.environment,+ );+ if (declaredConfig !== null) return declaredConfig;++ if (input.worktree === undefined) return null;+ return readWorkIdentityMarker(input.vault, input.worktree, {+ nowMs: input.nowMs ?? Date.now(),+ });+}++/** Path of the marker file for one worktree. */+export function workIdentityMarkerPath(vault: string, worktree: string): string {+ const file = `${createHash("sha256").update(worktree, "utf8").digest("hex")}${MARKER_FILE_SUFFIX}`;+ return ensureInsideVault(join(brainStateDirPath(vault), MARKER_DIR, file), vault);+}++/**+ * Read the marker recorded for one worktree. Fail-soft like every other+ * read on this path: a missing, unreadable or unparseable marker is+ * simply no declaration, which lets the rung below decide rather than+ * raising into a lifecycle hook. A marker whose recorded worktree is not+ * the one being asked about describes different work and is not read.+ *+ * A marker older than {@link WORK_IDENTITY_MARKER_MAX_AGE_MS}, and one+ * that records no instant at all, declare nothing. The second case is+ * deliberate and asymmetric with the gap sidecar's "an undatable record+ * never expires": there, an unexpiring record over-REPORTS; here it would+ * over-LINK, and a false stitch is the outcome this ladder refuses.+ */+export function readWorkIdentityMarker(+ vault: string,+ worktree: string,+ opts: WorkIdentityClockOptions = {},+): DeclaredWorkIdentity | null {+ const marker = readMarkerFile(workIdentityMarkerPathSafe(vault, worktree));+ if (marker === null || marker.worktree !== worktree) return null;+ if (markerAgeMs(marker, opts.nowMs ?? Date.now()) === null) return null;+ return compose(marker.wid, marker.lane, WORK_IDENTITY_SOURCE.marker);+}++/**+ * Forget one worktree's marker. Returns whether a marker was there to+ * remove, so "cleared" and "there was nothing to clear" stay+ * distinguishable; both are success. Fail-soft like the rest of this+ * path - an unremovable file reports `false` rather than raising into a+ * lifecycle hook.+ */+export function clearWorkIdentityMarker(vault: string, worktree: string): boolean {+ try {+ const path = workIdentityMarkerPath(vault, worktree);+ if (!existsSync(path)) return false;+ unlinkSync(path);+ return true;+ } catch {+ return false;+ }+}++/** The marker path, or `null` when it cannot be formed (guard refusal). */+function workIdentityMarkerPathSafe(vault: string, worktree: string): string | null {+ try {+ return workIdentityMarkerPath(vault, worktree);+ } catch {+ return null;+ }+}++/** Parse one marker file, or `null` when it is absent or unusable. */+function readMarkerFile(path: string | null): WorkIdentityMarkerFile | null {+ if (path === null) return null;+ let parsed: unknown;+ try {+ if (!existsSync(path)) return null;+ parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;+ } catch {+ return null;+ }+ if (parsed === null || typeof parsed !== "object") return null;+ const marker = parsed as WorkIdentityMarkerFile;+ return typeof marker.worktree === "string" ? marker : null;+}++/**+ * Age of a marker in ms, or `null` when it is undatable or past the+ * staleness bound - the two cases that mean "this declares nothing".+ */+function markerAgeMs(marker: WorkIdentityMarkerFile, nowMs: number): number | null {+ const declaredAt = typeof marker.at === "string" ? Date.parse(marker.at) : Number.NaN;+ if (!Number.isFinite(declaredAt)) return null;+ const age = nowMs - declaredAt;+ return age > WORK_IDENTITY_MARKER_MAX_AGE_MS ? null : age;+}++/**+ * Persist a declaration as this worktree's marker, so a later session+ * that the host does not tell about it still resolves the same work+ * item. Records the declaration VERBATIM - it never merges with what the+ * file already held, because a merge is the accumulating registry this+ * module refuses to build.+ *+ * The recorded instant is what the read path ages against, so only a+ * caller holding a LIVE declaration may call this - `session-lifecycle.ts`+ * skips a marker-sourced identity for exactly that reason. Handing back+ * what the marker itself supplied would refresh it forever and the+ * staleness bound would mean nothing.+ *+ * Throws only where a write genuinely cannot be trusted (the vault+ * identity guard, an unwritable state directory); the capture boundary+ * treats a marker failure as a non-blocker, exactly as it treats the+ * other enhancements that ride the lifecycle hook.+ */+export function recordWorkIdentityMarker(+ vault: string,+ worktree: string,+ declaration: WorkIdentityDeclaration,+ opts: WorkIdentityClockOptions = {},+): WorkIdentityMarkerStatus {+ assertVaultIdentityForWrite(vault);+ const nowMs = opts.nowMs ?? Date.now();+ const wid = declaredValue(declaration.workId);+ const lane = declaredValue(declaration.laneId);+ const path = workIdentityMarkerPath(vault, worktree);+ // An unchanged declaration still refreshes the recorded instant, so+ // work that keeps being declared keeps being inheritable - but only+ // once per refresh interval, so a replicated file is not rewritten on+ // every lifecycle event to say the same thing.+ const existing = readMarkerFile(path);+ if (+ existing !== null &&+ existing.worktree === worktree &&+ existing.wid === wid &&+ existing.lane === lane+ ) {+ const age = markerAgeMs(existing, nowMs);+ if (age !== null && age >= 0 && age < WORK_IDENTITY_MARKER_REFRESH_MS) {+ return WORK_IDENTITY_MARKER_STATUS.unchanged;+ }+ }+ const body: WorkIdentityMarkerFile = {+ worktree,+ ...(wid !== undefined ? { wid } : {}),+ ...(lane !== undefined ? { lane } : {}),+ at: new Date(nowMs).toISOString(),+ };+ const dir = join(brainStateDirPath(vault), MARKER_DIR);+ mkdirSync(dir, { recursive: true });+ atomicWriteFileSync(path, `${JSON.stringify(body)}\n`);+ boundMarkerDirectory(dir, path, nowMs);+ return WORK_IDENTITY_MARKER_STATUS.written;+}++/**+ * Keep the marker directory bounded, in the ledger's compaction idiom:+ * the cap TRIGGERS a sweep, the retained count is what survives one, so+ * the directory is not re-read on every write.+ *+ * What goes first is what has least to say: markers that are expired or+ * undatable (they already declare nothing) before live ones, and among+ * live ones the oldest. The marker just written is never a candidate.+ * Best-effort - the bound is hygiene, and a directory that cannot be+ * swept must not cost a lifecycle hook its capture.+ */+function boundMarkerDirectory(dir: string, keepPath: string, nowMs: number): void {+ try {+ const names = readdirSync(dir).filter((name) => name.endsWith(MARKER_FILE_SUFFIX));+ if (names.length <= WORK_IDENTITY_MARKER_MAX_FILES) return;+ const entries = names+ .map((name) => join(dir, name))+ .filter((path) => path !== keepPath)+ .map((path) => {+ const marker = readMarkerFile(path);+ return { path, age: marker === null ? null : markerAgeMs(marker, nowMs) };+ });+ // Expired / undatable first (age null), then oldest first.+ const ordered = entries.toSorted((a, b) => {+ if (a.age === null || b.age === null) return a.age === b.age ? 0 : a.age === null ? -1 : 1;+ return b.age - a.age;+ });+ const removeCount = names.length - RETAIN_WORK_IDENTITY_MARKERS;+ for (const entry of ordered.slice(0, removeCount)) unlinkSync(entry.path);+ } catch {+ // Best-effort; the marker itself is already written.+ }+}++/**+ * Build a declaration from one rung's pair, or `null` when that rung+ * declared neither field. Blank is not a declaration: a host that sends+ * an empty string has said nothing, and treating it as a value would+ * make every such session share one identity.+ */+function compose(+ workId: string | undefined,+ laneId: string | undefined,+ source: WorkIdentitySource,+): DeclaredWorkIdentity | null {+ const wid = declaredValue(workId);+ const lane = declaredValue(laneId);+ if (wid === undefined && lane === undefined) return null;+ return Object.freeze({+ ...(wid !== undefined ? { workId: wid } : {}),+ ...(lane !== undefined ? { laneId: lane } : {}),+ source,+ });+}++/** A trimmed non-empty declaration, or `undefined`. */+function declaredValue(value: string | undefined): string | undefined {+ if (typeof value !== "string") return undefined;+ const trimmed = value.trim();+ return trimmed.length > 0 ? trimmed : undefined;+}diff --git a/src/core/brain/lineage/ledger.ts b/src/core/brain/lineage/ledger.tsindex 69d720e6..71b9648e 100644--- a/src/core/brain/lineage/ledger.ts+++ b/src/core/brain/lineage/ledger.ts@@ -51,6 +51,17 @@* coded its field list - silently dropped any field a later writer* added. Verbatim retention removes all four at once, including the* last as a class of bug rather than an instance.+ *+ * ## Declared work identity (signals-that-survive, Unit 9)+ *+ * A line may also carry a DECLARED work id and lane id (`wid` / `lane`),+ * sourced at the capture boundary by `identity.ts` and never derived+ * here. They are the durable half of continuation: the crutch's freshness+ * window expires, a work id does not. Both are optional and are omitted+ * when blank, so a ledger written by a host that declares nothing is+ * byte-identical to the one this module wrote before they existed - and+ * because the hash covers the line body by REMOVAL of the chain fields,+ * they ride the integrity chain without any change to it.*/import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, unlinkSync } from "node:fs";@@ -186,6 +197,15 @@ export interface LineageObservation {* record.*/readonly workspace?: GitWorkspaceIdentity;+ /**+ * DECLARED work identity for this observation (signals-that-survive,+ * Unit 9). Never derived - see `identity.ts` for the three rungs it is+ * sourced from. Absent when nothing declared one, which is why every+ * pre-existing line is byte-identical.+ */+ readonly workId?: string;+ /** DECLARED lane. A hard separator between work items, never a tiebreak. */+ readonly laneId?: string;}export interface LineageLedgerEntry {@@ -205,10 +225,29 @@ export interface LineageLedgerEntry {* what the session already attested.*/readonly workspace?: GitWorkspaceIdentity;+ /**+ * Last declared work identity for the session, carried forward from+ * the newest observation that declared one - for the same reason+ * `cwd` and `workspace` are: an event that arrived without the+ * declaration does not retract it.+ */+ readonly workId?: string;+ /** Last declared lane for the session. See {@link LineageObservation.laneId}. */+ readonly laneId?: string;}export type LineageLedgerState = ReadonlyMap<string, LineageLedgerEntry>;+/**+ * The Brain state directory: the dot-directory this module's ledger, its+ * gap sidecar and the work-identity markers all live under. Exported so+ * a sibling state file resolves through one definition rather than+ * re-deriving the relative path.+ */+export function brainStateDirPath(vault: string): string {+ return ensureInsideVault(join(vault, STATE_DIR_REL), vault);+}+export function sessionLineageLedgerPath(vault: string): string {return ensureInsideVault(join(vault, STATE_DIR_REL, LEDGER_FILE), vault);}@@ -236,6 +275,10 @@ export interface LedgerLine {readonly repo?: string;readonly branch?: string;readonly commit?: string;+ /** Declared work id (Unit 9). Absent unless a rung declared one. */+ readonly wid?: string;+ /** Declared lane id (Unit 9). Absent unless a rung declared one. */+ readonly lane?: string;/** Monotonic sequence number (Unit D). Absent on pre-chain lines. */readonly seq?: number;/** Chain hash of the preceding line; `null` at a chain anchor. */@@ -305,6 +348,31 @@ function workspaceFields(};}+/**+ * Project a declared work identity onto its line fields (Unit 9). A+ * blank declaration is not a declaration: it is omitted, so a host that+ * sends an empty string leaves the line byte-identical to one that sent+ * nothing at all.+ */+function identityFields(+ workId: string | undefined,+ laneId: string | undefined,+): Pick<LedgerLine, "wid" | "lane"> {+ const wid = declared(workId);+ const lane = declared(laneId);+ return {+ ...(wid !== undefined ? { wid } : {}),+ ...(lane !== undefined ? { lane } : {}),+ };+}++/** A trimmed non-empty declaration, or `undefined`. */+function declared(value: string | undefined): string | undefined {+ if (typeof value !== "string") return undefined;+ const trimmed = value.trim();+ return trimmed.length > 0 ? trimmed : undefined;+}+/** Inverse of {@link workspaceFields}; `undefined` when nothing was attested. */function readWorkspace(line: LedgerLine): GitWorkspaceIdentity | undefined {const repo = typeof line.repo === "string" ? line.repo : null;@@ -330,6 +398,7 @@ function toLine(obs: LineageObservation): LedgerLine {}: {}),...workspaceFields(obs.workspace),+ ...identityFields(obs.workId, obs.laneId),};}@@ -620,6 +689,8 @@ function buildState(lines: ReadonlyArray<LedgerLine>): Map<string, LineageLedger}): prev?.lineage;const workspace = readWorkspace(line) ?? prev?.workspace;+ const workId = declared(line.wid) ?? prev?.workId;+ const laneId = declared(line.lane) ?? prev?.laneId;state.set(line.sid, {sessionId: line.sid,firstSeenMs: prev === undefined ? atMs : Math.min(prev.firstSeenMs, atMs),@@ -633,6 +704,8 @@ function buildState(lines: ReadonlyArray<LedgerLine>): Map<string, LineageLedgercompressionEvidence: line.ce === true,...(lineage !== undefined ? { lineage } : {}),...(workspace !== undefined ? { workspace } : {}),+ ...(workId !== undefined ? { workId } : {}),+ ...(laneId !== undefined ? { laneId } : {}),});}return state;diff --git a/src/core/brain/lineage/resolve.ts b/src/core/brain/lineage/resolve.tsindex b22fc763..f37eb5a9 100644--- a/src/core/brain/lineage/resolve.ts+++ b/src/core/brain/lineage/resolve.ts@@ -2,9 +2,13 @@* Session-lineage resolution (continuity-hygiene-freshness suite).** Single resolution point for "which conversation does this session id- * belong to". Precedence: native payload fields, then the interim- * ledger crutch, then flat. See `types.ts` for the contract and- * `crutch.ts` for the conservative inference rules.+ * belong to". Precedence: native payload fields, then the DECLARED work+ * identity (signals-that-survive, Unit 9), then the interim ledger+ * crutch, then flat. The last two rungs both live in `crutch.ts` and are+ * reached through one call, so the ledger is walked once and the+ * fail-closed guards - a session with history of its own, a predecessor+ * already continued from - are written once and apply to both. See+ * `types.ts` for the contract.** Two entry points, following the sibling pattern this repository uses* wherever a diagnostic channel is grafted onto an established@@ -48,10 +52,10 @@ export interface ResolveLineageOptions {export interface SessionLineageResolution {readonly lineage: SessionLineage;/**- * The crutch's named outcome, present only when the crutch actually- * ran (a ledger was supplied and the native payload did not already- * decide). A `linked` outcome IS the lineage; an `abstained` one is- * why continuation was refused.+ * The named outcome of the ledger rungs - declared identity, then the+ * crutch - present only when they actually ran (a ledger was supplied+ * and the native payload did not already decide). A `linked` outcome+ * IS the lineage; an `abstained` one is why continuation was refused.*/readonly crutch?: CrutchOutcome;}@@ -70,6 +74,11 @@ const REPORTABLE_ABSTENTIONS: ReadonlySet<string> = new Set([CRUTCH_ABSTENTION.ambiguous,CRUTCH_ABSTENTION.stale,CRUTCH_ABSTENTION.evidenceMissing,+ // Unit 9. Both mean a DECLARED identity named a predecessor and the+ // link was still refused, which is the loudest form of "available and+ // refused" this resolver can report.+ CRUTCH_ABSTENTION.laneConflict,+ CRUTCH_ABSTENTION.workAmbiguous,]);function readId(value: string | null | undefined): string | null {@@ -134,8 +143,8 @@ export function resolveSessionLineageDetailed(};}- // Interim inference for hosts without native lineage fields.- // CRUTCH(t_1459706f).+ // Declared work identity (Unit 9), then the interim inference for+ // hosts without native lineage fields. CRUTCH(t_1459706f).if (opts.ledger !== undefined) {const outcome = resolveCrutchLineage({sessionId,@@ -144,6 +153,8 @@ export function resolveSessionLineageDetailed(nowMs: opts.nowMs ?? 0,...(hints.workspace !== undefined ? { workspace: hints.workspace } : {}),...(opts.gapSessionIds !== undefined ? { gapSessionIds: opts.gapSessionIds } : {}),+ ...(hints.workId !== undefined ? { workId: hints.workId } : {}),+ ...(hints.laneId !== undefined ? { laneId: hints.laneId } : {}),});if (outcome.kind === "linked") {return { lineage: outcome.lineage, crutch: outcome };diff --git a/src/core/brain/lineage/types.ts b/src/core/brain/lineage/types.tsindex 1cf4ca71..be131160 100644--- a/src/core/brain/lineage/types.ts+++ b/src/core/brain/lineage/types.ts@@ -6,10 +6,16 @@* the host compresses context and rotates the id. The kernel resolves* every session id to a lineage: the root id of the conversation, the* immediate parent segment, and how many compression boundaries deep- * the segment sits. Three sources, in strict precedence order:+ * the segment sits. Four sources, in strict precedence order:** - `payload`: the hook payload carried native lineage fields* (`parent_session_id` et al. - upstream Hermes PR #42940).+ * - `identity`: this session and exactly one predecessor DECLARED the+ * same work id (signals-that-survive, Unit 9). Durable where the+ * crutch is not - it applies no freshness bound and no working-state+ * predicate, so resumed work re-attaches across a model, account,+ * branch or worktree switch. See `identity.ts` for where the+ * declaration is read from and `crutch.ts` for the rung itself.* - `crutch`: the interim ledger-based inference for hosts that do* not emit lineage yet. See `crutch.ts`, CRUTCH(t_1459706f).* - `flat`: no lineage known; the session is its own root. This is@@ -19,7 +25,7 @@import type { GitWorkspaceIdentity } from "../git/reader.ts";-export type SessionLineageSource = "payload" | "crutch" | "flat";+export type SessionLineageSource = "payload" | "identity" | "crutch" | "flat";export interface SessionLineage {/** Root session id of the whole conversation (self when flat). */@@ -51,6 +57,18 @@ export interface LineageHints {* the shell-out lives at the capture boundary, once per hook.*/readonly workspace?: GitWorkspaceIdentity;+ /**+ * DECLARED work id for this session (signals-that-survive, Unit 9).+ * Resolved at the capture boundary by `resolveWorkIdentity` and passed+ * IN for the same reason `workspace` is: resolution stays a pure+ * function of its inputs. Absent when nothing declared one.+ */+ readonly workId?: string;+ /**+ * DECLARED lane for this session. A hard separator: two sessions under+ * different lanes never link, at any rung, whatever else they share.+ */+ readonly laneId?: string;}/**diff --git a/src/core/brain/marker-routing.ts b/src/core/brain/marker-routing.tsnew file mode 100644index 00000000..f0e6a507--- /dev/null+++ b/src/core/brain/marker-routing.ts@@ -0,0 +1,222 @@+/**+ * Destinations for the two `@osb` marker kinds that materialise a Brain+ * artifact directly: `fact` and `skill` (signals-that-survive, unit 7).+ *+ * Both destinations already carry a review gate, so this module adds+ * none of its own:+ *+ * - a `fact` marker goes through `deriveFact`, which validates every+ * premise against the preferences on disk and commits the+ * conclusion as an UNCONFIRMED preference. The dream pass is what+ * later confirms or expires it. An unresolvable premise throws+ * {@link DeriveFactError} and nothing is written - never a partial+ * write, never a silent drop.+ * - a `skill` marker goes through `draftDeclaredSkillProposal`, which+ * writes into the PENDING proposal queue only. `acceptSkillProposal`+ * remains the human step that promotes it.+ *+ * The module owns exactly the translation between the marker's fields+ * and each writer's input - the derived slug, the source reference -+ * and delegates every validation to the writer that owns the rule.+ *+ * {@link previewCaptureMarker} is the same walk with the write removed,+ * for `scan-inline --dry-run`: same input, same identity, same outcome+ * vocabulary, nothing touched.+ */++import { existsSync } from "node:fs";++import { slugify } from "../vault.ts";+import {+ DeriveFactError,+ deriveFact,+ parseDeriveFactInput,+ type DeriveFactInput,+} from "./derived-fact.ts";+import {+ isFactMarker,+ isSkillMarker,+ type FactMarker,+ type MarkerKind,+ type ParsedMarker,+ type SkillMarker,+} from "./inline.ts";+import { preferencePath } from "./paths.ts";+import {+ draftDeclaredSkillProposal,+ previewDeclaredSkillProposal,+ type DeclaredSkillProposalInput,+ type DeclaredSkillProposalResult,+} from "./skill-proposals.ts";++/**+ * The marker kinds this module has a destination for. Callers gate on+ * this set and then call {@link routeCaptureMarker}; the two stay in+ * step because a kind in the set with no route is a hard error rather+ * than a skipped marker.+ */+export const ROUTED_MARKER_KINDS: ReadonlySet<MarkerKind> = new Set<MarkerKind>(["fact", "skill"]);++/** Where the marker was found, and the clock to stamp the artifact with. */+export interface CaptureRouteContext {+ /** Wikilink to the source note, e.g. `[[Daily/2026-07-27]]`. */+ readonly sourceRef: string;+ readonly now: Date;+}++/**+ * What a routed marker did at its destination. Same vocabulary for both+ * kinds, so a caller counts and reports one set of outcomes:+ *+ * - `created` - the artifact was written.+ * - `deduped` - an equivalent artifact already existed; nothing was+ * written and nothing was lost.+ * - `suppressed`- the destination declined and the marker's content is+ * stored nowhere. Named, never silent.+ */+export type CaptureRouteOutcome = "created" | "deduped" | "suppressed";++interface CaptureRouteResultBase {+ /** Id of the artifact the marker landed in; embedded in the consumed sentinel. */+ readonly id: string;+}++export type CaptureRouteResult = CaptureRouteResultBase &+ (+ | { readonly outcome: "created" | "deduped" }+ /** `reason` is required here so a decline can never reach a caller unexplained. */+ | { readonly outcome: "suppressed"; readonly reason: string }+ );++/**+ * Send one marker to the store its kind belongs in. Callers must have+ * checked {@link ROUTED_MARKER_KINDS} first; a kind in that set with no+ * branch here throws by name rather than returning a marker-shaped+ * nothing.+ */+export function routeCaptureMarker(+ vault: string,+ marker: ParsedMarker,+ ctx: CaptureRouteContext,+): CaptureRouteResult {+ if (isFactMarker(marker)) return routeFactMarker(vault, marker, ctx);+ if (isSkillMarker(marker)) return routeSkillMarker(vault, marker, ctx);+ throw new Error(`no capture route for marker kind: ${marker.kind}`);+}++/**+ * What {@link routeCaptureMarker} would do, without writing anything.+ *+ * This is what `scan-inline --dry-run` walks. A preview that reported+ * nothing while two vault writes were queued would be a result computed+ * and dropped, so the preview resolves the same identity, refuses the+ * same markers, and returns the same outcome vocabulary as the write.+ */+export function previewCaptureMarker(+ vault: string,+ marker: ParsedMarker,+ ctx: CaptureRouteContext,+): CaptureRouteResult {+ if (isFactMarker(marker)) return previewFactMarker(vault, marker);+ if (isSkillMarker(marker)) {+ return skillRouteResult(previewDeclaredSkillProposal(vault, skillInput(marker, ctx)));+ }+ throw new Error(`no capture route for marker kind: ${marker.kind}`);+}++/**+ * Commit a fact marker as an unconfirmed preference. The slug is derived+ * from the topic, the same derivation `scanInline` already applies when+ * it slugs a feedback signal, so a fact keeps one stable identity across+ * rescans instead of needing an author-supplied id.+ *+ * The outcome is `created` because that is `deriveFact`'s whole contract:+ * it validates, writes, and returns an id, with no branch that resolves+ * to an artifact it did not write. The census test+ * `DeriveFactResult carries only the id` fails the moment that result+ * grows a field describing what it did - at which point this mapping must+ * read that field instead of standing on the contract.+ */+function routeFactMarker(+ vault: string,+ marker: FactMarker,+ ctx: CaptureRouteContext,+): CaptureRouteResult {+ const result = deriveFact(vault, factInput(marker), { now: ctx.now });+ return { id: result.id, outcome: "created" };+}++/** Draft a skill marker as a pending proposal. Never reaches accepted. */+function routeSkillMarker(+ vault: string,+ marker: SkillMarker,+ ctx: CaptureRouteContext,+): CaptureRouteResult {+ return skillRouteResult(draftDeclaredSkillProposal(vault, skillInput(marker, ctx)));+}++/** The declaration input, identical for the write and the preview. */+function skillInput(marker: SkillMarker, ctx: CaptureRouteContext): DeclaredSkillProposalInput {+ return {+ name: marker.name,+ body: marker.body,+ sourceRefs: [ctx.sourceRef],+ now: ctx.now,+ };+}++/** Carry the queue's own outcome up unchanged; the vocabularies are one. */+function skillRouteResult(result: DeclaredSkillProposalResult): CaptureRouteResult {+ return result.outcome === "suppressed"+ ? { id: result.id, outcome: "suppressed", reason: result.reason }+ : { id: result.id, outcome: result.outcome };+}++/**+ * The derive-fact input, identical for the write and the preview.+ *+ * Routed through `parseDeriveFactInput` so the marker's verbatim `level`+ * meets the destination's own vocabulary check on both paths, instead of+ * being cast into the type and validated only where a write follows.+ */+function factInput(marker: FactMarker): DeriveFactInput {+ return parseDeriveFactInput({+ slug: slugify(marker.topic),+ topic: marker.topic,+ principle: marker.principle,+ premises: [...marker.premise],+ level: marker.level,+ });+}++/**+ * What a fact marker WOULD do. `parseDeriveFactInput` covers everything+ * `deriveFact` checks without touching the vault; the two conditions+ * below are the ones it checks against the vault, restated here because+ * a preview cannot run the writer.+ *+ * They are pinned to the writer by the test "a dry run refuses exactly+ * the markers a real run refuses", which runs both paths over the same+ * fixtures: a precondition that drifts out of `derived-fact.ts` fails+ * there rather than turning a preview into a comfortable lie.+ */+function previewFactMarker(vault: string, marker: FactMarker): CaptureRouteResult {+ const input = factInput(marker);+ for (const premise of input.premises) {+ const slug = premiseSlug(premise);+ if (!slug) throw new DeriveFactError("premise id must not be empty");+ if (!existsSync(preferencePath(vault, slug))) {+ throw new DeriveFactError(`premise preference not found: ${JSON.stringify(premise)}`);+ }+ }+ if (existsSync(preferencePath(vault, input.slug))) {+ throw new DeriveFactError(`a preference already exists for slug: ${input.slug}`);+ }+ return { id: `pref-${input.slug}`, outcome: "created" };+}++/** Strip a leading `pref-` so a premise can be given as an id or a bare slug. */+function premiseSlug(premise: string): string {+ const trimmed = premise.trim();+ return trimmed.startsWith("pref-") ? trimmed.slice("pref-".length) : trimmed;+}diff --git a/src/core/brain/parse-error.ts b/src/core/brain/parse-error.tsnew file mode 100644index 00000000..82a7d6c0--- /dev/null+++ b/src/core/brain/parse-error.ts@@ -0,0 +1,84 @@+/**+ * Typed parse failure for Brain artifacts, carrying the offending file+ * as a field rather than inside its prose.+ *+ * `o2b brain doctor` renders a finding as `<code>: <message> (<path>)`,+ * appending the location from the finding's structured `path` field. A+ * parser that also embedded the path in its message therefore made every+ * parse-error line name the same file twice. The v1.40.0 convention is+ * that a finding carries data as fields, so the doctor reads {@link+ * BrainParseError.detail} β the location-free prose β and supplies the+ * path itself.+ *+ * Dropping the path from what a caller reads would have been a silent+ * loss of operator context: several surfaces (`o2b brain reject`, `brain+ * merge`, `brain pin`, the apply-evidence paths) print+ * `(exc as Error).message` bare and have nowhere else to put a location.+ * So `message` keeps it β composed by {@link withLocation}, the ONE+ * place a filesystem location is appended to a message, rather than by a+ * template repeated at every throw site.+ *+ * What that composition does and does not preserve, precisely:+ *+ * - Every throw site whose message ALREADY carried the path composes+ * the same sentence as before. Where the historical sentence put the+ * location somewhere other than the end β `BrainStatusFolderMismatchError`+ * names it inside a `(path=β¦, status=β¦, folder=β¦)` group β the site+ * supplies that sentence through {@link BrainParseErrorOptions.composedMessage},+ * so an operator matching on the text sees no change.+ * - Four optional-field helpers in `preference.ts` (`optionalStringList`,+ * `optionalNullableString`, `optionalNumber`, `optionalStringArray`)+ * threw with NO location at all. They now carry one. That is a gain,+ * not a preserved shape, and it is the only wording change in the set.+ *+ * The class is deliberately not vocabulary-aware: it knows a file and a+ * failure, and nothing about preferences, retirement, or doctor codes.+ * Classification stays in `doctor.ts`, which maps the bare detail onto+ * its own code population.+ */++/**+ * Append a filesystem location to a failure description.+ *+ * The single definition of the located form. Both {@link BrainParseError}+ * and any surface that needs to re-derive the sentence from+ * `(detail, path)` go through here, so the shape cannot drift between+ * the parsers and their readers.+ */+export function withLocation(detail: string, path: string): string {+ return `${detail} (${path})`;+}++export interface BrainParseErrorOptions extends ErrorOptions {+ /**+ * The full sentence for `message`, replacing {@link withLocation}'s+ * composition. For a throw site whose historical sentence named the+ * location somewhere other than the end, so that keeping the location+ * costs no wording change. `detail` still carries none, so the doctor+ * reads the same field it reads everywhere else.+ */+ readonly composedMessage?: string;+}++/**+ * A Brain artifact that could not be parsed, plus the file it came from.+ *+ * `detail` is the failure with no location in it; `path` is the location;+ * `message` is the two joined by {@link withLocation}, unless the site+ * supplied its own composition. A consumer that renders its own path+ * field reads `detail`; a consumer that prints one string reads+ * `message`.+ */+export class BrainParseError extends Error {+ /** Absolute path of the file whose parse failed. */+ readonly path: string;+ /** The failure, with no location in it. */+ readonly detail: string;++ constructor(detail: string, path: string, options?: BrainParseErrorOptions) {+ super(options?.composedMessage ?? withLocation(detail, path), options);+ this.name = "BrainParseError";+ this.detail = detail;+ this.path = path;+ }+}diff --git a/src/core/brain/preference.ts b/src/core/brain/preference.tsindex 02a57e76..53dd5f2f 100644--- a/src/core/brain/preference.ts+++ b/src/core/brain/preference.ts@@ -38,6 +38,7 @@ import { basename, dirname, join, relative } from "node:path";import type { FrontmatterMap } from "../types.ts";import { formatFrontmatter, parseFrontmatter, writeFrontmatterAtomic } from "../vault.ts";+import { BrainParseError } from "./parse-error.ts";import { FrontmatterTierConflictError, mergeFrontmatterTiered } from "./frontmatter-tiers.ts";import { loadSchemaPack } from "./schema-pack.ts";import { DEFAULT_RELATION_TYPES, type DefaultRelationType } from "../graph/relation-vocab.ts";@@ -87,21 +88,38 @@ import { PREF_AUDIT_OP } from "./types.ts";* Raised when a preference / retired file disagrees with the folder* it lives in. Surfaces both pieces of information so the caller (and* `o2b brain doctor`) can render an actionable message.+ *+ * A {@link BrainParseError}, so the path travels as a field and the+ * doctor's `status-folder-mismatch` branch reports it the same way as+ * every other parse failure. `status` and `folder` stay in the prose:+ * unlike the path, a `DoctorIssue` has no field for them.+ *+ * The sentence a bare caller reads is unchanged: `o2b brain reject`+ * prints `(exc as Error).message` with nowhere else to put a location,+ * and this message has always named the path INSIDE the data group,+ * before `status` and `folder`. Moving it to the end would gain nothing+ * and would break an operator matching on the text, so the composition+ * is supplied rather than left to the default appender.*/-export class BrainStatusFolderMismatchError extends Error {- readonly path: string;+export class BrainStatusFolderMismatchError extends BrainParseError {readonly status: string;readonly folder: "preferences" | "retired";constructor(message: string, path: string, status: string, folder: "preferences" | "retired") {- super(`${message} (path=${path}, status=${status}, folder=${folder})`);+ super(`${message} (${statusFolderFacts(status, folder)})`, path, {+ composedMessage: `${message} (path=${path}, ${statusFolderFacts(status, folder)})`,+ });this.name = "BrainStatusFolderMismatchError";- this.path = path;this.status = status;this.folder = folder;}}+/** The two facts a `DoctorIssue` has no field for, in their stored order. */+function statusFolderFacts(status: string, folder: "preferences" | "retired"): string {+ return `status=${status}, folder=${folder}`;+}+// ----- Writer inputs --------------------------------------------------------export interface WritePreferenceInput {@@ -744,8 +762,9 @@ export function parsePreference(requireField(meta, "kind", path);if (meta["kind"] !== "brain-preference") {- throw new Error(- `preference kind must be 'brain-preference'; got ${JSON.stringify(meta["kind"])} (${path})`,+ throw new BrainParseError(+ `preference kind must be 'brain-preference'; got ${JSON.stringify(meta["kind"])}`,+ path,);}@@ -763,8 +782,9 @@ export function parsePreference(// doctor see a coherent tombstoned entry rather than a corrupt file;// recall / inject / active.md / dream exclude it via `isTombstoned`.if (!statusValues.includes(status) && status !== "retired" && status !== BRAIN_TOMBSTONE_STATUS) {- throw new Error(- `preference status must be one of ${statusValues.join(", ")}; got ${JSON.stringify(status)} (${path})`,+ throw new BrainParseError(+ `preference status must be one of ${statusValues.join(", ")}; got ${JSON.stringify(status)}`,+ path,);}enforceStatusFolderInvariant(path, status, "preferences");@@ -776,9 +796,9 @@ export function parsePreference(const topic = requireString(meta, "topic", path);const principle = requireString(meta, "principle", path);- const evidenced_by = optionalStringArray(meta, "evidenced_by");- const confirmed_at = optionalNullableString(meta, "confirmed_at");- const last_evidence_at = optionalNullableString(meta, "last_evidence_at");+ const evidenced_by = optionalStringArray(meta, "evidenced_by", path);+ const confirmed_at = optionalNullableString(meta, "confirmed_at", path);+ const last_evidence_at = optionalNullableString(meta, "last_evidence_at", path);// Provenance level: validated through the shared narrowing guard, never cast.const provenance = asProvenanceLevel(meta["provenance"]);@@ -793,13 +813,13 @@ export function parsePreference(status: status as BrainPreferenceStatus,principle,evidenced_by,- applied_count: optionalNumber(meta, "applied_count", 0),- violated_count: optionalNumber(meta, "violated_count", 0),+ applied_count: optionalNumber(meta, "applied_count", 0, path),+ violated_count: optionalNumber(meta, "violated_count", 0, path),last_evidence_at,confidence: parseConfidence(meta, path),confidence_value: parseConfidenceValue(meta, path),pinned: parsePinned(meta),- revision: optionalNumber(meta, "revision", 0),+ revision: optionalNumber(meta, "revision", 0, path),...(optionalScalarString(meta, "content_hash") !== undefined? { content_hash: optionalScalarString(meta, "content_hash") }: {}),@@ -858,7 +878,7 @@ function spreadMemorySemantics(out["memory_branch"] = validateMemoryBranch(memoryBranch, path);}for (const field of PREFERENCE_RELATION_FIELDS) {- const values = optionalStringList(meta, field);+ const values = optionalStringList(meta, field, path);if (values !== undefined) out[field] = values;}return out;@@ -875,8 +895,9 @@ function spreadSchemaMetadata(const schemaType = validateSchemaToken(raw, "schema_type");const vocab = options.schemaVocabulary;if (vocab !== undefined && !isKnownSchemaToken(vocab, category, schemaType)) {- throw new Error(- `schema_type ${JSON.stringify(schemaType)} is not declared in ${category} (${path})`,+ throw new BrainParseError(+ `schema_type ${JSON.stringify(schemaType)} is not declared in ${category}`,+ path,);}return { schema_type: schemaType };@@ -885,8 +906,9 @@ function spreadSchemaMetadata(function validateMemoryLayer(value: string, path: string): BrainMemoryLayer {if (isBrainMemoryLayer(value)) return value;const allowed = Object.values(BRAIN_MEMORY_LAYER).join(", ");- throw new Error(- `preference field 'memory_layer' must be one of ${allowed}; got ${JSON.stringify(value)} (${path})`,+ throw new BrainParseError(+ `preference field 'memory_layer' must be one of ${allowed}; got ${JSON.stringify(value)}`,+ path,);}@@ -895,7 +917,7 @@ function validateMemoryBranch(value: string, path: string): string {return validateSlug(value);} catch (err) {const reason = err instanceof Error ? err.message : String(err);- throw new Error(`preference field 'memory_branch' is invalid: ${reason} (${path})`, {+ throw new BrainParseError(`preference field 'memory_branch' is invalid: ${reason}`, path, {cause: err,});}@@ -938,8 +960,9 @@ export function parseRetired(path: string, options: ParsePreferenceOptions = {})requireField(meta, "kind", path);if (meta["kind"] !== "brain-retired") {- throw new Error(- `retired kind must be 'brain-retired'; got ${JSON.stringify(meta["kind"])} (${path})`,+ throw new BrainParseError(+ `retired kind must be 'brain-retired'; got ${JSON.stringify(meta["kind"])}`,+ path,);}@@ -959,8 +982,9 @@ export function parseRetired(path: string, options: ParsePreferenceOptions = {})const reasonStr = requireString(meta, "retired_reason", path);const reasonValues = Object.values(BRAIN_RETIRED_REASON) as ReadonlyArray<string>;if (!reasonValues.includes(reasonStr)) {- throw new Error(- `retired_reason must be one of ${reasonValues.join(", ")}; got ${JSON.stringify(reasonStr)} (${path})`,+ throw new BrainParseError(+ `retired_reason must be one of ${reasonValues.join(", ")}; got ${JSON.stringify(reasonStr)}`,+ path,);}const retired_by = requireString(meta, "retired_by", path);@@ -980,10 +1004,10 @@ export function parseRetired(path: string, options: ParsePreferenceOptions = {})tags,topic,principle,- evidenced_by: optionalStringArray(meta, "evidenced_by"),- applied_count: optionalNumber(meta, "applied_count", 0),- violated_count: optionalNumber(meta, "violated_count", 0),- last_evidence_at: optionalNullableString(meta, "last_evidence_at"),+ evidenced_by: optionalStringArray(meta, "evidenced_by", path),+ applied_count: optionalNumber(meta, "applied_count", 0, path),+ violated_count: optionalNumber(meta, "violated_count", 0, path),+ last_evidence_at: optionalNullableString(meta, "last_evidence_at", path),confidence: parseConfidence(meta, path),confidence_value: parseConfidenceValue(meta, path),pinned: parsePinned(meta),@@ -1133,7 +1157,7 @@ export function moveToRetired(created_at: requireString(meta, "created_at", prefPath),unconfirmed_until: requireString(meta, "unconfirmed_until", prefPath),status: BRAIN_PREFERENCE_STATUS.confirmed, // body render is status-agnostic- evidenced_by: optionalStringArray(meta, "evidenced_by"),+ evidenced_by: optionalStringArray(meta, "evidenced_by", prefPath),...(opts.evidenceApplied !== undefined ? { recentApplied: opts.evidenceApplied } : {}),...(opts.evidenceViolated !== undefined ? { recentViolated: opts.evidenceViolated } : {}),};@@ -1273,10 +1297,10 @@ function enforceStatusFolderInvariant(function requireField(meta: Record<string, unknown>, field: string, path: string): void {if (!(field in meta) || meta[field] === undefined || meta[field] === null) {- throw new Error(`preference missing field: ${field} (${path})`);+ throw new BrainParseError(`preference missing field: ${field}`, path);}if (typeof meta[field] === "string" && (meta[field] as string).trim() === "") {- throw new Error(`preference missing field: ${field} (${path})`);+ throw new BrainParseError(`preference missing field: ${field}`, path);}}@@ -1284,7 +1308,7 @@ function requireString(meta: Record<string, unknown>, field: string, path: strinrequireField(meta, field, path);const v = meta[field];if (typeof v !== "string") {- throw new Error(`preference field '${field}' must be a string (${path})`);+ throw new BrainParseError(`preference field '${field}' must be a string`, path);}return v;}@@ -1297,25 +1321,29 @@ function requireStringArray(requireField(meta, field, path);const v = meta[field];if (!Array.isArray(v)) {- throw new Error(`preference field '${field}' must be an array (${path})`);+ throw new BrainParseError(`preference field '${field}' must be an array`, path);}for (const item of v) {if (typeof item !== "string") {- throw new Error(`preference field '${field}' must be an array of strings (${path})`);+ throw new BrainParseError(`preference field '${field}' must be an array of strings`, path);}}return [...(v as ReadonlyArray<string>)];}-function optionalStringArray(meta: Record<string, unknown>, field: string): ReadonlyArray<string> {+function optionalStringArray(+ meta: Record<string, unknown>,+ field: string,+ path: string,+): ReadonlyArray<string> {const v = meta[field];if (v === undefined || v === null) return [];if (!Array.isArray(v)) {- throw new Error(`preference field '${field}' must be an array`);+ throw new BrainParseError(`preference field '${field}' must be an array`, path);}for (const item of v) {if (typeof item !== "string") {- throw new Error(`preference field '${field}' must be an array of strings`);+ throw new BrainParseError(`preference field '${field}' must be an array of strings`, path);}}return [...(v as ReadonlyArray<string>)];@@ -1324,16 +1352,23 @@ function optionalStringArray(meta: Record<string, unknown>, field: string): Readfunction optionalStringList(meta: Record<string, unknown>,field: PreferenceRelationField,+ path: string,): ReadonlyArray<string> | undefined {const v = meta[field];if (v === undefined || v === null) return undefined;if (typeof v === "string") return v.trim() ? [v] : [];if (!Array.isArray(v)) {- throw new Error(`preference field '${field}' must be a string or array of strings`);+ throw new BrainParseError(+ `preference field '${field}' must be a string or array of strings`,+ path,+ );}for (const item of v) {if (typeof item !== "string") {- throw new Error(`preference field '${field}' must be a string or array of strings`);+ throw new BrainParseError(+ `preference field '${field}' must be a string or array of strings`,+ path,+ );}}return [...(v as ReadonlyArray<string>)];@@ -1345,18 +1380,27 @@ function optionalStringList(* the on-disk roundtrip survives the simple YAML emitter (which has no* native null token).*/-function optionalNullableString(meta: Record<string, unknown>, field: string): string | null {+function optionalNullableString(+ meta: Record<string, unknown>,+ field: string,+ path: string,+): string | null {const v = meta[field];if (v === undefined || v === null) return null;if (typeof v !== "string") {- throw new Error(`preference field '${field}' must be a string or null`);+ throw new BrainParseError(`preference field '${field}' must be a string or null`, path);}const trimmed = v.trim();if (trimmed === "" || trimmed === "null") return null;return v;}-function optionalNumber(meta: Record<string, unknown>, field: string, fallback: number): number {+function optionalNumber(+ meta: Record<string, unknown>,+ field: string,+ fallback: number,+ path: string,+): number {const v = meta[field];if (v === undefined || v === null || v === "") return fallback;// The simple parser surfaces all values as strings; numerics included.@@ -1364,13 +1408,14 @@ function optionalNumber(meta: Record<string, unknown>, field: string, fallback:if (typeof v === "string") {const n = Number(v);if (!Number.isFinite(n)) {- throw new Error(+ throw new BrainParseError(`preference field '${field}' must be a finite number; got ${JSON.stringify(v)}`,+ path,);}return n;}- throw new Error(`preference field '${field}' must be a number`);+ throw new BrainParseError(`preference field '${field}' must be a number`, path);}/**@@ -1405,12 +1450,13 @@ function parseConfidence(meta: Record<string, unknown>, path: string): BrainConfconst v = meta["confidence"];if (v === undefined || v === null || v === "") return BRAIN_CONFIDENCE.low;if (typeof v !== "string") {- throw new Error(`preference field 'confidence' must be a string (${path})`);+ throw new BrainParseError("preference field 'confidence' must be a string", path);}const values = Object.values(BRAIN_CONFIDENCE) as ReadonlyArray<string>;if (!values.includes(v)) {- throw new Error(- `preference field 'confidence' must be one of ${values.join(", ")}; got ${JSON.stringify(v)} (${path})`,+ throw new BrainParseError(+ `preference field 'confidence' must be one of ${values.join(", ")}; got ${JSON.stringify(v)}`,+ path,);}return v as BrainConfidence;@@ -1443,8 +1489,9 @@ function parseConfidenceValue(meta: Record<string, unknown>, path: string): numbif (Number.isFinite(candidate)) n = candidate;}if (n === null || !Number.isFinite(n) || n < 0 || n > 1) {- throw new Error(- `preference field 'confidence_value' must be a number in [0, 1]; got ${JSON.stringify(v)} (${path})`,+ throw new BrainParseError(+ `preference field 'confidence_value' must be a number in [0, 1]; got ${JSON.stringify(v)}`,+ path,);}return n;diff --git a/src/core/brain/query-demand.ts b/src/core/brain/query-demand.tsindex 3ce7ef6b..e377b484 100644--- a/src/core/brain/query-demand.ts+++ b/src/core/brain/query-demand.ts@@ -2,9 +2,11 @@* Cross-query demand log (t_97091fff).** A persisted, deterministic record of every recall query against the- * vault, together with two satisfaction signals already computed- * elsewhere: the result count and the IDF-weighted coverage score from- * {@link ../search/coverage.ts}. Aggregated over time, the log surfaces+ * vault, together with three satisfaction signals already computed+ * elsewhere: the result count, the IDF-weighted coverage score from+ * {@link ../search/coverage.ts}, and β when the caller graded the attempt+ * β the unmet recall-adequacy verdict (signals-that-survive, unit 6).+ * Aggregated over time, the log surfaces* the *demand* gap β queries operators keep asking that the vault* answers poorly (weak or empty) β as a prioritized backlog of what to* write into `Brain/` next.@@ -39,6 +41,8 @@ import {significantTerms,} from "../search/coverage.ts";import type { CompletenessVerdict } from "../search/types.ts";+import { isRecallAdequacyLevel } from "./recall-adequacy.ts";+import type { RecallAdequacyLevel, RecallAdequacyVerdict } from "./recall-adequacy.ts";import { assertVaultIdentityForWrite } from "./vault-identity.ts";/** Longest single normalized term kept; longer tokens are dropped as a@@ -64,17 +68,34 @@ export const DEMAND_LOG_COMPACT_BYTES = 750_000;/** A query must recur at least this many times to count as demand. */export const DEMAND_DEFAULT_MIN_OCCURRENCES = 2;+/**+ * Adequacy levels that count as unmet recall (signals-that-survive, unit+ * 6). A `sufficient` attempt is not demand, so it is never stamped.+ */+export const DEMAND_UNMET_ADEQUACY_LEVELS: ReadonlyArray<RecallAdequacyLevel> = Object.freeze([+ "weak",+ "insufficient",+]);++/** Whether an adequacy level is unmet recall, i.e. actionable demand. */+export function isUnmetAdequacyLevel(level: RecallAdequacyLevel): boolean {+ return DEMAND_UNMET_ADEQUACY_LEVELS.includes(level);+}+/*** One persisted recall observation. `coverage` is absent when the caller* did not compute the evidence-pack coverage (the common non-verified* search path); the aggregator falls back to the result-presence signal- * for those buckets.+ * for those buckets. `adequacy` is absent unless the caller graded the+ * attempt through {@link ../brain/recall-adequacy.ts} and the grade came+ * back unmet (signals-that-survive, unit 6).*/export interface QueryDemandRecord {readonly ts: string;readonly terms: ReadonlyArray<string>;readonly results: number;readonly coverage?: number;+ readonly adequacy?: RecallAdequacyLevel;}export interface RecordQueryDemandInput {@@ -85,10 +106,20 @@ export interface RecordQueryDemandInput {readonly resultCount: number;/** IDF-weighted coverage (0..1) from coverage.ts, when available. */readonly coverage?: number | null;+ /** Graded recall adequacy, when the caller ran the verdict layer. */+ readonly adequacy?: RecallAdequacyLevel;/** ISO timestamp; defaults to now. */readonly at?: string;}+/** One recurring question the vault keeps answering with unmet grounding. */+export interface UnmetRecallBucket {+ /** The shared bucket key: sorted normalized terms joined by a space. */+ readonly key: string;+ readonly terms: ReadonlyArray<string>;+ readonly occurrences: number;+}+export interface QueryDemandFilter {readonly since?: string;readonly until?: string;@@ -205,6 +236,7 @@ export function recordQueryDemand(...(typeof input.coverage === "number" && Number.isFinite(input.coverage)? { coverage: clamp01(input.coverage) }: {}),+ ...(input.adequacy !== undefined ? { adequacy: input.adequacy } : {}),};// Vault-identity write guard (context-integrity-gates, Unit J).assertVaultIdentityForWrite(vault);@@ -220,6 +252,69 @@ export function recordQueryDemand(return record;}+/**+ * Stamp one graded recall attempt onto the demand log+ * (signals-that-survive, unit 6). The bucket key is whatever+ * {@link normalizeQueryTerms} derives from the query β the identity concept+ * this module already owns β so recurrence aggregates without a second one.+ *+ * Returns null, rather than writing, when the attempt is not demand: a+ * `sufficient` verdict is met recall, and a query with no significant terms+ * has no bucket to key on. Both are documented non-cases, not swallowed+ * failures; a genuine write fault still propagates from+ * {@link recordQueryDemand}.+ */+export function recordRecallAdequacyDemand(+ vault: string,+ input: {+ readonly query: string;+ readonly verdict: RecallAdequacyVerdict;+ readonly at?: string;+ },+): QueryDemandRecord | null {+ if (!isUnmetAdequacyLevel(input.verdict.level)) return null;+ return recordQueryDemand(vault, {+ query: input.query,+ resultCount: input.verdict.resultCount,+ adequacy: input.verdict.level,+ ...(input.at !== undefined ? { at: input.at } : {}),+ });+}++/**+ * Count how often each bucket came back with unmet grounding. This is the+ * verdict-side recurrence source the knowledge-gap loop aggregates+ * alongside its structural `gap_counts` source (signals-that-survive, unit+ * 6); the two are deliberately counted separately, never summed, because a+ * telemetry code bucket and a term bucket do not measure the same thing.+ */+export function aggregateUnmetRecall(+ vault: string,+ filter: QueryDemandFilter = {},+): ReadonlyArray<UnmetRecallBucket> {+ const buckets = new Map<string, { terms: ReadonlyArray<string>; occurrences: number }>();+ for (const record of readQueryDemand(vault, filter)) {+ if (record.adequacy === undefined || !isUnmetAdequacyLevel(record.adequacy)) continue;+ const key = demandBucketKey(record.terms);+ const bucket = buckets.get(key);+ if (bucket === undefined) {+ buckets.set(key, { terms: record.terms, occurrences: 1 });+ } else {+ bucket.occurrences += 1;+ }+ }+ return Object.freeze(+ [...buckets].map(([key, bucket]) =>+ Object.freeze({ key, terms: bucket.terms, occurrences: bucket.occurrences }),+ ),+ );+}++/** The bucket key both aggregators group by: sorted terms, space-joined. */+function demandBucketKey(terms: ReadonlyArray<string>): string {+ return terms.join(" ");+}+/** Read all demand records, filtered by [since, until] and sorted by ts. */export function readQueryDemand(vault: string,@@ -279,7 +374,7 @@ export function aggregateQueryDemand(}const buckets = new Map<string, Bucket>();for (const record of records) {- const key = record.terms.join(" ");+ const key = demandBucketKey(record.terms);let bucket = buckets.get(key);if (!bucket) {bucket = {@@ -398,6 +493,7 @@ function coerceRecord(line: string): QueryDemandRecord | null {if (!Array.isArray(terms) || !terms.every((t) => typeof t === "string")) return null;if (typeof results !== "number" || !Number.isFinite(results)) return null;const coverage = obj["coverage"];+ const adequacy = obj["adequacy"];return {ts,terms: Object.freeze(terms as string[]),@@ -405,6 +501,9 @@ function coerceRecord(line: string): QueryDemandRecord | null {...(typeof coverage === "number" && Number.isFinite(coverage)? { coverage: clamp01(coverage) }: {}),+ // An unrecognised level is dropped rather than trusted: the record+ // predates the field, or was hand-edited.+ ...(isRecallAdequacyLevel(adequacy) ? { adequacy } : {}),};}diff --git a/src/core/brain/recall-adequacy.ts b/src/core/brain/recall-adequacy.tsindex db8d2d5c..854a403d 100644--- a/src/core/brain/recall-adequacy.ts+++ b/src/core/brain/recall-adequacy.ts@@ -21,6 +21,15 @@export const RECALL_ADEQUACY_LEVELS = ["sufficient", "weak", "insufficient"] as const;export type RecallAdequacyLevel = (typeof RECALL_ADEQUACY_LEVELS)[number];+/**+ * Whether a value is one of the declared adequacy levels β the guard a+ * persisted verdict must clear before it is trusted, mirroring the sibling+ * `isRecallTelemetryMode`.+ */+export function isRecallAdequacyLevel(value: unknown): value is RecallAdequacyLevel {+ return RECALL_ADEQUACY_LEVELS.includes(value as RecallAdequacyLevel);+}+export const RECALL_ADEQUACY_ACTIONS = ["proceed", "re_recall", "abstain"] as const;export type RecallAdequacyAction = (typeof RECALL_ADEQUACY_ACTIONS)[number];diff --git a/src/core/brain/research/research.ts b/src/core/brain/research/research.tsindex ed2b99c6..3022a120 100644--- a/src/core/brain/research/research.ts+++ b/src/core/brain/research/research.ts@@ -25,6 +25,11 @@ import { canonicalNotePath } from "../../path-safety.ts";import { slugify, writeFrontmatterAtomic } from "../../vault.ts";import { isoDate, isoSecond } from "../time.ts";import { reportPagePath } from "../paths.ts";+import {+ RESEARCH_REPORT_SHAPE,+ RESEARCH_REPORT_SURFACE,+ assertResponseShape,+} from "../response-shape.ts";import { assertVaultIdentityForWrite } from "../vault-identity.ts";import { renderProvenanceSection, type Provenance } from "../provenance/provenance.ts";import {@@ -83,6 +88,32 @@ export class ResearchValidationError extends Error {}}+/**+ * Ingress of the agent-authored report payload. The payload is checked+ * against the frozen research-report shape BEFORE the citation contract is+ * evaluated, so a finding whose `sources` is not a list of strings is refused+ * by path instead of being read as one. A violation throws+ * `ResponseShapeError` and no report page is written - not even the findings+ * that preceded the malformed one.+ */+export function parseResearchReportInput(payload: unknown): ResearchReportInput {+ assertResponseShape(RESEARCH_REPORT_SURFACE, RESEARCH_REPORT_SHAPE, payload);+ const rec = payload as Record<string, unknown>;+ const findings = rec["findings"] as ReadonlyArray<Record<string, unknown>>;+ return {+ title: rec["title"] as string,+ sources: Object.freeze([...(rec["sources"] as ReadonlyArray<string>)]),+ findings: Object.freeze(+ findings.map((finding) =>+ Object.freeze({+ statement: finding["statement"] as string,+ sources: Object.freeze([...(finding["sources"] as ReadonlyArray<string>)]),+ }),+ ),+ ),+ };+}+/** Wrap a bare source identifier in a wikilink; leave an existing one as-is. */function asWikilink(source: string): string {const trimmed = source.trim();diff --git a/src/core/brain/response-shape.ts b/src/core/brain/response-shape.tsnew file mode 100644index 00000000..b3fd042d--- /dev/null+++ b/src/core/brain/response-shape.ts@@ -0,0 +1,368 @@+/**+ * Response-shape validation for model-authored write paths+ * (signals-that-survive, unit 8, t_80b01448).+ *+ * Three write paths accept a payload the calling agent authored - distilled+ * claims, a derived fact, a synthesized research report - and commit it+ * straight into the vault. Loose parsing there does not surface as an error:+ * it surfaces later as corrupted knowledge. This module is the ingress gate+ * those paths validate against BEFORE any normalization runs.+ *+ * The validator is the JSON-subset checker the Model Context Protocol output+ * contract has always used, promoted here so there is exactly ONE definition;+ * `src/mcp/output-contract.ts` now consumes it rather than owning a twin.+ *+ * Two properties are deliberate and load-bearing:+ *+ * - Validation is UNCONDITIONAL. This module reads no settings and no+ * environment. A gate that can be switched off is a gate the write path+ * cannot rely on, and one defaulting to today's tolerance would ship the+ * strict path inert - the silent no-op this project forbids.+ * - Descriptors stay SHALLOW: required keys, primitive types, arrays of+ * objects. Over-constraining an extraction payload degrades recall, which+ * is the failure this layer must not cause.+ *+ * The layer is named for response *shape* throughout, and never borrows the+ * noun the knowledge vocabulary already owns, so the two cannot be confused+ * with each other - a test pins that naming so it cannot drift back.+ */++/** Value kinds a descriptor can require. */+export const SHAPE_TYPES = Object.freeze([+ "object",+ "array",+ "string",+ "number",+ "integer",+ "boolean",+ "null",+] as const);++export type ShapeType = (typeof SHAPE_TYPES)[number];++/** The complete set of keys a descriptor node may declare. */+export const SHAPE_DESCRIPTOR_KEYS = Object.freeze([+ "type",+ "required",+ "properties",+ "items",+ "enum",+ "additionalProperties",+ "nonBlank",+] as const);++/**+ * One node of a response-shape descriptor. Anything outside+ * {@link SHAPE_DESCRIPTOR_KEYS} is not expressible here - by design: a+ * descriptor a reader can hold in their head is a descriptor that stays+ * accurate.+ */+export interface ShapeDescriptor {+ readonly type?: ShapeType;+ readonly required?: ReadonlyArray<string>;+ readonly properties?: Readonly<Record<string, ShapeDescriptor>>;+ readonly items?: ShapeDescriptor;+ readonly enum?: ReadonlyArray<unknown>;+ readonly additionalProperties?: boolean | ShapeDescriptor;+ /**+ * String values only: an empty or whitespace-only string is a violation.+ * A key can be present and still carry no content, and on these write paths+ * a blank string is not a value - it is a missing one wearing the right+ * type. Declaring that here keeps `required` about presence and lets the+ * descriptor say what the parsers it replaced said.+ */+ readonly nonBlank?: boolean;+}++/** Stable codes a violation is classified under; never assembled from prose. */+export const SHAPE_VIOLATION_CODES = Object.freeze({+ typeMismatch: "shape_type_mismatch",+ missingProperty: "shape_missing_property",+ unexpectedProperty: "shape_unexpected_property",+ disallowedValue: "shape_disallowed_value",+ blankString: "shape_blank_string",+} as const);++/** Wording of a blank-string violation, kept as the parsers it replaced read. */+const BLANK_STRING_MESSAGE = "must be a non-empty string";++export type ShapeViolationCode = (typeof SHAPE_VIOLATION_CODES)[keyof typeof SHAPE_VIOLATION_CODES];++/** One structural defect, located by path and classified by code. */+export interface ShapeViolation {+ readonly code: ShapeViolationCode;+ /** JSON-path-ish location, e.g. `$.findings[0].sources`. */+ readonly path: string;+ /** The defect, without the path - callers render `<path>: <message>`. */+ readonly message: string;+}++/** Path assigned to the payload root. */+export const SHAPE_ROOT_PATH = "$";++/** Render one violation as the single line a caller prints or joins. */+export function formatShapeViolation(violation: ShapeViolation): string {+ return `${violation.path}: ${violation.message}`;+}++/**+ * Check `value` against `descriptor`, returning every violation found. An+ * empty array means the payload conforms. Pure: reads nothing but its+ * arguments, so the same payload always produces the same verdict.+ */+export function checkResponseShape(+ descriptor: ShapeDescriptor,+ value: unknown,+ path: string = SHAPE_ROOT_PATH,+): ShapeViolation[] {+ const violations: ShapeViolation[] = [];++ if (descriptor.enum && !descriptor.enum.some((allowed) => Object.is(allowed, value))) {+ violations.push(+ makeViolation(+ SHAPE_VIOLATION_CODES.disallowedValue,+ path,+ `expected one of ${descriptor.enum.map(String).join(", ")}`,+ ),+ );+ return violations;+ }++ if (descriptor.type && !matchesType(value, descriptor.type)) {+ violations.push(typeViolation(path, descriptor.type));+ return violations;+ }++ if (descriptor.nonBlank === true && typeof value === "string" && value.trim().length === 0) {+ violations.push(makeViolation(SHAPE_VIOLATION_CODES.blankString, path, BLANK_STRING_MESSAGE));+ return violations;+ }++ if (descriptor.type === "object" || descriptor.properties || descriptor.required) {+ if (!isRecord(value)) {+ if (!descriptor.type) violations.push(typeViolation(path, "object"));+ return violations;+ }++ for (const requiredKey of descriptor.required ?? []) {+ if (!hasOwn(value, requiredKey)) {+ violations.push(+ makeViolation(+ SHAPE_VIOLATION_CODES.missingProperty,+ path,+ `missing required property '${requiredKey}'`,+ ),+ );+ }+ }++ const properties = descriptor.properties ?? {};+ for (const [key, childDescriptor] of Object.entries(properties)) {+ if (hasOwn(value, key)) {+ violations.push(...checkResponseShape(childDescriptor, value[key], `${path}.${key}`));+ }+ }++ const additional = descriptor.additionalProperties;+ if (additional === false) {+ for (const key of Object.keys(value)) {+ if (!hasOwn(properties, key)) {+ violations.push(+ makeViolation(+ SHAPE_VIOLATION_CODES.unexpectedProperty,+ path,+ `unexpected property '${key}'`,+ ),+ );+ }+ }+ } else if (typeof additional === "object") {+ for (const [key, childValue] of Object.entries(value)) {+ if (!hasOwn(properties, key)) {+ violations.push(...checkResponseShape(additional, childValue, `${path}.${key}`));+ }+ }+ }+ }++ if (descriptor.type === "array" || descriptor.items) {+ if (!Array.isArray(value)) {+ if (!descriptor.type) violations.push(typeViolation(path, "array"));+ return violations;+ }+ const items = descriptor.items;+ if (items) {+ value.forEach((item, index) => {+ violations.push(...checkResponseShape(items, item, `${path}[${index}]`));+ });+ }+ }++ return violations;+}++/**+ * An agent-authored payload did not match the shape its write path declares.+ * Carries the defect structurally - `code`, `path`, and the full violation+ * list - so a caller routes on fields rather than parsing the message.+ * Nothing has been written when this is thrown.+ */+export class ResponseShapeError extends Error {+ /** Code of the first violation; the full set is on {@link violations}. */+ readonly code: ShapeViolationCode;+ /** Path of the first violation. */+ readonly path: string;+ /** The write path that declared the descriptor, e.g. `distill_claims`. */+ readonly surface: string;+ readonly violations: ReadonlyArray<ShapeViolation>;++ constructor(surface: string, violations: ReadonlyArray<ShapeViolation>) {+ const first = violations[0];+ if (first === undefined) {+ throw new TypeError("ResponseShapeError requires at least one violation");+ }+ super(`${surface} response shape violated: ${violations.map(formatShapeViolation).join("; ")}`);+ this.name = "ResponseShapeError";+ this.code = first.code;+ this.path = first.path;+ this.surface = surface;+ this.violations = Object.freeze([...violations]);+ }+}++/**+ * Fail-closed gate: return silently when the payload conforms, throw+ * {@link ResponseShapeError} otherwise. There is no tolerant mode and no key+ * that relaxes it - a violating payload is never coerced, never partially+ * accepted, and never dropped.+ */+export function assertResponseShape(+ surface: string,+ descriptor: ShapeDescriptor,+ value: unknown,+): void {+ const violations = checkResponseShape(descriptor, value);+ if (violations.length > 0) throw new ResponseShapeError(surface, violations);+}++// ----- Declared descriptors, one per model-authored write path -------------++/** Surface label of the source-distillation claims payload. */+export const DISTILL_CLAIMS_SURFACE = "distill_claims";+/** Surface label of the derived-fact payload. */+export const DERIVED_FACT_SURFACE = "derived_fact";+/** Surface label of the research-report synthesis payload. */+export const RESEARCH_REPORT_SURFACE = "research_report";++const STRING_SHAPE: ShapeDescriptor = { type: "string" };+const STRING_LIST_SHAPE: ShapeDescriptor = { type: "array", items: STRING_SHAPE };+/** A string that must carry content - the previous parsers' `requiredString`. */+const FILLED_STRING_SHAPE: ShapeDescriptor = { type: "string", nonBlank: true };+const FILLED_STRING_LIST_SHAPE: ShapeDescriptor = {+ type: "array",+ items: FILLED_STRING_SHAPE,+};++/**+ * Atomic claims distilled from one source. Deliberately open to extra keys:+ * a claim carrying a field this version does not read is not a reason to+ * reject the whole distillation.+ */+export const DISTILL_CLAIMS_SHAPE: ShapeDescriptor = freezeDescriptor({+ type: "array",+ items: {+ type: "object",+ required: ["text"],+ properties: { text: STRING_SHAPE, block: STRING_SHAPE },+ },+});++/**+ * A second-order conclusion plus the premises it was reasoned from. `level`+ * is checked as a string here; the derivation vocabulary itself is owned by+ * `provenance.ts` and narrowed there, so it is never duplicated.+ */+export const DERIVED_FACT_SHAPE: ShapeDescriptor = freezeDescriptor({+ type: "object",+ required: ["slug", "topic", "principle", "premises", "level"],+ properties: {+ slug: STRING_SHAPE,+ topic: STRING_SHAPE,+ principle: STRING_SHAPE,+ premises: STRING_LIST_SHAPE,+ level: STRING_SHAPE,+ },+});++/**+ * A synthesized report: consulted sources plus findings that cite them.+ *+ * Every string here is required to carry content. The citation contract is+ * checked by SET MEMBERSHIP - a finding's source must be one of the consulted+ * sources - so a blank source satisfies a blank citation and an uncited claim+ * passes as a cited one. That contract can only be as strong as the strings it+ * compares, which is why the constraint belongs here rather than downstream.+ */+export const RESEARCH_REPORT_SHAPE: ShapeDescriptor = freezeDescriptor({+ type: "object",+ required: ["title", "sources", "findings"],+ properties: {+ title: FILLED_STRING_SHAPE,+ sources: FILLED_STRING_LIST_SHAPE,+ findings: {+ type: "array",+ items: {+ type: "object",+ required: ["statement", "sources"],+ properties: { statement: FILLED_STRING_SHAPE, sources: FILLED_STRING_LIST_SHAPE },+ },+ },+ },+});++/**+ * Every declared descriptor, by surface. The registry exists so the shallow-+ * and-expressible discipline can be asserted over the whole set at once+ * rather than one descriptor at a time.+ */+export const MODEL_AUTHORED_SHAPES: Readonly<Record<string, ShapeDescriptor>> = Object.freeze({+ [DISTILL_CLAIMS_SURFACE]: DISTILL_CLAIMS_SHAPE,+ [DERIVED_FACT_SURFACE]: DERIVED_FACT_SHAPE,+ [RESEARCH_REPORT_SURFACE]: RESEARCH_REPORT_SHAPE,+});++// ----- Internals ----------------------------------------------------------++function makeViolation(code: ShapeViolationCode, path: string, message: string): ShapeViolation {+ return Object.freeze({ code, path, message });+}++function typeViolation(path: string, type: ShapeType): ShapeViolation {+ return makeViolation(SHAPE_VIOLATION_CODES.typeMismatch, path, `expected ${type}`);+}++/** Freeze a declared descriptor all the way down, so it cannot drift at runtime. */+function freezeDescriptor<T>(descriptor: T): T {+ if (descriptor !== null && typeof descriptor === "object") {+ for (const child of Object.values(descriptor)) freezeDescriptor(child);+ Object.freeze(descriptor);+ }+ return descriptor;+}++function matchesType(value: unknown, type: ShapeType): boolean {+ if (type === "null") return value === null;+ if (type === "array") return Array.isArray(value);+ if (type === "object") return isRecord(value);+ if (type === "integer") return typeof value === "number" && Number.isInteger(value);+ if (type === "number") return typeof value === "number" && Number.isFinite(value);+ return typeof value === type;+}++function isRecord(value: unknown): value is Record<string, unknown> {+ return typeof value === "object" && value !== null && !Array.isArray(value);+}++function hasOwn(value: object, key: string): boolean {+ return Object.prototype.hasOwnProperty.call(value, key);+}diff --git a/src/core/brain/session-lifecycle.ts b/src/core/brain/session-lifecycle.tsindex 26efe3c2..2fb0c892 100644--- a/src/core/brain/session-lifecycle.ts+++ b/src/core/brain/session-lifecycle.ts@@ -25,6 +25,11 @@ import {recordLineageObservation,} from "./lineage/ledger.ts";import { resolveSessionLineageDetailed } from "./lineage/resolve.ts";+import {+ recordWorkIdentityMarker,+ resolveWorkIdentity,+ WORK_IDENTITY_SOURCE,+} from "./lineage/identity.ts";import { readGitWorkspaceIdentity } from "./git/reader.ts";import { type DegradationNotice, formatDegradationNotice } from "../integrity/degradation.ts";import { isCompressionEvidenceEvent, type SessionLineage } from "./lineage/types.ts";@@ -88,6 +93,10 @@ interface NormalizedPayload {readonly compressionDepth?: number;/** SessionStart discriminator (`startup|resume|clear|compact`). */readonly sessionStartSource?: string;+ /** Declared work id the host named (`work_id`), if any. Unit 9. */+ readonly workId?: string;+ /** Declared lane the host named (`lane_id`), if any. Unit 9. */+ readonly laneId?: string;/*** Host flag: this SessionEnd was an interrupted close* (SIGHUP/SIGTERM/force-quit/restart-drain). Absent by default; only@@ -151,6 +160,21 @@ export async function captureSessionLifecycleEvent(// failed spawn.const workspace =normalized.cwd !== undefined ? readGitWorkspaceIdentity(normalized.cwd) : null;+ // Unit 9: source the DECLARED work identity here for the same+ // reason the git probe lives here - resolution stays a pure+ // function of its inputs. Absent when nothing declares one, which+ // leaves every rung below exactly as it was.+ const identity = resolveWorkIdentity({+ vault,+ ...(normalized.workId !== undefined ? { payloadWorkId: normalized.workId } : {}),+ ...(normalized.laneId !== undefined ? { payloadLaneId: normalized.laneId } : {}),+ ...(normalized.cwd !== undefined ? { worktree: normalized.cwd } : {}),+ // The same clock the resolver below runs on: the marker rung is+ // the one rung with a freshness bound, and it must age against+ // this event's instant, not against a second reading of the wall+ // clock.+ nowMs: now.getTime(),+ });const resolution = resolveSessionLineageDetailed({sessionId: normalized.sessionId,@@ -165,6 +189,8 @@ export async function captureSessionLifecycleEvent(: {}),...(normalized.cwd !== undefined ? { cwd: normalized.cwd } : {}),...(workspace !== null ? { workspace } : {}),+ ...(identity?.workId !== undefined ? { workId: identity.workId } : {}),+ ...(identity?.laneId !== undefined ? { laneId: identity.laneId } : {}),},{ledger: readLineageLedger(vault),@@ -195,8 +221,11 @@ export async function captureSessionLifecycleEvent(: {}),...(lineage.source !== "flat" ? { lineage } : {}),...(workspace !== null ? { workspace } : {}),+ ...(identity?.workId !== undefined ? { workId: identity.workId } : {}),+ ...(identity?.laneId !== undefined ? { laneId: identity.laneId } : {}),});if (recorded.notice !== undefined) lineageDrops.push(recorded.notice);+ recordWorktreeIdentityMarker(vault, normalized.cwd, identity, now.getTime());}} catch {lineage = undefined; // lineage is an enhancement, never a blocker@@ -418,6 +447,37 @@ export async function captureSessionLifecycleEvent(};}+/**+ * Persist a live declaration as this worktree's marker (Unit 9), so the+ * next session here resolves the same work item even when its host says+ * nothing. Only a declaration that came from the payload or the+ * environment is written: re-writing what the marker itself supplied+ * would be a read echoed back as a write.+ *+ * Fail-soft in its own right, like the anticipatory cache below it - the+ * marker is a convenience for a LATER session, and a state directory+ * that cannot be written must not cost this one its capture.+ *+ * Skipping the marker-sourced case is also what gives the marker rung's+ * freshness bound its meaning: the recorded instant is the last time+ * something ACTUALLY declared this identity, so an inherited one cannot+ * keep refreshing itself and stay live forever.+ */+function recordWorktreeIdentityMarker(+ vault: string,+ worktree: string | undefined,+ identity: ReturnType<typeof resolveWorkIdentity>,+ nowMs: number,+): void {+ if (worktree === undefined || identity === null) return;+ if (identity.source === WORK_IDENTITY_SOURCE.marker) return;+ try {+ recordWorkIdentityMarker(vault, worktree, identity, { nowMs });+ } catch {+ // The marker is an enhancement, never a capture blocker.+ }+}+/*** Read the recorded transcript via the session adapters and write a* handoff note. Trust model: `transcript_path` is produced by the host@@ -487,6 +547,8 @@ function normalizePayload(payload: unknown): NormalizedPayload {? compressionDepthRaw: undefined;const sessionStartSource = readNonEmptyString(record["source"]);+ const workId = readNonEmptyString(record["work_id"]);+ const laneId = readNonEmptyString(record["lane_id"]);return {event,...(sessionId ? { sessionId } : {}),@@ -496,6 +558,8 @@ function normalizePayload(payload: unknown): NormalizedPayload {...(rootSessionId ? { rootSessionId } : {}),...(compressionDepth !== undefined ? { compressionDepth } : {}),...(sessionStartSource ? { sessionStartSource } : {}),+ ...(workId ? { workId } : {}),+ ...(laneId ? { laneId } : {}),...(record["interrupted"] === true ? { interrupted: true } : {}),...(extractPromptText(record) ? { promptText: extractPromptText(record)! } : {}),...(readNonEmptyString(record["tool_name"])diff --git a/src/core/brain/skill-proposals.ts b/src/core/brain/skill-proposals.tsindex f7eec510..a39979d1 100644--- a/src/core/brain/skill-proposals.ts+++ b/src/core/brain/skill-proposals.ts@@ -44,11 +44,35 @@ import {import { assertVaultIdentityForWrite } from "./vault-identity.ts";import { listContinuityRecords, type ContinuityRecord } from "./continuity/store.ts";+/**+ * Pattern kind stamped on a proposal an author DECLARED through an+ * `@osb skill` marker rather than one the miner inferred from+ * continuity records.+ *+ * It is deliberately outside the verifier gate. That gate+ * (`skill-proposal-verifier.ts`) scores a MINED candidate against its own+ * supporting records - at least `VERIFIER_MIN_EVIDENCE` (3) distinct+ * records structurally supporting the pattern, plus a confidence floor -+ * so a thin or padded inference never reaches a human. A declaration has+ * exactly one piece of evidence, the declaration itself, and claims no+ * statistical confidence, so running the same gate over it would reject+ * every marker and make the feature a silent no-op. The review gate that+ * does apply is the human one: a declared proposal lands in `pending` and+ * is promoted only by `acceptSkillProposal`.+ */+export const DECLARED_MARKER_PATTERN_KIND = "declared_marker";+export type SkillProposalPatternKind =| "repeated_action"| "structural_similarity"| "co_occurrence"- | "temporal_routine";+ | "temporal_routine"+ | typeof DECLARED_MARKER_PATTERN_KIND;++/** The three phases a proposal file can live in, most terminal first. */+const PROPOSAL_PHASES = ["accepted", "rejected", "pending"] as const;++export type SkillProposalPhase = (typeof PROPOSAL_PHASES)[number];export interface SkillProposalLearnOptions {readonly now?: Date;@@ -123,7 +147,7 @@ export type SkillEvidenceOutcomeState = "unrecorded" | "successful" | "failing"export interface SkillProposalEvidence {readonly slug: string;readonly id: string;- readonly phase: "pending" | "accepted" | "rejected";+ readonly phase: SkillProposalPhase;/** Support the proposal claims from its own pattern match - self-reported. */readonly claimedEvidenceCount: number;readonly claimedConfidence: number;@@ -165,6 +189,17 @@ const DEFAULT_PROCEDURAL_ROOTS = ["Brain/procedures", "skills"] as const;/** Version stamped on a freshly-drafted skill; increments on evolution. */const SKILL_PROPOSAL_INITIAL_VERSION = 1;+/** Slug budget: how much of the pattern key survives, and the hash suffix length. */+const PROPOSAL_SLUG_KEY_MAX_LEN = 40;+const PROPOSAL_SLUG_HASH_LEN = 8;++/**+ * Heading that separates the reviewable skill body from the pattern and+ * evidence sections. `renderAcceptedProcedureBody` splits on it, so both+ * the writer and the reader must name it from here.+ */+const SUGGESTED_BODY_HEADING = "## Suggested skill body";+/** Lock basename guarding the accept sequence, inside the proposals root. */const ACCEPT_LOCK_NAME = "accept";@@ -353,6 +388,220 @@ export function listPendingSkillProposals(vault: string): ReadonlyArray<{return Object.freeze(out);}+/** A declared skill proposal was rejected before anything was written. */+export class DeclaredSkillProposalError extends Error {+ constructor(message: string) {+ super(message);+ this.name = "DeclaredSkillProposalError";+ }+}++export interface DeclaredSkillProposalInput {+ /** Human-facing skill name; its slug is the proposal's identity key. */+ readonly name: string;+ /** What the skill does, carried verbatim into the reviewable body. */+ readonly body: string;+ /** Where the declaration was found, as wikilinks. */+ readonly sourceRefs: ReadonlyArray<string>;+ readonly now?: Date;+}++/**+ * What a declaration did, by name.+ *+ * - `created` - a new pending draft was written.+ * - `deduped` - an equivalent draft is already PENDING review, so the+ * declaration resolved to it and nothing was written.+ * - `suppressed`- the queue declined: the name is already reviewed+ * (accepted or rejected), or a file already occupies the+ * slug. Nothing was written and the declared body was+ * NOT stored anywhere.+ *+ * The three are distinct because the caller's next move differs: a+ * `deduped` declaration is safely consumed - the same skill is already+ * queued for a human - while a `suppressed` one has nowhere its content+ * survives, so consuming its marker would destroy the only copy.+ */+export type DeclaredSkillProposalOutcome = "created" | "deduped" | "suppressed";++interface DeclaredSkillProposalResultBase {+ readonly id: string;+ readonly slug: string;+ /** The proposal file this declaration created or resolved to. */+ readonly path: string;+}++export type DeclaredSkillProposalResult = DeclaredSkillProposalResultBase &+ (+ | { readonly outcome: "created" | "deduped" }+ /** `reason` is required here: a decline the caller cannot explain is a silent drop. */+ | { readonly outcome: "suppressed"; readonly reason: string }+ );++/**+ * Draft a PENDING proposal from an author's `@osb skill` declaration.+ *+ * The write lands in `pending` and nowhere else: acceptance stays the+ * human step, exactly as it is for a mined proposal. See+ * {@link DECLARED_MARKER_PATTERN_KIND} for why the mining verifier is not+ * in this path. No `confidence` key is written either - a declaration+ * makes no statistical claim, and `resolveSkillProposalEvidence` already+ * reads an absent claim as zero self-reported support.+ *+ * One name, one proposal: see {@link DeclaredSkillProposalOutcome} for+ * what happens when the name is taken.+ */+export function draftDeclaredSkillProposal(+ vault: string,+ input: DeclaredSkillProposalInput,+): DeclaredSkillProposalResult {+ // Vault-identity write guard (context-integrity-gates, Unit J).+ assertVaultIdentityForWrite(vault);+ const planned = planDeclaredSkillProposal(vault, input);+ if ("declined" in planned) return planned.declined;+ const plan = planned.plan;++ const now = (input.now ?? new Date()).toISOString();+ const sourceRefs = [...input.sourceRefs];++ writeFrontmatterAtomic(+ plan.path,+ {+ schema_version: 1,+ kind: "brain-skill-proposal",+ id: plan.id,+ slug: plan.slug,+ status: "pending",+ pattern_kind: DECLARED_MARKER_PATTERN_KIND,+ name_key: plan.nameKey,+ version: SKILL_PROPOSAL_INITIAL_VERSION,+ payload_hash: plan.payloadHash,+ created_at: now,+ updated_at: now,+ evidence_count: String(sourceRefs.length),+ source_refs: sourceRefs,+ },+ renderProposalDocument({+ title: plan.name,+ patternKind: DECLARED_MARKER_PATTERN_KIND,+ key: plan.key,+ suggestedBody: plan.body.split("\n"),+ evidence: sourceRefs.map((ref) => `- declared in ${ref}`),+ }),+ {+ overwrite: false,+ existsErrorKind: "skill proposal",+ vaultForRelativePath: vault,+ },+ );++ return { id: plan.id, slug: plan.slug, path: plan.path, outcome: "created" };+}++/**+ * What {@link draftDeclaredSkillProposal} would do, without writing.+ *+ * Same validation, same identity derivation, same decline reasons - the+ * two share {@link planDeclaredSkillProposal}, so a preview cannot report+ * an outcome the writer would not reach. Used by `scan-inline --dry-run`,+ * which must count and report what a real run would do while touching+ * nothing.+ */+export function previewDeclaredSkillProposal(+ vault: string,+ input: DeclaredSkillProposalInput,+): DeclaredSkillProposalResult {+ const planned = planDeclaredSkillProposal(vault, input);+ if ("declined" in planned) return planned.declined;+ const plan = planned.plan;+ return { id: plan.id, slug: plan.slug, path: plan.path, outcome: "created" };+}++/** Everything a declared draft needs, once the queue has agreed to take it. */+interface DeclaredSkillProposalPlan {+ readonly id: string;+ readonly slug: string;+ readonly path: string;+ readonly name: string;+ readonly body: string;+ readonly key: string;+ readonly nameKey: string;+ readonly payloadHash: string;+}++/**+ * Decide what a declaration does before anything is written: a plan to+ * draft, or the outcome the queue declined with.+ *+ * Both guards below refuse by name rather than letting the exclusive+ * write throw an untyped `EEXIST` later - the same two guards the mined+ * path carries in `learnSkillProposals`, in the same order.+ */+function planDeclaredSkillProposal(+ vault: string,+ input: DeclaredSkillProposalInput,+):+ | { readonly plan: DeclaredSkillProposalPlan }+ | { readonly declined: DeclaredSkillProposalResult } {+ const name = input.name.trim();+ if (!name) throw new DeclaredSkillProposalError("declared skill proposal requires a name");+ const body = input.body.trim();+ if (!body) throw new DeclaredSkillProposalError(`declared skill proposal '${name}' has no body`);++ const key = slugify(name);+ const nameKey = nameKeyFor(DECLARED_MARKER_PATTERN_KIND, key);+ for (const phase of PROPOSAL_PHASES) {+ const existing = findProposalByNameKey(vault, phase, nameKey);+ if (existing === null) continue;+ const found = { id: existing.id, slug: existing.slug, path: existing.path };+ if (phase === "pending") return { declined: { ...found, outcome: "deduped" } };+ return {+ declined: {+ ...found,+ outcome: "suppressed",+ reason:+ `a skill proposal named '${name}' is already ${phase} (${existing.id}); ` ++ "this declaration was not drafted and its body was not stored",+ },+ };+ }++ const payloadHash = createHash("sha256")+ .update(JSON.stringify({ patternKind: DECLARED_MARKER_PATTERN_KIND, key, body }), "utf8")+ .digest("hex");+ const slug = composeProposalSlug(DECLARED_MARKER_PATTERN_KIND, key, payloadHash);+ const id = `prop-${slug}`;++ for (const phase of PROPOSAL_PHASES) {+ const occupied = proposalPhasePath(vault, phase, slug);+ if (!existsSync(occupied)) continue;+ return {+ declined: {+ id,+ slug,+ path: occupied,+ outcome: "suppressed",+ reason:+ `a skill proposal file already occupies slug '${slug}' under ${phase}/; ` ++ "this declaration was not drafted and its body was not stored",+ },+ };+ }++ return {+ plan: {+ id,+ slug,+ path: skillProposalPendingPath(vault, slug),+ name,+ body,+ key,+ nameKey,+ payloadHash,+ },+ };+}+/*** Accept a pending proposal: archive it, materialize its procedure, drop* the pending copy, reproject.@@ -723,17 +972,25 @@ function outcomeState(successes: number, failures: number): SkillEvidenceOutcomereturn failures > 0 ? "failing" : "successful";}+/** Where a proposal with `slug` lives while it is in `phase`. */+function proposalPhasePath(vault: string, phase: SkillProposalPhase, slug: string): string {+ switch (phase) {+ case "accepted":+ return skillProposalAcceptedPath(vault, slug);+ case "rejected":+ return skillProposalRejectedPath(vault, slug);+ case "pending":+ return skillProposalPendingPath(vault, slug);+ }+}+/** Locate a proposal in whichever phase holds it, terminal phases first. */function findReviewedProposal(vault: string,slug: string,-): { phase: "pending" | "accepted" | "rejected"; fm: Record<string, unknown> } {- const candidates = [- ["accepted", skillProposalAcceptedPath(vault, slug)],- ["rejected", skillProposalRejectedPath(vault, slug)],- ["pending", skillProposalPendingPath(vault, slug)],- ] as const;- for (const [phase, path] of candidates) {+): { phase: SkillProposalPhase; fm: Record<string, unknown> } {+ for (const phase of PROPOSAL_PHASES) {+ const path = proposalPhasePath(vault, phase, slug);if (!existsSync(path)) continue;const [fm] = parseFrontmatter(path);return { phase, fm: fm as Record<string, unknown> };@@ -819,7 +1076,12 @@ function watermarkPath(vault: string): string {/** Stable name identity of a candidate, independent of the specific records. */function candidateNameKey(candidate: ProposalCandidate): string {- return `${candidate.patternKind}:${candidate.key}`;+ return nameKeyFor(candidate.patternKind, candidate.key);+}++/** The stored `name_key`, shared by the mined and the declared paths. */+function nameKeyFor(patternKind: SkillProposalPatternKind, key: string): string {+ return `${patternKind}:${key}`;}/** Source references a candidate contributes (record ids plus their source ids). */@@ -884,7 +1146,7 @@ interface FoundProposal {/** Find the first proposal in `phase` whose stored name key matches. */function findProposalByNameKey(vault: string,- phase: "pending" | "accepted" | "rejected",+ phase: SkillProposalPhase,nameKey: string,): FoundProposal | null {const dir = ensureInsideVault(join(vault, BRAIN_SKILL_PROPOSALS_REL, phase), vault);@@ -1112,30 +1374,49 @@ function confidence(support: number, minSupport: number): number {return Math.max(0.55, Math.round(raw * 1000) / 1000);}-function renderProposalBody(candidate: ProposalCandidate): string {- const evidence = candidate.records- .map((record) => {- const snippet = evidenceSnippet(record);- return `- ${record.createdAt} :: ${record.kind} :: ${record.id}${snippet ? ` :: ${snippet}` : ""}`;- })- .join("\n");-+/**+ * The one proposal document shape, whether the pattern was mined or+ * declared. Section order and headings are a contract with+ * `renderAcceptedProcedureBody`, so both producers go through here.+ */+function renderProposalDocument(input: {+ readonly title: string;+ readonly patternKind: SkillProposalPatternKind;+ readonly key: string;+ readonly suggestedBody: ReadonlyArray<string>;+ readonly evidence: ReadonlyArray<string>;+}): string {return [- `# ${candidate.suggestedTitle}`,+ `# ${input.title}`,"","## Pattern",- `- kind: ${candidate.patternKind}`,- `- key: ${candidate.key}`,+ `- kind: ${input.patternKind}`,+ `- key: ${input.key}`,"",- "## Suggested skill body",- `When pattern \`${candidate.key}\` appears, follow the observed repeatable workflow.`,- "Capture inputs first, execute steps in stable order, and emit audit-friendly outputs.",+ SUGGESTED_BODY_HEADING,+ ...input.suggestedBody,"","## Evidence",- evidence,+ ...input.evidence,].join("\n");}+function renderProposalBody(candidate: ProposalCandidate): string {+ return renderProposalDocument({+ title: candidate.suggestedTitle,+ patternKind: candidate.patternKind,+ key: candidate.key,+ suggestedBody: [+ `When pattern \`${candidate.key}\` appears, follow the observed repeatable workflow.`,+ "Capture inputs first, execute steps in stable order, and emit audit-friendly outputs.",+ ],+ evidence: candidate.records.map((record) => {+ const snippet = evidenceSnippet(record);+ return `- ${record.createdAt} :: ${record.kind} :: ${record.id}${snippet ? ` :: ${snippet}` : ""}`;+ }),+ });+}+function evidenceSnippet(record: ContinuityRecord): string {const payload = record.payload as Record<string, unknown>;for (const field of ["query", "summary", "note", "text"]) {@@ -1148,8 +1429,15 @@ function evidenceSnippet(record: ContinuityRecord): string {}function proposalSlug(candidate: ProposalCandidate, payloadHash: string): string {- const keySlug = slugify(candidate.key).slice(0, 40);- return `${candidate.patternKind}-${keySlug}-${payloadHash.slice(0, 8)}`;+ return composeProposalSlug(candidate.patternKind, slugify(candidate.key), payloadHash);+}++function composeProposalSlug(+ patternKind: SkillProposalPatternKind,+ keySlug: string,+ payloadHash: string,+): string {+ return `${patternKind}-${keySlug.slice(0, PROPOSAL_SLUG_KEY_MAX_LEN)}-${payloadHash.slice(0, PROPOSAL_SLUG_HASH_LEN)}`;}function candidateHash(candidate: ProposalCandidate): string {@@ -1166,9 +1454,9 @@ function candidateHash(candidate: ProposalCandidate): string {}function renderAcceptedProcedureBody(proposalId: string, proposalBody: string): string {- const marker = "## Suggested skill body";- const idx = proposalBody.indexOf(marker);- const suggested = idx >= 0 ? proposalBody.slice(idx + marker.length).trim() : proposalBody.trim();+ const idx = proposalBody.indexOf(SUGGESTED_BODY_HEADING);+ const suggested =+ idx >= 0 ? proposalBody.slice(idx + SUGGESTED_BODY_HEADING.length).trim() : proposalBody.trim();return ["# Procedure","",diff --git a/src/core/brain/types.ts b/src/core/brain/types.tsindex bde2e470..485840ee 100644--- a/src/core/brain/types.ts+++ b/src/core/brain/types.ts@@ -289,6 +289,18 @@ export const BRAIN_LOG_EVENT_KIND = {* double-fire on a single write.*/writeConflictAdvisory: "write-conflict-advisory",+ /**+ * `capture-routing-hint` (signals-that-survive unit 4, t_75597bb9) - a+ * feedback signal was written that resolved NO scope, so no scoped+ * recall reaches it. The hint NEVER blocks the write; this event is+ * its durable, queryable record, and it is what makes the unrouted-+ * capture rate countable at all - a hint that fires and is never+ * recorded cannot be measured. Payload carries the missing routing+ * signal (`missing_signal`), the eligible scope slugs with their+ * document frequency (`candidates`), and the `agent`. Fires only on+ * the operator-facing feedback path, never on the extracted-fact path.+ */+ captureRoutingHint: "capture-routing-hint",/*** `signal-retire` (A5, t_66c12a67) - an extracted fact signal was* retired: moved from `Brain/inbox/` into `Brain/retired/` with retire@@ -960,7 +972,7 @@ export interface BrainRollbackLogEvent extends BrainLogEventBase {/*** `scan-inline` entry β operator ran `o2b brain scan-inline`. Payload* keys are counters: `scanned`, `found`, `created`, `deduped`,- * `malformed`, `errors`, plus the agent identity.+ * `malformed`, `facts`, `skills`, `errors`, plus the agent identity.*/export interface BrainScanInlineLogEvent extends BrainLogEventBase {readonly kind: typeof BRAIN_LOG_EVENT_KIND.scanInline;diff --git a/src/core/brain/write-advisory.ts b/src/core/brain/write-advisory.tsindex 818ea4b1..5ac08541 100644--- a/src/core/brain/write-advisory.ts+++ b/src/core/brain/write-advisory.ts@@ -1,6 +1,17 @@/*** A4 (t_f79b4fe0): write-time conflict advisory seam.*+ * Two advisories live here, both built to the same shape: computed+ * AROUND an operator-facing feedback write, never gating it, returned as+ * a structured value the CLI and MCP surfaces render, and recorded under+ * its own log-event kind so what fired stays countable.+ *+ * - {@link adviseIncomingFeedback} - the incoming principle resembles a+ * confirmed same-scope preference (t_f79b4fe0).+ * - {@link adviseUnroutableCapture} - the capture resolved NO scope, so+ * it lands in the one bucket scoped recall never reaches+ * (signals-that-survive, unit 4 / t_75597bb9).+ ** When an operator records a feedback signal, this seam compares the* incoming principle against confirmed same-scope preferences and, when a* near-duplicate is found, returns a non-blocking advisory naming the@@ -28,11 +39,19 @@ import { join } from "node:path";import { adviseOnIncoming, type PreferenceForContradiction } from "./health/contradiction.ts";import { appendLogEvent } from "./log.ts";+import { nextCommandField, requireNextStep, type NextCommandField } from "./next-step.ts";import { brainDirs } from "./paths.ts";import { parsePreference } from "./preference.ts";+import { parseSignal } from "./signal.ts";import { isoSecond } from "./time.ts";import { BRAIN_LOG_EVENT_KIND, BRAIN_PREFERENCE_STATUS } from "./types.ts";+/** Extension every Brain corpus document on disk carries. */+const MARKDOWN_EXT = ".md";++/** Bucket key standing for "carries no scope", shared with `adviseOnIncoming`. */+const UNSCOPED_BUCKET = "";+/** One resembling preference: its id and the incoming-vs-confirmed jaccard. */export interface WriteConflictEvidence {readonly pref_id: string;@@ -62,23 +81,21 @@ export interface AdviseIncomingFeedbackParams {readonly now?: Date;}+/** The Markdown documents in `dir`, or nothing when it does not exist. */+function markdownNames(dir: string): ReadonlyArray<string> {+ if (!existsSync(dir)) return [];+ return readdirSync(dir).filter((name) => name.endsWith(MARKDOWN_EXT));+}+/**- * Load the confirmed preferences in the incoming signal's scope bucket.- * Scope-bucket loading only: preferences in a different scope (and every- * non-confirmed preference) are dropped here rather than compared. A- * corrupt / mis-foldered preference file is skipped (that is the doctor's- * concern, not the write path's).+ * Every confirmed preference in the vault. A corrupt / mis-foldered+ * preference file is skipped (that is the doctor's concern, not the write+ * path's).*/-function loadConfirmedScopePrefs(- vault: string,- scope: string | undefined,-): PreferenceForContradiction[] {+function loadConfirmedPrefs(vault: string): PreferenceForContradiction[] {const dir = brainDirs(vault).preferences;- if (!existsSync(dir)) return [];- const bucketKey = scope ?? "";const out: PreferenceForContradiction[] = [];- for (const name of readdirSync(dir)) {- if (!name.endsWith(".md")) continue;+ for (const name of markdownNames(dir)) {let pref;try {pref = parsePreference(join(dir, name));@@ -86,12 +103,24 @@ function loadConfirmedScopePrefs(continue;}if (pref.status !== BRAIN_PREFERENCE_STATUS.confirmed) continue;- if ((pref.scope ?? "") !== bucketKey) continue;out.push(pref);}return out;}+/**+ * Load the confirmed preferences in the incoming signal's scope bucket.+ * Scope-bucket loading only: preferences in a different scope (and every+ * non-confirmed preference) are dropped here rather than compared.+ */+function loadConfirmedScopePrefs(+ vault: string,+ scope: string | undefined,+): PreferenceForContradiction[] {+ const bucketKey = scope ?? UNSCOPED_BUCKET;+ return loadConfirmedPrefs(vault).filter((pref) => (pref.scope ?? UNSCOPED_BUCKET) === bucketKey);+}+/*** Compute (and log) the write-time conflict advisory for an incoming* feedback signal. Returns the advisory when a confirmed same-scope@@ -144,3 +173,184 @@ export function adviseIncomingFeedback(return null;}}++// ----- Unroutable-capture routing hint (unit 4, t_75597bb9) ----------------++/**+ * The routing signal a capture can be missing. Written once: it is the+ * signal frontmatter field, the flag name the exit command carries, and+ * the value the hint reports as absent.+ */+export const ROUTING_SIGNAL_FIELD = "scope";++/**+ * Registry code the routing hint's forward pointer resolves through. The+ * hint NAMES no command itself - the surfaces resolve this code, so the+ * exit is the registry's structural CLI string on every stream.+ */+export const CAPTURE_ROUTING_HINT_CODE = "capture-scope-absent";++/**+ * Resolved at module scope on purpose. This hint's whole value is telling+ * an operator how to route the capture, so an unregistered code is+ * registry drift rather than a case to handle: it fails at import instead+ * of inside the advisory it was meant to explain (see `next-step.ts`).+ */+const CAPTURE_ROUTING_HINT_STEP = requireNextStep(CAPTURE_ROUTING_HINT_CODE);++/** One scope slug the vault already uses, with the documents carrying it. */+export interface ScopeCandidate {+ readonly scope: string;+ /** Documents observed with this scope: its document frequency. */+ readonly documents: number;+}++/**+ * The routing hint surfaced to the feedback response / CLI output.+ * Present only when the capture resolved no scope AND the vault holds a+ * scope corpus to suggest from.+ */+export interface CaptureRoutingHint {+ /** The routing signal the capture lacked. */+ readonly missing_signal: string;+ /** Diagnostic code the surfaces resolve the forward pointer through. */+ readonly code: string;+ /** Non-empty, ranked by document frequency then slug. */+ readonly candidates: ReadonlyArray<ScopeCandidate>;+}++/**+ * The additive JSON key both machine-readable surfaces carry the hint+ * in, plus its forward pointer already resolved.+ *+ * Named and composed once for the same reason `NEXT_COMMAND_KEY` is: the+ * CLI `--json` renderer and its MCP twin must not drift on a spelling or+ * on which fields ride along. A consumer that learns the shape from one+ * surface reads it on the other.+ */+export const CAPTURE_ROUTING_HINT_KEY = "routing_hint";++export type CaptureRoutingHintField = {+ readonly [CAPTURE_ROUTING_HINT_KEY]?: CaptureRoutingHint & NextCommandField;+};++/** Absent case: no hint contributes no key whatsoever. */+const NO_CAPTURE_ROUTING_HINT: CaptureRoutingHintField = Object.freeze({});++/**+ * Resolve a hint into the object to spread onto a machine-readable+ * response. `null` yields the empty object, so the key is ABSENT rather+ * than present-and-null.+ */+export function captureRoutingHintField(hint: CaptureRoutingHint | null): CaptureRoutingHintField {+ if (hint === null) return NO_CAPTURE_ROUTING_HINT;+ return Object.freeze({+ [CAPTURE_ROUTING_HINT_KEY]: Object.freeze({ ...hint, ...nextCommandField(hint.code) }),+ });+}++export interface AdviseUnroutableCaptureParams {+ /**+ * The capture's effective scope (already resolved against+ * `feedback.default_scope`). Absent / blank is the unroutable case.+ */+ readonly scope?: string;+ /** Agent identity stamped on the hint log event. */+ readonly agent: string;+ /** Injected clock for a deterministic log timestamp. Defaults to now. */+ readonly now?: Date;+}++/**+ * Document frequency of every scope slug the vault declares.+ *+ * Two sources, both frontmatter: confirmed preferences (the rules scoped+ * recall actually reaches) and the OPEN signal inbox. The inbox is what+ * "recent" means structurally here - `inbox/processed/` is the archive+ * the dream pass has already consumed - so recency needs no window+ * constant and no clock.+ *+ * A corrupt signal is skipped, exactly as the conflict advisory skips a+ * corrupt preference - but the skip is REPORTED. Its scope is precisely+ * what could not be read, so it cannot be counted; leaving it silent+ * would change a ranking the operator reads with nothing to explain why.+ */+function countScopeDocuments(vault: string): ReadonlyMap<string, number> {+ const counts = new Map<string, number>();+ const tally = (scope: string | undefined): void => {+ const slug = scope?.trim();+ if (!slug) return;+ counts.set(slug, (counts.get(slug) ?? 0) + 1);+ };+ for (const pref of loadConfirmedPrefs(vault)) tally(pref.scope);+ const inbox = brainDirs(vault).inbox;+ for (const name of markdownNames(inbox)) {+ const path = join(inbox, name);+ try {+ tally(parseSignal(path).scope);+ } catch (err) {+ process.stderr.write(+ `warning: capture routing hint skipped unreadable signal ${path}: ${+ (err as Error).message+ }\n`,+ );+ }+ }+ return counts;+}++/**+ * Compute the routing hint for a capture that resolved no scope. Returns+ * `null` when the capture IS routable, and when the vault has no scope+ * corpus to suggest from - an empty candidate list would be prose that+ * names nothing, which is the dead end this unit removes rather than adds.+ *+ * Never throws: any failure is reported as a stderr warning and returns+ * `null`, so the surrounding feedback write is never affected.+ */+export function adviseUnroutableCapture(+ vault: string,+ params: AdviseUnroutableCaptureParams,+): CaptureRoutingHint | null {+ if (params.scope?.trim()) return null;+ try {+ const candidates = [...countScopeDocuments(vault)]+ .map(([scope, documents]) => Object.freeze({ scope, documents }))+ .toSorted((a, b) => b.documents - a.documents || a.scope.localeCompare(b.scope));+ if (candidates.length === 0) return null;++ const result: CaptureRoutingHint = Object.freeze({+ missing_signal: ROUTING_SIGNAL_FIELD,+ code: CAPTURE_ROUTING_HINT_STEP.code,+ candidates: Object.freeze(candidates),+ });++ try {+ appendLogEvent(vault, {+ timestamp: isoSecond(params.now ?? new Date()),+ eventType: BRAIN_LOG_EVENT_KIND.captureRoutingHint,+ agent: params.agent,+ body: {+ missing_signal: result.missing_signal,+ // One bullet per eligible scope: slug + the document frequency+ // that ranked it, so the rate of unrouted captures AND what+ // they could have been routed to are both countable later.+ candidates: result.candidates.map((c) => `${c.scope} documents=${c.documents}`),+ agent: params.agent,+ },+ });+ } catch (err) {+ process.stderr.write(+ `warning: append capture-routing-hint log failed: ${(err as Error).message}\n`,+ );+ }++ return result;+ } catch (err) {+ // Hint computation is best-effort and NEVER blocks the write.+ process.stderr.write(+ `warning: capture routing hint computation failed: ${(err as Error).message}\n`,+ );+ return null;+ }+}diff --git a/src/core/fs/git-discovery.ts b/src/core/fs/git-discovery.tsnew file mode 100644index 00000000..9f7b0c03--- /dev/null+++ b/src/core/fs/git-discovery.ts@@ -0,0 +1,262 @@+/**+ * Git-aware discovery: the ignore layering a repository declares about itself.+ *+ * Two walkers need the same three facts about a tree - what the root excludes+ * (`.git/info/exclude` plus the root `.gitignore`), what a given directory+ * excludes for its own subtree (a nested `.gitignore`), and where the working+ * tree stops (a submodule or a nested repository). The hygiene repo scan+ * ({@link ../hygiene/scan-repo.ts}) grew that layering first; the ingest batch+ * planner ({@link ../brain/ingest/batch-plan.ts}) needs it too. This module is+ * the one implementation both compose, so the precedence order cannot drift+ * between them.+ *+ * Matching itself is NOT reimplemented here: every layer is compiled by the+ * shared engine in {@link ./ignore.ts}, which owns the documented gitignore+ * subset. This module only decides which files are read and in what order they+ * stack.+ *+ * ## Base-dir contract+ *+ * `IgnoreLayer.baseDir` and the paths later passed to+ * {@link IgnoreScope.isIgnored} must be expressed in ONE path space, and this+ * module never assumes which one. The caller names it by passing the POSIX+ * path of the governed directory relative to the root of its own space:+ *+ * - the hygiene scan walks a repository and matches repo-root-relative paths,+ * so it passes `""` for the repository root;+ * - the ingest planner walks a source directory inside a vault and matches+ * vault-relative paths, so it passes the source dir's vault-relative path+ * for that same repository root.+ *+ * The `source` recorded on a warning follows the same space, which makes a+ * warning's provenance meaningful to whichever surface reports it.+ *+ * ## Stream discipline+ *+ * A malformed pattern is RETURNED as a structured {@link IgnoreWarning}, and so+ * is an ignore file that exists but cannot be honoured (unreadable, a symlink,+ * oversized). This is kernel code: it never writes to a stream, so the hygiene+ * scan can keep its `hygiene:` stderr sink while the ingest planner carries the+ * same warnings out on its plan. Nothing is ever dropped silently - a+ * declaration the walker could not apply always leaves a warning behind.+ */++import { lstatSync, readFileSync, statSync, type Stats } from "node:fs";+import { join } from "node:path";++import { IgnoreScope, parseIgnoreLayer, type IgnoreWarning } from "./ignore.ts";++/** Git's per-repository metadata entry: a directory, or a gitlink file. */+const GIT_ENTRY = ".git";++/** Per-directory ignore file, governing the subtree rooted at its directory. */+const GITIGNORE_FILE = ".gitignore";++/** Repo-local exclude file, layered beneath every `.gitignore`. */+const GIT_INFO_EXCLUDE_PATH: ReadonlyArray<string> = [GIT_ENTRY, "info", "exclude"];++/** Provenance recorded for a warning raised by the repo-local exclude file. */+const GIT_INFO_EXCLUDE_SOURCE = GIT_INFO_EXCLUDE_PATH.join("/");++/**+ * Largest ignore file this module will read. A `.gitignore` is a hand-written+ * list of patterns; anything past this is not one, and reading it unbounded+ * would let a single path stall or exhaust the walker.+ */+export const MAX_IGNORE_FILE_BYTES = 1024 * 1024;++/**+ * Line recorded on a warning that concerns no single pattern line - an ignore+ * file that could not be read at all, or a scoping decision a caller made about+ * a whole subtree. Pattern lines are 1-based, so zero can never collide with+ * one, and a surface can tell the two apart to render them differently.+ */+export const IGNORE_WARNING_NO_LINE = 0;++/** Errno codes that mean "there is simply no ignore file here" - the normal case. */+const ABSENT_FILE_CODES: ReadonlySet<string> = new Set(["ENOENT", "ENOTDIR"]);++/**+ * Render one warning as a single human-readable line, so every surface that+ * reports these (the hygiene stderr sink, the CLI plan output) words them+ * identically. Callers add their own prefix and indentation.+ */+export function formatIgnoreWarning(warning: IgnoreWarning): string {+ return warning.line === IGNORE_WARNING_NO_LINE+ ? `${warning.source}: ${warning.reason}`+ : `malformed ignore pattern at ${warning.source}:${warning.line} ` ++ `(${warning.pattern}): ${warning.reason}`;+}++/** A composed scope plus every malformed pattern found while composing it. */+export interface DiscoveredScope {+ readonly scope: IgnoreScope;+ /** Empty when every pattern read compiled cleanly. */+ readonly warnings: readonly IgnoreWarning[];+}++/** Join a base directory and a name in the caller's POSIX path space. */+function inBaseDir(baseDir: string, name: string): string {+ return baseDir === "" ? name : `${baseDir}/${name}`;+}++/** A warning about the ignore FILE rather than about one pattern inside it. */+function fileWarning(source: string, reason: string): IgnoreWarning {+ return { source, line: IGNORE_WARNING_NO_LINE, pattern: "", reason };+}++/** The errno code of an I/O failure, or its message when it carries no code. */+function ioReason(err: unknown): string {+ const code = (err as NodeJS.ErrnoException | null)?.code;+ if (typeof code === "string") return code;+ return err instanceof Error ? err.message : String(err);+}++/**+ * Read one ignore file, or return null and push a warning saying why it was not+ * read. An ABSENT file is the ordinary case and warns nothing; every other+ * refusal is reported, because a declaration the walker cannot apply changes+ * what the walk returns and the operator has to be able to see that.+ *+ * A symlinked ignore file is refused outright rather than resolved: the walk+ * itself never follows symlinked directories, so honouring one here would read+ * patterns from outside the tree being walked (`/etc/shadow`) or from a stream+ * with no end (`/dev/zero`). Containment-checking the resolved target was the+ * alternative; refusal is chosen because this module is composed by callers+ * walking different path spaces (a repo root, a vault subdirectory) and it must+ * not have to know which boundary "contained" means for each of them.+ */+function readIgnoreFile(+ filePath: string,+ source: string,+ warnings: IgnoreWarning[],+): string | null {+ let stats: Stats;+ try {+ // lstat, NOT stat: a symlink must be seen as itself, not as its target.+ stats = lstatSync(filePath);+ } catch (err) {+ const code = ioReason(err);+ if (!ABSENT_FILE_CODES.has(code)) {+ warnings.push(fileWarning(source, `ignore file could not be inspected (${code})`));+ }+ return null;+ }+ if (stats.isSymbolicLink()) {+ warnings.push(fileWarning(source, "ignore file is a symbolic link and was not read"));+ return null;+ }+ if (!stats.isFile()) {+ warnings.push(fileWarning(source, "ignore file is not a regular file and was not read"));+ return null;+ }+ if (stats.size > MAX_IGNORE_FILE_BYTES) {+ warnings.push(+ fileWarning(+ source,+ `ignore file is ${stats.size} bytes, over the ${MAX_IGNORE_FILE_BYTES}-byte limit, ` ++ "and was not read",+ ),+ );+ return null;+ }+ try {+ return readFileSync(filePath, "utf8");+ } catch (err) {+ warnings.push(fileWarning(source, `ignore file could not be read (${ioReason(err)})`));+ return null;+ }+}++/**+ * Read one ignore file and stack it at the highest precedence. A file that+ * cannot be honoured leaves the scope untouched - refusing to walk the tree over+ * it would be a worse answer than walking it unfiltered - but never quietly:+ * {@link readIgnoreFile} records why on `warnings`.+ */+function extendWithIgnoreFile(+ scope: IgnoreScope,+ filePath: string,+ baseDir: string,+ source: string,+ warnings: IgnoreWarning[],+): IgnoreScope {+ const content = readIgnoreFile(filePath, source, warnings);+ if (content === null) return scope;+ const parsed = parseIgnoreLayer(content, baseDir, source);+ warnings.push(...parsed.warnings);+ return scope.extend(parsed.layer);+}++/**+ * Base scope for a repository: `.git/info/exclude` at the lowest precedence,+ * then the root `.gitignore` above it - so a re-include the tracked file+ * declares wins over the untracked local one, matching git's own ordering.+ *+ * `baseDir` names `repoRoot`'s position in the caller's path space; see the+ * base-dir contract above.+ */+export function buildRepositoryBaseScope(repoRoot: string, baseDir: string): DiscoveredScope {+ const warnings: IgnoreWarning[] = [];+ let scope = IgnoreScope.empty();+ scope = extendWithIgnoreFile(+ scope,+ join(repoRoot, ...GIT_INFO_EXCLUDE_PATH),+ baseDir,+ inBaseDir(baseDir, GIT_INFO_EXCLUDE_SOURCE),+ warnings,+ );+ scope = extendWithIgnoreFile(+ scope,+ join(repoRoot, GITIGNORE_FILE),+ baseDir,+ inBaseDir(baseDir, GITIGNORE_FILE),+ warnings,+ );+ return { scope, warnings };+}++/**+ * Stack `dir`'s own `.gitignore` on top of `scope`, governing `dir`'s subtree.+ * Returns `scope` itself when the directory declares nothing, so a walk over a+ * tree with no nested ignore files allocates no layers.+ *+ * `baseDir` names `dir`'s position in the caller's path space.+ */+export function extendWithDirectoryIgnore(+ scope: IgnoreScope,+ dir: string,+ baseDir: string,+): DiscoveredScope {+ const warnings: IgnoreWarning[] = [];+ const extended = extendWithIgnoreFile(+ scope,+ join(dir, GITIGNORE_FILE),+ baseDir,+ inBaseDir(baseDir, GITIGNORE_FILE),+ warnings,+ );+ return { scope: extended, warnings };+}++/**+ * Whether `dir` is the root of a repository other than the one being walked -+ * a submodule or worktree (`.git` is a gitlink file) or a nested independent+ * checkout (`.git` is a directory). Either way its contents belong to that+ * repository's index, not the outer walk's, so a caller descending into it+ * would attribute foreign files to the tree it was asked about.+ *+ * The walk root itself is exempt: it is a repository root in the ordinary case,+ * and pruning it would empty the walk. Every OTHER directory a caller enters+ * must be checked - including the ones a caller starting deeper in the tree+ * (an ingest `--src-subpath`) descends past without ever reading them as+ * `readdir` entries. Checking only `readdir` children leaves that path open.+ */+export function isNestedRepositoryBoundary(dir: string): boolean {+ try {+ const stats = statSync(join(dir, GIT_ENTRY));+ return stats.isFile() || stats.isDirectory();+ } catch {+ return false; // no `.git` entry, or an unreadable one: an ordinary directory+ }+}diff --git a/src/core/hygiene/scan-repo.ts b/src/core/hygiene/scan-repo.tsindex 91b557d8..0e9b7f2a 100644--- a/src/core/hygiene/scan-repo.ts+++ b/src/core/hygiene/scan-repo.ts@@ -12,10 +12,15 @@* are never installed on an operator's machine.*/-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";+import { readdirSync, readFileSync, statSync } from "node:fs";import { join, relative, sep } from "node:path";-import { IgnoreScope, parseIgnoreLayer, type IgnoreWarning } from "../fs/ignore.ts";+import {+ buildRepositoryBaseScope,+ extendWithDirectoryIgnore,+ formatIgnoreWarning,+} from "../fs/git-discovery.ts";+import type { IgnoreScope, IgnoreWarning } from "../fs/ignore.ts";import { scanFiles, type HardcodedPathFinding } from "./hardcoded-paths.ts";/**@@ -101,44 +106,6 @@ function toPosixRel(root: string, abs: string): string {return relative(root, abs).split(sep).join("/");}-/** Read one ignore file into the scope, folding any warnings in. Fail-soft on I/O. */-function extendWithIgnoreFile(- scope: IgnoreScope,- filePath: string,- baseDir: string,- source: string,- warnings: IgnoreWarning[],-): IgnoreScope {- if (!existsSync(filePath)) return scope;- let content: string;- try {- content = readFileSync(filePath, "utf8");- } catch {- return scope; // an unreadable ignore file is not a scan failure- }- const parsed = parseIgnoreLayer(content, baseDir, source);- warnings.push(...parsed.warnings);- return scope.extend(parsed.layer);-}--/**- * Base ignore scope for the whole repo: `.git/info/exclude` at the lowest- * precedence, then the root `.gitignore` above it. Nested `.gitignore` files- * are layered per directory during the walk.- */-function buildBaseScope(root: string, warnings: IgnoreWarning[]): IgnoreScope {- let scope = IgnoreScope.empty();- scope = extendWithIgnoreFile(- scope,- join(root, ".git", "info", "exclude"),- "",- ".git/info/exclude",- warnings,- );- scope = extendWithIgnoreFile(scope, join(root, ".gitignore"), "", ".gitignore", warnings);- return scope;-}-/*** Recursively collect scannable files under `dir`, fail-soft on I/O. `scope`* carries the composed ignore rules from all shallower directories; this@@ -152,13 +119,9 @@ function collectFiles(out: string[],warnings: IgnoreWarning[],): void {- const dirScope = extendWithIgnoreFile(- scope,- join(dir, ".gitignore"),- toPosixRel(root, dir),- `${toPosixRel(root, dir)}/.gitignore`,- warnings,- );+ const extended = extendWithDirectoryIgnore(scope, dir, toPosixRel(root, dir));+ const dirScope = extended.scope;+ warnings.push(...extended.warnings);let entries;try {entries = readdirSync(dir, { withFileTypes: true });@@ -180,17 +143,19 @@ function collectFiles(}}-/** Emit one stderr line per malformed ignore pattern, deduplicated. */+/**+ * Emit one stderr line per ignore-file warning, deduplicated. Covers both a+ * malformed pattern and an ignore file that could not be honoured at all - the+ * shared formatter words each kind, so this sink and the ingest planner's plan+ * output never drift apart.+ */function reportIgnoreWarnings(warnings: ReadonlyArray<IgnoreWarning>): void {const seen = new Set<string>();for (const w of warnings) {const key = `${w.source}:${w.line}`;if (seen.has(key)) continue;seen.add(key);- process.stderr.write(- `hygiene: ignoring malformed ignore pattern at ${w.source}:${w.line} ` +- `(${w.pattern}): ${w.reason}\n`,- );+ process.stderr.write(`hygiene: ignoring ${formatIgnoreWarning(w)}\n`);}}@@ -203,8 +168,9 @@ function reportIgnoreWarnings(warnings: ReadonlyArray<IgnoreWarning>): void {* present the result is byte-identical to the baseline walk.*/export function listScanTargets(root: string): string[] {- const warnings: IgnoreWarning[] = [];- const baseScope = buildBaseScope(root, warnings);+ const base = buildRepositoryBaseScope(root, "");+ const warnings: IgnoreWarning[] = [...base.warnings];+ const baseScope = base.scope;const abs: string[] = [];for (const dir of SCAN_DIRS) {collectFiles(join(root, dir), root, baseScope, abs, warnings);diff --git a/src/core/search/query-plan.ts b/src/core/search/query-plan.tsindex 3b6427dc..ae6234bd 100644--- a/src/core/search/query-plan.ts+++ b/src/core/search/query-plan.ts@@ -15,12 +15,21 @@* structured field tokens (`source:`, `kind:`/`type:`) and a caller-supplied* artifact-kind vocabulary (the schema pack's page types), never a word list.*+ * Query-side temporal intent (t_58fc4720) is resolved here too, against+ * an INJECTED clock - see `temporal-intent.ts`, which holds the same+ * language-agnostic invariant.+ ** The module is pure and deterministic: same query string in, same plan- * out, with no I/O and no clock/random source.+ * out, with no I/O and no clock/random source of its own.*/import { WIKILINK_DETECT_RE } from "../brain/wikilink.ts";import { extractEntities } from "./entities.ts";+import {+ detectTemporalIntent,+ stripTemporalDirectives,+ type TemporalIntent,+} from "./temporal-intent.ts";import type { QueryIntent, QueryPlan, QuerySurface, WeightProfile } from "./types.ts";/** No-effect profile: every layer keeps its configured weight. */@@ -136,33 +145,67 @@ function classify(query: string, normalized: string): QueryIntent {return "neutral";}+/** Hash field for the resolved temporal window; absent leaves the hash intact. */+const TEMPORAL_HASH_FIELD = "t";+/*** Analyse a query into a deterministic plan. `expandedTerms` is empty* here; synonym expansion (a later layer) fills it before the hash is* meaningful for caching. The hash folds in the normalized query, the- * intent, and any expanded terms - everything that changes results.+ * intent, any expanded terms, and the resolved temporal window -+ * everything that changes results.+ *+ * `nowMs` is the clock temporal-intent detection resolves against.+ * Omitting it disables detection entirely, exactly as omitting+ * `surfaceVocabulary` pins the surface to `default`, so an existing call+ * site keeps a byte-identical plan.+ *+ * `temporalIntentOverride` is the window a caller ALREADY resolved from+ * the ORIGINAL query text. It exists because `search()` restructures the+ * keyword text before it plans - expansion rewrites the query into bare+ * lexical include terms, which destroys the `field:value` grammar - so+ * detection there must read the untouched query and hand the result in.+ * Detection and stripping then operate on the same text, which is the+ * invariant a plan built from restructured text silently broke. Omitted+ * (every other call site) means detect from `query` against `nowMs`.*/export function buildQueryPlan(query: string,expandedTerms: ReadonlyArray<string> = [],intentOverride?: QueryIntent | null,surfaceVocabulary?: ReadonlySet<string>,+ nowMs?: number,+ temporalIntentOverride?: TemporalIntent | null,): QueryPlan {- const normalized = normalize(query);- const intent = intentOverride ?? classify(query, normalized);+ const temporalIntent =+ temporalIntentOverride !== undefined+ ? temporalIntentOverride+ : nowMs === undefined+ ? null+ : detectTemporalIntent(query, nowMs);+ // A `since:` / `until:` directive states the window; it is not content.+ // Everything downstream of detection analyses the residual query, so a+ // directive never reaches the classifier or the keyword lane as a term.+ const analysed = temporalIntent === null ? query : stripTemporalDirectives(query);+ const normalized = normalize(analysed);+ const intent = intentOverride ?? classify(analysed, normalized);const terms = Object.freeze([...expandedTerms]);// Surface routing is advisory and does NOT enter the hash: it re-weights// nothing, so a query's cache identity and ranking stay byte-identical// regardless of surface. Omitting the vocabulary keeps the pure default// provably inert (always `default`), so existing call sites are unchanged.- const planHash = fnv1a(`${normalized}|${intent}|${terms.join(",")}`);+ const planHash = fnv1a(+ `${normalized}|${intent}|${terms.join(",")}` ++ (temporalIntent === null ? "" : `|${TEMPORAL_HASH_FIELD}:${temporalIntent.signature}`),+ );const surface =- surfaceVocabulary === undefined ? "default" : routeSummarySurface(query, surfaceVocabulary);+ surfaceVocabulary === undefined ? "default" : routeSummarySurface(analysed, surfaceVocabulary);return Object.freeze({intent,weightProfile: PROFILES[intent],expandedTerms: terms,planHash,surface,+ ...(temporalIntent !== null ? { temporalIntent } : {}),});}diff --git a/src/core/search/ranker.ts b/src/core/search/ranker.tsindex 17f22fe5..eeba966e 100644--- a/src/core/search/ranker.ts+++ b/src/core/search/ranker.ts@@ -14,6 +14,8 @@ import { PAGE_TIER_DEFAULT, tierWeight, type PageTier } from "../brain/page-metaimport { weibullDecay, DEFAULT_RECENCY, type WeibullRecencyOptions } from "./recency.ts";import { scoreSessionFocusTarget } from "./session-focus.ts";import { rrfFuse, DEFAULT_RRF_K, type FusionMode } from "./fusion.ts";+import { temporalProximity, DEFAULT_WINDOW_PAD_DAYS } from "./temporal-bridge.ts";+import type { TemporalIntent } from "./temporal-intent.ts";import type { KeywordHit, SemanticHit, HydratedChunk } from "./store.ts";import type {BrainSearchResult,@@ -85,8 +87,47 @@ export interface RankerInputs {* leaves ranking byte-identical.*/readonly relationalRankedChunkIds?: ReadonlyArray<number>;+ /**+ * Optional DECLARED event time per chunk in unix ms (t_58fc4720): the+ * validity-window start the document states in its frontmatter. Read+ * only by the query-side temporal layer, and only for chunks that+ * actually declare one - a missing entry (and the absent map) falls+ * back to the chunk's storage mtime, the same "validity start, else+ * mtime" rule `temporal-bridge.ts` applies.+ */+ readonly eventTimeMsByChunk?: ReadonlyMap<number, number>;}+/**+ * Bounded additive-boost caps. Every one of these layers is a re-ranker+ * over an already-relevant candidate set: large enough to reorder it,+ * never large enough to float an irrelevant chunk. They are named here,+ * together, because their PROPORTION to each other is the calibration -+ * a cap is only meaningful relative to its siblings.+ */+/** Inbound links plus shared tags, combined. */+export const LINK_BOOST_CAP = 0.05;+/** The inbound-link half of {@link LINK_BOOST_CAP}. */+const LINK_ONLY_BOOST_CAP = 0.03;+/** The shared-tag half of {@link LINK_BOOST_CAP}. */+const TAG_ONLY_BOOST_CAP = 0.02;+/** Query entities the chunk also carries. */+export const ENTITY_BOOST_CAP = 0.04;+/** Access-reinforced, type-decayed activation. */+export const ACTIVATION_BOOST_CAP = 0.04;+/** Habitual co-retrieval companions inside the candidate pool. */+export const CO_ACCESS_BOOST_CAP = 0.03;+/** Folded USED-vs-CONTRADICTED outcome rate: the strongest evidence layer. */+export const REUSE_BOOST_CAP = 0.06;+/**+ * Query-declared temporal window (t_58fc4720). Set level with the reuse+ * cap - the top of the band - because it corrects a prior that is itself+ * worth up to the full recency amplitude (0.05) in the WRONG direction:+ * a smaller cap could not overcome the freshness prior it exists to+ * offset, and the layer would be decorative.+ */+export const TEMPORAL_INTENT_BOOST_CAP = 0.06;+/** Freshness-trend multipliers on the relevance portion. */const TREND_MULTIPLIERS: ReadonlyMap<string, number> = new Map([["strengthening", 1.05],@@ -135,6 +176,16 @@ export interface RankerOptions {readonly fusionMode?: FusionMode;/** RRF damping constant; defaults to {@link DEFAULT_RRF_K}. */readonly rrfK?: number;+ /**+ * The time window the query declares (t_58fc4720), resolved by+ * `temporal-intent.ts` at the query-plan seam. When present it adds a+ * capped proximity boost for candidates whose event time falls in (or+ * near) the window, and damps the query-independent freshness prior+ * when that window is historical. Absent or null leaves ranking+ * byte-identical, including the `temporal` breakdown key, which is+ * then omitted rather than reported as zero.+ */+ readonly temporalIntent?: TemporalIntent | null;}const DAY_MS = 24 * 60 * 60 * 1000;@@ -205,6 +256,8 @@ function buildReasons(parts: {trendMul?: number;sessionFocus?: number;rrf?: number;+ temporalBoost?: number;+ temporalDamping?: number;}): ReadonlyArray<string> {const reasons: string[] = [];if (parts.keywordScore > 0) reasons.push(`fts5_bm25: ${fmt(parts.keywordScore)}`);@@ -227,6 +280,19 @@ function buildReasons(parts: {}if (parts.linkBoost > 0) reasons.push(`link_boost: ${fmt(parts.linkBoost)}`);if (parts.recency > 0) reasons.push(`recency: ${fmt(parts.recency)}`);+ // Query-side temporal intent, kept SEPARATE from the `recency` entry+ // above so a ranking change is attributable to one layer or the other.+ // Reported whenever the layer had an effect - a zero boost still+ // matters when the window damped the freshness prior, which is exactly+ // the case for an out-of-window recent document.+ if (+ parts.temporalBoost !== undefined &&+ (parts.temporalBoost > 0 || (parts.temporalDamping ?? 1) !== 1)+ ) {+ const damping = parts.temporalDamping ?? 1;+ const suffix = damping === 1 ? "" : ` recency x${fmt(damping)}`;+ reasons.push(`temporal_intent: ${fmt(parts.temporalBoost)}${suffix}`);+ }if (parts.tierMul !== 1) reasons.push(`tier: ${fmt(parts.tierMul)}`);if (parts.sessionFocus && parts.sessionFocus !== 0) {reasons.push(`session_focus: ${parts.sessionFocus >= 0 ? "+" : ""}${fmt(parts.sessionFocus)}`);@@ -254,6 +320,7 @@ function buildBreakdown(parts: {trendMul?: number;sessionFocus?: number;rrf?: number;+ temporalBoost?: number;}): ScoreBreakdown {return Object.freeze({keyword: parts.keywordScore,@@ -268,6 +335,11 @@ function buildBreakdown(parts: {tier: parts.tierMul,trend: parts.trendMul ?? 1,sessionFocus: parts.sessionFocus ?? 0,+ // The one layer reported by ABSENCE rather than by zero: a query+ // that declared no window has no temporal component at all, and a+ // consumer must be able to tell that from a window the candidate+ // simply fell outside of.+ ...(parts.temporalBoost !== undefined ? { temporal: parts.temporalBoost } : {}),});}@@ -281,6 +353,10 @@ export function rankResults(inputs: RankerInputs, opts: RankerOptions): BrainSeaconst semMul = opts.weightProfile?.semanticMul ?? 1;const entMul = opts.weightProfile?.entityMul ?? 1;const recMul = opts.weightProfile?.recencyMul ?? 1;+ // Query-side temporal intent (t_58fc4720). Null (the default) keeps+ // the damping neutral and leaves the layer entirely unreported.+ const temporalIntent = opts.temporalIntent ?? null;+ const temporalDamping = temporalIntent?.recencyDamping ?? 1;const kwNorm = normalizeBm25(inputs.keyword);@@ -386,7 +462,7 @@ export function rankResults(inputs: RankerInputs, opts: RankerOptions): BrainSeaif (candidateDocIds.has(s)) count++;}const raw = count * 0.02;- return Math.min(0.03, raw);+ return Math.min(LINK_ONLY_BOOST_CAP, raw);}function tagBoostFor(c: Candidate): number {@@ -403,7 +479,7 @@ export function rankResults(inputs: RankerInputs, opts: RankerOptions): BrainSea}}const raw = count * 0.01;- return Math.min(0.02, raw);+ return Math.min(TAG_ONLY_BOOST_CAP, raw);}const ranked: BrainSearchResult[] = [];@@ -412,8 +488,12 @@ export function rankResults(inputs: RankerInputs, opts: RankerOptions): BrainSeaif (!hyd) continue;const link = linkBoostFor(c);const tag = tagBoostFor(c);- const linkBoost = Math.min(0.05, link + tag);- const recency = recencyBoost(c.mtime, nowMs, recencyOpts) * recMul;+ const linkBoost = Math.min(LINK_BOOST_CAP, link + tag);+ // Freshness prior, damped when the query named a historical window:+ // the prior points at "now" and the query points at the past, so+ // leaving it undamped would fight the layer below. Damped, never+ // removed - `recencyAmplitude: 0` stays the only off switch.+ const recency = recencyBoost(c.mtime, nowMs, recencyOpts) * recMul * temporalDamping;// Relevance term: reciprocal-rank-fused when in rrf mode, otherwise// the weighted sum of the normalised lanes. RRF is weightless, so the// per-lane weights and intent multipliers do not apply to it.@@ -437,13 +517,13 @@ export function rankResults(inputs: RankerInputs, opts: RankerOptions): BrainSea// Per-match 0.02, capped at 0.04 so it only re-ranks an already// relevant set - never enough to float an irrelevant chunk.const entityMatches = inputs.entityMatchByChunk?.get(c.chunkId) ?? 0;- const entityBoost = Math.min(0.04, entityMatches * 0.02 * entMul);+ const entityBoost = Math.min(ENTITY_BOOST_CAP, entityMatches * 0.02 * entMul);// Activation boost (Time-Aware Recall & Activation Suite): the// effective (type-decayed) activation scales into a capped 0.04// contribution - a re-ranker for habitually-recalled memories,// never enough to float an irrelevant chunk.const activation = clamp01(inputs.activationByChunk?.get(c.chunkId) ?? 0);- const activationBoost = Math.min(0.04, activation * 0.04);+ const activationBoost = Math.min(ACTIVATION_BOOST_CAP, activation * ACTIVATION_BOOST_CAP);// Co-access companion boost (t_c5ef25a3): per habitual companion// that is ALSO in the candidate pool, 0.005 per recorded pair// count, capped at 0.03 - surfaces the rest of a recurring working@@ -456,7 +536,7 @@ export function rankResults(inputs: RankerInputs, opts: RankerOptions): BrainSeaif (candidateDocIds.has(docId)) coAccessRaw += count * 0.005;}}- const coAccessBoost = Math.min(0.03, coAccessRaw);+ const coAccessBoost = Math.min(CO_ACCESS_BOOST_CAP, coAccessRaw);// Observed-reuse boost (t_65588d8b): the folded USED-vs-CONTRADICTED// rate of the chunk's document. Capped at 0.06 - larger than the// activation / co-access caps so a memory the agent demonstrably reused@@ -464,7 +544,18 @@ export function rankResults(inputs: RankerInputs, opts: RankerOptions): BrainSea// that never floats an irrelevant chunk. Zero (byte-identical) when no// observed-use verdicts exist.const reuseRate = clamp01(inputs.reuseRateByChunk?.get(c.chunkId) ?? 0);- const reuseBoost = Math.min(0.06, reuseRate * 0.06);+ const reuseBoost = Math.min(REUSE_BOOST_CAP, reuseRate * REUSE_BOOST_CAP);+ // Query-side temporal intent (t_58fc4720): proximity of the+ // candidate's EVENT time (declared validity start, else storage+ // mtime) to the window the query named, scaled into a capped+ // contribution. Undefined - not zero - when the query named no+ // window, so the layer stays absent from `reasons` and `breakdown`.+ let temporalBoost: number | undefined;+ if (temporalIntent !== null) {+ const eventMs = inputs.eventTimeMsByChunk?.get(c.chunkId) ?? c.mtime * 1000;+ const proximity = temporalProximity(eventMs, temporalIntent.range, DEFAULT_WINDOW_PAD_DAYS);+ temporalBoost = Math.min(TEMPORAL_INTENT_BOOST_CAP, proximity * TEMPORAL_INTENT_BOOST_CAP);+ }const sessionFocus = scoreSessionFocusTarget(hyd, opts.sessionFocus, nowMs);const score = clamp01(weighted * tierMul * trendMul +@@ -474,6 +565,7 @@ export function rankResults(inputs: RankerInputs, opts: RankerOptions): BrainSeaactivationBoost +coAccessBoost +reuseBoost ++ (temporalBoost ?? 0) +sessionFocus,);@@ -509,6 +601,7 @@ export function rankResults(inputs: RankerInputs, opts: RankerOptions): BrainSea...(trend !== undefined ? { trend, trendMul } : {}),sessionFocus,rrf: rrfByChunk !== null ? rrf : 0,+ ...(temporalBoost !== undefined ? { temporalBoost, temporalDamping } : {}),}),breakdown: buildBreakdown({reuseBoost,@@ -523,19 +616,50 @@ export function rankResults(inputs: RankerInputs, opts: RankerOptions): BrainSeatrendMul,sessionFocus,rrf: rrfByChunk !== null ? rrf : 0,+ ...(temporalBoost !== undefined ? { temporalBoost } : {}),}),}),);}- // Tie-break per design Β§7: final_score desc, keywordScore desc, mtime desc, chunkId asc.+ // Tie-break ladder, top to bottom: final_score desc, then (under an+ // active window only) temporal desc, then authoring instant desc, then+ // keywordScore desc, mtime desc, chunkId asc. The last four are design+ // Β§7 plus the conversation-chronology rung; the temporal rung sits+ // above all of them - see below for why that is one step higher than a+ // purely freshness-facing correction would place it.// Conversation chronology (S1): on an EXACT hybrid-score tie, order by// more recent authoring instant FIRST - but only when BOTH results carry// an `authored_at`. A pair where either side has none falls through to// the historical tie-break, so any non-tied pair (and every pair without// turn instants) keeps today's order byte-identically.+ // Query-side temporal intent (t_58fc4720): under an active window the+ // temporal layer separates the tie FIRST - above the whole ladder+ // below, `keywordScore` included, not only above the two freshness+ // rungs.+ //+ // Two reasons, and the second is why the rung sits one step higher than+ // a freshness-only correction would need:+ //+ // - the authoring instant and `mtime` both order NEWER first, which+ // is the very bias a declared historical window contradicts, and a+ // saturating `clamp01` can hide a candidate's larger temporal+ // contribution behind an exact score tie;+ // - `keywordScore` is already a COMPONENT of `score`. On an exact+ // tie it re-applies a signal the composite has already counted,+ // which cannot separate what that composite could not. The window+ // is an axis the query stated and the score may have saturated+ // away, so it is the one that still carries information here.+ //+ // Equal contributions (including both zero) and an absent window fall+ // straight through to the historical ladder, byte-identically.ranked.sort((a, b) => {if (b.score !== a.score) return b.score - a.score;+ if (temporalIntent !== null) {+ const aTemporal = a.breakdown?.temporal ?? 0;+ const bTemporal = b.breakdown?.temporal ?? 0;+ if (aTemporal !== bTemporal) return bTemporal - aTemporal;+ }const aAuthored = inputs.hydrated.get(a.chunkId)?.authoredAt ?? null;const bAuthored = inputs.hydrated.get(b.chunkId)?.authoredAt ?? null;if (aAuthored !== null && bAuthored !== null && aAuthored !== bAuthored) {diff --git a/src/core/search/search.ts b/src/core/search/search.tsindex 0c7e8b33..0afd65c8 100644--- a/src/core/search/search.ts+++ b/src/core/search/search.ts@@ -62,6 +62,7 @@ import { detectHybridDegrade, rerankByRelevance } from "./enrich.ts";import { applyReinforceBoost, loadReinforceStrengths, reinforceFingerprint } from "./reinforce.ts";import { readActiveSessionFocus } from "./session-focus.ts";import { applyTemporalBridge } from "./temporal-bridge.ts";+import { detectTemporalIntent, stripTemporalDirectives } from "./temporal-intent.ts";import { resolveTimeRange } from "./time-range.ts";import { eventTimeInRange, parseValidityWindow, type ValidityWindow } from "./validity.ts";import { contradictedAbiFields, formatEmbeddingAbiDrift, Store } from "./store.ts";@@ -197,8 +198,8 @@ export async function search(config: ResolvedSearchConfig,opts: SearchOptions,): Promise<SearchOutcome> {- const query = (opts.query ?? "").trim();- if (!query) {+ const rawQuery = (opts.query ?? "").trim();+ if (!rawQuery) {throw new SearchError("INVALID_INPUT", "missing required argument: query");}// Recall profile (Recall & Working-Memory Quality Suite, t_98c39dd6) and@@ -224,12 +225,45 @@ export async function search(opts.sessionFocus === undefined? readActiveSessionFocus(config, opts.focusSession, Date.now()): opts.sessionFocus;+ // One clock for every time-resolving decision in this call, so the hard+ // filter and the query-declared window below cannot disagree by a few+ // milliseconds of wall-clock drift.+ const nowMs = Date.now();// Time-aware recall (recall-trust-suite): resolve since/until up front// so invalid input fails fast, before any store I/O.const timeRange =opts.since !== undefined || opts.until !== undefined- ? resolveTimeRange({ since: opts.since, until: opts.until }, Date.now())+ ? resolveTimeRange({ since: opts.since, until: opts.until }, nowMs): null;+ // Query-side temporal intent (t_58fc4720). Resolved HERE, from the raw+ // query as the caller typed it, and before any store I/O:+ //+ // - detection must read the ORIGINAL text. Expansion rewrites the+ // keyword lane into bare lexical terms, and the `field:value`+ // grammar does not survive that rewrite - planning from the+ // rewritten text saw no directive while the strip below still+ // removed one, so a declared window was voided and its directive+ // reached the implicit-AND keyword lane as a term nothing matches;+ // - a malformed directive then fails as fast as `since` / `until`+ // does, rather than after the index is opened.+ //+ // From here on the query text is the RESIDUAL text: a directive states+ // the window and is not a term, so it must not reach the keyword lane,+ // the semantic lane, the coverage gate or the evidence pack. Stripping+ // is byte-identical for a query that carries no directive.+ const temporalIntent = detectTemporalIntent(rawQuery, nowMs);+ const query = stripTemporalDirectives(rawQuery);+ if (query === "") {+ // A window with nothing to search for. Both lanes would be handed the+ // empty string - FTS short-circuits on an empty match and the semantic+ // lane embeds "" - so the honest answer is the same one the parameter+ // form gives: a window FILTERS a query, it is not a query.+ throw new SearchError(+ "INVALID_INPUT",+ "the query declares a time window and no search terms: " ++ "add the terms to look for, or pass the window as the since / until parameters",+ );+ }// Read-only origins (cross-vault search) disable self-healing: a// rebuild would write an index INTO the external vault. Default@@ -249,6 +283,10 @@ export async function search(// corpus-common tokens are derived from document frequency here// (language-agnostic, no stopword list) so an implicit-AND query is// not killed by a word that is ubiquitous in this vault.+ // Expansion reads the RESIDUAL text (see the strip above): a window+ // directive is an instruction, so it must never become an expansion+ // token, and the residual is byte-identical when no window was+ // declared.const commonTokens =opts.structuredQuery === undefined && expandActive === true? highFrequencyTokens(store, query)@@ -262,7 +300,14 @@ export async function search(// profile and the cache key. Expanded terms (if any) are folded in// once they have been derived from the store below.const surfaceVocabulary = summarySurfaceVocabulary(config.vault);- const basePlan = buildQueryPlan(keywordQuery, [], structured?.intent, surfaceVocabulary);+ const basePlan = buildQueryPlan(+ keywordQuery,+ [],+ structured?.intent,+ surfaceVocabulary,+ nowMs,+ temporalIntent,+ );// Summary-search router (t_7b96f242): a per-query structural decision,// independent of results, so it is resolved once here and echoed on// every outcome below. `default` is omitted from the outcome, keeping@@ -278,8 +323,13 @@ export async function search(// change bumps the generation. The cache write is best-effort.// A time-filtered query bypasses the cache: a relative range// ("24h") resolves to a different absolute window on every call, so- // a cached row would serve a stale window within the TTL.- const cacheEnabled = config.recall.cacheEnabled && timeRange === null;+ // a cached row would serve a stale window within the TTL. A window+ // the QUERY declared (`since:24h`) is the same hazard from the other+ // direction: its resolved signature is in the plan hash, so every+ // call keys differently, never hits, and writes one more row that can+ // never be served. Both forms are excluded by the one condition.+ const cacheEnabled =+ config.recall.cacheEnabled && timeRange === null && temporalIntent === null;const ttlMs = config.recall.cacheTtlSeconds * 1000;let cacheKey: string | null = null;let generation = "";@@ -365,7 +415,14 @@ export async function search(maxTerms: config.recall.synonymMaxTerms,});if (expandedTerms.length > 0) {- plan = buildQueryPlan(keywordQuery, expandedTerms, structured?.intent, surfaceVocabulary);+ plan = buildQueryPlan(+ keywordQuery,+ expandedTerms,+ structured?.intent,+ surfaceVocabulary,+ nowMs,+ temporalIntent,+ );kwOutcome = runFtsQueryDetailed(store, keywordQuery, {limit: limit * config.recall.poolMultiplier,pathPrefix,@@ -526,6 +583,15 @@ export async function search(validityWindowCache.set(path, window);return window;};+ // Declared EVENT time for a path (unix ms), or null when the page+ // declares none: validity start, else validity end. The single+ // definition of "event time, storage time only as fallback" shared by+ // the temporal bridge and the query-side temporal layer.+ const declaredEventTimeMs = (path: string): number | null => {+ const window = validityWindowFor(path);+ if (window === null || window.invalid) return null;+ return window.validFromMs ?? window.validUntilMs;+ };// Self-correcting two-pass recall (t_ef92dfdc): a zero-candidate// first pass in evidence-pack mode means the implicit-AND keyword@@ -596,10 +662,10 @@ export async function search(});}const poolCoverage = coverageOverChunks(store, query, coverageIds);- const plan = planTargetedRetry(poolCoverage);- if (plan.fire) {- const targeted = runFtsQueryDetailed(store, plan.terms[0]!, {- expandedTerms: plan.terms.slice(1),+ const retryPlan = planTargetedRetry(poolCoverage);+ if (retryPlan.fire) {+ const targeted = runFtsQueryDetailed(store, retryPlan.terms[0]!, {+ expandedTerms: retryPlan.terms.slice(1),limit: semanticPoolSize(limit),pathPrefix: pathPrefix ?? null,});@@ -615,9 +681,9 @@ export async function search(secondPass = Object.freeze({triggered: true,kind: "targeted",- reason: `partial coverage ${poolCoverage.idfWeightedCoverage.toFixed(2)} < ${COMPLETENESS_COMPLETE_THRESHOLD}; targeted retry on uncovered rare terms: ${plan.terms.join(", ")}`,+ reason: `partial coverage ${poolCoverage.idfWeightedCoverage.toFixed(2)} < ${COMPLETENESS_COMPLETE_THRESHOLD}; targeted retry on uncovered rare terms: ${retryPlan.terms.join(", ")}`,added: newHits.length,- targetedTerms: plan.terms,+ targetedTerms: retryPlan.terms,});}}@@ -814,6 +880,24 @@ export async function search(}}+ // Query-side temporal intent (t_58fc4720): hand the ranker the+ // DECLARED event time of every candidate that states one, so the+ // temporal layer judges a note by when it is about rather than by+ // when it was last written. Candidates with no declaration are+ // omitted and the ranker falls back to their mtime; with no window+ // declared the map is never built at all.+ let eventTimeMsByChunk: ReadonlyMap<number, number> | undefined;+ if (temporalIntent !== null) {+ const byChunk = new Map<number, number>();+ for (const chunkId of idsList) {+ const h = hydrated.get(chunkId);+ if (h === undefined) continue;+ const declared = declaredEventTimeMs(h.path);+ if (declared !== null) byChunk.set(chunkId, declared);+ }+ if (byChunk.size > 0) eventTimeMsByChunk = byChunk;+ }+// When a property filter is active, overfetch the ranked// candidates so the post-filter result set still has a chance// of producing `limit` matching rows. Without this, the@@ -905,6 +989,7 @@ export async function search(...(trendByDoc !== undefined ? { trendByDoc } : {}),...(reuseRateByChunk !== undefined ? { reuseRateByChunk } : {}),...(relationalRankedChunkIds.length > 0 ? { relationalRankedChunkIds } : {}),+ ...(eventTimeMsByChunk !== undefined ? { eventTimeMsByChunk } : {}),},{keywordWeight: opts.keywordWeight ?? config.keywordWeight,@@ -920,6 +1005,7 @@ export async function search(...(sessionFocus !== undefined ? { sessionFocus } : {}),fusionMode: config.fusionMode,rrfK: config.rrfK,+ temporalIntent,},);const capHit = ranked.length >= rankCap;@@ -947,10 +1033,8 @@ export async function search(ranked = applyTemporalBridge(ranked, {range: timeRange,eventTimeMs: (path) => {- const w = validityWindowFor(path);- if (w !== null && !w.invalid && (w.validFromMs !== null || w.validUntilMs !== null)) {- return w.validFromMs ?? w.validUntilMs!;- }+ const declared = declaredEventTimeMs(path);+ if (declared !== null) return declared;try {return statSync(join(config.vault, path)).mtimeMs;} catch {diff --git a/src/core/search/temporal-intent.ts b/src/core/search/temporal-intent.tsnew file mode 100644index 00000000..474e25d6--- /dev/null+++ b/src/core/search/temporal-intent.ts@@ -0,0 +1,226 @@+/**+ * Query-side temporal intent (t_58fc4720).+ *+ * The Weibull freshness prior in `recency.ts` is query-INDEPENDENT: it+ * always favours recent notes, including when the query explicitly asks+ * about an older period, where it actively hurts ranking. This module is+ * the detection half of the correction. It resolves the window a query+ * declares, so the ranker can bias toward that window and damp the+ * misdirected freshness prior.+ *+ * LANGUAGE-AGNOSTIC INVARIANT (the same one `query-plan.ts` audits):+ * detection reads ONLY structural tokens -+ *+ * - ISO date / datetime tokens anywhere in the query text, matched by+ * digit-and-separator shape with digit/hyphen-only boundaries, so a+ * token embedded in Han text with no whitespace at all is detected+ * exactly as it is in English; and+ * - the `<field>:<value>` grammar the surface router already uses,+ * with the `since` / `until` field names the time-range parameters+ * already own.+ *+ * No natural-language phrase ("last week", "recently", "before X") is+ * recognised, in any language: such a list is not portable to a system+ * that must behave identically across every script, so it is not+ * attempted.+ *+ * ## Exactly what a field value may say+ *+ * A `since:` / `until:` value in QUERY TEXT is admitted only in a+ * language-neutral form - an ISO date, an ISO datetime, or a `<n>h` /+ * `<n>d` / `<n>w` duration (`isLanguageNeutralTimePoint`). The word forms+ * `parseTimePoint` also accepts (`today`, `yesterday`, `last week`,+ * `last month`) belong to the explicit `since` / `until` PARAMETERS,+ * where an operator typed them deliberately; recognising them here would+ * make `since:yesterday` resolve while its translation into any other+ * language raised, which is precisely the asymmetry this module exists to+ * avoid. An inadmissible or unresolvable field value raises+ * `SearchError("INVALID_INPUT")`: the operator DECLARED a window, so a+ * value that cannot become one is an error, never a silent skip.+ *+ * Resolution itself is always `parseTimePoint`, the SAME parser the+ * parameters use - never a second one. The admission test above only+ * narrows what reaches it.+ *+ * ## A bare token is a shape, not a declaration+ *+ * A date-SHAPED run in free text (`invoice 2024-06-31`, a ticket number,+ * a version string) was not typed as an instruction. When such a token+ * does not resolve it declares NOTHING: it is skipped, it stays in the+ * query text as the content it is, and a previously-working search is not+ * aborted by it. Only the explicit field grammar above can fail loudly.+ *+ * Pure against an injected clock: same query and `nowMs`, same intent.+ */++import {+ resolveTimeRange,+ parseTimePoint,+ isLanguageNeutralTimePoint,+ type ResolvedTimeRange,+} from "./time-range.ts";+import { SearchError } from "./types.ts";++const DAY_MS = 24 * 60 * 60 * 1000;++/**+ * A closed window whose end is older than this reads as a query about+ * the past rather than about the present, and the freshness prior is+ * damped for it. A window reaching the present (open `until`, or an+ * `until` inside this age) keeps the prior intact.+ */+export const HISTORICAL_WINDOW_MIN_AGE_DAYS = 7;++/**+ * Multiplier applied to the freshness prior when the declared window is+ * historical. Modest by construction: the prior is DAMPED, never+ * removed, so a genuinely fresh document still carries its recency+ * signal and the correction cannot invert ranking on its own.+ */+export const HISTORICAL_RECENCY_DAMPING = 0.5;++/**+ * `<field>:<value>` directive, anchored at a word boundary with the+ * value running to the next whitespace - the grammar `routeSummarySurface`+ * already uses for `kind:` / `type:` / `source:`.+ */+const FIELD_TOKEN_RE = /(?:^|\s)(since|until):(\S+)/giu;++/**+ * ISO date, optionally with a time component. The boundaries reject only+ * adjacent digits and hyphens, so the token is found identically whether+ * it is surrounded by spaces, by Cyrillic, or by Han characters with no+ * whitespace - while a date-shaped run inside a longer digit run+ * (`12024-06-155`) is not a date.+ */+const ISO_TOKEN_RE =+ /(?<![0-9-])\d{4}-\d{2}-\d{2}(?:[Tt]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:[Zz]|[+-]\d{2}:?\d{2})?)?(?![0-9-])/gu;++export interface TemporalIntent {+ /** The window the query declares, in absolute unix ms. */+ readonly range: ResolvedTimeRange;+ /** True when the window closed longer ago than the minimum age. */+ readonly historical: boolean;+ /** Freshness-prior multiplier: `HISTORICAL_RECENCY_DAMPING` or 1. */+ readonly recencyDamping: number;+ /**+ * Stable fingerprint of the RESOLVED absolute bounds. Folded into the+ * query plan's hash, so a cache row is never served across two+ * different windows - including two calls of the same relative+ * directive that resolved differently.+ */+ readonly signature: string;+}++/**+ * Remove the `since:` / `until:` directives from a query. A directive is+ * an instruction, not content: left in the keyword lane it becomes an+ * implicit-AND term no document can match, which would turn this unit's+ * soft window into a hard exclusion - the opposite of its purpose.+ *+ * A query carrying no directive is returned unchanged, byte for byte.+ * Bare ISO tokens are content as well as signal and are always kept.+ */+export function stripTemporalDirectives(query: string): string {+ if (!new RegExp(FIELD_TOKEN_RE).test(query)) return query;+ return query.replace(new RegExp(FIELD_TOKEN_RE), " ").replace(/\s+/gu, " ").trim();+}++/**+ * Return a field value that query text is allowed to declare, or raise.+ * The gate is the language-neutral shape test; everything that passes is+ * handed to `parseTimePoint` unchanged, so this narrows the grammar+ * without becoming a second parser.+ */+function admitFieldValue(value: string): string {+ if (isLanguageNeutralTimePoint(value)) return value;+ throw new SearchError(+ "INVALID_INPUT",+ `unusable time point in query text: ${JSON.stringify(value)} ` ++ "(a query directive accepts an ISO date, an ISO datetime, or <n>h/<n>d/<n>w; " ++ "word forms are accepted only by the since / until parameters)",+ );+}++/** Collect the first occurrence of each directive. */+function readFieldTokens(query: string): {+ readonly since: string | undefined;+ readonly until: string | undefined;+} {+ let since: string | undefined;+ let until: string | undefined;+ for (const match of query.matchAll(new RegExp(FIELD_TOKEN_RE))) {+ const field = match[1]!.toLowerCase();+ const value = match[2]!;+ if (field === "since") since ??= value;+ else until ??= value;+ }+ return { since, until };+}++/**+ * Widest window spanned by the bare ISO tokens, or null when there are+ * none that RESOLVE. A token that matches the shape but names no instant+ * (`2024-06-31`, `2023-02-29`) is skipped rather than raised: see the+ * header - a shape found in free text is not a declaration, so it may not+ * abort a search that was working before the token was typed.+ */+function readIsoTokenRange(query: string, nowMs: number): ResolvedTimeRange | null {+ let sinceMs: number | null = null;+ let untilMs: number | null = null;+ for (const match of query.matchAll(new RegExp(ISO_TOKEN_RE))) {+ const resolved = resolveBareToken(match[0], nowMs);+ if (resolved === null) continue;+ sinceMs = sinceMs === null ? resolved.start : Math.min(sinceMs, resolved.start);+ untilMs = untilMs === null ? resolved.end : Math.max(untilMs, resolved.end);+ }+ if (sinceMs === null || untilMs === null) return null;+ return Object.freeze({ sinceMs, untilMs });+}++/**+ * Both edges of one bare token, or `null` when it names no instant. The+ * only place a `parseTimePoint` refusal is absorbed, and it is absorbed+ * as a NAMED outcome of this unit's grammar ("this token declares+ * nothing"), not as a swallowed failure.+ */+function resolveBareToken(token: string, nowMs: number): { start: number; end: number } | null {+ try {+ return {+ start: parseTimePoint(token, nowMs, "since"),+ end: parseTimePoint(token, nowMs, "until"),+ };+ } catch {+ return null;+ }+}++/**+ * Resolve the temporal window a query declares, or `null` when it+ * declares none. Explicit `since:` / `until:` directives win outright:+ * they state the window's edges, including which edge stays open, and a+ * bare token elsewhere in the query must not close it.+ */+export function detectTemporalIntent(query: string, nowMs: number): TemporalIntent | null {+ const fields = readFieldTokens(query);+ const range =+ fields.since !== undefined || fields.until !== undefined+ ? resolveTimeRange(+ {+ ...(fields.since !== undefined ? { since: admitFieldValue(fields.since) } : {}),+ ...(fields.until !== undefined ? { until: admitFieldValue(fields.until) } : {}),+ },+ nowMs,+ )+ : readIsoTokenRange(query, nowMs);+ if (range === null) return null;++ const historical =+ range.untilMs !== null && range.untilMs < nowMs - HISTORICAL_WINDOW_MIN_AGE_DAYS * DAY_MS;+ return Object.freeze({+ range,+ historical,+ recencyDamping: historical ? HISTORICAL_RECENCY_DAMPING : 1,+ signature: `${range.sinceMs ?? ""}:${range.untilMs ?? ""}`,+ });+}diff --git a/src/core/search/time-range.ts b/src/core/search/time-range.tsindex 112e26ff..af9f8d7f 100644--- a/src/core/search/time-range.ts+++ b/src/core/search/time-range.ts@@ -26,6 +26,34 @@ export type RangeEdge = "since" | "until";const ISO_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;const SHORTHAND_RE = /^(\d{1,4})([hdw])$/;+/**+ * ISO datetime SHAPE. `parseTimePoint` resolves a datetime through+ * `Date.parse` (which accepts more than this), so this is deliberately+ * not a second parser: it is the admission test+ * {@link isLanguageNeutralTimePoint} needs, and nothing here changes what+ * the `since` / `until` parameters accept.+ */+const ISO_DATETIME_RE =+ /^\d{4}-\d{2}-\d{2}t\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:z|[+-]\d{2}:?\d{2})?$/;++/**+ * True when a time point is stated in a LANGUAGE-NEUTRAL form: an ISO+ * date, an ISO datetime, or a `<n>h` / `<n>d` / `<n>w` duration. False for+ * every word form (`today`, `yesterday`, `last week`, `last month`) this+ * parser also accepts.+ *+ * The word forms belong to the explicit `since` / `until` PARAMETERS,+ * where an operator typed them deliberately. A surface that classifies+ * free query text may not recognise them: a fixed list of English words+ * would behave differently for a query written in any other language,+ * which is the one property `temporal-intent.ts` guarantees. That surface+ * calls this to decide ADMISSION; resolution stays with+ * {@link parseTimePoint}, so there is still exactly one parser.+ */+export function isLanguageNeutralTimePoint(raw: string): boolean {+ const text = raw.trim().toLowerCase();+ return ISO_DATE_RE.test(text) || ISO_DATETIME_RE.test(text) || SHORTHAND_RE.test(text);+}function utcDayStart(ms: number): number {const d = new Date(ms);diff --git a/src/core/search/types.ts b/src/core/search/types.tsindex ec7115d7..862b9c69 100644--- a/src/core/search/types.ts+++ b/src/core/search/types.ts@@ -8,6 +8,7 @@ import type { DegradationNotice } from "../integrity/degradation.ts";import type { StampMismatch } from "../integrity/stamp.ts";import type { VaultIgnoreRule } from "../vault-scope/defaults.ts";import type { DegreePredicate } from "./property-filter.ts";+import type { TemporalIntent } from "./temporal-intent.ts";import type {MemoryTrustAssessment,RetrievalDecisionTrace,@@ -104,6 +105,13 @@ export interface ScoreBreakdown {readonly tier: number;readonly trend: number;readonly sessionFocus: number;+ /**+ * Query-side temporal-intent boost (t_58fc4720). Present ONLY when the+ * query declared a time window; absent - not zero - for every query+ * that declared none, so a breakdown without temporal intent stays+ * byte-identical to pre-suite behaviour.+ */+ readonly temporal?: number;}/**@@ -261,6 +269,14 @@ export interface QueryPlan {* summary-shaped. See {@link QuerySurface}.*/readonly surface: QuerySurface;+ /**+ * The time window this query declares (t_58fc4720), resolved to+ * absolute bounds. Present only when the caller supplied a clock AND+ * the query carries an ISO token or a `since:` / `until:` directive;+ * absent otherwise, so a query with no temporal window keeps a+ * byte-identical plan and `planHash`. See {@link TemporalIntent}.+ */+ readonly temporalIntent?: TemporalIntent;}export interface IndexStats {diff --git a/src/mcp/brain/derive-tools.ts b/src/mcp/brain/derive-tools.tsindex 9418e9db..8e0f80ef 100644--- a/src/mcp/brain/derive-tools.ts+++ b/src/mcp/brain/derive-tools.ts@@ -11,12 +11,15 @@* produced and the brain is unchanged.*/-import { deriveFact, DeriveFactError } from "../../core/brain/derived-fact.ts";+import {+ deriveFact,+ DeriveFactError,+ parseDeriveFactInput,+} from "../../core/brain/derived-fact.ts";import { loadGuardrailsConfigSafe } from "../../core/brain/policy.ts";-import { asProvenanceLevel } from "../../core/brain/provenance/provenance.ts";+import { ResponseShapeError } from "../../core/brain/response-shape.ts";import { INVALID_PARAMS, MCPError } from "../protocol.ts";import type { ServerContext, ToolDefinition } from "../tool-contract.ts";-import { coerceStr, coerceStrList } from "../coerce.ts";import { wrapToolErrors } from "./shared.ts";const TOOL = "brain_derive_fact";@@ -25,7 +28,7 @@ async function toolBrainDeriveFact(ctx: ServerContext,args: Record<string, unknown>,): Promise<Record<string, unknown>> {- return wrapToolErrors(TOOL, [DeriveFactError], async () => {+ return wrapToolErrors(TOOL, [DeriveFactError, ResponseShapeError], async () => {if (!loadGuardrailsConfigSafe(ctx.vault).derived_fact_synthesis) {throw new MCPError(INVALID_PARAMS,@@ -33,25 +36,11 @@ async function toolBrainDeriveFact();}- const slug = coerceStr(args, "slug", true)!;- const topic = coerceStr(args, "topic", true)!;- const principle = coerceStr(args, "principle", true)!;- const levelRaw = coerceStr(args, "level", true)!;- const level = asProvenanceLevel(levelRaw);- if (level === null || level === "stated") {- throw new MCPError(INVALID_PARAMS, `${TOOL}: 'level' must be 'deduced' or 'inferred'`);- }- const premises = coerceStrList(args, "premises");- if (premises.length === 0) {- throw new MCPError(INVALID_PARAMS, `${TOOL}: 'premises' must list at least one premise id`);- }-- const res = deriveFact(- ctx.vault,- { slug, topic, principle, premises, level },- { now: new Date() },- );- return { id: res.id, level, premises };+ // Shape first: the payload is validated before any field is read, so a+ // structurally wrong request never reaches the premise lookup or a write.+ const input = parseDeriveFactInput(args);+ const res = deriveFact(ctx.vault, input, { now: new Date() });+ return { id: res.id, level: input.level, premises: input.premises };});}diff --git a/src/mcp/brain/distill-tools.ts b/src/mcp/brain/distill-tools.tsindex c61c62c9..a77728fc 100644--- a/src/mcp/brain/distill-tools.ts+++ b/src/mcp/brain/distill-tools.ts@@ -11,44 +11,31 @@import {distillSource,DistillValidationError,- normalizeClaim,- type DistillClaim,+ parseDistillClaims,} from "../../core/brain/distill/distill-source.ts";+import { ResponseShapeError } from "../../core/brain/response-shape.ts";import { resolveAgentName } from "../../core/config.ts";import { coerceStr } from "../coerce.ts";-import { INVALID_PARAMS, MCPError } from "../protocol.ts";import type { ServerContext, ToolDefinition } from "../tool-contract.ts";import { wrapToolErrors } from "./shared.ts";const TOOL = "brain_distill_source";-/** Coerce the `claims` arg into DistillClaim[], rejecting a malformed shape. */-function parseClaims(args: Record<string, unknown>): DistillClaim[] {- const raw = args["claims"];- if (!Array.isArray(raw) || raw.length === 0) {- throw new MCPError(INVALID_PARAMS, `${TOOL}: 'claims' must be a non-empty array`);- }- return raw.map((item, i) => {- if (item === null || typeof item !== "object" || Array.isArray(item)) {- throw new MCPError(INVALID_PARAMS, `${TOOL}: claim ${i} must be an object`);- }- return normalizeClaim(item as Record<string, unknown>);- });-}-async function toolBrainDistillSource(ctx: ServerContext,args: Record<string, unknown>,): Promise<Record<string, unknown>> {const sourcePath = coerceStr(args, "source_path", true)!;- const claims = parseClaims(args);const agentArg = coerceStr(args, "agent", false);const agent =agentArg && agentArg.trim().length > 0? agentArg: resolveAgentName(ctx.configPath ?? undefined);- return wrapToolErrors(TOOL, [DistillValidationError], async () => {+ return wrapToolErrors(TOOL, [DistillValidationError, ResponseShapeError], async () => {+ // Shape first: the payload is validated before a single claim is+ // normalized, so a malformed item aborts the whole batch unwritten.+ const claims = parseDistillClaims(args["claims"]);const res = distillSource(ctx.vault, { sourcePath, claims }, { agent, now: new Date() });return {distillation_path: res.distillationPath,diff --git a/src/mcp/brain/feedback-tools.ts b/src/mcp/brain/feedback-tools.tsindex ee701176..3702c661 100644--- a/src/mcp/brain/feedback-tools.ts+++ b/src/mcp/brain/feedback-tools.ts@@ -35,6 +35,9 @@ import { BRAIN_ROLES } from "../../core/brain/trust/role.ts";import { resolveEffectiveScope, writeSignal } from "../../core/brain/signal.ts";import {adviseIncomingFeedback,+ adviseUnroutableCapture,+ captureRoutingHintField,+ type CaptureRoutingHint,type WriteConflictAdvisory,} from "../../core/brain/write-advisory.ts";import { loadFeedbackDefaultScopeSafe } from "../../core/brain/policy.ts";@@ -203,6 +206,15 @@ async function toolBrainFeedback(now,});+ // Unroutable-capture routing hint (unit 4): the signal above resolved+ // no scope, so no scoped recall reaches it. Non-blocking like the+ // advisory, and absent entirely when this vault uses no scopes yet.+ const routingHint: CaptureRoutingHint | null = adviseUnroutableCapture(ctx.vault, {+ ...(effectiveScope !== undefined ? { scope: effectiveScope } : {}),+ agent,+ now,+ });+let prefResult: { path: string; id: string } | null = null;if (forceConfirmed) {// Escape hatch: skip the dream pass and create the confirmed rule now.@@ -253,6 +265,10 @@ async function toolBrainFeedback(kind: prefResult ? "preference" : "signal",...(mirror !== undefined ? { mirror } : {}),...(advisory !== null ? { advisory } : {}),+ // Same key and same resolution as the CLI's `--json` renderer, from+ // the one composer: an agent that learns the exit on one surface+ // reads it on the other.+ ...captureRoutingHintField(routingHint),signal_path: vaultRelativeSafe(ctx.vault, sigResult.path),signal_absolute_path: resolve(sigResult.path),signal_id: sigResult.id,diff --git a/src/mcp/brain/ingest-tools.ts b/src/mcp/brain/ingest-tools.tsindex 1833df75..aae5e0da 100644--- a/src/mcp/brain/ingest-tools.ts+++ b/src/mcp/brain/ingest-tools.ts@@ -177,7 +177,13 @@ async function toolBrainDeleteBySource(return serializePlan(plan);}-function serializeBatchPlan(plan: BatchPlan): Record<string, unknown> {+/**+ * The wire shape of a batch plan, shared by every surface that emits one: this+ * tool and `o2b brain batch-plan --json` (which spreads its own `reconcile` on+ * top). One serializer means a field added here cannot reach one surface and+ * miss the other.+ */+export function serializeBatchPlan(plan: BatchPlan): Record<string, unknown> {return {source_dir: plan.sourceDir,max_batch_bytes: plan.maxBatchBytes,@@ -195,6 +201,19 @@ function serializeBatchPlan(plan: BatchPlan): Record<string, unknown> {})),}: {}),+ // Only emitted when the repository's own ignore files carried a malformed+ // pattern (t_4b2bd8f7), so a tree that declares none - or declares only+ // well-formed patterns - serializes byte-identically to before.+ ...(plan.ignoreWarnings.length > 0+ ? {+ ignore_warnings: plan.ignoreWarnings.map((w) => ({+ source: w.source,+ line: w.line,+ pattern: w.pattern,+ reason: w.reason,+ })),+ }+ : {}),plan_id: plan.planId,resumed_completed: plan.resumedCompleted,batches: plan.batches.map((b) => ({@@ -422,7 +441,7 @@ export const INGEST_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([src_subpath: {type: "string",description:- "Scope discovery to a subtree of source_dir (e.g. pkg/a). A value escaping source_dir is a typed error. Absent walks the whole dir.",+ "Scope discovery to a subtree of source_dir (e.g. pkg/a). Narrows only: escaping source_dir or entering a submodule errors; an ignored subtree plans nothing.",},exclude: {type: "array",diff --git a/src/mcp/brain/pack-tools.ts b/src/mcp/brain/pack-tools.tsindex aa87a472..907486dd 100644--- a/src/mcp/brain/pack-tools.ts+++ b/src/mcp/brain/pack-tools.ts@@ -11,12 +11,15 @@import {resolveDensityRankingContextPack,resolveRecallAdequacyThresholds,+ resolveRecallGateTelemetry,resolveSearchFocusContextPack,} from "../../core/config.ts";import { resolveSearchConfig } from "../../core/search/index.ts";import { readActiveSessionFocus } from "../../core/search/session-focus.ts";import { packContext } from "../../core/brain/context-pack.ts";import { assessRecallAdequacy } from "../../core/brain/recall-adequacy.ts";+import { recordRecallAdequacyDemand } from "../../core/brain/query-demand.ts";+import { emitGatedTelemetry } from "../../core/brain/continuity/emit.ts";import {readAnticipatoryContext,refreshAnticipatoryCache,@@ -101,6 +104,26 @@ async function toolBrainContextPack(resolveRecallAdequacyThresholds(ctx.configPath ?? undefined),): undefined;+ // signals-that-survive, unit 6: an unmet verdict is stamped onto the+ // cross-query demand log under the bucket key normalizeQueryTerms already+ // computes, so the knowledge-gap loop can aggregate recurrence without a+ // second identity concept.+ //+ // ONE opt-in for that log, on every surface that writes it: the+ // `recall_gate_telemetry` config key, exactly as `brain_recall_gate`+ // uses. It is a vault-level durable log feeding a vault-level loop, so+ // whether it is written is an operator decision, not a per-call one -+ // gating it here on this tool's `telemetry` ARGUMENT instead made one+ // feature answer to two different opt-ins and left the log's contents+ // depending on which surface a caller happened to use. That argument+ // keeps its own meaning: it selects whether THIS call emits its own+ // continuity records. Fail-open as ever - a log write never breaks the+ // pack.+ if (adequacy !== undefined && query !== undefined) {+ emitGatedTelemetry(resolveRecallGateTelemetry(ctx.configPath ?? undefined), () =>+ recordRecallAdequacyDemand(ctx.vault, { query, verdict: adequacy }),+ );+ }// Focus wiring (Agent Surface Suite, t_5b478e47): gated on the// search_focus_context_pack config key (default off) so the default// pack stays byte-identical. Fail-soft - a broken search configdiff --git a/src/mcp/brain/research-tools.ts b/src/mcp/brain/research-tools.tsindex e050753b..521d291e 100644--- a/src/mcp/brain/research-tools.ts+++ b/src/mcp/brain/research-tools.ts@@ -11,62 +11,31 @@import {writeResearchReport,ResearchValidationError,- type ResearchFinding,+ parseResearchReportInput,} from "../../core/brain/research/research.ts";+import { ResponseShapeError } from "../../core/brain/response-shape.ts";import { resolveAgentName } from "../../core/config.ts";-import { INVALID_PARAMS, MCPError } from "../protocol.ts";import type { ServerContext, ToolDefinition } from "../tool-contract.ts";import { coerceStr } from "../coerce.ts";-import { isRecord, requiredString } from "./intake-args.ts";import { wrapToolErrors } from "./shared.ts";const TOOL = "brain_research_report";-function reqStringList(value: unknown, field: string): string[] {- if (!Array.isArray(value) || value.length === 0) {- throw new MCPError(INVALID_PARAMS, `${TOOL}: '${field}' must be a non-empty array of strings`);- }- return value.map((item, i) => requiredString(item, TOOL, `${field}[${i}]`));-}--function parseFinding(value: unknown, i: number): ResearchFinding {- if (!isRecord(value)) {- throw new MCPError(INVALID_PARAMS, `${TOOL}: findings[${i}] must be an object`);- }- const statement = value["statement"];- if (typeof statement !== "string" || statement.trim().length === 0) {- throw new MCPError(- INVALID_PARAMS,- `${TOOL}: findings[${i}].statement must be a non-empty string`,- );- }- const sources = reqStringList(value["sources"], `findings[${i}].sources`);- return { statement, sources };-}-async function toolBrainResearchReport(ctx: ServerContext,args: Record<string, unknown>,): Promise<Record<string, unknown>> {- const title = coerceStr(args, "title", true)!;- const sources = reqStringList(args["sources"], "sources");- const rawFindings = args["findings"];- if (!Array.isArray(rawFindings) || rawFindings.length === 0) {- throw new MCPError(INVALID_PARAMS, `${TOOL}: 'findings' must be a non-empty array`);- }- const findings = rawFindings.map((item, i) => parseFinding(item, i));const agentArg = coerceStr(args, "agent", false);const agent =agentArg && agentArg.trim().length > 0? agentArg: resolveAgentName(ctx.configPath ?? undefined);- return wrapToolErrors(TOOL, [ResearchValidationError], async () => {- const res = writeResearchReport(- ctx.vault,- { title, sources, findings },- { agent, now: new Date() },- );+ return wrapToolErrors(TOOL, [ResearchValidationError, ResponseShapeError], async () => {+ // Shape first: the payload is validated before the citation contract is+ // evaluated, so a malformed finding aborts the report unwritten.+ const input = parseResearchReportInput(args);+ const res = writeResearchReport(ctx.vault, input, { agent, now: new Date() });return {report_path: res.reportPath,created: res.created,diff --git a/src/mcp/output-contract.ts b/src/mcp/output-contract.tsindex 315f759a..ed029a52 100644--- a/src/mcp/output-contract.ts+++ b/src/mcp/output-contract.ts@@ -1,80 +1,32 @@-export type OutputSchemaType =- | "object"- | "array"- | "string"- | "number"- | "integer"- | "boolean"- | "null";--export interface OutputSchema {- readonly type?: OutputSchemaType;- readonly required?: ReadonlyArray<string>;- readonly properties?: Readonly<Record<string, OutputSchema>>;- readonly items?: OutputSchema;- readonly enum?: ReadonlyArray<unknown>;- readonly additionalProperties?: boolean | OutputSchema;-}--export function validateOutputContract(schema: OutputSchema, value: unknown, path = "$"): string[] {- const errors: string[] = [];-- if (schema.enum && !schema.enum.some((expected) => Object.is(expected, value))) {- errors.push(`${path}: expected one of ${schema.enum.map(String).join(", ")}`);- return errors;- }-- if (schema.type && !matchesType(value, schema.type)) {- errors.push(`${path}: expected ${schema.type}`);- return errors;- }-- if (schema.type === "object" || schema.properties || schema.required) {- if (!isRecord(value)) {- if (!schema.type) errors.push(`${path}: expected object`);- return errors;- }-- for (const requiredKey of schema.required ?? []) {- if (!hasOwn(value, requiredKey)) {- errors.push(`${path}: missing required property '${requiredKey}'`);- }- }-- const properties = schema.properties ?? {};- for (const [key, childSchema] of Object.entries(properties)) {- if (hasOwn(value, key)) {- errors.push(...validateOutputContract(childSchema, value[key], `${path}.${key}`));- }- }-- const additional = schema.additionalProperties;- if (additional === false) {- for (const key of Object.keys(value)) {- if (!hasOwn(properties, key)) errors.push(`${path}: unexpected property '${key}'`);- }- } else if (typeof additional === "object") {- for (const [key, childValue] of Object.entries(value)) {- if (!hasOwn(properties, key)) {- errors.push(...validateOutputContract(additional, childValue, `${path}.${key}`));- }- }- }- }-- if (schema.type === "array" || schema.items) {- if (!Array.isArray(value)) {- if (!schema.type) errors.push(`${path}: expected array`);- return errors;- }- if (schema.items) {- value.forEach((item, index) => {- errors.push(...validateOutputContract(schema.items!, item, `${path}[${index}]`));- });- }- }-- return errors;+/**+ * Output contracts for Model Context Protocol tools.+ *+ * The JSON-subset checker itself lives in `core/brain/response-shape.ts`,+ * which the agent-authored write paths validate against too. This module is+ * the protocol-facing skin over that ONE definition: it keeps the historical+ * `OutputSchema` vocabulary the tool table is written in, and renders the+ * structured violations as the `<path>: <detail>` lines the contract has+ * always reported.+ */++import {+ SHAPE_ROOT_PATH,+ checkResponseShape,+ formatShapeViolation,+ type ShapeDescriptor,+ type ShapeType,+} from "../core/brain/response-shape.ts";++export type OutputSchemaType = ShapeType;++export type OutputSchema = ShapeDescriptor;++export function validateOutputContract(+ schema: OutputSchema,+ value: unknown,+ path = SHAPE_ROOT_PATH,+): string[] {+ return checkResponseShape(schema, value, path).map(formatShapeViolation);}export function assertOutputContract(@@ -88,20 +40,3 @@ export function assertOutputContract(throw new Error(`${toolName} output contract failed: ${errors.join("; ")}`);}}--function matchesType(value: unknown, type: OutputSchemaType): boolean {- if (type === "null") return value === null;- if (type === "array") return Array.isArray(value);- if (type === "object") return isRecord(value);- if (type === "integer") return typeof value === "number" && Number.isInteger(value);- if (type === "number") return typeof value === "number" && Number.isFinite(value);- return typeof value === type;-}--function isRecord(value: unknown): value is Record<string, unknown> {- return typeof value === "object" && value !== null && !Array.isArray(value);-}--function hasOwn(value: object, key: string): boolean {- return Object.prototype.hasOwnProperty.call(value, key);-}diff --git a/src/mcp/search-tools.ts b/src/mcp/search-tools.tsindex 7d1e7af2..50f9eb47 100644--- a/src/mcp/search-tools.ts+++ b/src/mcp/search-tools.ts@@ -53,7 +53,7 @@ import { parseRecallBenchmarkDataset, runRecallBenchmark } from "../core/search/import { emitRecallTelemetry } from "../core/brain/recall-telemetry.ts";import { emitGateTelemetry } from "../core/brain/gate-telemetry.ts";import { emitGatedTelemetry } from "../core/brain/continuity/emit.ts";-import { recordQueryDemand } from "../core/brain/query-demand.ts";+import { recordQueryDemand, recordRecallAdequacyDemand } from "../core/brain/query-demand.ts";const MCP_LIMIT_MAX = 50;const MCP_CONTENT_MAX = 600;@@ -768,6 +768,19 @@ async function toolBrainRecallGate(if (scores === undefined) return { ...decision };const thresholds = resolveRecallAdequacyThresholds(ctx.configPath ?? undefined);const verdict = assessRecallAdequacy(scores, thresholds);+ // signals-that-survive, unit 6: an unmet verdict is stamped onto the+ // cross-query demand log under the bucket key normalizeQueryTerms already+ // computes, so the knowledge-gap loop can aggregate recurrence without a+ // second identity concept. Gated behind the same telemetry opt-in as the+ // gate record above and fail-open β a log write never breaks the gate.+ //+ // `recall_gate_telemetry` is the SINGLE opt-in for this log wherever it+ // is written: `brain_context_pack` writes the same records under the+ // same key (see `brain/pack-tools.ts`), so one config decision governs+ // the whole feature rather than one per surface.+ emitGatedTelemetry(resolveRecallGateTelemetry(ctx.configPath ?? undefined), () =>+ recordRecallAdequacyDemand(ctx.vault, { query: prompt, verdict }),+ );return {...decision,adequacy: {diff --git a/tests/cli/brain-batch-plan-ignore-warnings.test.ts b/tests/cli/brain-batch-plan-ignore-warnings.test.tsnew file mode 100644index 00000000..e2d9f857--- /dev/null+++ b/tests/cli/brain-batch-plan-ignore-warnings.test.ts@@ -0,0 +1,167 @@+/**+ * t_4b2bd8f7 follow-through: `o2b brain batch-plan` renders the planner's+ * `ignoreWarnings` on both the `--json` payload (structured, same key as the+ * MCP surface) and the human-readable surface (naming the offending file), in+ * the same non-fatal-reporting style the verb already uses for+ * `skippedNonExtractable`.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { join } from "node:path";+import { tmpdir } from "node:os";++import { INGEST_TOOLS } from "../../src/mcp/brain/ingest-tools.ts";+import { runCli } from "../helpers/run-cli.ts";++let vault: string;+let configHome: string;+let configPath: string;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-batchplan-warn-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-batchplan-warn-cfg-"));+ configPath = join(configHome, "config.yaml");+ writeFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`, "utf8");+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++function write(rel: string, content = "content\n"): void {+ const abs = join(vault, rel);+ mkdirSync(join(abs, ".."), { recursive: true });+ writeFileSync(abs, content, "utf8");+}++const ENV = () => ({ OPEN_SECOND_BRAIN_CONFIG: configPath });++describe("o2b brain batch-plan ignore_warnings (t_4b2bd8f7 follow-through)", () => {+ test("--json surfaces the warning with its structured fields", async () => {+ write("mono/keep.md");+ write("mono/.gitignore", "[unterminated\n");++ const res = await runCli(["brain", "batch-plan", "mono", "--json"], { env: ENV() });+ expect(res.returncode).toBe(0);+ const plan = JSON.parse(res.stdout);+ expect(plan.ignore_warnings).toEqual([+ {+ source: "mono/.gitignore",+ line: 1,+ pattern: "[unterminated",+ reason: expect.stringContaining("unterminated"),+ },+ ]);+ // Still succeeds; the file it could not filter is still discovered.+ expect(plan.total_files).toBe(1);+ });++ test("the human-readable surface names the file the bad pattern came from", async () => {+ write("mono/keep.md");+ write("mono/.gitignore", "[unterminated\n");++ const res = await runCli(["brain", "batch-plan", "mono"], { env: ENV() });+ expect(res.returncode).toBe(0);+ expect(res.stdout).toContain("mono/.gitignore");+ expect(res.stdout).toContain("[unterminated");+ });++ test("a clean tree's --json output omits the key entirely", async () => {+ write("mono/a.md");++ const res = await runCli(["brain", "batch-plan", "mono", "--json"], { env: ENV() });+ expect(res.returncode).toBe(0);+ const plan = JSON.parse(res.stdout);+ expect("ignore_warnings" in plan).toBe(false);+ });++ test("a clean tree's human-readable output carries no warning line", async () => {+ write("mono/a.md");++ const res = await runCli(["brain", "batch-plan", "mono"], { env: ENV() });+ expect(res.returncode).toBe(0);+ expect(res.stdout).not.toMatch(/malformed/i);+ });++ test("an unreadable .gitignore reaches both CLI surfaces", async () => {+ write("mono/secret.md");+ write("mono/.gitignore", "secret.md\n");+ chmodSync(join(vault, "mono", ".gitignore"), 0o000);++ const json = await runCli(["brain", "batch-plan", "mono", "--json"], { env: ENV() });+ expect(json.returncode).toBe(0);+ const plan = JSON.parse(json.stdout);+ expect(plan.ignore_warnings).toEqual([+ {+ source: "mono/.gitignore",+ line: 0,+ pattern: "",+ reason: expect.stringContaining("EACCES"),+ },+ ]);+ // The file the repository declared excluded is queued - but never silently.+ expect(plan.total_files).toBe(1);++ const human = await runCli(["brain", "batch-plan", "mono"], { env: ENV() });+ expect(human.returncode).toBe(0);+ expect(human.stdout).toContain("mono/.gitignore");+ expect(human.stdout).toContain("EACCES");+ });++ test("a subpath into an ignored subtree reports the override on both surfaces", async () => {+ write("mono/pkg/a/keep.md");+ write("mono/.gitignore", "pkg/\n");++ const json = await runCli(["brain", "batch-plan", "mono", "--src-subpath", "pkg/a", "--json"], {+ env: ENV(),+ });+ expect(json.returncode).toBe(0);+ const plan = JSON.parse(json.stdout);+ expect(plan.total_files).toBe(0);+ expect(plan.ignore_warnings).toHaveLength(1);+ expect(plan.ignore_warnings[0].source).toBe("--src-subpath");++ const human = await runCli(["brain", "batch-plan", "mono", "--src-subpath", "pkg/a"], {+ env: ENV(),+ });+ expect(human.returncode).toBe(0);+ expect(human.stdout).toContain("--src-subpath");+ expect(human.stdout).toContain("mono/pkg");+ });++ test("a subpath crossing a submodule boundary fails loudly", async () => {+ write("mono/sub/inner/x.md");+ write("mono/sub/.git", "gitdir: ../.git/modules/sub\n");++ const res = await runCli(["brain", "batch-plan", "mono", "--src-subpath", "sub/inner"], {+ env: ENV(),+ });+ expect(res.returncode).toBe(1);+ expect(res.stderr).toContain("nested repository boundary");+ });+});++describe("the CLI and MCP batch-plan payloads come from one serializer", () => {+ test("--json equals the MCP payload for the same plan", async () => {+ write("mono/a.md");+ write("mono/pkg/b.md");+ write("mono/.gitignore", "[unterminated\n");++ const res = await runCli(["brain", "batch-plan", "mono", "--json"], { env: ENV() });+ expect(res.returncode).toBe(0);+ const { ok, ...cli } = JSON.parse(res.stdout) as Record<string, unknown>;+ expect(ok).toBe(true);++ const handler = INGEST_TOOLS.find((t) => t.name === "brain_ingest_batch_plan")!.handler;+ const mcp = (await handler(+ { vault, configPath, repoRoot: null },+ { source_dir: "mono" },+ )) as Record<string, unknown>;++ // Same keys in the same order, same values: one serializer, two surfaces.+ expect(Object.keys(cli)).toEqual(Object.keys(mcp));+ expect(cli).toEqual(mcp);+ });+});diff --git a/tests/cli/brain-distill.test.ts b/tests/cli/brain-distill.test.tsindex 403a0728..dbee90a3 100644--- a/tests/cli/brain-distill.test.ts+++ b/tests/cli/brain-distill.test.ts@@ -55,6 +55,40 @@ test("an empty claim list is rejected (validation error, exit 1)", async () => {expect(res.returncode).toBe(1);});+const CLAIMS_SHAPE_HINT = "claims must be a JSON array of { text, block? } objects";++/** One `--claims` run; `runCli` swaps process env, so runs stay sequential. */+async function distillWithClaims(claims: string) {+ return runCli(["brain", "distill", "Articles/src.md", "--claims", claims, "--vault", vault], {+ env,+ });+}++test("a claims payload that is not a list names the shape the CLI accepts", async () => {+ // The operator's mistake is the WRAPPER, not an item, so the error has to+ // name the accepted payload rather than report a path inside one.+ const wrapperHoldsNoList = await distillWithClaims('{"claims": 3}');+ expect(wrapperHoldsNoList.returncode).toBe(1);+ expect(wrapperHoldsNoList.stderr).toContain(CLAIMS_SHAPE_HINT);++ const wrapperNamesAnotherKey = await distillWithClaims('{"notes": []}');+ expect(wrapperNamesAnotherKey.returncode).toBe(1);+ expect(wrapperNamesAnotherKey.stderr).toContain(CLAIMS_SHAPE_HINT);++ const notAWrapperAtAll = await distillWithClaims('"a claim"');+ expect(notAWrapperAtAll.returncode).toBe(1);+ expect(notAWrapperAtAll.stderr).toContain(CLAIMS_SHAPE_HINT);+});++test("a malformed claim item still reports its path", async () => {+ const res = await runCli(+ ["brain", "distill", "Articles/src.md", "--claims", '[{"text": 3}]', "--vault", vault],+ { env },+ );+ expect(res.returncode).toBe(1);+ expect(res.stderr).toContain("$[0].text");+});+test("missing <source> or --claims is a usage error (exit 2)", async () => {const noSource = await runCli(["brain", "distill", "--claims", "[]", "--vault", vault], { env });expect(noSource.returncode).toBe(2);diff --git a/tests/cli/brain-doctor-parse-error-path.test.ts b/tests/cli/brain-doctor-parse-error-path.test.tsnew file mode 100644index 00000000..f576f5a8--- /dev/null+++ b/tests/cli/brain-doctor-parse-error-path.test.ts@@ -0,0 +1,100 @@+/**+ * `o2b brain doctor` names the offending file once per finding+ * (signals-that-survive, task 2).+ *+ * The human renderer appends ` (<path>)` from the finding's structured+ * `path` field. While the parsers also embedded the path in their+ * message, every parse-error line read:+ *+ * [ERROR] preference-missing-field: preference missing field: \+ * created_at (/vault/Brain/preferences/pref-x.md) \+ * (/vault/Brain/preferences/pref-x.md)+ *+ * This pins the renderer as unchanged and the line as carrying the path+ * exactly once, on both the human and the machine surface.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { bootstrapBrain } from "../../src/core/brain/init.ts";+import { runCli } from "../helpers/run-cli.ts";++let tmp: string;+let vault: string;+let config: string;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-doctor-parse-path-"));+ vault = join(tmp, "vault");+ config = join(tmp, "config.yaml");+ writeFileSync(config, `vault: ${vault}\nagent_name: test-agent\n`);+ bootstrapBrain(vault, { configPath: config });+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++/** A preference file whose frontmatter omits `created_at`. */+function seedMissingField(): string {+ const path = join(vault, "Brain", "preferences", "pref-no-created-at.md");+ writeFileSync(+ path,+ [+ "---",+ "kind: brain-preference",+ "id: pref-no-created-at",+ "_confirmed_at: null",+ "unconfirmed_until: 2026-05-28T10:42:00Z",+ "tags: [brain, brain/preference]",+ "topic: broken",+ "_status: unconfirmed",+ "principle: A rule with no birthday",+ "_evidenced_by: []",+ "---",+ "",+ ].join("\n"),+ "utf8",+ );+ return path;+}++/** How many times `needle` occurs in `haystack`. */+function occurrences(haystack: string, needle: string): number {+ return haystack.split(needle).length - 1;+}++describe("brain doctor - the path appears once per parse-error line", () => {+ test("the human surface names the file exactly once", async () => {+ const path = seedMissingField();+ const r = await runCli(["brain", "doctor", "--vault", vault], {+ env: { OPEN_SECOND_BRAIN_CONFIG: config },+ });+ expect(r.returncode).toBe(1);+ const line = r.stdout+ .split("\n")+ .find((l) => l.startsWith("[ERROR] preference-missing-field:"));+ expect(line).toBeDefined();+ expect(occurrences(line!, path)).toBe(1);+ expect(line).toBe(+ `[ERROR] preference-missing-field: preference missing field: created_at (${path})`,+ );+ });++ test("the machine surface carries the path only in its own field", async () => {+ const path = seedMissingField();+ const r = await runCli(["brain", "doctor", "--vault", vault, "--json"], {+ env: { OPEN_SECOND_BRAIN_CONFIG: config },+ });+ const payload = JSON.parse(r.stdout) as {+ errors: ReadonlyArray<{ code: string; path?: string; message: string }>;+ };+ const issue = payload.errors.find((e) => e.code === "preference-missing-field");+ expect(issue).toBeDefined();+ expect(issue!.path).toBe(path);+ expect(issue!.message).toBe("preference missing field: created_at");+ });+});diff --git a/tests/cli/brain-feedback-routing-hint.test.ts b/tests/cli/brain-feedback-routing-hint.test.tsnew file mode 100644index 00000000..be60c858--- /dev/null+++ b/tests/cli/brain-feedback-routing-hint.test.ts@@ -0,0 +1,195 @@+/**+ * Unit 4 (t_75597bb9): the CLI surface of the unroutable-capture hint.+ *+ * `o2b brain feedback` without `--scope` records the signal exactly as+ * before and ADDITIONALLY reports the routing signal the capture lacked+ * plus the scope slugs this vault already uses. The forward pointer is+ * resolved through the advisory rail against the registered code - the+ * verb assembles no sentence of its own - and the machine stream carries+ * it as a field instead of a line.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { bootstrapBrain } from "../../src/core/brain/init.ts";+import { resolveNextStep } from "../../src/core/brain/next-step.ts";+import { CAPTURE_ROUTING_HINT_CODE } from "../../src/core/brain/write-advisory.ts";+import { runCli } from "../helpers/run-cli.ts";++let tmp: string;+let vault: string;+let configPath: string;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-feedback-routing-hint-"));+ vault = join(tmp, "vault");+ configPath = join(tmp, "config.yaml");+ writeFileSync(configPath, `vault: ${vault}\nagent_name: test-agent\n`);+ bootstrapBrain(vault, { configPath });+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++const env = () => ({ OPEN_SECOND_BRAIN_CONFIG: configPath });++/** The exact line the rail prints for the registered code - never retyped. */+const HINT_EXIT = `next: ${resolveNextStep(CAPTURE_ROUTING_HINT_CODE)?.nextCommand ?? "(unregistered)"}`;++async function seedScoped(topic: string, scope: string): Promise<void> {+ const out = await runCli(+ [+ "brain",+ "feedback",+ "--topic",+ topic,+ "--signal",+ "positive",+ "--principle",+ `principle for ${topic}`,+ "--scope",+ scope,+ "--force-confirmed",+ ],+ { env: env() },+ );+ expect(out.returncode).toBe(0);+}++async function record(+ extra: ReadonlyArray<string> = [],+): Promise<Awaited<ReturnType<typeof runCli>>> {+ return runCli(+ [+ "brain",+ "feedback",+ "--topic",+ "unrouted",+ "--signal",+ "positive",+ "--principle",+ "capture this without saying where it belongs",+ ...extra,+ ],+ { env: env() },+ );+}++interface RoutingHintPayload {+ readonly signal_path: string;+ readonly signal_id: string;+ readonly routing_hint?: {+ readonly missing_signal: string;+ readonly code: string;+ readonly candidates: ReadonlyArray<{ scope: string; documents: number }>;+ readonly next_command?: string;+ };+}++describe("o2b brain feedback - unroutable-capture routing hint", () => {+ test("a scope-less write on a scoped vault names the missing signal and the observed slugs", async () => {+ await seedScoped("tabs", "coding");+ await seedScoped("naming", "coding");+ await seedScoped("tone", "writing");++ const out = await record();++ expect(out.returncode).toBe(0);+ // The write landed, first and unconditionally.+ expect(out.stdout).toContain("signal: ");+ expect(out.stdout).toContain("id: sig-");+ // The missing routing signal and the vault's own slugs, ranked.+ expect(out.stdout).toContain("routing-hint: no scope");+ expect(out.stdout).toContain("coding");+ expect(out.stdout).toContain("writing");+ // The forward pointer came from the rail, against the registry.+ expect(out.stdout).toContain(`${HINT_EXIT}\n`);+ });++ test("the write lands identically whether or not the hint fires", async () => {+ // Silent vault: the write lands and nothing forward is printed.+ const withoutCorpus = await record();+ expect(withoutCorpus.returncode).toBe(0);+ expect(withoutCorpus.stdout).not.toContain("routing-hint:");+ expect(withoutCorpus.stdout).not.toContain(HINT_EXIT);+ const silent = signalBody(bareIdOf(withoutCorpus.stdout));++ // Same capture on a vault that HAS a scope corpus: the hint fires and+ // the signal file is the same document, modulo its identity fields.+ await seedScoped("tone", "writing");+ const withCorpus = await runCli(+ [+ "brain",+ "feedback",+ "--topic",+ "unrouted",+ "--signal",+ "positive",+ "--principle",+ "capture this without saying where it belongs",+ "--slug",+ "unrouted-again",+ ],+ { env: env() },+ );+ expect(withCorpus.returncode).toBe(0);+ expect(withCorpus.stdout).toContain(HINT_EXIT);+ const advised = signalBody(bareIdOf(withCorpus.stdout));++ // The hint never writes a scope onto the signal it advised about, and+ // never alters the recorded principle.+ for (const body of [silent, advised]) {+ expect(body).not.toContain("\nscope:");+ expect(body).toContain("capture this without saying where it belongs");+ }+ });++ test("an explicit --scope silences the hint", async () => {+ await seedScoped("tone", "writing");+ const out = await record(["--scope", "coding"]);+ expect(out.returncode).toBe(0);+ expect(out.stdout).not.toContain("routing-hint:");+ expect(out.stdout).not.toContain(HINT_EXIT);+ });++ test("the machine stream carries the hint as a field, never as a line", async () => {+ await seedScoped("tone", "writing");+ const out = await record(["--json"]);+ expect(out.returncode).toBe(0);+ expect(out.stdout).not.toContain("next: ");+ const payload = JSON.parse(out.stdout) as RoutingHintPayload;+ expect(payload.signal_id).toMatch(/^sig-/);+ expect(payload.routing_hint).toBeDefined();+ expect(payload.routing_hint!.missing_signal).toBe("scope");+ expect(payload.routing_hint!.code).toBe(CAPTURE_ROUTING_HINT_CODE);+ expect(payload.routing_hint!.candidates).toEqual([{ scope: "writing", documents: 2 }]);+ expect(payload.routing_hint!.next_command).toBe(+ resolveNextStep(CAPTURE_ROUTING_HINT_CODE)!.nextCommand,+ );+ });++ test("a vault with no scope corpus carries no hint key at all", async () => {+ const out = await record(["--json"]);+ expect(out.returncode).toBe(0);+ const payload = JSON.parse(out.stdout) as RoutingHintPayload;+ expect(payload.signal_id).toMatch(/^sig-/);+ expect("routing_hint" in payload).toBe(false);+ expect(existsSync(join(vault, "Brain", "inbox"))).toBe(true);+ });+});++/** The `id: <sig-...>` line the verb prints, read back for file assertions. */+function bareIdOf(stdout: string): string {+ const match = /^id: (sig-[\w.-]+)$/m.exec(stdout);+ expect(match).not.toBeNull();+ return match![1]!;+}++/** The on-disk signal document for a printed id. */+function signalBody(id: string): string {+ return readFileSync(join(vault, "Brain", "inbox", `${id}.md`), "utf8");+}diff --git a/tests/cli/brain-scan-inline-strict.test.ts b/tests/cli/brain-scan-inline-strict.test.tsnew file mode 100644index 00000000..c57d15fa--- /dev/null+++ b/tests/cli/brain-scan-inline-strict.test.ts@@ -0,0 +1,89 @@+/**+ * `o2b brain scan-inline --strict` and the routed marker kinds.+ *+ * `--strict` means "a scan that could not process everything it found is+ * a failure". It used to key on `malformed` alone, so a marker whose+ * DESTINATION refused it printed an error and still exited 0 - an+ * unattended run reading only the exit code saw a clean scan while a+ * fact never reached the preferences. The refusal is unprocessed work,+ * exactly as a malformed marker is, so both gate the exit.+ */++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 { bootstrapBrain } from "../../src/core/brain/init.ts";+import { brainConfigPath } from "../../src/core/brain/paths.ts";+import { DEFAULT_BRAIN_CONFIG_YAML } from "../../src/core/brain/config-template.ts";+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";+import { runCli } from "../helpers/run-cli.ts";++let tmp: string;+let vault: string;+let configPath: string;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-scan-inline-strict-"));+ vault = join(tmp, "vault");+ configPath = join(tmp, "config.yaml");+ writeFileSync(configPath, `vault: ${vault}\nagent_name: test-agent\n`);+ bootstrapBrain(vault, { configPath });+ atomicWriteFileSync(+ brainConfigPath(vault),+ `${DEFAULT_BRAIN_CONFIG_YAML}\nnotes:\n read_paths:\n - Daily\n`,+ );+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++const env = () => ({ OPEN_SECOND_BRAIN_CONFIG: configPath });++function writeNote(rel: string, content: string): void {+ const path = join(vault, rel);+ mkdirSync(join(path, ".."), { recursive: true });+ atomicWriteFileSync(path, content);+}++describe("--strict and a marker its destination refused", () => {+ test("an unresolvable premise exits non-zero instead of reporting a clean scan", async () => {+ writeNote("Daily/2026-07-27.md", "@osb fact topic=t principle=p premise=nope level=deduced\n");++ const strict = await runCli(["brain", "scan-inline", "--strict"], { env: env() });+ expect(strict.stdout).toContain("was refused");+ expect(strict.returncode).toBe(2);+ });++ test("without --strict the same scan still reports the refusal and exits 0", async () => {+ writeNote("Daily/2026-07-27.md", "@osb fact topic=t principle=p premise=nope level=deduced\n");++ const lenient = await runCli(["brain", "scan-inline"], { env: env() });+ expect(lenient.stdout).toContain("was refused");+ expect(lenient.returncode).toBe(0);+ });++ test("a scan with nothing to refuse still exits 0 under --strict", async () => {+ writeNote("Daily/2026-07-27.md", "@osb feedback positive topic=t principle=p\n");++ const strict = await runCli(["brain", "scan-inline", "--strict"], { env: env() });+ expect(strict.returncode).toBe(0);+ expect(strict.stdout).toContain("created: 1");+ });++ test("--dry-run --json reports the routed work it would do", async () => {+ writeNote(+ "Daily/2026-07-27.md",+ ['@osb skill name="release check" body="run the suite"', ""].join("\n"),+ );++ const dry = await runCli(["brain", "scan-inline", "--dry-run", "--json"], { env: env() });+ expect(dry.returncode).toBe(0);+ const payload = JSON.parse(dry.stdout) as Record<string, number>;+ expect(payload["skills"]).toBe(1);+ expect(payload["found"]).toBe(1);+ expect(payload["suppressed"]).toBe(0);+ });+});diff --git a/tests/core/brain.inline.test.ts b/tests/core/brain.inline.test.tsindex ab003319..3e9be6af 100644--- a/tests/core/brain.inline.test.ts+++ b/tests/core/brain.inline.test.ts@@ -468,3 +468,61 @@ describe("discoverMarkers widened kinds", () => {expect(feedback[0]!.topic).toBe("t");});});++// ββ Repeated single-valued fields, required and optional ββββββββββββββββββββ++describe("a repeated single-valued field is ambiguous whether or not it is required", () => {+ test("block form: a repeated optional `scope` refuses the marker and names it", () => {+ const body = [+ "kind: feedback",+ "signal: positive",+ "topic: t",+ "principle: p",+ "scope: coding",+ "scope: writing",+ ].join("\n");+ expect(parseBlockMarker(body, 1)).toBeNull();++ const result = discoverMarkersDetailed(["```osb", body, "```"].join("\n"));+ expect(result.markers.length).toBe(0);+ expect(result.malformed).toBe(1);+ expect(result.issues.length).toBe(1);+ expect(result.issues[0]!.duplicateFields).toEqual(["scope"]);+ expect(result.issues[0]!.message).toContain("scope");+ });++ test("inline form: a repeated optional `scope` refuses the marker and names it", () => {+ expect(+ parseInlineMarker(`@osb feedback positive topic=t principle=p scope=coding scope=writing`, 3),+ ).toBeNull();++ const result = discoverMarkersDetailed(+ `@osb feedback positive topic=t principle=p scope=coding scope=writing\n`,+ );+ expect(result.markers.length).toBe(0);+ expect(result.malformed).toBe(1);+ expect(result.issues.length).toBe(1);+ expect(result.issues[0]!.duplicateFields).toEqual(["scope"]);+ });++ test("a repeatable optional field is still collected, not refused", () => {+ const m = parseInlineMarker(+ `@osb feedback positive topic=t principle=p source=[[A]] source=[[B]]`,+ 1,+ );+ expect(m).not.toBeNull();+ expect(m!.source).toEqual(["[[A]]", "[[B]]"]);+ });++ test("a single optional value is unaffected in both shapes", () => {+ const inline = parseInlineMarker(`@osb feedback positive topic=t principle=p scope=coding`, 1);+ expect(inline!.scope).toBe("coding");+ const block = parseBlockMarker(+ ["kind: feedback", "signal: positive", "topic: t", "principle: p", "scope: coding"].join(+ "\n",+ ),+ 1,+ );+ expect(block!.scope).toBe("coding");+ });+});diff --git a/tests/core/brain.types.test.ts b/tests/core/brain.types.test.tsindex 3df99d46..3b4b496d 100644--- a/tests/core/brain.types.test.ts+++ b/tests/core/brain.types.test.ts@@ -95,6 +95,8 @@ describe("BRAIN_* const enums", () => {"durability-skip",// A4 (t_f79b4fe0) write-time conflict advisory"write-conflict-advisory",+ // signals-that-survive unit 4 (t_75597bb9) unroutable-capture hint+ "capture-routing-hint",// A5 (t_66c12a67) fact signal retire lifecycle"signal-retire",// Belief lifecycle suite (t_7d5a3589) cross-type tombstone + supersedediff --git a/tests/core/brain/dedup-telemetry.test.ts b/tests/core/brain/dedup-telemetry.test.tsindex 125b69ab..e7a6f3f3 100644--- a/tests/core/brain/dedup-telemetry.test.ts+++ b/tests/core/brain/dedup-telemetry.test.ts@@ -300,14 +300,22 @@ describe("scanInline dedup telemetry", () => {agent: "tester",now: new Date("2026-07-01T10:00:00Z"),});+ // The claim under test is that emitting the dedup record does not change+ // the result shape - not that the shape is frozen forever. `facts`,+ // `skills` and `suppressed` were added by the routed marker kinds+ // (signals-that-survive, unit 7); they are counters on the same result,+ // unrelated to this record.expect(Object.keys(result).toSorted()).toEqual(["created","deduped","errors",+ "facts","filesWithMarkers","found","malformed","scanned",+ "skills",+ "suppressed",]);});});diff --git a/tests/core/brain/gap-loop-adequacy.test.ts b/tests/core/brain/gap-loop-adequacy.test.tsnew file mode 100644index 00000000..064b1a85--- /dev/null+++ b/tests/core/brain/gap-loop-adequacy.test.ts@@ -0,0 +1,246 @@+import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { emitRecallTelemetry } from "../../../src/core/brain/recall-telemetry.ts";+import { assessRecallAdequacy } from "../../../src/core/brain/recall-adequacy.ts";+import {+ normalizeQueryTerms,+ readQueryDemand,+ recordRecallAdequacyDemand,+} from "../../../src/core/brain/query-demand.ts";+import {+ autoCloseRecalledGaps,+ detectRecurringGaps,+ gapTaskKey,+ GAP_LOOP_MAX_PROMOTIONS_PER_RUN,+ GAP_SOURCE_ADEQUACY,+ GAP_SOURCE_TELEMETRY,+ GAP_TASK_KIND,+ GAP_TASK_STATUS_CLOSED,+ GAP_TASK_STATUS_OPEN,+ listGapTasks,+ promoteGapsToTasks,+ renderGapAgenda,+} from "../../../src/core/brain/gaps/gap-loop.ts";+import type { RecallRetriever, RecallResultSet } from "../../../src/core/brain/recall-inject.ts";+import { parseFrontmatterText } from "../../../src/core/vault.ts";++let vault: string;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-gap-adequacy-"));+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+});++const NOW = new Date("2026-06-01T12:00:00.000Z");++/** A query whose bucket key is stable and shared across the tests below. */+const QUERY = "widget calibration procedure";+/** The bucket key `normalizeQueryTerms` derives for {@link QUERY}. */+const QUERY_BUCKET = normalizeQueryTerms(QUERY).join(" ");++/** Scores producing each verdict level under the default thresholds. */+const WEAK_SCORES = [0.4];+const SUFFICIENT_SCORES = [0.9];+const INSUFFICIENT_SCORES: ReadonlyArray<number> = [];++function stampUnmet(query: string, times: number, scores: ReadonlyArray<number>): void {+ const verdict = assessRecallAdequacy(scores);+ for (let i = 0; i < times; i++) {+ recordRecallAdequacyDemand(vault, {+ query,+ verdict,+ at: `2026-05-1${i}T09:00:00.000Z`,+ });+ }+}++function seedStructuralGap(topic: string, times: number): void {+ for (let i = 0; i < times; i++) {+ emitRecallTelemetry(vault, {+ host: "test",+ mode: "search",+ status: "empty",+ durationMs: 0,+ resultCount: 0,+ gaps: [topic],+ createdAt: `2026-05-2${i}T09:00:00.000Z`,+ });+ }+}++function retrieverWithScore(score: number): RecallRetriever {+ return async () =>+ ({+ candidates: [+ { path: "Brain/x.md", title: "X", score, searchType: "hybrid", startLine: 1, endLine: 2 },+ ],+ total: 1,+ }) satisfies RecallResultSet;+}++describe("recall-adequacy stamps the demand record (signals-that-survive, unit 6)", () => {+ test("a weak verdict stamps the record under the normalizeQueryTerms bucket key", () => {+ const record = recordRecallAdequacyDemand(vault, {+ query: QUERY,+ verdict: assessRecallAdequacy(WEAK_SCORES),+ });+ expect(record).not.toBeNull();+ expect(record!.adequacy).toBe("weak");+ // The bucket key is exactly what normalizeQueryTerms already computes β+ // no second identity concept.+ expect(record!.terms).toEqual(normalizeQueryTerms(QUERY));+ const [persisted] = readQueryDemand(vault);+ expect(persisted?.adequacy).toBe("weak");+ expect(persisted?.terms.join(" ")).toBe(QUERY_BUCKET);+ });++ test("an insufficient verdict stamps the record and carries its result count", () => {+ const verdict = assessRecallAdequacy(INSUFFICIENT_SCORES);+ const record = recordRecallAdequacyDemand(vault, { query: QUERY, verdict });+ expect(record!.adequacy).toBe("insufficient");+ expect(record!.results).toBe(verdict.resultCount);+ });++ test("a sufficient verdict stamps nothing β only unmet recall is demand", () => {+ const record = recordRecallAdequacyDemand(vault, {+ query: QUERY,+ verdict: assessRecallAdequacy(SUFFICIENT_SCORES),+ });+ expect(record).toBeNull();+ expect(readQueryDemand(vault)).toHaveLength(0);+ });++ test("a query with no significant terms records nothing rather than an empty bucket", () => {+ const record = recordRecallAdequacyDemand(vault, {+ query: "a b c",+ verdict: assessRecallAdequacy(WEAK_SCORES),+ });+ expect(record).toBeNull();+ expect(readQueryDemand(vault)).toHaveLength(0);+ });+});++describe("verdict recurrence feeds the gap loop (signals-that-survive, unit 6)", () => {+ test("a bucket at or above the threshold surfaces as an adequacy-sourced gap", () => {+ stampUnmet(QUERY, 3, WEAK_SCORES);+ const gaps = detectRecurringGaps(vault, { threshold: 3 });+ expect(gaps).toHaveLength(1);+ expect(gaps[0]?.topic).toBe(QUERY_BUCKET);+ expect(gaps[0]?.occurrences).toBe(3);+ expect(gaps[0]?.source).toBe(GAP_SOURCE_ADEQUACY);+ });++ test("a bucket below the threshold mints nothing", () => {+ stampUnmet(QUERY, 2, WEAK_SCORES);+ expect(detectRecurringGaps(vault, { threshold: 3 })).toHaveLength(0);+ const result = promoteGapsToTasks(vault, { threshold: 3, now: NOW });+ expect(result.created).toHaveLength(0);+ expect(existsSync(join(vault, "Brain", "gap-tasks"))).toBe(false);+ });++ test("a recurring bucket promotes to exactly one gap task carrying its source", () => {+ stampUnmet(QUERY, 3, WEAK_SCORES);+ const result = promoteGapsToTasks(vault, { threshold: 3, now: NOW });+ const key = gapTaskKey(QUERY_BUCKET, GAP_SOURCE_ADEQUACY);+ expect(result.created).toEqual([key]);+ const [fm] = parseFrontmatterText(+ readFileSync(join(vault, "Brain", "gap-tasks", `${key}.md`), "utf8"),+ );+ expect(fm["kind"]).toBe(GAP_TASK_KIND);+ expect(fm["gap_source"]).toBe(GAP_SOURCE_ADEQUACY);+ expect(fm["gap_topic"]).toBe(QUERY_BUCKET);+ // Still a plain vault note: never a kanban row.+ expect(fm["board"]).toBeUndefined();+ });++ test("an existing open gap task for the same key is not duplicated", () => {+ stampUnmet(QUERY, 3, WEAK_SCORES);+ const first = promoteGapsToTasks(vault, { threshold: 3, now: NOW });+ const second = promoteGapsToTasks(vault, { threshold: 3, now: NOW });+ expect(first.created).toHaveLength(1);+ expect(second.created).toHaveLength(0);+ expect(second.skipped).toEqual([gapTaskKey(QUERY_BUCKET, GAP_SOURCE_ADEQUACY)]);+ expect(listGapTasks(vault, { status: GAP_TASK_STATUS_OPEN })).toHaveLength(1);+ });++ test("promotion is capped per run at the named constant", () => {+ const buckets = GAP_LOOP_MAX_PROMOTIONS_PER_RUN + 1;+ for (let i = 0; i < buckets; i++) {+ stampUnmet(`coverage gap topic${i}`, 3 + (buckets - i), WEAK_SCORES);+ }+ expect(detectRecurringGaps(vault, { threshold: 3 })).toHaveLength(buckets);+ const first = promoteGapsToTasks(vault, { threshold: 3, now: NOW });+ expect(first.created).toHaveLength(GAP_LOOP_MAX_PROMOTIONS_PER_RUN);+ // The cap bounds NEW notes per run, so the remainder is minted next run+ // rather than being dropped.+ const second = promoteGapsToTasks(vault, { threshold: 3, now: NOW });+ expect(second.created).toHaveLength(buckets - GAP_LOOP_MAX_PROMOTIONS_PER_RUN);+ expect(listGapTasks(vault, { status: GAP_TASK_STATUS_OPEN })).toHaveLength(buckets);+ });++ test("an adequacy gap task auto-closes once its topic recalls with sufficient confidence", async () => {+ stampUnmet(QUERY, 3, WEAK_SCORES);+ promoteGapsToTasks(vault, { threshold: 3, now: NOW });+ const result = await autoCloseRecalledGaps(vault, retrieverWithScore(0.92), {+ confidenceFloor: 0.5,+ now: NOW,+ });+ expect(result.closed).toEqual([gapTaskKey(QUERY_BUCKET, GAP_SOURCE_ADEQUACY)]);+ expect(listGapTasks(vault, { status: GAP_TASK_STATUS_OPEN })).toHaveLength(0);+ expect(listGapTasks(vault, { status: GAP_TASK_STATUS_CLOSED })).toHaveLength(1);+ });+});++describe("the two occurrence sources stay distinguishable (signals-that-survive, unit 6)", () => {+ test("occurrences is never a sum across the structural and verdict sources", () => {+ // Same literal topic string from BOTH sources: a coarse telemetry code+ // bucket and a fine term bucket that happen to collide textually.+ seedStructuralGap(QUERY_BUCKET, 3);+ stampUnmet(QUERY, 4, WEAK_SCORES);++ const gaps = detectRecurringGaps(vault, { threshold: 3 });+ expect(gaps).toHaveLength(2);+ // Never one row of 7.+ expect(gaps.map((g) => g.occurrences).toSorted()).toEqual([3, 4]);+ expect(gaps.some((g) => g.occurrences === 7)).toBe(false);+ const bySource = new Map(gaps.map((g) => [g.source, g.occurrences]));+ expect(bySource.get(GAP_SOURCE_TELEMETRY)).toBe(3);+ expect(bySource.get(GAP_SOURCE_ADEQUACY)).toBe(4);+ });++ test("a textually identical topic from each source mints two separate tasks", () => {+ seedStructuralGap(QUERY_BUCKET, 3);+ stampUnmet(QUERY, 4, WEAK_SCORES);+ const result = promoteGapsToTasks(vault, { threshold: 3, now: NOW });+ expect(result.created).toHaveLength(2);+ // The keys are namespaced by source, so the two rows can never collapse+ // into one note.+ expect(new Set(result.created).size).toBe(2);+ expect(result.created).toContain(gapTaskKey(QUERY_BUCKET, GAP_SOURCE_TELEMETRY));+ expect(result.created).toContain(gapTaskKey(QUERY_BUCKET, GAP_SOURCE_ADEQUACY));+ });++ test("the structural gap key is unchanged by the new source argument", () => {+ // Notes minted before the adequacy source existed must keep resolving.+ expect(gapTaskKey("alpha topic")).toBe(gapTaskKey("alpha topic", GAP_SOURCE_TELEMETRY));+ expect(gapTaskKey("alpha topic")).not.toBe(gapTaskKey("alpha topic", GAP_SOURCE_ADEQUACY));+ });++ test("the agenda labels each row by its source", () => {+ seedStructuralGap("alpha topic", 3);+ stampUnmet(QUERY, 4, WEAK_SCORES);+ promoteGapsToTasks(vault, { threshold: 3, now: NOW });+ const agenda = renderGapAgenda(vault, NOW);+ // The structural row keeps its existing wording verbatim.+ expect(agenda).toContain("alpha topic (recall gap x3)");+ // The verdict row is labelled differently, so a reader can tell a coarse+ // telemetry code bucket from a fine term bucket.+ expect(agenda).toContain(`${QUERY_BUCKET} (weak recall x4)`);+ });+});diff --git a/tests/core/brain/gap-loop.test.ts b/tests/core/brain/gap-loop.test.tsindex c257dc6f..3771754d 100644--- a/tests/core/brain/gap-loop.test.ts+++ b/tests/core/brain/gap-loop.test.ts@@ -8,15 +8,21 @@ import {autoCloseRecalledGaps,detectRecurringGaps,gapTaskKey,+ GAP_SOURCE_ADEQUACY,+ GAP_SOURCE_TELEMETRY,+ GAP_SOURCES,+ GAP_TASK_CLOSED_RETENTION_MS,GAP_TASK_KIND,GAP_TASK_STATUS_CLOSED,GAP_TASK_STATUS_OPEN,+ GAP_TASKS_MAX_NOTES,listGapTasks,promoteGapsToTasks,renderGapAgenda,} from "../../../src/core/brain/gaps/gap-loop.ts";+import { brainGapTasksDir } from "../../../src/core/brain/paths.ts";import type { RecallRetriever, RecallResultSet } from "../../../src/core/brain/recall-inject.ts";-import { parseFrontmatterText } from "../../../src/core/vault.ts";+import { parseFrontmatterText, writeFrontmatterAtomic } from "../../../src/core/vault.ts";let vault: string;@@ -156,3 +162,105 @@ describe("gap loop (A3 / t_67d38036)", () => {expect(listGapTasks(vault, { status: GAP_TASK_STATUS_OPEN })).toHaveLength(1);});});++// ----- the directory the loop writes into is bounded ------------------------++describe("gap-task retention", () => {+ /** Write one gap-task note directly, bypassing the mint budget. */+ function writeTask(key: string, status: string, closedAt?: string): void {+ writeFrontmatterAtomic(+ join(brainGapTasksDir(vault), `${key}.md`),+ {+ kind: GAP_TASK_KIND,+ gap_key: key,+ gap_topic: key,+ gap_source: GAP_SOURCE_TELEMETRY,+ status,+ occurrences: "3",+ created_at: "2026-01-01T00:00:00.000Z",+ ...(closedAt !== undefined ? { closed_at: closedAt, closed_reason: "recalled" } : {}),+ },+ "body",+ { vaultForRelativePath: vault, overwrite: true },+ );+ }++ test("a closed task past the retention window is removed, and the removal is reported", () => {+ const stale = new Date(NOW.getTime() - GAP_TASK_CLOSED_RETENTION_MS - 1).toISOString();+ writeTask("gap-stale", GAP_TASK_STATUS_CLOSED, stale);+ writeTask("gap-recent", GAP_TASK_STATUS_CLOSED, NOW.toISOString());+ writeTask("gap-open", GAP_TASK_STATUS_OPEN);++ const result = promoteGapsToTasks(vault, { threshold: 2, now: NOW });+ expect(result.pruned).toEqual(["gap-stale"]);+ expect(+ listGapTasks(vault)+ .map((t) => t.key)+ .toSorted(),+ ).toEqual(["gap-open", "gap-recent"]);+ });++ test("an open task is never pruned, however old it is", () => {+ writeTask("gap-open", GAP_TASK_STATUS_OPEN);+ const result = promoteGapsToTasks(vault, {+ threshold: 2,+ now: new Date(NOW.getTime() + GAP_TASK_CLOSED_RETENTION_MS * 10),+ });+ expect(result.pruned).toEqual([]);+ expect(listGapTasks(vault)).toHaveLength(1);+ });++ test("at the cap, minting is REFUSED and named - never silently skipped", () => {+ for (let i = 0; i < GAP_TASKS_MAX_NOTES; i++)+ writeTask(`gap-filler-${i}`, GAP_TASK_STATUS_OPEN);+ seedGap("alpha topic", 3);+ const result = promoteGapsToTasks(vault, { threshold: 2, now: NOW });+ expect(result.created).toEqual([]);+ expect(result.capped).toBe(1);+ expect(listGapTasks(vault)).toHaveLength(GAP_TASKS_MAX_NOTES);+ });++ test("at the cap, a topic that already has a note is skipped, not counted as refused", () => {+ writeTask(gapTaskKey("alpha topic"), GAP_TASK_STATUS_OPEN);+ for (let i = 0; i < GAP_TASKS_MAX_NOTES - 1; i++) {+ writeTask(`gap-filler-${i}`, GAP_TASK_STATUS_OPEN);+ }+ seedGap("alpha topic", 3);+ const result = promoteGapsToTasks(vault, { threshold: 2, now: NOW });+ expect(result.capped).toBe(0);+ expect(result.skipped).toEqual([gapTaskKey("alpha topic")]);+ });++ test("room freed by pruning is usable in the same run", () => {+ const stale = new Date(NOW.getTime() - GAP_TASK_CLOSED_RETENTION_MS - 1).toISOString();+ for (let i = 0; i < GAP_TASKS_MAX_NOTES - 1; i++) {+ writeTask(`gap-filler-${i}`, GAP_TASK_STATUS_OPEN);+ }+ writeTask("gap-stale", GAP_TASK_STATUS_CLOSED, stale);+ seedGap("alpha topic", 3);+ const result = promoteGapsToTasks(vault, { threshold: 2, now: NOW });+ expect(result.pruned).toEqual(["gap-stale"]);+ expect(result.created).toEqual([gapTaskKey("alpha topic")]);+ expect(result.capped).toBe(0);+ });+});++// ----- keys are collision-free across the two recurrence sources ------------++describe("gapTaskKey", () => {+ test("a telemetry topic spelled like the adequacy namespace does not collide", () => {+ expect(gapTaskKey(`${GAP_SOURCE_ADEQUACY}:alpha`, GAP_SOURCE_TELEMETRY)).not.toBe(+ gapTaskKey("alpha", GAP_SOURCE_ADEQUACY),+ );+ });++ test("both sources are namespaced, so no pair of (source, topic) can share a key", () => {+ const seen = new Set<string>();+ for (const source of GAP_SOURCES) {+ for (const topic of ["alpha", "recall_adequacy:alpha", "recall_telemetry:alpha", "2:alpha"]) {+ seen.add(gapTaskKey(topic, source));+ }+ }+ expect(seen.size).toBe(8);+ });+});diff --git a/tests/core/brain/ingest/batch-plan-git-discovery.test.ts b/tests/core/brain/ingest/batch-plan-git-discovery.test.tsnew file mode 100644index 00000000..083e89eb--- /dev/null+++ b/tests/core/brain/ingest/batch-plan-git-discovery.test.ts@@ -0,0 +1,325 @@+/**+ * Unit 1 (t_4b2bd8f7): the ingest batch planner honours the repository's own+ * ignore declarations through the shared git-aware discovery module - root and+ * nested `.gitignore`, `.git/info/exclude`, and submodule boundaries - while the+ * operator's `--exclude` layer keeps winning over every one of them.+ *+ * A tree carrying no ignore files must plan byte-identically to before, planId+ * included.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { chmodSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { bootstrapBrain } from "../../../../src/core/brain/init.ts";+import { planBatches } from "../../../../src/core/brain/ingest/batch-plan.ts";+import { computePlanId } from "../../../../src/core/brain/ingest/checkpoint.ts";+import { atomicWriteFileSync } from "../../../../src/core/fs-atomic.ts";++let vault: string;+let configHome: string;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-gitdisc-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-gitdisc-cfg-"));+ const configPath = join(configHome, "config.yaml");+ atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);+ bootstrapBrain(vault, { configPath });+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++function write(rel: string, content = "hello\n"): void {+ const abs = join(vault, rel);+ mkdirSync(join(abs, ".."), { recursive: true });+ writeFileSync(abs, content, "utf8");+}++function plannedPaths(plan: ReturnType<typeof planBatches>): string[] {+ return plan.batches.flatMap((b) => b.files.map((f) => f.path)).toSorted();+}++const CAPS = { maxBatchBytes: 100_000, maxBatchFiles: 100 } as const;+const SOURCE = "mono";++describe("repository-declared ignore layers", () => {+ test("a .gitignore in the source dir excludes the paths it declares", () => {+ write("mono/keep.md");+ write("mono/build/out.md");+ write("mono/scratch.tmp.md");+ write("mono/.gitignore", "build/\n*.tmp.md\n");+ const plan = planBatches(vault, SOURCE, CAPS);+ expect(plannedPaths(plan)).toEqual(["mono/keep.md"]);+ });++ test("a nested .gitignore applies to its own subtree only", () => {+ write("mono/pkg/drop.md");+ write("mono/pkg/keep.md");+ write("mono/other/drop.md");+ write("mono/pkg/.gitignore", "drop.md\n");+ const plan = planBatches(vault, SOURCE, CAPS);+ expect(plannedPaths(plan)).toEqual(["mono/other/drop.md", "mono/pkg/keep.md"]);+ });++ test("a nearer ! re-include wins over the source-dir .gitignore", () => {+ write("mono/skip/important.md");+ write("mono/keep/important.md");+ write("mono/.gitignore", "important.md\n");+ write("mono/keep/.gitignore", "!important.md\n");+ const plan = planBatches(vault, SOURCE, CAPS);+ expect(plannedPaths(plan)).toEqual(["mono/keep/important.md"]);+ });++ test(".git/info/exclude is layered beneath the root .gitignore", () => {+ write("mono/a.md");+ write("mono/secret.md");+ write("mono/.git/info/exclude", "secret.md\n");+ const excluded = planBatches(vault, SOURCE, CAPS);+ expect(plannedPaths(excluded)).toEqual(["mono/a.md"]);++ // The root .gitignore sits ABOVE the exclude file, so its re-include wins.+ write("mono/.gitignore", "!secret.md\n");+ const reincluded = planBatches(vault, SOURCE, CAPS);+ expect(plannedPaths(reincluded)).toEqual(["mono/a.md", "mono/secret.md"]);+ });++ test("the source dir's .gitignore still governs when discovery is subpath-scoped", () => {+ write("mono/pkg/a/keep.md");+ write("mono/pkg/a/drop.md");+ write("mono/.gitignore", "drop.md\n");+ const plan = planBatches(vault, SOURCE, { ...CAPS, srcSubpath: "pkg/a" });+ expect(plannedPaths(plan)).toEqual(["mono/pkg/a/keep.md"]);+ });+});++describe("a subpath cannot silently re-enter an ignored subtree", () => {+ test("a subpath under an ignored directory plans nothing and says so", () => {+ write("mono/pkg/a/keep.md");+ write("mono/.gitignore", "pkg/\n");+ // Whole-tree planning already treats the subtree as ignored...+ expect(plannedPaths(planBatches(vault, SOURCE, CAPS))).toEqual([]);+ // ...and naming a directory inside it does not change the answer.+ const scoped = planBatches(vault, SOURCE, { ...CAPS, srcSubpath: "pkg/a" });+ expect(plannedPaths(scoped)).toEqual([]);+ expect(scoped.ignoreWarnings).toHaveLength(1);+ const warning = scoped.ignoreWarnings[0]!;+ expect(warning.source).toBe("--src-subpath");+ expect(warning.pattern).toBe("pkg/a");+ expect(warning.reason).toContain("mono/pkg");+ });++ test("the slashless ignore form prunes the subpath walk too", () => {+ write("mono/pkg/a/keep.md");+ write("mono/.gitignore", "pkg\n");+ const scoped = planBatches(vault, SOURCE, { ...CAPS, srcSubpath: "pkg/a" });+ expect(plannedPaths(scoped)).toEqual([]);+ expect(scoped.ignoreWarnings).toHaveLength(1);+ });++ test("the walk root itself being the ignored directory is pruned", () => {+ write("mono/pkg/keep.md");+ write("mono/.gitignore", "pkg/\n");+ const scoped = planBatches(vault, SOURCE, { ...CAPS, srcSubpath: "pkg" });+ expect(plannedPaths(scoped)).toEqual([]);+ expect(scoped.ignoreWarnings).toHaveLength(1);+ });++ test("an --exclude re-include is the explicit way to walk it anyway", () => {+ write("mono/pkg/a/keep.md");+ write("mono/.gitignore", "pkg/\n");+ const scoped = planBatches(vault, SOURCE, {+ ...CAPS,+ srcSubpath: "pkg/a",+ exclude: ["!pkg/"],+ });+ expect(plannedPaths(scoped)).toEqual(["mono/pkg/a/keep.md"]);+ expect(scoped.ignoreWarnings).toEqual([]);+ });++ test("a subpath under a directory the repository never ignored is unaffected", () => {+ write("mono/pkg/a/keep.md");+ write("mono/.gitignore", "other/\n");+ const scoped = planBatches(vault, SOURCE, { ...CAPS, srcSubpath: "pkg/a" });+ expect(plannedPaths(scoped)).toEqual(["mono/pkg/a/keep.md"]);+ expect(scoped.ignoreWarnings).toEqual([]);+ });+});++describe("a subpath cannot cross a nested repository boundary", () => {+ test("a subpath inside a submodule is refused", () => {+ write("mono/sub/inner/x.md");+ write("mono/sub/.git", "gitdir: ../.git/modules/sub\n");+ // The unscoped walk already refuses to attribute those files to this tree.+ expect(plannedPaths(planBatches(vault, SOURCE, CAPS))).toEqual([]);+ expect(() => planBatches(vault, SOURCE, { ...CAPS, srcSubpath: "sub/inner" })).toThrow(+ /nested repository boundary/,+ );+ });++ test("a subpath equal to the submodule root is refused", () => {+ write("mono/sub/inner.md");+ write("mono/sub/.git", "gitdir: ../.git/modules/sub\n");+ expect(() => planBatches(vault, SOURCE, { ...CAPS, srcSubpath: "sub" })).toThrow(+ /nested repository boundary/,+ );+ });++ test("a subpath inside a nested independent checkout is refused", () => {+ write("mono/vendor/inner/x.md");+ mkdirSync(join(vault, "mono", "vendor", ".git"), { recursive: true });+ expect(() => planBatches(vault, SOURCE, { ...CAPS, srcSubpath: "vendor/inner" })).toThrow(+ /nested repository boundary/,+ );+ });++ test("an --exclude re-include cannot open a repository boundary", () => {+ write("mono/sub/inner/x.md");+ write("mono/sub/.git", "gitdir: ../.git/modules/sub\n");+ expect(() =>+ planBatches(vault, SOURCE, { ...CAPS, srcSubpath: "sub/inner", exclude: ["!sub/"] }),+ ).toThrow(/nested repository boundary/);+ });++ test("an ordinary intermediate directory is still descended into", () => {+ write("mono/plain/inner/x.md");+ const plan = planBatches(vault, SOURCE, { ...CAPS, srcSubpath: "plain/inner" });+ expect(plannedPaths(plan)).toEqual(["mono/plain/inner/x.md"]);+ });+});++describe("an ignore file that cannot be honoured reaches the plan", () => {+ test("an unreadable .gitignore is a structured plan warning, not a silent pass", () => {+ write("mono/secret.md");+ write("mono/.gitignore", "secret.md\n");+ chmodSync(join(vault, "mono", ".gitignore"), 0o000);+ const plan = planBatches(vault, SOURCE, CAPS);+ // The file the repository declared excluded is still queued - but never+ // without a signal saying why the declaration was not applied.+ expect(plannedPaths(plan)).toEqual(["mono/secret.md"]);+ expect(plan.ignoreWarnings).toHaveLength(1);+ expect(plan.ignoreWarnings[0]!.source).toBe("mono/.gitignore");+ expect(plan.ignoreWarnings[0]!.reason).toContain("EACCES");+ });++ test("a symlinked .gitignore is refused with a warning", () => {+ write("mono/secret.md");+ write("elsewhere/rules", "secret.md\n");+ symlinkSync(join(vault, "elsewhere", "rules"), join(vault, "mono", ".gitignore"));+ const plan = planBatches(vault, SOURCE, CAPS);+ expect(plannedPaths(plan)).toEqual(["mono/secret.md"]);+ expect(plan.ignoreWarnings).toHaveLength(1);+ expect(plan.ignoreWarnings[0]!.reason).toContain("symbolic link");+ });+});++describe("submodule boundaries", () => {+ test("a directory carrying a gitlink file is not descended into", () => {+ write("mono/keep.md");+ write("mono/sub/inner.md");+ write("mono/sub/.git", "gitdir: ../.git/modules/sub\n");+ const plan = planBatches(vault, SOURCE, CAPS);+ expect(plannedPaths(plan)).toEqual(["mono/keep.md"]);+ });++ test("a directory carrying a nested .git directory is not descended into", () => {+ write("mono/keep.md");+ write("mono/vendor/inner.md");+ mkdirSync(join(vault, "mono", "vendor", ".git"), { recursive: true });+ const plan = planBatches(vault, SOURCE, CAPS);+ expect(plannedPaths(plan)).toEqual(["mono/keep.md"]);+ });++ test("the source dir being a repository root does not prune the whole walk", () => {+ write("mono/keep.md");+ mkdirSync(join(vault, "mono", ".git"), { recursive: true });+ const plan = planBatches(vault, SOURCE, CAPS);+ expect(plannedPaths(plan)).toEqual(["mono/keep.md"]);+ });+});++describe("operator --exclude wins over every repository layer", () => {+ test("--exclude drops a path the repository never declared", () => {+ write("mono/keep.md");+ write("mono/vendor/dep.md");+ write("mono/.gitignore", "nothing-here.md\n");+ const plan = planBatches(vault, SOURCE, { ...CAPS, exclude: ["vendor/"] });+ expect(plannedPaths(plan)).toEqual(["mono/keep.md"]);+ });++ test("an --exclude re-include overrides a repository-declared ignore", () => {+ write("mono/keep.md");+ write("mono/generated/out.md");+ write("mono/.gitignore", "generated/\n");+ const withoutOverride = planBatches(vault, SOURCE, CAPS);+ expect(plannedPaths(withoutOverride)).toEqual(["mono/keep.md"]);++ const plan = planBatches(vault, SOURCE, { ...CAPS, exclude: ["!generated/"] });+ expect(plannedPaths(plan)).toEqual(["mono/generated/out.md", "mono/keep.md"]);+ });++ test("--exclude also overrides a nested .gitignore", () => {+ write("mono/pkg/drop.md");+ write("mono/pkg/.gitignore", "drop.md\n");+ const plan = planBatches(vault, SOURCE, { ...CAPS, exclude: ["!drop.md"] });+ expect(plannedPaths(plan)).toEqual(["mono/pkg/drop.md"]);+ });+});++describe("byte-identical no-git path", () => {+ test("a tree with no ignore files produces the planId it produces today", () => {+ write("mono/a.md");+ write("mono/sub/b.md");+ const plan = planBatches(vault, SOURCE, CAPS);+ expect(plannedPaths(plan)).toEqual(["mono/a.md", "mono/sub/b.md"]);+ // Pinned against the documented derivation rather than against the walk, so+ // the assertion cannot drift with the discovery implementation.+ expect(plan.planId).toBe(computePlanId(SOURCE, ["mono/a.md", "mono/sub/b.md"]));+ expect(plan.ignoreWarnings).toEqual([]);+ });++ test("an empty --exclude list is identical to no --exclude at all", () => {+ write("mono/a.md");+ write("mono/sub/b.md");+ const baseline = planBatches(vault, SOURCE, CAPS);+ const withEmpty = planBatches(vault, SOURCE, { ...CAPS, exclude: [] });+ expect(withEmpty.planId).toBe(baseline.planId);+ expect(plannedPaths(withEmpty)).toEqual(plannedPaths(baseline));+ });+});++describe("malformed patterns", () => {+ test("a malformed repository pattern is a structured plan warning, not a failure", () => {+ write("mono/keep.md");+ write("mono/[weird.md");+ write("mono/.gitignore", "keep-nothing.md\n[unterminated\n");+ const plan = planBatches(vault, SOURCE, CAPS);+ // No rule was produced, so nothing was silently dropped.+ expect(plannedPaths(plan)).toEqual(["mono/[weird.md", "mono/keep.md"]);+ expect(plan.ignoreWarnings).toHaveLength(1);+ const warning = plan.ignoreWarnings[0]!;+ expect(warning.source).toBe("mono/.gitignore");+ expect(warning.line).toBe(2);+ expect(warning.pattern).toBe("[unterminated");+ expect(warning.reason).toContain("unterminated");+ });++ test("a malformed pattern in a nested .gitignore names that file", () => {+ write("mono/pkg/keep.md");+ write("mono/pkg/.gitignore", "[unterminated\n");+ const plan = planBatches(vault, SOURCE, CAPS);+ expect(plannedPaths(plan)).toEqual(["mono/pkg/keep.md"]);+ expect(plan.ignoreWarnings.map((w) => w.source)).toEqual(["mono/pkg/.gitignore"]);+ });++ test("a malformed operator --exclude pattern still throws", () => {+ write("mono/keep.md");+ expect(() => planBatches(vault, SOURCE, { ...CAPS, exclude: ["[unterminated"] })).toThrow(+ /malformed --exclude pattern/,+ );+ });+});diff --git a/tests/core/brain/lineage-work-identity.test.ts b/tests/core/brain/lineage-work-identity.test.tsnew file mode 100644index 00000000..af48d956--- /dev/null+++ b/tests/core/brain/lineage-work-identity.test.ts@@ -0,0 +1,832 @@+/**+ * Durable work identity above the timing crutch (signals-that-survive,+ * Unit 9; kanban t_e6be4f6b).+ *+ * Session continuation used to have exactly two durable signals - the+ * lineage the host declared and a fifteen-minute freshness window - so a+ * work item resumed after a model, account, branch or worktree switch+ * never re-attached. This pins the third: an OPTIONAL declared work id+ * and lane id, sourced in strict precedence at the capture boundary and+ * ranked above the window.+ *+ * Two properties carry the whole unit:+ *+ * - identity is DECLARED, never derived. Nothing here fingerprints a+ * remote, a merge-base or a gitdir, and no rung accumulates a union+ * of what it has seen;+ * - a lane is a HARD separator, never a tiebreak. Two entries sharing+ * a work id under different lanes can never link, at any rung, and+ * the refusal is a named outcome rather than a silent non-link.+ *+ * With both fields absent every assertion in `lineage.test.ts` and+ * `lineage-continuation.test.ts` still holds unmodified; the byte-+ * identical cases below pin the same property from this side.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import {+ existsSync,+ mkdirSync,+ mkdtempSync,+ readdirSync,+ readFileSync,+ rmSync,+ writeFileSync,+} from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import type { DegradationNotice } from "../../../src/core/integrity/degradation.ts";+import { CRUTCH_ABSTENTION, resolveCrutchLineage } from "../../../src/core/brain/lineage/crutch.ts";+import {+ brainStateDirPath,+ CRUTCH_LINK_WINDOW_MS,+ type LineageObservation,+ readLineageLedger,+ recordLineageObservation,+ sessionLineageLedgerPath,+} from "../../../src/core/brain/lineage/ledger.ts";+import {+ clearWorkIdentityMarker,+ readWorkIdentityMarker,+ recordWorkIdentityMarker,+ resolveWorkIdentity,+ WORK_IDENTITY_MARKER_MAX_AGE_MS,+ WORK_IDENTITY_MARKER_MAX_FILES,+ WORK_IDENTITY_MARKER_STATUS,+ WORK_IDENTITY_SOURCE,+ workIdentityMarkerPath,+} from "../../../src/core/brain/lineage/identity.ts";+import {+ resolveSessionLineage,+ resolveSessionLineageDetailed,+} from "../../../src/core/brain/lineage/resolve.ts";+import { verifyLineageLedger } from "../../../src/core/brain/lineage/verify.ts";+import { captureSessionLifecycleEvent } from "../../../src/core/brain/session-lifecycle.ts";+import { bootstrapBrain } from "../../../src/core/brain/init.ts";++let tmp: string;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-work-identity-"));+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++const T0 = Date.parse("2026-06-10T08:00:00Z");++const WORK_ID = "w-refactor-ledger";+const OTHER_WORK_ID = "w-unrelated";+const LANE_A = "lane-alpha";+const LANE_B = "lane-beta";+const WORKTREE_A = "/work/tree-a";+const WORKTREE_B = "/work/tree-b";++const WORK_ID_ENV_KEY = "OPEN_SECOND_BRAIN_WORK_ID";+const LANE_ID_ENV_KEY = "OPEN_SECOND_BRAIN_LANE_ID";++/** A config file carrying only the keys a case declares. */+function writeConfig(entries: Readonly<Record<string, string>>): string {+ const path = join(tmp, `config-${Object.keys(entries).join("-") || "empty"}.yaml`);+ writeFileSync(+ path,+ `${Object.entries(entries)+ .map(([key, value]) => `${key}: "${value}"`)+ .join("\n")}\n`,+ "utf8",+ );+ return path;+}++function seed(obs: Partial<LineageObservation> & { sessionId: string; atMs: number }): void {+ const { atMs, ...rest } = obs;+ recordLineageObservation(tmp, {+ at: new Date(atMs).toISOString(),+ event: "UserPromptSubmit",+ ...rest,+ });+}++// ----- rung 1..3: where a declaration is read from -------------------------++describe("resolveWorkIdentity - declared, in strict precedence", () => {+ test("the host payload field outranks the environment, the config and the marker", () => {+ recordWorkIdentityMarker(tmp, WORKTREE_A, { workId: "w-marker", laneId: LANE_B });+ const identity = resolveWorkIdentity({+ vault: tmp,+ payloadWorkId: WORK_ID,+ payloadLaneId: LANE_A,+ worktree: WORKTREE_A,+ env: { [WORK_ID_ENV_KEY]: "w-env", [LANE_ID_ENV_KEY]: LANE_B },+ configPath: writeConfig({ work_id: "w-config" }),+ });+ expect(identity).toEqual({+ workId: WORK_ID,+ laneId: LANE_A,+ source: WORK_IDENTITY_SOURCE.payload,+ });+ });++ test("the environment variable outranks the config key and the marker", () => {+ recordWorkIdentityMarker(tmp, WORKTREE_A, { workId: "w-marker" });+ const identity = resolveWorkIdentity({+ vault: tmp,+ worktree: WORKTREE_A,+ env: { [WORK_ID_ENV_KEY]: WORK_ID, [LANE_ID_ENV_KEY]: LANE_A },+ configPath: writeConfig({ work_id: "w-config", lane_id: LANE_B }),+ });+ expect(identity).toEqual({+ workId: WORK_ID,+ laneId: LANE_A,+ source: WORK_IDENTITY_SOURCE.environment,+ });+ });++ test("the config key is read when neither payload nor environment declares one", () => {+ recordWorkIdentityMarker(tmp, WORKTREE_A, { workId: "w-marker" });+ const identity = resolveWorkIdentity({+ vault: tmp,+ worktree: WORKTREE_A,+ env: {},+ configPath: writeConfig({ work_id: WORK_ID, lane_id: LANE_A }),+ });+ expect(identity).toEqual({+ workId: WORK_ID,+ laneId: LANE_A,+ source: WORK_IDENTITY_SOURCE.environment,+ });+ });++ test("the per-worktree marker is the last rung", () => {+ recordWorkIdentityMarker(tmp, WORKTREE_A, { workId: WORK_ID, laneId: LANE_A });+ const identity = resolveWorkIdentity({+ vault: tmp,+ worktree: WORKTREE_A,+ env: {},+ configPath: writeConfig({}),+ });+ expect(identity).toEqual({+ workId: WORK_ID,+ laneId: LANE_A,+ source: WORK_IDENTITY_SOURCE.marker,+ });+ });++ test("the lane rides with the rung that declared the work id", () => {+ const identity = resolveWorkIdentity({+ vault: tmp,+ payloadWorkId: WORK_ID,+ worktree: WORKTREE_A,+ env: { [LANE_ID_ENV_KEY]: LANE_B },+ configPath: writeConfig({}),+ });+ expect(identity).toEqual({ workId: WORK_ID, source: WORK_IDENTITY_SOURCE.payload });+ });++ test("a lane alone is a declaration - a work id is not required", () => {+ const identity = resolveWorkIdentity({+ vault: tmp,+ payloadLaneId: LANE_A,+ worktree: WORKTREE_A,+ env: {},+ configPath: writeConfig({}),+ });+ expect(identity).toEqual({ laneId: LANE_A, source: WORK_IDENTITY_SOURCE.payload });+ });++ test("nothing declared anywhere resolves to null", () => {+ expect(+ resolveWorkIdentity({+ vault: tmp,+ worktree: WORKTREE_A,+ env: {},+ configPath: writeConfig({}),+ }),+ ).toBeNull();+ });++ test("blank declarations are not declarations", () => {+ expect(+ resolveWorkIdentity({+ vault: tmp,+ payloadWorkId: " ",+ payloadLaneId: "",+ worktree: WORKTREE_A,+ env: { [WORK_ID_ENV_KEY]: " " },+ configPath: writeConfig({}),+ }),+ ).toBeNull();+ });++ test("a marker recorded for one worktree is never read for another", () => {+ recordWorkIdentityMarker(tmp, WORKTREE_A, { workId: WORK_ID });+ expect(readWorkIdentityMarker(tmp, WORKTREE_B)).toBeNull();+ expect(readWorkIdentityMarker(tmp, WORKTREE_A)).toEqual({+ workId: WORK_ID,+ source: WORK_IDENTITY_SOURCE.marker,+ });+ });++ test("a marker whose recorded worktree no longer matches is not read", () => {+ recordWorkIdentityMarker(tmp, WORKTREE_A, { workId: WORK_ID });+ const path = workIdentityMarkerPath(tmp, WORKTREE_A);+ const stored = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;+ writeFileSync(path, JSON.stringify({ ...stored, worktree: WORKTREE_B }), "utf8");+ expect(readWorkIdentityMarker(tmp, WORKTREE_A)).toBeNull();+ });++ test("the marker lives under the Brain state directory, not in the note tree", () => {+ recordWorkIdentityMarker(tmp, WORKTREE_A, { workId: WORK_ID });+ expect(workIdentityMarkerPath(tmp, WORKTREE_A).startsWith(brainStateDirPath(tmp))).toBe(true);+ });++ test("the environment rung is taken WHOLE: a config lane never joins a shell work id", () => {+ const identity = resolveWorkIdentity({+ vault: tmp,+ worktree: WORKTREE_A,+ env: { [WORK_ID_ENV_KEY]: WORK_ID },+ configPath: writeConfig({ lane_id: LANE_B }),+ });+ // A composite nobody declared - shell work id + file lane - is exactly+ // what the rung boundary exists to prevent, and a lane is a hard+ // separator, so composing one could refuse a link both sides agreed on.+ expect(identity).toEqual({ workId: WORK_ID, source: WORK_IDENTITY_SOURCE.environment });+ });++ test("the config rung is taken whole too, when the environment declares nothing", () => {+ const identity = resolveWorkIdentity({+ vault: tmp,+ worktree: WORKTREE_A,+ env: {},+ configPath: writeConfig({ work_id: WORK_ID, lane_id: LANE_A }),+ });+ expect(identity).toEqual({+ workId: WORK_ID,+ laneId: LANE_A,+ source: WORK_IDENTITY_SOURCE.environment,+ });+ });+});++// ----- the marker rung is bounded in time and in count ----------------------++describe("the marker rung expires; a declaration does not", () => {+ test("a marker read after the staleness bound declares nothing", () => {+ recordWorkIdentityMarker(tmp, WORKTREE_A, { workId: WORK_ID }, { nowMs: T0 });+ expect(readWorkIdentityMarker(tmp, WORKTREE_A, { nowMs: T0 + 1_000 })).toEqual({+ workId: WORK_ID,+ source: WORK_IDENTITY_SOURCE.marker,+ });+ expect(+ readWorkIdentityMarker(tmp, WORKTREE_A, {+ nowMs: T0 + WORK_IDENTITY_MARKER_MAX_AGE_MS + 1,+ }),+ ).toBeNull();+ });++ test("a payload or environment declaration still links across the same gap", () => {+ const nowMs = T0 + WORK_IDENTITY_MARKER_MAX_AGE_MS * 10;+ expect(+ resolveWorkIdentity({+ vault: tmp,+ payloadWorkId: WORK_ID,+ worktree: WORKTREE_A,+ env: {},+ configPath: writeConfig({}),+ nowMs,+ }),+ ).toEqual({ workId: WORK_ID, source: WORK_IDENTITY_SOURCE.payload });+ expect(+ resolveWorkIdentity({+ vault: tmp,+ worktree: WORKTREE_A,+ env: { [WORK_ID_ENV_KEY]: WORK_ID },+ configPath: writeConfig({}),+ nowMs,+ }),+ ).toEqual({ workId: WORK_ID, source: WORK_IDENTITY_SOURCE.environment });+ });++ test("an undatable marker declares nothing: freshness that cannot be shown is not assumed", () => {+ recordWorkIdentityMarker(tmp, WORKTREE_A, { workId: WORK_ID }, { nowMs: T0 });+ const path = workIdentityMarkerPath(tmp, WORKTREE_A);+ const stored = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;+ delete stored["at"];+ writeFileSync(path, `${JSON.stringify(stored)}\n`, "utf8");+ expect(readWorkIdentityMarker(tmp, WORKTREE_A, { nowMs: T0 + 1_000 })).toBeNull();+ });++ test("a live declaration refreshes the marker, so continuous work keeps inheriting", () => {+ recordWorkIdentityMarker(tmp, WORKTREE_A, { workId: WORK_ID }, { nowMs: T0 });+ const later = T0 + WORK_IDENTITY_MARKER_MAX_AGE_MS - 1;+ expect(recordWorkIdentityMarker(tmp, WORKTREE_A, { workId: WORK_ID }, { nowMs: later })).toBe(+ WORK_IDENTITY_MARKER_STATUS.written,+ );+ expect(+ readWorkIdentityMarker(tmp, WORKTREE_A, {+ nowMs: later + WORK_IDENTITY_MARKER_MAX_AGE_MS - 1,+ }),+ ).not.toBeNull();+ });++ test("an unchanged declaration inside the refresh interval does not rewrite the file", () => {+ recordWorkIdentityMarker(tmp, WORKTREE_A, { workId: WORK_ID }, { nowMs: T0 });+ const before = readFileSync(workIdentityMarkerPath(tmp, WORKTREE_A), "utf8");+ expect(+ recordWorkIdentityMarker(tmp, WORKTREE_A, { workId: WORK_ID }, { nowMs: T0 + 1_000 }),+ ).toBe(WORK_IDENTITY_MARKER_STATUS.unchanged);+ expect(readFileSync(workIdentityMarkerPath(tmp, WORKTREE_A), "utf8")).toBe(before);+ });++ test("a changed declaration always rewrites, refresh interval or not", () => {+ recordWorkIdentityMarker(tmp, WORKTREE_A, { workId: WORK_ID }, { nowMs: T0 });+ expect(+ recordWorkIdentityMarker(tmp, WORKTREE_A, { workId: OTHER_WORK_ID }, { nowMs: T0 + 1_000 }),+ ).toBe(WORK_IDENTITY_MARKER_STATUS.written);+ expect(readWorkIdentityMarker(tmp, WORKTREE_A, { nowMs: T0 + 2_000 })?.workId).toBe(+ OTHER_WORK_ID,+ );+ });++ test("clearing a marker is one documented call, and the rung goes quiet", () => {+ recordWorkIdentityMarker(tmp, WORKTREE_A, { workId: WORK_ID }, { nowMs: T0 });+ expect(clearWorkIdentityMarker(tmp, WORKTREE_A)).toBe(true);+ expect(readWorkIdentityMarker(tmp, WORKTREE_A, { nowMs: T0 + 1_000 })).toBeNull();+ // Idempotent: clearing what is not there is not an error.+ expect(clearWorkIdentityMarker(tmp, WORKTREE_A)).toBe(false);+ });++ test("the marker directory is bounded: a fresh worktree per job cannot grow it forever", () => {+ const total = WORK_IDENTITY_MARKER_MAX_FILES + 20;+ for (let i = 0; i < total; i++) {+ recordWorkIdentityMarker(tmp, `/ci/job-${i}`, { workId: `w-${i}` }, { nowMs: T0 + i });+ }+ const dir = join(brainStateDirPath(tmp), "work-identity");+ const files = readdirSync(dir);+ expect(files.length).toBeLessThanOrEqual(WORK_IDENTITY_MARKER_MAX_FILES);+ // The newest declaration is always among the survivors.+ expect(+ readWorkIdentityMarker(tmp, `/ci/job-${total - 1}`, { nowMs: T0 + total }),+ ).not.toBeNull();+ });++ test("the sweep drops expired markers before it drops live ones", () => {+ recordWorkIdentityMarker(tmp, "/ci/ancient", { workId: "w-ancient" }, { nowMs: T0 });+ const fresh = T0 + WORK_IDENTITY_MARKER_MAX_AGE_MS * 2;+ for (let i = 0; i < WORK_IDENTITY_MARKER_MAX_FILES + 1; i++) {+ recordWorkIdentityMarker(tmp, `/ci/job-${i}`, { workId: `w-${i}` }, { nowMs: fresh + i });+ }+ expect(existsSync(workIdentityMarkerPath(tmp, "/ci/ancient"))).toBe(false);+ });+});++// ----- the ledger line ------------------------------------------------------++describe("lineage ledger - the declared identity rides the line", () => {+ test("records and reads back the work id and the lane id", () => {+ seed({ sessionId: "s-1", atMs: T0, workId: WORK_ID, laneId: LANE_A });+ const entry = readLineageLedger(tmp).get("s-1");+ expect(entry?.workId).toBe(WORK_ID);+ expect(entry?.laneId).toBe(LANE_A);+ });++ test("carries the last declared identity forward across observations", () => {+ seed({ sessionId: "s-1", atMs: T0, workId: WORK_ID, laneId: LANE_A });+ seed({ sessionId: "s-1", atMs: T0 + 1_000, event: "PostToolUse" });+ const entry = readLineageLedger(tmp).get("s-1");+ expect(entry?.workId).toBe(WORK_ID);+ expect(entry?.laneId).toBe(LANE_A);+ });++ test("a line written without an identity carries neither key", () => {+ seed({ sessionId: "s-1", atMs: T0, cwd: WORKTREE_A });+ const raw = readFileSync(sessionLineageLedgerPath(tmp), "utf8").trim();+ const line = JSON.parse(raw) as Record<string, unknown>;+ expect("wid" in line).toBe(false);+ expect("lane" in line).toBe(false);+ expect(readLineageLedger(tmp).get("s-1")?.workId).toBeUndefined();+ });++ test("the integrity chain verifies with the new fields present", () => {+ seed({ sessionId: "s-1", atMs: T0, workId: WORK_ID, laneId: LANE_A });+ seed({ sessionId: "s-2", atMs: T0 + 1_000, workId: WORK_ID, laneId: LANE_A });+ seed({ sessionId: "s-3", atMs: T0 + 2_000 });+ const report = verifyLineageLedger(tmp);+ expect(report.ok).toBe(true);+ expect(report.notices).toEqual([]);+ });+});++// ----- the identity rung ----------------------------------------------------++describe("resolveCrutchLineage - the identity rung above the window", () => {+ test("links on a shared work id alone: outside the window, across worktrees", () => {+ seed({+ sessionId: "s-parent",+ atMs: T0,+ cwd: WORKTREE_A,+ workId: WORK_ID,+ workspace: { repo: "https://example.invalid/o/r", branch: "main", commit: "a".repeat(40) },+ });+ const outcome = resolveCrutchLineage({+ sessionId: "s-child",+ cwd: WORKTREE_B,+ workId: WORK_ID,+ workspace: { repo: "https://example.invalid/o/r", branch: "feature", commit: "b".repeat(40) },+ ledger: readLineageLedger(tmp),+ nowMs: T0 + CRUTCH_LINK_WINDOW_MS * 10,+ });+ expect(outcome).toEqual({+ kind: "linked",+ lineage: { rootId: "s-parent", parentId: "s-parent", depth: 1, source: "identity" },+ });+ });++ test("links with no compression evidence anywhere in the ledger", () => {+ seed({ sessionId: "s-parent", atMs: T0, cwd: WORKTREE_A, workId: WORK_ID });+ const outcome = resolveCrutchLineage({+ sessionId: "s-child",+ cwd: WORKTREE_A,+ workId: WORK_ID,+ ledger: readLineageLedger(tmp),+ nowMs: T0 + 1_000,+ });+ expect(outcome.kind).toBe("linked");+ });++ test("inherits the predecessor's root and continues its depth", () => {+ seed({+ sessionId: "s-parent",+ atMs: T0,+ workId: WORK_ID,+ lineage: { rootId: "s-root", parentId: "s-root", depth: 1, source: "payload" },+ });+ const outcome = resolveCrutchLineage({+ sessionId: "s-child",+ workId: WORK_ID,+ ledger: readLineageLedger(tmp),+ nowMs: T0 + 1_000,+ });+ expect(outcome).toMatchObject({+ kind: "linked",+ lineage: { rootId: "s-root", parentId: "s-parent", depth: 2 },+ });+ });++ test("a different lane id never links, and the refusal is named", () => {+ seed({+ sessionId: "s-parent",+ atMs: T0,+ cwd: WORKTREE_A,+ workId: WORK_ID,+ laneId: LANE_A,+ compressionEvidence: true,+ });+ const outcome = resolveCrutchLineage({+ sessionId: "s-child",+ cwd: WORKTREE_A,+ workId: WORK_ID,+ laneId: LANE_B,+ ledger: readLineageLedger(tmp),+ nowMs: T0 + 1_000,+ });+ expect(outcome).toMatchObject({ kind: "abstained", reason: CRUTCH_ABSTENTION.laneConflict });+ });++ test("a lane conflict blocks the window rung too, so no rung can link it", () => {+ // No shared work id: only the lane separates them, and everything the+ // window rung requires (same cwd, fresh, evidenced) holds.+ seed({+ sessionId: "s-parent",+ atMs: T0,+ cwd: WORKTREE_A,+ laneId: LANE_A,+ compressionEvidence: true,+ });+ const outcome = resolveCrutchLineage({+ sessionId: "s-child",+ cwd: WORKTREE_A,+ laneId: LANE_B,+ ledger: readLineageLedger(tmp),+ nowMs: T0 + 1_000,+ });+ expect(outcome).toMatchObject({ kind: "abstained", reason: CRUTCH_ABSTENTION.laneConflict });+ });++ test("two same-lane predecessors sharing a work id abstain as work-ambiguous", () => {+ seed({ sessionId: "s-one", atMs: T0, cwd: WORKTREE_A, workId: WORK_ID, laneId: LANE_A });+ seed({+ sessionId: "s-two",+ atMs: T0 + 1_000,+ cwd: WORKTREE_B,+ workId: WORK_ID,+ laneId: LANE_A,+ });+ const outcome = resolveCrutchLineage({+ sessionId: "s-child",+ cwd: WORKTREE_A,+ workId: WORK_ID,+ laneId: LANE_A,+ ledger: readLineageLedger(tmp),+ nowMs: T0 + 2_000,+ });+ expect(outcome).toMatchObject({+ kind: "abstained",+ reason: CRUTCH_ABSTENTION.workAmbiguous,+ considered: 2,+ });+ });++ test("a predecessor another session already continued from is spoken for", () => {+ seed({ sessionId: "s-a", atMs: T0, workId: WORK_ID });+ seed({+ sessionId: "s-b",+ atMs: T0 + 1_000,+ workId: WORK_ID,+ lineage: { rootId: "s-a", parentId: "s-a", depth: 1, source: "identity" },+ });+ const outcome = resolveCrutchLineage({+ sessionId: "s-c",+ workId: WORK_ID,+ ledger: readLineageLedger(tmp),+ nowMs: T0 + 2_000,+ });+ expect(outcome).toMatchObject({+ kind: "linked",+ lineage: { parentId: "s-b", rootId: "s-a", depth: 2 },+ });+ });++ test("falls through to the window rung when no predecessor shares the work id", () => {+ seed({+ sessionId: "s-parent",+ atMs: T0,+ cwd: WORKTREE_A,+ workId: OTHER_WORK_ID,+ compressionEvidence: true,+ });+ const outcome = resolveCrutchLineage({+ sessionId: "s-child",+ cwd: WORKTREE_A,+ workId: WORK_ID,+ ledger: readLineageLedger(tmp),+ nowMs: T0 + 1_000,+ });+ expect(outcome).toMatchObject({+ kind: "linked",+ lineage: { parentId: "s-parent", source: "crutch" },+ });+ });++ test("a session with its own ledger history stays self-known", () => {+ seed({ sessionId: "s-parent", atMs: T0, workId: WORK_ID });+ seed({ sessionId: "s-child", atMs: T0 + 1_000, workId: WORK_ID });+ const outcome = resolveCrutchLineage({+ sessionId: "s-child",+ workId: WORK_ID,+ ledger: readLineageLedger(tmp),+ nowMs: T0 + 2_000,+ });+ expect(outcome).toMatchObject({ kind: "abstained", reason: CRUTCH_ABSTENTION.selfKnown });+ });++ test("a spoken-for predecessor is checked BEFORE its lane, so it cannot veto rung 2", () => {+ // s-a declares the work id under lane A and has already been continued+ // from; s-b is the live predecessor and declares no lane at all.+ seed({ sessionId: "s-a", atMs: T0, cwd: WORKTREE_A, workId: WORK_ID, laneId: LANE_A });+ seed({+ sessionId: "s-b",+ atMs: T0 + 1_000,+ cwd: WORKTREE_A,+ compressionEvidence: true,+ lineage: { rootId: "s-a", parentId: "s-a", depth: 1, source: "identity" },+ });+ const outcome = resolveCrutchLineage({+ sessionId: "s-c",+ cwd: WORKTREE_A,+ workId: WORK_ID,+ laneId: LANE_B,+ ledger: readLineageLedger(tmp),+ nowMs: T0 + 2_000,+ });+ // A predecessor already spoken for is not a lane conflict: counting it+ // as one produced a TERMINAL lane-conflict abstention that hid the+ // legitimate window-rung link below.+ expect(outcome).toMatchObject({+ kind: "linked",+ lineage: { parentId: "s-b", source: "crutch" },+ });+ });++ test("the abstention detail names the lane only when a lane actually refused one", () => {+ seed({ sessionId: "s-parent", atMs: T0, cwd: WORKTREE_A });+ const quiet = resolveCrutchLineage({+ sessionId: "s-child",+ cwd: WORKTREE_A,+ ledger: readLineageLedger(tmp),+ nowMs: T0 + 1_000,+ });+ expect(quiet).toMatchObject({ kind: "abstained" });+ expect((quiet as { detail: string }).detail).not.toContain("another lane");++ seed({ sessionId: "s-laned", atMs: T0 + 2_000, cwd: WORKTREE_B, laneId: LANE_A });+ const refused = resolveCrutchLineage({+ sessionId: "s-other",+ cwd: WORKTREE_B,+ laneId: LANE_B,+ ledger: readLineageLedger(tmp),+ nowMs: T0 + 3_000,+ });+ expect((refused as { detail: string }).detail).toContain("1 in another lane");+ });++ test("a declared work id does not rescue a session the gap sidecar recorded", () => {+ seed({ sessionId: "s-parent", atMs: T0, workId: WORK_ID });+ const outcome = resolveCrutchLineage({+ sessionId: "s-child",+ workId: WORK_ID,+ ledger: readLineageLedger(tmp),+ nowMs: T0 + 1_000,+ gapSessionIds: new Set(["s-child"]),+ });+ expect(outcome).toMatchObject({ kind: "abstained", reason: CRUTCH_ABSTENTION.selfKnown });+ });+});++// ----- the resolution ladder ------------------------------------------------++describe("resolveSessionLineageDetailed - identity between payload and the window", () => {+ test("native payload lineage still outranks a declared work identity", () => {+ seed({ sessionId: "s-parent", atMs: T0, workId: WORK_ID });+ const resolution = resolveSessionLineageDetailed(+ { sessionId: "s-child", parentSessionId: "s-native", workId: WORK_ID },+ { ledger: readLineageLedger(tmp), nowMs: T0 + 1_000 },+ );+ expect(resolution.lineage).toEqual({+ rootId: "s-native",+ parentId: "s-native",+ depth: 1,+ source: "payload",+ });+ });++ test("resolves through the identity rung when the payload carries no lineage", () => {+ seed({ sessionId: "s-parent", atMs: T0, cwd: WORKTREE_A, workId: WORK_ID });+ const lineage = resolveSessionLineage(+ { sessionId: "s-child", cwd: WORKTREE_B, workId: WORK_ID },+ { ledger: readLineageLedger(tmp), nowMs: T0 + CRUTCH_LINK_WINDOW_MS * 4 },+ );+ expect(lineage).toEqual({+ rootId: "s-parent",+ parentId: "s-parent",+ depth: 1,+ source: "identity",+ });+ });++ test("a lane conflict is reported as a refused continuation, not a silent flat", () => {+ seed({+ sessionId: "s-parent",+ atMs: T0,+ cwd: WORKTREE_A,+ workId: WORK_ID,+ laneId: LANE_A,+ compressionEvidence: true,+ });+ const notices: DegradationNotice[] = [];+ const resolution = resolveSessionLineageDetailed(+ { sessionId: "s-child", cwd: WORKTREE_A, workId: WORK_ID, laneId: LANE_B },+ { ledger: readLineageLedger(tmp), nowMs: T0 + 1_000, notices },+ );+ expect(resolution.lineage.source).toBe("flat");+ expect(resolution.crutch).toMatchObject({ reason: CRUTCH_ABSTENTION.laneConflict });+ expect(notices.length).toBe(1);+ });++ test("with no identity declared the resolution shape is unchanged", () => {+ seed({ sessionId: "s-parent", atMs: T0, cwd: WORKTREE_A, compressionEvidence: true });+ const resolution = resolveSessionLineageDetailed(+ { sessionId: "s-child", cwd: WORKTREE_A },+ { ledger: readLineageLedger(tmp), nowMs: T0 + 1_000 },+ );+ expect(Object.keys(resolution).toSorted()).toEqual(["crutch", "lineage"]);+ expect(resolution.lineage).toEqual({+ rootId: "s-parent",+ parentId: "s-parent",+ depth: 1,+ source: "crutch",+ });+ });+});++// ----- the capture boundary -------------------------------------------------++describe("captureSessionLifecycleEvent - sourcing the declaration", () => {+ let vault: string;++ beforeEach(() => {+ vault = join(tmp, "vault");+ mkdirSync(vault, { recursive: true });+ bootstrapBrain(vault);+ });++ test("stamps the payload-declared work id and lane onto the ledger observation", async () => {+ await captureSessionLifecycleEvent(+ vault,+ {+ hook_event_name: "UserPromptSubmit",+ session_id: "c-1",+ cwd: WORKTREE_A,+ work_id: WORK_ID,+ lane_id: LANE_A,+ prompt: "hi",+ },+ { agent: "tester", now: new Date(T0) },+ );+ const entry = readLineageLedger(vault).get("c-1");+ expect(entry?.workId).toBe(WORK_ID);+ expect(entry?.laneId).toBe(LANE_A);+ });++ test("records the declaration as a per-worktree marker", async () => {+ await captureSessionLifecycleEvent(+ vault,+ {+ hook_event_name: "UserPromptSubmit",+ session_id: "c-1",+ cwd: WORKTREE_A,+ work_id: WORK_ID,+ lane_id: LANE_A,+ prompt: "hi",+ },+ { agent: "tester", now: new Date(T0) },+ );+ expect(readWorkIdentityMarker(vault, WORKTREE_A, { nowMs: T0 })).toEqual({+ workId: WORK_ID,+ laneId: LANE_A,+ source: WORK_IDENTITY_SOURCE.marker,+ });+ });++ test("a later session in the same worktree inherits the recorded marker", async () => {+ await captureSessionLifecycleEvent(+ vault,+ {+ hook_event_name: "UserPromptSubmit",+ session_id: "c-1",+ cwd: WORKTREE_A,+ work_id: WORK_ID,+ prompt: "hi",+ },+ { agent: "tester", now: new Date(T0) },+ );+ const result = await captureSessionLifecycleEvent(+ vault,+ { hook_event_name: "UserPromptSubmit", session_id: "c-2", cwd: WORKTREE_A, prompt: "again" },+ { agent: "tester", now: new Date(T0 + CRUTCH_LINK_WINDOW_MS * 5) },+ );+ expect(result.lineage).toEqual({+ rootId: "c-1",+ parentId: "c-1",+ depth: 1,+ source: "identity",+ });+ });++ test("an unrelated session a month later does NOT chain onto the inherited marker", async () => {+ await captureSessionLifecycleEvent(+ vault,+ {+ hook_event_name: "UserPromptSubmit",+ session_id: "c-1",+ cwd: WORKTREE_A,+ work_id: WORK_ID,+ prompt: "hi",+ },+ { agent: "tester", now: new Date(T0) },+ );+ const result = await captureSessionLifecycleEvent(+ vault,+ { hook_event_name: "UserPromptSubmit", session_id: "c-2", cwd: WORKTREE_A, prompt: "again" },+ { agent: "tester", now: new Date(T0 + WORK_IDENTITY_MARKER_MAX_AGE_MS + 1) },+ );+ // A missed stitch is strictly better than a false one: nothing here+ // declared this work, the marker is only what the directory last saw,+ // and it is now older than the rung's bound.+ expect(result.lineage).toBeUndefined();+ });++ test("a payload declaring nothing writes no marker and no identity fields", async () => {+ await captureSessionLifecycleEvent(+ vault,+ { hook_event_name: "UserPromptSubmit", session_id: "c-1", cwd: WORKTREE_A, prompt: "hi" },+ { agent: "tester", now: new Date(T0) },+ );+ expect(readWorkIdentityMarker(vault, WORKTREE_A)).toBeNull();+ const raw = readFileSync(sessionLineageLedgerPath(vault), "utf8").trim();+ expect(raw.includes('"wid"')).toBe(false);+ expect(raw.includes('"lane"')).toBe(false);+ });+});diff --git a/tests/core/brain/marker-kinds.test.ts b/tests/core/brain/marker-kinds.test.tsnew file mode 100644index 00000000..0c26fd79--- /dev/null+++ b/tests/core/brain/marker-kinds.test.ts@@ -0,0 +1,209 @@+/**+ * Grammar coverage for the two capture marker kinds added by+ * "signals that survive" unit 7: `@osb fact` and `@osb skill`.+ *+ * These kinds ride the SAME parser, fence walker and consumed-sentinel+ * skip as `feedback` / `loop` / `set`, so the tests here assert the two+ * surface forms, the required-field contract (which must name the+ * missing field rather than drop the marker silently), and that nothing+ * about a file without the new kinds changes.+ */++import { describe, expect, test } from "bun:test";++import {+ discoverMarkers,+ discoverMarkersDetailed,+ isFactMarker,+ isFeedbackMarker,+ isSkillMarker,+ parseBlockMarker,+ parseInlineMarker,+} from "../../../src/core/brain/inline.ts";++describe("parseInlineMarker fact", () => {+ test("parses topic, principle, a single premise and the derivation level", () => {+ const m = parseInlineMarker(+ `@osb fact topic=deploy-gate principle="ship only when the gate is green" premise=pref-gate level=deduced`,+ 7,+ );+ expect(m).not.toBeNull();+ expect(m!.kind).toBe("fact");+ expect(m!.topic).toBe("deploy-gate");+ expect(m!.principle).toBe("ship only when the gate is green");+ expect(m!.premise).toEqual(["pref-gate"]);+ expect(m!.level).toBe("deduced");+ expect(m!.originLine).toBe(7);+ expect(m!.shape).toBe("inline");+ });++ test("collects repeated premise values in source order", () => {+ const m = parseInlineMarker(+ `@osb fact topic=t principle=p premise=pref-a premise=b level=inferred`,+ 1,+ );+ expect(m!.premise).toEqual(["pref-a", "b"]);+ });++ test("a missing required field rejects the marker and names the field", () => {+ expect(parseInlineMarker(`@osb fact topic=t principle=p premise=pref-a`, 1)).toBeNull();+ const result = discoverMarkersDetailed(`@osb fact topic=t principle=p premise=pref-a\n`);+ expect(result.markers.length).toBe(0);+ expect(result.malformed).toBe(1);+ expect(result.issues.length).toBe(1);+ expect(result.issues[0]!.kind).toBe("fact");+ expect(result.issues[0]!.missingFields).toEqual(["level"]);+ expect(result.issues[0]!.message).toContain("level");+ expect(result.issues[0]!.originLine).toBe(1);+ });++ test("an absent premise is named just like any other required field", () => {+ const result = discoverMarkersDetailed(`@osb fact topic=t principle=p level=deduced\n`);+ expect(result.issues[0]!.missingFields).toEqual(["premise"]);+ expect(result.issues[0]!.message).toContain("premise");+ });++ test("the level value is not vetted by the grammar - the derive path owns it", () => {+ const m = parseInlineMarker(`@osb fact topic=t principle=p premise=pref-a level=guessed`, 1);+ expect(m).not.toBeNull();+ expect(m!.level).toBe("guessed");+ });+});++describe("parseBlockMarker fact", () => {+ test("parses the same field set from the block shape", () => {+ const body = [+ "kind: fact",+ "topic: deploy-gate",+ "principle: ship only when the gate is green",+ "premise: pref-gate",+ "premise: pref-review",+ "level: inferred",+ ].join("\n");+ const m = parseBlockMarker(body, 4);+ expect(m).not.toBeNull();+ expect(m!.kind).toBe("fact");+ expect(m!.topic).toBe("deploy-gate");+ expect(m!.principle).toBe("ship only when the gate is green");+ expect(m!.premise).toEqual(["pref-gate", "pref-review"]);+ expect(m!.level).toBe("inferred");+ expect(m!.shape).toBe("block");+ expect(m!.originLine).toBe(4);+ });++ test("a repeated single-valued required field is ambiguous and rejects", () => {+ const body = [+ "kind: fact",+ "topic: one",+ "topic: two",+ "principle: p",+ "premise: pref-a",+ "level: deduced",+ ].join("\n");+ expect(parseBlockMarker(body, 1)).toBeNull();+ const result = discoverMarkersDetailed(["```osb", body, "```"].join("\n"));+ expect(result.markers.length).toBe(0);+ expect(result.issues.length).toBe(1);+ expect(result.issues[0]!.duplicateFields).toEqual(["topic"]);+ expect(result.issues[0]!.message).toContain("topic");+ });+});++describe("parseInlineMarker skill", () => {+ test("parses name and body", () => {+ const m = parseInlineMarker(+ `@osb skill name="release check" body="run the suite, then the linter"`,+ 3,+ );+ expect(m).not.toBeNull();+ expect(m!.kind).toBe("skill");+ expect(m!.name).toBe("release check");+ expect(m!.body).toBe("run the suite, then the linter");+ expect(m!.shape).toBe("inline");+ });++ test("a missing body rejects the marker and names the field", () => {+ expect(parseInlineMarker(`@osb skill name="release check"`, 1)).toBeNull();+ const result = discoverMarkersDetailed(`@osb skill name="release check"\n`);+ expect(result.issues[0]!.kind).toBe("skill");+ expect(result.issues[0]!.missingFields).toEqual(["body"]);+ expect(result.issues[0]!.message).toContain("body");+ });+});++describe("parseBlockMarker skill", () => {+ test("parses a multi-line body through the block scalar form", () => {+ const body = [+ "kind: skill",+ "name: release check",+ "body: |",+ " run the suite",+ " then the linter",+ ].join("\n");+ const m = parseBlockMarker(body, 1);+ expect(m).not.toBeNull();+ expect(m!.kind).toBe("skill");+ expect(m!.name).toBe("release check");+ expect(m!.body).toBe("run the suite\nthen the linter");+ });+});++describe("type guards for the new kinds", () => {+ test("isFactMarker and isSkillMarker narrow, and neither claims a feedback marker", () => {+ const text = [+ "@osb feedback negative topic=t principle=p",+ "@osb fact topic=ft principle=fp premise=pref-a level=deduced",+ `@osb skill name="release check" body="run the suite"`,+ ].join("\n");+ const markers = discoverMarkers(text);+ expect(markers.length).toBe(3);+ expect(markers.filter(isFeedbackMarker).length).toBe(1);+ const facts = markers.filter(isFactMarker);+ const skills = markers.filter(isSkillMarker);+ expect(facts.length).toBe(1);+ expect(skills.length).toBe(1);+ expect(facts[0]!.premise).toEqual(["pref-a"]);+ expect(skills[0]!.name).toBe("release check");+ });+});++describe("the walker treats the new kinds exactly like the old ones", () => {+ test("a fact marker inside a non-osb fence stays inert", () => {+ const text = [+ "```markdown",+ "@osb fact topic=t principle=p premise=pref-a level=deduced",+ "```",+ ].join("\n");+ expect(discoverMarkers(text).length).toBe(0);+ });++ test("a consumed inline fact marker is skipped on a re-run", () => {+ const consumed = "@osbβ [[pref-t]] fact topic=t principle=p premise=pref-a level=deduced";+ expect(discoverMarkers(consumed).length).toBe(0);+ });++ test("a consumed skill block is skipped on a re-run", () => {+ const text = [+ "```osb-checked",+ "<!-- @osbβ [[prop-declared_marker-release-check-0badc0de]] -->",+ "kind: skill",+ "name: release check",+ "body: run the suite",+ "```",+ ].join("\n");+ expect(discoverMarkers(text).length).toBe(0);+ });++ test("a file with no fact or skill markers reports no issues", () => {+ const text = [+ "# notes",+ "@osb feedback negative topic=t principle=p",+ "@osb loop follow up on the contract",+ "@osb set note=Roadmap field=completion value=65",+ ].join("\n");+ const result = discoverMarkersDetailed(text);+ expect(result.markers.length).toBe(3);+ expect(result.malformed).toBe(0);+ expect(result.issues).toEqual([]);+ });+});diff --git a/tests/core/brain/marker-routing.test.ts b/tests/core/brain/marker-routing.test.tsnew file mode 100644index 00000000..fd2ffad8--- /dev/null+++ b/tests/core/brain/marker-routing.test.ts@@ -0,0 +1,498 @@+/**+ * Routing coverage for the two capture marker kinds added by "signals+ * that survive" unit 7.+ *+ * A `@osb fact` marker lands as an UNCONFIRMED preference through the+ * existing derive-fact path; a `@osb skill` marker lands in the PENDING+ * skill-proposal queue and never in accepted. Both destinations already+ * carry their own review gate, so nothing here asserts new gating - it+ * asserts the marker reaches the gated store, that a failure is named+ * rather than dropped, and that a second scan over the same file is a+ * no-op.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { DEFAULT_BRAIN_CONFIG_YAML } from "../../../src/core/brain/config-template.ts";+import { scanInline } from "../../../src/core/brain/inline-scan.ts";+import { brainDirs, preferencePath } from "../../../src/core/brain/paths.ts";+import { parsePreference, writePreference } from "../../../src/core/brain/preference.ts";+import { deriveFact } from "../../../src/core/brain/derived-fact.ts";+import {+ acceptSkillProposal,+ listPendingSkillProposals,+ rejectSkillProposal,+} from "../../../src/core/brain/skill-proposals.ts";+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";++let vault: string;++const NOW = new Date("2026-07-27T09:00:00Z");++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-marker-routing-"));+ const dirs = brainDirs(vault);+ for (const dir of [+ dirs.brain,+ dirs.inbox,+ dirs.processed,+ dirs.preferences,+ dirs.retired,+ dirs.log,+ dirs.snapshots,+ ]) {+ mkdirSync(dir, { recursive: true });+ }+ atomicWriteFileSync(+ join(dirs.brain, "_brain.yaml"),+ `${DEFAULT_BRAIN_CONFIG_YAML}\nnotes:\n read_paths:\n - Daily\n`,+ );+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+});++function writeNote(rel: string, content: string): string {+ const path = join(vault, rel);+ mkdirSync(join(path, ".."), { recursive: true });+ atomicWriteFileSync(path, content);+ return path;+}++function seedPremise(slug: string): void {+ writePreference(vault, {+ slug,+ topic: slug,+ principle: `premise ${slug}`,+ created_at: "2026-07-01T00:00:00Z",+ unconfirmed_until: "2026-08-01T00:00:00Z",+ status: "confirmed",+ evidenced_by: [],+ });+}++function acceptedProposalCount(): number {+ const dir = join(vault, "Brain", "skill-proposals", "accepted");+ if (!existsSync(dir)) return 0;+ return readdirSync(dir).filter((name) => name.endsWith(".md")).length;+}++describe("fact markers route to an unconfirmed preference", () => {+ test("a complete fact marker writes the preference and consumes the marker", async () => {+ seedPremise("gate-green");+ const note = writeNote(+ "Daily/2026-07-27.md",+ `@osb fact topic="deploy gate" principle="ship only when the gate is green" premise=gate-green level=deduced\n`,+ );++ const result = await scanInline(vault, { agent: "tester", now: NOW });++ expect(result.errors).toEqual([]);+ expect(result.facts).toBe(1);++ const path = preferencePath(vault, "deploy-gate");+ expect(existsSync(path)).toBe(true);+ const pref = parsePreference(path);+ expect(pref.status).toBe("unconfirmed");+ expect(pref.topic).toBe("deploy gate");+ expect(pref.evidenced_by).toEqual(["[[pref-gate-green]]"]);++ expect(readFileSync(note, "utf8")).toContain("@osbβ [[pref-deploy-gate]]");+ });++ test("an unresolvable premise is an explicit named error and writes nothing", async () => {+ writeNote("Daily/2026-07-27.md", `@osb fact topic=t principle=p premise=nope level=deduced\n`);++ const result = await scanInline(vault, { agent: "tester", now: NOW });++ expect(result.facts).toBe(0);+ expect(result.errors.length).toBe(1);+ expect(result.errors[0]!.message).toContain("nope");+ expect(existsSync(preferencePath(vault, "t"))).toBe(false);+ });++ test("a missing required field is reported as an error naming the field", async () => {+ const note = writeNote("Daily/2026-07-27.md", `@osb fact topic=t principle=p premise=x\n`);++ const result = await scanInline(vault, { agent: "tester", now: NOW });++ expect(result.facts).toBe(0);+ expect(result.errors.length).toBe(1);+ expect(result.errors[0]!.message).toContain("level");+ // Unconsumed: an operator can fix the marker and rescan.+ expect(readFileSync(note, "utf8")).not.toContain("@osbβ");+ });++ test("a block fact marker routes exactly like the inline shape", async () => {+ seedPremise("gate-green");+ writeNote(+ "Daily/2026-07-27.md",+ [+ "```osb",+ "kind: fact",+ "topic: block fact",+ "principle: derived from the gate rule",+ "premise: gate-green",+ "level: inferred",+ "```",+ "",+ ].join("\n"),+ );++ const result = await scanInline(vault, { agent: "tester", now: NOW });++ expect(result.errors).toEqual([]);+ expect(result.facts).toBe(1);+ expect(existsSync(preferencePath(vault, "block-fact"))).toBe(true);+ });+});++describe("skill markers route to the pending proposal queue", () => {+ test("a complete skill marker drafts a pending proposal and never an accepted one", async () => {+ const note = writeNote(+ "Daily/2026-07-27.md",+ `@osb skill name="release check" body="run the suite, then the linter"\n`,+ );++ const result = await scanInline(vault, { agent: "tester", now: NOW });++ expect(result.errors).toEqual([]);+ expect(result.skills).toBe(1);++ const pending = listPendingSkillProposals(vault);+ expect(pending.length).toBe(1);+ expect(pending[0]!.patternKind).toBe("declared_marker");+ expect(pending[0]!.status).toBe("pending");+ expect(acceptedProposalCount()).toBe(0);++ expect(readFileSync(note, "utf8")).toContain(`@osbβ [[${pending[0]!.id}]]`);+ });++ test("a block skill marker carries its multi-line body into the proposal", async () => {+ writeNote(+ "Daily/2026-07-27.md",+ [+ "```osb",+ "kind: skill",+ "name: release check",+ "body: |",+ " run the suite",+ " then the linter",+ "```",+ "",+ ].join("\n"),+ );++ const result = await scanInline(vault, { agent: "tester", now: NOW });+ expect(result.skills).toBe(1);++ const pending = listPendingSkillProposals(vault);+ expect(pending.length).toBe(1);+ const body = readFileSync(+ join(vault, "Brain", "skill-proposals", "pending", `prop-${pending[0]!.slug}.md`),+ "utf8",+ );+ expect(body).toContain("## Suggested skill body");+ expect(body).toContain("run the suite");+ expect(body).toContain("then the linter");+ });++ test("a missing required field is reported as an error naming the field", async () => {+ writeNote("Daily/2026-07-27.md", `@osb skill name="release check"\n`);++ const result = await scanInline(vault, { agent: "tester", now: NOW });++ expect(result.skills).toBe(0);+ expect(result.errors.length).toBe(1);+ expect(result.errors[0]!.message).toContain("body");+ expect(listPendingSkillProposals(vault).length).toBe(0);+ });++ test("two declarations of the same skill name yield one proposal, both consumed", async () => {+ const note = writeNote(+ "Daily/2026-07-27.md",+ [+ `@osb skill name="release check" body="run the suite"`,+ `@osb skill name="Release Check" body="run the suite, then the linter"`,+ "",+ ].join("\n"),+ );++ const result = await scanInline(vault, { agent: "tester", now: NOW });++ expect(result.errors).toEqual([]);+ // One draft was created; the second declaration resolved to it.+ expect(result.skills).toBe(1);+ const pending = listPendingSkillProposals(vault);+ expect(pending.length).toBe(1);+ const after = readFileSync(note, "utf8");+ expect(after.split(`@osbβ [[${pending[0]!.id}]]`).length - 1).toBe(2);+ });+});++describe("a destination that refuses a marker leaves it live and says why", () => {+ test("a fact whose topic collides with an existing preference is an explicit error", async () => {+ seedPremise("gate-green");+ seedPremise("deploy-gate");+ const note = writeNote(+ "Daily/2026-07-27.md",+ `@osb fact topic="deploy gate" principle="ship only when green" premise=gate-green level=deduced\n`,+ );+ const before = readFileSync(preferencePath(vault, "deploy-gate"), "utf8");++ const result = await scanInline(vault, { agent: "tester", now: NOW });++ expect(result.facts).toBe(0);+ expect(result.errors.length).toBe(1);+ expect(result.errors[0]!.message).toContain("fact marker at line 1 was refused");+ // The existing rule is untouched and the marker stays live for a retry.+ expect(readFileSync(preferencePath(vault, "deploy-gate"), "utf8")).toBe(before);+ expect(readFileSync(note, "utf8")).not.toContain("@osbβ");+ });+});++describe("re-running the scan is idempotent for the new kinds", () => {+ test("a second scan over the same file writes nothing more", async () => {+ seedPremise("gate-green");+ const note = writeNote(+ "Daily/2026-07-27.md",+ [+ `@osb fact topic="deploy gate" principle="ship only when green" premise=gate-green level=deduced`,+ `@osb skill name="release check" body="run the suite"`,+ "",+ ].join("\n"),+ );++ const first = await scanInline(vault, { agent: "tester", now: NOW });+ expect(first.facts).toBe(1);+ expect(first.skills).toBe(1);+ const afterFirst = readFileSync(note, "utf8");++ const second = await scanInline(vault, { agent: "tester", now: NOW });+ expect(second.facts).toBe(0);+ expect(second.skills).toBe(0);+ expect(second.errors).toEqual([]);+ expect(readFileSync(note, "utf8")).toBe(afterFirst);+ expect(listPendingSkillProposals(vault).length).toBe(1);+ expect(readdirSync(brainDirs(vault).preferences).filter((n) => n.endsWith(".md")).length).toBe(+ 2,+ );+ });+});++describe("a file with no markers of the new kinds is untouched by the new routing", () => {+ test("a feedback-only file still produces exactly one signal and nothing else", async () => {+ const note = writeNote(+ "Daily/2026-07-27.md",+ "@osb feedback negative topic=mocking principle=no-db-mocks\n",+ );++ const result = await scanInline(vault, { agent: "tester", now: NOW });++ expect(result.created).toBe(1);+ expect(result.found).toBe(1);+ expect(result.facts).toBe(0);+ expect(result.skills).toBe(0);+ expect(result.errors).toEqual([]);+ expect(readFileSync(note, "utf8")).toContain("@osbβ [[sig-");+ expect(readdirSync(brainDirs(vault).preferences).filter((n) => n.endsWith(".md")).length).toBe(+ 0,+ );+ expect(listPendingSkillProposals(vault).length).toBe(0);+ expect(acceptedProposalCount()).toBe(0);+ });+});++describe("a dry run previews the routed kinds instead of hiding them", () => {+ test("routed markers are counted and reported, and nothing is written", async () => {+ seedPremise("gate-green");+ const note = writeNote(+ "Daily/2026-07-27.md",+ [+ `@osb fact topic="deploy gate" principle="ship only when green" premise=gate-green level=deduced`,+ `@osb skill name="release check" body="run the suite"`,+ "",+ ].join("\n"),+ );+ const before = readFileSync(note, "utf8");++ const dry = await scanInline(vault, { agent: "tester", now: NOW, dryRun: true });++ expect(dry.facts).toBe(1);+ expect(dry.skills).toBe(1);+ expect(dry.found).toBe(2);+ expect(dry.filesWithMarkers).toEqual([{ path: note, markers: 2 }]);+ expect(dry.errors).toEqual([]);++ // Nothing on disk moved: no preference, no proposal, no rewrite.+ expect(existsSync(preferencePath(vault, "deploy-gate"))).toBe(false);+ expect(listPendingSkillProposals(vault).length).toBe(0);+ expect(readFileSync(note, "utf8")).toBe(before);+ });++ test("a dry run refuses exactly the markers a real run refuses", async () => {+ seedPremise("gate-green");+ seedPremise("taken-topic");+ const note = writeNote(+ "Daily/2026-07-27.md",+ [+ // Unresolvable premise.+ `@osb fact topic=t1 principle=p premise=nope level=deduced`,+ // Derivation level outside the destination's vocabulary.+ `@osb fact topic=t2 principle=p premise=gate-green level=stated`,+ // The conclusion's slug is already taken by an existing preference.+ `@osb fact topic="taken topic" principle=p premise=gate-green level=deduced`,+ "",+ ].join("\n"),+ );+ const before = readFileSync(note, "utf8");++ const dry = await scanInline(vault, { agent: "tester", now: NOW, dryRun: true });+ const real = await scanInline(vault, { agent: "tester", now: NOW });++ expect(dry.facts).toBe(0);+ expect(real.facts).toBe(0);+ expect(dry.errors.length).toBe(3);+ expect(real.errors.length).toBe(dry.errors.length);+ // Same markers, named the same way: the preview's preconditions have+ // not drifted from the ones the writer enforces.+ expect(dry.errors.map((e) => e.message.split(":")[0])).toEqual(+ real.errors.map((e) => e.message.split(":")[0]),+ );+ expect(dry.errors.map((e) => e.path)).toEqual(real.errors.map((e) => e.path));+ expect(dry.errors[0]!.message).toContain("nope");+ expect(dry.errors[1]!.message).toContain("stated");+ expect(readFileSync(note, "utf8")).toBe(before);+ });++ test("a dry run reports a declaration the queue would decline", async () => {+ writeNote("Daily/2026-07-26.md", `@osb skill name="release check" body="run the suite"\n`);+ expect((await scanInline(vault, { agent: "tester", now: NOW })).skills).toBe(1);+ rejectSkillProposal(vault, listPendingSkillProposals(vault)[0]!.slug, {+ note: "not a skill",+ now: NOW,+ });++ const note = writeNote(+ "Daily/2026-07-27.md",+ `@osb skill name="release check" body="a completely different, newer body"\n`,+ );+ const before = readFileSync(note, "utf8");++ const dry = await scanInline(vault, { agent: "tester", now: NOW, dryRun: true });++ expect(dry.skills).toBe(0);+ expect(dry.suppressed).toBe(1);+ expect(dry.errors.length).toBe(1);+ expect(readFileSync(note, "utf8")).toBe(before);+ });+});++describe("a re-declared skill on a reviewed name is a named outcome, never a silent drop", () => {+ test("a rejected name is reported, counted, and leaves the marker live", async () => {+ writeNote("Daily/2026-07-26.md", `@osb skill name="release check" body="run the suite"\n`);+ await scanInline(vault, { agent: "tester", now: NOW });+ rejectSkillProposal(vault, listPendingSkillProposals(vault)[0]!.slug, {+ note: "not a skill",+ now: NOW,+ });++ const note = writeNote(+ "Daily/2026-07-27.md",+ `@osb skill name="release check" body="a completely different, newer body"\n`,+ );++ const result = await scanInline(vault, { agent: "tester", now: NOW });++ expect(result.skills).toBe(0);+ expect(result.suppressed).toBe(1);+ expect(result.errors.length).toBe(1);+ expect(result.errors[0]!.message).toContain("skill marker at line 1 was not consumed");+ expect(result.errors[0]!.message).toContain("rejected");+ // The marker is the only copy of the declared body: it stays live and+ // never points at the rejected file.+ expect(readFileSync(note, "utf8")).not.toContain("@osbβ");+ expect(readFileSync(note, "utf8")).toContain("a completely different, newer body");+ expect(listPendingSkillProposals(vault).length).toBe(0);+ });++ test("an accepted name is reported the same way", async () => {+ writeNote("Daily/2026-07-26.md", `@osb skill name="release check" body="run the suite"\n`);+ await scanInline(vault, { agent: "tester", now: NOW });+ acceptSkillProposal(vault, listPendingSkillProposals(vault)[0]!.slug, { now: NOW });++ const note = writeNote(+ "Daily/2026-07-27.md",+ `@osb skill name="release check" body="a completely different, newer body"\n`,+ );++ const result = await scanInline(vault, { agent: "tester", now: NOW });++ expect(result.suppressed).toBe(1);+ expect(result.errors.length).toBe(1);+ expect(result.errors[0]!.message).toContain("accepted");+ expect(readFileSync(note, "utf8")).not.toContain("@osbβ");+ });++ test("a second declaration of a still-pending name stays benign dedup", async () => {+ writeNote("Daily/2026-07-26.md", `@osb skill name="release check" body="run the suite"\n`);+ await scanInline(vault, { agent: "tester", now: NOW });++ const note = writeNote(+ "Daily/2026-07-27.md",+ `@osb skill name="release check" body="run the suite"\n`,+ );++ const result = await scanInline(vault, { agent: "tester", now: NOW });++ expect(result.suppressed).toBe(0);+ expect(result.errors).toEqual([]);+ expect(result.skills).toBe(0);+ expect(listPendingSkillProposals(vault).length).toBe(1);+ expect(readFileSync(note, "utf8")).toContain("@osbβ");+ });+});++describe("a file whose only markers are routed still appears in the report", () => {+ test("filesWithMarkers names it and `found` counts its markers", async () => {+ seedPremise("gate-green");+ const note = writeNote(+ "Daily/2026-07-27.md",+ [+ `@osb fact topic="deploy gate" principle="ship only when green" premise=gate-green level=deduced`,+ `@osb skill name="release check" body="run the suite"`,+ "",+ ].join("\n"),+ );++ const result = await scanInline(vault, { agent: "tester", now: NOW });++ expect(result.found).toBe(2);+ expect(result.filesWithMarkers).toEqual([{ path: note, markers: 2 }]);+ });+});++describe("the fact route reads its outcome off the destination's contract", () => {+ test("DeriveFactResult carries only the id", () => {+ seedPremise("gate-green");+ const result = deriveFact(+ vault,+ {+ slug: "census-fact",+ topic: "census fact",+ principle: "p",+ premises: ["gate-green"],+ level: "deduced",+ },+ { now: NOW },+ );+ // `routeFactMarker` concludes "created" from the fact that deriveFact+ // has no branch resolving to an artifact it did not write. The day it+ // reports what it did, this census fails and that field must be read.+ expect(Object.keys(result).toSorted()).toEqual(["id"]);+ });+});diff --git a/tests/core/brain/parse-error-path-field.test.ts b/tests/core/brain/parse-error-path-field.test.tsnew file mode 100644index 00000000..681d3017--- /dev/null+++ b/tests/core/brain/parse-error-path-field.test.ts@@ -0,0 +1,336 @@+/**+ * A parse failure carries its file as a field, not inside its prose+ * (signals-that-survive, task 2).+ *+ * `o2b brain doctor` renders `<code>: <message> (<path>)` β the path is+ * appended by the renderer from the finding's structured `path` field.+ * The preference / retired parsers used to embed the same path inside+ * the message as well, so every parse-error line named the file twice.+ *+ * The fix is a typed error that carries `path` structurally and exposes+ * the location-free prose as `detail`, which is what the doctor reports.+ * The `message` a bare caller reads is still composed through ONE shared+ * formatter ({@link withLocation}), so no surface that prints+ * `(exc as Error).message` loses the location.+ *+ * Every parse-error code the doctor can classify is pinned here β the+ * two `*-missing-field` codes and the two `*-invalid` codes β because+ * the classification is a regex over the message, and shortening the+ * message is exactly the change that could break it.+ */++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 { DEFAULT_BRAIN_CONFIG_YAML } from "../../../src/core/brain/config-template.ts";+import { runDoctor } from "../../../src/core/brain/doctor.ts";+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";+import { BrainParseError, withLocation } from "../../../src/core/brain/parse-error.ts";+import { brainConfigPath, brainDirs } from "../../../src/core/brain/paths.ts";+import {+ BrainStatusFolderMismatchError,+ parsePreference,+ parseRetired,+} from "../../../src/core/brain/preference.ts";+import type { DoctorIssue } from "../../../src/core/brain/types.ts";++let tmp: string;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-parse-error-"));+ const dirs = brainDirs(tmp);+ for (const d of [+ dirs.brain,+ dirs.inbox,+ dirs.processed,+ dirs.preferences,+ dirs.retired,+ dirs.log,+ dirs.snapshots,+ ]) {+ mkdirSync(d, { recursive: true });+ }+ atomicWriteFileSync(brainConfigPath(tmp), DEFAULT_BRAIN_CONFIG_YAML);+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++/** Write `lines` as a Brain artifact at `path` and return the path. */+function seed(path: string, lines: ReadonlyArray<string>): string {+ writeFileSync(path, [...lines, ""].join("\n"), "utf8");+ return path;+}++/** A preference file whose frontmatter omits `created_at`. */+function seedPreferenceMissingField(): string {+ return seed(join(brainDirs(tmp).preferences, "pref-no-created-at.md"), [+ "---",+ "kind: brain-preference",+ "id: pref-no-created-at",+ "_confirmed_at: null",+ "unconfirmed_until: 2026-05-28T10:42:00Z",+ "tags: [brain, brain/preference]",+ "topic: broken",+ "_status: unconfirmed",+ "principle: A rule with no birthday",+ "_evidenced_by: []",+ "---",+ ]);+}++/** A preference file whose `_confidence` is outside the enum. */+function seedPreferenceInvalid(): string {+ return seed(join(brainDirs(tmp).preferences, "pref-bad-confidence.md"), [+ "---",+ "kind: brain-preference",+ "id: pref-bad-confidence",+ "created_at: 2026-05-14T10:42:00Z",+ "_confirmed_at: null",+ "unconfirmed_until: 2026-05-28T10:42:00Z",+ "tags: [brain, brain/preference]",+ "topic: broken",+ "_status: unconfirmed",+ "principle: A rule with an unknown confidence band",+ "_evidenced_by: []",+ "_confidence: hilarious",+ "---",+ ]);+}++/** A retired file whose frontmatter omits `retired_at`. */+function seedRetiredMissingField(): string {+ return seed(join(brainDirs(tmp).retired, "ret-no-retired-at.md"), [+ "---",+ "kind: brain-retired",+ "id: ret-no-retired-at",+ "created_at: 2026-05-14T10:42:00Z",+ "tags: [brain, brain/retired]",+ "topic: broken",+ "_status: retired",+ "retired_reason: superseded",+ "retired_by: [[Brain/log/2026-05-14]]",+ "principle: A rule with no retirement date",+ "---",+ ]);+}++/** A retired file whose `retired_reason` is outside the enum. */+function seedRetiredInvalid(): string {+ return seed(join(brainDirs(tmp).retired, "ret-bad-reason.md"), [+ "---",+ "kind: brain-retired",+ "id: ret-bad-reason",+ "created_at: 2026-05-14T10:42:00Z",+ "retired_at: 2026-06-14T10:42:00Z",+ "tags: [brain, brain/retired]",+ "topic: broken",+ "_status: retired",+ "retired_reason: hilarious",+ "retired_by: [[Brain/log/2026-06-14]]",+ "principle: A rule retired for an unknown reason",+ "---",+ ]);+}++/** A preference file whose optional `_applied_count` is not a number. */+function seedPreferenceBadAppliedCount(): string {+ return seed(join(brainDirs(tmp).preferences, "pref-bad-applied-count.md"), [+ "---",+ "kind: brain-preference",+ "id: pref-bad-applied-count",+ "created_at: 2026-05-14T10:42:00Z",+ "_confirmed_at: null",+ "unconfirmed_until: 2026-05-28T10:42:00Z",+ "tags: [brain, brain/preference]",+ "topic: broken",+ "_status: unconfirmed",+ "principle: A rule with an uncountable apply count",+ "_evidenced_by: []",+ "_applied_count: abc",+ "---",+ ]);+}++/** A preference file filed under `preferences/` with `_status: retired`. */+function seedStatusFolderMismatch(): string {+ return seed(join(brainDirs(tmp).preferences, "pref-mismatch.md"), [+ "---",+ "kind: brain-preference",+ "id: pref-mismatch",+ "created_at: 2026-05-14T10:42:00Z",+ "_confirmed_at: null",+ "unconfirmed_until: 2026-05-28T10:42:00Z",+ "tags: [brain, brain/preference]",+ "topic: broken",+ "_status: retired",+ "principle: A rule filed under the wrong folder",+ "_evidenced_by: []",+ "---",+ ]);+}++/** The single doctor finding carrying `code`. */+function finding(issues: ReadonlyArray<DoctorIssue>, code: string): DoctorIssue {+ const hits = issues.filter((i) => i.code === code);+ expect(hits).toHaveLength(1);+ return hits[0]!;+}++describe("the typed parse error carries the path as a field", () => {+ test("a missing required field throws BrainParseError with path and detail as fields", () => {+ const path = seedPreferenceMissingField();+ expect(() => parsePreference(path)).toThrow(BrainParseError);+ try {+ parsePreference(path);+ throw new Error("parsePreference did not throw");+ } catch (err) {+ expect(err).toBeInstanceOf(BrainParseError);+ const e = err as BrainParseError;+ expect(e.path).toBe(path);+ expect(e.detail).toBe("preference missing field: created_at");+ expect(e.detail).not.toContain(path);+ }+ });++ test("a caller that surfaces the message directly still receives the path", () => {+ const path = seedPreferenceInvalid();+ let surfaced = "";+ try {+ parsePreference(path);+ } catch (exc) {+ // Exactly what `o2b brain reject`, `brain merge` and the pin path do.+ surfaced = (exc as Error).message;+ }+ expect(surfaced).toContain(path);+ expect(surfaced).toBe(+ withLocation(+ "preference field 'confidence' must be one of low, medium, high; got \"hilarious\"",+ path,+ ),+ );+ });++ test("the located message is composed by the one shared formatter", () => {+ const path = seedRetiredInvalid();+ try {+ parseRetired(path);+ throw new Error("parseRetired did not throw");+ } catch (err) {+ const e = err as BrainParseError;+ expect(e.message).toBe(withLocation(e.detail, e.path));+ }+ });++ test("the status-folder mismatch keeps its own fields and its bare detail", () => {+ const path = seedStatusFolderMismatch();+ try {+ parsePreference(path);+ throw new Error("parsePreference did not throw");+ } catch (err) {+ expect(err).toBeInstanceOf(BrainStatusFolderMismatchError);+ expect(err).toBeInstanceOf(BrainParseError);+ const e = err as BrainStatusFolderMismatchError;+ expect(e.path).toBe(path);+ expect(e.status).toBe("retired");+ expect(e.folder).toBe("preferences");+ expect(e.detail).not.toContain(path);+ expect(e.message).toContain(path);+ }+ });+});++describe("what the composed sentence promises, precisely", () => {+ test("the status-folder mismatch sentence keeps its historical byte layout", () => {+ const path = seedStatusFolderMismatch();+ let surfaced = "";+ try {+ parsePreference(path);+ } catch (exc) {+ // `o2b brain reject` prints this string bare; an operator may match on it.+ surfaced = (exc as Error).message;+ }+ expect(surfaced).toBe(+ "preference file frontmatter status does not match preferences/ folder " ++ `(path=${path}, status=retired, folder=preferences)`,+ );+ });++ test("an optional-field failure that carried no location now carries one", () => {+ const path = seedPreferenceBadAppliedCount();+ try {+ parsePreference(path);+ throw new Error("parsePreference did not throw");+ } catch (err) {+ expect(err).toBeInstanceOf(BrainParseError);+ const e = err as BrainParseError;+ expect(e.detail).toBe(+ "preference field 'applied_count' must be a finite number; got \"abc\"",+ );+ expect(e.path).toBe(path);+ expect(e.message).toBe(withLocation(e.detail, path));+ }+ });+});++describe("the doctor reports the path once, as a field", () => {+ test("preference-missing-field names the file in `path` and not in `message`", () => {+ const path = seedPreferenceMissingField();+ const issue = finding(runDoctor(tmp).errors, "preference-missing-field");+ expect(issue.path).toBe(path);+ expect(issue.message).toBe("preference missing field: created_at");+ expect(issue.message).not.toContain(path);+ });++ test("preference-invalid names the file in `path` and not in `message`", () => {+ const path = seedPreferenceInvalid();+ const issue = finding(runDoctor(tmp).errors, "preference-invalid");+ expect(issue.path).toBe(path);+ expect(issue.message).not.toContain(path);+ });++ test("retired-missing-field names the file in `path` and not in `message`", () => {+ const path = seedRetiredMissingField();+ const issue = finding(runDoctor(tmp).errors, "retired-missing-field");+ expect(issue.path).toBe(path);+ expect(issue.message).toBe("preference missing field: retired_at");+ expect(issue.message).not.toContain(path);+ });++ test("retired-invalid names the file in `path` and not in `message`", () => {+ const path = seedRetiredInvalid();+ const issue = finding(runDoctor(tmp).errors, "retired-invalid");+ expect(issue.path).toBe(path);+ expect(issue.message).not.toContain(path);+ });++ test("status-folder-mismatch names the file in `path` and not in `message`", () => {+ const path = seedStatusFolderMismatch();+ const issue = finding(runDoctor(tmp).warnings, "status-folder-mismatch");+ expect(issue.path).toBe(path);+ expect(issue.message).not.toContain(path);+ // The structural facts the class carries stay in the sentence: they+ // have no field of their own on a `DoctorIssue`.+ expect(issue.message).toContain("status=retired");+ expect(issue.message).toContain("folder=preferences");+ });++ test("all four parse-error codes still classify from the shortened message", () => {+ seedPreferenceMissingField();+ seedPreferenceInvalid();+ seedRetiredMissingField();+ seedRetiredInvalid();+ const codes = runDoctor(tmp)+ .errors.map((e) => e.code)+ .toSorted();+ expect(codes).toEqual([+ "preference-invalid",+ "preference-missing-field",+ "retired-invalid",+ "retired-missing-field",+ ]);+ });+});diff --git a/tests/core/brain/query-demand.test.ts b/tests/core/brain/query-demand.test.tsindex d8e5d1f4..de068614 100644--- a/tests/core/brain/query-demand.test.ts+++ b/tests/core/brain/query-demand.test.ts@@ -6,6 +6,8 @@ import { join } from "node:path";import { queryDemandLogPath } from "../../../src/core/brain/paths.ts";import {DEMAND_LOG_MAX_BYTES,+ DEMAND_MAX_TERMS_PER_RECORD,+ DEMAND_TERM_MAX_LEN,aggregateQueryDemand,normalizeQueryTerms,readQueryDemand,@@ -239,9 +241,26 @@ describe("aggregateQueryDemand", () => {describe("rolling cap", () => {test("compacts the log once it exceeds the byte budget", () => {const path = queryDemandLogPath(vault);- // Each record ~ small; write enough to blow past the 1MB cap.- const terms = ["compaction", "stress", "budget"];- for (let i = 0; i < 20_000; i++) {+ // Reach the 1MB cap with FAT records rather than many small ones: the+ // branch under test is byte-budget-driven, so a record built out to the+ // documented per-record maximum (DEMAND_MAX_TERMS_PER_RECORD terms of+ // DEMAND_TERM_MAX_LEN chars) crosses the same threshold in ~1k appends+ // instead of ~20k. Each append takes a lockfile, so append count β not+ // byte count β was the runtime, and 20k of them ran ~4.7s against the+ // 5s limit and flaked under parallel load.+ const terms = Array.from({ length: DEMAND_MAX_TERMS_PER_RECORD }, (_, i) =>+ // Pure-alpha so sanitizeTerms keeps it: a long letters+digits token is+ // dropped as secret-shaped.+ `compaction${String.fromCharCode(97 + i)}`.padEnd(DEMAND_TERM_MAX_LEN, "x"),+ );+ const bucketKey = [...terms].toSorted().join(" ");+ const recordBytes = Buffer.byteLength(+ JSON.stringify({ ts: "2026-07-01T00:00:00.000Z", terms, results: 0, coverage: 0.1 }) + "\n",+ "utf8",+ );+ // Overshoot the cap so compaction is provably triggered, not borderline.+ const appends = Math.ceil((DEMAND_LOG_MAX_BYTES / recordBytes) * 1.2);+ for (let i = 0; i < appends; i++) {recordQueryDemand(vault, {terms,resultCount: 0,@@ -251,9 +270,11 @@ describe("rolling cap", () => {}const size = statSync(path).size;expect(size).toBeLessThanOrEqual(DEMAND_LOG_MAX_BYTES);- // Compaction keeps recent lines readable and parseable.+ // Compaction actually ran: fewer lines survive than were appended.const records = readQueryDemand(vault);expect(records.length).toBeGreaterThan(0);- expect(records.every((r) => r.terms.join(" ") === "budget compaction stress")).toBe(true);+ expect(records.length).toBeLessThan(appends);+ // Compaction keeps recent lines readable and parseable.+ expect(records.every((r) => r.terms.join(" ") === bucketKey)).toBe(true);});});diff --git a/tests/core/brain/response-shape-write-paths.test.ts b/tests/core/brain/response-shape-write-paths.test.tsnew file mode 100644index 00000000..792a869e--- /dev/null+++ b/tests/core/brain/response-shape-write-paths.test.ts@@ -0,0 +1,341 @@+/**+ * Response-shape validation at the ingress of the three model-authored write+ * paths (signals-that-survive, unit 8, t_80b01448): source distillation,+ * fact derivation, and research synthesis.+ *+ * Every case here asserts the same contract from a different angle: the+ * payload is checked against its frozen descriptor BEFORE any normalization,+ * a violation is a named error rather than a coercion, and nothing at all is+ * written when any item of a batch is malformed.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";+import { join } from "node:path";+import { tmpdir } from "node:os";++import { bootstrapBrain } from "../../../src/core/brain/init.ts";+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";+import {+ BRAIN_DISTILLATIONS_REL,+ BRAIN_REPORTS_REL,+ brainConfigPath,+} from "../../../src/core/brain/paths.ts";+import { writePreference } from "../../../src/core/brain/preference.ts";+import {+ ResponseShapeError,+ SHAPE_VIOLATION_CODES,+} from "../../../src/core/brain/response-shape.ts";+import { parseDistillClaims } from "../../../src/core/brain/distill/distill-source.ts";+import { parseDeriveFactInput } from "../../../src/core/brain/derived-fact.ts";+import { parseResearchReportInput } from "../../../src/core/brain/research/research.ts";+import { DISTILL_TOOLS } from "../../../src/mcp/brain/distill-tools.ts";+import { DERIVE_TOOLS } from "../../../src/mcp/brain/derive-tools.ts";+import { RESEARCH_TOOLS } from "../../../src/mcp/brain/research-tools.ts";+import { MCPError } from "../../../src/mcp/protocol.ts";+import type { ServerContext } from "../../../src/mcp/tool-contract.ts";++let vault: string;+let configHome: string;+let ctx: ServerContext;++const distillHandler = DISTILL_TOOLS[0]!.handler;+const deriveHandler = DERIVE_TOOLS[0]!.handler;+const researchHandler = RESEARCH_TOOLS[0]!.handler;++const SOURCE_PATH = "Articles/src.md";++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-response-shape-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-response-shape-cfg-"));+ const configPath = join(configHome, "config.yaml");+ atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);+ bootstrapBrain(vault, { configPath });+ mkdirSync(join(vault, "Articles"), { recursive: true });+ writeFileSync(join(vault, SOURCE_PATH), "# Src\n\nBody.\n", "utf8");+ ctx = { vault, configPath, repoRoot: null };+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++/** Vault-relative directory listing, empty when the directory was never made. */+function listing(relativeDir: string): string[] {+ const abs = join(vault, relativeDir);+ return existsSync(abs) ? readdirSync(abs) : [];+}++function enableDerivation(): void {+ writeFileSync(+ brainConfigPath(vault),+ "schema_version: 1\nguardrails:\n derived_fact_synthesis: true\n",+ );+}++function seedPremise(slug: string): void {+ writePreference(vault, {+ slug,+ topic: slug,+ principle: `premise ${slug}`,+ created_at: "2026-06-01T00:00:00Z",+ unconfirmed_until: "2026-07-01T00:00:00Z",+ status: "confirmed",+ evidenced_by: [],+ });+}++describe("distill claims ingress", () => {+ test("a non-string claim text is a shape violation, never coerced to empty text", () => {+ let caught: unknown;+ try {+ parseDistillClaims([{ text: "first" }, { text: 42 }]);+ } catch (err) {+ caught = err;+ }+ expect(caught).toBeInstanceOf(ResponseShapeError);+ const err = caught as ResponseShapeError;+ expect(err.code).toBe(SHAPE_VIOLATION_CODES.typeMismatch);+ expect(err.path).toBe("$[1].text");+ });++ test("a conforming payload normalizes as before", () => {+ expect(parseDistillClaims([{ text: "a", block: "^abc" }, { text: "b" }])).toEqual([+ { text: "a", block: "abc" },+ { text: "b" },+ ]);+ });++ test("a malformed third claim writes nothing at all", async () => {+ await expect(+ distillHandler(ctx, {+ source_path: SOURCE_PATH,+ claims: [{ text: "one" }, { text: "two" }, { block: "^abc" }, { text: "four" }],+ }),+ ).rejects.toThrow(MCPError);+ expect(listing(BRAIN_DISTILLATIONS_REL)).toEqual([]);+ });++ test("a well-formed batch still writes its page", async () => {+ const res = (await distillHandler(ctx, {+ source_path: SOURCE_PATH,+ claims: [{ text: "one" }, { text: "two", block: "^abc" }],+ })) as { claim_count: number };+ expect(res.claim_count).toBe(2);+ expect(listing(BRAIN_DISTILLATIONS_REL)).toHaveLength(1);+ });+});++describe("derived-fact ingress", () => {+ const INPUT = {+ slug: "derived-1",+ topic: "derived",+ principle: "Therefore C",+ premises: ["pref-a"],+ level: "deduced",+ };++ test("a non-string premise is a shape violation naming its index", () => {+ let caught: unknown;+ try {+ parseDeriveFactInput({ ...INPUT, premises: ["pref-a", 7] });+ } catch (err) {+ caught = err;+ }+ expect(caught).toBeInstanceOf(ResponseShapeError);+ expect((caught as ResponseShapeError).path).toBe("$.premises[1]");+ });++ test("a missing required key is refused before the premise lookup", () => {+ let caught: unknown;+ try {+ parseDeriveFactInput({ topic: "t", principle: "p", premises: ["pref-a"], level: "deduced" });+ } catch (err) {+ caught = err;+ }+ expect(caught).toBeInstanceOf(ResponseShapeError);+ expect((caught as ResponseShapeError).code).toBe(SHAPE_VIOLATION_CODES.missingProperty);+ });++ test("a malformed payload writes no preference", async () => {+ seedPremise("a");+ enableDerivation();+ await expect(deriveHandler(ctx, { ...INPUT, premises: [{ id: "pref-a" }] })).rejects.toThrow(+ MCPError,+ );+ expect(existsSync(join(vault, "Brain", "preferences", "pref-derived-1.md"))).toBe(false);+ });++ test("a conforming payload still commits the derived fact", async () => {+ seedPremise("a");+ enableDerivation();+ const res = await deriveHandler(ctx, INPUT);+ expect(res).toMatchObject({ id: "pref-derived-1", level: "deduced" });+ });+});++describe("research-report ingress", () => {+ const INPUT = {+ title: "Survey",+ sources: ["Articles/src.md"],+ findings: [{ statement: "A point", sources: ["Articles/src.md"] }],+ };++ test("a finding missing its citation key is a shape violation", () => {+ let caught: unknown;+ try {+ parseResearchReportInput({ ...INPUT, findings: [{ statement: "uncited" }] });+ } catch (err) {+ caught = err;+ }+ expect(caught).toBeInstanceOf(ResponseShapeError);+ const err = caught as ResponseShapeError;+ expect(err.code).toBe(SHAPE_VIOLATION_CODES.missingProperty);+ expect(err.path).toBe("$.findings[0]");+ });++ test("a malformed third finding writes nothing at all", async () => {+ await expect(+ researchHandler(ctx, {+ ...INPUT,+ findings: [+ { statement: "one", sources: ["Articles/src.md"] },+ { statement: "two", sources: ["Articles/src.md"] },+ { statement: "three", sources: "Articles/src.md" },+ ],+ }),+ ).rejects.toThrow(MCPError);+ expect(listing(BRAIN_REPORTS_REL)).toEqual([]);+ });++ test("a well-formed report still lands", async () => {+ const res = (await researchHandler(ctx, INPUT)) as { finding_count: number };+ expect(res.finding_count).toBe(1);+ expect(listing(BRAIN_REPORTS_REL)).toHaveLength(1);+ });++ const BLANK_CITATION = {+ title: "Empty citation",+ sources: ["", " "],+ findings: [{ statement: "claim with a blank citation", sources: [""] }],+ };++ test("a blank source is refused: nothing can satisfy the citation contract", () => {+ // A blank source is a member of the consulted set, so a finding citing it+ // passes the "no uncited claims" check against nothing at all.+ let caught: unknown;+ try {+ parseResearchReportInput(BLANK_CITATION);+ } catch (err) {+ caught = err;+ }+ expect(caught).toBeInstanceOf(ResponseShapeError);+ const err = caught as ResponseShapeError;+ expect(err.code).toBe(SHAPE_VIOLATION_CODES.blankString);+ expect(err.path).toBe("$.sources[0]");+ expect(err.message).toContain("must be a non-empty string");+ });++ test("the blank-citation report is never written", async () => {+ await expect(researchHandler(ctx, BLANK_CITATION)).rejects.toThrow(MCPError);+ expect(listing(BRAIN_REPORTS_REL)).toEqual([]);+ });++ test("a blank title or finding statement is refused by path", () => {+ const blankTitle = (() => {+ try {+ parseResearchReportInput({ ...INPUT, title: " " });+ } catch (err) {+ return err as ResponseShapeError;+ }+ return null;+ })();+ expect(blankTitle?.path).toBe("$.title");++ const blankStatement = (() => {+ try {+ parseResearchReportInput({+ ...INPUT,+ findings: [{ statement: "", sources: ["Articles/src.md"] }],+ });+ } catch (err) {+ return err as ResponseShapeError;+ }+ return null;+ })();+ expect(blankStatement?.path).toBe("$.findings[0].statement");+ expect(blankStatement?.code).toBe(SHAPE_VIOLATION_CODES.blankString);+ });+});++/**+ * The audit the research-report fix demanded of the other two descriptors:+ * neither one expresses non-blankness, and neither one needs to, because the+ * write path itself refuses blank content by name before writing anything.+ * These cases hold that conclusion to the behaviour rather than to prose.+ */+describe("blank content never reaches a page", () => {+ test("a blank claim text aborts the distillation", async () => {+ await expect(+ distillHandler(ctx, { source_path: SOURCE_PATH, claims: [{ text: "one" }, { text: " " }] }),+ ).rejects.toThrow(MCPError);+ expect(listing(BRAIN_DISTILLATIONS_REL)).toEqual([]);+ });++ test("an empty claim list aborts the distillation", async () => {+ await expect(distillHandler(ctx, { source_path: SOURCE_PATH, claims: [] })).rejects.toThrow(+ MCPError,+ );+ expect(listing(BRAIN_DISTILLATIONS_REL)).toEqual([]);+ });++ test("a blank slug, principle or premise aborts the derivation", async () => {+ seedPremise("a");+ enableDerivation();+ const base = {+ slug: "derived-1",+ topic: "derived",+ principle: "Therefore C",+ premises: ["pref-a"],+ level: "deduced",+ };+ const blanks = [{ slug: " " }, { principle: "" }, { premises: [" "] }, { level: "" }];+ const outcomes = await Promise.allSettled(+ blanks.map((blank) => deriveHandler(ctx, { ...base, ...blank })),+ );+ outcomes.forEach((outcome, i) => {+ expect(outcome.status, JSON.stringify(blanks[i])).toBe("rejected");+ expect((outcome as PromiseRejectedResult).reason).toBeInstanceOf(MCPError);+ });+ expect(existsSync(join(vault, "Brain", "preferences", "pref-derived-1.md"))).toBe(false);+ });+});++describe("validation is unconditional", () => {+ test("no configuration key turns the shape check off", async () => {+ // Every plausible opt-out spelling, set to the most permissive value a+ // caller could hope for. None of them is read: the check still fires.+ writeFileSync(+ brainConfigPath(vault),+ [+ "schema_version: 1",+ "response_shape: false",+ "response_shape_enabled: false",+ "response_shape_strict: false",+ "guardrails:",+ " derived_fact_synthesis: true",+ " response_shape_validation: false",+ "",+ ].join("\n"),+ );+ await expect(+ distillHandler(ctx, { source_path: SOURCE_PATH, claims: [{ text: 1 }] }),+ ).rejects.toThrow(MCPError);+ expect(listing(BRAIN_DISTILLATIONS_REL)).toEqual([]);+ await expect(+ researchHandler(ctx, { title: "Survey", sources: ["Articles/src.md"], findings: [{}] }),+ ).rejects.toThrow(MCPError);+ expect(listing(BRAIN_REPORTS_REL)).toEqual([]);+ });+});diff --git a/tests/core/brain/response-shape.test.ts b/tests/core/brain/response-shape.test.tsnew file mode 100644index 00000000..4f5eea79--- /dev/null+++ b/tests/core/brain/response-shape.test.ts@@ -0,0 +1,252 @@+/**+ * Response-shape layer (signals-that-survive, unit 8, t_80b01448).+ *+ * The validator itself, the frozen descriptors declared for the+ * model-authored write paths, and the two discipline rules that keep the+ * layer usable: descriptors stay inside the subset the validator can+ * express, and the layer never borrows the knowledge vocabulary's noun.+ */++import { describe, expect, test } from "bun:test";+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import * as responseShapeModule from "../../../src/core/brain/response-shape.ts";+import { parseDistillClaims } from "../../../src/core/brain/distill/distill-source.ts";+import { parseDeriveFactInput } from "../../../src/core/brain/derived-fact.ts";+import { parseResearchReportInput } from "../../../src/core/brain/research/research.ts";+import {+ DERIVED_FACT_SHAPE,+ DISTILL_CLAIMS_SHAPE,+ MODEL_AUTHORED_SHAPES,+ RESEARCH_REPORT_SHAPE,+ ResponseShapeError,+ SHAPE_DESCRIPTOR_KEYS,+ SHAPE_ROOT_PATH,+ SHAPE_TYPES,+ SHAPE_VIOLATION_CODES,+ assertResponseShape,+ checkResponseShape,+ formatShapeViolation,+ type ShapeDescriptor,+} from "../../../src/core/brain/response-shape.ts";++/** Object nesting an object descriptor reaches, counting through array items. */+function objectNestingDepth(descriptor: ShapeDescriptor): number {+ if (descriptor.type === "object" || descriptor.properties !== undefined) {+ const children = Object.values(descriptor.properties ?? {});+ return 1 + children.reduce((deepest, child) => Math.max(deepest, objectNestingDepth(child)), 0);+ }+ if (descriptor.items !== undefined) return objectNestingDepth(descriptor.items);+ return 0;+}++/** Every descriptor node reachable from a root, root included. */+function descriptorNodes(descriptor: ShapeDescriptor): ShapeDescriptor[] {+ const nodes = [descriptor];+ for (const child of Object.values(descriptor.properties ?? {})) {+ nodes.push(...descriptorNodes(child));+ }+ if (descriptor.items !== undefined) nodes.push(...descriptorNodes(descriptor.items));+ if (typeof descriptor.additionalProperties === "object") {+ nodes.push(...descriptorNodes(descriptor.additionalProperties));+ }+ return nodes;+}++/** Deepest object nesting a shallow descriptor may declare: object -> array -> object. */+const MAX_OBJECT_NESTING = 2;++describe("checkResponseShape", () => {+ test("accepts a payload that satisfies the descriptor", () => {+ expect(checkResponseShape(DISTILL_CLAIMS_SHAPE, [{ text: "a claim" }])).toEqual([]);+ });++ test("reports a type mismatch with a structured code and path", () => {+ const violations = checkResponseShape(DISTILL_CLAIMS_SHAPE, [{ text: "ok" }, { text: 42 }]);+ expect(violations).toHaveLength(1);+ expect(violations[0]).toEqual({+ code: SHAPE_VIOLATION_CODES.typeMismatch,+ path: "$[1].text",+ message: "expected string",+ });+ });++ test("reports a missing required property", () => {+ const violations = checkResponseShape(DERIVED_FACT_SHAPE, {+ topic: "t",+ principle: "p",+ premises: ["pref-a"],+ level: "deduced",+ });+ expect(violations).toEqual([+ {+ code: SHAPE_VIOLATION_CODES.missingProperty,+ path: SHAPE_ROOT_PATH,+ message: "missing required property 'slug'",+ },+ ]);+ });++ test("renders a violation as the path-prefixed line the callers print", () => {+ const [violation] = checkResponseShape({ type: "string" }, 1);+ expect(formatShapeViolation(violation!)).toBe("$: expected string");+ });+});++describe("assertResponseShape", () => {+ test("returns silently for a conforming payload", () => {+ expect(() =>+ assertResponseShape("demo", RESEARCH_REPORT_SHAPE, {+ title: "T",+ sources: ["a"],+ findings: [{ statement: "s", sources: ["a"] }],+ }),+ ).not.toThrow();+ });++ test("throws a named error carrying code, path and message as fields", () => {+ let caught: unknown;+ try {+ assertResponseShape("demo", RESEARCH_REPORT_SHAPE, {+ title: "T",+ sources: ["a"],+ findings: [{ statement: "s" }],+ });+ } catch (err) {+ caught = err;+ }+ expect(caught).toBeInstanceOf(ResponseShapeError);+ const err = caught as ResponseShapeError;+ expect(err.name).toBe("ResponseShapeError");+ expect(err.code).toBe(SHAPE_VIOLATION_CODES.missingProperty);+ expect(err.path).toBe("$.findings[0]");+ expect(err.message).toContain("missing required property 'sources'");+ expect(err.surface).toBe("demo");+ expect(err.violations).toEqual([+ {+ code: SHAPE_VIOLATION_CODES.missingProperty,+ path: "$.findings[0]",+ message: "missing required property 'sources'",+ },+ ]);+ });+});++describe("model-authored descriptors", () => {+ test("one descriptor per model-authored write path, all registered", () => {+ expect(new Set(Object.values(MODEL_AUTHORED_SHAPES))).toEqual(+ new Set([DISTILL_CLAIMS_SHAPE, DERIVED_FACT_SHAPE, RESEARCH_REPORT_SHAPE]),+ );+ });++ test("every descriptor is frozen all the way down", () => {+ for (const [surface, descriptor] of Object.entries(MODEL_AUTHORED_SHAPES)) {+ for (const node of descriptorNodes(descriptor)) {+ expect(Object.isFrozen(node), `${surface} descriptor node is mutable`).toBe(true);+ }+ }+ });++ test("no descriptor uses a construct the subset validator cannot express", () => {+ const allowedKeys = new Set<string>(SHAPE_DESCRIPTOR_KEYS);+ const allowedTypes = new Set<string>(SHAPE_TYPES);+ for (const [surface, descriptor] of Object.entries(MODEL_AUTHORED_SHAPES)) {+ for (const node of descriptorNodes(descriptor)) {+ for (const key of Object.keys(node)) {+ expect(allowedKeys.has(key), `${surface} descriptor declares '${key}'`).toBe(true);+ }+ if (node.type !== undefined) {+ expect(allowedTypes.has(node.type), `${surface} descriptor type '${node.type}'`).toBe(+ true,+ );+ }+ }+ }+ });++ test("descriptors stay shallow: required keys, primitives, arrays of objects", () => {+ for (const [surface, descriptor] of Object.entries(MODEL_AUTHORED_SHAPES)) {+ expect(+ objectNestingDepth(descriptor),+ `${surface} descriptor is too deep`,+ ).toBeLessThanOrEqual(MAX_OBJECT_NESTING);+ }+ });+});++describe("layer discipline", () => {+ test("the knowledge vocabulary's noun is absent from everything this layer emits", () => {+ // Asserted over the surface a caller can observe - exported names, the+ // descriptor vocabulary, the violation codes and a thrown message - rather+ // than over the module text, where a comment could fail the suite and a+ // borrowed noun in a caller could not.+ for (const name of Object.keys(responseShapeModule)) {+ expect(name).not.toMatch(/schema/i);+ }+ for (const key of SHAPE_DESCRIPTOR_KEYS) expect(key).not.toMatch(/schema/i);+ for (const code of Object.values(SHAPE_VIOLATION_CODES)) {+ expect(code).not.toMatch(/schema/i);+ }+ const thrown = (() => {+ try {+ assertResponseShape("demo", DERIVED_FACT_SHAPE, {});+ } catch (err) {+ return err as ResponseShapeError;+ }+ return null;+ })();+ expect(thrown!.name).not.toMatch(/schema/i);+ expect(thrown!.message).not.toMatch(/schema/i);+ });++ test("no configuration or environment can change a verdict", () => {+ const payload = { title: "T", sources: [""], findings: [{ statement: "s", sources: [""] }] };+ const baseline = checkResponseShape(RESEARCH_REPORT_SHAPE, payload);+ expect(baseline.length).toBeGreaterThan(0);++ const configHome = mkdtempSync(join(tmpdir(), "o2b-response-shape-cfg-"));+ const configPath = join(configHome, "config.yaml");+ // A config declaring every plausible opt-out spelling, at the path the+ // whole codebase resolves settings from, plus the same spellings as env.+ writeFileSync(+ configPath,+ [+ "vault: /nonexistent",+ "response_shape: false",+ "response_shape_enabled: false",+ "response_shape_strict: false",+ "validation: off",+ "",+ ].join("\n"),+ "utf8",+ );+ const hostile: Record<string, string> = {+ OPEN_SECOND_BRAIN_CONFIG: configPath,+ OPEN_SECOND_BRAIN_RESPONSE_SHAPE_ENABLED: "false",+ OPEN_SECOND_BRAIN_RESPONSE_SHAPE: "off",+ NODE_ENV: "production",+ };+ const saved = new Map(Object.keys(hostile).map((key) => [key, process.env[key]]));+ try {+ for (const [key, value] of Object.entries(hostile)) process.env[key] = value;+ // The validator, and the three ingress functions that own the callers'+ // half of the contract, all still refuse the same payload by the same+ // path - a gate introduced in a caller would break exactly here.+ expect(checkResponseShape(RESEARCH_REPORT_SHAPE, payload)).toEqual(baseline);+ expect(() => assertResponseShape("demo", RESEARCH_REPORT_SHAPE, payload)).toThrow(+ ResponseShapeError,+ );+ expect(() => parseResearchReportInput(payload)).toThrow(ResponseShapeError);+ expect(() => parseDistillClaims([{ text: 1 }])).toThrow(ResponseShapeError);+ expect(() => parseDeriveFactInput({ topic: "t" })).toThrow(ResponseShapeError);+ } finally {+ for (const [key, value] of saved) {+ if (value === undefined) delete process.env[key];+ else process.env[key] = value;+ }+ rmSync(configHome, { recursive: true, force: true });+ }+ });+});diff --git a/tests/core/brain/skill-proposals.test.ts b/tests/core/brain/skill-proposals.test.tsindex ca1f3f03..4033547a 100644--- a/tests/core/brain/skill-proposals.test.ts+++ b/tests/core/brain/skill-proposals.test.ts@@ -1,5 +1,5 @@import { afterEach, beforeEach, describe, expect, test } from "bun:test";-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";@@ -12,8 +12,10 @@ import {} from "../../../src/core/brain/paths.ts";import {acceptSkillProposal,+ draftDeclaredSkillProposal,learnSkillProposals,listPendingSkillProposals,+ previewDeclaredSkillProposal,rejectSkillProposal,} from "../../../src/core/brain/skill-proposals.ts";@@ -298,3 +300,46 @@ function seedCorePatterns(vaultPath: string): void {});}}++describe("a declared proposal refuses a taken slug by name", () => {+ const declaration = {+ name: "release check",+ body: "run the suite, then the linter",+ sourceRefs: ["[[Daily/2026-07-27]]"],+ now: new Date("2026-07-27T09:00:00Z"),+ };++ test("a file already occupying the slug is a named outcome, not an uncaught write error", () => {+ const first = draftDeclaredSkillProposal(vault, declaration);+ expect(first.outcome).toBe("created");++ // Simulate what a change to the slug derivation would produce: the same+ // slug reached from a name key the lookup no longer matches. The mined+ // path guards this with an existsSync over the three phases; the+ // declared path must not fall through to the exclusive write instead.+ const stored = readFileSync(first.path, "utf8");+ writeFileSync(+ first.path,+ stored.replace(/^name_key: .*$/m, "name_key: declared_marker:some-other-key"),+ "utf8",+ );++ const second = draftDeclaredSkillProposal(vault, declaration);+ expect(second.outcome).toBe("suppressed");+ if (second.outcome !== "suppressed") throw new Error("unreachable");+ expect(second.reason).toContain(first.slug);+ expect(second.reason).toContain("pending/");+ });++ test("the preview reaches the same outcomes without writing", () => {+ const preview = previewDeclaredSkillProposal(vault, declaration);+ expect(preview.outcome).toBe("created");+ expect(existsSync(preview.path)).toBe(false);++ draftDeclaredSkillProposal(vault, declaration);+ expect(previewDeclaredSkillProposal(vault, declaration).outcome).toBe("deduped");++ rejectSkillProposal(vault, listPendingSkillProposals(vault)[0]!.slug, { note: "no" });+ expect(previewDeclaredSkillProposal(vault, declaration).outcome).toBe("suppressed");+ });+});diff --git a/tests/core/brain/write-advisory-routing-hint.test.ts b/tests/core/brain/write-advisory-routing-hint.test.tsnew file mode 100644index 00000000..7d8169c8--- /dev/null+++ b/tests/core/brain/write-advisory-routing-hint.test.ts@@ -0,0 +1,260 @@+/**+ * Unit 4 (t_75597bb9): the unroutable-capture routing hint.+ *+ * `adviseUnroutableCapture` is the sibling of `adviseIncomingFeedback`:+ * it runs AROUND the feedback write, never gates it, and reports the ONE+ * routing signal the capture lacked (`scope`) together with the scope+ * slugs the vault actually holds, ranked by document frequency. An empty+ * candidate set is the absent case and returns `null`, so a fresh vault+ * stays silent instead of printing empty prose.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { bootstrapBrain } from "../../../src/core/brain/init.ts";+import { readAllLogEntries } from "../../../src/core/brain/query.ts";+import { NEXT_COMMAND_KEY, resolveNextStep } from "../../../src/core/brain/next-step.ts";+import { brainDirs } from "../../../src/core/brain/paths.ts";+import { writePreference } from "../../../src/core/brain/preference.ts";+import { writeSignal } from "../../../src/core/brain/signal.ts";+import {+ BRAIN_LOG_EVENT_KIND,+ BRAIN_PREFERENCE_STATUS,+ type BrainPreferenceStatus,+} from "../../../src/core/brain/types.ts";+import {+ adviseUnroutableCapture,+ CAPTURE_ROUTING_HINT_CODE,+ CAPTURE_ROUTING_HINT_KEY,+ captureRoutingHintField,+ ROUTING_SIGNAL_FIELD,+} from "../../../src/core/brain/write-advisory.ts";++let tmp: string;+let vault: string;++const NOW = new Date("2026-07-27T12:00:00Z");++/** The identity and clock every call in this file advises under. */+const ADVICE = { agent: "test-agent", now: NOW } as const;++function pref(+ slug: string,+ scope: string,+ status: BrainPreferenceStatus = BRAIN_PREFERENCE_STATUS.confirmed,+): void {+ writePreference(vault, {+ slug,+ topic: slug,+ principle: `principle for ${slug}`,+ created_at: NOW.toISOString(),+ unconfirmed_until: NOW.toISOString(),+ ...(status === BRAIN_PREFERENCE_STATUS.confirmed+ ? { confirmed_at: NOW.toISOString() }+ : { confirmed_at: null }),+ status,+ evidenced_by: ["[[sig-2026-07-27-seed]]"],+ scope,+ });+}++function signal(slug: string, scope?: string): void {+ writeSignal(vault, {+ topic: slug,+ signal: "positive",+ agent: "test-agent",+ principle: `principle for ${slug}`,+ created_at: NOW.toISOString(),+ date: "2026-07-27",+ slug,+ ...(scope !== undefined ? { scope } : {}),+ });+}++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-routing-hint-"));+ vault = join(tmp, "vault");+ const configPath = join(tmp, "config.yaml");+ writeFileSync(configPath, `vault: ${vault}\n`);+ bootstrapBrain(vault, { configPath });+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++describe("adviseUnroutableCapture", () => {+ test("names scope as the missing signal and ranks observed slugs by document frequency", () => {+ pref("tabs", "coding");+ pref("naming", "coding");+ pref("tone", "writing");+ signal("sources", "research");+ signal("more-code", "coding");++ const hint = adviseUnroutableCapture(vault, ADVICE);++ expect(hint).not.toBeNull();+ expect(hint!.missing_signal).toBe(ROUTING_SIGNAL_FIELD);+ expect(hint!.code).toBe(CAPTURE_ROUTING_HINT_CODE);+ // Document frequency descending, then slug ascending on a tie.+ expect(hint!.candidates.map((c) => `${c.scope}:${c.documents}`)).toEqual([+ "coding:3",+ "research:1",+ "writing:1",+ ]);+ });++ test("counts only confirmed preferences, so an unpromoted scope is not advertised", () => {+ pref("drafts", "drafting", BRAIN_PREFERENCE_STATUS.unconfirmed);+ pref("tone", "writing");++ const hint = adviseUnroutableCapture(vault, ADVICE);++ expect(hint!.candidates.map((c) => c.scope)).toEqual(["writing"]);+ });++ test("returns null when the vault holds no scope corpus", () => {+ // A scope-less signal is corpus, but it declares no scope, so there+ // is nothing to suggest and the hint stays silent.+ signal("unscoped-thought");+ expect(adviseUnroutableCapture(vault, ADVICE)).toBeNull();+ });++ test("returns null when the capture already resolved an effective scope", () => {+ pref("tabs", "coding");+ expect(adviseUnroutableCapture(vault, { ...ADVICE, scope: "coding" })).toBeNull();+ expect(adviseUnroutableCapture(vault, { ...ADVICE, scope: "brand-new-scope" })).toBeNull();+ });++ test("degrades to a visible warning (returns null) when the preferences dir is unreadable", () => {+ signal("sources", "research");+ const prefsDir = brainDirs(vault).preferences;+ rmSync(prefsDir, { recursive: true, force: true });+ writeFileSync(prefsDir, "not a directory");++ const originalStderrWrite = process.stderr.write.bind(process.stderr);+ let captured = "";+ process.stderr.write = ((chunk: string | Uint8Array): boolean => {+ captured += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");+ return true;+ }) as typeof process.stderr.write;+ try {+ expect(adviseUnroutableCapture(vault, ADVICE)).toBeNull();+ expect(captured).toContain("capture routing hint computation failed");+ } finally {+ process.stderr.write = originalStderrWrite;+ }+ });++ test("records one capture-routing-hint event carrying the structured fields", () => {+ pref("tabs", "coding");+ pref("tone", "writing");++ adviseUnroutableCapture(vault, ADVICE);++ const events = readAllLogEntries(vault).filter(+ (e) => e.eventType === BRAIN_LOG_EVENT_KIND.captureRoutingHint,+ );+ expect(events.length).toBe(1);+ expect(events[0]!.body["missing_signal"]).toBe(ROUTING_SIGNAL_FIELD);+ // Structured slug + frequency per candidate, never a prose sentence.+ expect(events[0]!.body["candidates"]).toEqual(["coding documents=1", "writing documents=1"]);+ expect(events[0]!.body["agent"]).toBe(ADVICE.agent);+ });++ test("records nothing when the hint stays silent", () => {+ // A vault with no corpus, then a routable capture: neither is a+ // hint, so neither may leave a countable event behind.+ adviseUnroutableCapture(vault, ADVICE);+ pref("tabs", "coding");+ adviseUnroutableCapture(vault, { ...ADVICE, scope: "coding" });+ const events = readAllLogEntries(vault).filter(+ (e) => e.eventType === BRAIN_LOG_EVENT_KIND.captureRoutingHint,+ );+ expect(events.length).toBe(0);+ });++ test("a corrupt corpus file is skipped, not fatal", () => {+ pref("tone", "writing");+ writeFileSync(join(brainDirs(vault).inbox, "sig-2026-07-27-broken.md"), "not a signal file\n");++ const hint = adviseUnroutableCapture(vault, ADVICE);++ expect(hint!.candidates.map((c) => c.scope)).toEqual(["writing"]);+ });+});++describe("the hint's forward pointer", () => {+ test("resolves through the registry to a structural re-record command", () => {+ const step = resolveNextStep(CAPTURE_ROUTING_HINT_CODE);+ expect(step).not.toBeNull();+ expect(step!.nextCommand).toContain(`--${ROUTING_SIGNAL_FIELD} `);+ expect(step!.nextCommand.startsWith("o2b brain feedback ")).toBe(true);+ });+});++describe("the extracted-fact path is untouched", () => {+ test("routeExtractedFacts does not reach the capture routing hint", () => {+ // The invariant `write-advisory.ts` states in its header: the+ // advisory surface attaches to the operator-facing feedback path+ // only. Asserted structurally so a future import cannot break it.+ const source = readFileSync(+ join(import.meta.dir, "..", "..", "..", "src", "core", "brain", "fact-extract.ts"),+ "utf8",+ );+ expect(source).not.toContain("adviseUnroutableCapture");+ expect(source).not.toContain("write-advisory");+ });+});++describe("a signal the ranking could not read is reported, not dropped", () => {+ test("a corrupt inbox signal warns on stderr and the ranking still returns", () => {+ pref("tabs", "coding");+ signal("scoped-thought", "research");+ const corrupt = join(brainDirs(vault).inbox, "sig-2026-07-27-corrupt.md");+ writeFileSync(corrupt, "this file has no frontmatter at all\n");++ const originalStderrWrite = process.stderr.write.bind(process.stderr);+ let captured = "";+ process.stderr.write = ((chunk: string | Uint8Array): boolean => {+ captured += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");+ return true;+ }) as typeof process.stderr.write;+ let hint;+ try {+ hint = adviseUnroutableCapture(vault, ADVICE);+ } finally {+ process.stderr.write = originalStderrWrite;+ }++ // The skip is named, with the file that caused it.+ expect(captured).toContain("capture routing hint skipped unreadable signal");+ expect(captured).toContain(corrupt);+ // The remaining corpus still ranks: a corrupt document is one missing+ // count, never a refusal of the whole hint.+ expect(hint).not.toBeNull();+ expect(hint!.candidates.map((c) => c.scope).toSorted()).toEqual(["coding", "research"]);+ });+});++describe("both machine surfaces spell the hint the same way", () => {+ test("the composer names the key and resolves the exit once", () => {+ pref("tabs", "coding");+ const hint = adviseUnroutableCapture(vault, ADVICE);+ expect(hint).not.toBeNull();++ const field = captureRoutingHintField(hint) as Record<string, Record<string, unknown>>;+ expect(Object.keys(field)).toEqual([CAPTURE_ROUTING_HINT_KEY]);+ expect(field[CAPTURE_ROUTING_HINT_KEY]![NEXT_COMMAND_KEY]).toBe(+ resolveNextStep(CAPTURE_ROUTING_HINT_CODE)!.nextCommand,+ );+ expect(field[CAPTURE_ROUTING_HINT_KEY]!["missing_signal"]).toBe(ROUTING_SIGNAL_FIELD);+ });++ test("no hint contributes no key at all", () => {+ expect(captureRoutingHintField(null)).toEqual({});+ });+});diff --git a/tests/core/fs/git-discovery.test.ts b/tests/core/fs/git-discovery.test.tsnew file mode 100644index 00000000..c9d1d473--- /dev/null+++ b/tests/core/fs/git-discovery.test.ts@@ -0,0 +1,232 @@+/**+ * Unit 1 (t_4b2bd8f7): the shared git-aware discovery module. The hygiene repo+ * scan and the ingest batch planner both compose their ignore layering from+ * these primitives, so the layering order, the base-dir contract and the+ * submodule boundary have exactly one implementation.+ *+ * The module is kernel code: a malformed pattern is RETURNED as a structured+ * warning and never written to a stream.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { chmodSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import {+ buildRepositoryBaseScope,+ extendWithDirectoryIgnore,+ isNestedRepositoryBoundary,+ MAX_IGNORE_FILE_BYTES,+} from "../../../src/core/fs/git-discovery.ts";+import { IgnoreScope } from "../../../src/core/fs/ignore.ts";++let root: string;++beforeEach(() => {+ root = mkdtempSync(join(tmpdir(), "git-discovery-"));+});++afterEach(() => {+ rmSync(root, { recursive: true, force: true });+});++/** Write `content` to `<root>/<rel>`, creating parent directories. */+function put(rel: string, content = "x\n"): void {+ const abs = join(root, rel);+ mkdirSync(join(abs, ".."), { recursive: true });+ writeFileSync(abs, content, "utf8");+}++/** Run `fn` with stderr captured, returning everything it wrote. */+function captureStderr(fn: () => void): string {+ const chunks: string[] = [];+ const real = process.stderr.write.bind(process.stderr);+ process.stderr.write = ((chunk: unknown) => {+ chunks.push(typeof chunk === "string" ? chunk : String(chunk));+ return true;+ }) as typeof process.stderr.write;+ try {+ fn();+ } finally {+ process.stderr.write = real;+ }+ return chunks.join("");+}++describe("buildRepositoryBaseScope", () => {+ test("a repository with no ignore files yields an empty scope and no warnings", () => {+ const { scope, warnings } = buildRepositoryBaseScope(root, "");+ expect(scope.isEmpty).toBe(true);+ expect(warnings).toEqual([]);+ });++ test("the root .gitignore governs the whole tree", () => {+ put(".gitignore", "build/\n*.log\n");+ const { scope } = buildRepositoryBaseScope(root, "");+ expect(scope.isIgnored("build", true)).toBe(true);+ expect(scope.isIgnored("src/a.log", false)).toBe(true);+ expect(scope.isIgnored("src/a.ts", false)).toBe(false);+ });++ test(".git/info/exclude is layered BENEATH the root .gitignore", () => {+ put(".git/info/exclude", "secret.md\n");+ put(".gitignore", "!secret.md\n");+ const { scope } = buildRepositoryBaseScope(root, "");+ // The higher-precedence root .gitignore re-includes what the exclude file+ // dropped; the reverse ordering would leave it ignored.+ expect(scope.isIgnored("docs/secret.md", false)).toBe(false);+ });++ test(".git/info/exclude alone still ignores", () => {+ put(".git/info/exclude", "secret.md\n");+ const { scope } = buildRepositoryBaseScope(root, "");+ expect(scope.isIgnored("docs/secret.md", false)).toBe(true);+ });++ test("baseDir places the layers in the caller's path space", () => {+ put(".gitignore", "drop.md\n");+ const { scope } = buildRepositoryBaseScope(root, "sources/repo");+ expect(scope.isIgnored("sources/repo/drop.md", false)).toBe(true);+ // Same basename outside the declared base directory is untouched.+ expect(scope.isIgnored("elsewhere/drop.md", false)).toBe(false);+ });+});++describe("extendWithDirectoryIgnore", () => {+ test("a directory's .gitignore scopes only its own subtree", () => {+ put("pkg/.gitignore", "drop.md\n");+ const { scope } = extendWithDirectoryIgnore(IgnoreScope.empty(), join(root, "pkg"), "pkg");+ expect(scope.isIgnored("pkg/drop.md", false)).toBe(true);+ expect(scope.isIgnored("pkg/deep/drop.md", false)).toBe(true);+ expect(scope.isIgnored("other/drop.md", false)).toBe(false);+ });++ test("a nearer ! re-include wins over the layer beneath it", () => {+ put(".gitignore", "important.md\n");+ put("keep/.gitignore", "!important.md\n");+ const base = buildRepositoryBaseScope(root, "").scope;+ const { scope } = extendWithDirectoryIgnore(base, join(root, "keep"), "keep");+ expect(scope.isIgnored("skip/important.md", false)).toBe(true);+ expect(scope.isIgnored("keep/important.md", false)).toBe(false);+ });++ test("an absent .gitignore leaves the scope's behaviour untouched and warns nothing", () => {+ put(".gitignore", "drop.md\n");+ const base = buildRepositoryBaseScope(root, "").scope;+ const { scope, warnings } = extendWithDirectoryIgnore(base, join(root, "pkg"), "pkg");+ // The directory declares nothing, so the composed scope decides every path+ // exactly as the scope it was built from does.+ expect(scope.isIgnored("pkg/drop.md", false)).toBe(base.isIgnored("pkg/drop.md", false));+ expect(scope.isIgnored("pkg/keep.md", false)).toBe(base.isIgnored("pkg/keep.md", false));+ expect(scope.isEmpty).toBe(base.isEmpty);+ expect(warnings).toEqual([]);+ });+});++describe("an ignore file that cannot be honoured is reported, never swallowed", () => {+ test("an unreadable .gitignore comes back as a structured file-level warning", () => {+ put(".gitignore", "secret.md\n");+ chmodSync(join(root, ".gitignore"), 0o000);+ const { scope, warnings } = buildRepositoryBaseScope(root, "");+ // Nothing was filtered - and the operator is told why.+ expect(scope.isIgnored("secret.md", false)).toBe(false);+ expect(warnings).toHaveLength(1);+ expect(warnings[0]!.source).toBe(".gitignore");+ expect(warnings[0]!.line).toBe(0);+ expect(warnings[0]!.reason).toContain("EACCES");+ });++ test("an unreadable nested .gitignore names that directory's file", () => {+ put("pkg/.gitignore", "drop.md\n");+ chmodSync(join(root, "pkg", ".gitignore"), 0o000);+ const { warnings } = extendWithDirectoryIgnore(IgnoreScope.empty(), join(root, "pkg"), "pkg");+ expect(warnings.map((w) => w.source)).toEqual(["pkg/.gitignore"]);+ });++ test("a symlinked .gitignore is refused with a warning, never followed", () => {+ put("outside/target.gitignore", "secret.md\n");+ symlinkSync(join(root, "outside", "target.gitignore"), join(root, ".gitignore"));+ const { scope, warnings } = buildRepositoryBaseScope(root, "");+ expect(scope.isIgnored("secret.md", false)).toBe(false);+ expect(warnings).toHaveLength(1);+ expect(warnings[0]!.source).toBe(".gitignore");+ expect(warnings[0]!.line).toBe(0);+ expect(warnings[0]!.reason).toContain("symbolic link");+ });++ test("an oversized .gitignore is refused with a warning rather than read", () => {+ put(".gitignore", `${"#".repeat(MAX_IGNORE_FILE_BYTES)}\nsecret.md\n`);+ const { scope, warnings } = buildRepositoryBaseScope(root, "");+ expect(scope.isIgnored("secret.md", false)).toBe(false);+ expect(warnings).toHaveLength(1);+ expect(warnings[0]!.reason).toContain(String(MAX_IGNORE_FILE_BYTES));+ });++ test("a .gitignore that is a directory is refused with a warning", () => {+ mkdirSync(join(root, ".gitignore"), { recursive: true });+ const { warnings } = buildRepositoryBaseScope(root, "");+ expect(warnings).toHaveLength(1);+ expect(warnings[0]!.reason).toContain("regular file");+ });++ test("an absent ignore file is the ordinary case and warns nothing", () => {+ const { warnings } = buildRepositoryBaseScope(root, "");+ expect(warnings).toEqual([]);+ });+});++describe("malformed patterns are returned, never printed", () => {+ test("a malformed root pattern comes back as a structured warning", () => {+ put(".gitignore", "ok.md\n[unterminated\n");+ let warnings: ReturnType<typeof buildRepositoryBaseScope>["warnings"] = [];+ const printed = captureStderr(() => {+ warnings = buildRepositoryBaseScope(root, "").warnings;+ });+ expect(printed).toBe("");+ expect(warnings).toHaveLength(1);+ expect(warnings[0]!.source).toBe(".gitignore");+ expect(warnings[0]!.line).toBe(2);+ expect(warnings[0]!.pattern).toBe("[unterminated");+ expect(warnings[0]!.reason).toContain("unterminated");+ });++ test("a malformed per-directory pattern names that directory's file", () => {+ put("pkg/.gitignore", "[unterminated\n");+ let warnings: ReturnType<typeof extendWithDirectoryIgnore>["warnings"] = [];+ const printed = captureStderr(() => {+ warnings = extendWithDirectoryIgnore(IgnoreScope.empty(), join(root, "pkg"), "pkg").warnings;+ });+ expect(printed).toBe("");+ expect(warnings).toHaveLength(1);+ expect(warnings[0]!.source).toBe("pkg/.gitignore");+ });++ test("a malformed pattern produces no rule, so nothing is silently ignored", () => {+ put(".gitignore", "[unterminated\n");+ const { scope } = buildRepositoryBaseScope(root, "");+ expect(scope.isIgnored("[unterminated", false)).toBe(false);+ expect(scope.isEmpty).toBe(true);+ });+});++describe("isNestedRepositoryBoundary", () => {+ test("a gitlink file marks a submodule boundary", () => {+ put("sub/.git", "gitdir: ../.git/modules/sub\n");+ expect(isNestedRepositoryBoundary(join(root, "sub"))).toBe(true);+ });++ test("a nested .git directory marks a boundary", () => {+ mkdirSync(join(root, "vendor", ".git"), { recursive: true });+ expect(isNestedRepositoryBoundary(join(root, "vendor"))).toBe(true);+ });++ test("an ordinary directory is not a boundary", () => {+ put("plain/a.md");+ expect(isNestedRepositoryBoundary(join(root, "plain"))).toBe(false);+ });++ test("a non-existent directory is not a boundary", () => {+ expect(isNestedRepositoryBoundary(join(root, "missing"))).toBe(false);+ });+});diff --git a/tests/core/hygiene/scan-repo-ignore.test.ts b/tests/core/hygiene/scan-repo-ignore.test.tsindex 41138450..fcfda5b1 100644--- a/tests/core/hygiene/scan-repo-ignore.test.ts+++ b/tests/core/hygiene/scan-repo-ignore.test.ts@@ -5,7 +5,7 @@*/import { afterEach, beforeEach, describe, expect, test } from "bun:test";-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { chmodSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";@@ -103,26 +103,65 @@ describe("root scan files", () => {});});+/** Run `fn` with stderr captured, returning everything it wrote. */+function captureStderr(fn: () => void): string {+ const chunks: string[] = [];+ const real = process.stderr.write.bind(process.stderr);+ process.stderr.write = ((chunk: unknown) => {+ chunks.push(typeof chunk === "string" ? chunk : String(chunk));+ return true;+ }) as typeof process.stderr.write;+ try {+ fn();+ } finally {+ process.stderr.write = real;+ }+ return chunks.join("");+}+describe("malformed patterns", () => {test("a malformed pattern warns on stderr and never silently skips", () => {put("src/a.ts");put("src/[weird.ts");put(".gitignore", "[unterminated\n");- const lines: string[] = [];- const real = process.stderr.write.bind(process.stderr);- process.stderr.write = ((chunk: unknown) => {- lines.push(typeof chunk === "string" ? chunk : String(chunk));- return true;- }) as typeof process.stderr.write;- let targets: string[];- try {+ let targets: string[] = [];+ const printed = captureStderr(() => {targets = listScanTargets(root);- } finally {- process.stderr.write = real;- }+ });// Malformed rule produced no matcher, so nothing was silently dropped.expect(targets).toContain("src/a.ts");expect(targets).toContain("src/[weird.ts");- expect(lines.join("")).toContain("malformed ignore pattern");+ expect(printed).toContain("malformed ignore pattern");+ });+});++describe("unusable ignore files", () => {+ test("an unreadable .gitignore warns on stderr instead of passing silently", () => {+ put("src/a.ts");+ put("src/secret.ts");+ put(".gitignore", "secret.ts\n");+ chmodSync(join(root, ".gitignore"), 0o000);+ let targets: string[] = [];+ const printed = captureStderr(() => {+ targets = listScanTargets(root);+ });+ // The declaration could not be applied, so the file is still scanned - and+ // the operator is told why rather than being left to guess.+ expect(targets).toContain("src/secret.ts");+ expect(printed).toContain(".gitignore");+ expect(printed).toContain("EACCES");+ });++ test("a symlinked .gitignore is refused with a stderr warning", () => {+ put("src/a.ts");+ put("src/secret.ts");+ put("outside/rules", "secret.ts\n");+ symlinkSync(join(root, "outside", "rules"), join(root, ".gitignore"));+ let targets: string[] = [];+ const printed = captureStderr(() => {+ targets = listScanTargets(root);+ });+ expect(targets).toContain("src/secret.ts");+ expect(printed).toContain("symbolic link");});});diff --git a/tests/core/search/ranker-temporal-intent.test.ts b/tests/core/search/ranker-temporal-intent.test.tsnew file mode 100644index 00000000..d1aa4cde--- /dev/null+++ b/tests/core/search/ranker-temporal-intent.test.ts@@ -0,0 +1,296 @@+/**+ * Query-side temporal intent in the ranker (t_58fc4720): a detected query+ * window contributes its OWN capped additive layer over temporal+ * proximity and damps the misdirected freshness prior when the window is+ * historical. Absent intent leaves ranking byte-identical.+ */++import { test, expect, describe } from "bun:test";++import {+ rankResults,+ ACTIVATION_BOOST_CAP,+ CO_ACCESS_BOOST_CAP,+ ENTITY_BOOST_CAP,+ LINK_BOOST_CAP,+ REUSE_BOOST_CAP,+ TEMPORAL_INTENT_BOOST_CAP,+} from "../../../src/core/search/ranker.ts";+import { DEFAULT_RECENCY } from "../../../src/core/search/recency.ts";+import { detectTemporalIntent } from "../../../src/core/search/temporal-intent.ts";+import type { KeywordHit, SemanticHit, HydratedChunk } from "../../../src/core/search/store.ts";++const NOW = Date.UTC(2026, 6, 27, 12, 0, 0);+/** Inside the historical window the queries below name. */+const IN_WINDOW_MS = Date.UTC(2024, 5, 15, 9, 0, 0);++function hyd(chunkId: number, docId: number, mtimeMs: number): HydratedChunk {+ return Object.freeze({+ chunkId,+ documentId: docId,+ path: `doc${docId}.md`,+ title: `Doc ${docId}`,+ content: `chunk ${chunkId}`,+ startLine: 1,+ endLine: 1,+ mtime: Math.floor(mtimeMs / 1000),+ });+}++/** Two equally relevant candidates: one recent, one inside the window. */+const EQUAL_RELEVANCE = {+ keyword: [+ { chunkId: 1, documentId: 10, bm25: -5 },+ { chunkId: 2, documentId: 20, bm25: -5 },+ ] as KeywordHit[],+ semantic: [] as SemanticHit[],+ hydrated: new Map([+ [1, hyd(1, 10, NOW)],+ [2, hyd(2, 20, IN_WINDOW_MS)],+ ]),+ inboundLinkSources: new Map(),+ tagsByDoc: new Map(),+};++const BASE_OPTS = {+ keywordWeight: 0.6,+ semanticWeight: 0.4,+ limit: 10,+ nowMs: NOW,+};++const HISTORICAL_INTENT = detectTemporalIntent("since:2024-06-01 until:2024-06-30", NOW)!;++describe("absent temporal intent", () => {+ test("leaves ranking byte-identical and the breakdown key absent", () => {+ const without = rankResults(EQUAL_RELEVANCE, BASE_OPTS);+ const explicitNull = rankResults(EQUAL_RELEVANCE, { ...BASE_OPTS, temporalIntent: null });+ expect(explicitNull).toEqual(without);+ for (const r of without) {+ expect(r.breakdown).toBeDefined();+ expect("temporal" in r.breakdown!).toBe(false);+ expect(r.reasons.some((x) => x.startsWith("temporal_intent"))).toBe(false);+ }+ });++ test("with no intent the fresher document wins", () => {+ const ranked = rankResults(EQUAL_RELEVANCE, BASE_OPTS);+ expect(ranked[0]!.chunkId).toBe(1);+ });+});++describe("an active historical window", () => {+ test("ranks an in-window note above an equally relevant recent one", () => {+ const ranked = rankResults(EQUAL_RELEVANCE, {+ ...BASE_OPTS,+ temporalIntent: HISTORICAL_INTENT,+ });+ expect(ranked[0]!.chunkId).toBe(2);+ expect(ranked[1]!.chunkId).toBe(1);+ });++ test("the freshness prior and the temporal layer are separate reasons entries", () => {+ const ranked = rankResults(EQUAL_RELEVANCE, {+ ...BASE_OPTS,+ temporalIntent: HISTORICAL_INTENT,+ });+ const recent = ranked.find((r) => r.chunkId === 1)!;+ const inWindow = ranked.find((r) => r.chunkId === 2)!;+ // The recent document keeps its (damped) freshness prior AND carries a+ // distinct temporal-intent entry, so the two are separately attributable.+ expect(recent.reasons.filter((x) => x.startsWith("recency: "))).toHaveLength(1);+ expect(recent.reasons.filter((x) => x.startsWith("temporal_intent: "))).toHaveLength(1);+ expect(inWindow.reasons.filter((x) => x.startsWith("temporal_intent: "))).toHaveLength(1);+ expect(recent.breakdown!.recency).toBe(recent.recencyBoost);+ expect(inWindow.breakdown!.temporal).toBeCloseTo(TEMPORAL_INTENT_BOOST_CAP, 10);+ expect(recent.breakdown!.temporal).toBe(0);+ });++ test("damps the freshness prior rather than removing it", () => {+ const undamped = rankResults(EQUAL_RELEVANCE, BASE_OPTS).find((r) => r.chunkId === 1)!;+ const damped = rankResults(EQUAL_RELEVANCE, {+ ...BASE_OPTS,+ temporalIntent: HISTORICAL_INTENT,+ }).find((r) => r.chunkId === 1)!;+ expect(damped.recencyBoost).toBeGreaterThan(0);+ expect(damped.recencyBoost).toBeLessThan(undamped.recencyBoost);+ expect(damped.recencyBoost).toBeCloseTo(+ undamped.recencyBoost * HISTORICAL_INTENT.recencyDamping,+ 10,+ );+ });++ test("biases without excluding: the out-of-window candidate still surfaces", () => {+ const ranked = rankResults(EQUAL_RELEVANCE, {+ ...BASE_OPTS,+ temporalIntent: HISTORICAL_INTENT,+ });+ expect(ranked.map((r) => r.chunkId).toSorted()).toEqual([1, 2]);+ });+});++describe("a present-reaching window", () => {+ test("leaves the freshness prior undamped", () => {+ const intent = detectTemporalIntent("since:7d", NOW)!;+ const undamped = rankResults(EQUAL_RELEVANCE, BASE_OPTS).find((r) => r.chunkId === 1)!;+ const withIntent = rankResults(EQUAL_RELEVANCE, {+ ...BASE_OPTS,+ temporalIntent: intent,+ }).find((r) => r.chunkId === 1)!;+ expect(withIntent.recencyBoost).toBe(undamped.recencyBoost);+ // ...and the recent document, being inside the window, gains the layer.+ expect(withIntent.breakdown!.temporal).toBeCloseTo(TEMPORAL_INTENT_BOOST_CAP, 10);+ });+});++describe("event time", () => {+ test("a declared event time overrides mtime for the temporal layer", () => {+ // Chunk 1 was WRITTEN today but declares an event time inside the+ // window: the event time is the authority, mtime the fallback.+ const ranked = rankResults(+ { ...EQUAL_RELEVANCE, eventTimeMsByChunk: new Map([[1, IN_WINDOW_MS]]) },+ { ...BASE_OPTS, temporalIntent: HISTORICAL_INTENT },+ );+ const recent = ranked.find((r) => r.chunkId === 1)!;+ expect(recent.breakdown!.temporal).toBeCloseTo(TEMPORAL_INTENT_BOOST_CAP, 10);+ });++ test("an absent map entry falls back to mtime", () => {+ const withEmptyMap = rankResults(+ { ...EQUAL_RELEVANCE, eventTimeMsByChunk: new Map<number, number>() },+ { ...BASE_OPTS, temporalIntent: HISTORICAL_INTENT },+ );+ const withoutMap = rankResults(EQUAL_RELEVANCE, {+ ...BASE_OPTS,+ temporalIntent: HISTORICAL_INTENT,+ });+ expect(withEmptyMap).toEqual(withoutMap);+ });+});++describe("the temporal cap", () => {+ test("is in proportion to the existing link / entity / activation / reuse caps", () => {+ const siblings = [+ LINK_BOOST_CAP,+ ENTITY_BOOST_CAP,+ ACTIVATION_BOOST_CAP,+ CO_ACCESS_BOOST_CAP,+ REUSE_BOOST_CAP,+ ];+ // The constant's own justification: level with the TOP of the band,+ // never above it. Asserting mere membership of [min, max] could not+ // fail - the cap IS the max - so it pinned nothing.+ expect(TEMPORAL_INTENT_BOOST_CAP).toBe(Math.max(...siblings));+ expect(TEMPORAL_INTENT_BOOST_CAP).toBeGreaterThan(Math.min(...siblings));+ // Strong enough to overcome the full undamped freshness prior it+ // corrects, so a declared window can actually re-order the set. That+ // prior's maximum is the configured recency amplitude, which is the+ // number this cap is calibrated against - referenced, not restated.+ expect(TEMPORAL_INTENT_BOOST_CAP).toBeGreaterThan(DEFAULT_RECENCY.amplitude);+ });++ test("bounds the layer: no candidate ever exceeds it", () => {+ const ranked = rankResults(EQUAL_RELEVANCE, {+ ...BASE_OPTS,+ temporalIntent: HISTORICAL_INTENT,+ });+ for (const r of ranked) {+ expect(r.breakdown!.temporal).toBeLessThanOrEqual(TEMPORAL_INTENT_BOOST_CAP);+ expect(r.breakdown!.temporal).toBeGreaterThanOrEqual(0);+ }+ });+});++describe("recencyAmplitude 0", () => {+ test("remains a global off switch under an active temporal intent", () => {+ const ranked = rankResults(EQUAL_RELEVANCE, {+ ...BASE_OPTS,+ recency: { shape: 0.8, scale: 30, amplitude: 0 },+ temporalIntent: HISTORICAL_INTENT,+ });+ for (const r of ranked) {+ expect(r.recencyBoost).toBe(0);+ expect(r.breakdown!.recency).toBe(0);+ expect(r.reasons.some((x) => x.startsWith("recency: "))).toBe(false);+ }+ // The temporal layer is independent and still fires.+ expect(ranked[0]!.chunkId).toBe(2);+ });+});++describe("the tie-break hazard", () => {+ /**+ * Both candidates saturate `clamp01`, so the in-window document's larger+ * temporal contribution is invisible in the final score and the historical+ * `mtime desc` rung would hand the win to the fresher document - exactly+ * the freshness bias this unit corrects.+ */+ const SATURATING_OPTS = { ...BASE_OPTS, keywordWeight: 1 };++ test("an exact score tie is broken toward the in-window result, not the newer mtime", () => {+ const ranked = rankResults(EQUAL_RELEVANCE, {+ ...SATURATING_OPTS,+ temporalIntent: HISTORICAL_INTENT,+ });+ expect(ranked[0]!.score).toBe(ranked[1]!.score);+ expect(ranked[0]!.chunkId).toBe(2);+ });++ test("with no intent the historical mtime-desc tie-break is untouched", () => {+ const ranked = rankResults(EQUAL_RELEVANCE, SATURATING_OPTS);+ expect(ranked[0]!.score).toBe(ranked[1]!.score);+ expect(ranked[0]!.chunkId).toBe(1);+ });++ /**+ * Two saturating candidates whose keyword scores DIFFER: chunk 1 has the+ * better keyword score and the fresher mtime, chunk 2 sits inside the+ * declared window. Pins where the temporal rung sits - above the whole+ * historical ladder (`keywordScore` included), not only above the two+ * freshness rungs.+ */+ const SPLIT_KEYWORD = {+ ...EQUAL_RELEVANCE,+ keyword: [+ { chunkId: 1, documentId: 10, bm25: -6 },+ { chunkId: 2, documentId: 20, bm25: -5.9 },+ // Anchors the min-max floor so the two above stay near-equal.+ { chunkId: 3, documentId: 30, bm25: -1 },+ ] as KeywordHit[],+ semantic: [+ { chunkId: 1, documentId: 10, distance: 0 },+ { chunkId: 2, documentId: 20, distance: 0 },+ ] as SemanticHit[],+ hydrated: new Map([+ [1, hyd(1, 10, NOW)],+ [2, hyd(2, 20, IN_WINDOW_MS)],+ [3, hyd(3, 30, NOW)],+ ]),+ // Chunk 2 trails on keyword score; this link boost lifts it back onto+ // an exact tie so the LADDER decides, with or without a window.+ inboundLinkSources: new Map([[2, new Set([10, 30])]]),+ };+ const SPLIT_OPTS = {+ ...BASE_OPTS,+ keywordWeight: 0.5,+ semanticWeight: 0.5,+ semanticEnabled: true,+ };++ test("the temporal rung outranks keywordScore, not only the two freshness rungs", () => {+ const ranked = rankResults(SPLIT_KEYWORD, {+ ...SPLIT_OPTS,+ temporalIntent: HISTORICAL_INTENT,+ });+ const [first, second] = [ranked[0]!, ranked[1]!];+ expect(first.score).toBe(second.score);+ expect(first.keywordScore).toBeLessThan(second.keywordScore);+ expect(first.chunkId).toBe(2);+ });++ test("with no window declared the same pair falls back to keywordScore desc", () => {+ const ranked = rankResults(SPLIT_KEYWORD, SPLIT_OPTS);+ expect(ranked[0]!.score).toBe(ranked[1]!.score);+ expect(ranked[0]!.chunkId).toBe(1);+ });+});diff --git a/tests/core/search/search-temporal-intent.test.ts b/tests/core/search/search-temporal-intent.test.tsnew file mode 100644index 00000000..7c2d571c--- /dev/null+++ b/tests/core/search/search-temporal-intent.test.ts@@ -0,0 +1,211 @@+/**+ * Query-side temporal intent end to end (t_58fc4720): `search()` detects+ * the window at the query-plan seam, strips the `since:` / `until:`+ * directives from the keyword lane so they bias rather than exclude, and+ * threads the declared event times into the ranker's temporal layer.+ */++import { test, expect, beforeEach, afterEach, describe } from "bun:test";+import { Database } from "bun:sqlite";+import { utimesSync } from "node:fs";++import { indexVault } from "../../../src/core/search/indexer.ts";+import { search } from "../../../src/core/search/search.ts";+import { SearchError } from "../../../src/core/search/types.ts";+import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";++const BODY = "Reactor coolant excursion timeline and valve maintenance log.";+const IN_WINDOW = new Date(Date.UTC(2024, 5, 15));+const OUT_OF_WINDOW_QUERY = "reactor coolant excursion";+const WINDOWED_QUERY = "reactor coolant excursion since:2024-06-01 until:2024-06-30";++describe("search() honours a query-declared temporal window", () => {+ let vault: string;+ let dbPath: string;+ let cleanup: () => void;++ beforeEach(() => {+ ({ vault, dbPath, cleanup } = createTempVault("temporal-intent"));+ });++ afterEach(() => {+ cleanup();+ });++ async function buildVault(): Promise<ReturnType<typeof makeConfig>> {+ const old = writeMd(vault, "Brain/notes/old.md", `# Old\n\n${BODY}\n`);+ writeMd(vault, "Brain/notes/recent.md", `# Recent\n\n${BODY}\n`);+ utimesSync(old, IN_WINDOW, IN_WINDOW);+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1 });+ await indexVault(config);+ return config;+ }++ test("without a window the fresher note wins", async () => {+ const config = await buildVault();+ const outcome = await search(config, { query: OUT_OF_WINDOW_QUERY });+ expect(outcome.results[0]!.path).toBe("Brain/notes/recent.md");+ });++ test("a declared historical window floats the in-window note without excluding the other", async () => {+ const config = await buildVault();+ const outcome = await search(config, { query: WINDOWED_QUERY });+ const paths = outcome.results.map((r) => r.path);+ // Biased, not filtered: both notes are still returned.+ expect(paths).toContain("Brain/notes/old.md");+ expect(paths).toContain("Brain/notes/recent.md");+ expect(paths[0]).toBe("Brain/notes/old.md");+ });++ test("the directive is stripped from the keyword lane, so it never kills the match", async () => {+ const config = await buildVault();+ const outcome = await search(config, { query: WINDOWED_QUERY });+ expect(outcome.results.length).toBeGreaterThan(0);+ const inWindow = outcome.results.find((r) => r.path === "Brain/notes/old.md")!;+ expect(inWindow.reasons.some((x) => x.startsWith("temporal_intent: "))).toBe(true);+ });++ test("a declared valid_from is the event-time authority over mtime", async () => {+ // Written today, but the note declares it is ABOUT the window.+ writeMd(+ vault,+ "Brain/notes/backfilled.md",+ `---\nvalid_from: 2024-06-10\nvalid_until: 2024-06-20\n---\n\n# Backfilled\n\n${BODY}\n`,+ );+ writeMd(vault, "Brain/notes/recent.md", `# Recent\n\n${BODY}\n`);+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1 });+ await indexVault(config);+ const outcome = await search(config, { query: WINDOWED_QUERY });+ expect(outcome.results[0]!.path).toBe("Brain/notes/backfilled.md");+ });++ test("the hard since/until filter still excludes, and composes with the soft window", async () => {+ const config = await buildVault();+ const outcome = await search(config, {+ query: OUT_OF_WINDOW_QUERY,+ since: "2024-06-01",+ until: "2024-06-30",+ });+ const paths = outcome.results.map((r) => r.path);+ expect(paths).toContain("Brain/notes/old.md");+ expect(paths).not.toContain("Brain/notes/recent.md");+ });++ // ----- the window survives query expansion ------------------------------+ //+ // Expansion rewrites the keyword text into `lex.include` terms, which is+ // a bare token list: the `field:value` grammar does not survive it. The+ // window must therefore be detected from the ORIGINAL query, or detection+ // and stripping disagree and the directive reaches the implicit-AND+ // keyword lane as a term no document carries.++ test("expansion alone (no window) is the control: both notes are found", async () => {+ const config = await buildVault();+ const outcome = await search(config, { query: OUT_OF_WINDOW_QUERY, expand: true });+ expect(outcome.results.map((r) => r.path).toSorted()).toEqual([+ "Brain/notes/old.md",+ "Brain/notes/recent.md",+ ]);+ });++ test("a declared window under expansion still finds both notes and still biases", async () => {+ const config = await buildVault();+ const outcome = await search(config, { query: WINDOWED_QUERY, expand: true });+ const paths = outcome.results.map((r) => r.path);+ expect(paths).toContain("Brain/notes/old.md");+ expect(paths).toContain("Brain/notes/recent.md");+ expect(paths[0]).toBe("Brain/notes/old.md");+ const inWindow = outcome.results.find((r) => r.path === "Brain/notes/old.md")!;+ expect(inWindow.reasons.some((x) => x.startsWith("temporal_intent: "))).toBe(true);+ });++ test("the thorough recall profile (expansion on) keeps the window too", async () => {+ const config = await buildVault();+ const outcome = await search(config, { query: WINDOWED_QUERY, profile: "thorough" });+ expect(outcome.results.length).toBeGreaterThan(0);+ const inWindow = outcome.results.find((r) => r.path === "Brain/notes/old.md")!;+ expect(inWindow.reasons.some((x) => x.startsWith("temporal_intent: "))).toBe(true);+ });++ // ----- a window with no terms is an input error --------------------------++ test("a directive-only query names what is missing instead of returning nothing", async () => {+ const config = await buildVault();+ await expect(search(config, { query: "since:2024-06-01 until:2024-06-30" })).rejects.toThrow(+ SearchError,+ );+ await expect(search(config, { query: "since:2024-06-01" })).rejects.toThrow(+ /no search terms/iu,+ );+ });++ // ----- a shape-only bare token is not a declaration ----------------------++ test("an ISO-shaped but impossible bare token never aborts the search", async () => {+ const config = await buildVault();+ for (const query of [+ "reactor coolant excursion 2024-06-31",+ "reactor coolant excursion 2023-02-29",+ "reactor coolant excursion 2026-13-45",+ ]) {+ // eslint-disable-next-line no-await-in-loop -- three sequential probes+ const outcome = await search(config, { query, limit: 5 });+ // No window is declared, so the token is ordinary content: the query+ // behaves exactly as it would with any other literal the corpus does+ // not carry, instead of raising INVALID_INPUT.+ expect(outcome.results.map((r) => r.path)).toEqual([]);+ }+ });++ test("an impossible date token stays in the query text as content", async () => {+ writeMd(vault, "Brain/notes/invoice.md", "# Invoice\n\nReactor invoice 2024-06-31 filed.\n");+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1 });+ await indexVault(config);+ const outcome = await search(config, { query: "reactor invoice 2024-06-31", limit: 5 });+ expect(outcome.results.map((r) => r.path)).toContain("Brain/notes/invoice.md");+ });++ // ----- no natural-language phrase is recognised in query text ------------++ test("an English phrase in a query directive is refused, exactly as any other language is", async () => {+ const config = await buildVault();+ for (const value of ["yesterday", "today", "ayer"]) {+ // eslint-disable-next-line no-await-in-loop -- three sequential probes+ await expect(search(config, { query: `reactor coolant since:${value}` })).rejects.toThrow(+ SearchError,+ );+ }+ });++ test("the language-neutral forms still resolve from query text", async () => {+ const config = await buildVault();+ for (const value of ["2024-06-01", "2024-06-01T00:00:00Z", "30d"]) {+ // eslint-disable-next-line no-await-in-loop -- three sequential probes+ const outcome = await search(config, { query: `reactor coolant since:${value}` });+ expect(outcome.results.length).toBeGreaterThan(0);+ }+ });++ // ----- the cache treats a query-declared window like the parameter form --++ test("a query-declared window bypasses the query cache", async () => {+ const old = writeMd(vault, "Brain/notes/old.md", `# Old\n\n${BODY}\n`);+ utimesSync(old, IN_WINDOW, IN_WINDOW);+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, cacheEnabled: true });+ await indexVault(config);++ await search(config, { query: OUT_OF_WINDOW_QUERY, limit: 5 });+ await search(config, { query: `${OUT_OF_WINDOW_QUERY} since:30d`, limit: 5 });++ const db = new Database(dbPath);+ try {+ const row = db.query<{ c: number }, []>("SELECT count(*) AS c FROM query_cache").get();+ // Only the windowless query was cached: a relative window resolves to+ // a new absolute signature on every call, so a row per call would be+ // pure growth that can never be served.+ expect(row?.c).toBe(1);+ } finally {+ db.close();+ }+ });+});diff --git a/tests/core/search/temporal-intent.test.ts b/tests/core/search/temporal-intent.test.tsnew file mode 100644index 00000000..c2fdaa68--- /dev/null+++ b/tests/core/search/temporal-intent.test.ts@@ -0,0 +1,212 @@+/**+ * Query-side temporal intent (t_58fc4720): a query carrying an explicit+ * time window is detected at the query-plan seam from STRUCTURAL tokens+ * only - ISO date/datetime tokens and the `since:` / `until:` field+ * grammar. No natural-language phrase list, in any language.+ */++import { test, expect, describe } from "bun:test";++import {+ detectTemporalIntent,+ stripTemporalDirectives,+ HISTORICAL_RECENCY_DAMPING,+ HISTORICAL_WINDOW_MIN_AGE_DAYS,+} from "../../../src/core/search/temporal-intent.ts";+import { buildQueryPlan } from "../../../src/core/search/query-plan.ts";+import { SearchError } from "../../../src/core/search/types.ts";++const DAY_MS = 24 * 60 * 60 * 1000;+const NOW = Date.UTC(2026, 6, 27, 12, 0, 0);++describe("detectTemporalIntent (pure)", () => {+ test("a query with no temporal token has no intent", () => {+ expect(detectTemporalIntent("reactor coolant excursion", NOW)).toBeNull();+ expect(detectTemporalIntent("", NOW)).toBeNull();+ });++ test("a bare ISO date resolves to that whole UTC day", () => {+ const intent = detectTemporalIntent("incident 2024-06-15 timeline", NOW);+ expect(intent).not.toBeNull();+ expect(intent!.range.sinceMs).toBe(Date.UTC(2024, 5, 15));+ expect(intent!.range.untilMs).toBe(Date.UTC(2024, 5, 15) + DAY_MS - 1);+ // A bare token is content as well as a signal: it stays in the query.+ expect(stripTemporalDirectives("incident 2024-06-15 timeline")).toBe(+ "incident 2024-06-15 timeline",+ );+ });++ test("a non-Latin-script query with an ISO date is detected identically to the English one", () => {+ // The language-agnostic proof: the same ISO token surrounded by+ // Cyrillic, by Han characters with NO whitespace at all, and by+ // English must produce byte-identical windows.+ const english = detectTemporalIntent("incident 2024-06-15 report", NOW);+ const cyrillic = detectTemporalIntent("ΠΈΠ½ΡΠΈΠ΄Π΅Π½Ρ 2024-06-15 ΠΎΡΡΡΡ", NOW);+ const han = detectTemporalIntent("δΊζ 2024-06-15ζ₯ε", NOW);+ expect(english).not.toBeNull();+ expect(cyrillic!.range).toEqual(english!.range);+ expect(han!.range).toEqual(english!.range);+ expect(cyrillic!.signature).toBe(english!.signature);+ expect(han!.signature).toBe(english!.signature);+ expect(cyrillic!.historical).toBe(english!.historical);+ });++ test("two ISO tokens span the earliest day-start to the latest day-end", () => {+ const intent = detectTemporalIntent("2024-06-15 through 2024-06-20", NOW)!;+ expect(intent.range.sinceMs).toBe(Date.UTC(2024, 5, 15));+ expect(intent.range.untilMs).toBe(Date.UTC(2024, 5, 20) + DAY_MS - 1);+ });++ test("an ISO datetime token resolves to its exact instant", () => {+ const intent = detectTemporalIntent("deploy 2024-06-15T10:30:00Z rollback", NOW)!;+ expect(intent.range.sinceMs).toBe(Date.UTC(2024, 5, 15, 10, 30, 0));+ expect(intent.range.untilMs).toBe(Date.UTC(2024, 5, 15, 10, 30, 0));+ });++ test("a date-shaped run embedded in a longer digit run is not a date", () => {+ expect(detectTemporalIntent("build 12024-06-155", NOW)).toBeNull();+ });++ test("since: / until: field tokens resolve through the shared time-point parser", () => {+ const intent = detectTemporalIntent("coolant since:2024-06-01 until:2024-06-30", NOW)!;+ expect(intent.range.sinceMs).toBe(Date.UTC(2024, 5, 1));+ expect(intent.range.untilMs).toBe(Date.UTC(2024, 5, 30) + DAY_MS - 1);+ });++ test("a field token is a directive, not content: it is stripped from the query text", () => {+ expect(stripTemporalDirectives("coolant since:2024-06-01 until:2024-06-30")).toBe("coolant");+ expect(stripTemporalDirectives("since:2024-06-01 coolant valve")).toBe("coolant valve");+ });++ test("stripping is byte-identical for a query carrying no directive", () => {+ const untouched = " reactor coolant ";+ expect(stripTemporalDirectives(untouched)).toBe(untouched);+ });++ test("field tokens take precedence over bare ISO tokens in the same query", () => {+ const intent = detectTemporalIntent("since:2024-06-01 incident 2025-01-01", NOW)!;+ expect(intent.range.sinceMs).toBe(Date.UTC(2024, 5, 1));+ expect(intent.range.untilMs).toBeNull();+ });++ test("relative field values resolve against the injected clock, never a wall clock", () => {+ const intent = detectTemporalIntent("coolant since:7d", NOW)!;+ expect(intent.range.sinceMs).toBe(NOW - 7 * DAY_MS);+ expect(intent.range.untilMs).toBeNull();+ });++ test("an open-ended since: window reaches the present and is not historical", () => {+ const intent = detectTemporalIntent("coolant since:7d", NOW)!;+ expect(intent.historical).toBe(false);+ expect(intent.recencyDamping).toBe(1);+ });++ test("a window that closed long ago is historical and damps the freshness prior", () => {+ const intent = detectTemporalIntent("coolant since:2024-06-01 until:2024-06-30", NOW)!;+ expect(intent.historical).toBe(true);+ expect(intent.recencyDamping).toBe(HISTORICAL_RECENCY_DAMPING);+ expect(HISTORICAL_RECENCY_DAMPING).toBeGreaterThan(0);+ expect(HISTORICAL_RECENCY_DAMPING).toBeLessThan(1);+ });++ test("a window closing inside the minimum age is not yet historical", () => {+ const untilMs = NOW - (HISTORICAL_WINDOW_MIN_AGE_DAYS - 1) * DAY_MS;+ const until = new Date(untilMs).toISOString();+ const intent = detectTemporalIntent(`coolant until:${until}`, NOW)!;+ expect(intent.historical).toBe(false);+ expect(intent.recencyDamping).toBe(1);+ });++ test("a malformed field-token value raises the named error, never a silent skip", () => {+ expect(() => detectTemporalIntent("coolant since:notadate", NOW)).toThrow(SearchError);+ });++ test("an inverted field window raises the named error", () => {+ expect(() => detectTemporalIntent("coolant since:2024-06-30 until:2024-06-01", NOW)).toThrow(+ SearchError,+ );+ });++ // ----- a bare token is a shape, not a declaration -----------------------++ test("an ISO-SHAPED but impossible bare token declares nothing and is left alone", () => {+ for (const query of [+ "reactor invoice 2024-06-31",+ "leap day 2023-02-29",+ "ticket 2026-13-45",+ "deploy 2024-06-15T99:99:99Z rollback",+ ]) {+ expect(detectTemporalIntent(query, NOW)).toBeNull();+ expect(stripTemporalDirectives(query)).toBe(query);+ }+ });++ test("a valid bare token beside an impossible one still declares its own window", () => {+ const intent = detectTemporalIntent("invoice 2024-06-31 filed 2024-06-15", NOW)!;+ expect(intent.range.sinceMs).toBe(Date.UTC(2024, 5, 15));+ });++ test("an impossible date in an explicit FIELD token still raises: the operator declared it", () => {+ expect(() => detectTemporalIntent("coolant since:2024-06-31", NOW)).toThrow(SearchError);+ expect(() => detectTemporalIntent("coolant until:2023-02-29", NOW)).toThrow(SearchError);+ });++ // ----- no phrase, in any language, is recognised ------------------------++ test("a natural-language field value is refused in every language alike", () => {+ for (const value of ["yesterday", "today", "ayer", "hoy", "gestern", "ζ¨ε€©"]) {+ expect(() => detectTemporalIntent(`coolant since:${value}`, NOW)).toThrow(SearchError);+ }+ });++ test("the language-neutral field forms are accepted", () => {+ expect(detectTemporalIntent("coolant since:2024-06-01", NOW)).not.toBeNull();+ expect(detectTemporalIntent("coolant since:2024-06-01T10:30:00Z", NOW)).not.toBeNull();+ expect(detectTemporalIntent("coolant since:12h", NOW)).not.toBeNull();+ expect(detectTemporalIntent("coolant since:7d", NOW)).not.toBeNull();+ expect(detectTemporalIntent("coolant until:2w", NOW)).not.toBeNull();+ });++ test("detection is deterministic against a fixed clock", () => {+ expect(detectTemporalIntent("since:2024-06-01 coolant", NOW)).toEqual(+ detectTemporalIntent("since:2024-06-01 coolant", NOW),+ );+ });++ test("the signature is derived from the resolved absolute bounds", () => {+ const a = detectTemporalIntent("2024-06-15", NOW)!;+ const b = detectTemporalIntent("2024-06-16", NOW)!;+ expect(a.signature).not.toBe(b.signature);+ });+});++describe("buildQueryPlan carries the temporal intent", () => {+ test("without an injected clock nothing is detected and the plan is unchanged", () => {+ const plan = buildQueryPlan("coolant since:2024-06-01");+ expect(plan.temporalIntent).toBeUndefined();+ });++ test("a query with no temporal window keeps a byte-identical planHash", () => {+ const withoutClock = buildQueryPlan("reactor coolant excursion");+ const withClock = buildQueryPlan("reactor coolant excursion", [], undefined, undefined, NOW);+ expect(withClock.planHash).toBe(withoutClock.planHash);+ expect(withClock.temporalIntent).toBeUndefined();+ expect(withClock).toEqual(withoutClock);+ });++ test("a temporal window changes the planHash so a cached row is never reused across windows", () => {+ const june = buildQueryPlan("coolant since:2024-06-01", [], undefined, undefined, NOW);+ const july = buildQueryPlan("coolant since:2024-07-01", [], undefined, undefined, NOW);+ const bare = buildQueryPlan("coolant", [], undefined, undefined, NOW);+ expect(june.temporalIntent).toBeDefined();+ expect(june.planHash).not.toBe(july.planHash);+ expect(june.planHash).not.toBe(bare.planHash);+ });++ test("intent classification reads the residual query, not the stripped directive", () => {+ const withDirective = buildQueryPlan("coolant since:2024-06-01", [], undefined, undefined, NOW);+ const residualOnly = buildQueryPlan("coolant", [], undefined, undefined, NOW);+ expect(withDirective.intent).toBe(residualOnly.intent);+ expect(withDirective.weightProfile).toEqual(residualOnly.weightProfile);+ });+});diff --git a/tests/hooks/gap-loop.test.ts b/tests/hooks/gap-loop.test.tsindex 41cb00b1..973eec1e 100644--- a/tests/hooks/gap-loop.test.ts+++ b/tests/hooks/gap-loop.test.ts@@ -1,15 +1,28 @@import { afterEach, beforeEach, describe, expect, test } from "bun:test";-import { existsSync, mkdtempSync, rmSync } from "node:fs";+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";import { tmpdir } from "node:os";import { dirname, join, resolve } from "node:path";import { fileURLToPath } from "node:url";import { emitRecallTelemetry } from "../../src/core/brain/recall-telemetry.ts";+import { assessRecallAdequacy } from "../../src/core/brain/recall-adequacy.ts";+import {+ normalizeQueryTerms,+ recordRecallAdequacyDemand,+} from "../../src/core/brain/query-demand.ts";import {listGapTasks,promoteGapsToTasks,+ GAP_SOURCE_ADEQUACY,+ GAP_SOURCE_TELEMETRY,+ GAP_TASK_CLOSED_RETENTION_MS,+ GAP_TASK_KIND,+ GAP_TASK_STATUS_CLOSED,GAP_TASK_STATUS_OPEN,+ GAP_TASKS_MAX_NOTES,} from "../../src/core/brain/gaps/gap-loop.ts";+import { brainGapTasksDir } from "../../src/core/brain/paths.ts";+import { writeFrontmatterAtomic } from "../../src/core/vault.ts";const HOOKS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "hooks");@@ -67,6 +80,22 @@ function seedGap(topic: string, times: number): void {}}+/** The bucket key `normalizeQueryTerms` derives for {@link ADEQUACY_QUERY}. */+const ADEQUACY_QUERY = "widget calibration procedure";+const ADEQUACY_BUCKET = normalizeQueryTerms(ADEQUACY_QUERY).join(" ");++/** Seed a recurring weak-recall bucket (signals-that-survive, unit 6). */+function seedUnmetRecall(times: number): void {+ const verdict = assessRecallAdequacy([0.4]);+ for (let i = 0; i < times; i++) {+ recordRecallAdequacyDemand(vault, {+ query: ADEQUACY_QUERY,+ verdict,+ at: `2026-05-1${i}T09:00:00.000Z`,+ });+ }+}+describe("gap-promote hook (SessionEnd)", () => {test("flag off is a no-op: no gap-task notes written", async () => {seedGap("alpha topic", 3);@@ -75,6 +104,32 @@ describe("gap-promote hook (SessionEnd)", () => {expect(existsSync(join(vault, "Brain", "gap-tasks"))).toBe(false);});+ test("flag off is a no-op for the adequacy source too", async () => {+ seedUnmetRecall(4);+ const r = await runHook("gap-promote", { hook_event_name: "SessionEnd" }, { VAULT_DIR: vault });+ expect(r.exit).toBe(0);+ expect(r.stdout).toBe("");+ expect(existsSync(join(vault, "Brain", "gap-tasks"))).toBe(false);+ expect(listGapTasks(vault)).toHaveLength(0);+ });++ test("flag on promotes a recurring weak-recall bucket to a gap task", async () => {+ seedUnmetRecall(4);+ const run = await runHook(+ "gap-promote",+ { hook_event_name: "SessionEnd" },+ {+ VAULT_DIR: vault,+ OPEN_SECOND_BRAIN_GAP_LOOP_ENABLED: "true",+ OPEN_SECOND_BRAIN_GAP_LOOP_THRESHOLD: "3",+ },+ );+ expect(run.exit).toBe(0);+ const open = listGapTasks(vault, { status: GAP_TASK_STATUS_OPEN });+ expect(open.map((t) => t.topic)).toContain(ADEQUACY_BUCKET);+ expect(open.map((t) => t.source)).toContain(GAP_SOURCE_ADEQUACY);+ });+test("flag on promotes a recurring gap to an open gap-task note", async () => {seedGap("alpha topic", 3);const run = await runHook(@@ -92,6 +147,102 @@ describe("gap-promote hook (SessionEnd)", () => {});});+describe("gap-promote hook audit line", () => {+ /** Every `gap_loop_run` details object the hook appended, oldest first. */+ function auditDetails(): ReadonlyArray<Record<string, unknown>> {+ const dir = join(vault, ".open-second-brain", "hook-audit");+ if (!existsSync(dir)) return [];+ return readdirSync(dir)+ .toSorted()+ .flatMap((name) => readFileSync(join(dir, name), "utf8").split("\n"))+ .filter((line) => line.trim().length > 0)+ .map((line) => JSON.parse(line) as { action?: string; details?: Record<string, unknown> })+ .filter((record) => record.action === "gap_loop_run")+ .map((record) => record.details ?? {});+ }++ /** Write one gap-task note directly, bypassing the hook's mint budget. */+ function writeTask(key: string, status: string, closedAt?: string): void {+ writeFrontmatterAtomic(+ join(brainGapTasksDir(vault), `${key}.md`),+ {+ kind: GAP_TASK_KIND,+ gap_key: key,+ gap_topic: key,+ gap_source: GAP_SOURCE_TELEMETRY,+ status,+ occurrences: "3",+ created_at: "2026-01-01T00:00:00.000Z",+ ...(closedAt !== undefined ? { closed_at: closedAt, closed_reason: "recalled" } : {}),+ },+ "body",+ { vaultForRelativePath: vault, overwrite: true },+ );+ }++ const FLAG_ON = {+ OPEN_SECOND_BRAIN_GAP_LOOP_ENABLED: "true",+ OPEN_SECOND_BRAIN_GAP_LOOP_THRESHOLD: "2",+ } as const;++ test("carries every count the promotion returns, not just the promotions", async () => {+ seedGap("alpha topic", 3);+ const run = await runHook(+ "gap-promote",+ { hook_event_name: "SessionEnd" },+ { VAULT_DIR: vault, ...FLAG_ON },+ );+ expect(run.exit).toBe(0);+ const [details] = auditDetails();+ expect(details).toBeDefined();+ expect(Object.keys(details ?? {}).toSorted()).toEqual([+ "capped",+ "closed",+ "kept",+ "promoted",+ "pruned",+ "skipped",+ ]);+ expect(details?.["promoted"]).toBe(1);+ expect(details?.["pruned"]).toBe(0);+ expect(details?.["capped"]).toBe(0);+ });++ test("reports a closed task removed under the retention window as pruned", async () => {+ const stale = new Date(Date.now() - GAP_TASK_CLOSED_RETENTION_MS - 60_000).toISOString();+ writeTask("gap-stale", GAP_TASK_STATUS_CLOSED, stale);+ const run = await runHook(+ "gap-promote",+ { hook_event_name: "SessionEnd" },+ { VAULT_DIR: vault, ...FLAG_ON },+ );+ expect(run.exit).toBe(0);+ const [details] = auditDetails();+ expect(details?.["pruned"]).toBe(1);+ expect(existsSync(join(brainGapTasksDir(vault), "gap-stale.md"))).toBe(false);+ });++ test("reports a refusal at the cap instead of an unremarkable run", async () => {+ // Closed-but-recent fillers fill the directory without giving the+ // auto-close pass anything to recall.+ const recent = new Date().toISOString();+ for (let i = 0; i < GAP_TASKS_MAX_NOTES; i++) {+ writeTask(`gap-filler-${i}`, GAP_TASK_STATUS_CLOSED, recent);+ }+ seedGap("alpha topic", 3);+ const run = await runHook(+ "gap-promote",+ { hook_event_name: "SessionEnd" },+ { VAULT_DIR: vault, ...FLAG_ON },+ );+ expect(run.exit).toBe(0);+ const [details] = auditDetails();+ expect(details?.["capped"]).toBe(1);+ expect(details?.["promoted"]).toBe(0);+ expect(listGapTasks(vault)).toHaveLength(GAP_TASKS_MAX_NOTES);+ });+});+describe("gap-agenda hook (SessionStart)", () => {test("flag off is a silent no-op: no stdout", async () => {seedGap("alpha topic", 3);diff --git a/tests/mcp/brain-feedback-routing-hint.test.ts b/tests/mcp/brain-feedback-routing-hint.test.tsnew file mode 100644index 00000000..0504e39d--- /dev/null+++ b/tests/mcp/brain-feedback-routing-hint.test.ts@@ -0,0 +1,136 @@+/**+ * Unit 4 (t_75597bb9): the `brain_feedback` MCP surface of the+ * unroutable-capture routing hint.+ *+ * The tool records the signal exactly as before and, when the call+ * resolved no effective scope, carries the structured hint alongside the+ * write. The hint is a field on an otherwise unchanged payload: it never+ * gates the write and never appears when the vault has no scope corpus.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { bootstrapBrain } from "../../src/core/brain/init.ts";+import { resolveNextStep } from "../../src/core/brain/next-step.ts";+import { writePreference } from "../../src/core/brain/preference.ts";+import { BRAIN_PREFERENCE_STATUS } from "../../src/core/brain/types.ts";+import { CAPTURE_ROUTING_HINT_CODE } from "../../src/core/brain/write-advisory.ts";+import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";++let tmp: string;+let vault: string;+let configPath: string;++const NOW = "2026-07-27T12:00:00Z";++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-mcp-routing-hint-"));+ vault = join(tmp, "vault");+ configPath = join(tmp, "config.yaml");+ writeFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);+ bootstrapBrain(vault, { configPath });+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++async function initialize(server: MCPServer): Promise<void> {+ await server.handleRequest({+ jsonrpc: JSONRPC_VERSION,+ id: 1,+ method: "initialize",+ params: {+ protocolVersion: PROTOCOL_VERSION,+ capabilities: {},+ clientInfo: { name: "routing-hint-test", version: "0" },+ },+ });+ await server.handleRequest({ jsonrpc: JSONRPC_VERSION, method: "notifications/initialized" });+}++async function callTool(+ server: MCPServer,+ name: string,+ args: Record<string, unknown>,+): Promise<Record<string, unknown>> {+ const response = (await server.handleRequest({+ jsonrpc: JSONRPC_VERSION,+ id: 9,+ method: "tools/call",+ params: { name, arguments: args },+ })) as+ | { result: { content: ReadonlyArray<{ type: string; text: string }> } }+ | { error: { message: string } };+ if ("error" in response) throw new Error(response.error.message);+ return JSON.parse(response.result.content[0]!.text);+}++function confirmScoped(slug: string, scope: string): void {+ writePreference(vault, {+ slug,+ topic: slug,+ principle: `principle for ${slug}`,+ created_at: NOW,+ unconfirmed_until: NOW,+ confirmed_at: NOW,+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ evidenced_by: ["[[sig-2026-07-27-seed]]"],+ scope,+ });+}++const capture = { topic: "unrouted", signal: "positive", principle: "capture this somewhere" };++describe("brain_feedback - unroutable-capture routing hint", () => {+ test("a scope-less call on a scoped vault carries the hint beside the write", async () => {+ confirmScoped("tabs", "coding");+ confirmScoped("naming", "coding");+ confirmScoped("tone", "writing");+ const server = new MCPServer({ vault, configPath });+ await initialize(server);++ const payload = await callTool(server, "brain_feedback", capture);++ // The write landed.+ expect(payload["kind"]).toBe("signal");+ expect(String(payload["signal_id"])).toMatch(/^sig-/);+ const hint = payload["routing_hint"] as {+ missing_signal: string;+ code: string;+ candidates: ReadonlyArray<{ scope: string; documents: number }>;+ next_command?: string;+ };+ expect(hint.missing_signal).toBe("scope");+ expect(hint.code).toBe(CAPTURE_ROUTING_HINT_CODE);+ expect(hint.candidates).toEqual([+ { scope: "coding", documents: 2 },+ { scope: "writing", documents: 1 },+ ]);+ expect(hint.next_command).toBe(resolveNextStep(CAPTURE_ROUTING_HINT_CODE)!.nextCommand);+ });++ test("an explicit scope leaves the payload without the key", async () => {+ confirmScoped("tone", "writing");+ const server = new MCPServer({ vault, configPath });+ await initialize(server);++ const payload = await callTool(server, "brain_feedback", { ...capture, scope: "coding" });++ expect(String(payload["signal_id"])).toMatch(/^sig-/);+ expect("routing_hint" in payload).toBe(false);+ });++ test("a vault with no scope corpus stays silent", async () => {+ const server = new MCPServer({ vault, configPath });+ await initialize(server);++ const payload = await callTool(server, "brain_feedback", capture);++ expect(String(payload["signal_id"])).toMatch(/^sig-/);+ expect("routing_hint" in payload).toBe(false);+ });+});diff --git a/tests/mcp/ingest-tool-ignore-warnings.test.ts b/tests/mcp/ingest-tool-ignore-warnings.test.tsnew file mode 100644index 00000000..f341a79d--- /dev/null+++ b/tests/mcp/ingest-tool-ignore-warnings.test.ts@@ -0,0 +1,86 @@+/**+ * t_4b2bd8f7 follow-through: `brain_ingest_batch_plan`'s MCP payload surfaces+ * the planner's `ignoreWarnings` (a malformed pattern in the repository's OWN+ * ignore files) as structured fields, following the same "emit only when+ * non-empty" idiom `skipped_non_extractable` already uses. A clean tree must+ * serialize byte-identically to before: no key, not an empty array.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { join } from "node:path";+import { tmpdir } from "node:os";++import { bootstrapBrain } from "../../src/core/brain/init.ts";+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";+import { INGEST_TOOLS } from "../../src/mcp/brain/ingest-tools.ts";+import type { ServerContext } from "../../src/mcp/tool-contract.ts";++let vault: string;+let configHome: string;+let ctx: ServerContext;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-ingest-tool-warn-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-ingest-tool-warn-cfg-"));+ const configPath = join(configHome, "config.yaml");+ atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);+ bootstrapBrain(vault, { configPath });+ ctx = { vault, configPath, repoRoot: null };+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++function write(rel: string, content = "hello\n"): void {+ const abs = join(vault, rel);+ mkdirSync(join(abs, ".."), { recursive: true });+ writeFileSync(abs, content, "utf8");+}++const batchPlan = INGEST_TOOLS.find((t) => t.name === "brain_ingest_batch_plan")!.handler;++describe("brain_ingest_batch_plan ignore_warnings (t_4b2bd8f7 follow-through)", () => {+ test("a malformed .gitignore pattern surfaces as a structured ignore_warnings entry", async () => {+ write("Docs/keep.md");+ write("Docs/.gitignore", "keep-nothing.md\n[unterminated\n");++ const res = (await batchPlan(ctx, { source_dir: "Docs" })) as Record<string, unknown>;++ expect(res["ignore_warnings"]).toEqual([+ {+ source: "Docs/.gitignore",+ line: 2,+ pattern: "[unterminated",+ reason: expect.stringContaining("unterminated"),+ },+ ]);+ // The plan still succeeds and the file is still discovered (nothing is+ // silently dropped by the malformed pattern).+ expect(res["total_files"]).toBe(1);+ expect(typeof res["plan_id"]).toBe("string");+ });++ test("a warning never changes the plan's planId versus the same tree without it", async () => {+ write("Docs/keep.md");+ const clean = (await batchPlan(ctx, { source_dir: "Docs" })) as Record<string, unknown>;++ write("Docs/.gitignore", "[unterminated\n");+ const withWarning = (await batchPlan(ctx, { source_dir: "Docs" })) as Record<string, unknown>;++ expect(withWarning["plan_id"]).toBe(clean["plan_id"]);+ expect(withWarning["total_files"]).toBe(1);+ });++ test("a clean tree produces a byte-identical payload: the key is absent, not empty", async () => {+ write("Docs/a.md");+ write("Docs/b.md");++ const res = (await batchPlan(ctx, { source_dir: "Docs" })) as Record<string, unknown>;++ expect("ignore_warnings" in res).toBe(false);+ expect(res).not.toHaveProperty("ignore_warnings");+ });+});diff --git a/tests/mcp/recall-adequacy-tool.test.ts b/tests/mcp/recall-adequacy-tool.test.tsindex 0c4ba7f5..e96ff158 100644--- a/tests/mcp/recall-adequacy-tool.test.ts+++ b/tests/mcp/recall-adequacy-tool.test.ts@@ -10,6 +10,7 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";+import { aggregateUnmetRecall } from "../../src/core/brain/query-demand.ts";import { buildToolTable, findTool } from "../../src/mcp/tools.ts";import type { ServerContext } from "../../src/mcp/tool-contract.ts";@@ -123,3 +124,40 @@ test("context_pack omits adequacy when recall_scores is absent", async () => {})) as { adequacy?: unknown };expect(packed.adequacy).toBeUndefined();});++// ----- one feature, one opt-in ---------------------------------------------+//+// The unmet-verdict stamp on the cross-query demand log is ONE durable+// write reachable from two surfaces. It is gated by the+// `recall_gate_telemetry` config key on both - never by the pack's own+// per-call `telemetry` argument, which selects whether that call emits its+// OWN continuity records and says nothing about this log.++function unmetTopics(): ReadonlyArray<string> {+ return aggregateUnmetRecall(vault).map((bucket) => bucket.key);+}++test("with the flag off neither surface writes the demand log", async () => {+ await tool("brain_recall_gate").handler(ctx(), { prompt: "reactor coolant", scores: [] });+ await tool("brain_context_pack").handler(ctx(), {+ max_tokens: 1000,+ query: "reactor coolant",+ recall_scores: [],+ telemetry: true,+ });+ expect(unmetTopics()).toEqual([]);+});++test("with the flag on both surfaces write it, pack telemetry argument or not", async () => {+ writeFileSync(configPath, `vault: "${vault}"\nrecall_gate_telemetry: "true"\n`);+ await tool("brain_recall_gate").handler(ctx(), { prompt: "reactor coolant", scores: [] });+ expect(unmetTopics().length).toBeGreaterThan(0);++ const before = unmetTopics().length;+ await tool("brain_context_pack").handler(ctx(), {+ max_tokens: 1000,+ query: "turbine bearing vibration",+ recall_scores: [],+ });+ expect(unmetTopics().length).toBeGreaterThan(before);+});