session-orchestrator 3.16.0

package/docs/USER-GUIDE.md

@@ -0,0 +1,1403 @@
+# Session Orchestrator — User Guide
+
+Session Orchestrator is a Claude Code and Codex plugin that brings structured, wave-based development sessions to any project. It handles session planning, parallel agent execution, VCS integration, quality gates, and session close-out — so you can focus on deciding *what* to build while it orchestrates *how*.
+
+---
+
+## Table of Contents
+
+1. [Quick Start](#1-quick-start)
+2. [Bootstrap Gate](#2-bootstrap-gate)
+3. [Commands Reference](#3-commands-reference)
+4. [Session Types](#4-session-types)
+5. [Session Config Reference](#5-session-config-reference)
+6. [The Wave Pattern](#6-the-wave-pattern)
+7. [Workflow Walkthrough](#7-workflow-walkthrough)
+8. [VCS Integration](#8-vcs-integration)
+9. [Quality Gates](#9-quality-gates)
+10. [Design-Code Alignment (Pencil Integration)](#10-design-code-alignment-pencil-integration)
+11. [Ecosystem Health](#11-ecosystem-health)
+12. [Quality Discovery](#12-quality-discovery)
+13. [Harness Audit](#13-harness-audit)
+14. [Session Persistence](#14-session-persistence)
+15. [Safety Features](#15-safety-features)
+16. [Session Metrics](#16-session-metrics)
+17. [Cross-Session Learning](#17-cross-session-learning)
+18. [Adaptive Wave Sizing](#18-adaptive-wave-sizing)
+19. [Cheat Sheet](#19-cheat-sheet)
+20. [FAQ](#20-faq)
+21. [Troubleshooting](#21-troubleshooting)
+
+---
+
+## 1. Quick Start
+
+### Install the plugin
+
+#### Claude Code
+
+Claude Code installs plugins through slash commands inside a running session. There is no `claude plugin` shell CLI — run these commands in the Claude Code prompt:
+
+**From GitHub (recommended for end users):**
+
+```text
+/plugin marketplace add Kanevry/session-orchestrator
+/plugin install session-orchestrator@kanevry
+```
+
+**From a local clone (for contributors or offline work):**
+
+```text
+/plugin marketplace add /absolute/path/to/session-orchestrator
+/plugin install session-orchestrator@kanevry
+```
+
+After installation, starting Claude Code will display:
+
+```
+🎯 Session Orchestrator v3.x — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]
+```
+
+#### Codex
+
+Clone the repository, then run the installer from the plugin root:
+
+```bash
+git clone https://github.com/Kanevry/session-orchestrator.git
+cd session-orchestrator
+npm install
+node scripts/codex-install.mjs
+codex plugin list --available --json
+```
+
+The installer uses Codex's public `plugin marketplace add` and `plugin add` lifecycle. Marketplace configuration only makes the plugin discoverable; the list output must separately show `session-orchestrator@kanevry` as installed and enabled. Next, fully restart Codex or start a fresh task, run `/hooks`, and review the bundle before approving it. Hook trust is operator-controlled and is never written or bypassed by the installer.
+
+Rerun the installer after pulling changes. It performs `plugin add` on every run to refresh the installed bundle. The committed `.codex-plugin/plugin.json` version uses `+codex.<UTC timestamp>` as an explicit invalidation marker; the installer validates that tracked version but never rewrites it. For the full lifecycle, hook subset, and troubleshooting steps, see [`docs/codex-setup.md`](codex-setup.md).
+
+### Add Session Config to your project
+
+Open your project's Session Config host file and add a `## Session Config` section:
+
+- `CLAUDE.md` on Claude Code
+- `AGENTS.md` on Codex
+
+A minimal configuration looks like this:
+
+```markdown
+## Session Config
+
+test-command: npm test
+typecheck-command: npm run typecheck
+lint-command: npm run lint
+agents-per-wave: 6
+waves: 5
+persistence: true
+enforcement: warn
+vcs: github
+```
+
+If you skip this step, the plugin uses sensible defaults: `feature` type, 6 agents per wave, 5 waves, and auto-detected VCS. See [`docs/session-config-template.md`](session-config-template.md) for the full field walkthrough.
+
+### Run your first session
+
+```
+/session feature
+```
+
+The orchestrator researches your project state autonomously, presents findings with recommendations, and asks you to pick a direction. Once you agree on a plan, run `/go` to execute it across multiple parallel agents in structured waves. When done, run `/close` to verify, commit, and clean up.
+
+---
+
+## 2. Bootstrap Gate
+
+The Bootstrap Gate ensures every repository has a minimal structure before any orchestrator command runs. It exists because LLMs will rationalize their way past soft warnings in empty repos — Codex was observed bypassing the `/plan` Phase-0 abort entirely by falling back to "pragmatic paths", leaving repos unstructured. The gate replaces soft warnings with a state-file-backed, non-bypassable check that works identically on Claude Code, Codex, and Cursor.
+
+### When the gate runs
+
+Phase 0 of every orchestrator skill — `/session`, `/go`, `/close`, `/plan`, `/discovery`, and `/evolve` — checks for three conditions before doing anything else:
+
+1. A `CLAUDE.md` (or `AGENTS.md` on Codex) exists in the project root
+2. That file contains a `## Session Config` section
+3. `.orchestrator/bootstrap.lock` is committed to the repository
+
+If all three are present, the gate passes silently in under a second. If any are missing, the bootstrap flow starts.
+
+### What happens in an empty repo
+
+When the gate triggers, the orchestrator:
+
+1. Reads your first prompt to infer what kind of project this is
+2. Recommends an intensity tier (see below) with one sentence of rationale
+3. Asks you to confirm with a single yes/no question (or choose a different tier)
+4. Runs the bootstrap flow for your tier
+5. Commits `.orchestrator/bootstrap.lock` and exits
+
+You then re-run your original command and proceed normally. The gate never fires again for this repo unless you delete the lock file.
+
+### The three tiers
+
+Tiers are cumulative — Standard includes everything Fast does, Deep includes everything Standard does.
+
+#### Fast — demos, spikes, prototypes
+
+Suitable for: a Glücksrad demo, a weekend prototype, a proof-of-concept you may throw away.
+
+Sets up:
+- Minimal `CLAUDE.md` with `## Session Config` (3-4 fields)
+- `.orchestrator/bootstrap.lock`
+
+No VCS issues, no PRD, no test scaffolding required.
+
+#### Standard — MVPs, internal tools, small SaaS
+
+Suitable for: a small SaaS product, an internal admin tool, a personal project you intend to maintain.
+
+Sets up everything in Fast, plus:
+- Standard `CLAUDE.md` with full Session Config
+- Baseline directory structure per archetype
+- VCS labels created (`priority:*`, `status:*`, `type:*`)
+- Initial `STATUS.md` SSOT file
+
+#### Deep — customer-facing systems, team repos, production
+
+Suitable for: a customer-facing product, a shared team repository, anything with SLAs or compliance requirements.
+
+Sets up everything in Standard, plus:
+- Full PRD scaffolding in `docs/prd/`
+- CI configuration baseline
+- Security policy stub
+- Comprehensive label taxonomy
+- `CONTRIBUTING.md` with session workflow conventions
+
+### Public path (no local baseline)
+
+If you do not have a local `projects-baseline` directory configured, the gate falls back to plugin-bundled minimal templates. Five archetypes are available:
+
+| Archetype | Use for |
+|-----------|---------|
+| `_minimal` | Any project not matching a specific archetype |
+| `static-html` | Static sites, landing pages |
+| `node-minimal` | Node.js scripts, CLI tools, Express APIs |
+| `nextjs-minimal` | Next.js applications |
+| `python-uv` | Python projects using uv |
+
+On Claude Code, `claude init` generates a baseline and then the gate proceeds normally. On Codex and Cursor, the plugin-bundled templates are used directly.
+
+### The `/bootstrap` command
+
+You can also run the bootstrap flow explicitly, outside of any session:
+
+```
+/bootstrap                    # Auto-detect tier from project context
+/bootstrap --fast             # Force Fast tier
+/bootstrap --standard         # Force Standard tier
+/bootstrap --deep             # Force Deep tier
+/bootstrap --upgrade standard # Upgrade an existing Fast repo to Standard
+/bootstrap --retroactive      # Bootstrap an existing repo without resetting it
+```
+
+`--retroactive` is the recommended path for existing repos that predate the Bootstrap Gate — it adds the missing `CLAUDE.md` structure and lock file without touching your existing code or configuration.
+
+### Anti-bureaucracy promise
+
+- **Normal flow:** exactly 1 question (tier confirmation)
+- **Ambiguous public path:** maximum 2 questions (archetype selection + tier confirmation)
+- The gate is idempotent — re-running it on an already-bootstrapped repo is a no-op
+- `.orchestrator/bootstrap.lock` is the mechanical truth — no external service, no network call
+
+### Troubleshooting: retroactively bootstrapping an existing repo
+
+If you have an existing repo that was created before the Bootstrap Gate and every orchestrator command now stops at Phase 0:
+
+```
+/bootstrap --retroactive
+```
+
+This adds the required structure around your existing files without modifying them. It takes under a minute.
+
+---
+
+## 3. Commands Reference
+
+This section introduces the core commands of the session lifecycle — the ones the subsections below document in detail. Session Orchestrator ships many more; the full command inventory lives in [`docs/components.md`](components.md).
+
+| Command | Purpose | When to use |
+|---------|---------|-------------|
+| `/session [type]` | Start a new session | Beginning of a work session |
+| `/go` | Approve the plan and begin wave execution | After reviewing the proposed wave plan |
+| `/close` | End the session with verification and commits | When all waves are complete |
+| `/discovery [scope]` | Systematic quality discovery and issue detection | Anytime, or automatically during `/close` |
+| `/plan [mode]` | Structured project planning and PRD generation | Before starting a session, or standalone |
+| `/evolve [mode]` | Extract and manage cross-session learnings | After 2+ sessions, or to review/prune learnings |
+
+### `/session [type]`
+
+Starts a new development session. Accepts one argument: `housekeeping`, `feature`, or `deep`. If omitted, the type is read from your Session Config or defaults to `feature`.
+
+```
+/session feature
+/session housekeeping
+/session deep
+```
+
+This triggers autonomous research: git state, open issues, SSOT freshness, CI status, cross-repo health, and more. You then review findings and pick a direction before any code changes happen.
+
+### `/go`
+
+Approves the wave plan and begins execution. You can optionally pass additional instructions:
+
+```
+/go
+/go focus on the API endpoints first
+```
+
+This dispatches parallel subagents wave by wave. You do not need to intervene during execution — the orchestrator handles inter-wave reviews and plan adaptation automatically.
+
+### `/close`
+
+Ends the session. This runs a full verification against the agreed plan, creates issues for any gaps, runs quality gates, commits cleanly, pushes, mirrors (if configured), and presents a session summary.
+
+```
+/close
+```
+
+### `/plan [mode]`
+
+Structured requirement gathering, PRD generation, and issue creation. Accepts one argument: `new`, `feature`, or `retro`.
+
+```
+/plan new
+/plan feature
+/plan retro
+```
+
+**`/plan new`** — Full project kickoff. Gathers requirements across 3 waves of questions (core decisions, technical details, business scope), generates an 8-section PRD, optionally scaffolds the repository, and creates a prioritized Epic with sub-issues. Typically 30-45 minutes.
+
+**`/plan feature`** — Compact feature planning. Gathers requirements in 1-2 waves, generates a 5-section PRD with acceptance criteria, and creates feature sub-issues. Typically 5-15 minutes.
+
+**`/plan retro`** — Data-driven retrospective. Reads session metrics from `.orchestrator/metrics/sessions.jsonl`, surfaces trends and patterns, guides reflection, and creates improvement issues. Typically 10-20 minutes.
+
+**When to use `/plan` vs `/session`:**
+- `/plan` answers **"What should we build?"** — requirements, PRDs, issues
+- `/session` answers **"How do we build it?"** — wave planning, agent execution, verification
+
+`/plan` runs outside of sessions. Its output (PRD + issues) feeds into the next `/session`, which picks from those issues and executes them. You can skip `/plan` entirely and create issues manually — sessions work with any existing issues.
+
+**Optional:** `plan-baseline-path` in Session Config (for `/plan new` repo scaffolding from your own baseline). When absent, `/bootstrap` falls back to plugin-bundled minimal templates. Not required for `/plan feature` or `/plan retro`.
+
+---
+
+## 4. Session Types
+
+### Housekeeping
+
+Best for: git cleanup, SSOT refresh, CI fixes, branch merges, documentation updates.
+
+- **Execution model:** Serial (no wave structure)
+- **Agents:** 1-2 per task
+- **Typical duration:** Short
+- **Use when:** Your repo needs maintenance, not new features
+
+```
+/session housekeeping
+```
+
+### Feature
+
+Best for: frontend/backend feature work, implementing issues, standard development.
+
+- **Execution model:** 5 waves with parallel agents
+- **Agents:** 4-6 per wave (configurable)
+- **Typical duration:** Medium
+- **Use when:** You have feature issues to implement
+
+```
+/session feature
+```
+
+### Deep
+
+Best for: complex backend work, security audits, database refactoring, architecture changes.
+
+- **Execution model:** 5 waves with parallel agents
+- **Agents:** Up to 10-18 per wave (configurable)
+- **Typical duration:** Longer
+- **Use when:** The work requires extensive discovery, testing, or touches critical systems
+
+```
+/session deep
+```
+
+---
+
+## 5. Session Config Reference
+
+> **Skill authors:** The authoritative field reference used by all skills is [`docs/session-config-reference.md`](session-config-reference.md). Update that file when adding or changing Session Config fields.
+
+Add a `## Session Config` section to your project's Session Config host file to configure how Session Orchestrator behaves in that repository:
+
+- `CLAUDE.md` on Claude Code
+- `AGENTS.md` on Codex
+
+### Example
+
+```markdown
+## Session Config
+
+- **agents-per-wave:** 6
+- **waves:** 5
+- **pencil:** designs/app.pen
+- **cross-repos:** [api-service, shared-lib]
+- **ssot-files:** [.claude/STATUS.md]
+- **mirror:** github
+- **ecosystem-health:** true
+- **vcs:** gitlab
+- **gitlab-host:** gitlab.company.com
+- **health-endpoints:** [{name: "API", url: "https://api.example.com/health"}, {name: "Worker", url: "http://worker:8080/healthz"}]
+- **special:** "Always run database migrations before testing"
+- **test-command:** pnpm vitest run
+- **stale-issue-days:** 14
+- **persistence:** true
+- **plan-baseline-path:** ~/Projects/projects-baseline
+- **plan-default-visibility:** internal
+- **plan-prd-location:** docs/prd/
+- **plan-retro-location:** docs/retro/
+- **memory-cleanup-threshold:** 5
+- **enforcement:** warn
+- **isolation:** auto
+- **max-turns:** auto
+```
+
+### Field Reference
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `agents-per-wave` | integer | `6` | Maximum number of parallel subagents per wave. Higher values increase parallelism but use more resources. |
+| `waves` | integer | `5` | Number of execution waves for feature and deep sessions. |
+| `pencil` | string | none | Path to a `.pen` design file (relative to project root). Enables design-code alignment reviews after Impl-Core and Impl-Polish waves. |
+| `cross-repos` | list | none | Related repositories under `~/Projects/`. The orchestrator checks their git state and critical issues during session start. |
+| `ssot-files` | list | none | Single Source of Truth files to track for freshness (e.g., `STATUS.md`, `STATE.md`). Flagged if older than 5 days. |
+| `mirror` | string | `none` | Mirror target after push. Set to `github` to automatically push to a GitHub remote after every session commit. |
+| `ecosystem-health` | boolean | `false` | Enable service health checks at session start. Requires `health-endpoints` to be configured. |
+| `vcs` | string | auto-detect | Version control platform: `github` or `gitlab`. Auto-detected from git remote URL if not set. |
+| `gitlab-host` | string | from remote | Custom GitLab hostname. Only needed if the host cannot be inferred from the git remote URL. |
+| `health-endpoints` | list | none | Service URLs to check health. Each entry is an object with `name` and `url` fields. |
+| `special` | string | none | Repo-specific instructions. Freeform text that the orchestrator reads and follows during sessions. |
+| `test-command` | string | `npm test` | Custom test command. Used by quality gates for all test invocations. |
+| `typecheck-command` | string | `npm run typecheck` | Custom TypeScript check command. Set to `skip` for non-TS projects. |
+| `lint-command` | string | `npm run lint` | Custom lint command. Used by the Full Gate quality check at session end. |
+| `ssot-freshness-days` | integer | `5` | Days before an SSOT file is flagged as stale during session start. |
+| `plugin-freshness-days` | integer | `30` | Days before the plugin itself is flagged as potentially outdated. |
+| `recent-commits` | integer | `20` | Number of recent commits to display during session start git analysis. |
+| `issue-limit` | integer | `50` | Maximum issues to fetch when querying VCS during session start. |
+| `stale-branch-days` | integer | `7` | Days of inactivity before a branch is flagged as stale. |
+| `stale-issue-days` | integer | `30` | Days without progress before an issue is flagged for triage. |
+| `discovery-on-close` | boolean | `false` | Run discovery probes automatically during `/close`. |
+| `discovery-probes` | list | `[all]` | Probe categories to run: `all`, `code`, `infra`, `ui`, `arch`, `session`, `audit`, `vault`, `feature`. |
+| `discovery-exclude-paths` | list | `[]` | Glob patterns to exclude from discovery scanning (e.g., `vendor/**`, `dist/**`). |
+| `discovery-severity-threshold` | string | `low` | Minimum severity for reported findings: `critical`, `high`, `medium`, `low`. |
+| `discovery-confidence-threshold` | integer | `60` | Minimum confidence score (0-100) for discovery findings to be reported. Findings below this threshold are auto-deferred. |
+| `persistence` | boolean | `true` | Enable session resumption via STATE.md and session memory files. |
+| `plan-baseline-path` | string | none | Path to projects-baseline directory (e.g., `~/Projects/projects-baseline`). Optional. When absent, `/bootstrap` falls back to plugin-bundled minimal templates. Only required if you want to scaffold from your own baseline during `/plan new`. |
+| `plan-default-visibility` | string | `internal` | Default repo visibility for `/plan new`: `internal`, `private`, or `public`. |
+| `plan-prd-location` | string | `docs/prd/` | Directory where PRD documents are saved (relative to project root). |
+| `plan-retro-location` | string | `docs/retro/` | Directory where retrospective documents are saved (relative to project root). |
+| `memory-cleanup-threshold` | integer | `5` | Recommend `/memory-cleanup` after N accumulated session memory files. |
+| `memory-cleanup-soft-limit` | integer | `180` | Hard ceiling on accumulated memory files before the cleanup nudge escalates from soft suggestion to strong recommendation. PRD F2.2 / issue #502. |
+| `vault-mirror.quality.min-narrative-chars` | integer | `400` | Minimum body length (characters) before a learning or session note is mirrored to the vault. Notes shorter than this threshold are skipped. PRD F1.2 / issue #504. |
+| `vault-mirror.quality.min-confidence` | float | `0.5` | Minimum learning confidence (0.0..1.0) before a learning note is mirrored. Set to `0.0` to mirror every learning regardless of confidence. PRD F1.2 / issue #504. |
+| `cold-start.enabled` | boolean | `true` | Master toggle for the cold-start detector. When `false`, no idle-time nudges fire at session-start. PRD F1.3 / issue #500. |
+| `cold-start.nudge-after-hours` | integer | `1` | Hours of wall-clock idle (since the last session-end) before the cold-start detector fires a nudge. PRD F1.3 / issue #500. |
+| `cold-start.silence-after-sessions` | integer | `1` | Consecutive silent sessions (no commits, no learnings) before the cold-start detector fires a nudge. PRD F1.3 / issue #500. |
+| `enforcement` | string | `warn` | Hook enforcement level for scope and command restrictions: `strict`, `warn`, or `off`. |
+| `isolation` | string | `auto` | Agent isolation mode: `worktree`, `none`, or `auto`. `auto` resolves per-wave via the graduated default (#194): ≤2 agents → `none`, 3–4 agents on feature/deep → `worktree`, ≥5 agents → `worktree`, housekeeping 3–4 → `none`. See Section 15 "Isolation Graduation" below. |
+| `max-turns` | integer or string | `auto` | Max agent turns before PARTIAL. Auto: housekeeping=8, feature=15, deep=25. |
+
+> **Security:** Do not embed credentials, API keys, or auth tokens in Session Config fields — especially `health-endpoints` URLs. These values are stored in your config host file (`CLAUDE.md` / `AGENTS.md`) which may be committed to version control. Use header-based auth or separate secret management instead.
+
+### Minimal Config
+
+If you add no Session Config at all, the orchestrator uses these defaults:
+
+- Session type: `feature`
+- Agents per wave: `6`
+- Waves: `5`
+- VCS: auto-detected from git remote
+- Everything else: disabled/none
+
+See [examples](examples/) for project-specific configurations (Next.js, Express API, Swift iOS).
+
+---
+
+## 6. The Wave Pattern
+
+Feature and deep sessions execute work in structured waves, each assigned one of 5 roles. Each wave has a specific purpose, and agents within a wave run in parallel.
+
+### Wave Structure
+
+| Role | Purpose | Agents modify code? |
+|------|---------|---------------------|
+| **Discovery** | Understand the current state before changing anything | No (read-only) |
+| **Impl-Core** | Core feature work — the primary implementation | Yes |
+| **Impl-Polish** | Polish, fix Impl-Core issues, integration, edge cases | Yes |
+| **Quality** | Tests, TypeScript checks, lint, security review | Yes (tests only) |
+| **Finalization** | Documentation, issue cleanup, commit preparation | Minimal |
+
+### Role-to-Wave Mapping
+
+Roles map dynamically to the configured wave count (default: 5):
+
+| `waves` | Mapping |
+|---------|---------|
+| 3 | W1=Discovery+Impl-Core, W2=Impl-Polish+Quality, W3=Finalization |
+| 4 | W1=Discovery, W2=Impl-Core+Impl-Polish, W3=Quality, W4=Finalization |
+| 5 | W1=Discovery, W2=Impl-Core, W3=Impl-Polish, W4=Quality, W5=Finalization |
+| 6+ | W1=Discovery, W2-W3=Impl-Core (split), W4-W5=Impl-Polish (split), W6=Quality+Finalization |
+
+### Wave Details
+
+**Discovery**
+Agents audit affected code paths, verify assumptions from the plan, check existing test coverage, and identify edge cases. This wave is read-only: no files are modified. If discoveries warrant it, the plan is adjusted before Impl-Core begins.
+
+**Impl-Core**
+The primary implementation wave. Agents write core feature code, database changes, API endpoints, and primary UI components. Each agent has a clearly scoped set of files and acceptance criteria. Output: a working (possibly rough) implementation.
+
+**Impl-Polish**
+Agents fix issues discovered during Impl-Core, implement secondary features, handle integration between Impl-Core outputs, and address edge cases. If Pencil design review is configured, a design-code alignment check runs after this wave.
+
+**Quality**
+Before test writers run, the orchestrator dispatches 1-2 simplification agents that scan all files changed in the session (excluding test files) and clean up common AI-generated code patterns — unnecessary try-catch wrappers, over-documentation, re-implemented stdlib functions, and redundant boolean logic. These agents reference `slop-patterns.md` (produced by the discovery skill) and do not change functionality. After simplification, the remaining agents write and update tests, run quality checks per the quality-gates skill, and perform a security review. Goal: all tests passing, zero TypeScript errors, no lint violations.
+
+**Finalization**
+One or two agents update SSOT files, close or update issues, write session handover documentation, and prepare clean commits. No new feature work happens here.
+
+### Agent Counts by Session Type
+
+| Session Type | Discovery | Impl-Core | Impl-Polish | Quality | Finalization |
+|-------------|-----------|-----------|-------------|---------|-------------|
+| housekeeping | 2 | 2 | 1 | 1 | 1 |
+| feature | 4-6 | 6 | 4-6 | 4 | 2 |
+| deep | 6-8 | 6-10 | 6-8 | 6 | 2-4 |
+
+The `agents-per-wave` config value caps the maximum. These counts are guidelines — the orchestrator adjusts based on task complexity.
+
+### Inter-Wave Checkpoints
+
+Between each wave, the orchestrator:
+
+1. Reviews all agent outputs
+2. Checks for file conflicts between agents
+3. Runs verification based on wave role (Incremental after Impl-Core/Impl-Polish, Full Gate after Quality)
+4. Runs design review if configured (after Impl-Core and Impl-Polish roles)
+5. Adapts the plan for the next wave if needed (adds fix tasks, re-scopes)
+6. Reports progress to you
+
+---
+
+## 7. Workflow Walkthrough
+
+Here is what happens step by step when you run a full feature session.
+
+### Step 1: Start the session
+
+```
+/session feature
+```
+
+The orchestrator autonomously researches your project:
+
+- **Git analysis:** Branch state, recent commits, unpushed changes, stale branches
+- **VCS deep dive:** Open issues (categorized by priority), recently closed issues, open MRs/PRs, CI pipeline status, active milestones
+- **SSOT check:** Freshness of tracked files, TypeScript error count, test baseline
+- **Cross-repo status:** Git state and critical issues in related repositories
+- **Ecosystem health:** Service endpoint checks (if configured)
+- **Pattern recognition:** Recurring issue patterns, blocking chains, quick wins, synergies
+
+### Step 2: Review findings and pick a direction
+
+The orchestrator presents a structured overview:
+
+```
+## Session Overview
+- Type: feature
+- Repo: my-app on branch main
+- Git: 0 uncommitted, 0 unpushed, 3 open branches
+- VCS: 12 open issues (2 high, 4 medium), 1 open PR
+- Health: TypeScript: 0 errors | Tests: passing | CI: green
+- SSOT: STATUS.md fresh (2 days)
+
+## Recommended Focus
+Option A (recommended): Issues #42 + #45 — high synergy, shared code paths
+Option B: Issue #38 — standalone deep work, can be done independently
+Option C: Issues #50 + #51 + #52 — quick wins, clean up the backlog
+```
+
+You pick an option (or propose your own). The orchestrator does not proceed until you confirm.
+
+### Step 3: Review the wave plan
+
+After you choose a direction, the orchestrator decomposes the work into a role-based wave plan:
+
+```
+## Wave Plan (Session: feature)
+
+### Wave 1: Discovery (4 agents)
+- Agent 1: Audit API endpoint structure → src/api/ → map current routes
+- Agent 2: Verify database schema → prisma/schema.prisma → check relations
+...
+
+### Wave 2: Impl-Core (6 agents)
+- Agent 1: Implement new API route → src/api/users.ts → endpoint returns 200
+...
+
+### Inter-Wave Checkpoints
+- After Impl-Core: Design review (Pencil configured)
+- After Quality: Full quality gate
+
+Ready to execute? Use /go to begin.
+```
+
+You can request changes to the plan. When satisfied:
+
+### Step 4: Execute
+
+```
+/go
+```
+
+Waves execute automatically. Agents within each wave run in parallel. Between waves, the orchestrator reviews results, runs checks, and adapts the plan if needed. You see progress updates after each wave:
+
+```
+## Wave 2 (Impl-Core) Complete ✓
+- Agent 1: done — API route implemented, returns correct schema
+- Agent 2: done — Database migration created
+- Agent 3: done — Frontend form component built
+- Tests: 3 new passing | TypeScript: 0 errors
+- Design: ALIGNED
+- Adaptations for Impl-Polish: none
+```
+
+### Step 5: Close the session
+
+After the Finalization wave completes:
+
+```
+/close
+```
+
+The orchestrator:
+
+1. **Verifies** every planned item against the agreed plan (with evidence)
+2. **Creates issues** for any work that was not completed (carryover issues)
+3. **Runs quality gates:** TypeScript (0 errors), tests (passing), lint (clean), no debug artifacts
+4. **Updates SSOT** files with current metrics
+5. **Commits** using Conventional Commits format, staging files individually
+6. **Pushes** to origin
+7. **Mirrors** to GitHub (if configured)
+8. **Closes/updates issues** on your VCS platform
+9. **Presents a session summary** with completed items, carryovers, new issues, metrics, and recommendations for the next session
+
+---
+
+## 8. VCS Integration
+
+Session Orchestrator works with both GitHub and GitLab. It manages issues, merge requests / pull requests, labels, milestones, and CI status throughout the session.
+
+### Auto-Detection
+
+The VCS platform is detected from your git remote URL:
+
+- Remote contains `github.com` --> uses `gh` CLI
+- All other remotes --> uses `glab` CLI
+
+To override auto-detection, set `vcs` in your Session Config:
+
+```markdown
+- **vcs:** github
+```
+
+or
+
+```markdown
+- **vcs:** gitlab
+- **gitlab-host:** gitlab.company.com
+```
+
+### What the orchestrator does with your VCS
+
+**At session start:**
+- Lists open issues, categorized by priority and status labels
+- Lists recently closed issues (context from last session)
+- Checks active milestones
+- Lists open MRs/PRs
+- Checks CI pipeline status
+
+**During execution:**
+- Marks selected issues as `status:in-progress`
+- Adds comments to issues noting which wave is working on them
+
+**At session end:**
+- Closes resolved issues with a summary comment
+- Updates issue labels to reflect actual state
+- Creates carryover issues for partially-completed work
+- Creates new issues for discovered problems
+- Updates milestone progress
+
+### Label Taxonomy
+
+The orchestrator uses a structured label system for issue management. For the complete label taxonomy (priority, status, area, and type labels), see the **Label Taxonomy** section of the `gitlab-ops` skill (`skills/gitlab-ops/SKILL.md`).
+
+Create these labels in your VCS platform if they do not already exist. The orchestrator will use them automatically during session start (categorizing issues), execution (marking in-progress), and close-out (updating status).
+
+### GitHub Mirroring
+
+If your primary VCS is GitLab but you also maintain a GitHub mirror, configure:
+
+```markdown
+- **mirror:** github
+```
+
+The orchestrator pushes to the `github` remote after every session commit. The remote must already be configured in your git config.
+
+---
+
+## 9. Quality Gates
+
+Session Orchestrator enforces quality at two levels: inter-wave checks during execution, and a full quality gate at session end.
+
+### Session Reviewer Agent
+
+The `session-reviewer` is a dedicated agent that verifies work quality. It runs between waves (especially before Impl-Polish and after Quality) and at session end. It checks:
+
+1. **Implementation correctness** — Changed files match task descriptions. No incomplete implementations, placeholder values, or hardcoded data. Error handling follows project patterns.
+
+2. **Test coverage** — Every changed source file has a corresponding test file. Tests cover the new behavior (not just boilerplate). Tests pass when run.
+
+3. **TypeScript health** — typecheck per quality-gates skill reports zero errors. This is non-negotiable.
+
+4. **Security basics (OWASP quick check):**
+   - No hardcoded secrets or API keys
+   - User input validated at boundaries (e.g., with Zod)
+   - No unjustified `any` types
+   - No `console.log` in production code (except `warn`/`error`)
+   - SQL uses parameterized queries
+   - Auth checks present in server actions
+
+5. **Issue tracking accuracy** — Claimed issues have the correct status labels. Acceptance criteria from issues are actually met.
+
+6. **Silent failure analysis** — Catch blocks that swallow errors, empty error handlers, and fallback returns that hide failures.
+
+7. **Test depth check** — Tests exercise changed behavior (not just boilerplate), edge cases are present, assertion quality is adequate, and mock boundaries are correct.
+
+8. **Type design spot-check** — String parameters that should be unions, overly broad `any` types, and unused generics.
+
+Each finding includes a **confidence score** (0-100). Only findings with confidence >= 80 appear in the main report. Findings scored 50-79 are listed in a separate "Possible Issues" section for manual review.
+
+### Review Output
+
+The reviewer produces a structured verdict:
+
+```
+## Quality Review — Impl-Core
+
+### Implementation: PASS
+### Tests: WARN — missing test for src/api/users.ts
+### TypeScript: PASS — 0 errors
+### Security: PASS
+### Issues: PASS
+
+### Verdict: PROCEED (address test gap in Quality wave)
+```
+
+Possible verdicts:
+- **PROCEED** — quality is acceptable, continue to next wave
+- **FIX REQUIRED** — specific items must be addressed before continuing
+
+### Session-End Quality Gate
+
+Before any code is committed, `/close` runs all checks:
+
+| Check | Requirement |
+|-------|------------|
+| TypeScript | 0 errors |
+| Tests | All passing |
+| Lint | No errors (warnings acceptable) |
+| Debug artifacts | No `console.log`, `debugger`, or `TODO: remove` in changed files |
+| Git status | All changes accounted for |
+
+If any check fails and cannot be quickly fixed, the orchestrator creates a `priority:high` issue for immediate follow-up rather than committing broken code.
+
+### Deterministic Scripts
+
+Session Orchestrator includes bash scripts for critical workflow paths. These provide deterministic, testable alternatives to agent-interpreted instructions:
+
+- `scripts/parse-config.mjs` — Parses `## Session Config` from a config host file, outputs validated JSON with all 40+ fields and defaults applied. Run: `node scripts/parse-config.mjs [path/to/CLAUDE.md|AGENTS.md]`
+- `scripts/run-quality-gate.mjs` — Runs quality gates with structured JSON output. Supports 4 variants: baseline, incremental, full-gate, per-file.
+- `scripts/validate-wave-scope.mjs` — Validates wave-scope.json before enforcement hooks consume it. Checks for path traversal, absolute paths, and required fields.
+
+Run `npm test` to execute the vitest suite.
+
+---
+
+## 10. Design-Code Alignment (Pencil Integration)
+
+If your project uses Pencil (`.pen`) design files, the orchestrator can automatically compare your implementation against the design after each implementation wave.
+
+### Setup
+
+Add the path to your `.pen` file in Session Config:
+
+```markdown
+- **pencil:** designs/app.pen
+```
+
+The path is relative to your project root. The orchestrator verifies the file exists during session start.
+
+### How it works
+
+After **Impl-Core** and **Impl-Polish** waves, the orchestrator:
+
+1. Opens the `.pen` file via Pencil MCP
+2. Finds design frames relevant to the current wave's UI work
+3. Screenshots those frames
+4. Reads the actual UI files changed in the wave
+5. Compares: layout structure, component hierarchy, visual elements (headings, buttons, inputs, cards), responsive behavior
+
+### Alignment Reports
+
+Each design review produces one of three verdicts:
+
+| Verdict | Meaning | Action |
+|---------|---------|--------|
+| **ALIGNED** | Implementation matches design | Proceed as planned |
+| **MINOR DRIFT** | Small differences (spacing, colors, minor layout) | Fix tasks added to next wave automatically |
+| **MAJOR MISMATCH** | Significant deviation from design | User informed, revised plan proposed |
+
+### Example output
+
+```
+## Wave 2 (Impl-Core) Complete ✓
+...
+- Design: MINOR DRIFT — card grid uses 3 columns instead of designed 2-column layout
+- Adaptations for Impl-Polish: Agent 2 assigned to fix card grid layout
+```
+
+### Without Pencil
+
+Pencil integration is entirely optional. If no `pencil` path is configured, design reviews are skipped with no impact on the rest of the session workflow.
+
+---
+
+## 11. Ecosystem Health
+
+For projects with deployed services or multiple related repositories, the orchestrator can check ecosystem health at session start.
+
+### Setup
+
+Enable ecosystem health and configure your endpoints in Session Config:
+
+```markdown
+- **ecosystem-health:** true
+- **health-endpoints:** [{name: "API", url: "https://api.example.com/health"}, {name: "Dashboard", url: "http://localhost:3000/api/health"}]
+- **cross-repos:** [api-service, shared-lib]
+```
+
+### What gets checked
+
+**Service health endpoints:**
+Each configured endpoint is queried with a simple HTTP check. If the endpoint returns JSON with a `status` field, that value is reported. Otherwise, the check reports OK or unreachable.
+
+**Cross-repo critical issues:**
+For each related repository, the orchestrator queries open issues with `priority:critical` or `priority:high` labels. This surfaces blocking problems in other parts of your ecosystem before you start working.
+
+**CI pipeline status:**
+The latest CI pipeline runs are checked for the current repository.
+
+### Health Report
+
+The report appears in the session overview:
+
+```
+## Ecosystem Health
+| Service   | Status      |
+|-----------|-------------|
+| API       | OK          |
+| Dashboard | unreachable |
+
+Critical issues: 2 across cross-repos
+CI: green
+```
+
+Any service that is down or any critical issue count above zero is flagged as requiring attention.
+
+### Graceful Degradation
+
+If `health-endpoints` is not configured, the service table is omitted. If `cross-repos` is not configured, the cross-project issue scan is omitted. The orchestrator does not fail — it simply skips the unconfigured checks.
+
+---
+
+## 12. Quality Discovery
+
+The `/discovery` command runs systematic quality probes to find issues that don't have VCS issues yet.
+
+### Usage
+
+```
+/discovery              # Scan all categories
+/discovery code         # Code quality only
+/discovery session      # Session gap analysis only
+/discovery code,session # Multiple categories
+```
+
+### Scope Options
+
+| Scope | Probes | Focus |
+|-------|--------|-------|
+| `all` | 23 probes | Everything (default) |
+| `code` | 8 probes | Hardcoded values, dead code, AI slop, type safety, tests, security |
+| `infra` | 4 probes | CI pipelines, env config, dependencies, deployments |
+| `ui` | 3 probes | Accessibility, responsive design, design drift |
+| `arch` | 3 probes | Circular deps, complexity hotspots, dependency security |
+| `session` | 5 probes | Gap analysis, hallucination check, stale issues, dependency chains, claude-md audit |
+
+### How It Works
+
+1. **Stack Detection** -- Detects your tech stack (JS/TS, Python, Docker, etc.) and activates relevant probes
+2. **Probe Execution** -- Runs probes in parallel as read-only subagents
+3. **Verification** -- Re-reads files to confirm findings, discards false positives
+4. **Interactive Triage** -- Critical/High findings reviewed individually; Medium/Low batched by category
+5. **Issue Creation** -- Approved findings become VCS issues with `type:discovery` label
+
+### Embedded Mode
+
+Set `discovery-on-close: true` in Session Config to automatically run discovery during `/close`. In embedded mode, critical/high findings become issues; medium/low are listed in the session report.
+
+### Confidence Scoring
+
+Each verified finding receives a confidence score from 0 to 100 that reflects how trustworthy the detection is. The score starts at a baseline of 40 and adds points from three factors: **pattern specificity** (how specific the match pattern is — generic patterns score lower), **file context** (whether surrounding code reinforces the finding), and **historical signal** (whether the same issue has appeared in prior discovery runs). Each factor contributes 0, 10, or 20 points, so scores range from 40 to 100 in practice.
+
+Findings below the confidence threshold are **auto-deferred** — they skip interactive triage entirely and appear in a collapsed summary instead. The threshold is controlled by `discovery-confidence-threshold` in your Session Config (default: `60`). Raise it if you are seeing too many false positives in triage; lower it if you want more aggressive detection. Auto-deferred findings are not lost — you can review them anytime with `/discovery --include-deferred`.
+
+One exception: findings with **critical** severity always receive a minimum confidence of 70, regardless of how the three factors score. This ensures that critical issues — potential security holes, data-loss risks — are never silently deferred. They always appear in interactive triage.
+
+```yaml
+## Session Config
+discovery-confidence-threshold: 60   # default; raise to reduce noise
+```
+
+---
+
+## 13. Harness Audit
+
+The harness audit scores this repository against the session-orchestrator rubric — a structured set of checks that verify the repo is set up correctly and the orchestrator has what it needs to run reliably. Run it whenever you want a baseline health reading or after making structural changes to the project setup.
+
+### How to run
+
+```
+/harness-audit
+```
+
+Or directly from the shell:
+
+```bash
+node scripts/harness-audit.mjs
+```
+
+No flags. The script always audits the current working directory / repo root.
+
+### What it produces
+
+- **stdout** — a JSON record matching the audit schema (see below)
+- **stderr** — a concise human-readable summary
+- **`.orchestrator/metrics/audit.jsonl`** — the same record appended as a single JSONL line for historical tracking
+
+### The 9 categories
+
+| Category | What it checks |
+|----------|----------------|
+| Session Discipline | STATE.md lifecycle, session-type usage, turn-limit compliance |
+| Quality Gate Coverage | Test command configured, typecheck command configured, lint command configured |
+| Hook Integrity | All registered hook handlers point to existing files |
+| Persistence Health | sessions.jsonl present and parseable, learnings.jsonl consistent |
+| Plugin-Root Resolution | Plugin path resolves correctly; bootstrap.lock committed |
+| Config Hygiene | Session Config fields are valid types; no unknown fields; no embedded secrets |
+| Policy Freshness | blocked-commands.json present; rubric_version matches `2026-06` |
+| Large-Codebase Readiness | Layered instruction files, a navigable codebase map, LSP/language-server tooling, scoped test/lint commands, a version-controlled destructive-command deny-list, and a lean delegated root |
+| Skill-Health Surfacing | Skill-invocation telemetry hygiene, the skill-health scorer module wired correctly, and an advisory (never-scored) verdict tally — absence of adoption is a healthy state, not a defect |
+
+### Severity escalation
+
+| Score | Level | Action |
+|-------|-------|--------|
+| ≥ 7/10 | Info | No action required |
+| 5–7/10 | Medium finding | Review and address in next session |
+| < 5/10 | High finding | Surfaces automatically via `/discovery audit` |
+
+### Rubric version and bump policy
+
+The current rubric version is `2026-06`. It is embedded in every audit record as the `rubric_version` field. When session-orchestrator releases a minor version that changes the rubric, the version string is bumped via a conventional commit (`chore: bump rubric version to YYYY-MM`). Older records in `audit.jsonl` retain their original `rubric_version` and remain valid — use the field to filter when comparing across versions.
+
+### Related commands
+
+`/discovery audit` runs only the harness-audit probe within the discovery framework, without the full multi-category scan.
+
+---
+
+## 14. Session Persistence
+
+Session Orchestrator persists session state so you can resume after crashes, pauses, or context window exhaustion.
+
+### STATE.md
+
+Lives at `.claude/STATE.md` in your project. Contains YAML frontmatter (`session-type`, `branch`, `issues`, `started`, `status`, `current-wave`, `total-waves`) and a Markdown body tracking the Current Wave, Wave History, and any Deviations from the plan. Written by the wave-executor after each wave; read by session-start on the next `/session` invocation.
+
+### Session Continuity
+
+When you run `/session`, the orchestrator checks for an existing STATE.md:
+
+- **`status: active`** -- Crashed or interrupted session detected. You are offered the choice to resume from the last completed wave or start fresh.
+- **`status: paused`** -- Intentional pause (e.g., you closed Claude Code mid-session). Resume picks up where you left off.
+- **`status: completed`** -- Normal end state. No resume offered; a new session starts cleanly.
+
+### Session Memory
+
+After each session, `/close` writes a memory file to `~/.claude/projects/<project>/memory/session-<date>.md` containing Outcomes, Learnings, and Next Session recommendations. On the next `/session`, the orchestrator reads the last 2-3 session memory files for context continuity across sessions.
+
+When memory files accumulate past the `memory-cleanup-threshold` (default: 5), the orchestrator recommends running `/memory-cleanup` to consolidate them.
+
+### Disabling Persistence
+
+Set `persistence: false` in your Session Config to disable STATE.md writing and session memory. Sessions will not be resumable and will not carry context forward.
+
+---
+
+## 15. Safety Features
+
+### Scope Enforcement
+
+Before each wave, the wave-executor writes `.claude/wave-scope.json` defining the allowed file paths and blocked commands for that wave's agents. PreToolUse hooks validate Edit/Write operations against `allowedPaths` and Bash commands against `blockedCommands`.
+
+Enforcement levels (configured via `enforcement`):
+
+| Level | Behavior |
+|-------|----------|
+| `strict` | Out-of-scope operations are denied |
+| `warn` | Out-of-scope operations are allowed but logged with a warning |
+| `off` | No enforcement; agents have full access |
+
+### Prerequisites
+
+Scope and command enforcement hooks require `jq` to be installed. If `jq` is not available, hooks degrade gracefully — all operations are allowed with a warning to stderr. Install `jq` for enforcement to be active:
+
+- **macOS**: `brew install jq`
+- **Ubuntu/Debian**: `sudo apt-get install jq`
+- **Alpine**: `apk add jq`
+
+### Circuit Breaker
+
+The orchestrator enforces turn limits per session type to prevent runaway execution:
+
+| Session Type | Default Max Turns |
+|-------------|-------------------|
+| housekeeping | 8 |
+| feature | 15 |
+| deep | 25 |
+
+Override with `max-turns` in Session Config, or set to `auto` for these defaults.
+
+The circuit breaker also detects execution spirals: a file edited 3+ times within a single agent's execution, repeated identical errors, or self-reverts. Recovery depends on the failure mode:
+
+- **FAILED** -- A fix task is created for the next wave
+- **PARTIAL** -- Completed work is carried forward; remaining tasks become carryover issues
+- **SPIRAL** -- Changes are reverted and the scope is narrowed before retrying
+
+### Worktree Isolation
+
+When `isolation` is set to `worktree`, each subagent gets its own git worktree. This prevents file conflicts between agents working in parallel within the same wave. When set to `none`, all agents work in the coordinator's working tree in-place.
+
+### Isolation Graduation (#194)
+
+`isolation: auto` (the default) is **not** a session-type switch — it is resolved per wave using the graduated default:
+
+| agentCount | sessionType | resolved |
+|---|---|---|
+| ≤ 2 | any | `none` |
+| 3–4 | housekeeping | `none` |
+| 3–4 | feature / deep | `worktree` |
+| ≥ 5 | any | `worktree` |
+
+The reason: worktrees are a tax, not a free lunch. Two full repo copies per wave, build artifacts duplicated, and merge-back risk when the coordinator commits inline. On small waves (1–2 agents on partitioned scopes) the tax is not worth paying — in-place dispatch is cleaner. On larger waves the isolation actually matters.
+
+**Overrides:**
+- Explicit `isolation: worktree` or `isolation: none` in Session Config disables the graduation entirely.
+- Session-plan may emit `collision-risk: high` on a wave spec to force `worktree` even at ≤2 agents — use it when agents will touch the same file.
+
+**Enforcement auto-promote:** when isolation resolves to `none`, `enforcement: warn` auto-promotes to `strict` for that wave. Worktrees provide filesystem-level isolation; in-place dispatch relies solely on the scope hook, so it must be hard. Explicit `enforcement: off` is respected.
+
+### Base-Ref Freshness (#195)
+
+Even with graduated isolation, worktree dispatch still carries a subtle risk: if the coordinator commits inline to `main` AFTER a worktree agent was created, the agent's merge-back silently overwrites those inline commits (the agent's base-ref is stale). This is not theoretical — it happened twice consecutively on 2026-04-20.
+
+The fix: wave-executor persists worktree meta at creation time (`.orchestrator/tmp/worktree-meta/<suffix>.json`) recording `baseSha`, `baseRef`, and `createdAt`. Before each merge-back, it checks whether `main` has advanced. Four outcomes:
+
+- **pass** — base matches current `main`. Merge-back proceeds normally.
+- **warn** — `main` advanced, but drift does not overlap the agent's scope. Log and proceed.
+- **block** — `main` advanced AND drift overlaps the agent's scope. Merge-back is refused; coordinator reconciles manually or rebases.
+- **no-meta** — meta missing/corrupted. Falls back to manual diff review.
+
+You do not configure this guard — it runs automatically for every `isolation: worktree` dispatch when persistence is enabled. The freshness events are logged to `.orchestrator/metrics/events.jsonl` as `event: freshness_check` for post-hoc analysis.
+
+---
+
+## 16. Session Metrics
+
+Session Orchestrator tracks metrics across sessions to provide historical trends and inform future planning.
+
+### What is tracked
+- **Per-wave**: duration (wall-clock), agent count, files changed, quality check result
+- **Per-session**: total duration, total waves, total agents, total files changed, agent summary (complete/partial/failed/spiral)
+
+### Storage
+Metrics are stored in `.orchestrator/metrics/sessions.jsonl` — one JSON line per session, append-only. This file is created automatically on first session close.
+
+### Historical Trends
+During session-start (Phase 7), the last 5 sessions are displayed as a trend table:
+
+| Session | Type | Duration | Waves | Agents | Files Changed |
+|---------|------|----------|-------|--------|---------------|
+
+If fewer than 2 sessions exist, the message "Not enough history for trends (need 2+)" is displayed.
+
+### Quality Gates Output
+Quality gates (Incremental and Full Gate variants) produce structured JSON output for metrics integration, including duration, check status, and error details.
+
+### Effectiveness Tracking
+
+After 5 or more completed sessions, session-start automatically computes effectiveness metrics from `sessions.jsonl` and surfaces them in the **Project Intelligence** section of the session overview. Three metrics are tracked:
+
+- **Completion rate trend** — averages `effectiveness.completion_rate` over the last 5 sessions. If the rate is below 0.6, the orchestrator suggests reducing scope. If above 0.9, it confirms that current sizing works well.
+- **Discovery probe value** — if the ratio of actioned findings to total findings stays below 0.1 across 3 or more sessions for a probe category, that category is flagged as low-value and may be excluded from future discovery runs.
+- **Carryover pattern** — if the ratio of carryover issues to planned issues exceeds 0.3 across 3 or more sessions, the orchestrator suggests smaller scope or switching to deep sessions to reduce persistent overflow.
+
+These metrics are only displayed once enough session history exists; projects with fewer than 5 sessions see the standard trend table instead.
+
+> **Requires:** `persistence: true` (default) in Session Config.
+
+---
+
+## 17. Cross-Session Learning
+
+The learning system captures patterns from completed sessions and surfaces them in future sessions as "Project Intelligence."
+
+### What is learned
+- **Fragile files**: files that needed 3+ iterations or caused cascading failures
+- **Effective sizing**: which agent counts worked for different complexity levels
+- **Recurring issues**: issue patterns that appear across waves (type errors, missing imports)
+- **Scope guidance**: how many issues fit comfortably in one session
+- **Deviation patterns**: plan adaptations that recur across sessions (scope changes, unexpected blockers)
+
+### Storage
+Learnings are stored in `.orchestrator/metrics/learnings.jsonl` — one JSON line per learning.
+
+### Confidence System
+Each learning has a confidence score (0.0 to 1.0):
+- New learnings start at **0.5**
+- Confirmed by a subsequent session: **+0.15**
+- Contradicted by a subsequent session: **-0.2**
+- Learnings at **0.0** are removed
+- Learnings expire after **90 days**
+- Only learnings with confidence **> 0.3** are surfaced
+
+### Lifecycle
+1. **Collection** (session-end Phase 3.5a): analyze completed session, extract learnings
+2. **Consumption** (session-start Phase 5.6 + session-plan Step 1): read and apply learnings
+3. **Pruning** (session-end Phase 3.6): remove expired and zero-confidence entries
+
+> **Requires:** `persistence: true` (default) in Session Config.
+
+### Managing Learnings with /evolve
+
+The `/evolve` command gives you manual control over the learning system.
+
+#### Analyze Mode (default)
+
+```
+/evolve
+/evolve analyze
+```
+
+Reads `sessions.jsonl`, extracts patterns (fragile files, sizing, scope, recurring issues, deviations), deduplicates against existing learnings, and presents candidates for your approval via interactive selection. Only confirmed learnings are saved.
+
+**When to use:** After 2-3 sessions to validate the tool, or when you suspect the learning system is missing patterns.
+
+#### Review Mode
+
+```
+/evolve review
+```
+
+Displays all active learnings in a formatted table grouped by type. You can:
+- **Boost** confidence (+0.15) for learnings you've validated
+- **Reduce** confidence (-0.2) for learnings that seem wrong
+- **Delete** specific learnings
+- **Extend** expiry (+90 days) for learnings you want to keep longer
+
+**When to use:** When Project Intelligence suggestions seem off, or to prune stale learnings.
+
+#### List Mode
+
+```
+/evolve list
+```
+
+Read-only display of all active learnings with confidence scores and expiry dates. Shows high-confidence (>0.7) and expiring-soon (<14 days) counts.
+
+**When to use:** Quick check of what the system has learned, without making changes.
+
+---
+
+## 18. Adaptive Wave Sizing
+
+Instead of fixed agent counts, the orchestrator scores session complexity and adjusts agent allocation dynamically.
+
+### Complexity Scoring
+Three factors are scored (0-2 points each):
+
+| Factor | 0 points | 1 point | 2 points |
+|--------|----------|---------|----------|
+| Files to change | 1-5 | 6-15 | 16+ |
+| Cross-module scope | 1 directory | 2-3 directories | 4+ directories |
+| Issue count | 1 issue | 2-3 issues | 4+ issues |
+
+### Complexity Tiers
+- **Simple** (0-1 points): fewer agents per wave
+- **Moderate** (2-3 points): standard allocation
+- **Complex** (4-6 points): maximum agents per wave
+
+### Dynamic Scaling Between Waves
+After each wave, agent count is adjusted based on performance:
+- All agents fast + no issues → reduce next wave
+- Failures or broken code → add fix agents
+- Scope expansion → scale up
+- Quality regressions → targeted fix agents
+
+The `agents-per-wave` config value always caps the maximum.
+
+> **Note:** Housekeeping sessions skip complexity scoring and use fixed counts.
+
+---
+
+## 19. Cheat Sheet
+
+### Commands
+
+```
+/session feature       Start a feature session
+/session housekeeping  Start a cleanup/maintenance session
+/session deep          Start a deep work session (complex, many agents)
+/go                    Approve plan, begin wave execution
+/go <instructions>     Approve plan with additional guidance
+/close                 Verify all work, commit, push, clean up issues
+/discovery             Run quality probes across all categories
+/discovery code        Scan code quality only
+/discovery code,arch   Scan multiple categories
+/plan new              Plan a new project (PRD + repo setup + issues)
+/plan feature          Plan a feature (compact PRD + issues)
+/plan retro            Run a data-driven retrospective
+/evolve                Analyze sessions, extract learnings (default: analyze)
+/evolve analyze        Extract patterns from session history
+/evolve review         Interactively manage existing learnings
+/evolve list           Display active learnings
+```
+
+### Session Config (add to `CLAUDE.md` or `AGENTS.md`)
+
+```markdown
+## Session Config
+
+- **agents-per-wave:** 6
+- **waves:** 5
+- **vcs:** github
+- **gitlab-host:** gitlab.company.com
+- **mirror:** github
+- **pencil:** designs/app.pen
+- **cross-repos:** [other-repo]
+- **ssot-files:** [.claude/STATUS.md]
+- **ecosystem-health:** true
+- **health-endpoints:** [{name: "API", url: "https://api.example.com/health"}]
+- **special:** "Run migrations before testing"
+- **discovery-on-close:** true
+- **discovery-probes:** [code, arch]
+- **discovery-severity-threshold:** medium
+- **persistence:** true
+- **enforcement:** warn
+- **isolation:** auto
+- **max-turns:** auto
+```
+
+### Typical Session Flow
+
+```
+/plan feature             # (Optional) Define requirements → PRD + issues
+/session feature          # Research + recommendations → pick issues
+  (pick a direction)      # User chooses focus
+  (review wave plan)      # Orchestrator proposes role-based wave plan
+/go                       # Execute waves with parallel agents
+  (role-based waves execute) # Automatic, with inter-wave reviews
+/close                    # Verify, commit, push, summarize
+/plan retro               # (Optional) Retrospective → improvement issues
+```
+
+### Wave Quick Reference
+
+```
+Discovery       Validation & read-only audit
+Impl-Core       Primary implementation (core work)
+Impl-Polish     Fix, integrate, polish, edge cases
+Quality         Tests, TypeScript, lint, security
+Finalization    Documentation, issues, commits
+```
+
+---
+
+## 20. FAQ
+
+### Can I use this with GitHub?
+
+Yes. The orchestrator auto-detects your VCS platform from the git remote URL. If your remote points to `github.com`, it uses the `gh` CLI. You can also force it with `vcs: github` in Session Config. Both GitHub and GitLab are fully supported for issues, PRs/MRs, CI status, and milestones.
+
+### What if an agent fails during a wave?
+
+The wave executor does not ignore failures. If an agent produces broken code or reports errors, the orchestrator adds fix tasks to the next wave. If an agent times out, it is re-dispatched with a smaller scope. If there is a major blocker, the orchestrator informs you and proposes a revised plan for the remaining waves.
+
+### Can I change the plan mid-session?
+
+Yes. Between each wave, the orchestrator reviews results and can adapt the plan. If you need to change direction, you can communicate that and the remaining waves will be re-scoped. The orchestrator documents every deviation from the original plan so the session summary remains accurate.
+
+### How many agents run in parallel?
+
+This is controlled by the `agents-per-wave` setting in your Session Config. The default is 6. For deep sessions, you can increase this to 10-18. All agents within a single wave run in parallel; the orchestrator waits for all of them to complete before starting the next wave.
+
+### Do I need Pencil?
+
+No. Pencil design integration is entirely optional. If you do not configure a `pencil` path in Session Config, design-code alignment reviews are simply skipped. Everything else works the same.
+
+### What is the Soul system?
+
+The Soul is a personality layer that shapes how the orchestrator communicates and makes decisions. It defines the orchestrator as a seasoned engineering lead who drives outcomes — direct, opinionated, systems-thinking, pragmatic. It affects communication style (recommendations first, not analysis), decision-making priorities (user safety > productivity > code quality > ecosystem health > speed), and values (pragmatism over perfection, evidence over assumptions). You do not need to configure it; it is built into the plugin.
+
+### Does the orchestrator commit automatically?
+
+No. The orchestrator never commits code until you run `/close`. During wave execution, agents do not commit independently — the coordinator handles all commits at session end after running quality gates. This ensures only verified, clean code is committed.
+
+### What happens to unfinished work?
+
+During `/close`, any work that was planned but not completed is documented. The orchestrator creates carryover issues on your VCS platform with the title prefix `[Carryover]`, including context on what was done and what remains. Nothing is silently dropped.
+
+### Can I use this across multiple repos?
+
+Yes. Configure `cross-repos` in your Session Config with the names of related repositories (located under `~/Projects/`). The orchestrator checks their git state and critical issues at session start, giving you ecosystem-wide awareness.
+
+### When should I use `/plan` vs creating issues manually?
+
+`/plan` provides structured requirement gathering with parallel research agents, auto-prioritization, and PRD documents for reference. Use it when you want a thorough requirements process. Skip it when you already know exactly what to build — just create issues manually and run `/session`.
+
+### What's the difference between `/plan new` and `/plan feature`?
+
+`/plan new` is for brand-new projects — it scaffolds a repository, creates a full PRD, and generates an Epic with sub-issues. `/plan feature` is for adding a feature to an existing project — it produces a compact PRD and feature issues. Use `/plan new` once per project, `/plan feature` once per feature.
+
+### Can I run `/plan` during an active session?
+
+No. `/plan` runs outside of sessions. The session scope is locked after `/session` + user alignment + `/go`. If new requirements emerge during a session, create them as issues for the next session or let `/close` generate carryover issues.
+
+---
+
+## 21. Troubleshooting
+
+### "glab: command not found" or "gh: command not found"
+
+The orchestrator needs the appropriate VCS CLI tool installed:
+
+- **GitLab:** Install `glab` — [https://gitlab.com/gitlab-org/cli](https://gitlab.com/gitlab-org/cli)
+- **GitHub:** Install `gh` — [https://cli.github.com](https://cli.github.com)
+
+After installing, authenticate:
+
+```bash
+glab auth login
+# or
+gh auth login
+```
+
+### "No issues found" when issues exist
+
+This usually means the CLI tool is not authenticated or is pointing at the wrong host.
+
+- Run `glab auth status` or `gh auth status` to verify authentication
+- For GitLab with a custom host, ensure `gitlab-host` is set in Session Config or that your `.env` / `.env.local` contains the correct `GITLAB_HOST`
+- Check that `git remote get-url origin` returns the expected URL
+
+### Plugin not loading
+
+For Codex, start with the public state view:
+
+```bash
+codex plugin list --available --json
+```
+
+Confirm that `session-orchestrator@kanevry` appears exactly once with `installed: true`, `enabled: true`, and the version committed in `.codex-plugin/plugin.json`. If it is only available, run `codex plugin add session-orchestrator@kanevry`. If it is missing or stale, run `codex plugin marketplace list --json`, remove the exact target with `codex plugin remove session-orchestrator@kanevry` when present, and rerun `node scripts/codex-install.mjs` from the clone. A healthy install still needs a fresh task plus operator review in `/hooks`; installation does not grant hook trust.
+
+The installer removes only the allowlisted legacy IDs `session-orchestrator@openai-curated` and `session-orchestrator@local`; those exact IDs can also be removed through `codex plugin remove`. For a conflicting `kanevry` source, use `codex plugin marketplace remove kanevry` and rerun the installer from the intended clone. Any other pre-public plugin/config/cache/hook-state residue is unsupported: do not modify private Codex files; file an issue with `codex --version` plus the public plugin and marketplace list output.
+
+For Claude Code, run these commands inside a Claude Code session, not in your shell:
+
+```text
+/plugin marketplace add /absolute/path/to/session-orchestrator
+/plugin install session-orchestrator@kanevry
+```
+
+### "tsgo: command not found"
+
+The default typecheck command is `npm run typecheck`. If your project's `typecheck` script invokes `tsgo`, install it or change `typecheck-command` to the runner your project actually uses:
+
+```bash
+npm install -g @anthropic-ai/tsgo
+```
+
+### Agents timing out
+
+If agents consistently time out during wave execution:
+
+- Reduce `agents-per-wave` in Session Config (fewer parallel agents = less resource contention)
+- Switch from `deep` to `feature` session type if you do not need the extra agent count
+- Check that your machine has sufficient resources for parallel agent execution
+
+### Design review skipped unexpectedly
+
+If you configured `pencil` but design reviews are not running:
+
+- Verify the `.pen` file exists at the configured path (relative to project root)
+- Ensure the Pencil MCP server is running and accessible
+- Check the wave progress output for messages like "Pencil review skipped — .pen file unavailable"
+
+### Session Config not being read
+
+The orchestrator looks for a `## Session Config` section in your project's config host file. Ensure:
+
+- The file is named exactly `CLAUDE.md` on Claude Code or `AGENTS.md` on Codex, and is in the project root
+- The section heading is exactly `## Session Config`
+- Fields use the exact format: `- **field-name:** value`
+
+### Mirror push fails
+
+If `mirror: github` is configured but mirroring fails:
+
+- Verify a `github` remote exists: `git remote get-url github`
+- If not, add it: `git remote add github git@github.com:user/repo.git`
+- Ensure you have push access to the GitHub repository
+
+---
+
+## License
+
+Session Orchestrator is released under the MIT License. See the project repository for details: [https://github.com/Kanevry/session-orchestrator](https://github.com/Kanevry/session-orchestrator)