session-orchestrator 5.6.0 → 5.8.0

package/scripts/site-numbers.mjs

@@ -178,8 +178,9 @@ export function countSkills(root) {
 }
 
 /**
- * The product's "slash commands" number: `commands/*.md` ∪ skills carrying an
- * EXPLICIT `user-invocable: true`, deduplicated by name.
+ * The product's "slash commands" number: `commands/*.md` ∪ skills whose
+ * `user-invocable` is `true` or ABSENT (Claude Code lists a keyless skill in the
+ * `/` picker — #1515), deduplicated by name.
  *
  * NOT `ls commands/*.md | wc -l` any more, and the change is not cosmetic. After
  * the 2026-09-16 fold (#1370) `commands/` holds two files — `session` and
@@ -435,7 +436,7 @@ export const METRIC_DEFS = Object.freeze([
     id: 'commands',
     provenance: false,
     source:
-      'ls commands/*.md | wc -l  +  grep -l "^user-invocable: true" skills/*/SKILL.md | wc -l   (union by name — see countCommands)',
+      'ls commands/*.md | wc -l  +  grep -L "^user-invocable: *false" skills/*/SKILL.md | wc -l   (union by name; a skill without the key counts, as in Claude Code — see countCommands)',
     compute: (root) => fmtCount(countCommands(root)),
   },
   {

package/scripts/sweep-expired-learnings.mjs

@@ -123,7 +123,7 @@
  */
 
 import { existsSync, realpathSync, statSync } from 'node:fs';
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { mkdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import {
@@ -135,6 +135,7 @@ import {
   warnUnparseableLines,
 } from './lib/learnings/expiry-sweep.mjs';
 import { readLearningsSnapshot, parseLearningsText } from './lib/learnings/io.mjs';
+import { atomicWriteText, envelopeToError } from './lib/io.mjs';
 import { validateLearning } from './lib/learnings/schema.mjs';
 import { validatePathInsideProject } from './lib/path-utils.mjs';
 import { emitEvolveCompleted } from './lib/learnings/evolve-telemetry.mjs';
@@ -668,9 +669,10 @@ async function runSnapshot(args) {
       ...snap.entries.map((e) => JSON.stringify(e)),
     ];
     await mkdir(path.dirname(args.snapshot), { recursive: true });
-    const tmp = `${args.snapshot}.tmp-${process.pid}`;
-    await writeFile(tmp, lines.join('\n') + '\n', 'utf8');
-    await rename(tmp, args.snapshot);
+    const res = await atomicWriteText(args.snapshot, lines.join('\n') + '\n', {
+      tmpPrefix: `.${path.basename(args.snapshot)}.tmp`,
+    });
+    if (!res.ok) throw envelopeToError(res);
   } catch (err) {
     process.stderr.write(`sweep-expired-learnings: snapshot failed: ${err.message}\n`);
     process.exit(2);

package/scripts/sync-vault-schema.mjs

@@ -26,13 +26,9 @@
  *   2 — missing file
  *   3 — malformed sentinels (only one of begin/end present)
  *
- * Vendor-ahead state (2026-05-23, #503, I5):
- *   The vaultNoteTypeSchema enum in validator.mjs currently includes
- *   `peer-card` which is NOT yet present in the canonical
- *   projects-baseline source. Until #503 lands upstream, `--check` will
- *   report drift; this is expected and is tracked as upstream-sync-debt
- *   in the #503 PRD (W5 F2 docs agent owns the PRD update). Once
- *   upstream catches up, `--write` will become a no-op (idempotent).
+ * The #503 vendor-ahead state (`peer-card` in validator.mjs before the
+ * canonical source carried it) is resolved: projects-baseline has
+ * `peer-card`, and `--check` passed against baseline `9108018` (2026-10-04).
  */
 
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';

package/scripts/vault-mirror-prune.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * vault-mirror-prune.mjs — CLI for the mirror-zone retention prune (#1513).
+ *
+ * Applies the vault-mirror retention rules to the notes the mirror wrote
+ * BEFORE those rules existed: expired / superseded / duplicate learnings,
+ * metrics-only session notes (rolled up first), namespace-alias folders and
+ * flat legacy notes. All decisions live in `scripts/lib/vault-mirror/prune.mjs`
+ * (rules table in its header) and `retention.mjs`; this file is argv parsing,
+ * the manifest, output and exit codes.
+ *
+ * SAFETY: dry run is the DEFAULT and writes nothing — not even the manifest
+ * unless `--manifest` names a path. `--apply` moves files (archive → under
+ * `90-archive/mirror/`), never deletes a note's content, never touches a note
+ * without the mirror's `_generator` marker.
+ *
+ * Usage:
+ *   node scripts/vault-mirror-prune.mjs --vault-dir PATH [--apply]
+ *     [--manifest PATH] [--now ISO] [--min-narrative-chars N]
+ *     [--alias FROM=TO ...] [--json]
+ *
+ * Exit codes: 0 success · 1 usage error · 2 apply finished with per-path errors
+ */
+
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { expandTilde, redactHomeDir } from './lib/common.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+import { MANIFEST_SCHEMA, applyPrune, planPrune } from './lib/vault-mirror/prune.mjs';
+
+const HELP = `Usage: node scripts/vault-mirror-prune.mjs --vault-dir PATH [--apply] [--manifest PATH]
+       [--now ISO] [--min-narrative-chars N] [--alias FROM=TO ...] [--json]
+
+Plans (default) or applies the vault-mirror retention rules to 40-learnings/
+and 50-sessions/ of a vault. Only notes carrying the vault-mirror _generator
+marker are considered; hand-written notes are never touched.
+
+Options:
+  --vault-dir PATH          Vault root (required; no host-local default on purpose)
+  --apply                   Write: rollups, then archive moves to 90-archive/mirror/, then renames
+  --manifest PATH           Write the JSON manifest (path, reason, action, target) there
+  --now ISO                 Injected clock for the expiry check (default: now)
+  --min-narrative-chars N   Session narrative gate (default 400, as vault-mirror.quality)
+  --alias FROM=TO           Explicit namespace alias (repeatable); the hyphen rule applies without it
+  --json                    Print the summary as one JSON line
+
+Exit codes: 0 success  1 usage error  2 apply finished with per-path errors
+`;
+
+function usageError(msg) {
+  process.stderr.write(`vault-mirror-prune: ${msg}\n`);
+  process.exit(1);
+}
+
+export function parseArgs(argv) {
+  const args = { vaultDir: null, apply: false, manifest: null, now: null, minNarrativeChars: 400, aliases: {}, json: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    const value = () => {
+      const v = argv[i + 1];
+      if (v === undefined || v.startsWith('--')) usageError(`${a} needs a value`);
+      i += 1;
+      return v;
+    };
+    if (a === '--help' || a === '-h') {
+      process.stdout.write(HELP);
+      process.exit(0);
+    } else if (a === '--vault-dir') args.vaultDir = value();
+    else if (a === '--apply') args.apply = true;
+    else if (a === '--dry-run') args.apply = false;
+    else if (a === '--manifest') args.manifest = value();
+    else if (a === '--now') {
+      args.now = value();
+      if (!Number.isFinite(Date.parse(args.now))) usageError(`--now is not a date: ${args.now}`);
+    } else if (a === '--min-narrative-chars') {
+      const raw = value();
+      if (!/^\d+$/.test(raw)) usageError(`--min-narrative-chars must be a non-negative integer, got ${raw}`);
+      args.minNarrativeChars = Number(raw);
+    } else if (a === '--alias') {
+      const m = /^([a-z0-9][a-z0-9-]*)=([a-z0-9][a-z0-9-]*)$/.exec(value());
+      if (!m) usageError('--alias expects FROM=TO with lowercase kebab namespaces');
+      args.aliases[m[1]] = m[2];
+    } else if (a === '--json') args.json = true;
+    else usageError(`unknown argument ${a}`);
+  }
+  if (!args.vaultDir) usageError('--vault-dir is required');
+  return args;
+}
+
+export function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  const vaultDir = resolve(expandTilde(args.vaultDir));
+  const today = new Date(args.now ? Date.parse(args.now) : Date.now()).toISOString().slice(0, 10);
+  const plan = planPrune({ vaultDir, today, minNarrativeChars: args.minNarrativeChars, aliases: args.aliases });
+
+  const manifest = {
+    schema: MANIFEST_SCHEMA,
+    generated_at: new Date().toISOString(),
+    today,
+    dry_run: !args.apply,
+    min_narrative_chars: args.minNarrativeChars,
+    aliases: plan.aliases,
+    skipped_handwritten: plan.handwritten,
+    counts: plan.counts,
+    rollups: Object.fromEntries(Object.entries(plan.rollups).map(([k, rows]) => [k, rows.length])),
+    actions: plan.actions,
+  };
+  let applied = null;
+  if (args.apply) {
+    applied = applyPrune(plan, { vaultDir });
+    // The apply result belongs in the manifest: notes written beside an
+    // occupied archive target (`suffixed`) and per-path errors.
+    manifest.applied = applied;
+  }
+  if (args.manifest) writeFileSync(resolve(expandTilde(args.manifest)), JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+
+  const summary = {
+    dry_run: !args.apply,
+    counts: plan.counts,
+    rollups: Object.keys(plan.rollups).length,
+    aliases: plan.aliases,
+    skipped_handwritten: plan.handwritten,
+    ...(applied ? { applied: { ...applied, suffixed: applied.suffixed.length, errors: applied.errors.length } } : {}),
+  };
+  if (args.json) process.stdout.write(JSON.stringify(summary) + '\n');
+  else {
+    process.stdout.write(`vault-mirror-prune ${args.apply ? 'APPLY' : 'dry run'} (today ${today})\n`);
+    for (const [k, n] of Object.entries(plan.counts).sort()) process.stdout.write(`  ${k.padEnd(36)} ${n}\n`);
+    process.stdout.write(`  rollup notes                         ${Object.keys(plan.rollups).length}\n`);
+    for (const [from, to] of Object.entries(plan.aliases)) process.stdout.write(`  alias ${from} -> ${to}\n`);
+    if (applied) {
+      process.stdout.write(`  applied: archived ${applied.archived}, moved ${applied.moved}, rollups written ${applied.rollupsWritten}, suffixed ${applied.suffixed.length}, errors ${applied.errors.length}\n`);
+    }
+  }
+  if (applied && applied.errors.length > 0) {
+    for (const e of applied.errors.slice(0, 20)) process.stderr.write(`vault-mirror-prune: ${e.path}: ${redactHomeDir(e.error)}\n`);
+    return 2;
+  }
+  return 0;
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exit(main());
+}

package/scripts/vault-mirror.mjs

@@ -20,7 +20,7 @@
  *       `--repo-root` — #1503)
  *
  * Output: one JSON line per action on stdout:
- *   {"action":"created|updated|skipped-noop|skipped-handwritten|skipped-collision-resolved|skipped-foreign-owner|skipped-invalid|skipped-quality-low|skipped-abandoned|skipped-duplicate-session","path":"...","kind":"...","id":"..."}
+ *   {"action":"created|updated|skipped-noop|skipped-handwritten|skipped-collision-resolved|skipped-foreign-owner|skipped-invalid|skipped-quality-low|skipped-abandoned|skipped-duplicate-session|skipped-metrics-only|skipped-expired|skipped-duplicate-insight","path":"...","kind":"...","id":"..."}
  *
  * Idempotency rules:
  *   1. File does not exist → create.
@@ -45,8 +45,10 @@
  *
  * Quality gate (PRD F1.2):
  *   Learnings with confidence < --quality-min-confidence emit `skipped-quality-low`.
- *   Sessions with rendered-narrative length < --quality-min-narrative-chars emit
- *   `skipped-quality-low`. Quality gate runs BEFORE --force; --force does NOT
+ *   Sessions whose free text (`notes`/`narrative`/`summary`) is shorter than
+ *   --quality-min-narrative-chars get no note: `skipped-metrics-only` with one row
+ *   in the month rollup `50-sessions/<repo>/_rollup-YYYY-MM.md` (#1513; rules in
+ *   scripts/lib/vault-mirror/retention.mjs). Quality gate runs BEFORE --force; --force does NOT
  *   bypass the filter. Quality-skipped entries emit `path: null` and an
  *   additional `reason` field describing the violated threshold.
  *
@@ -65,14 +67,16 @@
  * Part of session-orchestrator vault-mirror (Issue #14).
  */
 
-import { existsSync, realpathSync } from 'node:fs';
-import { basename, dirname, resolve } from 'node:path';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
 import { createReadStream } from 'node:fs';
 
 import {
   processLearning,
   processSession,
+  processArchivedLearning,
+  learningNoteSlugs,
   getMaskerStats,
   emitAction,
 } from './lib/vault-mirror/process.mjs';
@@ -81,6 +85,7 @@ import { emitEvent } from './lib/events.mjs';
 import { autoCommitVaultMirror } from './lib/vault-mirror/auto-commit.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
 import { resolveRepoNamespace } from './lib/vault-mirror/namespace.mjs';
+import { SESSION_NARRATIVE_FIELDS, canonicalNamespace } from './lib/vault-mirror/retention.mjs';
 import { sessionSourceRecord } from './lib/vault-mirror/render-sessions.mjs';
 import { checkCanonicalVault, describeOriginForLog, findRepoRoot, normalizeRemote } from './lib/named-vault-resolver.mjs';
 import { loadOwnerConfig } from './lib/owner-yaml.mjs';
@@ -249,8 +254,9 @@ if (flagValues.help === true) {
       '                                        project holding --source (<root>/.orchestrator/metrics/), else',
       '                                        the git repo containing it, else the cwd. Refused (exit 2,',
       '                                        "source-repo-mismatch") when --source lies in a different repo.',
-      '  --quality-min-narrative-chars <int>   Sessions: minimum rendered-narrative length (default 400).',
-      '                                        Entries below the threshold emit "skipped-quality-low".',
+      '  --quality-min-narrative-chars <int>   Sessions: minimum free text in notes/narrative/summary',
+      '                                        (default 400, 0 = off). Below it: "skipped-metrics-only",',
+      '                                        one row in 50-sessions/<repo>/_rollup-YYYY-MM.md.',
       '  --quality-min-confidence <float>      Learnings: minimum confidence threshold (default 0.5).',
       '                                        Entries below the threshold emit "skipped-quality-low".',
       '',
@@ -641,6 +647,9 @@ async function main() {
     // superseded duplicates included — filled while buffering below, read by
     // processSession's owner guard (a key from this ledger is never foreign).
     sourceRecordKeys: new Set(),
+    // #1513: note slugs of every LIVE learning in --source; the archive pass
+    // below never marks a note one of them still owns.
+    liveLearningSlugs: new Set(),
     qualityMinNarrativeChars,
     qualityMinConfidence,
   };
@@ -662,14 +671,15 @@ async function main() {
    *   always supplies a real line number.
    * @returns {Promise<void>}
    */
-  async function dispatchEntry(entry, entryLineNum) {
+  async function dispatchEntry(entry, entryLineNum, processor = null) {
     try {
       // Both processors return the `action` string they emitted (every one of
       // their exit paths is an `emitAction` call), so the tally needs no second
       // census of the 18 call sites in process.mjs — a census that would go
       // stale the first time a branch is added.
-      const action =
-        kind === 'learning'
+      const action = processor
+        ? await processor(entry, entryLineNum, ctx)
+        : kind === 'learning'
           ? await processLearning(entry, entryLineNum, ctx)
           : await processSession(entry, entryLineNum, ctx);
       tally(action);
@@ -776,9 +786,39 @@ async function main() {
       continue;
     }
 
+    for (const slug of learningNoteSlugs(entry)) ctx.liveLearningSlugs.add(slug);
     await dispatchEntry(entry, lineNum);
   }
 
+  // #1513 ARCHIVE PASS (`--kind learning` only): records /evolve or the expiry
+  // sweep moved out of `learnings.jsonl` live on in the sibling
+  // `learnings-archive.jsonl`. Their vault notes used to stay `status: draft`
+  // forever, because the mirror only ever saw the live store. Each archived
+  // record now marks its existing note archived (never creates one). Counted
+  // into `total` like any other line, so the run partition still holds. A
+  // malformed archive line is reported and skipped — the archive is secondary
+  // input and must not abort a mirror run that already wrote the live store.
+  if (kind === 'learning' && basename(resolve(source)) === 'learnings.jsonl') {
+    const archivePath = join(dirname(resolve(source)), 'learnings-archive.jsonl');
+    if (existsSync(archivePath)) {
+      const archiveLines = readFileSync(archivePath, 'utf8').split('\n');
+      for (let i = 0; i < archiveLines.length; i += 1) {
+        const trimmed = archiveLines[i].trim();
+        if (!trimmed) continue;
+        let archived;
+        try {
+          archived = JSON.parse(trimmed);
+        } catch {
+          process.stderr.write(`WARN vault-mirror: malformed JSON on learnings-archive.jsonl line ${i + 1} — skipped\n`);
+          continue;
+        }
+        if (archived === null || typeof archived !== 'object') continue;
+        runState.total++;
+        await dispatchEntry(archived, i + 1, processArchivedLearning);
+      }
+    }
+  }
+
   if (kind === 'session') {
     // Only an OBJECT entry carrying a non-empty `session_id` is eligible for
     // the dedup collapse — the same predicate canonicalizeSessions itself uses
@@ -803,6 +843,30 @@ async function main() {
     // never a guess (scripts/lib/sessions-canonical.mjs header, "RULE ORDER").
     const survivors = new Set(canonicalizeSessions(identifiable));
 
+    // #1513 review H2: "newest wins" must not cost a session its narrative. A
+    // re-appended record often carries only the metrics; the free text sits on
+    // the line it supersedes (vault ledger: 1.172 chars on line 101, none on the
+    // winning line 108). The winner inherits every narrative field it LACKS
+    // from the losers, latest loser first — its own fields always win.
+    const inherited = new Map();
+    for (const e of sessionEntries) {
+      if (!isIdentifiable(e) || survivors.has(e)) continue;
+      const carry = inherited.get(e.session_id) ?? {};
+      for (const field of SESSION_NARRATIVE_FIELDS) {
+        if (e[field] !== undefined && e[field] !== null && e[field] !== '') carry[field] = e[field];
+      }
+      inherited.set(e.session_id, carry);
+    }
+    const withNarrative = (e) => {
+      const carry = isIdentifiable(e) ? inherited.get(e.session_id) : undefined;
+      if (!carry) return e;
+      const merged = { ...e };
+      for (const [field, value] of Object.entries(carry)) {
+        if (merged[field] === undefined || merged[field] === null || merged[field] === '') merged[field] = value;
+      }
+      return merged;
+    };
+
     for (let i = 0; i < sessionEntries.length; i++) {
       const entry = sessionEntries[i];
       if (isIdentifiable(entry) && !survivors.has(entry)) {
@@ -831,7 +895,7 @@ async function main() {
         );
         continue;
       }
-      await dispatchEntry(entry, sessionLineNums[i]);
+      await dispatchEntry(withNarrative(entry), sessionLineNums[i]);
     }
   }
 
@@ -863,7 +927,8 @@ async function main() {
     autoCommitVaultMirror(
       resolve(vaultDir),
       sessionIdArg,
-      resolveRepoNamespace({ vaultName, repoRoot: ctx.repoRoot }),
+      // #1513 review M2: the folder the processors actually wrote into.
+      canonicalNamespace(resolve(vaultDir), resolveRepoNamespace({ vaultName, repoRoot: ctx.repoRoot })),
     );
   }
 }

package/scripts/windows-setup.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/** Opt-in native MCP configuration for an installed Windows plugin. */
+import { copyFileSync, existsSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { isMainModule } from './lib/is-main-module.mjs';
+
+export function configureNativeMcp(pluginRoot, { node = process.execPath, platform = process.platform } = {}) {
+  if (platform !== 'win32') throw new Error('This setup is for native Windows only.');
+  const root = realpathSync(pluginRoot);
+  if (existsSync(path.join(root, '.git'))) throw new Error('Refusing to configure a Git checkout.');
+  const segments = root.split(path.sep);
+  const inCache = segments.some((segment, index) =>
+    segment === 'plugins' && segments[index + 1] === 'cache' && index + 2 < segments.length);
+  if (!inCache) throw new Error('Expected an installed plugin inside plugins/cache.');
+  const pkg = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'));
+  if (pkg.name !== 'session-orchestrator') throw new Error('Expected a session-orchestrator plugin directory.');
+  const server = path.join(root, 'scripts', 'mcp-server.mjs');
+  if (!existsSync(server)) throw new Error('Native MCP server is missing; install the updated package first.');
+  const file = path.join(root, '.mcp.json');
+  const raw = readFileSync(file, 'utf8');
+  const config = JSON.parse(raw);
+  const current = config.mcpServers?.['session-orchestrator'];
+  if (!current || typeof current !== 'object') throw new Error('Expected session-orchestrator MCP configuration.');
+  if (current.command === node && current.args?.length === 1 && current.args[0] === server) {
+    return { changed: false, file };
+  }
+  const backup = `${file}.before-windows-setup`;
+  if (existsSync(backup)) throw new Error(`Backup already exists: ${backup}; inspect it before reconfiguring.`);
+  config.mcpServers['session-orchestrator'] = { ...current, command: node, args: [server] };
+  copyFileSync(file, backup);
+  const temporary = `${file}.windows-setup-${process.pid}`;
+  writeFileSync(temporary, `${JSON.stringify(config, null, 2)}\n`, { flag: 'wx' });
+  renameSync(temporary, file);
+  return { changed: true, file, backup };
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    if (process.argv.length !== 3) throw new Error('Usage: node scripts/windows-setup.mjs <installed-plugin-directory>');
+    process.stdout.write(`${JSON.stringify(configureNativeMcp(process.argv[2]))}\n`);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/skills/_shared/fleet-protocol.md

@@ -103,6 +103,14 @@ Bedingungen, die der Navigator einer Session schreibt (z. B. Agent-Caps, volle P
 Offload-Regel, Merge- und Zeitregeln, Besitzkonflikte); Inhalt und Form gehören dem Navigator. Die
 Session **liest** die Datei; sie wartet auf keine Nachricht. Keine Auflage ist eine Freigabe.
 
+**Pflichtfeld `repo`** (#1520, navigator#190): absoluter Pfad auf Toplevel oder git-common-dir des
+Ziel-Repos. Der Dateiname ist die semantische Session-ID, und die kollidiert über Repos hinweg.
+Gelesen wird über `node scripts/fleet-auflagen.mjs <session_id>` (Code: `readAuflagen()`); die
+Datei gilt nur, wenn `repo` und das eigene Repo auf dasselbe `git rev-parse --path-format=absolute
+--git-common-dir` auflösen, ein Worktree passt also zu seinem Haupt-Checkout. Fehlt das Feld, passt
+es nicht oder ist die Datei unlesbar: fail-closed, WARN auf stderr, die Datei zählt als nicht
+vorhanden, die Standard-Auflagen gelten.
+
 **Standard-Auflagen (konservative Stufe).** Sie gelten ab `fallback_due_at` (stdout der
 Check-in-CLI), wenn bis dahin keine Auflagen-Datei liegt. Die Frist rechnet `fallbackDueAt()`:
 `CHECKIN_FALLBACK_MIN` = 10 Minuten nach `checkin.zeit`, solange ein Navigator aktiv ist; ohne

package/skills/architecture/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: architecture
 description: Use when the user asks to improve architecture, find refactoring opportunities, surface deepening opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. Surfaces shallow modules and hypothetical seams using a precise vocabulary (Module / Interface / Implementation / Depth / Seam / Adapter / Leverage / Locality from LANGUAGE.md).
+user-invocable: true
 model: inherit
 derived-from: mattpocock/skills@90ea8ee
 license: MIT

package/skills/bootstrap/_shared-template.md

@@ -342,7 +342,7 @@ On Codex CLI / Cursor IDE, substitute `.codex/` or `.cursor/` for `.claude/` per
 
 Applied by Fast Step 3 (so by every tier), by the Upgrade Flow and by the Refresh-Lock Flow in `SKILL.md` — the last two because a repo bootstrapped before this step existed never gets it otherwise: both flows write no `.gitignore` of their own.
 
-`.orchestrator/` itself stays versioned: `bootstrap.lock`, `policy/`, `steering/`, `peers/` and the `.orchestrator/metrics/*.jsonl` ledgers are durable project data. What the plugin writes there at runtime is per-process state or a per-run artifact that a `git add -A` would otherwise commit — the session lock is rewritten on every SessionStart, every store rewrite leaves a full backup copy of the ledger beside it, the auto-dream sidecar is a full replacement body of the operator's private MEMORY.md, and the quality-gate and ux-grill artifacts can carry secrets or a rendered password. Each pattern below names one writer's file, its `.acquire` guard where it has one, and its own temp files (left behind only by a crash mid-write). Rotated and archived ledger copies (`*.jsonl.[0-9]*`, `*.jsonl.archive-*`, `metrics/_archive/`) are not on this list: they carry ledger history, and whether that is versioned is the consumer's call.
+`.orchestrator/` itself stays versioned: `bootstrap.lock`, `policy/`, `steering/`, `peers/` and the `.orchestrator/metrics/*.jsonl` ledgers are durable project data. What the plugin writes there at runtime is per-process state or a per-run artifact that a `git add -A` would otherwise commit — the session lock is rewritten on every SessionStart, every store rewrite leaves a full backup copy of the ledger beside it, the auto-dream sidecar is a full replacement body of the operator's private MEMORY.md, and the quality-gate and ux-grill artifacts can carry secrets or a rendered password. Each pattern below names one writer's file, its `.acquire` guard where it has one, and its own temp files (left behind only by a crash mid-write). Rotated and archived ledger copies (`*.jsonl.[0-9]*`, `*.jsonl.archive-*`, `metrics/_archive/`) are ignored too (owner decision 2026-10-03, #1507 Pkt 4): the live `*.jsonl` ledger is the versioned record, and the rotated history beside it is not.
 
 | Pattern(s) | Written by |
 |---|---|
@@ -360,7 +360,9 @@ Applied by Fast Step 3 (so by every tier), by the Upgrade Flow and by the Refres
 | `.orchestrator/staging-fence/` | the staging-fence commit mutex and intent log |
 | `.orchestrator/tmp/` | machine-local scratch: lock-reaper archives of reaped session locks (`tmp/reaped-locks/`, carrying host name, pid and session ids), worktree metadata (`tmp/worktree-meta/`), the orphan-reaper throttle marker (`tmp/reaper-last-scan`) |
 | `.orchestrator/metrics/*.jsonl.bak.*` | the legacy evolve backup `learnings.jsonl.bak.evolve-<ts>`, a full store copy still on disk in older repos (`scripts/lib/learnings/io.mjs`) |
+| `.orchestrator/metrics/*.jsonl.[0-9]*`, `.orchestrator/metrics/*.jsonl.archive-*`, `.orchestrator/metrics/_archive/` | rotated ledger history of the events log (`scripts/lib/events.mjs`): the legacy numbered `events.jsonl.<n>` slots, older `*.jsonl.archive-*` copies and the `_archive/` directory of rotated `events-<first>_<last>.jsonl` files (`scripts/lib/events-schema.mjs`); the live `*.jsonl` ledgers stay versioned |
 | `.orchestrator/metrics/*.jsonl.tmp-*` | atomic-write temp files of the ledgers (`scripts/lib/autopilot/telemetry.mjs`), left behind only by a crash |
+| `.orchestrator/metrics/.*.tmp.*` | temp files of the shared atomic writers (`scripts/lib/io.mjs`, named `.<base>.tmp.<hex>`), left behind only by a crash |
 | `.orchestrator/pending-dream.md` | the auto-dream sidecar — a full replacement body of the private MEMORY.md (`scripts/lib/auto-dream.mjs`) |
 | `.orchestrator/dialectic-pending.md`, `.orchestrator/dialectic-last-run`, `.orchestrator/consumed/` | the auto-dialectic sidecar, its last-run timestamp and the archive of consumed sidecars (`scripts/lib/auto-dialectic.mjs`) |
 | `.orchestrator/promoted-from.json` | the worktree-promotion marker, a per-worktree fact (`scripts/lib/autopilot/worktree-pipeline.mjs`, read by `scripts/lib/session-end/worktree-cleanup.mjs`) |
@@ -396,7 +398,8 @@ _GI_PATTERNS=(
   '.orchestrator/metrics/proposals-write.lock*' '.orchestrator/metrics/.proposals-write.lock.*'
   '.orchestrator/staging-fence/'
   '.orchestrator/tmp/'
-  '.orchestrator/metrics/*.jsonl.bak.*' '.orchestrator/metrics/*.jsonl.tmp-*'
+  '.orchestrator/metrics/*.jsonl.bak.*' '.orchestrator/metrics/*.jsonl.tmp-*' '.orchestrator/metrics/.*.tmp.*'
+  '.orchestrator/metrics/*.jsonl.[0-9]*' '.orchestrator/metrics/*.jsonl.archive-*' '.orchestrator/metrics/_archive/'
   '.orchestrator/pending-dream.md'
   '.orchestrator/dialectic-pending.md' '.orchestrator/dialectic-last-run' '.orchestrator/consumed/'
   '.orchestrator/promoted-from.json'

package/skills/claude-md-drift-check/SKILL.md

@@ -9,6 +9,7 @@ description: >
   globs), and docs-parity (docs/components.md count-claims vs on-disk counts, template-vs-reference
   config-key parity, stale .claude/metrics/ paths). Full per-check spec in the body table. Invoked as an
   opt-in session-end phase; mirrors vault-sync's lean JSON+exit-code contract.
+user-invocable: false
 model: haiku
 ---
 
@@ -37,7 +38,7 @@ PHASE 1 IMPLEMENTED (2026-04-19). Session-end opt-in quality gate. Upstream of `
 | 2 | `project-count-sync` | Hardcoded "N registered" / "N projects" claims next to `01-projects/` | compare to `ls -d 01-projects/*/` |
 | 3 | `issue-reference-freshness` | `#NN` in forward-looking sections (What's Next, Backlog, Open Issues, Offene Themen, Todo, Next Steps) | `glab issue view NN --repo <origin>` |
 | 4 | `session-file-existence` | `50-sessions/YYYY-MM-DD-*.md` references anywhere in scope | `existsSync(vault/50-sessions/<file>)` |
-| 5 | `command-count` | "N commands" / "N /commands" claims in prose | compare to the name-deduplicated union of `commands/*.md` and skills with explicit `user-invocable: true`; skipped only when both directories are absent |
+| 5 | `command-count` | "N commands" / "N /commands" claims in prose | compare to the name-deduplicated union of `commands/*.md` and skills whose `user-invocable` is `true` or absent (Claude Code picker semantics, #1515); skipped only when both directories are absent |
 | 6 | `session-config-parity` | Top-level keys under `## Session Config` in `CLAUDE.md` / `AGENTS.md` | diff against `docs/session-config-template.md`; a missing MANDATORY (minimal-baseline) key is an error, a missing OPT-IN-baseline-only key is a note, a local key absent from the template's Session Config blocks is a warning |
 | 7 | `vault-dir-parity` | `vault-integration.vault-dir` in BOTH `CLAUDE.md` AND `AGENTS.md` | reuse `_parseVaultIntegration`; flag when the two files disagree. Short-circuits to PASS when the two are the SAME file by construction (symlink / same inode / byte-identical generated copy) |
 | 8 | `generated-rule-staleness` *(WARN only)* | `.claude/rules/*.md` with `auto-generated: true` frontmatter | extract `learning-key`; WARN when the key is absent from `.orchestrator/metrics/learnings.jsonl` or its learning's `expires_at` is in the past; skipped silently when no auto-generated rules exist |
@@ -61,6 +62,8 @@ A local CLAUDE.md / AGENTS.md that omits any of these surfaces a `session-config
 
 Check 7 (issue #600) is the **only** check that intentionally reads BOTH instruction files rather than the single alias-resolved one. The alias rule (CLAUDE.md wins ties, AGENTS.md is the Codex alias) means `resolveInstructionFile()` picks exactly one — so a repo carrying both files can silently let `AGENTS.md` drift out of sync with `CLAUDE.md`. A sibling project ran for weeks with a correct `vault-integration.vault-dir` in `CLAUDE.md` and a dead path in `AGENTS.md`. Check 7 reads `vault-integration.vault-dir` from each file (reusing the `_parseVaultIntegration` parser from `scripts/lib/config/vault-integration.mjs` — no hand-rolled YAML) and flags a `vault-dir-parity` error when the two values diverge (the error is attributed to `AGENTS.md`, the secondary alias, and names both values). The check skips gracefully when only one instruction file is present (nothing to compare), when neither file declares a `vault-integration:` block, or when explicitly disabled via `--skip-vault-dir-parity`. Two files that both omit `vault-dir` (both unset) agree and pass.
 
+**Runtime override caveat.** `SO_CONFIG_FILE=AGENTS.md` reads a config-free `@CLAUDE.md` pointer as raw text; `parse-config.mjs` does not follow its import. Check 7 accepting that pointer does not prove an effective runtime config. Set the override to the config-bearing file (for example, `SO_CONFIG_FILE=CLAUDE.md`).
+
 **Alias-by-construction short-circuit.** Since this repo's root `AGENTS.md` became a GENERATED byte-identical copy of `CLAUDE.md` (`scripts/generate-agents-skills.mjs`), Check 7 no longer skips here — it RUNS on every invocation. Two files that cannot disagree have nothing to diff, so the check reports parity as satisfied without deriving one: `instructionFilesAreAliased()` recognises a symlink resolving to the same path, the same inode/device (hardlink or already-resolved symlink), and byte-identical content. Branch order is load-bearing: the "neither file has a `vault-integration:` block" skip is evaluated FIRST, because an absent subject is a different (and more informative) outcome than "the files cannot disagree". The error class the check exists for is untouched — two INDEPENDENT files that declare different `vault-dir` values still produce the `vault-dir-parity` error attributed to `AGENTS.md`.
 
 The same predicate guards Check 9's probe 2a, which iterates `['CLAUDE.md', 'AGENTS.md']`: with an aliased `AGENTS.md` it scans `CLAUDE.md` only, because otherwise every dangling `.claude/rules/*.md` citation would be reported TWICE — one defect, two errors, and in `--mode strict` a doubled blocking surface against a file the operator is not allowed to edit.