session-orchestrator 5.1.0 → 5.3.0

package/skills/gitlab-ops/SKILL.md

@@ -178,7 +178,8 @@ glab issue list -R <OWNER>/<REPO> --closed --per-page 10                   # Rec
 glab issue view -R <OWNER>/<REPO> <IID>                                    # View issue details
 glab issue view -R <OWNER>/<REPO> <IID> --comments                         # With comments
 glab issue create -R <OWNER>/<REPO> --title "title" --label "priority::high,status:ready"
-glab issue update -R <OWNER>/<REPO> <IID> --label "status:in-progress"     # WARNING: --label REPLACES the full set — see caveat below
+glab issue update -R <OWNER>/<REPO> <IID> --label "status:in-progress"     # ADDS; existing labels stay — see caveat below
+glab issue update -R <OWNER>/<REPO> <IID> --unlabel "status:in-progress"   # removes only the named label(s)
 glab issue close -R <OWNER>/<REPO> <IID>                                   # then VERIFY: re-read the issue; it must show state=closed
 glab issue note -R <OWNER>/<REPO> <IID> -m "Comment text"                  # Add comment
 
@@ -196,7 +197,7 @@ glab api --hostname "$GITLAB_HOST" "projects/${ENCODED_PROJECT_PATH}/issues?stat
 glab api --hostname "$GITLAB_HOST" "projects/${ENCODED_PROJECT_PATH}/milestones?state=active"
 ```
 
-**Label update caveat (PUT-replaces, not additive):** `glab issue update --label` (and the underlying GitLab labels API) PUT-REPLACES the entire label set — it does not add to the existing set. To change a single label you must pass the FULL desired label list, or use the dedicated add/remove operations, which are themselves unreliable across `glab` versions. Preferred safe pattern: use `--label` (adds) together with `--unlabel` (removes) on `glab issue update` when your installed `glab` version supports both; otherwise read the current labels first, compute the full new set, and PUT once. The same PUT-replace semantics apply to `glab mr update --label`.
+**Label update caveat: the `glab` flags add or remove, the raw API `labels=` sets the whole list.** Measured 2026-09-19 with `glab 1.117.0 (44790937b)`: `glab issue update <IID> --label "status:in-progress"` on 7 issues (#1390 #1389 #1339 #1298 #1273 #1221 #1202) ADDED the label and left every existing label in place. Read-only re-check (canonical identity form above): `glab api --hostname "$GITLAB_HOST" "projects/${ENCODED_PROJECT_PATH}/issues/${ISSUE_IID}" | jq .labels` → for #1390 `["area:meta","follow-up","priority::low","status:in-progress","type:chore"]`. `glab issue update --help` agrees (`-l --label  Add labels.`, `-u --unlabel  Remove labels.`). To remove a label, use `--unlabel` (comma-separated for several); `stripStatusLabels` in `scripts/lib/issue-close-strip-labels.mjs` does exactly that. The raw REST API is different, and this part comes from the docs, not a measurement: the GitLab Issues API documents `labels` on `PUT /projects/:id/issues/:issue_iid` as "Comma-separated label names for an issue. Set to an empty string to unassign all labels.", with `add_labels` / `remove_labels` as the incremental parameters. So a `glab api --silent --hostname "$GITLAB_HOST" -X PUT "projects/${ENCODED_PROJECT_PATH}/issues/${ISSUE_IID}" -f labels=…` call must carry the FULL desired set; prefer `add_labels=` / `remove_labels=`. Other `glab` versions were not measured, so re-run the read-only check after an upgrade. `glab mr update` lists the same `--label` "Add labels." / `--unlabel` "Remove labels." help text in 1.117.0; its behaviour was not measured.
 
 **Close verification:** after `glab issue close <IID>`, always verify the close actually landed — re-read the issue (`glab issue view <IID>`) and confirm `state: closed` in the output. A stale or wrong project path, or a silent 404, can report local success while closing nothing; use the canonical project identity above for API operations rather than resolving a numeric ID.
 

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:

package/skills/hook-development/SKILL.md

@@ -6,21 +6,23 @@ model: sonnet
 
 # Hook Development for Claude Code Plugins
 
-Adapted from [claude-plugins-official/plugin-dev/skills/hook-development](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/plugin-dev/skills/hook-development). Trimmed to what we actually author (our plugin already has 6 event matchers covering 7 hook handlers — see `hooks/hooks.json`).
+Use the [official Claude Code hooks reference](https://code.claude.com/docs/en/hooks) as the source of truth for current events and schemas. This skill keeps only the conventions needed to author this plugin's hooks.
 
-## Hook types
+## Hook types used in this plugin
+
+Claude Code also documents `http`, `mcp_tool`, and experimental `agent` handlers. Use those only after checking their current fields and event support in the official reference.
 
 ### Prompt-based (LLM-driven, for complex reasoning)
 
 ```json
 {
   "type": "prompt",
-  "prompt": "Evaluate if this tool use is appropriate: $TOOL_INPUT",
+  "prompt": "Evaluate whether this event should proceed: $ARGUMENTS",
   "timeout": 30
 }
 ```
 
-Supported events: `Stop`, `SubagentStop`, `UserPromptSubmit`, `PreToolUse`.
+Prompt hooks are supported only on events documented for that handler type. `$ARGUMENTS` contains the hook input JSON.
 
 Use for: context-aware decisions, flexible evaluation, natural-language reasoning.
 
@@ -36,11 +38,11 @@ Use for: context-aware decisions, flexible evaluation, natural-language reasonin
 
 Use for: fast deterministic validations, file-system ops, external tools, performance-critical paths.
 
-**Our convention:** all our command hooks are `.mjs` (Node.js) — see `hooks/pre-bash-destructive-guard.mjs`, `hooks/enforce-scope.mjs`. The v3.0 migration moved us off bash for native Windows support.
+**Our convention:** hook logic lives in `.mjs` files — see `hooks/pre-bash-destructive-guard.mjs` and `hooks/enforce-scope.mjs`. The manifest invokes them through the repository's runtime wrapper.
 
 ## Configuration formats
 
-This is where people trip up. Two formats exist; they are NOT interchangeable.
+Keep the file location and its outer document shape explicit when copying an example.
 
 ### Plugin `hooks/hooks.json` — wrapper format
 
@@ -63,25 +65,27 @@ This is where people trip up. Two formats exist; they are NOT interchangeable.
 - `hooks` wrapper is required
 - `description` is optional
 
-### User `.claude/settings.json` — direct format
+### User or project `.claude/settings.json` — settings format
 
 ```json
 {
-  "PreToolUse": [
-    {
-      "matcher": "Write|Edit",
-      "hooks": [
-        { "type": "command", "command": "~/my-hook.sh" }
-      ]
-    }
-  ]
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          { "type": "command", "command": "~/my-hook.sh" }
+        ]
+      }
+    ]
+  }
 }
 ```
 
-- No wrapper
-- No description
+- The top-level `hooks` key is required in settings.
+- Plugin `hooks/hooks.json` may additionally carry a top-level `description`.
 
-Mixing these up is the #1 reason new hooks don't fire.
+The distinction is registration and scope: settings hooks belong to a user, project, or managed policy; plugin hooks run while the plugin is enabled. The nested event → matcher group → handler shape is the same.
 
 ## Hook events
 
@@ -92,7 +96,7 @@ Mixing these up is the #1 reason new hooks don't fire.
 | `UserPromptSubmit` | User submits prompt | Add context, validate |
 | `Stop` | Main agent stopping | Completeness check |
 | `SubagentStop` | Subagent stopping | Task validation |
-| `SessionStart` | Session begins | Context load |
+| `SessionStart` | Session begins or resumes | Context load |
 | `SessionEnd` | Session ends | Cleanup, logging |
 | `PreCompact` | Before compaction | Preserve critical state |
 | `Notification` | User notified | Logging, reactions |
@@ -102,7 +106,9 @@ Mixing these up is the #1 reason new hooks don't fire.
 ```json
 {
   "hookSpecificOutput": {
-    "permissionDecision": "allow|deny|ask",
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Why this decision was made",
     "updatedInput": { "field": "modified_value" }
   },
   "systemMessage": "Explanation shown to Claude"
@@ -113,12 +119,14 @@ Mixing these up is the #1 reason new hooks don't fire.
 
 ```json
 {
-  "decision": "approve|block",
-  "reason": "Why blocked / approved",
+  "decision": "block",
+  "reason": "Why Claude should continue",
   "systemMessage": "Additional context"
 }
 ```
 
+Omit `decision` to allow stopping. `approve` is not a valid Stop decision. For non-error feedback that keeps the conversation running, use `hookSpecificOutput.additionalContext` with `hookEventName` set to `Stop` or `SubagentStop`.
+
 ### SessionStart: persist env vars
 
 ```bash
@@ -136,17 +144,18 @@ All hooks receive JSON on stdin:
   "session_id": "abc123",
   "transcript_path": "/path/to/transcript.jsonl",
   "cwd": "/current/working/dir",
-  "permission_mode": "ask|allow",
+  "permission_mode": "default",
   "hook_event_name": "PreToolUse"
 }
 ```
 
 Event-specific extras:
-- `PreToolUse`/`PostToolUse`: `tool_name`, `tool_input`, `tool_result`
-- `UserPromptSubmit`: `user_prompt`
-- `Stop`/`SubagentStop`: `reason`
+- `PreToolUse`: `tool_name`, `tool_input`, `tool_use_id`
+- `PostToolUse`: `tool_name`, `tool_input`, `tool_response`, `tool_use_id`
+- `UserPromptSubmit`: `prompt`
+- `Stop`: `stop_hook_active`, `last_assistant_message`; `SubagentStop` also carries agent identity and transcript fields
 
-Access in prompt hooks via `$TOOL_INPUT`, `$TOOL_RESULT`, `$USER_PROMPT`.
+Event fields vary and evolve. Parse only fields needed by the hook and consult the official event section before depending on one. The `UserPromptSubmit` field name above was last checked against the official reference on 2026-09-15 (branch `codex/ecc-systematic-review`); this plugin registers no `UserPromptSubmit` handler, so no code here exercises either spelling — verify before depending on it. Prompt and agent hooks receive the complete input through `$ARGUMENTS`.
 
 ## Environment variables
 
@@ -222,7 +231,7 @@ echo $file_path          # ❌ unquoted injection risk
 
 ### Timeouts
 
-Defaults: command hooks 60s, prompt hooks 30s. Set explicitly when the work is known-slow:
+Current defaults are 600 seconds for command/HTTP/MCP-tool hooks, 30 seconds for prompt hooks, and 60 seconds for agent hooks, with shorter defaults for some events. `SessionEnd` also has a shared time budget. Set a short explicit timeout appropriate to the hook; a timed-out `PreToolUse` command hook does not block the tool call.
 
 ```json
 { "type": "command", "command": "...", "timeout": 10 }
@@ -232,17 +241,13 @@ Defaults: command hooks 60s, prompt hooks 30s. Set explicitly when the work is k
 
 All matching hooks run **in parallel** — they don't see each other's output, ordering is non-deterministic. Design for independence.
 
-## Lifecycle limitation — NO hot-swap
+## Registration and reload behavior
 
-Hooks load at session start. Changes to `hooks.json` or hook scripts do **not** affect the running session.
+Installed capability and active registration are different. A plugin can ship hook files without those hooks running when the plugin is disabled. Settings hooks merge with plugin and managed hooks; `/hooks` shows the active sources.
 
-To test hook changes:
-1. Edit hook
-2. Exit Claude Code
-3. Restart (`claude` or `cc`)
-4. Verify with `/hooks` command or `claude --debug`
+Direct edits to hooks in settings files are normally picked up by Claude Code's file watcher. Plugin registration changes may require disabling/re-enabling the plugin or starting a fresh session. A command hook's script is launched when the event fires, so editing the script itself can affect the next invocation without re-registering the manifest.
 
-This is the #2 reason "my hook isn't working" — the change hasn't loaded yet.
+To test a registration change, inspect `/hooks`, trigger the matching event, and use `claude --debug` when the source, matcher, output, or timeout remains unclear.
 
 ## Debugging
 
@@ -269,7 +274,7 @@ output=$(./your-hook.mjs < test-input.json)
 echo "$output" | jq .
 ```
 
-Invalid JSON breaks silently — always verify.
+Invalid structured output is normally reported as a non-blocking hook error and the action proceeds, so always verify the output and the resulting decision.
 
 ## Conditional activation
 
@@ -292,8 +297,8 @@ enabled=$(jq -r '.strictMode // false' "$CONFIG_FILE" 2>/dev/null)
 
 ## Our in-house examples (read these, not the upstream `examples/`)
 
-- `hooks/pre-bash-destructive-guard.mjs` — policy-driven command blocker, 14 rules in `.orchestrator/policy/blocked-commands.json`
-- `hooks/enforce-scope.mjs` — wave-scope boundary enforcement using `.orchestrator/wave-scope.json`
+- `hooks/pre-bash-destructive-guard.mjs` — policy-driven command blocker backed by `.orchestrator/policy/blocked-commands.json`
+- `hooks/enforce-scope.mjs` — scope enforcement using `wave-scope.json` in the platform's state directory
 - `hooks/on-session-start.mjs` — banner + session init
 - `hooks/post-edit-validate.mjs` — validates edits after the fact
 - `hooks/on-stop.mjs` — session-event capture + metrics
@@ -306,7 +311,7 @@ enabled=$(jq -r '.strictMode // false' "$CONFIG_FILE" 2>/dev/null)
 - Validate every input field before trusting it
 - Quote all shell variables
 - Set explicit timeouts for known-slow work
-- Return structured JSON on stdout
+- Return only schema-valid structured JSON when the event needs a decision or context; emit nothing on a silent allow
 
 **Don't:**
 - Hardcoded paths
@@ -409,5 +414,5 @@ env-precedence, PluginRootResolutionError class shape.
 
 ## References
 
-- [Official hooks docs](https://docs.claude.com/en/docs/claude-code/hooks)
+- [Official hooks reference](https://code.claude.com/docs/en/hooks)
 - Upstream: [patterns.md](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/plugin-dev/skills/hook-development/references/patterns.md), [advanced.md](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/plugin-dev/skills/hook-development/references/advanced.md) — read these for edge cases we haven't hit yet

package/skills/memory-cleanup/SKILL.md

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

package/skills/npm-publish/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: npm-publish
-user-invocable: true
+user-invocable: false
 model: sonnet
 description: Use when publishing this package to npm — a version release (npm publish), verifying the registry/pi.dev listing, or diagnosing npm auth failures (E403 2FA/token errors). Token-based flow via NPM_TOKEN in .env.local with a temp userconfig, the leakage gate before every publish, post-publish verification and marker/badge upkeep. Trigger on "publish to npm", "npm release", "E403 publish error".
 ---
@@ -39,7 +39,7 @@ The script gates mechanics. These three are yours, and it will not make them for
 
 **2. What a leak means when one is found.** A hit from the leakage gate is not a pattern to silence. Decide which of two it is: a real leak (fix `package.json` `files`, re-pack, re-check) or genuine over-matching (fix `LEAKAGE_PATTERNS` in `scripts/release.mjs` **with a test**). There is no third option, and neither is "publish anyway and clean it up in the next version" — an npm publish is not revocable, and unpublishing burns the version number permanently. Operator handling detail: `docs/distribution/npm-publish-checklist.md` § 3.
 
-**3. When to abort instead of repair.** Abort — do not patch forward — when the failure is upstream of the target-confirmed npm receipt: a red preflight row, a lagging `github` mirror, CI not green on the exact commit **on either platform** (`--check` carries both `ci-green-on-head` for GitLab and `ci-green-on-head-github` for the mirror, whose macOS matrix leg has no GitLab equivalent), a dead token, or a publish that did not issue the target receipt. These are cheap to fix and re-run from the top. Repair-in-place is only appropriate *after* that receipt, where the version is already immutable: registry propagation, a missing GitHub release, or a lagging site deploy can be reconciled because npm already has the correct artifact. When `--publish` reports **Post-publish reconciliation required**, **do not rerun `--publish`**; repair the listed state directly. `commands/release.md` § Abort criteria is the operative list.
+**3. When to abort instead of repair.** Abort — do not patch forward — when the failure is upstream of the target-confirmed npm receipt: a red preflight row, a lagging `github` mirror, CI not green on the exact commit **on either platform** (`--check` carries both `ci-green-on-head` for GitLab and `ci-green-on-head-github` for the mirror, whose macOS matrix leg has no GitLab equivalent), a dead token, or a publish that did not issue the target receipt. These are cheap to fix and re-run from the top. Repair-in-place is only appropriate *after* that receipt, where the version is already immutable: registry propagation, a missing GitHub release, or a lagging site deploy can be reconciled because npm already has the correct artifact. When `--publish` reports **Post-publish reconciliation required**, **do not rerun `--publish`**; repair the listed state directly. `skills/release/SKILL.md` § Abort criteria is the operative list.
 
 ## Failure-mode table
 

package/skills/persona-panel/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: persona-panel
 user-invocable: true
+argument-hint: "<target> [--personas <names,...>] [--mode <voting|hard-gate|summary>] [--threshold <M-of-N|all|any>] [--grounding <off|re-derive>] [--dry-run]"
 tags: [review, personas, content, quality, multi-agent]
 model: inherit
 description: >
@@ -13,6 +14,60 @@ description: >
 
 # Persona Panel Skill
 
+## Invocation
+
+The user invoked `/persona-panel` with arguments: **$ARGUMENTS**. Parse them before doing anything else — including before the Phase 0 bootstrap gate's side effects.
+
+**Positional argument (required):**
+
+- `<target>` — file path, directory, or range to review. Must be resolvable via `validatePathInsideProject` against the current project root (Phase 2). Relative paths are resolved from the project root. Globs are accepted (e.g. `src/app/api/*.ts`).
+
+**Recognized flags:**
+
+- `--personas <names,...>` — comma-separated subset of catalog names to include (e.g. `physicist,ai-expert`). Default: all personas discovered in `.claude/personas/`. Names are matched case-insensitively against `<name>.md` catalog files.
+- `--mode <voting|hard-gate|summary>` — consolidation mode; the short forms are aliases of the Phase 4 mode names `voting-quorum`, `hard-gate-threshold` and `coordinator-summary` respectively. Default: `voting-quorum`. `summary` emits an explicit WARN that this mode adds one additional LLM call.
+- `--threshold <spec>` — quorum spec. Accepted forms: `M-of-N` where M and N are integers 1..20, `all`, or `any`. Parsed by `scripts/lib/persona-panel/threshold.mjs::parseThreshold()`. Default: `all` for `hard-gate-threshold`. In `voting-quorum` the majority default of Phase 4 applies unless `--quorum <M>` overrides it.
+- `--quorum <M>` — integer M-of-N override for `voting-quorum` (see Phase 4).
+- `--grounding <off|re-derive>` — Grounding-Review mode (#730 Epic H). `off` (default): personas evaluate the target as-is. `re-derive`: each persona independently re-derives supporting sources via Read/Grep/Glob instead of trusting a "Sources" section the target may already assert, and reports them as `derived_sources`. Advisory-only in v1 — never influences `final_verdict`. See `skills/persona-panel/persona-format.md` § "Grounding Mode (optional)".
+- `--lines <start>-<end>` — restrict the review to a line range of the target (validated in Phase 2: start ≤ end, both positive integers).
+- `--dry-run` — resolve catalog and target, print the dispatch plan (persona names, models, target), do NOT call `Agent()`, do NOT write a sidecar. Exit 0 on success.
+
+**Validation errors (all exit 1):**
+
+- Missing `<target>`: `missing required arg <target>` — print the usage line and exit 1 without running any phase.
+- Unknown flag (starts with `--` but not in the list above): `unknown flag: --<name>. Valid: --personas, --mode, --threshold, --quorum, --grounding, --lines, --dry-run`.
+- `--mode` value not in enum: `invalid --mode value: '<value>'. Valid: voting, hard-gate, summary`.
+- `--threshold` value fails `parseThreshold()`: echo the parser error verbatim, e.g. `invalid threshold 'foo': expected M-of-N (M,N integers 1..20), 'all', or 'any'`.
+- `--grounding` value not in enum: `invalid --grounding value: '<value>'. Valid: off, re-derive`.
+- `<target>` outside project root: `target path outside project: <path>`.
+
+### Examples
+
+```
+/persona-panel src/app/api/invoices.ts
+```
+All `.claude/personas/*.md` are dispatched, voting consolidation, sidecar written.
+
+```
+/persona-panel src/app/api/invoices.ts --personas physicist,ai-expert
+```
+Only the `physicist` and `ai-expert` catalog entries are dispatched.
+
+```
+/persona-panel notes/draft.md --mode hard-gate --threshold all
+```
+All resolved personas must return PASS; a single FAIL produces a final FAIL verdict.
+
+```
+/persona-panel src/ --dry-run
+```
+Prints the planned dispatch list and exits 0 without calling `Agent()` or writing a sidecar.
+
+```
+/persona-panel docs/design-doc.md --grounding re-derive
+```
+Each persona re-derives its own supporting sources rather than trusting a "Sources" section already present in the input document (for example, `docs/design-doc.md`), reporting them as `derived_sources`. Advisory-only — `final_verdict` is unaffected. <!-- path-check: example -->
+
 ## Overview
 
 Persona Panel runs any number of catalog-defined personas in parallel against a single target
@@ -355,7 +410,7 @@ result. If `final_verdict == "warn"`: exit 0 with a warning line on stderr. If
 
 ## See Also
 
-- `commands/persona-panel.md` — argument parsing and CLI contract
+- `scripts/lib/persona-panel/threshold.mjs` — parseThreshold() for `--threshold` specs
 - `agents/schemas/persona-panel-sidecar.schema.json` — sidecar JSON Schema (Draft 2020-12)
 - `scripts/lib/persona-panel/catalog-loader.mjs` — loadCatalog() implementation
 - `scripts/lib/persona-panel/persona-runner.mjs` — buildPersonaPrompt() implementation

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

@@ -170,7 +170,7 @@ diff is reported alongside the panel result and has **zero influence on `final_v
 is signal for the operator to review, not a consolidation input. `consolidate()` and `tally()`
 in `consolidator.mjs` are deliberately unaware of grounding data.
 
-**Enabling it:** pass `--grounding re-derive` to `/persona-panel` (see `commands/persona-panel.md`).
+**Enabling it:** pass `--grounding re-derive` to `/persona-panel` (see `skills/persona-panel/SKILL.md`).
 Default remains `--grounding off`.
 
 ---

package/skills/plan/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: plan
-user-invocable: false
+user-invocable: true
+disable-model-invocation: true
+argument-hint: "[new|feature|retro]"
 tags: [planning, prd, requirements, research]
 model: inherit
 model-preference: opus
@@ -19,6 +21,24 @@ description: >
 
 > Project-instruction file resolution: CLAUDE.md and AGENTS.md (Codex CLI) are transparent aliases — see [skills/_shared/instruction-file-resolution.md](../_shared/instruction-file-resolution.md). All references below to `CLAUDE.md` resolve via that precedence rule.
 
+## Invocation
+
+You are beginning a structured planning session. The user invoked `/plan` with mode: **$ARGUMENTS** (if empty, Phase 2's Mode Router asks which mode they want: `new`, `feature`, or `retro`).
+
+**Modes:** `new` = project kickoff, `feature` = feature PRD, `retro` = retrospective.
+
+**Your job: guide the user through structured requirement gathering and produce a complete plan document for the chosen mode.** Follow the phases below precisely. Do NOT skip any phase. Do NOT make assumptions — gather requirements interactively.
+
+### Headless (`claude -p`)
+
+`session` and `plan` are **reserved terminal-only built-in names** in non-interactive sessions — under `claude -p` the bare form answers `"/plan isn't available in this environment."`, and no frontmatter or manifest field overrides that (reproduced with an empty `CLAUDE_CONFIG_DIR` and no plugin loaded, claude 2.1.273, measured 2026-09-16). Use the namespaced form, which does resolve:
+
+```bash
+claude -p "/session-orchestrator:plan feature" --plugin-dir "$PWD"
+```
+
+Interactive sessions are unaffected — `/plan` works there as it always has.
+
 ## File Structure
 
 - `SKILL.md` — Core framework: mode router, Q&A engine, shared phases
@@ -92,6 +112,13 @@ This is the distinctive mechanic shared by all three modes. Every question wave
 
 ### 3.1 Pre-Question Research
 
+Read [Research Evidence Contract](../_shared/research-evidence.md) before the
+first research wave. Apply it to findings that materially affect an option or
+recommendation; keep trivial local lookups concise. Carry the source revision or
+date, evidence basis, local equivalent, disposition, and any falsifiable next
+check into each research brief and the synthesis so documented claims and
+inferences remain distinct.
+
 Before each Q&A wave, dispatch 2-3 `Agent()` tool calls in a single message (parallel execution) with `subagent_type: "Explore"`:
 
 1. **Market/online context agent** — searches for relevant market data, best practices, competitor analysis, or technical patterns depending on the questions to be asked. Tools: WebSearch, WebFetch.

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

@@ -1,11 +1,17 @@
 ---
+name: portfolio
 description: Aggregate cross-repo issue/MR/CI health across vault-registered projects into a single Markdown dashboard
+user-invocable: true
 argument-hint: "[--dry-run] [--repo <name>]"
+model: inherit
 ---
-
 # Portfolio
 
-Aggregates open issues, MRs, and staleness signals across all vault-registered repositories and writes a structured dashboard to `<vault-dir>/01-projects/_PORTFOLIO.md`. Invoke the `gitlab-portfolio` skill with arguments: **$ARGUMENTS**
+## Invocation
+
+The user invoked `/portfolio` with arguments: **$ARGUMENTS**. This skill carries the argument validation (`--dry-run`, `--repo <name>`), the config/mode/vault gates, the dispatch into `scripts/lib/gitlab-portfolio/cli.mjs`, and the exit-code table — all below; `skills/gitlab-portfolio/SKILL.md` owns the dashboard schema.
+
+Aggregates open issues, MRs, and staleness signals across all vault-registered repositories and writes a structured dashboard to `<vault-dir>/01-projects/_PORTFOLIO.md`.
 
 ## Argument Validation
 

package/skills/reconcile/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: reconcile
 user-invocable: true
+argument-hint: "[--dry-run]"
 tags: [learning, rules, intelligence, meta]
 model: sonnet
 model-preference: sonnet
@@ -19,6 +20,15 @@ description: >
 
 # Reconcile Skill
 
+## Invocation
+
+The user invoked `/reconcile` with arguments: **$ARGUMENTS** — parsed in Phase 1.3 below.
+
+- `/reconcile` — full approval flow: engine → AUQ → write approved rules.
+- `/reconcile --dry-run` — print proposals and rejections without writing anything or rendering the AUQ prompt.
+
+**Engine seams used:** `runReconcile` (engine.mjs) · `writeApprovedRules` (writer.mjs) · `reconcile` config block · `.claude/rules/` write target.
+
 On-demand version of the session-end Phase 3.6.8 reconciliation flow. Turns eligible learnings
 from `.orchestrator/metrics/learnings.jsonl` into proposed `.claude/rules/<slug>.md` entries,
 presenting each batch of 4 to the coordinator via AUQ multiSelect for operator approval before
@@ -384,6 +394,17 @@ consolidation survives the next `/reconcile`:
   regenerates that learning as a standalone file on the next run.
 - **A merged file's `expires-at` is the EARLIEST of its parts**, never the
   latest: it must not outlive its shortest-lived content.
+- **An EXPIRED file no longer dedupes** (#1387): the provenance reader skips it
+  whole, so its learnings become re-proposable — fail-open on an unparseable
+  date. Two known limits, measured 2026-09-18: this is the on-disk half only
+  (79 of this repo's 92 provenance keys are ALSO sidecar-terminal, so just 13
+  return), and a file the sweep cannot split or cannot read
+  (`no-1to1-mapping`, `no-provenance-block`, `unreadable`, and since GH#70
+  `no-counter-sentence` — the fail-closed branch that touches such a file not
+  at all, deletion included; none in the live tree today, `skipped: []` over 7
+  files) that expires legitimately
+  re-proposes on every run with no mechanical exit. Detail:
+  `docs/rule-authoring.md` § Consolidated rules.
 - **A dropped learning must be STAMPED before deletion, or it regenerates.**
   `rm .claude/rules/<slug>.md` alone leaves `isProcessed()` false and no
   on-disk marker, so the engine re-proposes it. Stamp it terminal first with

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

@@ -1,14 +1,28 @@
 ---
+name: release
 description: Cut a release — the order the steps must run in, and the criteria that abort a release
+user-invocable: true
 disable-model-invocation: true
 argument-hint: "[X.Y.Z]"
+model: inherit
 ---
-
 # Release
 
 The user wants to cut a release of this package. Optional argument — the target version: **$ARGUMENTS**.
 
-**The mechanism is `scripts/release.mjs`.** It exists, it is executable, and its pure half is unit-tested (`tests/scripts/release.test.mjs`). This command carries only the two things the script cannot carry: the **order**, and the **criteria that stop a release**. Do not restate the script's internals here — `node scripts/release.mjs --help` and the file header are the reference.
+**The mechanism is `scripts/release.mjs`.** It exists, it is executable, and its pure half is unit-tested (`tests/scripts/release.test.mjs`). This skill carries only the two things the script cannot carry: the **order**, and the **criteria that stop a release**. Do not restate the script's internals here — `node scripts/release.mjs --help` and the file header are the reference.
+
+## Invocation
+
+`$ARGUMENTS` is optional and holds the target version `X.Y.Z`. When it is empty, resolve the target from `package.json` and the CHANGELOG before step 2.
+
+The flags this repo's release path uses — the operator-facing entry points, in the order they run:
+
+- `node scripts/release.mjs --set-version X.Y.Z` — rewrite every version surface and sync `package-lock.json`.
+- `node scripts/release.mjs --check --json` — the preflight gate; every row must be green.
+- `node scripts/release.mjs --publish` — the irreversible step; give it ≥600 s of wall clock.
+
+`--skip-ci` marks the CI row green without checking anything and is **refused by the script** when combined with `--publish`; it is an inspection aid for `--check`, never a release path.
 
 ## Why the order is written down
 

package/skills/repo-audit/SKILL.md

@@ -10,6 +10,7 @@ description: >
   (optional), and MCP Configuration. Will produce a Markdown checklist report and JSON sidecar."
   <commentary>The user wants a compliance check; this skill is appropriate because it runs all 9
   categories with pass/fail/warn/skipped statuses and writes structured output.</commentary></example>
+user-invocable: true
 model: inherit
 color: cyan
 ---
@@ -18,6 +19,12 @@ color: cyan
 
 Perform a comprehensive audit of the host repository against the ecosystem baseline. Emits a structured Markdown checklist report and a JSON sidecar for trend tracking.
 
+## Invocation
+
+There are no arguments — ignore `$ARGUMENTS`; anything passed is discarded.
+
+Do NOT skip any category (except Clank when not detected). Do NOT auto-fix findings — report only.
+
 ## Purpose
 
 Answer the question: "Does this repo match the ecosystem baseline?" — a compliance-focused, checkable question with a fixed 9-category checklist. Distinct from `/discovery` (broad quality probes) and `/harness-audit` (plugin installation health).