/vault-mirror

name: vault-mirror
description: >
  Use when you need to populate the Meta-Vault with machine-generated notes derived from
  session-orchestrator JSONL records. Converts entries from `.orchestrator/metrics/sessions.jsonl` and
  `.orchestrator/metrics/learnings.jsonl` into vault-conformant Markdown under `50-sessions/` and
  `40-learnings/`. Called automatically at session-end Phase 3.7 and after evolve Phase 3.5 — only when
  `vault-integration.enabled=true` and `vault-integration.mode != "off"`. Idempotent: re-runs safely;
  skips hand-authored notes. Triggers: "mirror to vault", "sync session notes to vault", "write learning
  notes to vault", "vault-mirror failed at session close". <example>Context: session-end is finalizing,
  vault-integration.mode is "warn". user: "/close" assistant: "Running vault-mirror to write
  50-sessions/session-2026-05-17.md from the closing session record — 1 created, 0 skipped."</example>
user-invocable: false
model: haiku

Vault Mirror Skill

> Project-instruction file resolution: `CLAUDE.md` and `AGENTS.md` (Codex CLI) are transparent aliases — see [skills/_shared/instruction-file-resolution.md](../_shared/instruction-file-resolution.md). When this skill mentions Session Config in `CLAUDE.md`, the alias rule applies.

Purpose

vault-mirror populates the Meta-Vault with machine-generated notes derived from structured JSONL records. It converts entries from `.orchestrator/metrics/sessions.jsonl` and `.orchestrator/metrics/learnings.jsonl` into vault-conformant Markdown files under numeric-prefix subdirectories. This is distinct from vault-sync, which validates the vault — vault-sync validates the vault; vault-mirror populates it. The two skills are complementary: vault-mirror writes notes, vault-sync checks that the vault as a whole remains conformant.

When Invoked

vault-mirror is called in two places:

• **Phase 3.7 of session-end** (`skills/session-end/session-metrics-write.md`) — mirrors the sessions.jsonl entry for the closing session.
• **Phase 3.5 of evolve** (`skills/evolve/SKILL.md`) — mirrors all learnings.jsonl entries added during the evolve cycle.

Both call sites are conditional: vault-mirror runs only when `vault-integration.enabled == true` AND `vault-integration.mode != "off"` in the project's Session Config. When either condition is not met, the call site skips silently and vault-mirror is never invoked.

Inputs

`scripts/vault-mirror.mjs` is the implementation (call it by its plugin path, `"$PLUGIN_ROOT/scripts/vault-mirror.mjs"` — never `cd` into the plugin checkout to run it). `--vault-dir`, `--source` and `--kind` are required; `node "$PLUGIN_ROOT/scripts/vault-mirror.mjs" --help` lists every flag.

| Flag | Type | Required | Description | |---|---|---|---| | `--vault-dir` | path | yes | Absolute path to the Meta-Vault root directory. Must exist. | | `--source` | path | yes | Path to the JSONL file to read (one JSON object per line). Must exist. Pass it absolute — a relative path resolves against the cwd. | | `--kind` | `session` or `learning` | yes | Determines which generator and target path are used. | | `--repo-root` | path | no | The repo whose ledger `--source` is (#1503). Its `.vault.yaml` slug / git remote decides the vault namespace. Default: the project holding `--source` (`<root>/.orchestrator/metrics/<file>` → `<root>`, so a monorepo package with its own `.orchestrator/` keeps its own namespace), else the git repo containing it, else the cwd (only for a loose source outside any git repo, with a stderr `WARN`). Callers pass `--repo-root "$PWD"` from the repo root. | | `--dry-run` | flag | no | Parse and resolve paths but do not write any files. Emits action lines as normal. |

Empty lines in the JSONL source are silently skipped.

Outputs

One JSON line is written to stdout for each non-empty JSONL entry processed. Exit code reflects the run outcome. Diagnostics (`SKIP …`, `WARN …`, refusals) go to stderr and are NOT JSON — a caller that captures `2>&1` must parse line by line (`jq -R -r 'fromjson? | objects | …'`), or one `SKIP` line ends the parse and drops every action after it.

Action values

| `action` | Meaning | |---|---| | `created` | Entry did not exist in the vault; file created. | | `updated` | Entry existed (generator marker present, same id) with an older `updated` date; file overwritten. | | `skipped-noop` | Entry existed, same id, `updated` date not advanced; file unchanged. | | `skipped-handwritten` | A file at the target path has no `_generator` marker (or an unknown generator); left untouched. | | `skipped-collision-resolved` | A file at the target path has the generator marker but a different `id`; a disambiguated slug was used instead. | | `skipped-foreign-owner` | A generator note at the target path was rendered from another record (#1503), and this write must not replace it. **Sessions:** its `source-record` differs from this write and occurs nowhere in this `--source` ledger (`reason: "source-record mismatch"`), or its `id` names a different session (`reason: "id mismatch"`). **Learnings:** only for the disambiguated `<slug>-<uuid8>.md` file — a mismatch on the main `<slug>.md` is routed to disambiguation instead (`skipped-collision-resolved`, see Idempotency rule 6). One `SKIP foreign owner` line goes to stderr; `--force` does not bypass it. A leak in the foreign note is masked in place — owner, content and `source-record` kept — and the line carries `healed_leak: true`. A note without `source-record` (written before #1503) stays writable. | | `skipped-invalid` | Entry is missing one or more required fields; entry skipped, processing continues. | | `skipped-quality-low` | Learning `confidence` below `vault-mirror.quality.min-confidence` (CLI: `--quality-min-confidence`, default `0.5`), or a metrics-only session whose note ALREADY exists (left untouched; the pruner decides). Carries `reason` and `path: null`. Runs **before** `--force`; `--force` does not bypass it. | | `sk