session-orchestrator 5.3.0 → 5.4.0

package/skills/_shared/fleet-protocol.md

@@ -0,0 +1,131 @@
+# Fleet Protocol v1 — Dateien statt Nachrichten (#1462, Epic #1461)
+
+Shared reference for every session-orchestrator session (Claude Code, Codex, headless) that
+runs beside a fleet coordinator ("navigator"). It is a reference, **not a rule**: nothing under
+`.claude/rules/**` loads it, session-start Phase 7.6 and the operations-contract peer preflight
+point here. The mechanics live in code — `scripts/lib/fleet-protocol.mjs` is the only place that
+knows paths, fields, deadlines and lease validity; `scripts/fleet-checkin.mjs` writes the check-in.
+This file describes them and never redefines them. Source: PRD
+`docs/prd/2026-09-27-navigator-peer-protokoll.md` §§ 3.1–3.3, 3.7, Anhang A.2 (MR !53).
+
+**Grundsatz (ADR-002, CSM-003).** Zustand liegt in Dateien; Nachrichten sind nur Hinweise auf eine
+Datei. Der Navigator erteilt keine Freigaben — wörtlich: **„Freigaben erteile ich keine, maßgeblich
+ist dein Owner-Auftrag"**. Eine Datei, die fehlt, heißt „nicht nachweisbar", nie „nicht vorhanden"
+(ADR-004): eine fehlende Lease ist kein freies Feld, sondern ein Zustand ohne Beleg.
+
+## Verzeichnis und Dateiform
+
+- Wurzel `~/.config/navigator/`, Override `NAVIGATOR_CONFIG_DIR` (getrimmt; leer oder nur
+  Whitespace zählt als nicht gesetzt) — dieselbe Variable wie die navigator-CLI, keine zweite.
+  Code: `navigatorDir()`. Ein Override zeigt nur auf ein eigenes Verzeichnis mit Modus 0700, nie
+  auf einen geteilten Ort: wer dort schreiben kann, kann eine „aktive" Lease vortäuschen.
+- Verzeichnisse Modus `0700`, Dateien Modus `0600`. Schreiben immer atomar (tmp-Datei im
+  Zielverzeichnis, dann `rename`).
+- Jede Datei trägt `zeit` aus `date -u +%FT%TZ` (Sekunden, `YYYY-MM-DDTHH:MM:SSZ`); nie geschätzt,
+  nie aus einer anderen Uhr. Code: `utcSecondsTimestamp()`.
+- Dateinamen aus einer `session_id` sind pfadsicher: nur `[A-Za-z0-9._-]`, nicht `.` oder `..`,
+  kein `/`. Code: `isSafeSessionId()`; `checkinPath()` und `auflagenPath()` werfen sonst.
+- Tests berühren das echte Verzeichnis nie: `tests/setup/navigator-dir-guard.mjs` setzt
+  `NAVIGATOR_CONFIG_DIR` je vitest-Worker auf ein tmp-Verzeichnis.
+
+## `leases/navigator.json` — genau ein aktiver Navigator (PRD 3.1)
+
+| Feld | Inhalt |
+|---|---|
+| `session_id` | Registry-ID des Navigators (Pflicht; pfadsicher wie oben, höchstens 128 Zeichen) |
+| `plattform` | `claude` \| `codex` \| `kopflos` (Pflicht) |
+| `adresse` | `ListAgents`-Name, wenn Claude (`[A-Za-z0-9._:@-]`, 1–128 Zeichen); sonst `null` |
+| `seit` | Zeit des Erwerbs, UTC mit `Z`, Sekunden oder Millisekunden (Pflicht) |
+| `laeuft_ab` | UTC mit `Z`; Erneuerung je Ticker-Runde, Ablauf 30 min nach der letzten (Pflicht) |
+| `uebergabe_an` | `null` oder Session-ID des Nachfolgers |
+
+**„Aktiv" heißt ausschließlich: gültige Lease.** `readNavigatorLease()` liefert genau eines von
+`active` (Datei lesbar, Pflichtfelder da, `laeuft_ab` in der Zukunft), `none` (Datei fehlt oder
+`laeuft_ab` überschritten) oder `unreadable` (kaputtes JSON, fehlende Pflichtfelder, Lesefehler, oder ein Feld außerhalb der
+Tabellenform: unbekannte `plattform`, Steuerzeichen in `session_id`/`adresse`, eine Zeit ohne `Z`
+oder mit Offset — sie würde in lokaler Zeit gelesen und könnte die Lease verlängern).
+Unlesbar oder abgelaufen ist **nie** aktiv (fail-closed). Registry-Heartbeat (`role: navigator`,
+`scripts/lib/session-registry.mjs`) und `ListAgents` sind Zusatzsignale, keine Lebendbeweise.
+Erwerb und Übergabe der Lease sind S4 (agents/navigator#36), nicht Teil dieses Repos.
+
+## `checkin/<session_id>.json` — Session an Navigator (PRD 3.2)
+
+**Schreibend** heißt: Änderung an Repo-Inhalt oder VCS-Zustand (Datei im Arbeitsbaum außerhalb
+`.orchestrator/` und `.claude/`, Commit, Branch, Push, MR, Issue, Kommentar). SO-eigener
+Sitzungszustand zählt nicht: Phase 1.1 (CLAUDE.md-Migration, einmalig), 1.2 `session.lock`, 1.5
+`STATE.md`, 1.6 Metriken, 1.7 Live-Status-Board. Phase 1.1 ist eine Repo-Datei und wird deshalb
+als Ausnahme im Check-in genannt (`vorab_geschrieben`). (`CLAUDE.md` heißt auf Codex CLI `AGENTS.md`, siehe
+`skills/_shared/instruction-file-resolution.md`.)
+
+Der Check-in liegt **vor der ersten schreibenden Aktion** (Phase 7.6, oder der Peer-Preflight der
+Operations-Route). Schreiber: `node scripts/fleet-checkin.mjs` liest das JSON von stdin, ergänzt
+`zeit`, validiert (`validateCheckin()`), schreibt atomar mit Modus 0600 und emittiert
+`orchestrator.fleet.checkin` (Payload `session`, `repo`, `modus`, `kandidaten`, `navigator_state`).
+Exit 0 geschrieben, 2 ungültige Eingabe (Fehlerliste auf stderr, keine Datei), 1 Schreibfehler.
+
+| Feld | Inhalt |
+|---|---|
+| `session`, `plattform` | Registry-ID (aus `.orchestrator/current-session.json`); `claude` / `codex` / `kopflos` |
+| `repo`, `repo_id`, `worktree` | Name; `repo_id` aus `navigator identity` oder `null`; Worktree `true`/`false` |
+| `modus` | `housekeeping` / `feature` / `deep` / `operations` |
+| `auftrag_ref` | Pfad der Auftragsdatei oder „Owner-Chat <zeit>" mit Wortlaut in einem Satz |
+| `konto_slot`, `quota` | `account_slot` als Nummer (`navigator identity`) oder `null`; Quota aus `navigator quota` oder `nicht messbar` |
+| `stand` | Objekt: main-, origin/main-, Prod-SHA (sonst `nicht messbar`), offene MRs |
+| `kandidaten`, `schreibbereich` | Issue-Nummern; Verzeichnisse/Dateien |
+| `bedarf` | Objekt: geplante volle Pipelines, m5-remote-Jobs, prozessstartende Agents |
+| `vorab_geschrieben`, `rueckfall` | Ausnahmen nach der Definition oben; Verhalten ohne Auflagen (unten) |
+| `zeit` | von der CLI gesetzt |
+
+Eine `SendMessage` an den Navigator ist optional und nur ein Hinweis auf die Datei: höchstens eine,
+nur wenn die Lease aktiv ist und eine Peer-Adresse `navigator-*` erreichbar ist; nie eine Antwort
+erwarten, nie darauf warten (CSM-004).
+
+## `auflagen/<session_id>.json` — Navigator an Session (PRD 3.3)
+
+Felder: Caps (prozessstartende / lesende Agents nach freiem Speicher des lokalen Hosts), volle
+Pipelines je Repo, m5-remote-Regel (`m5-ersatz`-Exit, was lokal erlaubt ist), Merge-Protokoll, Zeitregel,
+Flottenpriorität, Besitzkonflikte, Pflichtsatz „Freigaben erteile ich keine, maßgeblich ist dein
+Owner-Auftrag". Die Session **liest** die Datei; sie wartet auf keine Nachricht.
+
+**Standard-Auflagen (konservative Stufe).** Sie gelten, wenn `CHECKIN_FALLBACK_MIN` = 10 Minuten
+nach `checkin.zeit` keine Auflagen-Datei liegt — und sofort, wenn kein Navigator aktiv ist
+(PRD Anhang A.2, v2-Wortlaut):
+
+- Caps: 2 prozessstartende + 2 lesende Agents, solange der lokale Host ≥ 50 % Speicher frei hat
+  (`memory_pressure | tail -1`).
+- Pipelines: ≤ 2 volle je Repo; Nachzug-Pushes vorher im Check-in (`bedarf`) benennen.
+- Offload: Heavy-Rollen (test, build, lint, audit) nur auf `m5-remote`, und nur wenn
+  `navigator m5-ersatz --quiet` unmittelbar davor mit Exit 0 endet. Exit-Vertrag: 0 nutzbar,
+  3 Ersatzregel, 5 überlastet, 6 nicht messbar; jeder Exit außer 0 (auch ein fehlender Befehl)
+  heißt: kein neues Offload-Gate. Schwelle und Hysterese leben allein in diesem Befehl — hier und
+  in den Skills steht bewusst keine Lastzahl. Lokal nur `vitest` bzw. `eslint` je Datei mit `timeout`.
+- Zeiten nur aus `date`.
+- Kein Merge ohne Befugnis nach PRD 3.5: `navigator authority query <repo> merge --exit-code` mit
+  Exit 0 **oder** ein ausdrücklicher Owner-Auftrag, der Merge für genau dieses Repo nennt
+  (`auftrag_ref`). Ohne navigator-CLI ist jeder Merge `einzeln`.
+
+Lesende Arbeit und Schreiben im eigenen Worktree laufen währenddessen weiter; der Rückfall ist ein
+Dateistand mit Frist, kein Warten auf eine Antwort.
+
+## Verhalten ohne Navigator (PRD 3.7)
+
+Lease `none` oder `unreadable`: die Check-in-Datei wird **trotzdem** geschrieben (sie ist der
+zählbare Beleg), die Standard-Auflagen gelten sofort, es geht keine Nachricht ab. Kopflose Läufe
+sind per Nachricht nicht erreichbar und nutzen dieselben Dateien; ihr Brief verlangt, vor jeder
+Welle und vor jedem MR `auflagen/` und `merge/` zu lesen.
+
+## Vorschau: `merge/<repo_id>/*` (S2, #1463 — hier keine Mechanik)
+
+Ansage `ansage-<mr>.json` (MR, gepinnte Head-SHA, Pipeline-ID, Jobliste, Gate-Log-SHA, Review-Stand,
+Migration, `laeuft_ab` +20 min), Lease `lease-<mr>.json` (Navigator, +15 min), Meldung
+`done-<mr>.json` (Merge-SHA, main-Pipeline-ID, Prod-SHA). Verfall bei Ablauf, MR nicht mehr
+`opened` oder geändertem Head. Nichts davon ist in diesem Repo implementiert; bis S2 gilt PRD 3.4
+Punkt 3: selbst messen und nach 3.5 mergen, oder `navigator ask --aktion merge`.
+
+## See Also
+
+`skills/session-start/SKILL.md` Phase 7.6 · `skills/session-start/references/operations-contract.md`
+(Peer-Preflight) · `skills/_shared/state-ownership.md` § Session Identity and Lock Ownership (`role`) ·
+`docs/events-schema.md` (`orchestrator.fleet.checkin`) · `.claude/rules/cross-session-messaging.md`
+(CSM-003/004) · `scripts/lib/fleet-protocol.mjs` · `scripts/fleet-checkin.mjs` ·
+`skills/navigator/SKILL.md` (`/session-orchestrator:navigator`)

package/skills/_shared/state-ownership.md

@@ -104,6 +104,11 @@ layer.
   contract requires a trusted native resume identifier and remains a follow-up.
   In particular, a host rotation that changes both raw and semantic values has
   no guaranteed continuity.
+- **Registry `role` (`'navigator'`) is display, never ownership.** The
+  authoritative claim is the navigator lease (`leases/navigator.json` under
+  `~/.config/navigator/`, see `skills/_shared/fleet-protocol.md`); `registerSelf()`
+  does not carry the field across a repeated SessionStart, so the `/navigator`
+  skill re-sets it each ticker round via `heartbeat(id, { role })` (#1462).
 
 The peer-discovery and issue-budget procedures below apply these rules at their
 narrow surfaces; neither creates a second ownership model.

package/skills/autopilot/SKILL.md

@@ -39,11 +39,19 @@ the invocation surface only:
 Headless requirements:
 
 - Anthropic API key configured for `claude -p` (Claude Code CLI auth).
-- `scripts/autopilot.mjs` reads `sessions.jsonl` tail after each child exit to construct
-  the `sessionRunner` return shape — the spawned session must complete cleanly and append
-  its record (session-end Phase 3.7 handles this).
-- `AUTOPILOT_RUN_ID` env var is propagated to the child so session-end stamps it onto the
-  per-iteration `sessions.jsonl` record.
+- `scripts/autopilot.mjs` starts each child with `--session-id <fresh uuid>` and, after it
+  exits, reads the one canonical `sessions.jsonl` record whose `raw_session_id` is that uuid
+  to construct the `sessionRunner` return shape — the spawned session must complete cleanly
+  and append its record (session-end Phase 3.7 handles this). No such record, or more than
+  one, stops the loop with `failed-wave` instead of reading the ledger tail (#1457). So does
+  a unique record that is only a backfill stub (no waves/agents/token totals — the child never
+  closed): its token usage is unknown, not 0, so it is never counted as a healthy 0-token
+  iteration (#1457 F2).
+- `AUTOPILOT_RUN_ID` env var is set in the child's env, but **nothing reads it yet**
+  (measured 2026-10-01: `rg -n "AUTOPILOT_RUN_ID" scripts hooks skills` finds only the writer
+  in `scripts/autopilot.mjs` and this line). CLI-driven iterations therefore carry no
+  `autopilot_run_id` on their `sessions.jsonl` record yet; join them to `autopilot.jsonl` via
+  the `sessions` list there, not via that field.
 
 Do NOT re-implement loop logic inline — this skill and `scripts/lib/autopilot.mjs` are
 authoritative. Kill-switches are enforced by `scripts/lib/autopilot.mjs`, not inline by
@@ -111,7 +119,7 @@ intent for THIS run, not a standing policy.
 ## Command Surface
 
 ```
-/autopilot [--max-sessions=N] [--max-hours=H] [--confidence-threshold=0.X] [--dry-run]
+/autopilot [--max-sessions=N] [--max-hours=H] [--confidence-threshold=0.X] [--max-tokens=N] [--dry-run]
 ```
 
 | Flag | Default | Bounds | Meaning |
@@ -119,6 +127,7 @@ intent for THIS run, not a standing policy.
 | `--max-sessions` | `5` | 1..50 | Iteration cap (graceful exit when reached) |
 | `--max-hours` | `4.0` | 0.5..24.0 | Wall-clock budget for entire loop |
 | `--confidence-threshold` | `0.85` | 0.0..1.0 | Minimum `selectMode` confidence for auto-execute |
+| `--max-tokens` | `0` (off) | 0..10000000 | Token budget for `token-budget-exceeded`. Unit: cumulative **subagent OUTPUT** tokens, summed from each `sessions.jsonl` record's `total_token_output` (falling back to `total_tokens`, which is subagent-only as well) — coordinator tokens are not counted. Off by default until calibrated: one measured deep session's subagents produced 450 499 output tokens, so a six-figure budget stops the loop after about one deep session |
 | `--dry-run` | `false` | — | Print planned iterations without executing |
 
 Out-of-range values silently clamp to bounds. `--dry-run` exits after printing — never
@@ -136,7 +145,7 @@ WHILE state.iterations_completed < max-sessions:
     kill_switch := 'max-sessions-reached'; break
   IF (now() - state.started_at) > max-hours:
     kill_switch := 'max-hours-exceeded'; break
-  IF cumulative_tokens_used >= max-tokens:
+  IF max-tokens > 0 AND cumulative_tokens_used >= max-tokens:
     kill_switch := 'token-budget-exceeded'; break
   IF resource_verdict() == 'critical' AND peer_count() > autopilot-peer-abort:
     kill_switch := 'resource-overload'; break
@@ -222,7 +231,7 @@ session — drives `runLoop` between manual `/session` invocations. The headless
 | Field | Signature | Source |
 |---|---|---|
 | `modeSelector` | `() => Promise<{mode, confidence, rationale?}>` | wraps `selectMode(await buildLiveSignals())` |
-| `sessionRunner` | `({mode, autopilotRunId}) => Promise<{session_id, agent_summary?, effectiveness?}>` | wraps a `/session <mode>` invocation; reads `sessions.jsonl` tail to construct return value |
+| `sessionRunner` | `({mode, autopilotRunId}) => Promise<{session_id, agent_summary?, effectiveness?}>` | wraps a `/session <mode>` invocation; reads the child's own record (matched on `raw_session_id`) to construct return value |
 | `resourceEvaluator` | `() => {verdict}` | calls `evaluate(cachedProbeSnapshot, thresholds)` from `resource-probe.mjs` over a snapshot `peerCounter` refreshed on the prior iteration — never calls `probe()` itself, which is what keeps it synchronous |
 | `peerCounter` | `() => Promise<number>` | returns `peers.length` from `detectPeers({ sessionId, freshnessMin: 15 })` (a SESSION count, not a process count — see `host-resources.md` HR-103) while refreshing the cached `probe()` snapshot `resourceEvaluator` reads |
 
@@ -278,6 +287,10 @@ const sessionRunner = async ({ mode, autopilotRunId }) => {
   // The coordinator (Claude) invokes /session <mode> manually here. After the
   // session completes (/close runs, sessions.jsonl appended), this function
   // reads the tail entry and projects it into the runLoop return-shape.
+  // CAUTION: a tail read has the peer-append error class — a parallel session
+  // that appends after this one supplies ITS record (and token usage). A real
+  // run should read its own record by raw session id, as scripts/autopilot.mjs
+  // does (readOwnSession → raw_session_id match, #1457).
   const tail = readSessionsJsonlTail(1);   // last line, normalized
   return {
     session_id: tail.session_id,
@@ -314,9 +327,10 @@ four required `runLoop` dependencies (`modeSelector`, `sessionRunner`,
 `resourceEvaluator`, `peerCounter`) plus the optional `abortSignal` to production
 sources — distinct from, and more concrete than, the in-process skeleton above:
 
-- `sessionRunner` — spawns `claude -p '/session <mode>'` as a child process; after it
-  exits cleanly, reads the `sessions.jsonl` tail to construct the return shape
-  `{session_id, agent_summary?, effectiveness?}` (`scripts/autopilot.mjs` `sessionRunner`).
+- `sessionRunner` — spawns `claude -p '/session <mode>' --session-id <uuid>` as a child
+  process; after it exits cleanly, reads the one canonical `sessions.jsonl` record whose
+  `raw_session_id` is that uuid to construct the return shape
+  `{session_id, agent_summary?, effectiveness?, usage?}` (`scripts/autopilot.mjs` `sessionRunner`).
 - `resourceEvaluator` — calls `evaluate(cachedProbeSnapshot, thresholds)` from
   `scripts/lib/resource-probe.mjs`, reading a snapshot refreshed by `peerCounter` on the
   prior iteration so the function itself stays synchronous, per the `runLoop` contract

package/skills/bootstrap/SKILL.md

@@ -94,7 +94,7 @@ Store `INVOCATION_MODE = transitive | direct`.
 
 - `private`: the existing host-local config resolution found a baseline directory and its reduced contract validated. Use `private-contract.md` for selection, templates, commands, CI and rules.
 - `public`: the resolved baseline is absent, empty, or points to a missing directory. Use plugin-bundled templates.
-- Existing but invalid configured baseline: abort before dispatch; report the reader's sanitized error reason.
+- Existing but invalid configured baseline: abort before dispatch; report the reader's sanitized error reason; for `producer-missing` also surface the `message` and the migrate-or-unconfigure choice (see `public-fallback.md` § Step 1).
 
 Pass `PATH_TYPE` into Phase 1 and all subsequent phases. All tier templates (`fast-template.md`, `standard-template.md`, `deep-template.md`) must consult `public-fallback.md` for CLAUDE.md generation and archetype file sourcing when `PATH_TYPE = public`.
 

package/skills/bootstrap/_shared-template.md

@@ -17,7 +17,7 @@ Vendor the canonical always-on rules from the plugin's `rules/` library into `$R
 
 Idempotency is handled by the writer itself:
 - Missing → create
-- Exists, plugin-owned (first line is the `<!-- source: session-orchestrator plugin ... -->` header) and byte-identical → skip silently
+- Exists, plugin-owned (the `<!-- source: session-orchestrator plugin ... -->` header is on line 1, or is the first line after a line-1 frontmatter's closing `---` — `isPluginOwnedContent()`, #1449) and byte-identical → skip silently
 - Exists, plugin-owned and stale → overwrite (the plugin copy is canonical)
 - Exists WITHOUT that header → preserved untouched (a repo-private rule the operator authored)
 

package/skills/bootstrap/fast-template.md

@@ -182,7 +182,7 @@ inherited Fast passes the confirmed contract ID and records all created paths.
 
 Idempotency is handled by the writer itself:
 - Missing → create
-- Exists, plugin-owned (first line is the `<!-- source: session-orchestrator plugin ... -->` header) and byte-identical → skip silently
+- Exists, plugin-owned (the `<!-- source: session-orchestrator plugin ... -->` header is on line 1, or is the first line after a line-1 frontmatter's closing `---` — `isPluginOwnedContent()`, #1449) and byte-identical → skip silently
 - Exists, plugin-owned and stale → overwrite (the plugin copy is canonical)
 - Exists WITHOUT that header → preserved untouched (a repo-private rule the operator authored)
 

package/skills/bootstrap/private-contract.md

@@ -22,7 +22,8 @@ BOOTSTRAP_CONTRACT=$(node "$PLUGIN_ROOT/scripts/baseline-archetypes.mjs" \
 export BOOTSTRAP_CONTRACT
 ```
 
-`status: error` aborts before scaffolding. Its reason is safe to report; do not
+`status: error` aborts before scaffolding. Its reason — and, for
+`producer-missing`, its path-free `message` — is safe to report; do not
 print baseline paths, raw producer diagnostics, or private catalog files.
 `insufficient-evidence` is a selection state, not permission to use `node-minimal`.
 Fast tier has no archetype; use the plugin's minimal instruction-file flow and

package/skills/bootstrap/public-fallback.md

@@ -23,12 +23,15 @@ export BOOTSTRAP_CONTRACT PATH_TYPE
 |----------------|--------------------|
 | No configured baseline, empty value, or missing directory | `public`; use bundled templates |
 | Existing baseline with valid reduced schema v1 export | `private`; retain `archetypes` and `selected` |
-| Existing baseline with missing CLI, invalid export, unsafe source, or producer failure | Abort; report the sanitized error reason |
+| Existing baseline directory without its `scripts/archetype-manifest.mjs` exporter (`reason: producer-missing`) | Abort with the sanitized reason and its `message`; tell the user which interface is missing and offer the two ways forward: migrate the baseline to the exporter contract ([`docs/baseline.md`](../../docs/baseline.md) § How bootstrap finds it) or unset the configured baseline path (`SO_BASELINE_PATH` / matching `owner.yaml` `baselines` entry / `paths.baseline-path` / `plan-baseline-path`) to run the public path. This is the user's decision — never silently downgrade to public. <!-- path-check: example --> |
+| Existing baseline with invalid export, unsafe source (symlink, path escape), or producer failure | Abort; report the sanitized error reason |
 | Valid private contract but no matching repository markers | `private`, `selected: null`; require selection for Standard/Deep |
 
 Lookup is offline and read-only. A broken configured contract never silently
-switches to a public archetype. Missing directories retain the established
-public fallback. Never guess a baseline path or fetch one automatically.
+switches to a public archetype. `producer-missing` is the one reason with a
+documented migration path (migrate or unconfigure, above); even then the public
+path runs only after the user unsets the configured baseline. Missing
+directories retain the established public fallback. Never guess a baseline path or fetch one automatically.
 
 ## Private Path
 

package/skills/bootstrap/references/bootstrap-retroactive-flow.md

@@ -28,7 +28,8 @@ Entered when `$ARGUMENTS` contains `--retroactive`. Writes the lock file and, pe
 4. **Infer archetype.** Run Phase 0.5's read-only source detection. For a private
    contract, use its detected `selected.id`; retain `null` with an explicit
    `insufficient-evidence` report if no markers match. An invalid configured
-   contract aborts. Do not scaffold or apply rules in this retroactive flow.
+   contract aborts (for `producer-missing`, report its path-free `message` with
+   the reason). Do not scaffold or apply rules in this retroactive flow.
    For the public path, use best-effort detection from existing files:
    - `pyproject.toml` present → `python-uv`
    - `package.json` with `next` in dependencies → `nextjs-minimal`

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/evolve/SKILL.md

@@ -173,13 +173,13 @@ Use the same archive-safe pipeline as Phase 3, Step 3.5 — **never** a hand-rol
 
 1. Read all lines from `learnings.jsonl`
 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

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`)
 
@@ -238,7 +237,12 @@ For confirmed learnings, use atomic rewrite strategy:
 
    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
+   (not a shell `>` redirect — the destructive-command guard blocks it) at
+   `.orchestrator/tmp/learnings-next.jsonl` (the Write tool creates the missing
+   `.orchestrator/tmp/` itself; from a shell, `mkdir -p .orchestrator/tmp` 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). 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,7 +251,7 @@ 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"
@@ -301,13 +305,13 @@ 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:
       ```bash

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.