session-orchestrator 5.3.0 → 5.5.0

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

@@ -4,7 +4,7 @@ description: >
   Use when detecting drift between CLAUDE.md (or AGENTS.md, the Codex CLI alias) / _meta narrative and
   live repository state. Ten checks: absolute-path resolution, 01-projects/ count claims, issue-reference
   freshness, session-file existence, command-count sync, session-config-parity (mandatory template keys =
-  error, opt-in gaps = warning), vault-dir-parity (CLAUDE.md vs AGENTS.md), generated-rule-staleness
+  error, opt-in gaps = note, unknown local keys = warning), vault-dir-parity (CLAUDE.md vs AGENTS.md), generated-rule-staleness
   (WARN-only), rule-scoping (paths:/globs: frontmatter defects, dangling rule citations, zero-match
   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
@@ -37,18 +37,18 @@ 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 `ls commands/*.md \| wc -l`; skipped if no `commands/` dir |
-| 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 warning |
+| 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 |
+| 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 |
-| 9 | `rule-scoping` | `.claude/rules/*.md` frontmatter + `## See Also` footers + `.claude/rules/<name>.md` citations in `CLAUDE.md`/`AGENTS.md` | six probes: `paths:` frontmatter (error), cited-but-missing rule citations (error), zero-match `globs:` patterns (warn), foreign PascalCase glob tokens (warn), unreadable rule files (warn — surfaced instead of silently skipped), declared fleet-intent globs (**note**, never warn); skipped silently when `.claude/rules/` is absent |
+| 9 | `rule-scoping` | `.claude/rules/*.md` frontmatter + `## See Also` footers + `.claude/rules/<name>.md` citations in `CLAUDE.md`/`AGENTS.md` | six probes: `paths:` frontmatter incl. frontmatter not at line 1 (error, #1449), cited-but-missing rule citations (error), zero-match `globs:` patterns (warn), foreign PascalCase glob tokens (warn), unreadable rule files (warn — surfaced instead of silently skipped), declared fleet-intent globs (**note**, never warn); skipped silently when `.claude/rules/` is absent |
 | 10 | `docs-parity` | `docs/components.md` count-claims, Session Config key parity (`docs/session-config-template.md` vs `docs/session-config-reference.md`), `.claude/metrics/` stale-path references in `docs/*.md` / `docs/examples/*.md` | three sub-checks (a/b/c) — see below; skipped silently when `docs/components.md` is absent |
 
 Check 3 deliberately scopes to forward-looking sections. Mentions inside "Recently Closed", "Decisions", "Archive", etc. describe history and must not be flagged.
 
-Check 5 counts `*.md` files directly inside `commands/` (non-recursive, non-hidden). The `commands/` directory is resolved relative to `VAULT_DIR` by default; use `--commands-dir <path>` to override.
+Check 5 uses `countSlashCommands()` to count the union of non-hidden `*.md` files directly inside `commands/` and skills under `skills/` whose frontmatter explicitly declares `user-invocable: true`, deduplicated by name. The `commands/` directory is resolved relative to `VAULT_DIR` by default; `--commands-dir <path>` overrides that side of the union, while skills remain relative to `VAULT_DIR`. Either directory alone is sufficient; an existing directory with no commands contributes zero rather than causing a skip.
 
-Check 6 (issue #30; severity split per #785) extracts the YAML block under `## Session Config` from both the canonical template (`docs/session-config-template.md` by default, override with `--config-template`) and the resolved local instruction file — reading the template TWICE, once per occurrence: `{ occurrence: 'first' }` reaches the "Full minimal baseline" (the 7 schema-mandatory keys), `{ occurrence: 'last' }` reaches the "Full opt-in baseline" (the full key catalog, a strict superset of the minimal block). A template key missing from the local file is a `session-config-parity` **error** when it belongs to the minimal-baseline set, and a **warning** when it is opt-in-baseline-only — a consumer repo that legitimately does not adopt an opt-in feature (e.g. no `handover-gate`) must not go red; only the true 7-key mandatory contract does. When the template carries a single `## Session Config` heading (no separate opt-in block), `'first'` and `'last'` resolve to the same block and every key is treated as mandatory, preserving prior behaviour for single-block templates. Both fenced YAML (```` ```yaml ... ``` ````) and raw YAML body (up to next `## ` heading) are accepted. The check skips gracefully when the template file is absent, when no instruction file is detected, or when explicitly disabled via `--skip-session-config-parity`.
+Check 6 (issue #30; severity split per #785 and #1356) extracts the YAML block under `## Session Config` from both the canonical template (`docs/session-config-template.md` by default, override with `--config-template`) and the resolved local instruction file — reading the template TWICE, once per occurrence: `{ occurrence: 'first' }` reaches the "Full minimal baseline" (the 7 schema-mandatory keys), `{ occurrence: 'last' }` reaches the "Full opt-in baseline" (the full key catalog, a strict superset of the minimal block). A template key missing from the local file is a `session-config-parity` **error** when it belongs to the minimal-baseline set, and a **note** with `probe: "opt-in-gap"` when it is opt-in-baseline-only. A local key absent from those template blocks produces a **warning**: it may be a typo or a template gap, and this check makes no claim about documentation elsewhere or runtime use. When the template carries a single `## Session Config` heading (no separate opt-in block), `'first'` and `'last'` resolve to the same block, every template key is treated as mandatory, and unknown-local-key warnings are skipped. Both fenced YAML (```` ```yaml ... ``` ````) and raw YAML body (up to next `## ` heading) are accepted. The check skips gracefully when the template file is absent, when no instruction file is detected, or when explicitly disabled via `--skip-session-config-parity`.
 
 The parity set is **template-driven**: every column-0 YAML key under `## Session Config` in the template (across both occurrences) is checked. As of the gsd Pattern Adoption Quick-Wins bundle (PRD 2026-05-22, issues #517–#521), the template-side keys include four opt-in top-level blocks:
 
@@ -57,7 +57,7 @@ The parity set is **template-driven**: every column-0 YAML key under `## Session
 - `templates-first` (Pattern 3 / #519) — gh/glab template-read enforcement hook
 - `verification-auto-fix` (Pattern 4 / #521) — opt-in auto-fix retry loop after Quality-Gate fail
 
-A local CLAUDE.md / AGENTS.md that omits any of these now surfaces a `session-config-parity` **warning** (not an error) — they are opt-in-baseline-only keys, so omitting them never trips `mode: hard`, and never blocks `autonomous-gated` skill-evolution's `runConfigValidationGate()` (which runs the checker with `--mode hard` and reads only `errors[]`).
+A local CLAUDE.md / AGENTS.md that omits any of these surfaces a `session-config-parity` **note** — they are opt-in-baseline-only keys, so omitting them never trips `mode: hard`, and never blocks `autonomous-gated` skill-evolution's `runConfigValidationGate()` (which runs the checker with `--mode hard` and reads only `errors[]`).
 
 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.
 
@@ -65,11 +65,11 @@ Check 7 (issue #600) is the **only** check that intentionally reads BOTH instruc
 
 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.
 
-Check 9 (`rule-scoping`) validates `.claude/rules/*.md` frontmatter against the `scripts/lib/rule-loader.mjs` contract, catching the class of defect where a rule silently drifts out of the activation pipeline the loader actually implements. Six probes: **(1) paths-presence** — since #795 `paths:` is a full same-shape alias for `globs:` in `rule-loader.mjs` (`globs:` wins silently when both are present), so a well-formed `paths:`-only rule loads correctly SCOPED and is NOT flagged (#840). The probe fires only when the frontmatter textually carries a top-level `paths:` key AND `parseGlobsFrontmatter` — the loader's own parser, imported rather than re-derived — returns `globs === null` (e.g. a malformed frontmatter line makes it throw); that parse mismatch means the rule may silently load ALWAYS-ON, and is flagged as an error. **(2) cited-but-missing** — `(a)` `.claude/rules/<name>.md` citations inside `CLAUDE.md`/`AGENTS.md` that don't resolve to a file on disk, and `(b)` bare `<name>.md` tokens in a rule's own `## See Also` footer that don't exist as sibling rule files (tokens carrying a path separator, e.g. `../../skills/_shared/state-ownership.md`, are cross-directory references and explicitly out of scope); both flagged as errors. **(3) zero-match-globs** — a `globs:` pattern matching zero files in `git ls-files` (falls back to a manual directory walk when git is unavailable); flagged as a WARNING, not an error, because library/exemplar repos legitimately carry dead stack rules. **(4) foreign-glob** — a glob pattern containing a PascalCase product-like token (regex `[A-Z][a-z]+[A-Z]`, e.g. `WalkAITalkieTests`) — a likely copy-paste leftover from another project's rule scope; flagged as a WARNING. **(5) unreadable-file** — a rule file that could not be read (permissions, a race with a concurrent delete); flagged as a WARNING rather than silently skipped, so a completeness audit does not drop files, and so an unreadable file cannot brick the gate under `mode: hard`. **(6) fleet-intent-glob** — a `globs:` pattern DECLARED as fleet intent goes to `notes[]` (see below), never to `warnings[]`, and the declaration also settles probe 4 for that same pattern: a pattern the rule author declared is by construction not a copy-paste leftover. Glob matching reuses the same picomatch-with-inline-fallback resolution `scripts/lib/rule-loader.mjs` uses (`parseGlobsFrontmatter` is imported directly; the picomatch resolution itself is duplicated locally since `rule-loader.mjs` does not export a public matcher function). The check is skipped silently (no `checks_run` entry, no `checks_skipped` entry) when `.claude/rules/` is absent, or explicitly via `--skip-rule-scoping`.
+Check 9 (`rule-scoping`) validates `.claude/rules/*.md` frontmatter against the `scripts/lib/rule-loader.mjs` contract, catching the class of defect where a rule silently drifts out of the activation pipeline the loader actually implements. Six probes: **(1) paths-presence** — a frontmatter block that does not open on line 1 (text or a provenance comment before `---`) is an ERROR since #1449: Claude Code ignores it and loads the rule always-on; the probe reports `parseGlobsFrontmatter(...).defect === 'frontmatter-not-at-top'` with the remedy (move the block to line 1, provenance comment after the closing `---`). Otherwise, since #795 `paths:` is a full same-shape alias for `globs:` in `rule-loader.mjs` (`globs:` wins silently when both are present), so a well-formed `paths:`-only rule loads correctly SCOPED and is NOT flagged (#840). The probe fires only when the frontmatter textually carries a top-level `paths:` key AND `parseGlobsFrontmatter` — the loader's own parser, imported rather than re-derived — returns `globs === null` (e.g. a malformed frontmatter line makes it throw); that parse mismatch means the rule may silently load ALWAYS-ON, and is flagged as an error. **(2) cited-but-missing** — `(a)` `.claude/rules/<name>.md` citations inside `CLAUDE.md`/`AGENTS.md` that don't resolve to a file on disk, and `(b)` bare `<name>.md` tokens in a rule's own `## See Also` footer that don't exist as sibling rule files (tokens carrying a path separator, e.g. `../../skills/_shared/state-ownership.md`, are cross-directory references and explicitly out of scope); both flagged as errors. **(3) zero-match-globs** — a `globs:` pattern matching zero files in `git ls-files` (falls back to a manual directory walk when git is unavailable); flagged as a WARNING, not an error, because library/exemplar repos legitimately carry dead stack rules. **(4) foreign-glob** — a glob pattern containing a PascalCase product-like token (regex `[A-Z][a-z]+[A-Z]`, e.g. `WalkAITalkieTests`) — a likely copy-paste leftover from another project's rule scope; flagged as a WARNING. **(5) unreadable-file** — a rule file that could not be read (permissions, a race with a concurrent delete); flagged as a WARNING rather than silently skipped, so a completeness audit does not drop files, and so an unreadable file cannot brick the gate under `mode: hard`. **(6) fleet-intent-glob** — a `globs:` pattern DECLARED as fleet intent goes to `notes[]` (see below), never to `warnings[]`, and the declaration also settles probe 4 for that same pattern: a pattern the rule author declared is by construction not a copy-paste leftover. Glob matching reuses the same picomatch-with-inline-fallback resolution `scripts/lib/rule-loader.mjs` uses (`parseGlobsFrontmatter` is imported directly; the picomatch resolution itself is duplicated locally since `rule-loader.mjs` does not export a public matcher function). The check is skipped silently (no `checks_run` entry, no `checks_skipped` entry) when `.claude/rules/` is absent, or explicitly via `--skip-rule-scoping`.
 
 **Fleet-intent declaration (Check 9, probe 6).** A rule may declare that a `globs:` pattern is aimed at CONSUMER repos rather than this one, via its own frontmatter key `fleet-intent-globs:`. Accepted forms are block style (`fleet-intent-globs:` plus indented `  - "<pattern>"` lines), flow style (`fleet-intent-globs: ["a", "b"]`) and a single inline value; surrounding quotes are stripped, blank and `#` comment lines are ignored. The key is inert for rule loading — `rule-loader.mjs`'s `parseGlobsFrontmatter` skips unknown top-level keys and their continuation lines. A declared pattern is reported in `notes[]` with its file, the pattern, whether it matches `≥1` or `0` tracked files here, and the declaration `source` (`frontmatter`). The grain is per pattern AND per rule file: declaring one glob amnesties neither a sibling glob in the same rule nor the same pattern in another rule. There is deliberately NO checker-side exemption list: a rule that does not declare the pattern itself is not exempt, so the declaration always sits with the rule it describes.
 
-Check 10 (`docs-parity`, issue #780) validates the public docs surface against live repository state via three sub-checks, all reported under the single `docs-parity` check id: **(a) count-claims** — `docs/components.md`'s own heading counts ("## Skills (N user-facing)", "## Commands (N)", "## Agents (N typed sub-agents)", "## Hook event types (N)") are compared against the SAME actual on-disk derivation the surface-count family (Check 5) uses (`countSkills`/the commands-dir listing/`countAgents`/`readHookCounts`) — NOT Check 5's `claimRe` regexes, which are tuned for CLAUDE.md/README prose phrasing and verifiably do not match `components.md`'s own heading convention; a dedicated set of regexes tailored to the doc's actual authored structure is used instead. **(b) config-block-parity** — top-level Session Config keys documented in `docs/session-config-template.md` (opt-in baseline, via the Check 6 'last'-occurrence extractor) are compared against `docs/session-config-reference.md`; a key is considered documented in the reference when it appears in a `yaml` fence (any indent), a `##`/`###`/`####` heading, or the first cell of a markdown table row (`` | `key-name` | ... ``) — the reference's dominant documentation shape is one table row per field, so a naive fence-only extraction under-counts what it actually documents. Missing keys surface as `docs-parity` errors attributed to `docs/session-config-reference.md`. **(c) metrics-path-liveness** — any `.claude/metrics/` path reference (stale; canonical is `.orchestrator/metrics/`) found in root `docs/*.md` or `docs/examples/*.md` surfaces as an error at its exact file/line. The whole check is skipped silently (no `checks_run` entry, no `checks_skipped` entry) when `docs/components.md` is absent, or explicitly via `--skip-docs-parity`.
+Check 10 (`docs-parity`, issue #780) validates the public docs surface against live repository state via three sub-checks, all reported under the single `docs-parity` check id: **(a) count-claims** — `docs/components.md`'s own heading counts ("## Skills (N user-facing)", "## Commands (N)", "## Agents (N typed sub-agents)", "## Hook event types (N)") are compared against the SAME actual on-disk derivation the surface-count family (Check 5) uses (`countSkills`/`countSlashCommands`/`countAgents`/`readHookCounts`) — NOT Check 5's `claimRe` regexes, which are tuned for CLAUDE.md/README prose phrasing and verifiably do not match `components.md`'s own heading convention; a dedicated set of regexes tailored to the doc's actual authored structure is used instead. **(b) config-block-parity** — top-level Session Config keys documented in `docs/session-config-template.md` (opt-in baseline, via the Check 6 'last'-occurrence extractor) are compared against `docs/session-config-reference.md`; a key is considered documented in the reference when it appears in a `yaml` fence (any indent), a `##`/`###`/`####` heading, or the first cell of a markdown table row (`` | `key-name` | ... ``) — the reference's dominant documentation shape is one table row per field, so a naive fence-only extraction under-counts what it actually documents. Missing keys surface as `docs-parity` errors attributed to `docs/session-config-reference.md`. **(c) metrics-path-liveness** — any `.claude/metrics/` path reference (stale; canonical is `.orchestrator/metrics/`) found in root `docs/*.md` or `docs/examples/*.md` surfaces as an error at its exact file/line. The whole check is skipped silently (no `checks_run` entry, no `checks_skipped` entry) when `docs/components.md` is absent, or explicitly via `--skip-docs-parity`.
 
 ## Files
 
@@ -133,7 +133,7 @@ Environment:
 }
 ```
 
-`notes[]` is the THIRD output category, alongside `errors[]` and `warnings[]`: a finding that is reported but asks for no action. It never affects `status` or the exit code, and it is always present (empty array when nothing was noted, including on the short-circuit "no scope files matched" path). Its only producer today is Check 9's fleet-intent-glob probe.
+`notes[]` is the THIRD output category, alongside `errors[]` and `warnings[]`: a finding that is reported but asks for no action. It never affects `status` or the exit code, and it is always present (empty array when nothing was noted, including on the short-circuit "no scope files matched" path). Producers are Check 6's `opt-in-gap` probe and Check 9's `fleet-intent-glob` probe. Opt-in-gap notes carry `check: "session-config-parity"`, `probe: "opt-in-gap"`, the instruction file and line, a message, and the omitted key in `extracted`; they have no `source` field.
 
 The `resolved_path` / `resolved_kind` pair surfaces the alias resolution outcome (issue #33 AC2) so users on either platform can audit which instruction file the checker scanned. `kind: 'claude'` for `CLAUDE.md`, `kind: 'agents'` for `AGENTS.md`, `null` when neither was found.
 

package/skills/claude-md-drift-check/checker.mjs

@@ -25,7 +25,9 @@
  * Reuses `_parseVaultIntegration` from scripts/lib/config/ for Check 7;
  * reuses `parseGlobsFrontmatter` from scripts/lib/rule-loader.mjs for Check 9's
  * glob extraction (mirrors the same picomatch-with-inline-fallback resolution
- * rule-loader.mjs uses); otherwise pure Node stdlib.
+ * rule-loader.mjs uses) and its line-1-only frontmatter rule (#1449: a block
+ * with anything before its opening `---` is not frontmatter, exactly as Claude
+ * Code reads it); otherwise pure Node stdlib.
  */
 
 import { readFileSync, readdirSync, existsSync, statSync, lstatSync, realpathSync } from 'node:fs';
@@ -36,7 +38,7 @@ import { resolveInstructionFile } from '../../scripts/lib/common.mjs';
 import { _parseVaultIntegration } from '../../scripts/lib/config/vault-integration.mjs';
 import { _parseDriftCheck } from '../../scripts/lib/config/drift-check.mjs';
 import { isSessionConfigHeading } from '../../scripts/lib/config/section-extractor.mjs';
-import { parseGlobsFrontmatter } from '../../scripts/lib/rule-loader.mjs';
+import { FRONTMATTER_NOT_AT_TOP, parseGlobsFrontmatter } from '../../scripts/lib/rule-loader.mjs';
 import { resolveRepoSpec } from '../../scripts/lib/vcs-repo-spec.mjs';
 import { userInvocableSkills } from '../../scripts/lib/user-invocable-skills.mjs';
 
@@ -573,7 +575,11 @@ function lookupIssueState(iid, repo, cache, vaultDir) {
 //      rule-loader.mjs's parseGlobsFrontmatter (the `paths:` alias, issue
 //      #795) fails to recognise — a genuine parse mismatch. A well-formed
 //      `paths:`-only rule is NOT flagged: since #795, `paths:` is a full
-//      alias for `globs:` and loads correctly SCOPED (#840).
+//      alias for `globs:` and loads correctly SCOPED (#840). Also an error
+//      (#1449): a frontmatter block that does not start on line 1 (a
+//      provenance comment, a blank line or any text before the opening
+//      `---`) — parseGlobsFrontmatter reports it as `frontmatter-not-at-top`,
+//      Claude Code ignores such a block, and the rule loads ALWAYS-ON.
 //   2. cited-but-missing → errors[]:  (a) `.claude/rules/<name>.md` citations in
 //      CLAUDE.md/AGENTS.md that don't exist on disk; (b) bare `<name>.md`
 //      tokens in a rule's own `## See Also` footer that don't exist on disk
@@ -674,21 +680,12 @@ function listTrackedFiles(vaultDir) {
   }
 }
 
-const RULE_HEADER_LINE_RE = /^[ \t]*(?:<!--.*-->)?[ \t]*$/;
-
-function stripLeadingRuleHeaderLines(content) {
-  const lines = content.split(/\r?\n/);
-  let idx = 0;
-  while (idx < lines.length && RULE_HEADER_LINE_RE.test(lines[idx])) idx++;
-  return lines.slice(idx).join('\n');
-}
-
 /** Extracts the raw frontmatter block body (text between the `---` delimiters),
- * or null when the file has no frontmatter block. Leading blank/comment
- * provenance lines are tolerated so Check 9 sees the same frontmatter shape
- * that rule-loader.mjs accepts. */
+ * or null when the file has no frontmatter block. Only a block whose opening
+ * `---` is line 1 counts (#1449) — the rule rule-loader.mjs and Claude Code
+ * apply; a displaced block is body text, reported by probe 1 instead. */
 function extractFrontmatterBlockBody(content) {
-  const m = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(stripLeadingRuleHeaderLines(content));
+  const m = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);
   return m ? m[1] : null;
 }
 
@@ -1173,7 +1170,7 @@ function main() {
     // Minimal inline frontmatter extractor for auto-generated + learning-key.
     // Reads the opening --- ... --- block from a markdown file.
     function extractFrontmatterFields(mdContent) {
-      const m = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(stripLeadingRuleHeaderLines(mdContent));
+      const m = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(mdContent);
       if (!m) return { autoGenerated: false, learningKey: null, expiresAt: null, evidenceDigest: null };
       const block = m[1];
       const autoGenM = /^auto-generated:\s*(.+)$/m.exec(block);
@@ -1370,10 +1367,21 @@ function main() {
         // parseGlobsFrontmatter failed to recognise it (globs === null) —
         // a genuine parse mismatch between this probe's textual detection
         // and the loader's actual behaviour, not routine `paths:` usage.
+        // #1449: the same parser also reports a frontmatter block that does
+        // not start on line 1. Claude Code ignores that block, so whatever
+        // key it carries (globs:, paths:, tier:, …) has no effect and the
+        // rule loads ALWAYS-ON — an error of its own, reported instead of
+        // the paths: mismatch (fmBody is null for such a file anyway).
         let parsed;
         try { parsed = parseGlobsFrontmatter(content); } catch { parsed = { globs: null, meta: {} }; }
         const fmBody = extractFrontmatterBlockBody(content);
-        if (fmBody && /^paths:/m.test(fmBody) && parsed.globs === null) {
+        if (parsed.defect === FRONTMATTER_NOT_AT_TOP) {
+          errors.push({
+            check: 'rule-scoping', file: relPath, line: 1,
+            message: `${relPath}: frontmatter is not at line 1 (text before the opening ---) — Claude Code ignores it, the rule loads ALWAYS-ON; move the frontmatter to line 1 and put the provenance comment after the closing ---`,
+            extracted: FRONTMATTER_NOT_AT_TOP,
+          });
+        } else if (fmBody && /^paths:/m.test(fmBody) && parsed.globs === null) {
           errors.push({
             check: 'rule-scoping', file: relPath, line: 1,
             message: `Rule frontmatter declares 'paths:' but rule-loader.mjs's parseGlobsFrontmatter did not recognise it — the rule may silently load ALWAYS-ON. Verify the paths:/globs: frontmatter syntax.`,

package/skills/discovery/probes/ssot-code-diff.mjs

@@ -24,7 +24,8 @@
  *   2. `.claude/rules/*.md` file count (non-recursive) vs. "N rule files" claims.
  *   3. `skills/` user-facing directory count (excludes `_shared/`) vs.
  *      "N user-facing skills" / "N skills" claims.
- *   4. `commands/*.md` file count vs. "N slash-commands" / "N commands" claims.
+ *   4. Slash-command count (`commands/*.md` ∪ skills with `user-invocable: true`)
+ *      vs. "N slash-commands" / "N commands" claims.
  *
  * Scope exclusions: CHANGELOG.md, docs/adr/, docs/prd/, docs/retro/ are never
  * scanned — same principle as the docs-staleness probe (historical/immutable
@@ -45,6 +46,7 @@
 
 import { existsSync, readdirSync, readFileSync, mkdirSync, appendFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { slashCommandNames } from '../../../scripts/lib/user-invocable-skills.mjs';
 
 // ---------------------------------------------------------------------------
 // Doc source sets (deliberately small and hand-curated)
@@ -101,12 +103,16 @@ function countUserFacingSkills(root) {
   }
 }
 
+// Slash commands = `commands/*.md` ∪ skills with an explicit
+// `user-invocable: true` (the #1370 commands→skills fold) — the shared census
+// in user-invocable-skills.mjs, not a second copy. Counting `commands/` alone
+// reported 2 against the real 27 on every run (#1506 pt 7). `null` (entry
+// skipped) only when the repo has neither source.
 function countCommands(root) {
-  const dir = join(root, 'commands');
-  if (!existsSync(dir)) return null;
   try {
-    const entries = readdirSync(dir, { withFileTypes: true });
-    return entries.filter((e) => e.isFile() && e.name.endsWith('.md')).length;
+    const names = slashCommandNames(root);
+    if (names.length === 0 && !existsSync(join(root, 'commands'))) return null;
+    return names.length;
   } catch {
     return null;
   }
@@ -180,7 +186,7 @@ const REGISTRY = [
   },
   {
     id: 'commands-count',
-    label: 'commands/*.md file count',
+    label: 'slash-command count (commands/*.md + user-invocable skills)',
     sources: SOURCE_SET_INVENTORY,
     severity: 'medium',
     getActual: countCommands,

package/skills/discovery/probes/vault-narrative-staleness.mjs

@@ -24,6 +24,7 @@
 
 import { existsSync, readFileSync, readdirSync, mkdirSync, appendFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { expandTilde } from '../../../scripts/lib/common.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -73,9 +74,12 @@ function parseFrontmatter(text) {
 // Helpers
 // ---------------------------------------------------------------------------
 
+// #1506 pt 6: the committed value is `~/Projects/vault`; unexpanded it resolved
+// against the cwd (`<cwd>/~/Projects/vault`), where a stray `~` directory
+// produced a false all-clear (0 stale narratives instead of 33).
 function resolveVaultDir(projectRoot, config) {
-  if (config?.['vault-integration']?.['vault-dir']) return config['vault-integration']['vault-dir'];
-  if (process.env.VAULT_DIR) return process.env.VAULT_DIR;
+  if (config?.['vault-integration']?.['vault-dir']) return expandTilde(config['vault-integration']['vault-dir']);
+  if (process.env.VAULT_DIR) return expandTilde(process.env.VAULT_DIR);
   return null;
 }
 

package/skills/discovery/probes/vault-staleness.mjs

@@ -38,6 +38,7 @@
 
 import { existsSync, readFileSync, readdirSync, mkdirSync, appendFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { expandTilde } from '../../../scripts/lib/common.mjs';
 
 // ---------------------------------------------------------------------------
 // Minimal YAML frontmatter parser — top-level scalar fields only (<30 lines).
@@ -112,13 +113,18 @@ export async function runProbe(projectRoot, config) {
   try {
     // --- Config validation (early exit paths) ---
 
-    const vaultDir = config?.['vault-integration']?.['vault-dir'];
-    if (!vaultDir) {
+    const configuredVaultDir = config?.['vault-integration']?.['vault-dir'];
+    if (!configuredVaultDir) {
       return makeSkip('vault-dir not configured');
     }
+    // #1506 pt 6: the committed value is `~/Projects/vault`; unexpanded it
+    // resolved against the cwd (`<cwd>/~/Projects/vault`), where a stray `~`
+    // directory produced a false all-clear (0 projects scanned instead of 45).
+    const vaultDir = expandTilde(configuredVaultDir);
 
     if (!existsSync(vaultDir)) {
-      return makeSkip(`vault-dir does not exist: ${vaultDir}`);
+      // The configured spelling, not the expanded one: no home dir in the output.
+      return makeSkip(`vault-dir does not exist: ${configuredVaultDir}`);
     }
 
     const projectsDir = join(vaultDir, '01-projects');

package/skills/docs-orchestrator/SKILL.md

@@ -177,9 +177,15 @@ No Docs task generated for this audience.
 documents what the docs-writer MUST do when executing a dispatched Docs task.
 
 Before writing any documentation, the docs-writer MUST read and ingest the actual
-source material provided in the task prompt. The canonical four source types are:
-
-1. **diff** — `git diff $SESSION_START_REF..HEAD` — the verbatim diff of all changes
+source material provided in the task prompt. The canonical four source types are
+below. `$SESSION_RANGE` is ONE complete diff range: inside a wave run it is
+`"$SESSION_START_REF..HEAD"` (the SHA wave-executor pins at Pre-Wave 1a); at
+session end it is what the accessor in `skills/session-end/plan-verification.md`
+§ SESSION_START_REF accessor exports — the pinned SHA, else the resolved
+`<base>...HEAD`, never a hard-coded `origin/main`. Diffs take the range; the log
+keeps the two-dot `$SESSION_START_REF..HEAD`, which is the correct form for `git log`.
+
+1. **diff** — `git diff "$SESSION_RANGE"` — the verbatim diff of all changes
    made during this session. This is the primary authoritative source for what changed.
 2. **git-log** — `git log $SESSION_START_REF..HEAD --format="%H %s%n%b"` — commit
    messages and associated bodies. Secondary context for all audiences; use to
@@ -284,9 +290,10 @@ The docs-writer MUST emit a brief structured output summary:
 1. Collect every task classified as `Docs` in the plan.
 2. For each task, resolve the expected `file-pattern` target and check for a diff:
    ```bash
-   git diff --name-only $SESSION_START_REF..HEAD
+   git diff --name-only "$SESSION_RANGE"
    ```
-   Match the output against the task's file-pattern using glob matching.
+   (`$SESSION_RANGE` from the session-end accessor above; an empty range is a skip
+   with a named reason, never "no docs changed".) Match the output against the task's file-pattern using glob matching.
 3. Classify gaps by severity:
    - **missing diff** — no matching file was changed; the task did not run or produced
      no output.

package/skills/docs-orchestrator/audience-mapping.md

@@ -23,14 +23,16 @@ traceable source gets `<!-- REVIEW: source needed -->` — the agent NEVER inven
 
 | Source | Command / Path | Primary audience(s) | Notes |
 |--------|---------------|---------------------|-------|
-| **diff** | `git diff $SESSION_START_REF..HEAD` | Dev, Vault | Authoritative for what changed and when. Preferred primary source for Dev. |
+| **diff** | `git diff "$SESSION_RANGE"` | Dev, Vault | Authoritative for what changed and when. Preferred primary source for Dev. |
 | **git-log** | `git log $SESSION_START_REF..HEAD --format="%H %s%n%b"` | All | Secondary context; use to reconstruct the "why" when diffs alone are ambiguous. |
 | **session-memory** | `~/.claude/projects/<project>/memory/session-*.md`, `.orchestrator/` outputs | Vault, User | Primary for Vault narratives (status updates, decisions made in conversation). Also primary for User tasks designed interactively. |
 | **affected-files** | Files in wave-scope `allowedPaths` / coordinator `affected-files` context block | User, Dev | Primary for understanding updated interfaces, config schemas, or module structures. |
 
+`$SESSION_RANGE` is one complete diff range — `"$SESSION_START_REF..HEAD"` inside a wave run, the session-end accessor's export at close (`../session-end/plan-verification.md` § SESSION_START_REF accessor; never a hard-coded `origin/main`). The log keeps the two-dot `$SESSION_START_REF..HEAD`, the correct form for `git log`.
+
 **Detailed source descriptions:**
 
-1. **diff** — Direct code changes from `git diff $SESSION_START_REF..HEAD`. Authoritative
+1. **diff** — Direct code changes from `git diff "$SESSION_RANGE"`. Authoritative
    for Dev narratives (what changed and why) and Vault decisions (what was decided, when).
    Preferred primary source for Dev audience tasks.
 2. **git-log** — Commit messages and associated PR/MR bodies from
@@ -90,7 +92,7 @@ Trigger: New `coordinator-snapshot.mjs` module added; CWD-drift guard introduced
 ## Allowed Sources
 Only these four sources are permitted. Do not use general knowledge.
 
-- diff: `git diff $SESSION_START_REF..HEAD` (provided below)
+- diff: `git diff "$SESSION_RANGE"` (provided below)
 - git-log: `git log $SESSION_START_REF..HEAD --format="%H %s%n%b"` (provided below)
 - session-memory: wave summaries and agent outputs from
   ~/.claude/projects/<project>/memory/session-*.md and .orchestrator/ (provided below)

package/skills/evolve/SKILL.md

@@ -171,18 +171,27 @@ If user selects "Confidence ändern", "Ablauf verlängern", or "Delete specific
 
 Use the same archive-safe pipeline as Phase 3, Step 3.5 — **never** a hand-rolled `>` rewrite (#1017):
 
-1. Read all lines from `learnings.jsonl`
+1. Snapshot the store into the sidecar exactly as Phase 3, Step 3.5(1) does (`--prune --snapshot`,
+   with the same `--file` / `--archive` the apply will use) and work on the sidecar, never on a
+   separate read of `learnings.jsonl` (#1486). A snapshot exit `1` (a malformed store line, or a
+   PATH that would replace a ledger) wrote nothing: surface it and stop
 2. Apply the selected operation to selected learnings:
-   - **Boost:** +0.15 confidence (cap 1.0), reset expires_at to +`learning-expiry-days`
+   - **Boost:** +0.15 confidence (cap 1.0), reset expires_at to `deriveExpiresAt(now, type)` (per-type TTL, `scripts/lib/learnings/schema.mjs`)
    - **Reduce:** -0.2 confidence
    - **Delete:** omit the selected entries from the next generation — do NOT delete them by hand.
      `pruneLearnings()` detects every **record** that left the store — reconciled by `id`, or by a
      content fingerprint when a record carries no usable `id` — and archives it with
      `_archive_reason: "pruned"`, so a `learning-id` referenced by a rendered rule stays resolvable.
-   - **Extend:** reset expires_at to current date + `learning-expiry-days`
+   - **Extend:** reset expires_at to `deriveExpiresAt(now, type)` — `learning-expiry-days` is parsed but read by no script (`skills/_shared/config-reading.md` § Learning Expiry Semantics)
 3. Steps 3–5 of the old prose (prune / consolidate / rewrite) are `pruneLearnings()` — run the
    **exact** Step 3.5(5) invocation, writing the post-operation entry set to the `--entries`
-   sidecar. It prunes
+   sidecar below its line-1 `_store_generation` header. Exit `1` or `2`: surface the error and
+   stop (`1` includes a sidecar snapshotted from another store than `--file`). Exit `3` means the
+   store changed after the snapshot and nothing was written: snapshot into a FRESH path,
+   re-apply the selected operations to the records in that file, and apply it once more — a
+   second consecutive `3`: stop and report. Never move the fresh header onto the old sidecar's
+   records, whose missing peer change the prune would archive `pruned` (Step 3.5(5) carries the
+   full exit-code rule). It prunes
    (`expires_at` < now → `expired`; `confidence <= 0.0` → `pruned`), consolidates duplicates
    (same `type` + non-empty `subject`, highest confidence wins, loser archived `superseded` with
    `_superseded_by`; null-subject entries preserved individually per #284), and rewrites through

package/skills/evolve/references/evolve-analyze-mode.md

@@ -61,10 +61,9 @@ For each of the 9 built-in analyzer learning types, apply these heuristics.
 
 - Compare `total_agents` and `total_waves` across session types
 - Calculate average agents per wave for each session type. Read a wave's agent count defensively — older records use other keys: `agent_count`, else `agents` when it is a number, else the length of `agents` when it is an array (of descriptions), else `agents_dispatched`. A record with `total_waves: 0` contributes no per-wave ratio — skip it rather than divide by zero. Exclude coordinator-direct waves (`coordinator_direct: true`, which dispatched no agents) from the ratio. In particular, a record whose waves are all coordinator-direct `Housekeeping` waves (predicate `isCoordinatorDirectHousekeeping` in `scripts/lib/session-schema/filters.mjs`, the session-end writer shape since #1321) contributes no per-wave ratio, same as `total_waves: 0`. Counting it would log a false 0.0 agents-per-wave observation.
-- **Group by `(session_type, session_profile)` (#1247), never by `session_type` alone.** `ultradeep` is a PROFILE over `session_type: deep` (7 waves vs. deep's 4-5, STATE.md frontmatter key `session-profile` — see `scripts/lib/state-md.mjs`), not a distinct type, so a bare `session_type` grouping folds a 7-wave ultradeep session and a 5-wave deep session into the same row and silently averages their agents-per-wave and over-delivery numbers together.
+- **Group by `(session_type, session_profile)` (#1247), never by `session_type` alone.** `ultradeep` is a PROFILE over `session_type: deep` (7 waves vs. deep's 4-5, STATE.md frontmatter key `session-profile` — see `scripts/lib/state-md.mjs`), not a distinct type, so a bare `session_type` grouping folds a 7-wave ultradeep session and a 5-wave deep session into the same row and silently averages their agents-per-wave numbers together.
 - Subject = `sizingSubject({ session_type, session_profile })` from `scripts/lib/learnings/sizing-subject.mjs` — e.g. `deep-session-sizing` (no profile, byte-identical to the pre-#1247 literal), `deep-ultradeep-session-sizing` (profile `ultradeep`), or `feature-session-sizing`. Always derive via this helper; do not hand-concatenate the subject string.
 - Insight = "Deep sessions average X agents across Y waves" or "Ultradeep sessions average X agents across Y waves" (name the profile in the insight whenever `session_profile` is present, so the two rows read as distinct sizing observations, not variants of one sentence)
-- **Over-delivery ratio aggregation (#730/H4, #794.7; keyed by profile since #1247):** compute the MEDIAN of `waves[].over_delivery_ratio` across the last ~5 `sessions.jsonl` records of the same `(session_type, session_profile)` pair, filtered to waves whose `role` is not `Discovery`/`Finalization` and which carry the field (skip records lacking the field — pre-#730; also skip Discovery/Finalization waves, whose planned set is empty by design). This exclusion clause is intentionally identical to `skills/session-plan/SKILL.md` Step 0.5 "Over-delivery sizing" — keep the two wordings in sync on edit. Fold the median into this candidate's `insight`/`evidence` fields — e.g. `evidence`: `"median_over_delivery_ratio: 1.4 (n=12 waves, session_type=deep, session_profile=ultradeep)"` — so `session-plan` Step 0.5 can read the ratio from the `effective-sizing` learning first, falling back to its own direct `sessions.jsonl` scan only when no such learning exists.
 
 #### 3. recurring-issue (type: `recurring-issue`)
 
@@ -209,7 +208,7 @@ If user selects "Skip all" or selects nothing, abort gracefully: "No learnings s
 
 For confirmed learnings, use atomic rewrite strategy:
 
-1. Read ALL existing lines from `.orchestrator/metrics/learnings.jsonl` (if exists) into memory. If not found, check `<state-dir>/metrics/learnings.jsonl` as a legacy fallback. If legacy data is found, it will be migrated to the v2 path on write (step 5).
+1. Snapshot the store into the sidecar: `node scripts/sweep-expired-learnings.mjs --prune --snapshot .orchestrator/tmp/learnings-next.jsonl`. It writes every record of `.orchestrator/metrics/learnings.jsonl` to that file behind a line-1 `{"_store_generation": "sha256:…", "_store_path": "…"}` header naming the exact store state and the store they came from. Read the SIDECAR, not the store, as your starting set — step 5 explains why. On a non-default store, pass the SAME `--file` / `--archive` here as to the step-5 apply: the apply refuses (exit `1`) a sidecar snapshotted from another store. A store holding a malformed (unparseable) line does NOT stop the snapshot: it prints a stderr WARN naming the line numbers and adds a `malformed` count to its summary. The sidecar carries records only, and the step-5 apply keeps the store's malformed lines verbatim at the end of the rewrite, never archived — report the count to the operator; never hand-edit the store to remove them. The one sanctioned repair is `node scripts/sweep-expired-learnings.mjs --drop-malformed --line N [--line M …]`: a dry run by default, printing each line's preview, any readable record it still carries (`bom` / `embedded_record`) and the store generation; only after the operator confirmed those previews, `--drop-malformed --line N --apply --generation <TOKEN> --repo-root "$(pwd)"` removes the lines (backup `<stem>.pre-drop-malformed.jsonl.bak-<ISO>` beside the store). A line still holding a readable record needs `--accept-embedded`; a store that changed since the dry run exits `3`. If the snapshot holds zero records, check `<state-dir>/metrics/learnings.jsonl` as a legacy fallback and add its records below line 1; they are migrated to the v2 path on write (step 5).
 2. Apply confidence updates for confirmed existing learnings:
    - Increment confidence by +0.15
    - Cap at 1.0
@@ -236,9 +235,22 @@ For confirmed learnings, use atomic rewrite strategy:
    deleted 11 of 13 `learning-id` provenance targets referenced by rendered `.claude/rules/*.md`.
    Do not hand-roll a `jq | ... > learnings.jsonl` pass; it bypasses every #721 safety net.
 
-   Write the full next-generation entry set (existing entries **with** the step-2/3 confidence
-   updates, **plus** the step-4 new learnings) as JSONL to a temp sidecar **via the Write tool**
-   (not a shell `>` redirect — the destructive-command guard blocks it), then invoke the
+   Turn the step-1 sidecar `.orchestrator/tmp/learnings-next.jsonl` into the full
+   next-generation entry set (existing entries **with** the step-2/3 confidence updates,
+   **plus** the step-4 new learnings) **via the Write or Edit tool** (not a shell `>` redirect —
+   the destructive-command guard blocks it), **keeping line 1, the `_store_generation` header,
+   unchanged and first**. The sidecar lives under `.orchestrator/tmp/`, never
+   `.orchestrator/metrics/`, because `tmp/` is outside
+   the ledger guard's `ledger-delete-protected` denylist — a metrics-dir sidecar made the
+   cleanup `rm` below a blocked command (#1453).
+
+   **Snapshot → token → apply refuses on drift (#1486).** Minutes pass between step 1 and the
+   call below, and a peer session may append to the store meanwhile. Such a record is on disk
+   but absent from your sidecar, so the prune would archive it `pruned` — a delete nobody
+   decided, which the store lock cannot prevent because your read happened before it, in
+   another process. So the prune re-reads the store under its lock and compares that
+   generation with the header: any difference writes nothing and exits `3`. A sidecar without
+   the header exits `1` — the header is mandatory, never optional. Then invoke the
    `--prune` subcommand of the sweep CLI. **This call is also `/evolve`'s ONLY
    `orchestrator.evolve.completed` success emit (#1206)** — export `N` (Step 3.5(4)'s
    new-learnings count), `M` (Step 3.5(2)'s reinforced-existing count) and `DURATION_MS`
@@ -247,14 +259,15 @@ For confirmed learnings, use atomic rewrite strategy:
    an argument error:
 
    ```bash
-   NEXT=".orchestrator/metrics/.learnings-next.jsonl"   # written by the step above
+   NEXT=".orchestrator/tmp/learnings-next.jsonl"   # written by the step above
    node scripts/sweep-expired-learnings.mjs --prune --apply --json --entries "$NEXT" \
      --appended "${N:-0}" --boosted "${M:-0}" --duration-ms "${DURATION_MS:-0}" \
      --repo-root "$(pwd)" && rm -f "$NEXT"
    ```
 
    `--file` / `--archive` default to the canonical store + archive paths — pass them only when
-   operating on a non-default pair. The command prints ONE JSON line; capture it as `$PRUNE` and
+   operating on a non-default pair, and then pass the same pair to the step-1 `--snapshot` too.
+   The command prints ONE JSON line; capture it as `$PRUNE` and
    report its `{scanned, kept, archived, byReason}` in the final summary — `$PRUNE.archived` is
    also the `pruned` counter the emit above just wrote, so there is nothing left to compute for
    the telemetry after this line. Preview first with `--prune --dry-run --json` (same counts,
@@ -269,12 +282,22 @@ For confirmed learnings, use atomic rewrite strategy:
    > independently of the write it reported on. Do not re-inline either, and do not hand-roll a
    > `jq | ... > learnings.jsonl` pass — that bypasses every #721 safety net.
 
-   **Exit codes are the no-op rule.** `0` = applied (or a clean no-op). `1` = input error: the
-   sidecar is absent, carries a malformed line, or holds no records — the store and the archive
-   were **not touched**;
-   re-write the sidecar and re-run. `2` = the prune itself failed inside the lib. On any non-zero
-   exit, surface the error and stop — never retry with a shell rewrite, and never delete `$NEXT`
-   (the `&&` above already withholds the `rm`, so the assembled generation survives for a retry).
+   **Exit codes are the no-op rule.** `0` = applied (or a clean no-op). On `1` and `2`, surface
+   the error and stop. `1` = input error: the sidecar is absent, carries a malformed line, holds
+   no records, lacks its line-1 `_store_generation` header, or was snapshotted from another store
+   than this call's `--file` — the store and the archive were **not touched**. `2` = the prune
+   itself failed inside the lib. `3` =
+   `store-generation-mismatch`: the store changed after step 1 and nothing was written. This one
+   is a retry, not a stop: snapshot into a FRESH path
+   (`--prune --snapshot .orchestrator/tmp/learnings-next-retry.jsonl`, with the same `--file` /
+   `--archive` as the apply), re-apply this run's
+   decisions to the records in THAT file — they now include the peer's change — and run the block
+   above with its `NEXT` set to the fresh path. Retry once: a second consecutive `3` means the
+   store keeps moving under you — stop and report it. Never move the fresh header onto the old
+   sidecar's records: they lack exactly the peer change the header exists to protect, so the
+   prune would archive it `pruned` (the error prints no token for that reason). On every exit,
+   never retry with a shell rewrite and never delete `$NEXT` — the `&&` above withholds the `rm`,
+   so the assembled generation survives as the record of this run's decisions.
 
    `pruneLearnings()` — the function the subcommand calls — performs steps 6 + 7 + 8 mechanically
    and archives **every** record that
@@ -301,21 +324,22 @@ For confirmed learnings, use atomic rewrite strategy:
    old "read back the first line to confirm valid JSON" check is redundant here: `rewriteLearnings()`
    round-trip-validates EVERY line before any byte reaches disk (#662), and the `malformed` guard
    above rejects an unparseable sidecar before the store is touched at all.
-6. **Vault mirror (conditional):** Check `$CONFIG."vault-integration".enabled` via jq. If the field is missing or `false`, skip this step entirely — skill behavior is unchanged.
+6. **Vault mirror (conditional):** Check `$CONFIG."vault-integration".enabled` via jq. If `$CONFIG."vault-integration"."host-override"` is set and the integration is off (`enabled` is `false` or `mode` is `off`), report `vault-mirror: bewusst aus auf diesem Host (<host-override>)` and skip this step — the host switched it off on purpose (SO#1448), so this is never a failure, even when the committed mode is `strict`. Otherwise, if the field is missing or `false`, skip this step entirely — skill behavior is unchanged.
 
    If `enabled` is `true`:
 
    a. Check `$CONFIG."vault-integration".mode`. If `mode` is `off`, skip the mirror invocation (treat as disabled). If `mode` is absent, default to `warn`.
 
-   b. Resolve the vault directory: use `$CONFIG."vault-integration"."vault-dir"` if non-null, otherwise fall back to the `$VAULT_DIR` environment variable. If neither is set, emit a warning and skip.
+   b. Resolve the vault directory: use `$CONFIG."vault-integration"."vault-dir"` if non-null, otherwise fall back to the `$VAULT_DIR` environment variable. If neither is set, emit a warning and skip. Report `vault-dir=<path> (Quelle: <source>)`, where `<source>` is `$CONFIG."vault-integration"."vault-dir-source"` (`env`, `match`, `owner`, `committed`), or `env VAULT_DIR` when the fallback was used.
 
-   c. Invoke the mirror script. Derive a synthetic `EVOLVE_SESSION_ID` so the vault-mirror auto-commit phase (#31) produces a traceable commit subject (`chore(vault): mirror evolve-<date> — N learnings + 0 sessions`). Pass `--vault-name` when `vault-integration.vault-name` is set in Session Config:
+   c. Invoke the mirror script from the repo root, by its plugin path — `--repo-root "$PWD"` plus an absolute `--source` make the vault namespace this repo's identity, and a ledger from a different repo is refused (exit 2, `source-repo-mismatch`, #1503) instead of overwriting another project's notes. Derive a synthetic `EVOLVE_SESSION_ID` so the vault-mirror auto-commit phase (#31) produces a traceable commit subject (`chore(vault): mirror evolve-<date> — N learnings + 0 sessions`). Pass `--vault-name` when `vault-integration.vault-name` is set in Session Config:
       ```bash
       EVOLVE_SESSION_ID="evolve-$(date -u +%Y-%m-%d-%H%M)"
       EVOLVE_VAULT_NAME=$(echo "$CONFIG" | jq -r '."vault-integration"."vault-name" // empty')
       node "$PLUGIN_ROOT/scripts/vault-mirror.mjs" \
         --vault-dir "<vault-dir>" \
-        --source .orchestrator/metrics/learnings.jsonl \
+        --repo-root "$PWD" \
+        --source "$PWD/.orchestrator/metrics/learnings.jsonl" \
         --kind learning \
         --session-id "$EVOLVE_SESSION_ID" \
         ${EVOLVE_VAULT_NAME:+--vault-name "$EVOLVE_VAULT_NAME"}

package/skills/memory-cleanup/SKILL.md

@@ -25,7 +25,7 @@ description: >
 
 The user invoked `/memory-cleanup` with arguments: **$ARGUMENTS**. Parse them before anything else — two optional, mutually-exclusive flags are recognised (`--dry-run`, `--apply-pending`, see PRD #502); passing both is an error, and the absence of both selects the legacy interactive 4-phase mode. The per-flag behaviour, the exact status lines and the exit codes are in § Argument Handling (Phase 0) below; the interactive default runs Phases 1-4 (Orient → Gather Signal → Consolidate → Prune & Index) against `~/.claude/projects/<encoded-cwd>/memory/` and reports per § Output.
 
-Sidecar producer/consumer contract: session-end Phase 3.6.5 (`scripts/lib/auto-dream.mjs`) is nudge-only (#614) — it never dispatches a subagent to write the sidecar. The only real producer of `.orchestrator/pending-dream.md` is a manual `/memory-cleanup --dry-run` run; `--apply-pending` is the operator-confirmed consumer in a later session. The sidecar file is single-writer — concurrent sessions cannot collide because the writer holds the session-lock. <!-- path-check: example -->
+Sidecar producer/consumer contract: session-start's `maintenance-due` probe uses `scripts/lib/auto-dream.mjs` to report when cleanup is due; the former session-end Phase 3.6.5 nudge was retired in #1288. Neither path generates the sidecar. The only real producer of `.orchestrator/pending-dream.md` is a manual `/memory-cleanup --dry-run` run; `--apply-pending` is the operator-confirmed consumer in a later session. The sidecar file is single-writer — concurrent sessions cannot collide because the writer holds the session-lock. <!-- path-check: example -->
 
 Implements the 4-phase memory consolidation process modelled after Claude Code's Auto Dream feature. Run after major refactors, framework migrations, or every 5+ sessions in a repo.
 

package/skills/persona-panel/SKILL.md

@@ -184,8 +184,8 @@ Dispatch one Agent per persona from the active catalog set.
 
 **Model selection per persona:**
 - If `persona.model` is a full Claude model ID (`MODEL_ID_RE`): use it as-is.
-- If `persona.model` is `opus` or unset AND `persona.tier == 'domain-expert'`: override to
-  `claude-opus-4-7` (empirically validated — Opus finds real problems Sonnet misses; see vault
+- If `persona.model` is `opus` or unset AND `persona.tier == 'domain-expert'`: use the alias
+  `opus`, which tracks the current Opus — pin a full ID only for a named reproducibility need (empirically validated — Opus finds real problems Sonnet misses; see vault
   learning `[[persona-opus-finds-real-failing-cibadge]]`).
 - Otherwise: use the persona's declared model alias.
 

package/skills/persona-panel/persona-format.md

@@ -28,7 +28,7 @@ name: ai-expert
 schema_version: 1
 version: "2"
 role: "AI/ML domain expert — evaluates technical accuracy and implementation quality"
-model: claude-opus-4-7
+model: opus
 tier: domain-expert
 output_contract:
   type: object
@@ -59,7 +59,7 @@ evaluation_criteria:
 | `schema_version` | integer | Must be `1`. |
 | `version` | string | Non-empty string. Persona content version. Increment on any output-affecting change. Used in sidecar + trend-tracking (#459). |
 | `role` | string | Identity statement. Injected verbatim as prompt opener. Keep under 200 chars. |
-| `model` | string | Full model ID (`MODEL_ID_RE`) or alias (`inherit|sonnet|opus|haiku`). Validated at load time. Recommend `claude-opus-4-7` for `domain-expert` and `compliance` tiers (Opus finds real issues Sonnet misses — vault learning `[[persona-opus-finds-real-failing-cibadge]]`). |
+| `model` | string | Full model ID (`MODEL_ID_RE`) or alias (`inherit|sonnet|opus|haiku`). Validated at load time. Recommend the Opus tier via alias `opus` for `domain-expert` and `compliance` tiers (Opus finds real issues Sonnet misses — vault learning `[[persona-opus-finds-real-failing-cibadge]]`); the alias tracks the current Opus; pin a full model ID only for a named reproducibility need, and name the reason. |
 | `output_contract` | object | Inline JSON Schema Draft 2020-12. `$ref/$defs/allOf/anyOf` FORBIDDEN (H3). Must require `verdict` + `rationale`. AJV compile wrapped in 2s AbortSignal timeout. |
 | `evaluation_criteria` | array | Non-empty. Each string max 512 chars. Injected wrapped in `<persona-criteria>` delimiters (M1). Write as statements, not questions. |
 | `tier` | enum | `domain-expert` \| `buyer-persona` \| `auditor` \| `compliance` \| `reviewer` \| `custom`. Affects model selection (Phase 3). |

package/skills/persona-panel/presets/designer-lens.md

@@ -3,7 +3,7 @@ name: designer-lens
 schema_version: 1
 version: "1"
 role: "Designer lens — evaluates interaction flow, cognitive load, consistency, and accessibility"
-model: claude-opus-4-7
+model: opus
 tier: domain-expert
 evaluation_criteria:
   - "The interaction flow is legible on first encounter — a new user can predict what happens next without hidden state."

package/skills/persona-panel/presets/engineer-lens.md

@@ -3,7 +3,7 @@ name: engineer-lens
 schema_version: 1
 version: "1"
 role: "Engineer lens — evaluates feasibility, complexity, failure modes, and long-term maintainability"
-model: claude-opus-4-7
+model: opus
 tier: domain-expert
 evaluation_criteria:
   - "Failure modes are enumerated — what breaks under load, bad input, or partial failure, and how the system responds."

package/skills/persona-panel/presets/pm-lens.md

@@ -3,7 +3,7 @@ name: pm-lens
 schema_version: 1
 version: "1"
 role: "Product Manager lens — evaluates user value, outcome-metric clarity, and scope discipline"
-model: claude-opus-4-7
+model: opus
 tier: domain-expert
 evaluation_criteria:
   - "The change is tied to a specific, named user or business problem — not a solution in search of one."