session-orchestrator 5.1.0 → 5.2.0

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/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/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.

package/skills/dispatcher/SKILL.md

@@ -10,6 +10,8 @@ description: >
   portfolio. user: "/dispatcher" assistant: "Ranked 18 free repos — top recommendation: Pencil-Designs
   (score 4.50, 90d stale). Confirm via the picker, I'll claim its lease atomically, then route you to
   /session deep."</example>
+user-invocable: true
+argument-hint: "[--dry-run] [--repo <name>]"
 model: sonnet
 ---
 
@@ -17,6 +19,25 @@ model: sonnet
 
 > Cross-repo autopilot front-door — enumerate → rank → owner-AUQ → atomic claim → route. Read-only until the operator confirms; the only mutating step is the atomic `session.lock` claim, and it happens BEFORE any launch.
 
+## Invocation
+
+Invoked as `/dispatcher [--dry-run] [--repo <name>]` with arguments: **$ARGUMENTS**.
+
+Parse `$ARGUMENTS` before doing anything else. The recognized flags are exactly those of the CLI table below and are passed straight through to `scripts/lib/dispatcher/cli.mjs`:
+
+- `--dry-run` — run the non-mutating rank only; print the recommendation and the free-candidate table; do NOT claim any lease (skip Phase 3).
+- `--repo <name>` — limit the human-readable output to a single `repoName` (informational; does not change ranking).
+- `--start-dir <path>` — override the scan root (defaults to the confinement root).
+- `--json` — emit the full `{ candidates, free, ranked, warnings, recommended }` object to stdout.
+
+If `$ARGUMENTS` contains an unrecognized flag (starts with `--` but is not one of the above), inform the user:
+
+```
+Unknown flag '<flag>'. Recognized flags: --dry-run, --repo <name>, --start-dir <path>, --json.
+```
+
+Then continue with the remaining valid arguments.
+
 ## Soul
 
 The dispatcher answers one question: *"of all my repos, which is the most worthwhile to work on right now, and is it free?"* It scans the confinement-root children, resolves each repo's free/busy status from its `session.lock` v2 lease (same lease semantics as the vault-status board), ranks only the FREE ones by `priority × staleness × readiness`, and recommends the single best one. You confirm via a picker, it claims the lease atomically (winning the race or excluding-and-re-ranking on a loss), then routes you to the entry command for that repo. Busy repos are listed-as-such, never selected.
@@ -119,13 +140,23 @@ Do NOT reinvent the claim — always go through `claimRepo`/`acquire`. The `ok:f
 
 ## Phase 4: Route
 
-With the lease held, the **coordinator** invokes the chosen entry slash-command for repo R:
-
-- `/session housekeeping` or `/session deep` — execution modes.
-- `/plan` — read-only planning precursor (produces a wave plan; does not execute).
-- `/discovery` — read-only investigation precursor (maps scope; does not execute).
-
-`/plan` and `/discovery` are **read-only precursors**, NOT execution modes — the menu may route to them, but they only produce artifacts for a later execution session. The full mode taxonomy lives in the mode-selector surface (P2 of this epic); the dispatcher only routes to the entry command the operator picked.
+With the lease held, routing splits on whether the chosen entry is model-invocable:
+
+- **`/session housekeeping` or `/session deep`** (execution modes) and **`/plan`** (read-only
+  planning precursor) are NOT something the coordinator can invoke itself. `commands/session.md`
+  documents `session` and `plan` as **reserved terminal-only built-in names** — under
+  non-interactive (`claude -p`) invocation the bare form answers `"isn't available in this
+  environment"` — and `skills/plan/SKILL.md` additionally carries
+  `disable-model-invocation: true`, which blocks the `Skill` tool from invoking it regardless of
+  interactivity. The coordinator therefore **hands the operator the exact command to type**, one
+  line per option — `/session-orchestrator:session <mode>` or `/session-orchestrator:plan
+  [new|feature|retro]` — rather than attempting to invoke either itself.
+- **`/discovery`** — read-only investigation precursor (maps scope; does not execute).
+  `skills/discovery/SKILL.md` carries no `disable-model-invocation` flag, so the coordinator MAY
+  invoke it directly via the `Skill` tool when the operator picks this option — no hand-off line
+  needed.
+
+`/plan` and `/discovery` remain **read-only precursors**, NOT execution modes — the menu may route to them, but they only produce artifacts for a later execution session. The full mode taxonomy lives in the mode-selector surface (P2 of this epic); the dispatcher only routes to the entry command the operator picked.
 
 ## Phase 5: Edge cases
 

package/skills/eli5/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: eli5
 description: Explain a topic like I'm a 5 year old — restate my last output, or a named topic, in plain words without dropping a single fact. Use when the user types /eli5 [topic], or says an answer was too technical, too long, or unclear about what he now has to do.
+user-invocable: true
+argument-hint: "[topic]"
 model: inherit
 tools: Read, Grep, Glob, Bash
 ---
@@ -9,6 +11,15 @@ tools: Read, Grep, Glob, Bash
 
 Say it again in plain words. Same facts, in the order he needs them.
 
+## Invocation
+
+Invoked as `/eli5 [topic]` with arguments: **$ARGUMENTS**.
+
+The argument is optional and is a topic, in prose. If `$ARGUMENTS` is empty, the target is my own last substantial output in this conversation; if there is none yet, say so rather than picking a topic for him.
+
+- `/eli5` — restate what I just said.
+- `/eli5 warum ist der Regel-Korpus voll?` — explain that, grounded in what this session measured.
+
 ## The frame
 
 **Write for someone who knows this project but has not seen what you just saw.**

package/skills/eval/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: eval
 user-invocable: true
+argument-hint: "[--session <id>] [--no-write] [--verify <run-id>]"
 tags: [eval, measurement, quality, meta, standard]
 model: sonnet
 model-preference: sonnet
@@ -31,6 +32,19 @@ renders an HTML report. An opt-in LLM judge overlays two advisory dimensions.
 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).
 
+## Invocation
+
+Invoked as `/eval [--session <id>] [--no-write] [--verify <run-id>]` with arguments: **$ARGUMENTS** (parsed in Phase 1.2).
+
+- `/eval` — evaluate the last completed session (resolution cascade), append the record, render the report.
+- `/eval --session <id>` — evaluate a specific `session_id`.
+- `/eval --no-write` — evaluate + report without appending to the journal (dry-run).
+- `/eval --verify <run-id>` — re-score a stored run and diff for drift (the reproducibility proof; exit 1 on drift).
+
+**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).
+
 ## Posture Contract (load-bearing — read before executing)
 
 - **No global score, by construction.** The record has no overall/total/mean

package/skills/evolve/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: evolve
-user-invocable: false
+user-invocable: true
+argument-hint: "[analyze|review|list|dialectic [--apply]]"
 tags: [learning, intelligence, meta]
 model: sonnet
 model-preference: sonnet
@@ -24,6 +25,12 @@ description: >
 
 # Evolve Skill
 
+## Invocation
+
+Invoked as `/evolve [analyze|review|list|dialectic [--apply]]` with mode: **$ARGUMENTS** (if empty, default to `analyze` — parsed in Step 1.3).
+
+Analyze session history for patterns, review existing learnings, list active intelligence, or derive USER.md/AGENT.md peer-card updates via the dialectic mode. Every learning must be confirmed by the user before persisting. Evidence before assertions.
+
 ## Phase 0: Bootstrap Gate
 
 Read `skills/_shared/bootstrap-gate.md` and execute the gate check. If the gate is CLOSED, invoke `skills/bootstrap/SKILL.md` and wait for completion before proceeding. If the gate is OPEN, continue to Phase 1.

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

@@ -67,9 +67,11 @@ const result = await runDialecticDeriver({
 ```
 
 ### Step 6.4: Diff Output & Apply Gate
-- If dry-run (default): present diff inline; write to `.orchestrator/dialectic-pending.md` (atomic tmp+rename); EXIT. Suggestion: "Re-run with `/evolve --dialectic --apply` to apply." <!-- path-check: example -->
+- If dry-run (default): present diff inline; write to `.orchestrator/dialectic-pending.md` via `writeDialecticPending({ repoRoot, diff })` from `scripts/lib/auto-dialectic.mjs` (path constant `DIALECTIC_PENDING_PATH`; atomic tmp+rename). `runDialecticDeriver()` does NOT write this file itself — the dry-run branch returns the diff and the caller persists it. The body parameter is named `diff`, not `body`: a non-string or empty value throws `TypeError`, as does a missing `repoRoot`. EXIT. Suggestion: "Re-run with `/evolve --dialectic --apply` to apply." <!-- path-check: example -->
 - If `--apply`: call **`mergeDerivedBody(existingBody, result.diff[target])`** from `scripts/lib/peer-cards/merger.mjs` for each card target, then `writePeerCard(repoRoot, 'user', mergedUserCard)` and `writePeerCard(repoRoot, 'agent', mergedAgentCard)` from `scripts/lib/peer-cards/writer.mjs`. Update the `updated:` frontmatter.
 
+  **`writePeerCard` shape (#1303).** `writePeerCard(repoRoot, target, card)` takes `card = { frontmatter, body }`. `frontmatter.id` (kebab-case slug, 2..128 chars) is **required and never auto-filled**; `type: 'peer-card'`, `target`, `updated` (defaults to `new Date().toISOString()`) and `created` (defaults to `updated`) are filled by the writer. ISO timestamps may carry optional milliseconds (`scripts/lib/peer-cards/schema.mjs` `ISO_DATETIME_REGEX`). A missing `id` returns `{ ok: false, errors: [...] }` and leaves the target file untouched — it does **not** throw; branch on `result.ok`.
+
   **Why `mergeDerivedBody` and not `mergePeerCard` directly (#1310):** the deriver emits a FULL BODY STRING per target (`agents/dialectic-deriver.md` § Output format); `mergePeerCard` consumes a SECTION MAP keyed by sentinel name. `mergeDerivedBody` is the adapter between the two — it splits the proposed body at `## ` headings and maps each heading to a sentinel section. `mergePeerCard` stays available as the section-map primitive. Handling per heading class, all of it in `mergeDerivedBody`'s return value:
 
   | Heading in the proposed body | Section name | Merge effect | Surfaced as |
@@ -77,6 +79,7 @@ const result = await runDialecticDeriver({
   | Matches an existing managed section's own `## ` heading | that section's EXISTING name (read from the card, NOT re-slugified) | REPLACE | `mapping[].origin === 'existing'` |
   | No existing section | slugified heading (`[a-z0-9-]+`, collisions suffixed `-2`) | APPEND | `mapping[].origin === 'new'` |
   | Existing managed section the proposal omits | — | KEPT (no auto-delete, per `mergePeerCard` semantics) | — |
+  | Section name outside `[A-Za-z0-9_-]+` | — | `mergePeerCard` **throws** `invalid section name` | fix the name before merging |
   | Text before the first `## ` heading | — | NOT applied | `preamble` + a `{ type: 'unmapped-preamble' }` entry in `conflicts[]` |
 
   Existing names are read back out of the card rather than re-derived because the live names are not a pure function of their headings — measured 2026-09-11 in `.orchestrator/peers/AGENT.md`: `## Guard and protocol-migration discipline` → `guard-and-protocol-migration`. Re-slugifying would APPEND a duplicate section instead of replacing one.
@@ -113,7 +116,8 @@ await recordDialecticRun({
 
 ### Step 6.5: Error Handling
 - `status: 'unknown-model'` → fail with clear error (already thrown by validateModel)
-- `status: 'budget-exceeded'` → emit `{status:'budget-exceeded', used:N, budget:M}`, do NOT truncate
+- `status: 'budget-exceeded'` → emit `{status:'budget-exceeded', used:N, budget:M}`, do NOT truncate.
+  Measured in a consumer repo (S119, 2026-09-10): 12 learnings + 127 sessions estimated at 11 158 input tokens against the 8000 default. Raise with `--budget-tokens 16000` or `dialectic.budget-tokens` in Session Config rather than trimming inputs.
 - `status: 'would-empty-card'` → warn + require `--allow-emptying` flag
 - `status: 'empty-input'` → exit clean with message "dialectic: skipped (no input)"
 - subagent crash → log ⚠, exit cleanly (do NOT write to `.orchestrator/dialectic-pending.md`) <!-- path-check: example -->

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

@@ -1,13 +1,21 @@
 ---
+name: go
 description: Approve session plan and begin wave execution
+user-invocable: true
 disable-model-invocation: true
 argument-hint: "[optional instructions]"
+model: inherit
 ---
-
 # Execute Session Plan
 
 The user has approved the session plan. Begin execution immediately.
 
+## Invocation
+
+Invoked as `/go [optional instructions]` with arguments: **$ARGUMENTS**. The user has approved the session plan; begin execution immediately.
+
+`$ARGUMENTS` is optional priority guidance, forwarded verbatim to `skills/wave-executor/SKILL.md` for agent prompts (see "Standard Execution" below). It never re-opens the plan: do NOT re-plan, do NOT re-analyze — execute the agreed plan NOW with maximum efficiency.
+
 ## Express Path Detection
 
 Before invoking the wave-executor, check the conversation context for the Express Path activation banner — printed by `node scripts/express-path.mjs` in session-start Phase 8.5, and carried through session-plan's Short-Circuit (#1146):

package/skills/grill/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: grill
 description: Use when the user wants a plan, design, or PRD stress-tested before any build — relentlessly interrogates one decision at a time, grounds every question in the codebase, hunts contradictions against the domain language and the code, and challenges the load-bearing assumptions. Triggered by "grill me", "stress-test this plan", "poke holes in my design". Composable — run standalone or as an adversarial pass before /plan feature.
+user-invocable: true
+argument-hint: "[file-path-or-topic]"
 model: inherit
 color: red
 tools: Read, Grep, Glob, Bash, Write
@@ -10,6 +12,23 @@ tools: Read, Grep, Glob, Bash, Write
 
 > Adversarial pressure-test for a plan, design, or PRD the user already believes in. The complement to `/brainstorm`: brainstorm *narrows* an ambiguous design space cooperatively; grill *attacks* a settled-feeling plan to find what's wrong before it's built. Optionally writes `docs/specs/YYYY-MM-DD-<slug>-grill.md`. No HARD-GATE — composable by design.
 
+## Invocation
+
+Invoked as `/grill [file-path-or-topic]` with arguments: **$ARGUMENTS** (resolved in Phase 0).
+
+The argument is optional and is either a file path to grill (a PRD, spec, `STATE.md`) or a topic/slug. If absent, grill the plan already present in the current conversation; if there is none, ask the user — via AUQ — to state it first.
+
+- `/grill` — grills the plan in the current conversation context.
+- `/grill docs/prd/2026-06-09-export.md` — grills a specific PRD file. <!-- path-check: example -->
+- `/grill "partial order cancellation"` — grills the named idea, slug pre-set.
+
+| Situation | Use |
+|-----------|-----|
+| A settled-feeling plan needs stress-testing before build | `/grill` |
+| The design is still ambiguous and needs narrowing | `/brainstorm` |
+| Scope is clear, need a formal PRD + issues | `/plan feature` |
+| Adversarial pass before formalizing | `/grill` → `/plan feature` |
+
 ## Soul Reference
 
 Read `soul.md` in this skill directory before anything else. It defines WHO you are — the Interrogator, a staff engineer playing devil's advocate. The Six Tactics in soul.md (glossary conflict, sharpen fuzzy language, code contradiction, edge-case scenario, assumption audit, pre-mortem) are the substance of every grill; internalize them before Phase 0.

package/{commands/harness-audit.md → skills/harness-audit/SKILL.md}

@@ -1,10 +1,15 @@
 ---
+name: harness-audit
 description: Run the harness audit and report the rubric score for this repository
-argument-hint: ""
+user-invocable: true
+model: inherit
 ---
-
 # Harness Audit
 
+## Invocation
+
+`/harness-audit` takes no arguments — `$ARGUMENTS` is always ignored; anything passed is discarded without a warning. Run the audit exactly as described below and report the rubric score.
+
 The user wants to audit this repository against the session-orchestrator harness rubric. There are no arguments.
 
 Run the audit script and surface the results: