vault-mirror

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. All arguments are required except --dry-run.

| 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. | | --kind | session or learning | yes | Determines which generator and target path are used. | | --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.

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-invalid | Entry is missing one or more required fields; entry skipped, processing continues. | | skipped-quality-low | Entry failed the quality gate (PRD F1.2): learning confidence below vault-mirror.quality.min-confidence (CLI: --quality-min-confidence, default 0.5), or session rendered-narrative length below vault-mirror.quality.min-narrative-chars (CLI: --quality-min-narrative-chars, default 400). The emitted JSON line includes a reason field describing the violated threshold and path: null (no file was created). The quality gate runs before --force; --force does not bypass it. |

Output line shape

{"action":"created","path":"50-sessions/session-2026-04-13.md","kind":"session","id":"session-2026-04-13"}

path is relative to --vault-dir.

Exit codes

| Code | Meaning | |---|---| | 0 | Success (including idempotent no-ops and per-entry skips). | | 1 | Malformed JSON on a JSONL line — fatal, processing stops. Also returned when required CLI args are missing. | | 2 | Filesystem error: --vault-dir not found, --source not found, or an unexpected write error. |

Target Paths

| Kind | Target | |---|---| | session | <vault-dir>/50-sessions/<session-id>.md | | learning | <vault-dir>/40-learnings/<slug>.md |

Subdirectories are created automatically with mkdirSync({ recursive: true }) when writing (not in --dry-run mode).

The numeric prefix (50-sessions/, 40-learnings/) follows the vault folder ordering convention so that sessions and learnings appear in the correct position in the vault tree relative to other note types.

Path contract note: Issue #187 proposed <vault>/05-orchestrator/<repo>/ as the target layout. The shipped implementation uses numeric-prefix paths for vault ordering. If you need the issue-text path, file a new issue — do NOT silently change the script.

Idempotency

vault-mirror is safe to run multiple times against the same JSONL source:

1. No file exists → create.
2. File exists, _generator marker present, same id, updated date not advanced → skipped-noop, file unchanged.
3. File exists, _generator marker present, same id, updated date advanced → updated, file overwritten.
4. File exists, no _generator marker → skipped-handwritten, file untouched. The absence of the marker means the file was written by a human and must not be overwritten automatically.
5. File exists, _generator marker present, different id → slug collision. A disambiguated slug is derived by appending -<first-8-chars-of-entry-uuid> (hyphens stripped from the UUID before taking the prefix). The original file is left unchanged; the new note is written at the disambiguated path with action skipped-collision-resolved.

The generator marker value is session-orchestrator-vault-mirror@1 and appears in the YAML frontmatter as _generator: session-orchestrator-vault-mirror@1.

Failure Modes

| Condition | Behaviour | |---|---| | Entry missing a required field | skipped-invalid emitted on stdout, error written to stderr, exit 0 (processing continues for remaining entries). | | Malformed JSON on a JSONL line | Error written to stderr, exit 1 (processing stops). | | --vault-dir not found | Error written to stderr, exit 2. | | --source file not found | Error written to stderr, exit 2. | | Hand-written file at target path | skipped-handwritten emitted on stdout, note written to stderr, file left unchanged. | | Unknown _generator value in existing file | Treated as hand-written: skipped-handwritten, file left unchanged. | | Unexpected filesystem write error | Error written to stderr, exit 2. |

Examples

Mirror the sessions.jsonl for the current project into a vault:

node scripts/vault-mirror.mjs \
  --vault-dir ~/Projects/vault \
  --source .orchestrator/metrics/sessions.jsonl \
  --kind session

Dry-run a learnings mirror to preview actions without writing:

node scripts/vault-mirror.mjs \
  --vault-dir ~/Projects/vault \
  --source .orchestrator/metrics/learnings.jsonl \
  --kind learning \
  --dry-run

Live State

Phase 1 shipped and actively running. As of 2026-05-09, the skill has produced:

• 847 learning notes under vault://40-learnings/ — each carries _generator: session-orchestrator-vault-mirror@1 in the YAML frontmatter.
• 466 session notes under vault://50-sessions/ — same generator stamp.

Both target directories were verified by direct ls | wc -l measurement against ~/Projects/vault/. The numeric-prefix layout (40-learnings/, 50-sessions/) confirmed correct per the Target Paths spec above.

Configuration

vault-mirror respects the vault-integration block in the project's Session Config (CLAUDE.md, or AGENTS.md on Codex CLI). The script itself does not read Session Config — the calling skill (session-end, evolve) is responsible for reading the config and deciding whether to invoke vault-mirror at all.

| Field | Type | Default | Meaning | |---|---|---|---| | vault-integration.enabled | boolean | false | When false, the calling skill skips vault-mirror entirely. | | vault-integration.vault-dir | string | —