session-orchestrator 3.20.0 → 3.22.0

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

@@ -0,0 +1,43 @@
+---
+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.
+model: inherit
+tools: Read, Grep, Glob, Bash
+---
+
+# eli5
+
+Say it again in plain words. Same facts, in the order he needs them.
+
+## The frame
+
+**Write for someone who knows this project but has not seen what you just saw.**
+
+He owns this repo. He is not missing knowledge, he is missing observation — he did not watch the command run or read the file it points at. Write across, not down. `.claude/rules/ask-via-tool.md` § AUQ-006 and `skills/session-start/soul.md` § Register are the canonical statement of this register; apply them, do not restate them.
+
+## What to restate
+
+- `/eli5` — my last substantial output in this conversation. If there is none yet, say so instead of inventing a topic.
+- `/eli5 <topic>` — that topic (`$ARGUMENTS`), grounded in what THIS session already measured: name the file, command, or record it came from. If it was never measured here, say that rather than filling the gap from memory.
+
+Answer in the operator's language: `owner.language` in `~/.config/session-orchestrator/owner.yaml`, falling back to `en` when that file is missing, unreadable, or the key is absent — and follow the operator's own language the moment he writes in another one.
+
+## Two limits, and they are the whole skill
+
+**1. Say more simply what actually happens — introduce nothing that does not exist.**
+Test: delete every noun the system does not contain. Sentence still true and complete → it was no analogy. Sentence collapses → describe what actually happens instead.
+✓ "Waiting means the other session finishes first." ✗ "Think of the session as a level crossing."
+
+**2. Simplifying removes words, never facts.** If a path, a number, an error code, an identifier, or an instruction to act disappears, that is data loss, not simplification. The mechanical decider: **could the token you are about to cut ever appear in a `grep`? Then it stays.** `skills/session-start/soul.md` § "Never traded for brevity" outranks every brevity instruction in this file.
+
+## Shape
+
+Line 1 answers the question he actually has: **do I have to do something now, and what happens if I don't?** Then the facts, in the order he needs them — not the order you found them.
+
+This is a terminal, so there is no picture to draw. The second channel is the `preview` field on an `AskUserQuestion` option: when the options differ in something literal — a diff, a title, a config block, a file list — put that text there and he reads the thing instead of a description of it.
+
+## What this is not
+
+- **Not shorter by default.** Eight lines before may be eight lines after. Reorder first; cut only filler.
+- **Not a children's explanation.** The label is a poster, the reader is an expert who was not in the room.
+- **Not a second attempt at the answer.** If the first answer was wrong, fix the answer — `/eli5` restates, it never re-derives.

package/skills/evolve/SKILL.md

@@ -248,8 +248,8 @@ Present extracted patterns to the user for confirmation. Use AskUserQuestion wit
 ```
 AskUserQuestion({
   questions: [{
-    question: "Which learnings should be saved?\n\nExtracted patterns from session history:",
-    header: "Evolve — Confirm Learnings",
+    question: "Which of the patterns extracted from this session's history should be saved?",
+    header: "Speichern?",
     options: [
       {
         label: "[type] subject",
@@ -455,19 +455,18 @@ Use AskUserQuestion with options:
 AskUserQuestion({
   questions: [{
     question: "What would you like to do with your learnings?",
-    header: "Evolve — Review",
+    header: "Learnings",
     options: [
-      { label: "Boost confidence", description: "Select learnings to boost (+0.15)" },
-      { label: "Reduce confidence", description: "Select learnings to reduce (-0.2)" },
-      { label: "Delete specific learnings", description: "Select learnings to remove" },
-      { label: "Extend expiry", description: "Reset expires_at by learning-expiry-days from now" },
-      { label: "Done — no changes", description: "Exit without changes" }
+      { label: "Confidence ändern", description: "Pick the learnings, then the direction: +0.15 or -0.2. Cheapest fix when a learning is merely mis-weighted." },
+      { label: "Ablauf verlängern", description: "Keeps a still-useful learning alive: its expiry date moves to today plus the configured window. Confidence is untouched." },
+      { label: "Delete specific learnings", description: "Takes the selected learnings out of the store. They are archived rather than shredded, but they stop influencing anything." },
+      { label: "Done — no changes", description: "Leaves the store exactly as it is and ends the review. Nothing is written." }
     ]
   }]
 })
 ```
 
-If user selects "Boost confidence", "Reduce confidence", "Delete specific learnings", or "Extend expiry", present a follow-up AskUserQuestion with `multiSelect: true` listing all learnings by `# | type | subject` so the user can select which ones to modify.
+If user selects "Confidence ändern", "Ablauf verlängern", or "Delete specific learnings", present a follow-up AskUserQuestion with `multiSelect: true` listing all learnings by `# | type | subject` so the user can select which ones to modify. For "Confidence ändern" the same follow-up also asks for the direction — **Boost** (+0.15) or **Reduce** (-0.2). Both operations are unchanged; only the point at which the direction is chosen moved, because a single AskUserQuestion accepts at most 4 options and the previous list had 5.
 
 > On Codex CLI where AskUserQuestion is unavailable, present as a numbered Markdown list.
 

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
+  paths 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
@@ -37,7 +45,7 @@ syntax inline. This skill is the single source of truth for all VCS operations.
 When a skill needs VCS operations, include this reference block in its instructions:
 
 > **VCS Reference:** Detect the VCS platform per the "VCS Auto-Detection" section of the gitlab-ops skill.
-> Use CLI commands per the "Common CLI Commands" section. For cross-project queries, see "Dynamic Project Resolution."
+> Use CLI commands per the "Common CLI Commands" section. For GitLab API operations, see "Canonical Project Identity."
 
 **Canonical commands:** All `glab` and `gh` command syntax — flags, output formats,
 pagination options — is defined in the "Common CLI Commands" section below. Consuming
@@ -49,34 +57,35 @@ command variant not listed there, add it to this file first, then reference it.
 - Any skill-specific *parameters* they pass to commands (e.g., label names, issue templates)
 - They should NOT include raw `glab`/`gh` invocations or detection snippets
 
-## Dynamic Project Resolution
+## Canonical Project Identity
 
-Never hardcode project IDs. Resolve them at runtime — and re-resolve live each session; never cache a project ID across sessions (a stale ID silently targets the wrong project on rename/fork/mirror-drift, and is the root cause behind the close-verification incident documented below).
+GitLab REST endpoints accept a URL-encoded `namespace/project` path. Select the GitLab host and project path explicitly; never derive a numeric project ID from `glab repo view`, search `projects?search=`, or use `:id` placeholders. Those forms can resolve through the ambient working directory or a stale search result and target another project after a rename, fork, or scaffold.
 
-### Current project
+Set the identity once per operation sequence and reuse the encoded identifier without encoding it again:
 
 ```bash
-# GitLab — get numeric project ID
-glab repo view --output json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])"
+GITLAB_HOST="<selected GitLab hostname>"
+GROUP_PATH="<selected group path>"
+PROJECT_NAME="<selected project name>"
+PROJECT_PATH="$GROUP_PATH/$PROJECT_NAME"
+ENCODED_PROJECT_PATH="$(node -e 'process.stdout.write(encodeURIComponent(process.argv[1]))' "$PROJECT_PATH")"
+```
 
-# GitHub — get owner/name identifier
-gh repo view --json nameWithOwner -q '.nameWithOwner'
+For a link target in another project, use the same path-first shape instead of a numeric ID:
+
+```bash
+TARGET_PROJECT_PATH="<target namespace>/<target project>"
+TARGET_ENCODED_PROJECT_PATH="$(node -e 'process.stdout.write(encodeURIComponent(process.argv[1]))' "$TARGET_PROJECT_PATH")"
 ```
 
-### Cross-project queries
+Pass `--hostname "$GITLAB_HOST"` to every `glab api` call. The endpoint itself then pins the project, including directly after creating a repository when the current directory does not yet identify the new project.
 
-When a skill needs to reference other projects (e.g., from `cross-repos` in Session Config):
+GitHub continues to use an `owner/repo` slug; `gh repo` takes it positionally and rejects `-R`:
 
 ```bash
-# GitLab — resolve project ID by name
-glab api "projects?search=<project-name>" | python3 -c "import json,sys; [print(p['id'], p['path_with_namespace']) for p in json.load(sys.stdin)]"
-
-# GitHub — resolve repo details
-gh api "repos/<owner>/<name>" --jq '.full_name'
+gh repo view --json nameWithOwner -q '.nameWithOwner'
 ```
 
-**Note:** Some API calls require numeric project IDs (GitLab) or `owner/repo` slugs (GitHub). Always resolve dynamically from the project name.
-
 ### Canonical enumeration pattern
 
 To enumerate ALL projects (or issues) in a group, a single page is never the whole result — paginate and guard against silent truncation:
@@ -85,7 +94,7 @@ To enumerate ALL projects (or issues) in a group, a single page is never the who
 # GitLab — paginate a group's projects, following x-next-page until empty
 page=1
 while [ -n "$page" ]; do
-  resp=$(glab api "groups/<group-id>/projects?include_subgroups=true&per_page=100&page=$page" --include)
+  resp=$(glab api --hostname "$GITLAB_HOST" "groups/<group-id>/projects?simple=true&include_subgroups=true&per_page=100&page=$page" --include)
   # parse the response body ($resp) for project ids/paths here, deduping by id.
   # Then advance by reading the `x-next-page` response header — an empty value
   # means this was the last page, so the loop exits (the guard above is what breaks).
@@ -138,13 +147,16 @@ done
 
 ## Issue Linking (`blocks` / `is_blocked_by`)
 
-GitLab's native issue-link types `blocks` and `is_blocked_by` (`glab api -X POST projects/:id/issues/:issue_iid/links -f link_type=blocks|is_blocked_by`) are a **Premium/Ultimate license feature**. On a Free/Core-tier GitLab instance this call returns **HTTP 403** — a license-gate signal, not an auth/permission failure. Do not retry with different credentials or escalate as an auth bug.
+GitLab's native issue-link types `blocks` and `is_blocked_by` (`glab api --silent --hostname "$GITLAB_HOST" -X POST "projects/${ENCODED_PROJECT_PATH}/issues/${ISSUE_IID}/links" -f target_project_id="$TARGET_ENCODED_PROJECT_PATH" -f target_issue_iid="$OTHER_ISSUE_IID" -f link_type="$LINK_TYPE"`) are a **Premium/Ultimate license feature**. Set `LINK_TYPE` to `blocks` or `is_blocked_by`; the target accepts an encoded project path, so no numeric project ID is needed. On a Free/Core-tier GitLab instance this call returns **HTTP 403** — a license-gate signal, not an auth/permission failure. Do not retry with different credentials or escalate as an auth bug.
 
 **Fallback (non-Premium instances):**
 1. **Use `relates_to` instead** — `link_type=relates_to` is available on every GitLab tier (no ordering semantics, just an unscoped relation). Same API shape, only the `link_type` value changes:
    ```bash
-   glab api -X POST "projects/:id/issues/:issue_iid/links" \
-     -f target_project_id=:id -f target_issue_iid=:other_iid -f link_type=relates_to
+   glab api --silent --hostname "$GITLAB_HOST" -X POST \
+     "projects/${ENCODED_PROJECT_PATH}/issues/${ISSUE_IID}/links" \
+     -f target_project_id="$TARGET_ENCODED_PROJECT_PATH" \
+     -f target_issue_iid="$OTHER_ISSUE_IID" \
+     -f link_type=relates_to
    ```
 2. **Document the blocking semantics in the issue body** — since `relates_to` carries no ordering meaning, add an explicit ordering note to both issues, e.g. `⚠ Ordering: erst #<blocker_iid>, dann dieses Issue — blocks-Link nicht verfügbar (non-Premium)`.
 3. **Recognize the 403 as a license signal, not an auth error** — before assuming a token/scope problem, try `relates_to` on the same project pair: if `relates_to` succeeds where `blocks`/`is_blocked_by` 403s, the license gate — not authentication — is the cause.
@@ -153,38 +165,40 @@ 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 encoded endpoint and explicit host identify the target)
+glab api --hostname "$GITLAB_HOST" "projects/${ENCODED_PROJECT_PATH}/issues?state=opened&per_page=50"
+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`.
 
-**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/wrong project ID or a silent 404 can report local success while closing nothing; a documented incident closed 32 issues into the void this way (project ID pointed at the wrong project — see "Dynamic Project Resolution" above for the re-resolve-each-session rule that prevents it).
+**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.
 
 **Commit-body close-keyword footgun:** GitLab (and GitHub) auto-close an issue when a commit pushed to the default branch contains a close keyword — `close`/`closes`/`closed`/`fix`/`fixes`/`fixed`/`resolve`/`resolves`/`resolved` — followed by `#N` ANYWHERE in the commit body, not just the subject line. This fires even inside a negation ("does NOT close #N") — the platform pattern-matches the keyword + issue reference; it does not parse English negation, so the negation offers no protection. Rule: when a commit body needs to MENTION an issue without closing intent, always use a non-closing reference — `refs #N`, `part of #N`, `siehe #N` — never a close-keyword verb next to the number, negated or not.
 
@@ -194,27 +208,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 +381,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/grill/SKILL.md

@@ -66,7 +66,7 @@ Walk the decision tree **one question at a time**. For each branch, in order:
 AskUserQuestion({
   questions: [{
     question: "Your code cancels whole Orders, but the PRD says a customer can cancel one line item. Which is the real model?",
-    header: "Cancellation Scope",
+    header: "Cancel scope",
     options: [
       { label: "Line-item cancellation (Recommended)", description: "Matches the PRD intent. Cost: new partial-refund path + Order stays open after one item is voided." },
       { label: "Whole-order only", description: "Matches today's code. Cost: contradicts the stated user story — re-scope the PRD." },
@@ -118,12 +118,12 @@ Per the user's configured behaviour, the grill ends with a hand-off and an OPTIO
 AskUserQuestion({
   questions: [{
     question: "Grill complete. How do you want to proceed?",
-    header: "Grill Hand-off",
+    header: "Hand-off",
     options: [
-      { label: "Write grill summary + hand off to /plan feature (Recommended)", description: "Persist resolved decisions to docs/specs/, then formalize into a PRD." },
-      { label: "Write grill summary only", description: "Keep the resolved decisions as a reference; no further step now." },
-      { label: "Hand off to /plan feature — no file", description: "Carry the resolved decisions straight into planning; nothing persisted." },
-      { label: "Done — no file, no hand-off", description: "The grilling itself was the value; leave no artifact." }
+      { label: "Summary + /plan feature (Recommended)", description: "Writes the resolved decisions to docs/specs/ (a folder of markdown notes), then hands them to planning. Cost: one file." },
+      { label: "Write grill summary only", description: "Same file, no planning step. The decisions keep, so you can hand them off later." },
+      { label: "Hand off to /plan feature — no file", description: "Carries the decisions straight into planning. They then live only in this conversation." },
+      { label: "Done — no file, no hand-off", description: "The grilling itself was the value. Nothing is written, nothing is handed on." }
     ],
     multiSelect: false
   }]

package/skills/grill/soul.md

@@ -76,6 +76,22 @@ This is the tightest of the orchestrator's budgets by design. A turn is structur
 - Shape: explain which tactic you are applying and why it bites here, name the branches of the decision tree you are deferring, define unfamiliar terms on first use.
 - Escalation: `expand <topic>` — see § Escalation above.
 
+### Register — how a sentence reads
+
+The budgets above set *how much* you say; the register sets *how*. It is
+defined once, in `skills/session-start/soul.md` § "Register — how a sentence
+reads", and binds here unchanged: the frame ("write for someone who knows this
+project but has not seen what you just saw"), the plain-words test with its
+five worked cases, and its precedence over § "Never traded for brevity" above.
+Read it there. It is not repeated here on purpose — the § Output Levels intro
+sentence already exists in four copies across the four souls with nothing
+checking their parity, and a fifth copied rule would drift the same way. A
+pointer cannot.
+
+Note the one place register and adversarial posture meet: a challenge is
+plainer, never softer. "Say it more simply" never becomes "say it less
+sharply" — the contradiction still lands, in shorter words.
+
 ### Companion dials
 
 Same file, same lookup, same fallback-to-default rule:

package/skills/memory-cleanup/SKILL.md

@@ -246,8 +246,8 @@ const peerWarning = wt.activePeer
 
 AskUserQuestion({
   questions: [{
-    question: `Stale auto-promoted worktree found: ${path.basename(wt.wtPath)} (age ${ageDays}d, branch=${wt.branch}).${peerWarning} Remove?`,
-    header: "Stale-Worktree",
+    question: `Auto-promoted worktree ${path.basename(wt.wtPath)} is ${ageDays}d old (branch ${wt.branch}).${peerWarning} Remove?`,
+    header: "Worktree",
     multiSelect: false,
     options: [
       {
@@ -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, the target-confirmed npm receipt boundary, tag-after-receipt, push to both remotes, GitHub-release handling, and 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 target-confirmed npm receipt: a red preflight row, a lagging `github` mirror, CI not green on the exact commit, 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.
 
 ## 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 |
-| `E404` on `npm view` after publish | Registry propagation (rare, seconds) or publish actually failed | Re-check the publish output for `+ <name>@<version>` |
+| `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 a target-confirmed publish receipt | Registry propagation (rare, seconds) | Let the script finish its tag/push/GitHub/site tail, then reconcile the registry result; do **not** rerun `--publish` |
 | `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` attempts registry verification and polls the live site itself. A target-confirmed receipt plus a delayed registry result is a reconciliation outcome, not a failed publish or a retry instruction. 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/peekaboo-driver/SKILL.md

@@ -96,10 +96,10 @@ For each `${PERM_NAME}` in `$MISSING`:
 ```
 AskUserQuestion({
   questions: [{
-    question: `${PERM_NAME} permission is required but not granted. Open System Settings > Privacy & Security > ${PERM_NAME}, enable the terminal entry, then confirm here.`,
-    header: `Missing Permission: ${PERM_NAME}`,
+    question: `${PERM_NAME} is not granted. Enable the terminal entry under System Settings > Privacy & Security, then confirm.`,
+    header: "Zugriff",
     options: [
-      { label: "Granted — continue (Recommended)", description: `I have enabled ${PERM_NAME} in System Settings.` },
+      { label: "Granted — continue (Recommended)", description: "I enabled the terminal entry in that pane — the driver then checks again and carries on if the grant took effect." },
       { label: "Skip this run", description: "Abort peekaboo-driver. Test-runner will record a framework-error finding." }
     ],
     multiSelect: false