oh-my-second-brain 0.1.9 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.2.0] - 2026-08-19
+
+### Added
+- The npm package now ships `CHANGELOG.md`, so release notes are available offline and in version control.
+- Releases are published by CI from `oms-v*` tags with npm provenance and an auto-generated GitHub Release whose notes come from the CHANGELOG.
+- Maintainers release with a single command: `npm run release -- <X.Y.Z>` rolls the `[Unreleased]` section into a versioned entry, bumps all version carriers (package.json, plugin manifests), commits, tags, and pushes atomically.
+
+#### Note linking
+
+- `term` is now a first-class concept in the core ontology, bound to a `terms/` folder. A term note is the one place you define a piece of vocabulary, and its new `aliases` frontmatter field lists every other way you write that word.
+- Two MCP tools turn those terms into links. `oms_link_suggest` is read-only: it ranks the spans in a note that could point at a term note and hands back a hash of the content it looked at. `oms_link_apply` writes, but only the candidates you accepted, and only while that hash still matches, so a note you edited in the meantime is never overwritten by a stale suggestion.
+- `oms linkify [--folder <f>] [--apply] [--yes]` does the same job in bulk over notes you already have. It reports and changes nothing by default; mutation needs both `--apply` and `--yes`.
+- Matching understands Korean josa, so `아타락시아를` links as `[[ataraxia|아타락시아]]를` instead of being skipped for not matching the bare term.
+- A note-linking skill ships to Claude, Codex, and Hermes, so each host knows the suggest-review-apply loop without you explaining it every session.
+
+#### Updates and install
+
+- A root `.claude-plugin/marketplace.json` makes OMS discoverable through Claude Code's native plugin marketplace. Claude installs now go through `claude plugin marketplace add` plus `claude plugin install oms@oms`, and fall back to the local plugin path when the marketplace flow can't complete, so offline and dev checkouts still work.
+- The MCP server tells you when a newer version exists. It reads a 24-hour cache at boot and appends one line to its `instructions`; the registry lookup happens in a bounded background refresh, never on the startup path. `OMS_UPDATE_NOTICE=0` turns it off.
+- A test and a CI release-tag guard now check that `marketplace.json` and `package.json` agree on the version, so a release can't ship a marketplace manifest pointing at the wrong build.
+
+### Changed
+
+- Wikilinks resolve through frontmatter `aliases`. `[[some-alias]]` used to resolve to nothing; it now finds the note that claims that alias, which means alias links count as real graph edges during retrieval.
+- Installing several hosts at once no longer stops at the first failure. Each runtime is isolated, so a broken Codex config can't cost you your Claude and Hermes install.
+- Hermes config writes are an upsert instead of a full overwrite: your comments and key ordering in `~/.hermes/config.yaml` survive an install or update.
+- Claude's third-party marketplace auto-update stays off unless you turn it on. Install prints how to enable `extraKnownMarketplaces.<name>.autoUpdate` in `~/.claude/settings.json` rather than flipping it for you; the `claude` CLI owns that setting.
+
+### Fixed
+
+- The MCP server reports its real package version instead of a hardcoded `0.0.0`, so host-side version checks and bug reports show what you're actually running.
+
+## [0.1.9] - 2026-08-14
+
+### Added
+- MCP `write` is now the single vault write window, with `mode: create | append | update`, returning `ask`, `inbox`, `written`, or `rejected` so the agent always knows what happened to a note (#52).
+- A contract gate validates required fields, types, enums, and routing law before anything touches the vault. Extra keys survive the round trip (`additionalProperties: preserve`).
+- Thin write skills for each host: `/oms-write` on Claude, `$oms-write` on Codex, and `write` on Hermes.
+
+### Changed
+- **Breaking:** capture skills are gone (`/oms-capture`, `$oms-capture`, Hermes `capture`), along with the MCP aliases `oms_capture_prepare` and `oms_capture_commit`. After upgrading, reinstall the host adapters with `oms update --yes` or `oms install --runtime <host> --vault <path> --yes`.
+
+### Fixed
+- Transitive production advisories cleared through same-major overrides for `hono`, `@hono/node-server`, `body-parser`, `fast-uri`, `ip-address`, `nanoid`, and `tar`. No new runtime dependencies were added.
+
+## [0.1.8] - 2026-06-17
+
+### Fixed
+- Upstage Solar embeddings work again: the model id `solar-embedding-1-passage` didn't exist, so every embedding call returned HTTP 400. It's now `embedding-passage` (4096d).
+- `embed()` guards its inputs. Empty input becomes a zero vector, and input over 4000 tokens is shrunk and retried, so one oversized or empty chunk no longer fails a whole vault sync.
+- Transitive high-severity advisory in `hono` (pulled in by `@modelcontextprotocol/sdk`) resolved via `overrides: hono ^4.12.25`.
+
+### Changed
+- Claude Code, Codex, and Hermes adapter manifests are synced to 0.1.8.
+
+## [0.1.7] - 2026-06-05
+
+> No GitHub Release was published for the `oms-v0.1.7` tag. This section is reconstructed from the commits between `oms-v0.1.6` and `oms-v0.1.7`.
+
+### Added
+- Live graph retrieval plus fail-soft qmd fusion, so retrieval keeps working when the optional qmd side is unavailable.
+- MCP retrieval context surfaced to hosts.
+
+### Changed
+- The npm package root is the runtime asset root: built releases resolve `core/` and `adapters/` from the package root, matching the source layout.
+- `oh-my-second-brain` becomes the canonical repository, npm package, and installed command, with `oms` kept as a compatibility alias for existing MCP, skill, and vault `.oms` surfaces.
+- Install docs point at 0.1.7 so the one-line and npm install examples resolve to the published version.
+- The release workflow no longer requires an `NPM_TOKEN` preflight, allowing npm trusted publishing over OIDC while still using `NODE_AUTH_TOKEN` when the secret exists.
+
+### Fixed
+- Frontmatter diagnostics are tolerant: malformed frontmatter no longer blocks retrieve or build paths.
+
+## [0.1.6] - 2026-06-02
+
+### Changed
+- The project is published to npm as `oh-my-second-brain`, while `oms` stays the CLI, MCP, skill, and repo slug.
+- The installer defaults to the published npm package instead of `npx` against GitHub release URLs.
+- Host MCP registration now points at the installed `oms mcp --vault ...` command.
+
+## [0.1.5] - 2026-06-02
+
+### Changed
+- Oh My Second Brain is the project and display name; `oms` remains the short technical slug for the package, CLI, MCP server, skills, and release assets.
+- Human-facing docs, adapter manifests, host shims, skills, CLI output, MCP tool titles, and installer text all use the Oh My Second Brain name.
+- Release package URLs point at `oms-v0.1.5` / `oms-0.1.5.tgz`.

package/adapters/claude-code/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "oms",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "Oh My Second Brain convention layer for Obsidian vaults — capture, retrieve, and validate knowledge under a declared semantic convention.",
   "author": {
     "name": "gobeumsu"

package/adapters/claude-code/skills/link/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: oms-link
+description: Two-path note-linking skill — Path A (pre-write): compose a new note body that already carries [[wikilinks]] to existing term notes; Path B (retrofit): add missing links to existing notes via oms linkify or oms_link_apply.
+---
+
+# Skill: oms-link (Claude Code)
+
+Two-path skill — thin pointer to `core/skills/link`. Requires `OMS_VAULT`.
+
+## Invocation
+
+```
+/link
+```
+
+## Which path?
+
+Check **before acting**:
+- **Path A (pre-write):** you are about to write the note → learn the term
+  vocabulary first, then draft a body that already contains `[[wikilinks]]`.
+- **Path B (retrofit):** the note already exists → `oms linkify` or
+  MCP `oms_link_suggest` → `oms_link_apply`.
+
+These paths are **mutually exclusive**.
+
+## The link universe
+
+Only notes bound to the `term` concept in `vault/.oms/taxonomy.yaml` are link
+targets; their surface forms are the basename and the frontmatter `aliases`.
+`0 term note(s) available as link targets` means the vault has no term layer —
+build one with the `wiki` skill first.
+
+Three engine rules, not negotiable:
+- **Surface-anchored** — a link exists only where the term literally appears.
+- **First occurrence only** — one link per target note per body.
+- **Ambiguity is reported, never resolved** — `ambiguous: true` plus `rivalPaths`
+  means ask the user or skip the span.
+
+Frontmatter, code, existing links, headings, URLs, and tags are masked out; a
+"missing" link inside any of them is correct.
+
+---
+
+## Path A — pre-write linking
+
+*(Only while drafting, so no retrofit pass is ever needed for this note.)*
+
+### Agent-guided steps
+
+1. Call MCP `oms_link_suggest` on an existing note in the same folder (or
+   `oms linkify --folder <folder>` in report mode) and read the `targetPath`
+   list — that is the vault's current term vocabulary.
+2. Draft the body with those exact surface forms, writing `[[wikilinks]]` inline
+   at the first mention of each term.
+3. Commit via MCP `write`. Host `Write`/`Edit` never touches vault `.md`.
+4. Re-check with `oms_link_suggest`; zero candidates means the draft was already
+   fully linked.
+
+---
+
+## Path B — retrofit existing notes
+
+*(Only when the note is already on disk. Report first, always.)*
+
+### Batch
+
+```bash
+oms linkify --folder notes                  # report only, writes nothing
+oms linkify --folder notes --apply --yes    # rewrite in place
+```
+
+`--apply` without `--yes` refuses before reading any note and writes nothing.
+Show the report and get agreement before adding `--yes`. Writes go through the
+capture kernel, so path safety and the concept contract hold.
+
+### Single note
+
+1. `oms_link_suggest { notePath, folder? }` → candidates + `baseContentHash`.
+2. Present the candidates; drop ambiguous ones the user does not resolve.
+3. `oms_link_apply { notePath, baseContentHash, candidateIds, folder? }` — pass
+   back the same `baseContentHash` and the same `folder` scope.
+
+`oms_link_apply` refuses without writing on `note-changed`, `candidate-drift`,
+or overlapping candidates. Re-run `oms_link_suggest` for fresh offsets instead
+of retrying stale ids.
+
+After a retrofit run, run `oms doctor` (non-blocking, exits 0).

package/adapters/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "oms",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "Oh My Second Brain convention layer for Obsidian vaults \u2014 Codex native rules, skills, and MCP adapter.",
   "_note": "oms install writes Codex MCP config, installs ~/.codex/rules/oms.md, and installs ~/.codex/skills/oms-*.",
   "skills": "./skills/",

package/adapters/codex/skills/oms-link/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: oms-link
+description: Two-path note-linking skill — Path A (pre-write): compose a new note body that already carries [[wikilinks]] to existing term notes; Path B (retrofit): add missing links to existing notes via oms linkify or oms_link_apply.
+---
+
+# oms-link
+
+Thin pointer to `core/skills/link`. Requires `OMS_VAULT`.
+
+Determine which path applies before acting. These paths are **mutually exclusive**.
+
+Link targets are ONLY notes bound to the `term` concept in `vault/.oms/taxonomy.yaml`; their surface forms are the basename and the frontmatter `aliases`. Three engine rules hold in both paths: a link exists only where the term literally appears (surface-anchored, never invented by retrieval); first occurrence per target note only; ambiguity (`ambiguous: true` + `rivalPaths`) is reported and never auto-resolved — ask the user or skip the span. Frontmatter, code, existing links, headings, URLs, and tags are masked out, so a "missing" link inside any of them is correct.
+
+## Path A — pre-write linking
+
+*(Use while drafting, so the note lands already linked and needs no retrofit.)*
+
+1. Call MCP `oms_link_suggest` on an existing note in the same folder (or run `oms linkify --folder <folder>` in report mode) and read the `targetPath` list — that is the vault's current term vocabulary.
+2. Draft the body with those exact surface forms, writing `[[wikilinks]]` inline at the first mention of each term.
+3. Commit via MCP `write`. Host file edits never touch vault `.md`.
+4. Re-check with `oms_link_suggest`: zero candidates means the draft was already fully linked.
+
+NOTE: `0 term note(s) available as link targets` means the vault has no term layer yet — build one with the `oms-wiki` skill first.
+
+## Path B — retrofit existing notes
+
+*(Use when the note is already on disk. Report first, always.)*
+
+1. `oms linkify --folder <folder>` — report only, writes nothing.
+2. Show the report and get agreement before mutating anything.
+3. Whole folder → `oms linkify --folder <folder> --apply --yes`. `--apply` without `--yes` refuses before reading any note and writes nothing.
+4. Per-note acceptance → `oms_link_suggest { notePath, folder? }` returns candidates plus `baseContentHash`; drop unresolved ambiguous ones; then `oms_link_apply { notePath, baseContentHash, candidateIds, folder? }` with the SAME `baseContentHash` and the SAME `folder` scope.
+5. Run `oms doctor` after a retrofit run (non-blocking, exits 0).
+
+NOTE: `oms_link_apply` refuses without writing on `note-changed`, `candidate-drift`, or overlapping candidates. Re-run `oms_link_suggest` for fresh offsets instead of retrying stale ids. Every write — CLI or MCP — goes through the capture kernel, so path safety and the concept contract hold.

package/adapters/hermes/README.md

@@ -6,3 +6,5 @@ Installed by `oms install --runtime hermes` into:
 - `~/.hermes/config.yaml` as `mcp_servers.oms`
 
 The skill bundle mirrors Oh My Second Brain's write/retrieve/setup/doctor lifecycle and uses the Oh My Second Brain MCP server for runtime operations.
+
+Unlike Claude Code (`claude plugin install`), Hermes exposes no native marketplace or plugin-update command, so this adapter stays OMS-managed: `oms update` reconciles it by re-running the same install path. `mcp_servers.oms` is edited surgically, leaving the rest of `~/.hermes/config.yaml` — including comments and key ordering — untouched.

package/adapters/hermes/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "oms",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "Oh My Second Brain convention layer for Obsidian vaults \u2014 Hermes skill bundle and MCP adapter.",
   "_note": "oms install writes ~/.hermes/config.yaml mcp_servers.oms and installs skills under ~/.hermes/skills/knowledge-management/oms/.",
   "skills": "./skills/"

package/adapters/hermes/skills/link/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: link
+description: Two-path note-linking skill — Path A (pre-write): compose a new note body that already carries [[wikilinks]] to existing term notes; Path B (retrofit): add missing links to existing notes via oms linkify or oms_link_apply.
+---
+
+# oms-link
+
+Thin pointer to `core/skills/link`. Requires `OMS_VAULT`.
+
+Link targets are ONLY notes bound to the `term` concept in `vault/.oms/taxonomy.yaml`; their surface forms are the basename and the frontmatter `aliases`. Three engine rules hold in both paths: a link exists only where the term literally appears (surface-anchored — retrieval never invents one); first occurrence per target note only; ambiguity (`ambiguous: true` + `rivalPaths`) is reported, never auto-resolved — ask the user or skip the span. Frontmatter, code, existing links, headings, URLs, and tags are masked out, so a "missing" link inside any of them is correct.
+
+**Path A (pre-write) — use while drafting the note:** Call MCP `oms_link_suggest` on an existing note in the same folder (or run `oms linkify --folder <folder>` in report mode) and read the `targetPath` list — that is the vault's current term vocabulary. Draft the body with those exact surface forms, writing `[[wikilinks]]` inline at the first mention of each term, then commit via MCP `write` (host file edits never touch vault `.md`). Re-check with `oms_link_suggest`: zero candidates means the draft was already fully linked.
+
+NOTE: `0 term note(s) available as link targets` means the vault has no term layer yet — build one with the `wiki` skill first.
+
+**Path B (retrofit) — use when the note already exists:** Run `oms linkify --folder <folder>` first; it reports only and writes nothing. Show the report and get agreement before mutating. For a whole folder use `oms linkify --folder <folder> --apply --yes` — `--apply` without `--yes` refuses before reading any note and writes nothing. For per-note acceptance call `oms_link_suggest { notePath, folder? }` for candidates plus `baseContentHash`, drop unresolved ambiguous ones, then `oms_link_apply { notePath, baseContentHash, candidateIds, folder? }` with the SAME `baseContentHash` and the SAME `folder` scope. Run `oms doctor` afterwards (non-blocking, exits 0).
+
+NOTE: `oms_link_apply` refuses without writing on `note-changed`, `candidate-drift`, or overlapping candidates. Re-run `oms_link_suggest` for fresh offsets instead of retrying stale ids. Every write — CLI or MCP — goes through the capture kernel, so path safety and the concept contract hold. The two paths are mutually exclusive.

package/core/ontology/concepts/term.yaml

@@ -0,0 +1,12 @@
+concept: term
+intent: "A named unit of vocabulary the vault defines once and links to everywhere else."
+folder: terms
+fields:
+  - name: title
+    type: string
+    required: true
+    intent: "The canonical name of the term; the wikilink target other notes point at."
+  - name: aliases
+    type: list
+    required: false
+    intent: "Alternative surface forms and synonyms that should link back to this term."

package/core/ontology/taxonomy.yaml

@@ -9,3 +9,6 @@ folders:
   inbox:
     intent: "Raw unprocessed captures awaiting triage; nothing required yet."
     concept: inbox
+  terms:
+    intent: "Defined vocabulary the vault links to from other notes."
+    concept: term

package/core/skills/link/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: link
+version: 0.1.0
+description: Two-path note-linking skill — Path A (pre-write): compose a new note body that already carries [[wikilinks]] to existing term notes; Path B (retrofit): add missing links to notes that already exist, via oms linkify or oms_link_apply.
+trigger: /link
+tags: [link, wikilink, linkify, term, backlink, second-brain, oms]
+---
+
+## link
+
+Keep the vault interlinked. There is no autolink daemon — follow this recipe as
+the agent. Requires `OMS_VAULT` (or a resolved vault target).
+
+## Which path?
+
+Determine which path applies **before acting**:
+
+| | Path A — pre-write | Path B — retrofit |
+|---|---|---|
+| **When to use** | You are about to write or rewrite a note | The note already exists on disk |
+| **Entry point** | MCP `oms_link_suggest` on a sibling note, then MCP `write` | `oms linkify` (report) → `oms linkify --apply --yes`, or MCP `oms_link_suggest` → `oms_link_apply` |
+| **Writes to** | The new note only | Existing notes in scope |
+| **Prerequisite** | Term notes exist to link at | Term notes exist to link at |
+
+These paths are **mutually exclusive and never combined in a single invocation.**
+
+---
+
+## The link universe — term notes only
+
+A link target is a note bound to the `term` concept in `vault/.oms/taxonomy.yaml`.
+Notes bound to any other concept are never proposed as targets, in either path.
+Surface forms of a target are its **basename** and its frontmatter **`aliases`**.
+
+If a run reports `0 term note(s) available as link targets`, the vault has no
+term layer yet — build one with the `wiki` skill (Path B) first. Linking is not
+the tool that creates vocabulary; it is the tool that connects it.
+
+## Three rules the engine enforces — do not fight them
+
+1. **Surface-anchored.** A candidate exists only because the term's basename or
+   alias literally appears in the note. Retrieval never invents a link. Do not
+   hand-add a `[[link]]` to a note whose title does not appear in the text —
+   write the sentence that mentions it instead.
+2. **First occurrence only.** One link per target note per body. A term linked
+   ten times is noise, not navigation.
+3. **Ambiguity is reported, never auto-resolved.** When 2+ notes claim one span,
+   the candidate carries `ambiguous: true` and every `rivalPaths` entry. Ask the
+   user which note is meant, or skip the span. Never guess.
+
+Protected regions are masked out before matching: frontmatter, fenced and inline
+code, existing wikilinks and markdown links, image embeds, HTML, headings, URLs,
+block ids, and tags. A "missing" link inside any of those is correct behavior.
+
+---
+
+## Path A — pre-write linking
+
+*(Use while drafting. The goal is that the body arrives on disk already linked,
+so no retrofit pass is ever needed for this note.)*
+
+### Agent-guided steps
+
+1. Establish the vocabulary **before** drafting: call MCP `oms_link_suggest` on
+   an existing note in the same folder (or run `oms linkify --folder <folder>`
+   in report mode) and read the `targetPath` list. That list IS the vault's
+   current term vocabulary.
+2. Draft the body using those exact surface forms, and write `[[wikilinks]]`
+   inline as you compose — first mention of each term only.
+3. Commit through MCP `write`. Host `Write`/`Edit` never touches vault `.md`.
+4. Re-check with `oms_link_suggest` on the committed note. Zero candidates means
+   the draft was already fully linked; remaining candidates are terms you missed.
+
+### Example agent steps (Path A)
+
+```
+User: "Write a note about our retrieval pipeline."
+
+1. oms_link_suggest { notePath: "notes/software-engineering/indexing.md" }
+   → targets: notes/terms/embedding.md, notes/terms/reranker.md, notes/terms/chunk.md
+2. Draft body mentioning embedding / reranker / chunk, each first mention
+   written as [[embedding]], [[reranker]], [[chunk]]
+3. write { mode: "create", notePath: "notes/software-engineering/retrieval-pipeline.md", ... }
+4. oms_link_suggest on the new note → 0 candidates ✓
+```
+
+---
+
+## Path B — retrofit existing notes
+
+*(Use when the note is already on disk. Report first, always.)*
+
+### Batch — `oms linkify` (whole vault or one folder)
+
+```bash
+oms linkify --folder notes          # report only, writes nothing
+oms linkify --folder notes --apply --yes   # rewrite in place
+```
+
+`--apply` without `--yes` refuses before reading a single note and writes
+nothing. Show the user the report and get agreement before adding `--yes`.
+Every write still goes through the capture kernel, so path safety and the
+concept contract hold exactly as they do for MCP `write`.
+
+### Single note — `oms_link_suggest` → `oms_link_apply`
+
+Use when the user wants to accept some candidates and reject others:
+
+1. `oms_link_suggest { notePath, folder? }` → candidates + `baseContentHash`.
+2. Present the candidates; drop ambiguous ones the user does not resolve.
+3. `oms_link_apply { notePath, baseContentHash, candidateIds, folder? }` —
+   pass back the **same** `baseContentHash` and the **same** `folder` scope.
+
+`oms_link_apply` refuses without writing when the note changed since the
+suggest call (`note-changed`), when a candidate's text moved (`candidate-drift`),
+or when accepted candidates overlap. A refusal is a correct outcome: re-run
+`oms_link_suggest` for fresh offsets rather than retrying the stale ids.
+
+### Example agent steps (Path B)
+
+```
+User: "Link up the notes I wrote last week."
+
+1. oms linkify --folder notes            ← report only
+   → 14 candidate(s) across 9 note(s); 2 marked ambiguous
+2. Show the report; ask which note the 2 ambiguous spans mean
+3. Accepted whole folder → oms linkify --folder notes --apply --yes
+   Accepted per-note → oms_link_suggest → oms_link_apply with the chosen ids
+4. Run `oms doctor` (non-blocking, exits 0)
+```

package/dist/capture/safe.d.ts

@@ -1,5 +1,6 @@
 import { type WriteContractViolation, type WriteFieldDescriptor } from "../conventions/write-contract.js";
-import type { Ontology } from "../core/ontology/types.js";
+import { type WriteRejection, type WriteReceipt, type WriteTargetSource } from "../conventions/write-protocol.js";
+import type { Concept, Ontology } from "../core/ontology/types.js";
 export type CapturePrepareAction = "ready" | "ask-missing-fields" | "route-to-inbox";
 export type CaptureWriteMode = "create" | "append";
 export type WriteMode = "create" | "append" | "update";
@@ -23,8 +24,13 @@ export interface CapturePlan {
     violations: WriteContractViolation[];
     reason?: string;
 }
+export interface WriteTarget {
+    vault: string;
+    source: WriteTargetSource;
+}
 export interface CaptureCommitInput {
     vault: string;
+    source: WriteTargetSource;
     ontology: Ontology;
     notePath: string;
     frontmatter: Record<string, unknown>;
@@ -37,7 +43,7 @@ export interface CaptureCommitResult {
     notePath: string;
 }
 export interface WriteNoteInput {
-    vault: string;
+    target: WriteTarget;
     ontology: Ontology;
     mode: WriteMode;
     dryRun: boolean;
@@ -47,6 +53,12 @@ export interface WriteNoteInput {
     notePath?: string;
     frontmatter?: Record<string, unknown>;
     body?: string;
+    /**
+     * Test-only DI seam for the postcondition read-back. Defaults to reading the
+     * persisted file with node:fs/promises. Exists so tests can force a
+     * postcondition failure deterministically without mocking node:fs/promises.
+     */
+    readBack?: (fullPath: string) => Promise<string>;
 }
 export interface WriteNoteResult {
     status: WriteStatus;
@@ -59,8 +71,26 @@ export interface WriteNoteResult {
     missingFields: string[];
     violations: WriteContractViolation[];
     reason?: string;
+    rejection?: WriteRejection;
+    receipt?: WriteReceipt;
 }
 export declare function safeVaultNotePath(vault: string, notePath: string): string;
 export declare function prepareCapture(input: CapturePrepareInput): CapturePlan;
+export interface StagedEvaluation {
+    ok: boolean;
+    violations: WriteContractViolation[];
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+/**
+ * Acceptance Criteria - staged evaluation (pre-persist).
+ *
+ * Parses the note content that is ABOUT to be written and re-runs the kernel
+ * write contract against the RENDERED frontmatter. This catches divergence
+ * between the caller-supplied frontmatter and what actually lands on disk
+ * (yaml round-trip artifacts such as `NaN` rendering as `.nan` and parsing
+ * back as `null`).
+ */
+export declare function evaluateStagedNote(stagedContent: string, concept: Concept, notePath: string, strictZones: ReadonlySet<string>): StagedEvaluation;
 export declare function writeNote(input: WriteNoteInput): Promise<WriteNoteResult>;
 export declare function commitCapture(input: CaptureCommitInput): Promise<CaptureCommitResult>;