session-orchestrator 5.2.0 → 5.4.0

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** — a top-level `paths:` frontmatter key is not a key `rule-loader.mjs` recognises (it only reads `globs:`), so a rule with `paths:` silently loads ALWAYS-ON regardless of intended file scope; 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/convergence-monitoring/README.md

@@ -19,7 +19,14 @@ Implemented from spec since upstream skill not yet published as of 2026-04-30.
 
 ## Invocation
 
-**Explicit:** `/convergence-monitoring` — standalone assessment from current session history.
+`user-invocable: false` — there is no `/convergence-monitoring` slash command.
+
+**Platform-native (primary, CC 2.1.105+):** registered as a plugin monitor
+(`monitors/monitors.json`); auto-starts in the background on `wave-executor`
+invocation and tails `.orchestrator/metrics/events.jsonl` for convergence signals.
+
+**Direct/model invocation:** the model dispatches this skill by name for a
+standalone assessment from current session history (fallback for harness < 2.1.105).
 
 **Embedded:** Set `convergence-monitoring: true` in Session Config. `wave-executor` and
 `/autoresearch` will call this skill automatically after each Impl-Core/Impl-Polish wave.

package/skills/convergence-monitoring/SIGNALS.md

@@ -208,12 +208,56 @@ VEL_LINES_PRIOR=<read from events.jsonl for wave N-1>
 
 The `velocity_drop` NDJSON signal counts **one `orchestrator.agent.stopped`
 record per dispatched agent** (wave read from `wave` or `wave_number`) and fires
-when the later wave stopped fewer agents than the earlier one. Measured
-2026-09-05 over `.orchestrator/metrics/events.jsonl`: 11,754
-`orchestrator.agent.stopped` records versus **0** for the `agent.dispatched` type
-the reader also accepts — `agent.stopped` is the only per-agent record this repo
-actually emits with a wave number. The git-based `VEL_COMMITS` / `VEL_LINES`
-recipe above is the SKILL-level computation and is independent of the monitor.
+when the later wave stopped fewer agents than the earlier one. `agent.stopped`
+is the only per-agent record this repo actually emits with a wave number — but
+the type is BIMODAL (#939/#949), so only records carrying a **non-empty `agent`
+field** are counted; the rest are the phantom-stop class and counting them
+inflated every per-wave count ~10.5x (#1379 P10).
+
+Measured 2026-09-18 over `.orchestrator/metrics/events.jsonl` plus the legacy
+`.jsonl.1` backup that then sat beside it — that backup was destroyed on
+2026-09-19, so the counts below are a record, not something this repo's ledger
+still reproduces.
+
+**Read the ledger through `readEventsWithRotations(repoRoot, opts)`**
+(`scripts/lib/events.mjs`), never by `cat`-ing rotation files together. It
+returns the active file plus every archive in time order, counts unreadable
+lines (`malformed_lines`), and — the reason it exists — reports a rotation
+whose archive is no longer on disk as an entry in `gaps` with `complete:
+false`, instead of silently returning a shorter history. Rotation itself no
+longer writes a `.1`..`.N` ring: since #1401 it renames the active file to
+`_archive/events-<firstTs>_<lastTs>.jsonl` and makes an
+`orchestrator.events.rotated` record naming that archive the first line of the
+new active file (`scripts/lib/events-rotation.mjs:230-258`); the reader still
+reads a legacy ring left on disk by older versions
+(`scripts/lib/events.mjs:512-539`).
+
+```bash
+node --input-type=module -e '
+import { readEventsWithRotations } from "./scripts/lib/events.mjs";
+const r = readEventsWithRotations(process.cwd());
+console.error(JSON.stringify({ gaps: r.gaps, malformed_lines: r.malformed_lines, complete: r.complete }));
+for (const e of r.events) process.stdout.write(JSON.stringify(e) + "\n");
+' | jq -s '{
+  total_stopped:      [.[]|select(.event=="orchestrator.agent.stopped")]|length,
+  with_wave:          [.[]|select(.event=="orchestrator.agent.stopped" and ((.wave//.wave_number)!=null))]|length,
+  with_wave_no_agent: [.[]|select(.event=="orchestrator.agent.stopped" and ((.wave//.wave_number)!=null) and ((.agent//"")==""))]|length,
+  with_wave_and_agent:[.[]|select(.event=="orchestrator.agent.stopped" and ((.wave//.wave_number)!=null) and ((.agent//"")!=""))]|length }'
+# 2026-09-18 (active + `.jsonl.1`):
+# → { total_stopped: 16438, with_wave: 6553, with_wave_no_agent: 5930, with_wave_and_agent: 623 }
+```
+
+i.e. 5930 of 6553 wave-scoped stops (90.5%) are phantoms, against **0** records
+of the `agent.dispatched` type the reader also accepts. The git-based
+`VEL_COMMITS` / `VEL_LINES` recipe above is the SKILL-level computation and is
+independent of the monitor.
+
+The `console.error` line is the honesty half of the reading and belongs in every
+re-measurement: a count taken from a ledger whose `gaps` is non-empty is a count
+over an unknown fraction of the history. Its blind spot is bounded and named —
+an archive deleted BEFORE #1401 left no tombstone and is undetectable by
+construction (`scripts/lib/events.mjs:556-561`), which is exactly how the
+53,896-line `.jsonl.1` vanished on 2026-09-19 without any analysis noticing.
 
 ### Thresholds
 

package/skills/convergence-monitoring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: convergence-monitoring
-user-invocable: true
+user-invocable: false
 tags: [autoresearch, convergence, loop-control, wave-executor]
 model: haiku
 model-preference: sonnet
@@ -32,9 +32,17 @@ For harness < 2.1.105 (no monitor support), the skill's manual probes documented
 
 ## When to Invoke
 
-**Explicit invocation (`/convergence-monitoring`):** Standalone assessment — reads wave
-history from `.orchestrator/metrics/events.jsonl`, computes all three signals, reports
-verdict + recovery options.
+This skill is `user-invocable: false` — there is no `/convergence-monitoring` slash
+command. It is reached two ways:
+
+**Platform-native monitor (primary path, CC 2.1.105+):** the background watcher below
+auto-starts on `wave-executor` invocation and streams verdicts as it tails
+`events.jsonl` — no explicit call needed.
+
+**Direct/model invocation (fallback, harness < 2.1.105, or a standalone assessment):**
+the model dispatches this skill by name — reads wave history from
+`.orchestrator/metrics/events.jsonl`, computes all three signals, reports verdict +
+recovery options.
 
 **Embedded (loop context):** `/autoresearch` and `wave-executor` invoke this skill after
 each Impl-Core or Impl-Polish wave when `convergence-monitoring: true` is set in Session
@@ -48,9 +56,10 @@ toward done or oscillating/stalling.
 
 ## Phase 0: Activation Gate
 
-### 0.1 Explicit Invocation
+### 0.1 Direct Invocation
 
-If invoked via `/convergence-monitoring`, skip to Phase 1 unconditionally.
+If invoked directly (not embedded from `wave-executor` or `/autoresearch`), skip to
+Phase 1 unconditionally.
 
 ### 0.2 Embedded Invocation
 

package/skills/eval/SKILL.md

@@ -15,7 +15,7 @@ args-schema:
   - flag: --verify
     description: "Re-evaluate a stored run-id and diff per-dimension for scoring drift (exit 1 on drift)"
 description: >
-  Use this skill to run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed orchestrator session against the pre-registered rubric-v1 dimensions, run /eval, evaluate this session, produce an eval report, or re-verify a stored eval run for reproducibility. Deterministic-first with an optional advisory LLM judge; never produces a global score.
+  Use this skill to run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed orchestrator session against the pre-registered rubric-v2 dimensions, run /eval, evaluate this session, produce an eval report, or re-verify a stored eval run for reproducibility. Deterministic-first with an optional advisory LLM judge; never produces a global score.
 ---
 
 > **Platform Note:** State files use the platform's native directory: `.claude/` (Claude Code), `.codex/` (Codex CLI), or `.cursor/` (Cursor IDE). Shared metrics + the eval journal live in `.orchestrator/metrics/`. See `skills/_shared/platform-tools.md`.
@@ -23,14 +23,17 @@ description: >
 # Eval Skill — Session-Process Evaluation (aiat-llm-eval/1.0)
 
 On-demand, honest measurement of ONE completed orchestrator session against the
-pre-registered **rubric-v1** check set. The deterministic engine
+pre-registered **rubric-v2** check set. The deterministic engine
 (`scripts/eval-session.mjs` → `scripts/lib/eval/engine.mjs`) reads only local
-metrics files (`sessions.jsonl` + `events.jsonl`), scores the five deterministic
+metrics files (`sessions.jsonl` + `events.jsonl`), scores the six deterministic
 dimensions, appends a `session-eval` record to the journal, and optionally
-renders an HTML report. An opt-in LLM judge overlays two advisory dimensions.
+renders an HTML report. An opt-in LLM judge overlays ONE advisory dimension
+(`instruction-adherence`; `report-quality` was retired in rubric-v2, #1381).
 
 The standard this skill implements is [`docs/eval/aiat-llm-eval-v1.md`](../../docs/eval/aiat-llm-eval-v1.md);
-the frozen, content-hashed check set is [`skills/eval/rubric-v1.md`](./rubric-v1.md).
+the frozen, content-hashed check set is [`skills/eval/rubric-v2.md`](./rubric-v2.md)
+(stored records written before 2026-09-19 carry `rubric-v1` and are read against
+[`rubric-v1.md`](./rubric-v1.md), which is never edited again).
 
 ## Invocation
 
@@ -43,7 +46,7 @@ Invoked as `/eval [--session <id>] [--no-write] [--verify <run-id>]` with argume
 
 **On-demand `/eval` runs regardless of `eval.enabled`** — that flag gates only the automatic session-end eval phase (see Phase 1.1).
 
-**Seams used:** `scripts/eval-session.mjs` (deterministic CLI) · `runEvalJudge` / `mergeJudgeDimensions` (`scripts/lib/eval/judge.mjs`, opt-in) · `writeEvalReport` (`scripts/lib/eval/report.mjs`) · `appendEvalRecord` (`scripts/lib/eval/sink.mjs`) · the `eval` config block · [`skills/eval/rubric-v1.md`](./rubric-v1.md) (frozen check set).
+**Seams used:** `scripts/eval-session.mjs` (deterministic CLI) · `runEvalJudge` / `mergeJudgeDimensions` (`scripts/lib/eval/judge.mjs`, opt-in) · `writeEvalReport` (`scripts/lib/eval/report.mjs`) · `appendEvalRecord` (`scripts/lib/eval/sink.mjs`) · the `eval` config block · [`skills/eval/rubric-v2.md`](./rubric-v2.md) (frozen check set).
 
 ## Posture Contract (load-bearing — read before executing)
 
@@ -52,9 +55,9 @@ Invoked as `/eval [--session <id>] [--no-write] [--verify <run-id>]` with argume
 - **Never guess.** Missing source data yields `cannot-determine` (a first-class,
   non-error verdict) with an honest reason — never a fabricated `pass`/`fail`.
   Do NOT "fill in" a missing KPI or infer a gate result the events do not show.
-- **Deterministic before judge.** The five deterministic dimensions are complete
-  on their own. The judge (Phase 3) is opt-in, ADVISORY, and `uncalibrated` in
-  v1 — never blend a judge verdict into the deterministic tally.
+- **Deterministic before judge.** The six deterministic dimensions are complete
+  on their own. The judge (Phase 3) is opt-in, ADVISORY, and `uncalibrated` —
+  never blend a judge verdict into the deterministic tally.
 - **Journal is SSOT; the report is a derived view.** The append-only
   `.orchestrator/metrics/eval.jsonl` is authoritative. The HTML report is
   rebuildable from any stored record and is never authoritative over the journal.
@@ -148,10 +151,13 @@ node scripts/eval-session.mjs [--session <id>] --json \
   On exit `1` (e.g. "no completed session found"), surface the message and stop —
   do not retry with fabricated inputs.
 
-Parse the emitted JSON record. It carries `dimensions[]` (5 deterministic
-entries), `kpis{}`, `provenance.rubric_sha256` (non-null once `rubric-v1.md`
-exists), `model`, `harness`, and `run_id`. Unless `--no-write` was passed, the
-record is already appended to `.orchestrator/metrics/eval.jsonl` by the CLI.
+Parse the emitted JSON record. It carries `dimensions[]` (6 deterministic
+entries — the two reported-only ones, `guard-friction` and `efficiency-kpis`,
+are always `not-applicable`), `kpis{}`, `provenance.rubric_sha256` (the sha256
+of `rubric-v2.md`; `null` means the rubric file was not found and the append
+will fail validation), `model`, `harness`, and `run_id`. Unless `--no-write` was
+passed, the record is already appended to `.orchestrator/metrics/eval.jsonl` by
+the CLI.
 
 **Contamination check:** if the human-render/summary reports a peer-overlapped
 window, note it — `verification-evidence` and `gate-health` will read
@@ -187,9 +193,13 @@ const merged = mergeJudgeDimensions(record, dimensions);
 appendEvalRecord(merged, { path: '.orchestrator/metrics/eval.jsonl' });
 ```
 
-- Every judge dimension arrives `advisory: true` + `calibration_status:
-  "uncalibrated"` (the schema firewall rejects any other shape). Keep them
-  visibly separated from the deterministic five in the summary.
+- The judge dimension arrives `advisory: true` + `calibration_status:
+  "uncalibrated"` (the schema firewall rejects any other shape). Keep it
+  visibly separated from the deterministic six in the summary.
+- `runEvalJudge` pre-computes a `facts` block (`computeRecordFacts`) from the
+  deterministic evidence strings and hands it to the judge OUTSIDE the
+  untrusted-data fence — anything countable is counted in code, never inferred
+  by the model. Do not reimplement that here.
 - If `runEvalJudge` returns a non-ok `status` (e.g. dispatch failed), keep the
   deterministic record as-is and note the judge was unavailable — the
   deterministic evaluation is complete without it.
@@ -226,20 +236,20 @@ const res = writeEvalReport(record, { generatedAt: new Date().toISOString() });
 Emit a compact, honest per-dimension summary. Status lines only — no global score.
 
 ```
-## /eval — <session_id>  (self-evaluation, aiat-llm-eval/1.0 · rubric-v1 · n=1, no CI)
+## /eval — <session_id>  (self-evaluation, aiat-llm-eval/1.0 · rubric-v2 · n=1, no CI)
 
 Deterministic:
   verification-evidence   PASS   <one-line evidence>
   plan-fidelity           PASS   completion_rate=1.0 (score)
   gate-health             PASS   <one-line evidence>
-  process-safety          PASS   <one-line evidence + guard-emission disclosure>
+  process-safety          PASS   <one-line evidence + both guard disclosures>
+  guard-friction          N/A    (reported: blocked=… warned=… loop.warning=… <attribution>)
   efficiency-kpis         N/A    (reported: duration=…s waves=… agents=… tok_in=… tok_out=… carryover=…)
 
 Judge (advisory, uncalibrated)  [only when eval.judge != off]:
-  instruction-adherence   <verdict>   advisory
-  report-quality          <verdict>   advisory
+  instruction-adherence   <verdict>   advisory   (rule <n> applied)
 
-cannot-determine: <k> of 5 deterministic dimensions (<reasons>)
+cannot-determine: <k> of 6 deterministic dimensions (<reasons>)
 Report:  .orchestrator/eval/reports/<run_id>.html
 Journal: .orchestrator/metrics/eval.jsonl  (appended: <yes|--no-write>)
 Re-verify: node scripts/eval-session.mjs --verify <run_id>
@@ -266,6 +276,11 @@ node scripts/eval-session.mjs --verify <run-id> --json
   changed since the record was written — investigate, do not overwrite.
 - `--verify` reproduces the stored model + timestamp verbatim (no env override),
   so a MATCH is a real reproducibility proof of the scoring, not of model output.
+- **A cross-version DRIFT is not a defect.** A stored `rubric-v1` record
+  re-scored by today's rubric-v2 engine necessarily differs on `process-safety`
+  and reports `present-in-fresh-only: guard-friction`. Read the record's
+  `rubric_version` before treating a diff as a regression (#1400 replaces that
+  report with an explicit version verdict).
 
 ---
 
@@ -282,9 +297,9 @@ platform. Only the judge phase needs harness-specific tooling.
   `skills/_shared/platform-tools.md` § Agent Dispatch Pattern.
 - **`harness.platform`** on the record is resolved from `$SO_PLATFORM`
   (falls back to `claude-code`) inside the engine — no skill action needed.
-- The deterministic five dimensions + the HTML report + `--verify` are fully
-  available on all platforms; the judge overlay is a Claude-Code-only enrichment
-  in v1.
+- The deterministic six dimensions + the HTML report + `--verify` are fully
+  available on all platforms; the judge overlay is a Claude-Code-only
+  enrichment.
 
 ---
 

package/skills/eval/rubric-v1.md

@@ -5,6 +5,7 @@
 - **Conforms to standard:** `aiat-llm-eval/1.0` — see [`docs/eval/aiat-llm-eval-v1.md`](../../docs/eval/aiat-llm-eval-v1.md)
 - **Reference engine:** [`scripts/lib/eval/engine.mjs`](../../scripts/lib/eval/engine.mjs) (the executable scorers this document mirrors verbatim)
 - **Hash binding:** the sha256 of THIS FILE is written to every record's `provenance.rubric_sha256`.
+- **Superseded for NEW records by [`rubric-v2.md`](./rubric-v2.md) (2026-09-19, issue #1037).** This file stays frozen and authoritative for every record already carrying `rubric_version: "rubric-v1"` — its formulas are the ones those verdicts were produced under and must not be edited. v2 changed exactly two things: `process-safety` no longer fails on `destructive_guard.blocked`, and the guard counts moved to a new reported-only `guard-friction` dimension. The reasoning and the measurement live in rubric-v2 § Änderungen gegenüber v1.
 
 > **Pre-Registration (leading principle, standard §1.1).** The checks below are
 > **fixed BEFORE the first scored run executes against this rubric**. This document