session-orchestrator 3.20.0 → 3.21.0

package/skills/discovery/probes-feature.md

@@ -113,11 +113,11 @@ Export Status: exported/public | internal
 1. List open feature/enhancement issues via the VCS CLI (syntax reference: `skills/gitlab-ops/SKILL.md` § "Common CLI Commands" — do not duplicate CLI flags here beyond what's needed to name the call):
 ```bash
 # GitLab
-glab issue list --label "feature" --per-page 100
-glab issue list --label "enhancement" --per-page 100
+glab issue list -R <OWNER>/<REPO> --label "feature" --per-page 100
+glab issue list -R <OWNER>/<REPO> --label "enhancement" --per-page 100
 # GitHub
-gh issue list --label "feature" --limit 100
-gh issue list --label "enhancement" --limit 100
+gh issue list -R <OWNER>/<REPO> --label "feature" --limit 100
+gh issue list -R <OWNER>/<REPO> --label "enhancement" --limit 100
 ```
 
 2. Extract theme keywords from each issue's title (and first paragraph of body where available): lowercase, strip stop-words, tokenize on non-alphanumeric boundaries. Group issues that share two or more significant keywords (e.g. "export", "csv", "invoice") into a candidate cluster.
@@ -125,10 +125,10 @@ gh issue list --label "enhancement" --limit 100
 3. For each candidate cluster with 3 or more issues, check whether ANY member issue is already linked to an epic (`epic` label, a GitLab Epic relationship, or an in-body reference such as `part of #<epic-iid>` / `Epic: #<epic-iid>`):
 ```bash
 # GitLab -- inspect labels + description for epic linkage
-glab issue view <IID>
+glab issue view -R <OWNER>/<REPO> <IID>
   Grep pattern: (^Labels:.*\bepic\b|part of #|Epic:\s*#)
 # GitHub -- same check against issue body/labels
-gh issue view <NUMBER>
+gh issue view -R <OWNER>/<REPO> <NUMBER>
   Grep pattern: (^labels:.*\bepic\b|part of #|Epic:\s*#)
 ```
 

package/skills/discovery/probes-infra.md

@@ -10,10 +10,10 @@
 
 ```bash
 # GitLab: query recent pipeline status
-glab pipeline list --per-page 10
+glab pipeline list -R <OWNER>/<REPO> --per-page 10
 
 # GitHub: query recent workflow runs
-gh run list --limit 10
+gh run list -R <OWNER>/<REPO> --limit 10
 
 # Parse output for:
 # - Repeated failures (same pipeline failing 3+ times in a row)

package/skills/discovery/probes-session.md

@@ -55,9 +55,9 @@ Grep pattern: <claimed_addition>
 git show <commit_hash> -- <relevant_files>
 
 # "Closes #N" -> verify acceptance criteria from issue #N are met
-gh issue view <N> --json body -q '.body'
+gh issue view -R <OWNER>/<REPO> <N> --json body -q '.body'
 # or
-glab issue view <N>
+glab issue view -R <OWNER>/<REPO> <N>
 
 # Step 3: Cross-reference claims against actual changes
 git diff <commit_hash>~1..<commit_hash>
@@ -83,10 +83,10 @@ Evidence: <what was found or not found>
 
 ```bash
 # GitLab: list open issues sorted by last update
-glab issue list --per-page 100 | head -50
+glab issue list -R <OWNER>/<REPO> --per-page 100 | head -50
 
 # GitHub: list open issues sorted by last update
-gh issue list --limit 100 --json number,title,labels,updatedAt,assignees --jq '.[] | select(.updatedAt < "<30_days_ago_iso>")'
+gh issue list -R <OWNER>/<REPO> --limit 100 --json number,title,labels,updatedAt,assignees --jq '.[] | select(.updatedAt < "<30_days_ago_iso>")'
 
 # Flag:
 # - Issues with no activity in stale-issue-days (default: 30 days)
@@ -131,7 +131,7 @@ for issue in issues:
 "
 
 # GitHub: fetch issue bodies and parse cross-references
-gh issue list --limit 100 --json number,body --jq '.[] | {number, body}' | python3 -c "
+gh issue list -R <OWNER>/<REPO> --limit 100 --json number,body --jq '.[] | {number, body}' | python3 -c "
 import json, sys, re
 for line in sys.stdin:
     issue = json.loads(line)

package/skills/dispatcher/SKILL.md

@@ -1,6 +1,15 @@
 ---
 name: dispatcher
-description: Use when you want the orchestrator to pick the next repo to work on across your whole portfolio — it enumerates candidate repos below the confinement root, resolves free/busy from each repo's session.lock lease, ranks the FREE ones by backlog priority × staleness × readiness, recommends the single most worthwhile one via AskUserQuestion, atomically claims it, and routes you to the chosen entry command. Triggers: "what should I work on next", "dispatch me to a repo", "pick the next project", "run /dispatcher". <example>Context: operator finished a session and wants the next-best repo across the 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>
+description: >
+  Use when you want the orchestrator to pick the next repo to work on across your whole portfolio — it
+  enumerates candidate repos below the confinement root, resolves free/busy from each repo's session.lock
+  lease, ranks the FREE ones by backlog priority × staleness × readiness, recommends the single most
+  worthwhile one via AskUserQuestion, atomically claims it, and routes you to the chosen entry command.
+  Triggers: "what should I work on next", "dispatch me to a repo", "pick the next project", "run
+  /dispatcher". <example>Context: operator finished a session and wants the next-best repo across the
+  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>
 model: sonnet
 ---
 

package/skills/frontmatter-guard/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: frontmatter-guard
-description: Injects the canonical vault frontmatter schema snippet into agent prompts before any vault-write task, preventing malformed YAML frontmatter in Obsidian notes. <example>Context: wave-executor is about to dispatch a vault-mirror agent that writes learning notes under ~/Projects/vault/40-learnings/. user: "dispatch vault-write agent" assistant: "Injecting frontmatter-guard snippet into agent prompt (vault scope detected). Required fields: id, type, created, updated. Enum type: note|daily|project|person|reference|idea|learning|session." <commentary>The wave-executor pre-dispatch hook calls detectVaultTaskScope() — the fileScope contains /Projects/vault/40-learnings/ so the guard triggers and the snippet is prepended to the agent system prompt.</commentary></example>
+description: >
+  Injects the canonical vault frontmatter schema snippet into agent prompts before any vault-write task,
+  preventing malformed YAML frontmatter in Obsidian notes. <example>Context: wave-executor is about to
+  dispatch a vault-mirror agent that writes learning notes under ~/Projects/vault/40-learnings/. user:
+  "dispatch vault-write agent" assistant: "Injecting frontmatter-guard snippet into agent prompt (vault
+  scope detected). Required fields: id, type, created, updated. Enum type:
+  note|daily|project|person|reference|idea|learning|session." <commentary>The wave-executor pre-dispatch
+  hook calls detectVaultTaskScope() — the fileScope contains /Projects/vault/40-learnings/ so the guard
+  triggers and the snippet is prepended to the agent system prompt.</commentary></example>
 model: inherit
 ---
 

package/skills/gitlab-ops/SKILL.md

@@ -6,7 +6,15 @@ model: haiku
 model-preference: sonnet
 model-preference-codex: gpt-5.4-mini
 model-preference-cursor: claude-sonnet-4-6
-description: Use this skill when performing VCS operations on GitLab or GitHub repositories — creating, updating, or closing issues and MRs, applying label taxonomy, running `glab`/`gh` CLI commands, or resolving project IDs dynamically. Acts as the single source of truth for CLI command syntax and label conventions; consuming skills reference this rather than duplicating logic. Triggers: "create a GitLab issue", "list open MRs", "apply priority label", "how do I resolve the project ID", "what's the carryover issue template". <example>Context: session-end needs to file a carryover issue for an incomplete task. user: "/close" assistant: "Creating carryover issue via glab with the Carryover Template from gitlab-ops — labels: carryover, priority::high."</example>
+description: >
+  Use this skill when performing VCS operations on GitLab or GitHub repositories — creating, updating, or
+  closing issues and MRs, applying label taxonomy, running `glab`/`gh` CLI commands, or resolving project
+  IDs dynamically. Acts as the single source of truth for CLI command syntax and label conventions;
+  consuming skills reference this rather than duplicating logic. Triggers: "create a GitLab issue", "list
+  open MRs", "apply priority label", "how do I resolve the project ID", "what's the carryover issue
+  template". <example>Context: session-end needs to file a carryover issue for an incomplete task. user:
+  "/close" assistant: "Creating carryover issue via glab with the Carryover Template from gitlab-ops —
+  labels: carryover, priority::high."</example>
 ---
 
 # VCS Operations Reference
@@ -57,9 +65,9 @@ Never hardcode project IDs. Resolve them at runtime — and re-resolve live each
 
 ```bash
 # GitLab — get numeric project ID
-glab repo view --output json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])"
+glab repo view -R <OWNER>/<REPO> --output json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])"
 
-# GitHub — get owner/name identifier
+# GitHub — get owner/name identifier (gh repo takes the repo POSITIONALLY; it rejects -R)
 gh repo view --json nameWithOwner -q '.nameWithOwner'
 ```
 
@@ -153,33 +161,35 @@ GitHub has no native issue-blocking relation at all — the body-ordering-note f
 
 ## Common CLI Commands
 
+**Directive — consult this only for a command NOT listed below; every example here already complies.** Each repo-scoped `glab`/`gh` invocation carries `-R <OWNER>/<REPO>` (`glab` also accepts `GROUP/SUBGROUP/REPO` or a full remote URL — `resolveRepoSpec()` in `scripts/lib/vcs-repo-spec.mjs` produces the right spec per platform); without the flag the target is whatever the ambient cwd remote happens to be, which is the wrong project in a sibling worktree, an `/autopilot` child, or a fork. Exactly four exceptions, each probed against the binaries: `glab api`/`gh api` (no `--repo` exists — pin the host with `--hostname` from `resolveRepoHost()` instead), `gh repo <*>` (rejects `-R`; takes the repository positionally), a `glab repo` call that already names the repository positionally, and — conditionally, not subcommand-wide — `gh pr checks|view|diff|ready|merge|comment`, where `-R` is legal ONLY alongside the `<number>|<url>|<branch>` positional: `gh pr checks -R <OWNER>/<REPO> <BRANCH>` carries the flag, while a positional-less `gh pr checks -R <OWNER>/<REPO> --watch` exits 1 with `argument required when using the` `--repo` `flag` — so name the PR or drop the flag, and never derive this from `--help`, which lists `-R` under INHERITED FLAGS with no such qualifier.
+
 ### GitLab (glab)
 
 ```bash
 # Issues
-glab issue list --per-page 50                              # All open issues
-glab issue list --label "status:ready" --per-page 10       # Ready to work on
-glab issue list --label "priority::high" --per-page 10     # High priority
-glab issue list --closed --per-page 10                      # Recently closed
-glab issue view <IID>                                       # View issue details
-glab issue view <IID> --comments                            # With comments
-glab issue create --title "title" --label "priority::high,status:ready"
-glab issue update <IID> --label "status:in-progress"        # WARNING: --label REPLACES the full set — see caveat below
-glab issue close <IID>                                       # then VERIFY: glab issue view <IID> must show state=closed
-glab issue note <IID> -m "Comment text"                    # Add comment
+glab issue list -R <OWNER>/<REPO> --per-page 50                            # All open issues
+glab issue list -R <OWNER>/<REPO> --label "status:ready" --per-page 10     # Ready to work on
+glab issue list -R <OWNER>/<REPO> --label "priority::high" --per-page 10   # High priority
+glab issue list -R <OWNER>/<REPO> --closed --per-page 10                   # Recently closed
+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 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
 
 # MRs
-glab mr list                                                # Open MRs
-glab mr create --fill --draft                               # Create draft MR
-glab mr merge <MR_IID>                                     # Merge MR
+glab mr list -R <OWNER>/<REPO>                                             # Open MRs
+glab mr create -R <OWNER>/<REPO> --fill --draft                            # Create draft MR
+glab mr merge -R <OWNER>/<REPO> <MR_IID>                                   # Merge MR
 
 # Pipelines
-glab pipeline list --per-page 5                            # Recent pipelines
-glab pipeline status <ID>                                  # Pipeline details
+glab pipeline list -R <OWNER>/<REPO> --per-page 5                          # Recent pipelines
+glab pipeline status -R <OWNER>/<REPO> <ID>                                # Pipeline details
 
-# API (reads host from git remote automatically)
-glab api "projects/$(glab repo view --output json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")/issues?state=opened&per_page=50"
-glab api "projects/$(glab repo view --output json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")/milestones?state=active"
+# API (no --repo exists here — the endpoint path IS the target; pin the host with --hostname)
+glab api "projects/$(glab repo view -R <OWNER>/<REPO> --output json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")/issues?state=opened&per_page=50"
+glab api "projects/$(glab repo view -R <OWNER>/<REPO> --output json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")/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`.
@@ -194,27 +204,27 @@ glab api "projects/$(glab repo view --output json | python3 -c "import json,sys;
 
 ```bash
 # Issues
-gh issue list --limit 50                                   # All open issues
-gh issue list --label "status:ready" --limit 10            # Ready to work on
-gh issue list --label "priority::high" --limit 10          # High priority
-gh issue list --state closed --limit 10                    # Recently closed
-gh issue view <NUMBER>                                      # View issue details
-gh issue view <NUMBER> --comments                           # With comments
-gh issue create --title "title" --label "priority::high,status:ready"
-gh issue edit <NUMBER> --add-label "status:in-progress"
-gh issue close <NUMBER>
-gh issue comment <NUMBER> --body "Comment text"            # Add comment
+gh issue list -R <OWNER>/<REPO> --limit 50                                 # All open issues
+gh issue list -R <OWNER>/<REPO> --label "status:ready" --limit 10          # Ready to work on
+gh issue list -R <OWNER>/<REPO> --label "priority::high" --limit 10        # High priority
+gh issue list -R <OWNER>/<REPO> --state closed --limit 10                  # Recently closed
+gh issue view -R <OWNER>/<REPO> <NUMBER>                                   # View issue details
+gh issue view -R <OWNER>/<REPO> <NUMBER> --comments                        # With comments
+gh issue create -R <OWNER>/<REPO> --title "title" --label "priority::high,status:ready"
+gh issue edit -R <OWNER>/<REPO> <NUMBER> --add-label "status:in-progress"
+gh issue close -R <OWNER>/<REPO> <NUMBER>
+gh issue comment -R <OWNER>/<REPO> <NUMBER> --body "Comment text"          # Add comment
 
 # PRs
-gh pr list --state open                                    # Open PRs
-gh pr create --fill --draft                                 # Create draft PR
-gh pr merge <NUMBER>                                       # Merge PR
+gh pr list -R <OWNER>/<REPO> --state open                                  # Open PRs
+gh pr create -R <OWNER>/<REPO> --fill --draft                              # Create draft PR
+gh pr merge -R <OWNER>/<REPO> <NUMBER>                                     # Merge PR
 
 # Workflows (CI equivalent)
-gh run list --limit 5                                      # Recent workflow runs
-gh run view <RUN_ID>                                       # Run details
+gh run list -R <OWNER>/<REPO> --limit 5                                    # Recent workflow runs
+gh run view -R <OWNER>/<REPO> <RUN_ID>                                     # Run details
 
-# API
+# API (no --repo exists here — the endpoint path IS the target; pin the host with --hostname)
 gh api "repos/{owner}/{repo}/issues?state=open&per_page=50"
 gh api "repos/{owner}/{repo}/milestones?state=open"
 ```
@@ -367,8 +377,8 @@ Read .gitlab/merge_request_templates/Default.md
 Read .github/PULL_REQUEST_TEMPLATE.md
 
 # 2. Then create — hook now passes
-glab mr create --title "..." --description "..."
-gh pr create --title "..." --body "..."
+glab mr create -R <OWNER>/<REPO> --title "..." --description "..."
+gh pr create -R <OWNER>/<REPO> --title "..." --body "..."
 ```
 
 ### Cross-References

package/skills/gitlab-portfolio/SKILL.md

@@ -1,6 +1,15 @@
 ---
 name: gitlab-portfolio
-description: Use when you need a single-pane cross-repo health view across all vault-registered GitLab and GitHub projects. Discovers repos from `_overview.md` frontmatter in `<vault>/01-projects/*/`, aggregates open issues, MRs, critical labels, and stale signals via parallel `glab`/`gh` calls, then writes an idempotent `_PORTFOLIO.md` dashboard. Runs automatically at session-start Phase 2 when `gitlab-portfolio.enabled=true`. Triggers: "show portfolio status", "refresh the portfolio dashboard", "which repos have critical issues", "run /portfolio". <example>Context: session-start, gitlab-portfolio.enabled=true, vault has 5 registered repos. user: "/session deep" assistant: "Portfolio: 3 critical issues across 2 repos — run /portfolio for details. Dashboard written to vault/01-projects/_PORTFOLIO.md."</example>
+description: >
+  Use when you need a single-pane cross-repo health view across all vault-registered GitLab and GitHub
+  projects. Discovers repos from `_overview.md` frontmatter in `<vault>/01-projects/*/`, aggregates open
+  issues, MRs, critical labels, and stale signals via parallel `glab`/`gh` calls, then writes an
+  idempotent `_PORTFOLIO.md` dashboard. Runs automatically at session-start Phase 2 when
+  `gitlab-portfolio.enabled=true`. Triggers: "show portfolio status", "refresh the portfolio dashboard",
+  "which repos have critical issues", "run /portfolio". <example>Context: session-start,
+  gitlab-portfolio.enabled=true, vault has 5 registered repos. user: "/session deep" assistant:
+  "Portfolio: 3 critical issues across 2 repos — run /portfolio for details. Dashboard written to
+  vault/01-projects/_PORTFOLIO.md."</example>
 model: sonnet
 ---
 

package/skills/memory-cleanup/SKILL.md

@@ -296,11 +296,24 @@ After completing all four phases, report:
 
 This advances the auto-dream cadence marker (`readDreamSignals` → `lastCleanupAt` in `scripts/lib/auto-dream.mjs`) so `shouldDispatchAutoDream` does not fire a false nudge on the next session.
 
-**Signalling contract (coordinator responsibility at session-end Phase 3.7):**
-- Set `ranMemoryCleanupThisSession = true` when `/memory-cleanup` ran this session in ANY mode or with ANY outcome.
-- Pass this flag to `stampMemoryCleanup()` from `scripts/lib/memory-cleanup-stamp.mjs` before emitting the session record (see `skills/session-end/session-metrics-write.md` § 1-pre).
-- Do NOT distinguish between "applied changes" and "healthy no-op" — both count.
-- Do NOT set `memory_cleanup_at` to `null`; simply omit the field when cleanup did not run.
+**Signalling contract — emit the event, do not rely on remembering.**
+
+As the LAST step of every completed run — dry-run, apply-pending, or healthy no-op alike — emit the completion event. This is mandatory and it is the whole mechanism; there is no second, prose-only path that also works:
+
+```bash
+node scripts/emit-event.mjs \
+  --type orchestrator.memory.cleanup_completed \
+  --payload "{\"semantic_session_id\":\"<the session: value from STATE.md frontmatter>\",\"mode\":\"<dry-run|apply-pending|no-op>\"}"
+```
+
+`scripts/emit-session.mjs` then DERIVES `memory_cleanup_at` from that event at session-close time via `deriveMemoryCleanupSignal()` (`scripts/lib/memory-cleanup-stamp.mjs`), matching events whose `timestamp` falls inside the session's own `[started_at, completed_at]` window. Nothing downstream depends on the coordinator recalling that a cleanup happened.
+
+- **Do NOT distinguish "applied changes" from "healthy no-op"** — both count as a run, so both emit. Put the distinction in `mode`, never in whether you emit.
+- **Do NOT hand-append to `events.jsonl`.** Route through `emit-event.mjs` → `emitEvent()`; hand-rolled appenders drift from the canonical record shape (the `stop` vs `orchestrator.session.stopped` divergence, #609).
+- **`semantic_session_id` is the semantic id** (`main-2026-08-17-session-1`), not the UUID — `sessions.jsonl` `session_id` lives in that same space, and the matcher compares against it. Omitting the field is tolerated (the event is then claimed on the time window alone), but supplying it is what makes attribution exact when two sessions overlap.
+- **An explicit `memory_cleanup_at` already on the record WINS** over derivation and is never overwritten. That path exists for backfills and tests, not for normal operation.
+
+**Why this is mechanical and not a prose instruction:** it used to be one. On 2026-08-14 a `/memory-cleanup` ran and produced a documented yield, the coordinator did not execute the prose step, and all three session records of that day carried `memory_cleanup_at: null` — so the session-start banner reported "last cleanup 29 days ago" while the operator's own notes said 3. `stampMemoryCleanup()` had zero production callers at the time; every reference to it was an instruction asking an LLM to remember. Same failure class as the STATE.md write-race that Epic #583 replaced with a lock: Disziplin statt Mechanik.
 
 ## Anti-Patterns
 

package/skills/npm-publish/SKILL.md

@@ -2,12 +2,14 @@
 name: npm-publish
 user-invocable: true
 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, leakage-gate greps before every publish, post-publish verification and marker/badge upkeep. Trigger on "publish to npm", "npm release", "E403 publish error".
+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".
 ---
 
-# npm-publish — Token-based publish runbook
+# npm-publish — token auth, and the calls the script cannot make
 
-> Companion to `docs/distribution/npm-publish-checklist.md` (the original 7-step operator runbook). This skill adds the token-auth mechanics and the failure-mode diagnosis learned during the v3.16.0 first publish (2026-07-19).
+> **The release itself is `/release` → `scripts/release.mjs`.** That script mechanizes the whole sequence: version surfaces, CHANGELOG gate, drift sweep, tag/registry collision, CI, leakage gate, publish, tag-after-publish, push to both remotes, live-site poll. This skill does not restate it.
+>
+> What lives here is the half a script cannot own: the **token setup**, the **auth failure diagnosis**, and the **judgement calls** — which version, what a leak means, when to abort rather than repair.
 
 ## Why this skill exists
 
@@ -24,60 +26,20 @@ Create at https://www.npmjs.com/settings/<user>/tokens → Generate New Token
 
 ## Auth resolution order
 
-1. `NPM_TOKEN` in `.env.local` at the repo root (gitignored — verify with `git check-ignore .env.local` before writing; also confirm no `.env` pattern in the `files` whitelist of package.json).
+1. `NPM_TOKEN` in `.env.local` at the repo root (gitignored — verify with `git check-ignore .env.local` before writing; also confirm no `.env` pattern in the `files` whitelist of package.json). `scripts/release.mjs` refuses to read the token if that ignore check fails.
 2. Interactive fallback: operator runs `npm publish --access public` in a real terminal (only works when account 2FA is enrolled — OTP prompt appears).
 
 **Never** put the token in the tracked `.npmrc` (it holds `ignore-scripts=true` per SEC-020 and is committed), never persist it into `~/.npmrc`, never echo it into logs.
 
-## Canonical path: `scripts/release.mjs` (Release als ein Dispatch, #978)
+## The three judgement calls
 
-Since v3.19.0 the release is ONE dispatch — the script mechanizes every step below plus the
-version-surface sync this skill previously left to operator memory (the gap that let v3.18.0
-ship tagged but unpublished):
+The script gates mechanics. These three are yours, and it will not make them for you.
 
-```bash
-node scripts/release.mjs --set-version X.Y.Z   # rewrite all 12 version literals (10 files) + codex cachebuster + lock sync
-# … author CHANGELOG entry + README highlights (enforced by --check) …
-node scripts/release.mjs --check               # preflight: surfaces, CHANGELOG, tag/registry collision, CI green, leakage gate
-node scripts/release.mjs --publish             # token publish → registry verify → tag AFTER publish → push origin+github
-```
+**1. Which version is the right one.** Semver per `.claude/rules/development.md` § Package Lifecycle & Versioning: patch = fixes/docs/internal refactor; minor = additive and backwards-compatible; major = removed or renamed exports, or changed runtime behaviour — and a major never merges without a migration guide and a `BREAKING CHANGE:` footer. The script validates the *shape* `X.Y.Z` and nothing about whether the number matches the diff. Read the CHANGELOG entry you just wrote and ask whether a consumer pinning `^` would be broken by it; if yes, the bump is a major regardless of how small the diff looks.
 
-The tag is created only AFTER a registry-verified publish — never before. The manual flow
-below remains as the fallback and as documentation of what the script does.
+**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.
 
-## Publish flow (manual fallback)
-
-```bash
-# 1. Pre-flight (first publish: expect E404 = name free; upgrade: expect the previous version)
-npm view session-orchestrator version
-
-# 2. Leakage gate — every grep MUST print 0 (from docs/distribution/npm-publish-checklist.md)
-npm pack --dry-run 2>&1 | grep -cE "npm notice.* tests/"
-npm pack --dry-run 2>&1 | grep -c "npm notice.*\.orchestrator/"
-npm pack --dry-run 2>&1 | grep -cE "npm notice.*[[:space:]]\.claude/"
-npm pack --dry-run 2>&1 | grep -c "npm notice.*\.github/"
-npm pack --dry-run 2>&1 | grep -c "node_modules"
-npm pack --dry-run 2>&1 | grep -ci "\.env"
-npm pack --dry-run 2>&1 | grep -ci "owner\.yaml"
-
-# 3. Publish via temp userconfig (never a persistent npmrc)
-NPM_TOKEN=$(grep '^NPM_TOKEN=' .env.local | cut -d= -f2-)
-TMPRC=$(mktemp) && printf '//registry.npmjs.org/:_authToken=%s\n' "$NPM_TOKEN" > "$TMPRC" && chmod 600 "$TMPRC"
-npm publish --access public --userconfig "$TMPRC"; rm "$TMPRC"
-
-# 4. Verify
-npm view session-orchestrator version   # must print the new version
-```
-
-Success marker: `+ session-orchestrator@<version>` on the publish output.
-
-## Post-publish checklist
-
-1. **Verify registry**: `npm view session-orchestrator version dist.unpackedSize keywords` — `pi-package` keyword must be present.
-2. **pi.dev gallery**: indexing is asynchronous — check https://pi.dev/packages later; do not block on it.
-3. **Marker upkeep** (first publish only — done in v3.16.0): README install matrix + npm badge, `site/index.html` install section, `docs/pi-setup.md` availability paragraph.
-4. **Rotate/delete the token** at https://www.npmjs.com/settings/<user>/tokens once the release is done — especially if the token value ever transited chat, a screenshot, or any log. A token pasted into a conversation is burned: rotate immediately after use.
-5. Update the release issue / CHANGELOG if the publish was part of a tracked release.
+**3. When to abort instead of repair.** Abort — do not patch forward — when the failure is upstream of the publish: a red preflight row, a lagging `github` mirror, CI not green on the exact commit, a dead token. These are cheap to fix and re-run from the top. Repair-in-place is only ever appropriate *after* a verified publish, where the version is already immutable: a missing GitHub release or a lagging site deploy can be reconciled, because npm already has the correct artifact. The dividing line is whether the registry has accepted the tarball — before that point, restart; after it, reconcile. `commands/release.md` § Abort criteria is the operative list.
 
 ## Failure-mode table
 
@@ -85,13 +47,23 @@ Success marker: `+ session-orchestrator@<version>` on the publish output.
 |---|---|---|
 | `E403 ... Two-factor authentication or granular access token with bypass 2fa enabled is required` — no OTP prompt | Account has no 2FA enrolled AND token (if any) lacks Bypass-2FA | Create granular token with all four requirements above, or enroll 2FA |
 | Same E403 despite a fresh token | Token created without the Bypass-2FA checkbox, or Read-only, or package-scoped on a first publish | Re-create: RW + All packages + Bypass-2FA |
+| `npm whoami` silent or non-zero | Token expired, or `.env.local` missing | Re-create the token; do not proceed — the preflight fails this row on purpose |
 | `E404` on `npm view` after publish | Registry propagation (rare, seconds) or publish actually failed | Re-check the publish output for `+ <name>@<version>` |
 | `ENEEDAUTH` | No login/token at all | Token flow above, or `npm login` |
 | OTP prompt appears but flow is non-interactive (`!`-prefix, script) | No TTY for the prompt | Use the token flow, or a real terminal |
 
+## Post-publish — the human half
+
+`--publish` verifies the registry and polls the live site itself, and prints the rest. What still needs a person:
+
+1. **Rotate/delete the token** at https://www.npmjs.com/settings/<user>/tokens. A token that ever transited a conversation, a screenshot, or any log is burned — rotate immediately.
+2. **pi.dev gallery**: indexing is asynchronous — check https://pi.dev/packages later; do not block on it.
+3. **Marker upkeep** on a first publish only (done in v3.16.0): README install matrix + npm badge, `site/index.html` install section, `docs/pi-setup.md` availability paragraph.
+4. Update the release issue if the publish was part of tracked work.
+
 ## Security invariants
 
 - `.env.local` is gitignored AND absent from the npm `files` whitelist — verify both before writing a token into it.
-- Temp userconfig: `chmod 600`, deleted immediately after publish.
+- Temp userconfig: `chmod 600`, deleted in a `finally` block immediately after publish.
 - The leakage gate runs before EVERY publish, not only the first.
 - npm's own recommendation for unattended CI/CD is **Trusted Publishing** (OIDC) — evaluate it if publishing ever moves into CI (ref: https://docs.npmjs.com/about-access-tokens).

package/skills/persona-panel/SKILL.md

@@ -40,7 +40,9 @@ catalog rather than referencing the plugin copy in place.
 Install:
 ```bash
 mkdir -p .claude/personas
-cp "$(claude plugin dir session-orchestrator)/skills/persona-panel/presets/"*.md .claude/personas/
+# Claude Code has no `plugin dir` subcommand — resolve the install path from the cache.
+SO_DIR="$(dirname "$(find ~/.claude/plugins/cache -path '*session-orchestrator*' -name package.json 2>/dev/null | head -1)")"
+cp "$SO_DIR/skills/persona-panel/presets/"*.md .claude/personas/
 ```
 
 ## Phase 0: Bootstrap Gate

package/skills/plan/mode-new.md

@@ -38,7 +38,7 @@ Agent({ subagent_type: "Explore", description: "Check ecosystem for conflicts",
 3. **Target audience** — Options informed by market research agent. User selects or provides custom.
 4. **User-Story-Schicht** — "User-Story-Schicht für dieses Feature erzeugen?" Immer fragen (kein Audience-Heuristik-Gate). Drei Antwortoptionen: **Ja (Als/möchte/damit)** — klassische Persona-Story-Form; **Ja (job-story)** — job-story-Form ("When [situation], I want [motivation], so I can [outcome]"); **Nein** — byte-identisches Status-quo-Verhalten. Bei einer der beiden "Ja"-Optionen emittiert die PRD eine optionale ## User Stories Sektion (je Story ein ↳ AC-Pointer) in der gewählten Form; bei "Nein" wird die Sektion vollständig weggelassen.
 5. **Core problem being solved** — Open-ended. Claude suggests structure if answer is vague.
-6. **GitLab group** — Discover available groups dynamically. Run `ls $BASELINE_PATH/templates/` for project types, and check for a groups config in `$BASELINE_PATH/config/` or use `glab group list` to discover GitLab groups. Present findings via AskUserQuestion.
+6. **GitLab group** — Discover available groups dynamically. Run `ls $BASELINE_PATH/templates/` for project types, and check for a groups config in `$BASELINE_PATH/config/` or run `glab api "groups?per_page=100&min_access_level=10"` to discover GitLab groups — read each entry's `full_path` field. (`glab` has no `group` subcommand at all — invoking one exits 1 with `Unknown command "group"`.) Present findings via AskUserQuestion.
 
 ### Wave 2 — Technical Details (5 questions, dynamic per archetype)
 
@@ -129,6 +129,11 @@ Map gathered answers to script input choices:
 # 4. Map user's selected style name → numeric choice for STYLE_CHOICE (if applicable)
 # 5. Map user's selected group name → numeric choice for GROUP_CHOICE
 # Do NOT hardcode numeric mappings — they must be derived from the script.
+#
+# GROUP_CHOICE is a MENU INDEX, never a namespace. Keep the group's real
+# namespace in a separate variable — every later step addresses the project as
+# "<group-path>/<project>", and a numeric index there silently targets nothing.
+GROUP_PATH="$(...)"    # e.g., "products" — the full_path of the chosen group
 (
   echo "$TYPE_CHOICE"    # e.g., "1" for nextjs-saas
   echo "$STYLE_CHOICE"   # e.g., "1" for vega (only if nextjs-saas)
@@ -143,7 +148,7 @@ Map gathered answers to script input choices:
 Check exit code. Confirm repo exists:
 
 ```bash
-glab repo view $GROUP/$PROJECT_NAME
+glab repo view "$GROUP_PATH/$PROJECT_NAME"
 ```
 
 ### Step 3: Adjust visibility
@@ -151,9 +156,22 @@ glab repo view $GROUP/$PROJECT_NAME
 If visibility is not `internal` (the default):
 
 ```bash
-glab repo edit --visibility private   # or --visibility public
+# There is no `glab repo edit`, and `glab repo update` carries no --visibility
+# flag (its FLAGS are --archive/--defaultBranch/-d/--description). Go through the
+# API, addressing the project by its URL-encoded path — `projects/:id` resolves
+# from the CWD remote, which is the wrong project right after scaffolding.
+ENCODED="${GROUP_PATH}%2F${PROJECT_NAME}"
+glab api -X PUT "projects/${ENCODED}" -f visibility=private   # or visibility=public
+
+# Verify (this GET is the read-only proof the PUT landed). Note `glab api` has
+# no --jq flag — that is `gh api`'s. Pipe to jq instead.
+glab api "projects/${ENCODED}" | jq -r '.visibility'
 ```
 
+> The GET path above is verified against glab 1.91.0; the PUT is the documented
+> GitLab API shape but was **not** executed during authoring (write operations
+> were out of scope). Confirm with the GET before relying on it.
+
 For public/OSS, also configure GitHub mirror if applicable.
 
 ### Step 4: Set branch protection
@@ -274,11 +292,11 @@ Use AskUserQuestion to present the full issue structure:
 
 ```bash
 # Create epic
-glab issue create --title "$EPIC_TITLE" --description "$EPIC_DESC" \
+glab issue create -R "$GROUP_PATH/$PROJECT_NAME" --title "$EPIC_TITLE" --description "$EPIC_DESC" \
   --label "type:epic,priority::$PRIORITY" --milestone "$MILESTONE"
 
 # Create sub-issues
-glab issue create --title "$ISSUE_TITLE" --description "$ISSUE_DESC" \
+glab issue create -R "$GROUP_PATH/$PROJECT_NAME" --title "$ISSUE_TITLE" --description "$ISSUE_DESC" \
   --label "type:feature,priority::$PRIORITY,status:ready,area:$AREA,appetite:$APPETITE"
 ```
 

package/skills/repo-audit/SKILL.md

@@ -1,6 +1,15 @@
 ---
 name: repo-audit
-description: Use this skill when the user wants to audit a repository for baseline compliance, check code quality, security posture, CI/CD setup, testing, documentation, and ecosystem configuration. Runs 9 checklist categories and emits a Markdown report plus JSON sidecar at .orchestrator/metrics/repo-audit-<timestamp>.json. <example>Context: User is in a project repo and wants a baseline compliance check. user: "/repo-audit" assistant: "Running repo-audit across 9 categories — Configuration, Code Quality, Git Hygiene, CI/CD, Testing, Security, Documentation, Clank Integration (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>
+description: >
+  Use this skill when the user wants to audit a repository for baseline compliance, check code quality,
+  security posture, CI/CD setup, testing, documentation, and ecosystem configuration. Runs 9 checklist
+  categories and emits a Markdown report plus JSON sidecar at
+  .orchestrator/metrics/repo-audit-<timestamp>.json. <example>Context: User is in a project repo and wants
+  a baseline compliance check. user: "/repo-audit" assistant: "Running repo-audit across 9 categories —
+  Configuration, Code Quality, Git Hygiene, CI/CD, Testing, Security, Documentation, Clank Integration
+  (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>
 model: inherit
 color: cyan
 ---

package/skills/session-end/SKILL.md

@@ -780,11 +780,53 @@ git push origin HEAD
 ```
 
 ### 4.4 GitHub Mirror (if configured in Session Config)
+
+Three states, three DISTINGUISHABLE outcomes. The predecessor of this block
+(`git remote get-url github 2>/dev/null && git push github HEAD 2>/dev/null || echo "GitHub mirror: not configured"`)
+collapsed a **failed push** into `GitHub mirror: not configured` and exited 0 — git's real
+error went to `/dev/null`, so a broken mirror was indistinguishable from an unconfigured one
+(`.claude/rules/bash-harness-pitfalls.md` — "Silence is not success"). That matters more once
+anything is wired to the mirror (e.g. a Vercel Git deploy): a silently-failing push means the
+downstream artifact never updates and nobody is told.
+
+Run it verbatim — `tests/skills/session-end/github-mirror-push.test.mjs` extracts the block
+between the markers and executes it, so no second copy of this command may exist.
+
 ```bash
-# Only attempt if 'mirror: github' is in Session Config AND remote exists
-git remote get-url github 2>/dev/null && git push github HEAD 2>/dev/null || echo "GitHub mirror: not configured"
+# --- github-mirror-push:begin ---
+# Only attempt if 'mirror: github' is in Session Config.
+# State 0: not a git repository at all → loud WARN, exit 1. This state was MISSED
+#          in the first version and is the reason it is listed first now: outside
+#          a repo, `git remote get-url` fails with "fatal: not a git repository",
+#          which is indistinguishable from "no such remote" by exit code alone.
+#          The block then announced "no 'github' remote configured — skipping
+#          (not an error)" and exited 0 — fail-open, in the very fix written to
+#          close a fail-open. Found by an adversarial reviewer, not by the author.
+# State 1: no 'github' remote      → informational, exit 0 (legitimate for consumer repos)
+# State 2: push succeeded          → confirmation WITH the pushed SHA, exit 0
+# State 3: push FAILED             → loud WARN on stderr WITH git's real output, exit 1
+if ! git_dir=$(git rev-parse --git-dir 2>&1); then
+  echo "WARN GitHub mirror: not a git repository — cannot mirror anything." >&2
+  echo "  git said: ${git_dir}" >&2
+  exit 1
+elif ! mirror_url=$(git remote get-url github 2>&1); then
+  echo "GitHub mirror: no 'github' remote configured — skipping (not an error)."
+  echo "  git said: ${mirror_url}" >&2
+elif push_out=$(git push github HEAD 2>&1); then
+  echo "GitHub mirror: pushed $(git rev-parse HEAD) -> ${mirror_url}"
+else
+  echo "WARN GitHub mirror PUSH FAILED: $(git rev-parse HEAD) is NOT on ${mirror_url}" >&2
+  echo "${push_out}" >&2
+  echo "WARN Mirror is stale — anything wired to it (site deploy) will not update." >&2
+  exit 1
+fi
+# --- github-mirror-push:end ---
 ```
 
+State 3 exits non-zero on purpose: it is the only machine-readable signal that the mirror is
+behind. Report it to the operator in the session summary; do not retry silently and do not
+swallow it with `|| true`.
+
 ## Phase 4a: Auto-Promoted Worktree Cleanup (#575 P3.2)
 
 > Skip if `persistence: false` in Session Config. Skip silently if the current worktree is NOT an Auto-promoted sibling (the common case).

package/skills/session-end/metrics-collection.md

@@ -185,4 +185,4 @@ Finalize session metrics by reading the wave data accumulated during execution:
 > - `open_questions_asked` / `open_questions_answered` / `open_questions_deferred` (#773): the three open-question counts from the Phase 1.65 gate's AUQ Call 2 (identical to the `questions_*` payload fields on the `orchestrator.handover.gated` event). Top-level, additive, non-negative integers. Populate ONLY when the gate ran an interactive triage ("Closen + Triage" path). OMIT all three (do NOT write `0`) when the gate was skipped (fail-open / headless / disabled) or took the fast-path — absent = "not measured", `0` = "measured, zero questions". Validator accepts absent/null/non-negative-integer.
 > - `stagnation_events`: populated ONLY when ≥1 stagnation event was logged to `events.jsonl` during this session. When `total == 0`, the field is omitted from the JSONL entry.
 > - `grounding_injections`: populated ONLY when ≥1 `orchestrator.grounding.injected` event was logged to `events.jsonl` during this session. When `count == 0`, the field is omitted from the JSONL entry.
-> - `memory_cleanup_at`: populated whenever `/memory-cleanup` ran **THIS session** in ANY mode — dry-run, apply-pending, OR healthy no-op (MEMORY.md already healthy, no files mutated). Set `memory_cleanup_at = completed_at` so the auto-dream cadence marker (`readDreamSignals` → `lastCleanupAt`) advances and `shouldDispatchAutoDream` does not fire a false nudge. **A no-op is still a cleanup; the cadence marker MUST advance.** Use `stampMemoryCleanup(record, { ranCleanup: true, completedAt: record.completed_at })` from `scripts/lib/memory-cleanup-stamp.mjs` — this is the testable, no-throw seam that applies the stamp. Omit the field (do NOT set it to null) when `/memory-cleanup` did not run this session. (#699)
+> - `memory_cleanup_at`: **derived by the writer, not supplied by the coordinator.** `scripts/emit-session.mjs` sets it to `completed_at` whenever an `orchestrator.memory.cleanup_completed` event for THIS session sits in `events.jsonl` — emitted by every `/memory-cleanup` run in ANY mode (dry-run, apply-pending, OR healthy no-op). **A no-op is still a cleanup; it still emits, so the cadence marker (`readDreamSignals` → `lastCleanupAt`) still advances and `shouldDispatchAutoDream` does not fire a false nudge.** No event → field absent (never `null`). An explicit value already on the record wins and is not overwritten. Do NOT hand-call `stampMemoryCleanup()` here — the coordinator-supplied-boolean form was removed on 2026-08-17 after it silently failed for a real cleanup on 2026-08-14. (#699)