session-orchestrator 3.16.0

package/skills/memory-cleanup/SKILL.md

@@ -0,0 +1,310 @@
+---
+name: memory-cleanup
+user-invocable: true
+tags: [memory, maintenance, meta, dream]
+model: sonnet
+model-preference: sonnet
+model-preference-codex: gpt-5.4-mini
+model-preference-cursor: claude-sonnet-4-6
+args-schema:
+  - flag: --dry-run
+    description: "Produce complete-body proposal in .orchestrator/pending-dream.md, no mutations."
+  - flag: --apply-pending
+    description: "Consume .orchestrator/pending-dream.md (atomic apply)."
+description: >
+  Use this skill when performing manual memory consolidation (Dream-equivalent). Reviews, consolidates, and prunes memory files
+  under ~/.claude/projects/*/memory/. Run after major refactors, every 5+ sessions, or when memory
+  quality degrades (broken links, stale references, contradictions, MEMORY.md > 200 lines).
+  Invoke with /memory-cleanup.
+---
+
+# Memory Cleanup — Manual Dream Process
+
+Implements the 4-phase memory consolidation process modelled after Claude Code's Auto Dream feature. Run after major refactors, framework migrations, or every 5+ sessions in a repo.
+
+The memory system lives at `~/.claude/projects/<encoded-cwd>/memory/` and consists of:
+
+- `MEMORY.md` — index file (must stay under 200 lines; lines after 200 are truncated by the harness).
+- Topic files — one Markdown file per memory entry with YAML frontmatter (`name`, `description`, `metadata.type`).
+
+The four memory types are `user`, `feedback`, `project`, `reference` (see global `auto memory` instructions for semantics). This skill never invents new types.
+
+## Argument Handling (Phase 0)
+
+This skill accepts two optional flags. Default (no flag) runs the interactive 4-phase consolidation defined below.
+
+| Flag | Behavior |
+|---|---|
+| `--dry-run` | Run Phases 1-3 read-only; instead of mutating MEMORY.md / topic files, write a complete-body MEMORY.md proposal (single fenced block — never a unified-diff) to `.orchestrator/pending-dream.md` (atomic). Exit 0. |
+| `--apply-pending` | Read `.orchestrator/pending-dream.md`; refuse if older than 14 days (`stale`) or if MEMORY.md changed since the producing --dry-run (`stale-index`, #788); apply diff; delete pending file; print `auto-dream applied: -<X> lines, +<Y> entries`. Exit 0. |
+
+Flags are mutually exclusive — passing both is an error. Absence of both = legacy interactive mode (Phases 1-4 below).
+
+**`--dry-run` flow:**
+- Read MEMORY.md and topic files (read-only).
+- Produce the same internal plan the interactive mode would (merges, prunes, rewrites).
+- **Serialisation contract (#717 — load-bearing, read before writing the proposal):** `applyPendingDream()` in `scripts/lib/auto-dream.mjs` consumes ONLY the FIRST fenced code block in the sidecar body and writes it VERBATIM as the complete new MEMORY.md. It does NOT parse or apply git-style diff hunks. Therefore the proposal MUST ALWAYS be the complete new MEMORY.md body, in EXACTLY ONE fenced ` ```markdown ` block — never git-style unified-diff hunks (`--- `/`+++ `/`@@ … @@` lines), and never multiple fences for MEMORY.md itself. Any topic-file (non-MEMORY.md) change needed by the plan CANNOT be carried inside that single fence — instead, append it AFTER the fence as a separate, clearly-delimited machine-readable section per topic file, using the heading `### Topic-file change: <path>` followed by plain-language instruction text (not a diff). These sections are for a human to apply by hand; `applyPendingDream()` never reads past the first fence. If a `### Topic-file change:` section needs to show illustrative code, use 4-space-indented code text, never a fenced ``` block — `countFencedBlocks()` counts every fence in the raw sidecar body (not just MEMORY.md's), so a second fence anywhere in the document trips the >1-fence unsupported-format guard and blocks the whole apply.
+- Call `writePendingDream({ repoRoot, diff, sourceSession, memoryLinesBefore, proposedLinesAfter })` from `scripts/lib/auto-dream.mjs`, passing the single-fence MEMORY.md body (plus any `### Topic-file change:` sections) as `diff`.
+- Print one-line status: `pending-dream written: <N> lines proposed` (or `no consolidation needed (MEMORY.md is healthy)` when the plan is empty).
+- Exit 0 in both branches.
+
+**`--apply-pending` flow:**
+- Call `applyPendingDream({ repoRoot, memoryDir })` from `scripts/lib/auto-dream.mjs`.
+- Behavior matrix on the helper return:
+  - `applied: true` → print `auto-dream applied: -<linesBefore-linesAfter> lines, +<entries> consolidated entries` and exit 0.
+  - `applied: false, reason: 'missing'` → print `no pending dream to apply` and exit 1.
+  - `applied: false, reason: 'stale'` → print `pending dream is stale (>14d), re-run --dry-run` and exit 1.
+  - `applied: false, reason: 'stale-index'` (#788) → print `MEMORY.md changed since the producing --dry-run; re-run --dry-run.` and exit 1. The sidecar is preserved and MEMORY.md is left untouched (MEMORY.md's mtime is newer than the sidecar's `generated_at`, so applying the frozen dry-run snapshot would clobber the interim edits).
+  - `applied: false, reason: 'unsupported-format'` → print `auto-dream NOT applied: pending-dream.md contains git-style diff hunks this applier cannot consume. MEMORY.md left untouched, sidecar preserved. Re-run /memory-cleanup --dry-run to regenerate a complete-body proposal.` and exit 1.
+- The sidecar file is deleted on successful apply; staleness (`stale` / `stale-index`), missing sidecar, or unsupported-format never deletes anything.
+
+Both flag-driven flows delegate atomicity and staleness enforcement to `scripts/lib/auto-dream.mjs`. The interactive Phases 1-4 below remain unchanged.
+
+## Phase 1: Orient
+
+Understand the current memory state before making changes.
+
+1. List all files in the memory directory:
+   ```bash
+   ls -la ~/.claude/projects/*/memory/ 2>/dev/null | grep "$(basename "$(pwd)")"
+   ```
+   Or directly list the project's memory dir (the path is in the `auto memory` system instructions).
+
+2. Read `MEMORY.md` (the index file) — note its line count:
+   ```bash
+   wc -l <memory-dir>/MEMORY.md
+   ```
+
+3. Skim each topic file referenced in the index. Build a mental map:
+   - Which topics are covered?
+   - Are there overlapping files?
+   - Any files not referenced in the index?
+   - Any index entries pointing to files that no longer exist?
+
+**Goal**: Improve existing files, never create duplicates.
+
+## Phase 2: Gather Signal
+
+Find what's changed since the last consolidation.
+
+1. **Git history** — recent commits give the timeline for "did this fact change?":
+   ```bash
+   git log --oneline -20
+   ```
+
+2. **Stale references** — for each file/function/symbol mentioned in memory, verify it still exists:
+   ```bash
+   grep -rn "specific-file-or-function" src/ lib/ scripts/ 2>/dev/null
+   ```
+
+3. **Relative dates** — find temporal references that need conversion:
+   ```bash
+   grep -rni "yesterday\|today\|tomorrow\|last week\|this week\|gestern\|heute\|morgen\|letzte woche" <memory-dir>/
+   ```
+
+4. **Version drift** — package versions stored in memory vs reality:
+   ```bash
+   cat package.json | grep '"version"'
+   ```
+
+5. **Test/issue-count drift** — claims like "5001 passed" or "8 open issues" age fast. Cross-check with current state if mentioned.
+
+## Phase 3: Consolidate
+
+Apply maintenance operations to memory files.
+
+### 3a: Merge overlapping entries
+If multiple files or entries describe the same thing, combine them into one authoritative entry. Update inbound `[[wiki-link]]`s accordingly.
+
+### 3b: Convert relative dates to absolute
+"Yesterday we decided X" → "On 2026-03-24 we decided X". Always use ISO date format (YYYY-MM-DD). This rule applies on **write**, but cleanup catches what slipped through.
+
+### 3c: Remove stale references
+- Delete entries about files that were removed during refactors.
+- Remove debugging notes for bugs that are fixed.
+- Update function/file paths that were renamed (`git log --diff-filter=R` surfaces renames).
+
+### 3d: Update outdated facts
+- Package versions that have been bumped.
+- Test counts, issue counts, line counts that changed.
+- Feature flags that were toggled.
+- Architecture decisions that were reversed (keep a `decisions.md`-style note that the decision was reversed, with the reason — don't silently overwrite).
+
+### 3e: Resolve contradictions
+If two memory entries conflict, check the codebase to determine which is current. Delete the outdated entry. **Never leave contradictions.**
+
+## Phase 4: Prune & Index
+
+Keep `MEMORY.md` clean and under the 200-line limit.
+
+1. **Check line count**:
+   ```bash
+   wc -l <memory-dir>/MEMORY.md
+   ```
+
+2. **If over 180 lines**, extract detailed content into topic files. Suggested naming:
+   - Session summaries → `project_sessions.md` or `session-YYYY-MM-DD-<slug>.md`
+   - Architecture decisions → `reference_decisions.md`
+   - Package/tooling details → `reference_packages.md`
+   - Use the convention: `{type}_{topic}.md`
+
+3. **Topic file frontmatter** (required):
+   ```yaml
+   ---
+   name: descriptive-name
+   description: one-line description for relevance matching
+   metadata:
+     type: project   # one of: user | feedback | project | reference
+   ---
+   ```
+
+4. **Update the index**:
+   - `MEMORY.md` is an index, not a dump.
+   - One-line `- [Title](file.md) — hook` entries.
+   - Remove stale pointers to deleted files.
+   - Add links for new topic files.
+   - Reorder by relevance (most-accessed topics first).
+
+5. **Final verification**:
+   ```bash
+   wc -l <memory-dir>/MEMORY.md  # must be < 200
+   # verify all index links resolve to existing files
+   grep -oP '\]\(([^)]+\.md)\)' <memory-dir>/MEMORY.md | sed 's/](\(.*\))/\1/' | while read f; do
+     [ -f "<memory-dir>/$f" ] || echo "BROKEN: $f"
+   done
+   ```
+
+## Phase 4.5: Worktree-Stale-Sweep (#575 P3.2)
+
+> Skip if `persistence: false` in Session Config. Silent no-op if no Auto-promoted sibling worktrees exist or none are stale.
+
+Detect stale Auto-promoted worktrees (older than `stale-branch-days` from Session Config, default 7 days) and offer them for batch-removal alongside the other housekeeping prune actions from Phase 4. This sub-phase is **additive** — it appends candidates to the existing prune flow rather than introducing a separate independent confirmation cycle.
+
+### Detection: list candidate auto-promoted worktrees
+
+Auto-promoted worktrees follow the layout `<parentDir>/<repoName>-<sessionId>/`, where `<sessionId>` is a semantic session-id (per `parseSessionId()` from `scripts/lib/session-id.mjs`). Random-suffix worktrees (UUID-format) are NOT auto-promoted and MUST be ignored.
+
+> **Authoritative impl:** `scripts/lib/memory-cleanup/worktree-sweep.mjs` — `listAutoPromotedWorktrees(repoRoot, mainCheckoutRoot, opts)`. Import and call; do NOT re-implement from this doc.
+>
+> Algorithm: split `git worktree list --porcelain` on the blank-line delimiter; for each `worktree ` entry, skip the main checkout, then require the basename to start with `<repoName>-` and the suffix to parse as a `semantic` session-id via `parseSessionId()` (UUID / random suffixes excluded). Each match yields `{ wtPath, sessionId, branch }`. Any git failure → `[]` (conservative no-op). Git invocation is via the injection-safe `opts.execFileFn` (default `execFileSync` with an args array — #577 HARDEN-001).
+
+### Staleness check
+
+A worktree is stale iff `mtime(worktree-dir) < now - stale-branch-days × 86400 × 1000`. Read `stale-branch-days` from Session Config (default 7):
+
+> **Authoritative impl:** `scripts/lib/memory-cleanup/worktree-sweep.mjs` — `isWorktreeStale(wtPath, staleBranchDays)`. Import and call; do NOT re-implement from this doc.
+>
+> Algorithm: `statSync(wtPath)`; stale iff `Date.now() - stat.mtimeMs > staleBranchDays × 24 × 60 × 60 × 1000`. A missing or unreadable path → `false` (conservative no-op).
+
+### Integration with the existing housekeeping prune AUQ
+
+After Phase 4 (Prune & Index) compiles its list of items to offer for removal, ALSO include any stale auto-promoted worktrees. The user sees them in the same AUQ ("batch-decide" per PRD §3 P3 Gherkin row 4):
+
+```js
+import { execFileSync } from 'node:child_process';
+import { listAutoPromotedWorktrees, isWorktreeStale } from '$PLUGIN_ROOT/scripts/lib/memory-cleanup/worktree-sweep.mjs';
+import { discoverActiveSessions } from '$PLUGIN_ROOT/scripts/lib/session-discovery.mjs';
+
+const staleBranchDays = $CONFIG['stale-branch-days'] ?? 7;
+const candidates = listAutoPromotedWorktrees(process.cwd(), mainCheckoutRoot);
+const stale = candidates.filter((c) => isWorktreeStale(c.wtPath, staleBranchDays));
+
+if (stale.length === 0) {
+  // Silent no-op — no stale worktrees to offer.
+} else {
+  // #580-HARDEN-002: cross-check candidates against LIVE peer sessions before offering removal.
+  // A stale-by-mtime worktree may still be the checkout of an active parallel session — removing
+  // it would disrupt that session (PSA-002 overlap). Flag any such candidate so the AUQ can warn.
+  const active = await discoverActiveSessions(mainCheckoutRoot);
+  const livePaths = new Set(active.map((s) => s.worktreePath));
+  const annotated = stale.map((wt) => ({ ...wt, activePeer: livePaths.has(wt.wtPath) }));
+
+  // Add to the existing housekeeping prune AUQ. Each stale worktree becomes one option line:
+  // Format: `[ ] Stale auto-promoted worktree: <basename> (age <N>d) — remove via 'git worktree remove --force'`
+  // If `activePeer` is true, prefix the option with "⚠ ACTIVE PEER SESSION" and make Behalten the default.
+  //
+  // If memory-cleanup currently presents per-item AUQs (one question per prune candidate),
+  // append one question per stale worktree.
+  //
+  // If memory-cleanup uses a single multiSelect AUQ for the whole batch,
+  // add stale worktrees as additional options.
+  //
+  // Operator selects which to remove; coordinator runs (arg-array, no shell — #577 HARDEN-001):
+  //   execFileSync('git', ['-C', mainCheckoutRoot, 'worktree', 'remove', '--force', wtPath])
+  // for each selected. WARN line per removal.
+}
+```
+
+### AUQ example (per-item)
+
+When the candidate's `wtPath` matches a LIVE peer session (`wt.activePeer === true`, from `discoverActiveSessions()` above), the AUQ MUST surface a `⚠ ACTIVE PEER SESSION` warning and keep `Behalten` as the safe default — removing a live session's worktree mid-flight is a PSA-002 overlap that can corrupt another session's working state.
+
+```js
+const peerWarning = wt.activePeer
+  ? ' ⚠ ACTIVE PEER SESSION — removing may disrupt a live session.'
+  : '';
+
+AskUserQuestion({
+  questions: [{
+    question: `Stale auto-promoted worktree found: ${path.basename(wt.wtPath)} (age ${ageDays}d, branch=${wt.branch}).${peerWarning} Remove?`,
+    header: "Stale-Worktree",
+    multiSelect: false,
+    options: [
+      {
+        label: "Behalten (Recommended)",
+        description: wt.activePeer
+          ? "Keep this worktree — a LIVE peer session is using it. Removal would disrupt the active session."
+          : "Keep this worktree. Re-evaluate at next /memory-cleanup run.",
+      },
+      {
+        label: "Entfernen",
+        description: wt.activePeer
+          ? `⚠ ACTIVE PEER SESSION detected. Only choose this if you have confirmed no live session needs it, then run 'git worktree remove --force ${wt.wtPath}'.`
+          : `Run 'git worktree remove --force ${wt.wtPath}'.`,
+      },
+    ],
+  }],
+});
+```
+
+### PSA-003 compliance
+
+Per `.claude/rules/parallel-sessions.md` PSA-003: every `git worktree remove` is destructive — operator must explicitly authorize. The AUQ above satisfies this. Never auto-remove without user confirmation, even for stale worktrees. The `--force` flag is acceptable here only because the AUQ already secured explicit per-worktree consent; never apply `--force` to worktrees the operator did not select.
+
+### Cross-references
+
+- PRD: "Parallel-Aware Sessions" (#568; archived in the private Meta-Vault) §3 P3 Gherkin row 4 + §3.A P3 EARS state-driven clause
+- `stale-branch-days` config: `scripts/lib/config.mjs:138` (default: 7)
+- Detection helper: `parseSessionId()` from `scripts/lib/session-id.mjs`
+- Stale-sweep helpers: `listAutoPromotedWorktrees()` + `isWorktreeStale()` from `scripts/lib/memory-cleanup/worktree-sweep.mjs`
+- Live-peer detection (#580-HARDEN-002): `discoverActiveSessions(repoRoot)` from `scripts/lib/session-discovery.mjs` — flags stale candidates whose `wtPath` matches an active session so the AUQ warns before removal
+- PSA-003: `.claude/rules/parallel-sessions.md`
+
+## Output
+
+After completing all four phases, report:
+
+- Files created / updated / deleted (paths only — no full diffs in the chat output).
+- `MEMORY.md` line count (before → after).
+- Contradictions resolved (with one-line summary each).
+- Stale entries pruned (count + categories).
+- Any issues that need manual attention (e.g. ambiguous facts that need user input — surface via `AskUserQuestion` rather than guessing).
+
+### Session-End Signal: "cleanup ran this session" (#699)
+
+**A completed cleanup — including a healthy no-op where MEMORY.md was already healthy and no files were mutated — counts as a cleanup run.** The session-end skill MUST stamp `memory_cleanup_at` on the session record whenever `/memory-cleanup` ran in THIS session, regardless of outcome (dry-run, apply-pending, or no-op).
+
+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.
+
+## Anti-Patterns
+
+- **Don't rewrite memory you don't understand.** If a fact's provenance is unclear, leave it and flag it in the output instead of deleting.
+- **Don't bulk-delete on the first run.** Cleanup runs are cheap; aggressive pruning costs context that can't easily be reconstructed.
+- **Don't create new memory types.** The four-type taxonomy (`user`, `feedback`, `project`, `reference`) is load-bearing for the relevance heuristic.
+- **Don't touch `MEMORY.md` if line-count is already healthy.** Re-ordering for its own sake creates churn without value.

package/skills/mode-selector/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: mode-selector
+description: >
+  Use this skill when performing deterministic mode selection for session-start. Reads Phase A STATE.md
+  recommendations + (future) learnings, sessions, backlog, bootstrap signals
+  and returns {mode, rationale, confidence, alternatives}. Pure-function
+  contract — no side effects, no STATE.md writes. Phase B scaffold (issue #276);
+  full heuristic is follow-up sub-issues.
+model: haiku
+user-invocable: false
+tags: [phase-b, autopilot, mode-selection, scaffold]
+---
+
+# Mode-Selector Skill
+
+## Status
+
+Heuristic v1 active (issue #291, shipped 2026-04-25). Wired into session-start Phase 7.5
+(issue #292, shipped 2026-04-25). Backlog signal source live (issue #293, shipped 2026-04-25):
+`signals.backlog` is populated by `scripts/lib/backlog-scan.mjs::scanBacklog`. Accuracy feedback
+loop live (issue #294, shipped 2026-04-25): `scripts/lib/mode-selector-accuracy.mjs::recordAccuracy`
+writes a `mode-selector-accuracy` learning after the user confirms/overrides the Phase 7.5 banner.
+Phase B contract is **closed**. Phase C (#277) `/autopilot` Loop Command is the next epic and
+owns its own PRD.
+
+## Purpose
+
+Mode-Selector centralizes the session-mode decision across all consumers: session-start Phase 1.5
+banner, `/autopilot` (Phase C), and any future caller that needs a structured recommendation rather
+than ad-hoc heuristics inline at the call site. Before this skill existed, mode-picking logic was
+either implicit (user-typed free text) or embedded directly in session-start with no reuse path.
+
+Phase A (`state-md.mjs::parseRecommendations`, issue #272) established the `recommended-mode`
+frontmatter field written by session-end Phase 3.7a. Phase B is the skill that reads that field
+(plus future signals) and returns a structured recommendation. The key output is a four-field
+tuple: `{mode, rationale, confidence, alternatives}`. `mode` is the recommended session type.
+`rationale` is a ≤120-char human-readable explanation. `confidence` is a float (0.0–1.0)
+indicating how strongly the selector commits to the recommendation. `alternatives` is an ordered
+list of `{mode, confidence}` objects representing the next-best choices, enabling callers to offer
+override options without re-running the selector.
+
+The selector is a pure function: given the same `signals` object it always returns the same output.
+No file I/O, no network calls, no global state. This makes it trivially testable and safe to call
+from any skill without side-effect risk.
+
+## Contract
+
+### Input: `signals` object
+
+- `recommendedMode` (string|null) — Phase A frontmatter field; the `recommended-mode` key from `parseRecommendations()`
+- `topPriorities` (number[]|null) — issue numbers from the `top-priorities` frontmatter field
+- `carryoverRatio` (number|null) — float 0.0–1.0 from Phase A; fraction of issues carried over from previous session
+- `completionRate` (number|null) — float 0.0–1.0 from Phase A; ratio of planned issues completed
+- `previousRationale` (string|null) — the `rationale` string written by session-end Phase 3.7a
+- `learnings` (object[]|null) — RESERVED; not consumed in scaffold; Phase B-1 heuristic input
+- `recentSessions` (object[]|null) — RESERVED; not consumed in scaffold; recent-sessions trend input
+- `backlog` (object|null) — `{criticalCount, highCount, staleCount, byLabel, total, vcs, limit}` from `scripts/lib/backlog-scan.mjs::scanBacklog` (Phase B-3, #293). `null` when CLI missing or no git origin — contributes 0 delta.
+- `bootstrapLock` (object|null) — RESERVED; not consumed in scaffold; tier-aware sizing hints
+
+### Output: `Recommendation` object
+
+| Field | Type | Range / Values | Purpose |
+|---|---|---|---|
+| `mode` | string enum | `housekeeping` \| `feature` \| `deep` \| `discovery` \| `evolve` \| `plan-retro` | Recommended session type |
+| `rationale` | string | ≤120 chars | Human-readable explanation for the recommendation |
+| `confidence` | float | 0.0–1.0 | Selector commitment; see Fallback Behavior for threshold semantics |
+| `alternatives` | `{mode, confidence}[]` | 0–3 entries; may be empty, never null | Next-best modes with partial confidence scores |
+
+## Invocation Points
+
+### Current
+
+- **`skills/session-start/SKILL.md` Phase 7.5** — first wired invocation (issue #292). Renders
+  `📊 Mode-Selector suggests:` when `confidence < 0.5` (informational, no pre-selection) or
+  `📊 Mode-Selector recommends:` when `confidence >= 0.5` (pre-selects AUQ option 1). Eight
+  graceful no-op conditions documented inline. Note: Phase 1.5 `📋` banner is NOT a Mode-Selector
+  invocation — it reads Phase A STATE.md frontmatter directly via `parseRecommendations`; the
+  Mode-Selector lives at Phase 7.5.
+- **`tests/lib/mode-selector.test.mjs`** — 75 tests (7 describe blocks) exercising SPIRAL,
+  CARRYOVER, high-confidence path, conflicting-signals, stale-signals, alternatives generation,
+  and defensive parsing. `mode-selector.mjs` coverage 100%/100%/100%/100%. Issue #291.
+
+### Future
+
+- **`/autopilot` (Phase C, #277)** — auto-execute when `confidence >= 0.85` AND
+  SPIRAL/FAILED/carryover-50% kill-switches pass. No user prompt in that path.
+
+### Companion modules (Phase B closure)
+
+- **`scripts/lib/backlog-scan.mjs::scanBacklog`** — feeds `signals.backlog`. Phase B-3 (#293).
+  Module-level cache, glab/gh auto-detection, returns `null` on graceful-degradation paths.
+- **`scripts/lib/mode-selector-accuracy.mjs::recordAccuracy`** — post-AUQ feedback writer. Phase B-4 (#294).
+  Subject pattern `<recommended>-selected-vs-<chosen>`; agreement and override land at distinct subjects so
+  the existing learning lifecycle can confirm/contradict them independently.
+
+## Scaffold Heuristic (v0)
+
+The v0 scaffold implements a minimal three-branch passthrough. It is intentionally thin so
+the contract is exercisable by tests before the full Phase B-1 rule-set lands.
+
+```
+selectMode(signals):
+  if signals is null/undefined:
+    → {mode: 'feature', rationale: 'scaffold: null signals → default', confidence: 0.0, alternatives: []}
+  if signals.recommendedMode is valid mode:
+    → {mode: <recommendedMode>, rationale: 'scaffold: passthrough of Phase A recommended-mode', confidence: 0.5, alternatives: []}
+  otherwise:
+    → {mode: 'feature', rationale: 'scaffold: missing/invalid recommendedMode → default', confidence: 0.0, alternatives: []}
+```
+
+Note: the full Phase B heuristic — rule-set consuming learnings.jsonl, recent sessions trend,
+VCS backlog priority-weighting, and bootstrap.lock tier — is the Phase B-1 follow-up sub-issue.
+
+## Fallback Behavior
+
+- `confidence = 0.0` means the selector is declining to choose; caller should fall back to its own
+  logic (v0 heuristic) or prompt the user without pre-selecting any option.
+- `0.0 < confidence < 0.5` means low-confidence; caller should present as a suggestion, never
+  auto-execute; AUQ should show the recommended mode without marking it as "Recommended".
+- `confidence ≥ 0.5` means accept as default; present as the pre-selected AUQ option; user can
+  still override.
+- `confidence ≥ 0.85` (future Phase C threshold) means suitable for autonomous execution in
+  `/autopilot` mode without user prompt, subject to kill-switch guards.
+
+## Integration with Other Skills
+
+- **`state-md.mjs::parseRecommendations`** → read Phase A frontmatter fields; consumed via
+  `signals.recommendedMode`, `signals.carryoverRatio`, `signals.completionRate`, etc.
+- **`recommendations-v0.mjs::isValidMode`** → mode enum validation; import and use — do not
+  redefine the six-value enum inline.
+- **`learnings.mjs::readLearnings`** → reserved for Phase B-1 heuristic input via
+  `signals.learnings`
+- **`session-schema.mjs::normalizeSession`** → reserved for recent-sessions trend input via
+  `signals.recentSessions`
+- **`bootstrap-lock-freshness.mjs::parseBootstrapLock`** → reserved for tier-aware sizing hints
+  via `signals.bootstrapLock`
+- **`gitlab-ops.md`** → reserved for VCS backlog scan (Phase B-3) via `signals.backlog`
+
+## Critical Rules
+
+- **Pure function only.** No I/O, no side effects, no throws, no dynamic imports. `selectMode`
+  must be synchronous and referentially transparent.
+- **Never write STATE.md.** session-start or Phase C writes any derived state; the selector is
+  read-only. session-end Phase 3.7a is the sole writer of `recommended-mode`.
+- **Every return path returns all 4 keys.** The `{mode, rationale, confidence, alternatives}`
+  shape is enforced by tests; missing keys are a contract violation.
+- **`alternatives` is always an array.** Never `null`, never `undefined`, may be empty (`[]`).
+- **Use `isValidMode` from `recommendations-v0.mjs`.** Do not redefine the mode enum; drift
+  between selector and validator is a schema bug.
+
+## Anti-Patterns
+
+- Do not call `selectMode` from inside session-end. session-end Phase 3.7a is the SOLE producer
+  of the `recommended-mode` frontmatter field; the selector is a consumer only.
+- Do not add logging inside `selectMode` — the function must stay pure. Logging (breadcrumbs,
+  sweep.log events) happens at the call site, not inside the selector.
+- Do not expand the scaffold to consume `learnings` inside this session. That is Phase B-1
+  follow-up work; the RESERVED fields in `signals` are intentionally ignored here.
+- Do not treat `confidence` as binary. Threshold semantics (`0.5` accept-as-default, `0.85`
+  auto-execute) live at the call site, not in the selector. The selector emits a float; the
+  caller decides what to do with it.
+
+## References
+
+- Implementation: `scripts/lib/mode-selector.mjs`
+- Tests: `tests/lib/mode-selector.test.mjs` (selector core, 75 tests), `tests/lib/backlog-scan.test.mjs` (signal source), `tests/lib/mode-selector-accuracy.test.mjs` (feedback loop)
+- Backlog signal source: `scripts/lib/backlog-scan.mjs` (Phase B-3, #293)
+- Accuracy feedback writer: `scripts/lib/mode-selector-accuracy.mjs` (Phase B-4, #294)
+- PRD: "Mode Selector" (#276; archived in the private Meta-Vault)
+- Epic: [#271 v3.2 Autopilot](https://github.com/Kanevry/session-orchestrator/issues/271)
+- Issue: [#276 Phase B Mode-Selector](https://github.com/Kanevry/session-orchestrator/issues/276)
+- Phase A Contract PRD: "STATE.md Recommendations Contract" (#271; archived in the private Meta-Vault)
+- Phase A parser: `scripts/lib/state-md.mjs::parseRecommendations` (issue #272)
+- Phase A writer: `skills/session-end/SKILL.md` Phase 3.7a (issue #273)
+- Mode enum: `scripts/lib/recommendations-v0.mjs::isValidMode`
+
+## Context-Pressure Signal (#332)
+
+Context-pressure is a single 0.0–1.0 score combining scope size, cross-cutting keyword presence,
+and recent-session carryover-ratio. It modulates `selectMode()` decisions without overriding them:
+
+| Level  | Score       | Effect on mode delta                                  |
+|--------|-------------|-------------------------------------------------------|
+| low    | < 0.3       | feature +0.05 (rewards clean scope)                   |
+| medium | 0.3 – 0.7   | no adjustment                                         |
+| high   | ≥ 0.7       | feature −0.15, housekeeping −0.10 (favors deep)       |
+
+### Components
+
+- **Scope**: `(priorityCount - 3) / 10`, clamped to [0, 0.5] — 0 issues = 0, 3 = 0, 8 = 0.5, 13+ = 0.5
+- **Cross-cutting keywords**: +0.25 fixed bonus if task description matches `/across all|every (skill|agent|repo)|repo-?wide|cross-cutting|rename across|massive refactor/i`
+- **Carryover**: mean of `effectiveness.carryover / effectiveness.planned_issues` over the last 5 sessions, then `ratio - 0.3` clamped to [0, 0.25]
+
+### Examples
+
+- 2 issues, no cross-cutting keywords, low carryover → score ≈ 0.0 (low) → feature +0.05
+- 8 issues, "rename across all skills", carryover 0.4 → score ≈ 0.5 + 0.25 + 0.1 = 0.85 (high) → feature −0.15, housekeeping −0.10
+- 5 issues, no keywords, carryover 0.2 → score ≈ 0.2 (low) → feature +0.05
+
+### Output
+
+`selectMode()` now returns `context_pressure: { score, components: { scope, keywords, carryover }, level }` on all
+return paths. The rationale string is annotated with `; pressure:<level>(<score>)` when level is `medium` or `high`.
+
+### API
+
+`computeContextPressure(signals)` is exported as a standalone pure function for testing and
+future callers (e.g. session-start Phase 7.5 AUQ rendering — deferred to W3-C5).
+
+### Constraints
+
+Context-pressure is NOT an Express Path gate (Express Path is structural: housekeeping + ≤3 issues).
+It is a complementary heuristic that surfaces in the session-start AUQ alongside the recommended mode.
+Missing signal fields contribute 0 to the score — no NaN propagation.
+
+## Open Questions (for Phase B-1 follow-up)
+
+- Learnings freshness window — default 30d? Configurable per-type or a single global TTL?
+- Backlog priority weighting — rule-based (`priority:critical = +0.2` confidence bonus) vs.
+  learned from historical completion rates?
+- Alternative-generation algorithm — top-N non-selected modes scored by partial signal match, or
+  fixed set derived from v0 heuristic branches?
+- Confidence computation — additive bonuses per signal (each signal adds a fixed delta) or
+  multiplicative penalties (each contradicting signal scales down a base score)?
+- Per-session-type thresholds — should `housekeeping` require higher confidence for auto-execution
+  than `deep` given the asymmetry in effort and risk?