session-orchestrator 5.1.0 → 5.3.0

package/skills/_shared/state-ownership.md

@@ -18,6 +18,7 @@ total-waves: <N>
 # Optional fields (schema-version 1, additive for backward-compat):
 updated: <ISO 8601 UTC>      # last write timestamp, touched by any writer
 session: <session-label>     # attribution/history label; normally semantic since #573, legacy UUID-v4 remains readable; never a lock/registry ownership key
+session-id: <raw id>         # the RAW/native harness session id from session.lock (#1368); omit when absent; never a lock/registry ownership key
 session-start-ref: <sha>     # git ref at session start
 ---
 ```
@@ -25,6 +26,8 @@ session-start-ref: <sha>     # git ref at session start
 ### Required vs. optional fields
 
 - `schema-version`, `session-type`, `branch`, `issues`, `started_at`, `status`, `current-wave`, `total-waves` — **required** in every session-owned STATE.md.
+- `session-id` — **optional**, additive under `schema-version: 1` (#1368). The RAW/native harness session id, taken from `.orchestrator/session.lock` via `resolveSessionIds()` (`scripts/lib/state-md.mjs`). Writers OMIT the key when the lock yields none; readers MUST tolerate its absence. It exists so `/close`'s #429 pre-check can join STATE.md to sessions.jsonl on a NATIVE identity (`findRecordedSession`'s UUID fast path) instead of falling through to the semantic label. Like `session`, it grants no lock or registry ownership.
+- `started_at` is SOURCED from the same lock (`resolveSessionStartedAt()`), never from the writer's clock — see `skills/wave-executor/references/wave-executor-state-init.md` § Pre-Wave 1b for the template and the 48-minute drift that motivated it (#1368). On the READ side `started_at` is a CORROBORATING signal, never an identity key: `findRecordedSession()` (`scripts/lib/session-close-backfill.mjs`) joins STATE.md to `sessions.jsonl` on the native `session-id` FIRST and never consults `started_at` on that path — only the legacy-LABEL path compares the two timestamps, and it tolerates up to `STARTED_AT_DRIFT_TOLERANCE_MS` = **6 h** of drift (`session-close-backfill.mjs:559`, the single definition) before vetoing a label match: wider than any plausible write-lag (the 48 minutes above), narrower than the day the label's own date component already distinguishes.
 - `updated`, `session`, `session-start-ref` — **optional**. Added by #184. STATE.md files without these fields remain valid and should be treated as `updated: null` / `session: null`. Writers SHOULD populate these fields but readers MUST tolerate their absence. `session` is an attribution/history label, normally `<branch>-<YYYY-MM-DD>-<mode>-<n>` since #573 (Epic #568 Parallel-Aware Sessions P2.2); pre-#573 files may contain a UUID-v4 — both formats are read via `parseSessionId()` from `scripts/lib/session-id.mjs` per PRD §3 P2 row 3 (backward-compat). Neither form grants lock or registry ownership.
 
 The `session-type: none` + `status: idle` combination is used only for bootstrap-scaffolded placeholder files (no active session).

package/skills/autopilot/SKILL.md

@@ -9,12 +9,47 @@ description: >
   record per loop run. Phase C scaffold (issue #277); implementation lives in
   scripts/lib/autopilot.mjs (Phase C-1 follow-up).
 user-invocable: true
+argument-hint: "[--headless] [--verbose] [--max-sessions=N] [--max-hours=H] [--confidence-threshold=0.X] [--dry-run]"
 tags: [phase-c, autopilot, autonomous, loop]
 model: sonnet
 ---
 
 # Autopilot Skill
 
+## Invocation
+
+The user invokes `/autopilot` with arguments: **$ARGUMENTS**. This is autonomous
+session-orchestration mode — a top-level invocation only, never from inside a running
+session.
+
+Parse `$ARGUMENTS` before anything else. Unrecognized flags are ignored; out-of-range
+values silently clamp to bounds. Use `parseFlags` from `scripts/lib/autopilot.mjs` for
+canonical parsing — never re-implement clamping inline. The loop flags
+(`--max-sessions`, `--max-hours`, `--confidence-threshold`, `--dry-run`) and their
+defaults/bounds are tabled once in § Command Surface below. Two further flags belong to
+the invocation surface only:
+
+| Flag | Default | Meaning |
+|------|---------|---------|
+| `--headless` | `false` | Run via the standalone driver `scripts/autopilot.mjs`, which spawns `claude -p '/session <mode>'` as a child process per iteration. Required for unattended walk-away mode. Without it, `/autopilot` runs the in-process driver inside the current chat session (see § Production Wiring). |
+| `--verbose` | `false` | Verbose driver output. |
+
+### Headless (`claude -p`)
+
+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.
+
+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
+Claude. The runtime writes ONE record to `.orchestrator/metrics/autopilot.jsonl` per
+invocation via atomic tmp+rename; no other code path appends to that file.
+
 ## Phase 0.5: Parallel-Aware Preamble
 
 > Skip silently when `persistence: false` in Session Config.
@@ -177,7 +212,8 @@ Phase C-1 ships `runLoop` as a pure controller. Phase C-1.c ships `buildLiveSign
 the canonical signals-assembly helper. This section documents the **in-process driver
 protocol** (Option B from #301): how Claude — running as the coordinator in a chat
 session — drives `runLoop` between manual `/session` invocations. The headless wrapper
-(Option A, `scripts/autopilot.mjs` CLI spawning `claude -p`) is reserved for Phase C-5.
+(Option A, `scripts/autopilot.mjs` CLI spawning `claude -p`) is selected with `--headless`
+— see § Invocation.
 
 ### Dependency-Injection Contract
 
@@ -187,8 +223,8 @@ session — drives `runLoop` between manual `/session` invocations. The headless
 |---|---|---|
 | `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 |
-| `resourceEvaluator` | `() => {verdict}` | wraps `evaluate(await probe(), thresholds)` from `resource-probe.mjs` |
-| `peerCounter` | `() => number` | reads `claude_processes_count` from a fresh `probe()` snapshot |
+| `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 |
 
 `abortSignal` is optional (Ctrl+C / Esc → `user-abort` kill-switch).
 
@@ -199,6 +235,7 @@ import { runLoop, parseFlags } from '$PLUGIN_ROOT/scripts/lib/autopilot.mjs';
 import { buildLiveSignals } from '$PLUGIN_ROOT/scripts/lib/build-live-signals.mjs';
 import { selectMode } from '$PLUGIN_ROOT/scripts/lib/mode-selector.mjs';
 import { probe, evaluate } from '$PLUGIN_ROOT/scripts/lib/resource-probe.mjs';
+import { detectPeers } from '$PLUGIN_ROOT/scripts/lib/session-registry.mjs';
 
 const flags = parseFlags(process.argv.slice(2));
 
@@ -214,14 +251,27 @@ const modeSelector = async () => {
   return selectMode(signals);
 };
 
+let cachedProbeSnapshot = null;   // written by peerCounter, read by resourceEvaluator
+
 const resourceEvaluator = () => {
-  const snapshot = probeSync();   // or cached snapshot if probe is async
-  return evaluate(snapshot, thresholds);
+  // Synchronous by contract: never calls probe() itself (it is async) — reads
+  // the snapshot peerCounter refreshed on the prior iteration.
+  if (cachedProbeSnapshot === null) {
+    return { verdict: 'warn', reasons: ['probe not yet available'], recommended_agents_per_wave_cap: null };
+  }
+  return evaluate(cachedProbeSnapshot, thresholds);
 };
 
-const peerCounter = () => {
-  // Synchronous-friendly count from a recent probe snapshot.
-  return latestSnapshot.claude_processes_count ?? 0;
+const peerCounter = async () => {
+  // A SESSION count, not a process count (host-resources.md HR-103) —
+  // claude_processes_count runs ~6 processes per session. `ownSessionId` is
+  // this coordinator's registry id, so detectPeers() excludes it.
+  const [peers, snapshot] = await Promise.all([
+    detectPeers({ sessionId: ownSessionId, freshnessMin: 15 }),
+    probe(),
+  ]);
+  cachedProbeSnapshot = snapshot;
+  return peers.length;
 };
 
 const sessionRunner = async ({ mode, autopilotRunId }) => {
@@ -253,8 +303,28 @@ The in-process driver has Claude (the coordinator) call `/session <mode>` betwee
 - **Pro:** zero new infra. Reuses canonical kill-switch logic. Validates `buildLiveSignals`
   against real Phase 7.5 swap before headless complexity. Each iteration carries
   inter-session memory through STATE.md / sessions.jsonl / learnings.
-- **Con:** not truly autonomous — Claude must stay in the chat. Doesn't deliver
-  walk-away UX. That's Phase C-5's job.
+- **Con:** not truly autonomous — Claude must stay in the chat. The in-process
+  driver does not deliver walk-away UX; that is the shipped headless driver
+  (`--headless`, `scripts/autopilot.mjs`, Phase C-5; see § Headless Driver Wiring).
+
+### Headless Driver Wiring (Option A — `scripts/autopilot.mjs`)
+
+The standalone headless driver invoked via `--headless` (see § Invocation) wires all
+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`).
+- `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
+  (`scripts/autopilot.mjs` `resourceEvaluator`).
+- `peerCounter` — calls `detectPeers({ sessionId: autopilotRunId, freshnessMin: 15 })` from
+  `scripts/lib/session-registry.mjs` AND refreshes the cached `probe()` snapshot in the
+  same call, returning `peers.length` (`scripts/autopilot.mjs` `makePeerCounter`).
+- `abortSignal` — an `AbortController` aborted on the process's `SIGINT` handler.
 
 ### `autopilot_run_id` Propagation
 
@@ -387,7 +457,6 @@ Single-story `/autopilot` takes no Session Config block. Multi-story
 - PRD: "Autopilot Loop" (#277; archived in the private Meta-Vault)
 - Implementation (Phase C-1 + C-1.b): `scripts/lib/autopilot.mjs` — exports `runLoop`, `parseFlags`, `writeAutopilotJsonl`, `KILL_SWITCHES`, `FLAG_BOUNDS`, `SCHEMA_VERSION`, `DEFAULT_PEER_ABORT_THRESHOLD`, `DEFAULT_JSONL_PATH`, `DEFAULT_CARRYOVER_THRESHOLD`
 - Tests (Phase C-1 + C-1.b): `tests/lib/autopilot.test.mjs`
-- Command file: `commands/autopilot.md`
 - Mode-Selector contract: `skills/mode-selector/SKILL.md`
 - Resource probe: `scripts/lib/resource-probe.mjs`
 - Session registry: `scripts/lib/session-registry.mjs`

package/skills/bootstrap/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bootstrap
 user-invocable: true
+disable-model-invocation: true
+argument-hint: "[--upgrade <tier>]"
 tags: [bootstrap, setup, scaffold, init]
 model: sonnet
 model-preference: sonnet
@@ -15,6 +17,54 @@ description: >
 
 # Bootstrap Skill
 
+## Invocation
+
+The user invokes `/bootstrap` with arguments: **$ARGUMENTS**. Direct invocation runs with
+`INVOCATION_MODE = direct` (see § Invocation Context) and is standalone: after bootstrap
+completes, report the files created and the git commit hash, and do NOT automatically
+continue into any other skill.
+
+**TL;DR — for first-time users:** Run `/bootstrap` with no flags. The skill auto-detects the right tier (fast/standard/deep) from your repo, recommends one with a one-line reason, then walks a **fixed questionnaire** — tier/stack (1–2 prompts), owner persona (5), dispatcher autonomy (1); **7–9 prompts** on a first-run full bootstrap. Bestätigen → fertig. Keine weiteren Schritte.
+
+The flags below cover special cases (re-adopting an existing repo, upgrading a tier, syncing rules). If you don't recognize the case in the description, you don't need the flag.
+
+> **Instruction file alias:** Bootstrap creates and reads `CLAUDE.md` (or `AGENTS.md` on Codex CLI). The two are transparent aliases — pick one, never both. Resolution rule: see `skills/_shared/instruction-file-resolution.md`.
+
+### Standard usage (no flags)
+
+This is the path 95 % of users want.
+
+| Invocation | Behavior |
+|------------|----------|
+| `/bootstrap` | Auto-detect tier (fast / standard / deep) from repo context. Present recommendation via `AskUserQuestion` with options to confirm or override. Tier/stack: 1–2 questions; first-run full bootstrap adds owner interview (5, `owner-interview.mjs`) + dispatcher-autonomy capture (1). Then scaffold files + commit. |
+
+What the user sees:
+
+```
+Skill: "Repo leer. Empfehle 'standard' weil <reason>. Passt das?"
+User: [Enter on "standard (Empfohlen)"]
+Skill: <writes files, commits, prints summary>
+```
+
+### Flag reference (special cases)
+
+Only use a flag if you have one of the situations described. Parsed flags decide the mode
+dispatch in § Invocation Context — `--fast` / `--standard` / `--deep` skip the tier
+confirmation question, while `--retroactive`, `--refresh-lock`, `--sync-rules` and
+`--ecosystem-health` are standalone short-circuit flows that run to completion in this
+skill without dispatching to a tier template.
+
+| Flag | When to use it |
+|------|----------------|
+| `--upgrade <tier>` | You bootstrapped `fast` earlier and now need `standard` or `deep`. Idempotent — writes only the delta. Refuses downgrade. Valid: `fast → standard`, `fast → deep`, `standard → deep`. |
+| `--retroactive` | The repo already has `CLAUDE.md` (or `AGENTS.md` on Codex CLI) + `## Session Config` but no `bootstrap.lock` (manually bootstrapped before the gate existed). Writes the lock based on file inventory; **makes no scaffolding changes**. Commit: `chore: bootstrap lock (retroactive)`. |
+| `--refresh-lock` | Your `bootstrap.lock` already has valid `version`/`tier` fields but the freshness probe flags it as stale or plugin-version-drifted — `--retroactive` is a no-op here. Acknowledges the current plugin version and resets the freshness clock (`refreshed-at` + `refreshed-plugin-version`) without touching the lock's original bootstrap provenance. No scaffolding, no auto-commit. |
+| `--sync-rules` | Pull canonical rules from the plugin's `rules/` library into `.claude/rules/`. Preserves local rules (files without the plugin source header). Standalone — does not touch `bootstrap.lock`. |
+| `--ecosystem-health` | Run the ecosystem-health wizard: detects CI provider + package manager, prompts for health endpoints, pipelines, and critical issue labels. Writes the config block + `.orchestrator/policy/ecosystem.json`. No scaffolding, no auto-commit. |
+| `--fast` / `--standard` / `--deep` | Skip the tier confirmation question (e.g., for scripted runs). Equivalent to running `/bootstrap` and selecting that option. |
+
+All flag-driven flows are idempotent — running twice with no upstream change is a no-op.
+
 ## Overview
 
 This skill runs when the Bootstrap Gate is closed (missing CLAUDE.md, Session Config, or `.orchestrator/bootstrap.lock`) or when the user invokes `/bootstrap` directly. It scaffolds the minimum structure required by all session-orchestrator skills, commits it, and writes the lock file that opens the gate for all future invocations.
@@ -26,7 +76,7 @@ This skill runs when the Bootstrap Gate is closed (missing CLAUDE.md, Session Co
 Before starting, determine how this skill was invoked:
 
 - **Transitive (gate-closed):** Invoked from another skill's Phase 0. The user's original intent (their first prompt) is available in context. After bootstrap completes, execution must return to the original skill's Phase 1.
-- **Direct (`/bootstrap`):** User invoked manually. Parse `$ARGUMENTS` for flags: `--fast`, `--standard`, `--deep`, `--upgrade <tier>`, `--retroactive`. See `commands/bootstrap.md` for flag semantics.
+- **Direct (`/bootstrap`):** User invoked manually. Parse `$ARGUMENTS` for flags: `--fast`, `--standard`, `--deep`, `--upgrade <tier>`, `--retroactive`. See § Invocation above for flag semantics.
 
 Store `INVOCATION_MODE = transitive | direct`.
 

package/skills/brainstorm/SKILL.md

@@ -3,6 +3,9 @@ name: brainstorm
 description: Use when you have a feature idea but the scope or UX is still ambiguous — runs a lightweight Socratic design dialogue (3-5 AUQ rounds) and writes a spec markdown file. Use BEFORE /plan feature when product intent needs validation; skip to /plan feature when scope is already clear. HARD-GATE prevents any code work until the design is user-approved.
 model: inherit
 color: cyan
+user-invocable: true
+disable-model-invocation: true
+argument-hint: "[topic-or-feature-slug]"
 tools: Read, Grep, Glob, Bash, Write
 ---
 
@@ -10,6 +13,19 @@ tools: Read, Grep, Glob, Bash, Write
 
 > Lightweight Socratic design dialogue for per-feature exploration. Sibling to `/plan feature`, not a replacement. Produces `docs/specs/YYYY-MM-DD-<slug>-design.md` after the user approves an approach.
 
+## Invocation
+
+The user invokes `/brainstorm` with arguments: **$ARGUMENTS**.
+
+The optional argument is a topic or feature slug used in the spec filename (lowercase, hyphens, no special characters). If absent, the skill derives a slug from the user's Phase 1 answer.
+
+Examples:
+- `/brainstorm` — no slug; skill prompts for the problem in Phase 1
+- `/brainstorm export-to-csv` — slug pre-set to `export-to-csv`
+- `/brainstorm "user notification system"` — normalize to `user-notification-system`
+
+The HARD-GATE in Phase 0 below prevents any Edit, Write (code), or Bash (implementation) call until the user approves the design in Phase 6 — the only Write permitted before approval is the spec file itself in Phase 4.
+
 ## Soul Reference
 
 Read `soul.md` in this skill directory before anything else. It defines WHO you are — a Design Facilitator who shapes vague ideas into approved designs through Socratic questioning. Every interaction in this skill should reflect that identity.

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

@@ -65,7 +65,7 @@ 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** — 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.
 

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

@@ -38,6 +38,7 @@ 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 { resolveRepoSpec } from '../../scripts/lib/vcs-repo-spec.mjs';
+import { userInvocableSkills } from '../../scripts/lib/user-invocable-skills.mjs';
 
 const FORWARD_HEADING_RE =
   /(?:^|\b)(what'?s?\s+next|backlog|open\s+issues?|offene\s+(?:issues?|themen)|todo|next\s+steps?|roadmap)(?:$|\b)/i;
@@ -412,6 +413,45 @@ function countTestFiles(vaultDir) {
   return n;
 }
 
+/**
+ * The product's slash-command count: `commands/*.md` ∪ skills carrying an
+ * explicit `user-invocable: true`, deduplicated by name — the same union
+ * `scripts/site-numbers.mjs` and
+ * `tests/commands/headless-bare-command-availability.test.mjs` use. In a
+ * consumer repo without `skills/` (or without `commands/`) the union
+ * collapses to whichever side is present, so nothing changes there.
+ *
+ * ONE implementation shared by the `command-count` surface (Check 5) and the
+ * `docs-parity` sub-check (a) `commands` actual (Check 10) — the two counters
+ * drifted independently before this extraction (#1370 fold left the
+ * docs-parity side on a raw `commands/` `readdirSync`, undercounting after 24
+ * `commands/*.md` files were folded into skills).
+ *
+ * Returns `null` when NEITHER `commands/` NOR `skills/` exists — the caller's
+ * "artifact absent" skip path. A `skills/` directory that exists but contains
+ * zero `user-invocable: true` skills is a measured `0`, not a skip — matching
+ * `scripts/site-numbers.mjs` `countCommands`, whose gate is
+ * `isDir(commands) || isDir(skills)` (#1370 follow-up: the old gate skipped on
+ * `fromSkills.length === 0`, which conflated "no skills/ dir" with "skills/
+ * dir present, nothing user-invocable yet").
+ *
+ * @param {string} vaultDir
+ * @param {string|null} [commandsDir] `--commands-dir` override
+ * @returns {number|null}
+ */
+function countSlashCommands(vaultDir, commandsDir) {
+  const dir = commandsDir || join(vaultDir, 'commands');
+  const dirExists = existsSync(dir) && statSync(dir).isDirectory();
+  const fromDir = dirExists
+    ? readdirSync(dir).filter((f) => f.endsWith('.md') && !f.startsWith('.')).map((f) => f.replace(/\.md$/, ''))
+    : [];
+  const fromSkills = userInvocableSkills(vaultDir);
+  const skillsDir = join(vaultDir, 'skills');
+  const skillsDirExists = existsSync(skillsDir) && statSync(skillsDir).isDirectory();
+  if (!dirExists && !skillsDirExists) return null;
+  return new Set([...fromDir, ...fromSkills]).size;
+}
+
 /**
  * Build the surface-count descriptor table for the given vault. `hookCounts`
  * is computed once and shared by the two hook surfaces. Each descriptor's
@@ -427,14 +467,13 @@ function buildSurfaceDescriptors(vaultDir, commandsDir) {
     {
       id: 'command-count',
       noun: 'commands',
-      actual: (() => {
-        const dir = commandsDir || join(vaultDir, 'commands');
-        if (!existsSync(dir) || !statSync(dir).isDirectory()) return null;
-        return readdirSync(dir).filter((f) => f.endsWith('.md') && !f.startsWith('.')).length;
-      })(),
+      // A slash command is a `commands/*.md` file OR a skill whose frontmatter
+      // says `user-invocable: true` — see countSlashCommands() for the shared
+      // union derivation (also used by docs-parity sub-check (a) below).
+      actual: countSlashCommands(vaultDir, commandsDir),
       // "8 commands", "8 /commands", "8 slash commands"
       claimRe: /\b(\d+)\s+(?:\/)?commands?\b/gi,
-      skipMsg: 'command-count: no commands/ directory found (use --commands-dir to override)',
+      skipMsg: 'command-count: no commands/ or skills/ directory found (use --commands-dir to override)',
     },
     {
       id: 'skill-count',
@@ -1485,11 +1524,10 @@ function main() {
         },
         {
           noun: 'commands',
-          actual: (() => {
-            const dir = commandsDir || join(vaultDir, 'commands');
-            if (!existsSync(dir) || !statSync(dir).isDirectory()) return null;
-            return readdirSync(dir).filter((f) => f.endsWith('.md') && !f.startsWith('.')).length;
-          })(),
+          // Shared with the command-count surface (Check 5) — see
+          // countSlashCommands() doc-comment for why this must be ONE
+          // implementation, not a second `commands/` readdirSync.
+          actual: countSlashCommands(vaultDir, commandsDir),
           re: /^##\s+Commands\s+\((\d+)\)/i,
         },
         {

package/{commands/close.md → skills/close/SKILL.md}

@@ -1,17 +1,23 @@
 ---
+name: close
 description: End session with verification, commits, and documentation
+user-invocable: true
 disable-model-invocation: true
+model: inherit
 ---
-
 # Close Session
 
+## Invocation
+
+The user invokes `/close` (arguments: **$ARGUMENTS** — none are interpreted; anything passed is context only) to end the current session. Run the STATE.md pre-check below, then hand off to `skills/session-end/SKILL.md`. Do NOT skip any verification step — evidence before assertions.
+
 The user wants to end the current session.
 
 **Pre-check before invoking session-end:** Determine `<state-dir>` from the current platform (`.claude/`, `.codex/`, `.cursor/`, or `.pi/`). Check if `<state-dir>/STATE.md` exists and read its `status` field. Three exit conditions:
 
 1. **STATE.md does not exist:** Read Session Config to check `persistence`. If `persistence: false`, inform the user: "Session completed (persistence is off — STATE.md was never created). Use `/session` to start a new session." If `persistence: true` (or Session Config unavailable), inform the user: "No active session found. Use `/session` to start a session first." Either way, stop.
-2. **STATE.md exists and `status: completed`:** `status: completed` alone is NOT proof that session-end's Phase 3.7 writer ever ran (#429) — the field can be set by hand, or by any path that stops short of that write. Parse STATE.md with `parseStateMd` and parse `.orchestrator/metrics/sessions.jsonl` as JSONL. Import `findRecordedSession` from the plugin's `scripts/lib/session-close-backfill.mjs` and call it with the parsed records and `{ sessionId: frontmatter['session-id'], semanticSessionId: frontmatter.session, startedAt: frontmatter.started_at }`. This is the shared backfill identity reader: native UUIDs take precedence, conflicting native IDs never match through a label, and legacy semantic records remain readable. Do not substitute a text grep or compare the semantic label only against `session_id`. A missing ledger means no record; an unreadable or malformed ledger is inconclusive — report the read/parse failure and stop before repeating close side effects.
-   - **A matching completed record exists (including a legacy authoritative record without a `status` field):** Inform the user: "Previous session was already finalized by session-end. Start a new session with `/session`, or inspect `<state-dir>/STATE.md` to review the prior close. (Note: if this is unexpected after an Express Path session, `commands/go.md` should have auto-invoked /close — check that STATE.md `## Deviations` contains an `Express path:` entry.)" and stop.
+2. **STATE.md exists and `status: completed`:** `status: completed` alone is NOT proof that session-end's Phase 3.7 writer ever ran (#429) — the field can be set by hand, or by any path that stops short of that write. Parse STATE.md with `parseStateMd` and parse `.orchestrator/metrics/sessions.jsonl` as JSONL. Import `findRecordedSession` from the plugin's `scripts/lib/session-close-backfill.mjs` and call it with the parsed records and `{ sessionId: frontmatter['session-id'] ?? readLock({ repoRoot })?.session_id ?? null, semanticSessionId: frontmatter.session, startedAt: frontmatter.started_at }` (`readLock` from `scripts/lib/session-lock.mjs`). The lock fallback is sound here and ONLY here: `/close` runs inside the very session whose STATE.md it is reading, so the live lock names that same session — it is never a peer's id. STATE.md files written before #1368 carry no `session-id` key at all, and without the fallback every one of them misses the native fast path. This is the shared backfill identity reader: native UUIDs take precedence, conflicting native IDs never match through a label, and legacy semantic records remain readable. Do not substitute a text grep or compare the semantic label only against `session_id`. A missing ledger means no record; an unreadable or malformed ledger is inconclusive — report the read/parse failure and stop before repeating close side effects.
+   - **A matching completed record exists (including a legacy authoritative record without a `status` field):** Inform the user: "Previous session was already finalized by session-end. Start a new session with `/session`, or inspect `<state-dir>/STATE.md` to review the prior close. (Note: if this is unexpected after an Express Path session, `skills/go/SKILL.md` should have auto-invoked /close — check that STATE.md `## Deviations` contains an `Express path:` entry.)" and stop.
    - **No matching completed record exists:** Warn the user: "STATE.md completed ohne passenden Abschluss im Ledger — session-end wird zur Vervollständigung ausgeführt (#429)." An abandoned backfill stub does not prove finalization. Do NOT stop — proceed to invoke the session-end skill exactly as in exit condition 3, so the missing completion gets written this time. (The SessionEnd hook's `backfillCompletedFromStateMd` independently self-heals this same gap on a later session's teardown; this Pre-Check branch covers the case where /close is re-run before that hook has had a chance to fire.)
 3. **STATE.md exists and `status: active` or `status: paused`:** Proceed to invoke the session-end skill.
 

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

@@ -6,6 +6,8 @@ description: >
   INVESTIGATION FIRST. Produces a `.orchestrator/debug/` artifact the fixer agent must reference.
 model: inherit
 color: red
+user-invocable: true
+argument-hint: "[bug-description-or-issue-ref]"
 tools: Read, Grep, Glob, Bash, Write
 ---
 
@@ -13,6 +15,14 @@ tools: Read, Grep, Glob, Bash, Write
 
 > 4-phase root-cause investigation. Iron Law: no fix without root cause.
 
+## Invocation
+
+The user invokes `/debug` with arguments: **$ARGUMENTS**.
+
+The optional argument is a short bug description or issue reference (e.g. `"test timeout in CI"` or `#408`). If absent, inspect recent errors and `git log` to surface the most likely candidate, then confirm it with the user before starting Phase 1.
+
+The four phases (Root Cause → Pattern → Impact → Solution) run in order, and the Phase-1 artifact at `.orchestrator/debug/<session-id>-<sequence>.md` is written before any fix code exists — it is a prerequisite for Phase 4, not optional documentation.
+
 ## When to use
 
 - Any test failure (unit, integration, E2E)

package/skills/discovery/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: discovery
-user-invocable: false
+user-invocable: true
+argument-hint: "[all|code|infra|ui|arch|session|audit|vault|feature] [--since <git-ref>] [--full]"
 tags: [quality, discovery, probes, issues]
 model: sonnet
 model-preference: sonnet
@@ -15,6 +16,28 @@ description: >
 
 # Discovery Skill
 
+## Invocation
+
+The user invokes `/discovery` with scope: **$ARGUMENTS** (if empty, default to `all`).
+
+Parse `$ARGUMENTS` before doing anything else. Extract the following flags and tokens in any order:
+
+- `--since <git-ref>` — restrict discovery to files changed since the given git ref (e.g. `HEAD~5`, `main`, a commit hash). Sets `since_ref = <git-ref>`, which is passed into Phase 3 plumbing.
+- `--full` — explicit full-repo scan. Sets `full_scan = true`.
+- Any remaining tokens are treated as scope specifiers (see the scope enum in § Invocation Modes).
+
+**Conflict check:** If BOTH `--since` and `--full` are present, stop immediately and report:
+
+```
+Error: Cannot use --since with --full. Provide one, not both.
+```
+
+Do NOT proceed with discovery when this conflict is present.
+
+**Argument validation:** Valid scopes: `all`, `code`, `infra`, `ui`, `arch`, `session`, `audit`, `vault`, `feature` (comma-separated for multiple). If any scope is invalid, inform the user: "Invalid scope '[token]'. Valid scopes: all, code, infra, ui, arch, session, audit, vault, feature." and default that token to `all`.
+
+Scan the codebase for quality issues, technical debt, and improvement opportunities within the requested scope. Do NOT skip the interactive triage phase — every finding must be confirmed by the user before issue creation. Evidence before assertions.
+
 ## Invocation Modes
 
 Two modes of operation:

package/skills/discovery/probes-session.md

@@ -506,11 +506,11 @@ Violations:
   - tools (no-json-array): tools must be a comma-separated string, not a JSON array
   - description (no-block-scalar): description must be inline, not a block scalar
   - color (enum): color must be one of "blue"|"cyan"|"green"|"yellow"|"magenta"|"red"
-Recommendation: Run /bootstrap --retroactive to auto-surface violations, or manually fix per CLAUDE.md Agent Authoring Rules.
+Recommendation: Run node scripts/validate-plugin.mjs to surface every violation, or manually fix per CLAUDE.md Agent Authoring Rules.
 ```
 
 **Default Severity:** High — broken agents fail at runtime silently.
 
-**Remediation:** Run `/bootstrap --retroactive` (validator auto-surfaces violations) or manually fix per CLAUDE.md Agent Authoring Rules.
+**Remediation:** Run `node scripts/validate-plugin.mjs` (the agent-frontmatter validator lists every violation; `/bootstrap --retroactive` only writes a missing lock, it does not validate) or manually fix per CLAUDE.md Agent Authoring Rules.
 
 **Dependencies:** Requires `${PLUGIN_ROOT}/scripts/lib/agent-frontmatter.mjs` (issue #189). Degrades gracefully when the helper is absent — skip with a note, do not fabricate findings.