session-orchestrator 3.20.0 → 3.22.0

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

@@ -281,17 +281,17 @@ If any criterion is FAIL:
 2. Revise the affected PRD sections
 3. Re-submit to the reviewer
 
-Maximum 3 iterations. After 3 iterations with remaining issues, present them to the user via AskUserQuestion:
+Maximum 3 iterations. After 3 iterations with remaining issues, list the flagged points in plain text (they are context, not a choice), then ask via AskUserQuestion:
 
 ```
 AskUserQuestion({
   questions: [{
-    question: "The PRD reviewer flagged these remaining issues after 3 revision rounds:\n\n[list issues]\n\nHow do you want to proceed?",
+    question: "The reviewer still flags [N] points after 3 revision rounds. Proceed anyway?",
     header: "PRD Review",
     options: [
-      { label: "Accept as-is (Recommended)", description: "Issues are minor, proceed with current PRD." },
-      { label: "Manual edit", description: "I'll edit the PRD myself before continuing." },
-      { label: "Re-run review", description: "Try one more revision round." }
+      { label: "Accept as-is (Recommended)", description: "Three rounds did not close them, so a fourth probably will not. The flags then stay in the PRD and travel into the issues filed from it." },
+      { label: "Manual edit", description: "You edit the PRD yourself; the flow waits, then re-runs the reviewer on your version." },
+      { label: "Re-run review", description: "One more revision round. Cost: another reviewer pass, and the same points may come back unchanged." }
     ],
     multiSelect: false
   }]
@@ -300,16 +300,16 @@ AskUserQuestion({
 
 ### 5.3 User Review Gate
 
-After the reviewer passes (or user accepts), present the final PRD:
+After the reviewer passes (or user accepts), present the final PRD in plain text — path plus a short section summary — then ask:
 
 ```
 AskUserQuestion({
   questions: [{
-    question: "PRD is ready for your review. It has been saved to [path].\n\nPlease review the document and confirm.",
+    question: "Approve the PRD at [path]?",
     header: "PRD Approval",
     options: [
-      { label: "Approve PRD (Recommended)", description: "PRD looks good, proceed to issue creation." },
-      { label: "Request changes", description: "I have feedback — let me describe what to change." }
+      { label: "Approve PRD (Recommended)", description: "Nothing further is checked after this: approval commits the PRD to HEAD (Phase 5.5), then issue creation starts." },
+      { label: "Request changes", description: "Describe what to change; the PRD is rewritten and comes back here. No limit on rounds." }
     ],
     multiSelect: false
   }]
@@ -395,18 +395,20 @@ Assign labels from the standard taxonomy:
 
 ### 6.3 User Review
 
-Present the full issue structure via AskUserQuestion before creating anything:
+Present the full issue structure via AskUserQuestion before creating anything. The table is the text that is about to be filed, so it belongs in `preview` — not in the question:
 
 ```
 AskUserQuestion({
   questions: [{
-    question: "Proposed issue structure:\n\n**Epic:** [title]\n\n| # | Sub-Issue | Priority | Labels | Blocked By |\n|---|----------|----------|--------|------------|\n| 1 | [title]  | critical | [labels] | — |\n| 2 | [title]  | high     | [labels] | #1 |\n| ... | ... | ... | ... | ... |\n\nTotal: [N] issues. Confirm or adjust.",
-    header: "Issue Review",
+    question: "Create these [N] issues from the PRD?",
+    header: "Issues",
     options: [
-      { label: "Create all issues (Recommended)", description: "Proceed with the proposed structure." },
-      { label: "Adjust priorities", description: "I want to change some priorities before creating." },
-      { label: "Remove issues", description: "Some issues should not be created." },
-      { label: "Cancel", description: "Do not create any issues." }
+      { label: "Create all [N] (Recommended)",
+        description: "Priorities and blocked-by links come straight from the approved PRD. Cost: one API call per issue, ~1s apart.",
+        preview: "**Epic:** [title]\n\n| # | Sub-Issue | Priority | Labels | Blocked By |\n|---|----------|----------|--------|------------|\n| 1 | [title]  | critical | [labels] | — |\n| 2 | [title]  | high     | [labels] | #1 |\n| ... | ... | ... | ... | ... |" },
+      { label: "Adjust priorities", description: "Same [N] issues, different priority labels. Name them and this question comes back with the table updated." },
+      { label: "Remove issues", description: "Name the ones to drop; the rest are created unchanged." },
+      { label: "Cancel", description: "Nothing is created. The PRD stays committed, so Phase 6 can run again later." }
     ],
     multiSelect: false
   }]

package/skills/plan/mode-feature.md

@@ -127,7 +127,7 @@ Apply per gitlab-ops skill label taxonomy:
 
 ### User Review Gate
 
-Present the full issue structure via AskUserQuestion before creation:
+Present the full issue structure via the AskUserQuestion payload in `SKILL.md` § 6.3 — the issue table belongs in the option's `preview` field, not in the question text:
 
 - Epic title and description
 - Each sub-issue: title, priority, labels, dependency links

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** — Select the GitLab host explicitly, then 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 --hostname "$GITLAB_HOST" "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,17 @@ 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
+
+# These values identify the NEW project, not the directory in which this plan runs.
+# Select the host with the group; do not let glab infer it from an ambient remote.
+GITLAB_HOST="<selected GitLab hostname>"
+PROJECT_PATH="$GROUP_PATH/$PROJECT_NAME"
+ENCODED_PROJECT_PATH="$(node -e 'process.stdout.write(encodeURIComponent(process.argv[1]))' "$PROJECT_PATH")"
 (
   echo "$TYPE_CHOICE"    # e.g., "1" for nextjs-saas
   echo "$STYLE_CHOICE"   # e.g., "1" for vega (only if nextjs-saas)
@@ -140,10 +151,12 @@ Map gathered answers to script input choices:
 
 ### Step 2: Verify success
 
-Check exit code. Confirm repo exists:
+Check the setup script exit code. Confirm the selected path exists without fetching a full REST project object:
 
 ```bash
-glab repo view $GROUP/$PROJECT_NAME
+glab api --hostname "$GITLAB_HOST" graphql \
+  -f query='query($fullPath: ID!) { project(fullPath: $fullPath) { fullPath } }' \
+  -f fullPath="$PROJECT_PATH" | jq -er '.data.project.fullPath'
 ```
 
 ### Step 3: Adjust visibility
@@ -151,15 +164,30 @@ 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). The encoded
+# endpoint and explicit host target the new project independently of the CWD.
+glab api --silent --hostname "$GITLAB_HOST" -X PUT \
+  "projects/${ENCODED_PROJECT_PATH}" \
+  -f visibility=private   # or visibility=public
+
+# Fetch only the scalar needed to verify the mutation, never a full REST object.
+glab api --hostname "$GITLAB_HOST" graphql \
+  -f query='query($fullPath: ID!) { project(fullPath: $fullPath) { visibility } }' \
+  -f fullPath="$PROJECT_PATH" | jq -er '.data.project.visibility'
 ```
 
+> The GraphQL verification query is read-only and requests only `visibility`; the
+> PUT's unused response is intentionally suppressed. Confirm the selected host and
+> path before running the mutation.
+
 For public/OSS, also configure GitHub mirror if applicable.
 
 ### Step 4: Set branch protection
 
 ```bash
-glab api -X PUT projects/:id/protected_branches \
+glab api --silent --hostname "$GITLAB_HOST" -X POST \
+  "projects/${ENCODED_PROJECT_PATH}/protected_branches" \
   -f name=main \
   -f push_access_level=30 \
   -f merge_access_level=30
@@ -264,7 +292,7 @@ Always use the `priority::<level>` format in VCS CLI commands, not P0/P1/P2/P3.
 
 ### Step 4: Present for user confirmation
 
-Use AskUserQuestion to present the full issue structure:
+Use the AskUserQuestion payload in `SKILL.md` § 6.3 verbatim — the issue table belongs in the option's `preview` field, not in the question text:
 
 - Epic title and description
 - Sub-issues with: title, priority, labels, dependency links
@@ -274,11 +302,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 "https://${GITLAB_HOST}/${PROJECT_PATH}" --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 "https://${GITLAB_HOST}/${PROJECT_PATH}" --title "$ISSUE_TITLE" --description "$ISSUE_DESC" \
   --label "type:feature,priority::$PRIORITY,status:ready,area:$AREA,appetite:$APPETITE"
 ```
 
@@ -287,10 +315,12 @@ glab issue create --title "$ISSUE_TITLE" --description "$ISSUE_DESC" \
 For issues with technical dependencies, set `blocks`/`is-blocked-by` relationships:
 
 ```bash
-# Issue #2 is blocked by Issue #1
-glab api -X POST projects/:id/issues/:issue2_iid/links \
-  -f target_project_id=:id \
-  -f target_issue_iid=:issue1_iid \
+# Issue #2 is blocked by Issue #1 in this project. An encoded project path is
+# valid for target_project_id, so no numeric project ID is needed.
+glab api --silent --hostname "$GITLAB_HOST" -X POST \
+  "projects/${ENCODED_PROJECT_PATH}/issues/${ISSUE_2_IID}/links" \
+  -f target_project_id="$ENCODED_PROJECT_PATH" \
+  -f target_issue_iid="$ISSUE_1_IID" \
   -f link_type=is_blocked_by
 ```
 

package/skills/plan/soul.md

@@ -69,6 +69,18 @@ The active level is `efficiency.output-level` in `~/.config/session-orchestrator
 - Shape: name the alternatives you rejected and why, spell out the appetite and the scope cuts, 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.
+
 ### Companion dials
 
 Same file, same lookup, same fallback-to-default rule:

package/skills/reconcile/SKILL.md

@@ -243,12 +243,12 @@ For each batch (proposals sliced into groups of 4):
 ```
 AskUserQuestion({
   questions: [{
-    question: "Which rule proposals should be written to .claude/rules/?  (batch K of N)",
-    header: "Reconcile — Approve Rule Proposals",
+    question: "Batch K of N — which rule proposals should be written into .claude/rules/?",
+    header: "Regeln",
     options: [
       {
         label: "<slug>.md (confidence: 0.72)",
-        description: "Learning: <learningKey> | Path: .claude/rules/<slug>.md | <first 100 chars of rendered content>"
+        description: "From learning <learningKey>. Becomes a file under .claude/rules/ — where this repo keeps its rules. Text: <first 100 chars of rendered content>"
       },
       ...up to 4 options per batch...
       {

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

@@ -141,7 +141,8 @@ For every `SPIRAL` or `FAILED` agent surfaced in the walk above, ALSO append a c
 ```js
 import { appendWhatNotToRetryOnDisk } from '${PLUGIN_ROOT}/scripts/lib/state-md.mjs';
 
-// `parsed` = parseStateMd(STATE.md); session id from the `session:` frontmatter field.
+// `parsed` = parseStateMd(STATE.md); `session:` is an attribution/history label.
+// It records this entry's provenance only and never authorizes lock ownership.
 const sessionId = parsed.frontmatter.session ?? 'unknown-session';
 const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
 
@@ -646,7 +647,7 @@ import { planTailPhases } from '${PLUGIN_ROOT}/scripts/lib/session-end/phase-ski
 const { plan, skippedReport } = await planTailPhases({
   repoRoot: process.cwd(),
   config,        // parsed Session Config (from $CONFIG)
-  sessionId,     // session.lock `session_id` / STATE.md `session:` field (or null)
+  sessionId,     // physical session.lock `session_id` only (or null), never STATE.md `session`
   platform,      // 'claude' | 'codex' | 'cursor'
 });
 // plan: Array<{ phase, run, reason, inputSource }>, already in ascending phase order.
@@ -733,20 +734,21 @@ After STATE.md is finalized with `status: completed` (Phase 3.4) and Recommendat
 
 ```javascript
 import { release } from 'scripts/lib/session-lock.mjs';
-// sessionId = the session identifier established by session-start Phase 1.2 acquire()
-//   and stored in .orchestrator/session.lock (session_id field); matches the
-//   STATE.md frontmatter `session:` field written during Pre-Wave 1b initialization.
-const result = release({ sessionId, repoRoot: process.cwd() });
+// sessionId is the physical raw value established by session-start Phase 1.2
+// and stored in .orchestrator/session.lock `session_id`. It is not STATE.md
+// `session:` or `semantic_session_id`, both of which are attribution labels.
+const rawSessionId = sessionId;
+const result = release({ sessionId: rawSessionId, repoRoot: process.cwd() });
 // result.ok is always true unless a filesystem error occurred.
 // result.deleted === true  → lock file removed successfully.
-// result.deleted === false → lock was absent or belonged to a different session_id (silent-OK).
+// result.deleted === false → lock was absent or had a different raw session_id.
 ```
 
-If `result.deleted === false`, log `info: session-lock not released — already absent or session_id mismatch (no action needed)` and continue. This is a non-error state.
+If `result.deleted === false`, log `info: session-lock not released — already absent or raw session_id mismatch` and continue. An active lock whose raw id differs is ambiguous: do **not** retry release with an equal `semantic_session_id`, STATE.md `session`, or owner proof. Leave that live lock for its TTL/Reaper lifecycle.
 
 If `result.ok === false` (rare filesystem error), log `⚠ session-lock: release failed — <result.reason>` and continue. Do NOT block the close for a lock-release failure — the TTL provides automatic expiry for the next session.
 
-The lock is released here — AFTER all STATE.md writes are complete and BEFORE the commit is staged in Phase 4.1. This ordering ensures a clean handover: the lock file is absent from the working tree when the commit is assembled, so it is not accidentally staged.
+The lock is released here — AFTER all STATE.md writes are complete and BEFORE the commit is staged in Phase 4.1. This ordering ensures a clean handover when the current raw owner releases it: the lock file is absent from the working tree when the commit is assembled, so it is not accidentally staged.
 
 ## Phase 4: Commit & Push
 
@@ -780,11 +782,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).
@@ -848,15 +892,24 @@ if (!promoted) {
 When the worktree is dirty (uncommitted, untracked, OR unpushed), render this AUQ via the coordinator's `AskUserQuestion` tool. The AUQ is coordinator-only — per `.claude/rules/ask-via-tool.md` AUQ-004, dispatched agents cannot call AUQ. Calling `git worktree remove --force` without explicit operator confirmation would violate PSA-003 (destructive action safeguards) — the dirty state may contain another session's work-in-progress or unmerged commits.
 
 ```js
+// What is actually at stake, shown beside the options via `preview` (AUQ-006):
+// the operator must see WHICH changes he would lose before he authorises the delete.
+// Capped at 10 lines so the preview never outgrows the option list next to it.
+const dirtyDetail = execFileSync('git', ['-C', promoted.wtPath, 'status', '--short', '--branch'], { encoding: 'utf8' })
+  .trim()
+  .split('\n')
+  .slice(0, 10)
+  .join('\n');
+
 AskUserQuestion({
   questions: [{
     question: `Auto-promoted worktree at ${promoted.wtPath} has uncommitted/untracked/unpushed changes. How should I proceed?`,
-    header: "Worktree-Cleanup",
+    header: "Worktree",
     multiSelect: false,
     options: [
-      { label: "Behalten (Recommended)", description: "Keep the worktree as-is. No cleanup. Review and remove manually later." },
-      { label: "Löschen", description: "I confirm the changes are handled or expendable. Run 'git worktree remove --force' on the worktree." },
-      { label: "Manuell", description: "Exit /close. I will inspect the worktree before re-running /close." },
+      { label: "Behalten (Recommended)", description: "Keeps the worktree exactly as it is — nothing is deleted, and you can still remove it by hand later.", preview: `Stays on disk:\n${dirtyDetail}` },
+      { label: "Löschen", description: "I confirm the changes are handled or expendable. Run 'git worktree remove --force' on the worktree.", preview: `Deleted with the worktree:\n${dirtyDetail}` },
+      { label: "Manuell", description: "Exit /close. I will inspect the worktree before re-running /close.", preview: `You would inspect this first:\n${dirtyDetail}` },
     ],
   }],
 });
@@ -865,8 +918,8 @@ AskUserQuestion({
 **Codex CLI / Cursor IDE fallback** (numbered Markdown list):
 
 ```
-Worktree cleanup options:
-1. **Behalten (Recommended)** — Keep the worktree as-is. No cleanup. Review and remove manually later.
+Worktree cleanup options (the changes at stake are the `git status --short --branch` lines printed above):
+1. **Behalten (Recommended)** — Keeps the worktree exactly as it is; nothing is deleted, and you can still remove it by hand later.
 2. **Löschen** — I confirm the changes are handled or expendable. Run 'git worktree remove --force'.
 3. **Manuell** — Exit /close. I will inspect the worktree before re-running /close.
 Reply with the number of your choice.
@@ -984,16 +1037,38 @@ if (sweep) {
     **Ordering (load-bearing):** run this as the LAST issue-creating action of Phase 5 — after step 3, after "Discovery Issue Creation", after step 4 — and re-read the counter file at that moment. Those steps can themselves push new entries into `overflow[]`; draining early would leave them unfiled.
 
     ```js
-    import { readBudgetState, budgetStatePath } from '${PLUGIN_ROOT}/scripts/lib/issue-budget.mjs';
-    const state = readBudgetState(repoRoot, sessionId);   // { sessionId, count, exempt, overflow: [...] }
+    import { readFileSync } from 'node:fs';
+    import {
+      readBudgetState,
+      budgetStatePath,
+      resolveIssueBudgetSessionId,
+    } from '${PLUGIN_ROOT}/scripts/lib/issue-budget.mjs';
+
+    // `sessionId` is the physical raw lock/registry identity from session-start.
+    const rawSessionId = sessionId;
+    let currentSession = null;
+    try {
+      currentSession = JSON.parse(
+        readFileSync(`${repoRoot}/.orchestrator/current-session.json`, 'utf8'),
+      );
+    } catch { /* no verified semantic accounting bridge */ }
+    const accountingSessionId = resolveIssueBudgetSessionId(rawSessionId, currentSession);
+    const state = readBudgetState(repoRoot, accountingSessionId);
+    // { sessionId, count, exempt, overflow: [...] }
     ```
 
+    `accountingSessionId` may be semantic only after
+    `currentSession.session_id === rawSessionId`; this is budget accounting, not
+    lock/registry ownership. When that proof is absent it remains the raw id.
+    A host rotation that changes both raw and semantic values has no guaranteed
+    budget continuity.
+
     - **`issue-budget.overflow: collect-issue` (default)** — create exactly ONE issue:
-      - Title: `[Backlog-Sammel] <session-id>, <N> zurückgestellte Punkte`
+      - Title: `[Backlog-Sammel] <accountingSessionId>, <N> zurückgestellte Punkte`
       - Labels: `type::backlog`, `priority::low`
       - Body: a Markdown checklist with one `- [ ]` line per `overflow[]` entry (`title` when present, otherwise the truncated `command`, plus its `at` timestamp).
       - This collector issue is itself EXEMPT from the cap (`[Backlog-Sammel]` is in the exemption list in `scripts/lib/issue-budget.mjs`), so it always lands even at count == max.
-    - **`issue-budget.overflow: vault-note`** — create NO issue. Write one Markdown file `vault/00-inbox/<session-id>-backlog-sammel.md` (path relative to `vault-integration.vault-dir`) with valid vault frontmatter and the same checklist body.
+    - **`issue-budget.overflow: vault-note`** — create NO issue. Write one Markdown file `vault/00-inbox/<accountingSessionId>-backlog-sammel.md` (path relative to `vault-integration.vault-dir`) with valid vault frontmatter and the same checklist body.
     - After the artefact exists, reset `overflow` to `[]` in the counter file and record the collector issue ID / note path in the Phase 6 Final Report under `### Zurückgestellt (issue-budget)`.
     - **Never exempt-by-accident:** the cap never applied to `priority::critical`, the carryover class (`[Carryover]`, SPIRAL/FAILED, `type::carryover`), or `broken-window` closure issues, so nothing on the Phase 1.65 carry-list can ever appear in `overflow[]`. The promises at Phase 1.8 ("SPIRAL / FAILED agent carryover … non-deselectable") and the Critical Rule "ALWAYS create issues for unfinished PLANNED work" stay intact by construction.
     - Fail-open: a missing or malformed counter file means "no overflow" — log a WARN and continue the close.
@@ -1092,7 +1167,7 @@ Present to the user:
 | `phase-3-7a-recommendations.md` § 3.7b | Phase 3.7b full procedural body — `withDurableCommit` invocation for `sessions.jsonl` + `STATE.md` (#490 AC2), `enabled:false` local no-op, autopilot.jsonl exclusion note |
 | (inline) Phase 3.7c | Vault Board → Closed (#674) — `mirrorBoard({ explicitStatus: 'closed' })` transitions this repo's board row to `closed`; gated on `vault-integration.enabled`, generator-marked + idempotent, non-blocking, ordered after 3.7b and before 3.7d/3.4/3.8 |
 | (inline) Phase 3.7d | Session-Eval (opt-in — #803) — `node scripts/eval-session.mjs --json` scores the just-closed session; gated on `eval.enabled` + `eval.mode != off` (parsed by `scripts/lib/config/eval.mjs`), optional `eval-judge` dispatch + `writeEvalReport`, advisory/never-blocks-close, ordered after 3.7 (record must exist) and before 3.4/Phase 4 (record committed with the session). Full flow in `skills/eval/SKILL.md` |
-| (inline) Phase 3.8 | Session Lock Release — `release()` call, silent-OK on mismatch/absent, non-fatal on fs-error, ordering note (after STATE.md writes, before Phase 4 commit staging) |
+| (inline) Phase 3.8 | Session Lock Release — `release()` uses the physical raw `session_id`; raw mismatch/absent is non-fatal but never repaired with semantic labels or proof (live ambiguity remains for TTL/Reaper); fs-errors are non-fatal; runs after STATE.md writes and before Phase 4 commit staging |
 
 ## Anti-Patterns
 

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)

package/skills/session-end/phase-3-6-tail.md

@@ -81,7 +81,25 @@ The proposals queue is populated mid-session by wave-executor agents calling `no
    }
    ```
 
-   Then iterate `batches` and emit one `AskUserQuestion` per batch with `header: "Memory — Confirm Proposals (Batch N of M)"`. Option label format: `[<type-12>] | <subject-40> | conf=X.XX`. Option description: `evidence: <first 60 chars of insight>`. `multiSelect: true`.
+   Then iterate `batches` and emit one `AskUserQuestion` per batch. The verbatim template is `agents/memory-proposal-collector.md` § AUQ Question Template — keep the two in step:
+
+   ```javascript
+   AskUserQuestion({
+     questions: [{
+       header: "Memory",
+       question: "Batch <N> of <M> — which of these learnings should be stored permanently?",
+       options: [
+         // one entry per proposal in this batch (max 4)
+         // label + description formats are LOCKED by D3 — see that file, do not restate them here
+         { label: "[type   ] | subject(40) | conf=X.XX", description: "evidence: <first 60 chars of insight>" },
+         ...
+       ],
+       multiSelect: true
+     }]
+   })
+   ```
+
+   The batch counter moved out of `header` and into the question because `header` is cut off after 12 characters — `Memory — Confirm Proposals (Batch N of M)` reached the operator as `Memory — Con`.
 
 5. After all batches answered, partition the queue into `approved` (any option selected across all batches) and `rejected` (all unselected).
 
@@ -337,7 +355,24 @@ After the auto-dialectic nudge decision is made (Phase 3.6.7), and when the reco
    }
    ```
 
-   Iterate `batches` and emit one `AskUserQuestion` per batch with `header: "Reconciliation — Confirm Rule Proposals (Batch N of M)"`. Option label format: `<slug-40> | conf=<confidence>`. Option description: first 80 chars of the rendered `content` (the rule prose preview). `multiSelect: true`.
+   Iterate `batches` and emit one `AskUserQuestion` per batch:
+
+   ```javascript
+   AskUserQuestion({
+     questions: [{
+       header: "Regeln",
+       question: "Batch <N> of <M> — which rule proposals should be written into .claude/rules/?",
+       options: [
+         // one entry per proposal in this batch (max 4)
+         { label: "<slug-40>", description: "Confidence <confidence>. First 80 chars of the rendered rule text: <…>" },
+         ...
+       ],
+       multiSelect: true
+     }]
+   })
+   ```
+
+   The batch counter moved out of `header` and into the question because `header` is cut off after 12 characters — `Reconciliation — Confirm Rule Proposals (Batch N of M)` reached the operator as `Reconciliati`. The rendered `content` shown in the description is the rule prose that will land on disk.
 
 6. After all batches are answered, partition proposals into `approved` (any option selected across all batches) and `rejected` (all unselected). Proposals the operator rejected join the engine's `rejected` array for archival.
 

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

@@ -19,19 +19,13 @@
 
 1. Ensure `.orchestrator/metrics/` directory exists: `mkdir -p .orchestrator/metrics`
 
-1-pre. **`memory_cleanup_at` always-stamp (#699)** — Before emitting the record, if `/memory-cleanup` ran THIS session in any mode (dry-run, apply-pending, OR healthy no-op), stamp `memory_cleanup_at = completed_at` on the record using `stampMemoryCleanup()` from `scripts/lib/memory-cleanup-stamp.mjs`:
+1-pre. **`memory_cleanup_at` is DERIVED, not remembered (#699 + 2026-08-17 follow-up)** — there is **no coordinator step here any more**. Do not set a `ranMemoryCleanupThisSession` boolean and do not call `stampMemoryCleanup()` by hand at session-end.
 
-   ```js
-   import { stampMemoryCleanup } from '../../scripts/lib/memory-cleanup-stamp.mjs';
+   `scripts/emit-session.mjs` derives the field itself: it calls `deriveMemoryCleanupSignal()` (`scripts/lib/memory-cleanup-stamp.mjs`), which reads the sibling `events.jsonl` for `orchestrator.memory.cleanup_completed` records whose `timestamp` falls inside this session's own `[started_at, completed_at]` window (and whose `semantic_session_id`, when present, matches). The emitting side is the LAST step of every `/memory-cleanup` run — see `skills/memory-cleanup/SKILL.md` § "Session-End Signal".
 
-   // ranCleanup: true when /memory-cleanup ran this session (ANY outcome)
-   metricsEntry = stampMemoryCleanup(metricsEntry, {
-     ranCleanup: ranMemoryCleanupThisSession, // boolean
-     completedAt: metricsEntry.completed_at,
-   });
-   ```
+   **Contract:** a no-op run (MEMORY.md already healthy, no files mutated) is still a cleanup, so it still emits and therefore still stamps. When `/memory-cleanup` did not run, no event exists, nothing is derived, and the field is simply absent — never `null`. An EXPLICIT `memory_cleanup_at` already present on the record WINS over derivation and is never overwritten; that path is for backfills and tests, not for normal operation.
 
-   **Contract:** A no-op run (MEMORY.md already healthy, no files mutated) is still a cleanup — `memory_cleanup_at` MUST be stamped. This advances `readDreamSignals` → `lastCleanupAt` in `auto-dream.mjs` so `shouldDispatchAutoDream` does not fire a false nudge. When `/memory-cleanup` did not run, omit the field entirely (do NOT set null). The helper is no-throw and pure — it returns the record unchanged on bad inputs.
+   **Why this stopped being a coordinator instruction.** It was one until 2026-08-17, and it measurably failed: a `/memory-cleanup` ran on 2026-08-14 with a documented yield, the prose step above was not executed, and all three session records of that day carried `memory_cleanup_at: null` — so the session-start banner reported "last cleanup 29 days ago" against the operator's own "3 days". `stampMemoryCleanup()` had **zero production callers** at that point; every reference to it was an instruction asking an LLM to remember. Same failure class as the STATE.md write-race Epic #583 replaced with a lock: Disziplin statt Mechanik.
 
    > **#701.2 DOC NOTE — `completed_at >= started_at` guard:** This invariant is enforced mechanically by `scripts/emit-session.mjs`. The writer applies `clampTimestampsMonotonic()` (from `scripts/lib/session-schema/timestamps.mjs`) before `validateSession()`, clamping any inversion of `completed_at < started_at` to `started_at` and recording forensics in `_clamped: true` / `_original_completed_at`. Previously-inverted entries (e.g. `main-2026-06-21-session-4`) are already corrected. **No per-session coordinator action is needed** — the writer enforces the invariant at write time. Do not add defensive clamping logic here; the canonical guard lives in `emit-session.mjs`.
 

package/skills/session-plan/SKILL.md

@@ -275,7 +275,7 @@ mission-status:
 - `status`: always `brainstormed` at plan emission. Terminal values are updated at gate transitions by wave-executor: `brainstormed` → `validated` (user confirms via `/go`) → `in-dev` (agent dispatched) → `testing` (Quality wave) → `completed` (Quality gate green). session-end Phase 1.9 reads the current value to classify the item.
 
 **Transition gates (summary):**
-At plan time, all items start at `brainstormed`. When the user runs `/go` to approve the plan, wave-executor updates each item to `validated`. When an agent for a wave-plan item is dispatched, wave-executor updates that item to `in-dev`. When the Quality wave begins, items from prior waves move to `testing`. When the Quality gate passes, items finalize at `completed`. Rollback to `brainstormed` is permitted from any state. All transitions are validated against the schema in `scripts/lib/mission-status-schema.mjs`.
+At plan time, all items start at `brainstormed`. When the user runs `/go` to approve the plan, wave-executor updates each item to `validated`. When an agent for a wave-plan item is dispatched, wave-executor updates that item to `in-dev`. When the Quality wave begins, items from prior waves move to `testing`. When the Quality gate passes, items finalize at `completed`. Rollback to `brainstormed` is permitted from any state. This ordering is **coordinator convention, not a mechanical gate** — nothing validates a transition before it is written (see "Default and transitions" below).
 
 **Omission rule:** When the plan has 0 wave-plan items (e.g., pure express-path coord-direct with no sub-agent tasks), do NOT emit the `### Wave-Plan Mission Status (machine-readable)` block.
 
@@ -298,7 +298,7 @@ Every wave-plan item carries a `status` field drawn from a 5-value enum. The fie
 - **Default at plan creation:** `brainstormed` — all items start here.
 - **Transitions are coordinator-level orchestration** (not inside individual agent prompts). See `skills/wave-executor/SKILL.md` "Mission-Status Updates (#340)" for when each transition fires.
 - **Rollback:** any item may return to `brainstormed` from any state (e.g. if work is discarded or re-planned).
-- **Schema validation:** transitions are validated against `scripts/lib/mission-status-schema.mjs` before being written to STATE.md.
+- **No mechanical validation — by design.** The `status` values come from the 5-value enum in the table above, but nothing checks a transition before it is written. `setMissionStatus` (`scripts/lib/state-md/mission-status.mjs`) mirrors whatever string it is handed onto BOTH the body section and the frontmatter array, deliberately without an enum gate: gating it would reintroduce the exact body-says-X/frontmatter-says-Y divergence that sync exists to remove. An out-of-enum value therefore lands visibly on both surfaces instead of being silently rejected on one. Keeping the enum honest is the coordinator's job.
 
 #### Status field in wave-plan items
 

package/skills/session-plan/wave-template.md

@@ -18,7 +18,7 @@ For each wave, define agents with:
 
 - `Isolation: worktree` means the wave-executor will pass `isolation: "worktree"` to the Agent tool, giving each agent its own git worktree copy
 - `MaxTurns` is enforced via the agent prompt — wave-executor includes a turn limit instruction in each agent's prompt
-- `status` is the mission-status enum value for this wave-plan item (#340). Always `brainstormed` in the initial plan. Wave-executor updates it at gate transitions (validated → in-dev → testing → completed). Values are validated against `scripts/lib/mission-status-schema.mjs`. Rollback to `brainstormed` is allowed from any state.
+- `status` is the mission-status enum value for this wave-plan item (#340). Always `brainstormed` in the initial plan. Wave-executor updates it at gate transitions (validated → in-dev → testing → completed). Rollback to `brainstormed` is allowed from any state. The five values are listed in `SKILL.md` § Mission-Status Enum; nothing validates them mechanically — `setMissionStatus` writes the string it is given to both STATE.md surfaces on purpose, so keeping the value in-enum is the coordinator's job.
 
 > **Deconfliction rule:** Before finalizing agent specs for a wave, verify that no two agents in the same wave list overlapping `Files:` paths. If overlap is found, either merge the agents into one or move one task to a later wave. Two agents editing the same file in parallel causes merge conflicts that require manual resolution.