session-orchestrator 3.16.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bernhard Goetzendorfer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,64 @@
+Session Orchestrator
+Copyright (c) 2025-2026 Bernhard Goetzendorfer
+
+This product is licensed under the MIT License (see LICENSE).
+
+================================================================================
+Third-Party Attributions
+================================================================================
+
+This product includes material derived from `mattpocock/skills`
+(https://github.com/mattpocock/skills), used under the MIT License.
+
+Upstream: https://github.com/mattpocock/skills
+Commit:   90ea8eec03d4ae8f43427aaf6fe4722653561a42  (pinned, 2026-04-26)
+License:  MIT — Copyright (c) 2026 Matt Pocock
+
+The following files in this repository are vendored from `mattpocock/skills`
+at the commit above:
+
+  Byte-identical (verbatim) sub-files:
+    skills/architecture/LANGUAGE.md
+    skills/architecture/DEEPENING.md
+    skills/architecture/INTERFACE-DESIGN.md
+    skills/domain-model/CONTEXT-FORMAT.md
+    skills/domain-model/ADR-FORMAT.md
+
+  Adapted SKILL.md files (description and frontmatter re-tuned for our
+  trigger conventions; process body and structural content preserved):
+    skills/architecture/SKILL.md
+      (from improve-codebase-architecture/SKILL.md)
+    skills/domain-model/SKILL.md
+      (from domain-model/SKILL.md)
+    skills/ubiquitous-language/SKILL.md
+      (from ubiquitous-language/SKILL.md)
+
+Each adapted SKILL.md carries `derived-from: mattpocock/skills@90ea8ee`
+and `license: MIT` in its YAML frontmatter for traceability.
+
+The MIT License notice from the upstream project is reproduced below in
+satisfaction of the "above copyright notice and this permission notice
+shall be included in all copies or substantial portions of the Software"
+condition:
+
+    MIT License
+
+    Copyright (c) 2026 Matt Pocock
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+    all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,242 @@
+# Session Orchestrator
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-3.16.0-blue.svg)](CHANGELOG.md)
+[![Tests](https://img.shields.io/badge/tests-10%2C000%2B-brightgreen.svg)](docs/telemetry/telemetry-claims.md)
+
+Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on **Claude Code, Codex CLI, Cursor, and [Pi](docs/pi-setup.md)**.
+
+The same skills and commands run across all four, with platform-adapted hooks and enforcement (see [Platform support](#platform-support)). Community plugin (MIT, community-maintained) for solo devs and small teams.
+
+## Install
+
+> **Prerequisite:** Node.js 24 or later (`node --version`). v3.x runs as ES modules and needs a real Node runtime. [Install Node.js](https://nodejs.org/).
+
+| Platform | Install |
+|---|---|
+| **Claude Code** | `/plugin marketplace add Kanevry/session-orchestrator` then `/plugin install session-orchestrator@kanevry` (run both inside Claude Code). Also listed on the official community catalog: `/plugin install session-orchestrator@claude-community` (that catalog can lag HEAD). |
+| **Codex CLI** | `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/codex-install.mjs` |
+| **Cursor IDE** | `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/cursor-install.mjs /path/to/your/project` |
+| **Pi** | `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/pi-install.mjs /path/to/your/project --settings-only` (npm path `pi install npm:session-orchestrator` lands once published — not yet available) |
+
+For Claude Code, also install Node dependencies **once** (hooks import `zx`) and restart Claude Code:
+
+```bash
+cd "$(claude plugin dir session-orchestrator 2>/dev/null || echo ~/.claude/plugins/session-orchestrator)"
+npm install
+```
+
+Setup guides: [Codex](docs/codex-setup.md) · [Cursor IDE](docs/cursor-setup.md) · [Pi](docs/pi-setup.md). Per-IDE notes on `CLAUDE.md` vs `AGENTS.md`: [instruction-file-resolution](skills/_shared/instruction-file-resolution.md).
+
+## What makes it different
+
+- **Verification gates** — every wave ends at a typecheck/lint/test gate; a confidence-filtered session-reviewer catches regressions between waves, not only at the end.
+- **Wave orchestration** — five typed roles (Discovery → Impl-Core → Impl-Polish → Quality → Finalization), parallel subagents inside each wave, not one big batch.
+- **Persistent memory & learnings** — `STATE.md` survives crashes and resumes the next session; `/evolve` extracts confidence-scored patterns across sessions, nothing hidden.
+- **Multi-harness** — the same skills and commands run on Claude Code, Codex CLI, Cursor IDE, and Pi, with platform-adapted hooks and enforcement.
+
+## A session in three commands
+
+```text
+/session feature    # research + Q&A — inspect git, issues, history, then agree on scope
+/go                 # execute in five typed waves (fixed roles), with a quality gate between each
+/close              # verify every item, commit cleanly, file carryover issues for the rest
+```
+
+That is the whole loop. `/plan` and `/evolve` extend it (see [Lifecycle](#lifecycle-at-a-glance)), but you can start with just these three.
+
+## Quick Start
+
+Add a `## Session Config` section to your project's `CLAUDE.md` (Claude Code and Cursor IDE) or `AGENTS.md` (Codex CLI and Pi) — see [instruction-file-resolution](skills/_shared/instruction-file-resolution.md) for which file each platform reads. The smallest valid config is seven fields:
+
+```yaml
+## 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
+```
+
+Everything else is opt-in. See [`docs/session-config-template.md`](docs/session-config-template.md) for the full template and [`docs/session-config-reference.md`](docs/session-config-reference.md) for the canonical type and default reference.
+
+## What you get
+
+- **44 skills** for the session lifecycle (start, plan, execute, close, evolve), discovery, vault sync, MCP authoring, debugging, brainstorming, plan grilling, persona panels, cross-repo dispatch, learning→rule reconciliation, session-process eval, audits, and more
+- **24 slash commands** (`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/grill`, `/evolve`, `/autopilot`, `/dispatcher`, `/reconcile`, `/eval`, `/test`, `/debug`, …)
+- **15 typed subagents** (code-implementer, test-writer, security-reviewer, session-reviewer, qa-strategist, architect-reviewer, …)
+- **10 hook event types** enforcing scope, blocking destructive commands, gating templates-first, capturing telemetry — full on Claude Code; experimental, post-hoc, or bridged on the other platforms ([Platform support](#platform-support))
+- **10,000+ vitest tests** run on every commit ([telemetry methodology](docs/telemetry/telemetry-claims.md))
+
+Full component inventory: [`docs/components.md`](docs/components.md).
+
+## Lifecycle at a glance
+
+```mermaid
+flowchart TD
+    A["/plan [feature|retro]"] -->|optional, defines WHAT| B["/session [type]"]
+    B -->|research + Q&A| C["/go"]
+    C -->|5 waves with quality gates| D["/close"]
+    D -->|verifies + commits| E["/evolve [analyze]"]
+    E -->|extracts cross-session learnings| B
+    style C fill:#1f6feb,color:#fff
+    style D fill:#238636,color:#fff
+```
+
+`/plan` is optional — you can create issues manually and jump straight to `/session`. `/evolve` runs deliberately after 5+ sessions, not automatically.
+
+## How it works
+
+Most agentic-coding tools jump straight into writing code. Session Orchestrator adds a structured loop on top: research first, agree on scope, then execute in five typed waves with verification gates between them.
+
+```mermaid
+flowchart LR
+    W1["1·Discovery<br/>read-only audit"] --> G1{Gate}
+    G1 --> W2["2·Impl-Core<br/>primary code"]
+    W2 --> G2{Gate}
+    G2 --> W3["3·Impl-Polish<br/>integration, edges"]
+    W3 --> G3{Gate}
+    G3 --> W4["4·Quality<br/>simplify + tests"]
+    W4 --> G4{Full Gate}
+    G4 --> W5["5·Finalization<br/>commit + close"]
+    style G4 fill:#d29922,color:#000
+```
+
+When you type `/session feature`:
+
+1. **Phase analysis runs in parallel** — git state, open issues, recent commits, SSOT freshness, resource health, and prior-session memory are all inspected, then distilled into a structured Session Overview with a recommendation, not a wall of raw data.
+2. **You agree on scope** — through a tool-rendered picker (Claude Code) or a numbered list (Codex / Cursor / Pi). The orchestrator has an opinion and tells you what it would do.
+3. **The plan is decomposed into five waves** — Discovery (read-only), Impl-Core, Impl-Polish, Quality, Finalization. Each wave has a defined purpose and a deliverable; agent counts scale by session type.
+4. **`/go` executes** — agents work in parallel within a wave. A session-reviewer audits the output between waves on eight dimensions; only findings at confidence ≥ 80 reach you.
+5. **`/close` ships it** — every planned item is verified, quality gates run full, and unfinished work becomes carryover issues. Files are staged individually, so parallel sessions can't stomp each other.
+
+Two complementary commands round out the loop: **`/plan`** runs *before* a session when you need a PRD or retrospective; **`/evolve`** runs occasionally to surface patterns across sessions and feed them back at the next start.
+
+The system is markdown-driven config plus a thin Node runtime — skills, commands, and agents are Markdown with YAML frontmatter; `scripts/lib/*.mjs` and `hooks/*.mjs` handle dispatch, validation, and telemetry. Everything is plain text: if something goes wrong, you can read every file and see what happened.
+
+## Why this design
+
+- **Five typed waves, not one big batch.** Discovery first, so implementers start with shared context. Impl-Core before Impl-Polish, so architecture lands before integrations. Quality runs a *simplification pass* on AI-generated code **before** tests are written — otherwise tests pin the AI patterns into place.
+- **Inter-wave reviews, not just end-of-session.** Catching regressions between waves — not only at the end — stops a bad pattern from propagating into later work; the confidence floor filters speculative criticism so only high-signal findings reach you.
+- **State persists across crashes.** `STATE.md` records wave progress and deviations; the next `/session` offers to resume from the last completed wave.
+- **Hooks enforce, not just warn.** A pre-Bash guard blocks destructive shell commands, and pre-Edit scope enforcement blocks writes outside an agent's allowed paths — in main sessions and subagent waves alike (specifics in [Safety](#safety)). This hard enforcement is full on Claude Code; it degrades to experimental / post-hoc / bridged on Codex CLI, Cursor IDE, and Pi (see [Platform support](#platform-support)).
+- **Cross-session learning is opt-in and inspectable.** Every session writes a record; after 5+ sessions `/evolve analyze` extracts confidence-scored patterns you can read and prune. Nothing is hidden.
+- **VCS dual support, no lock-in.** Auto-detects GitLab or GitHub from your remote and drives the full lifecycle for both.
+
+## Recent highlights (v3.16.0)
+
+Every release is additive and backward-compatible. Highlights of the v3.16.0 line:
+
+- **Class-wide bold-key parser fix (`matchBlockHeader`)** — the `- **key:**` blind spot #823 fixed for one parser is now closed across all 34 Session-Config block parsers via a shared zero-import helper, with the inline-comment gotcha and drift-check raw-parity preserved.
+- **Vault-namespace de-collapse (`VAULT_CLEAR_SLUGS`)** — already-public repo slugs regain distinct vault namespaces (no more shared `redacted-repo/` bucket) while the public-mirror tracked-file scanner keeps blocking all private slugs.
+- **Vault board TTL self-healing** — preserved in-progress rows past the heartbeat TTL now flip to `force-closed`; narrative folders loose-match existing `01-projects/` folders instead of minting duplicates.
+- **Actionable freshness remediation (`/bootstrap --refresh-lock`)** — reason-aware banners plus a provenance-honest lock refresher (only two refresh fields written, original bootstrap provenance byte-identical).
+
+Previous line (v3.15.0): `/eval` session-process evaluation (standard v1), out-of-scope shell-write guard, per-context `baselines:` in owner.yaml, `bash-harness-pitfalls` rule, distribution foundation (landing page + submission kit), parser/config hardening bundle.
+
+Full version history: [CHANGELOG.md](CHANGELOG.md).
+
+## Comparison
+
+| Capability | Session Orchestrator | Manual `CLAUDE.md` | Other orchestrators |
+|---|---|---|---|
+| Session lifecycle (start → plan → execute → close) | Full, automated | Manual | Partial |
+| Typed waves with quality gates | 5 roles, progressive verification | None | Batch execution |
+| Session persistence and crash recovery | `STATE.md` plus memory files | None | Partial |
+| Scope and command enforcement hooks | PreToolUse with strict / warn / off | None | None |
+| Circuit breaker and spiral detection | Per-agent, with recovery | None | Partial |
+| Cross-session learning | Confidence-scored learnings | None | None |
+| VCS integration (GitLab + GitHub) | Dual, auto-detected | Manual CLI | Usually GitHub only |
+| Session close with carryover | Verified, with issue creation | Manual | Partial |
+
+The design goal is engineering quality: every wave exits verified, every unfinished issue gets a carryover ticket, every session closes with a clean commit. A detailed head-to-head vs. [maestro-orchestrate](https://github.com/josstei/maestro-orchestrate) is in [`docs/components.md`](docs/components.md#comparison-vs-maestro-orchestrate).
+
+## Platform support
+
+| Feature | Claude Code | Codex CLI | Cursor IDE | Pi |
+|---|---|---|---|---|
+| All 24 commands | Native slash commands | Native plugin commands | Rules-based (.mdc) | Prompt templates |
+| Parallel agents | Agent tool | Multi-agent roles | Sequential only | Sequential (parallel planned) |
+| Session persistence | `.claude/STATE.md` | `.codex/STATE.md` | `.cursor/STATE.md` | `.pi/STATE.md` |
+| Scope enforcement | PreToolUse hooks | Unavailable — pending a real `apply_patch` adapter | `afterFileEdit` (post-hoc) | `tool_call` bridge |
+| AskUserQuestion | Native tool | Numbered-list fallback | Numbered-list fallback | Numbered-list fallback |
+| Quality gates | Full | Full | Full | Full |
+
+All platforms share the same skills, commands, and scripts; hooks use platform-specific adapters and event subsets. Codex intentionally wires only its six supported project event slots and omits Claude-only events plus Edit/Write payload handlers until a real Codex `apply_patch` adapter exists, so scope enforcement is currently unavailable there. Platform detection and adaptation live in `scripts/lib/platform.mjs`. **OS:** macOS and Linux are first-class and run in CI (`ubuntu-latest`, `macos-latest`). Windows runs natively (all paths via `path.join`, tmp via `os.tmpdir()`) but is **not** covered by CI — treat it as best-effort and run smoke tests locally when changing OS-sensitive code. Cursor and Pi have known event-coverage caveats — see [`docs/cursor-setup.md`](docs/cursor-setup.md) and [`docs/pi-setup.md`](docs/pi-setup.md).
+
+## Troubleshooting
+
+**Codex plugin or hooks not loading.** Start with `codex plugin list --available --json`. Confirm `session-orchestrator@kanevry` is installed, enabled, unique, and at the tracked manifest version; then start a fresh task and review `/hooks`. Remove only the two allowlisted legacy IDs through `codex plugin remove`, and resolve marketplace conflicts through the public marketplace remove/add lifecycle before reinstalling. 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. The full decision tree is in [`docs/codex-setup.md`](docs/codex-setup.md#troubleshooting).
+
+**"'node' not found on the hook PATH — plugin hooks are skipped."** The harness executes hook commands via `/bin/sh -c` with its own PATH — that shell does not source `~/.zshrc`/`~/.bashrc`, so Node installed via Homebrew (`/opt/homebrew/bin`), nvm, volta, or asdf can be invisible to hooks even though `node` works fine in your terminal. All hook commands route through [`hooks/run-node.sh`](hooks/run-node.sh), which resolves Node via `$SO_NODE_BIN` → PATH → well-known install dirs → nvm and degrades gracefully when nothing is found: hooks are skipped with **one** warning per 6 hours instead of a shell error on every tool call. Fixes, in order of preference: launch the harness from a shell where `node` resolves; export `SO_NODE_BIN=/abs/path/to/node`; or install Node 24+ to a standard location.
+
+## Safety
+
+`hooks/pre-bash-destructive-guard.mjs` blocks destructive shell commands (`git reset --hard`, `rm -rf`, `git push --force`, and more) in the main session *and* in subagent waves. Policy lives in `.orchestrator/policy/blocked-commands.json`. Bypass per session only for intentional maintenance:
+
+```yaml
+allow-destructive-ops: true
+```
+
+The rule source of truth is [`.claude/rules/parallel-sessions.md`](.claude/rules/parallel-sessions.md) (PSA-003), vendored to consumer repos via `/bootstrap`.
+
+## Development
+
+```bash
+git clone https://github.com/Kanevry/session-orchestrator.git && cd session-orchestrator
+npm install
+npm test          # vitest
+npm run lint      # ESLint v10 + Prettier
+npm run typecheck # node --check on every .mjs file
+```
+
+`.npmrc` ships with `ignore-scripts=true` (supply-chain defence), so Husky git hooks don't auto-wire on install — run `npx husky` once after cloning. `git commit` then runs gitleaks → owner-privacy scan → lint-staged → commitlint. CI re-runs everything, plus more.
+
+Contributor docs: [Plugin Architecture (v3)](docs/plugin-architecture-v3.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [agent authoring spec](agents/AGENTS.md).
+
+## Support & scope
+
+Session Orchestrator is provided **as-is** — a community project with no SLA, no commercial support contract, and no guaranteed response time. Maintenance is best-effort.
+
+- Questions, ideas, show-and-tell → [GitHub Discussions](https://github.com/Kanevry/session-orchestrator/discussions)
+- Bugs and feature requests → [Issues](https://github.com/Kanevry/session-orchestrator/issues)
+
+What it is **not**:
+
+- **Not an official product of any agent vendor.** An independent, community-maintained project — not affiliated with, endorsed by, or sponsored by Anthropic, OpenAI, Cursor, or any agent it integrates with. (It is distributed through the Claude Code plugin marketplace, but is not an Anthropic product.)
+- **Not a replacement** for Claude Code / Codex CLI / Cursor / Pi. It is a workflow layer that runs *on top of* your existing agent — you still need one of those installed.
+- **Not a hosted service.** Runs locally — no server, account, or cloud component.
+- **No guarantee that telemetry numbers transfer to your repo.** Reported test counts and metrics describe *this* repository under its own conditions ([details](docs/telemetry/telemetry-claims.md)). Your results will vary by stack, project size, and configuration.
+
+## Documentation
+
+- [docs/ Router](docs/README.md) — living reference vs. public decision history vs. active work documents; what moved to the private Meta-Vault and why
+- [User Guide](docs/USER-GUIDE.md) — installation, config reference, workflow walkthrough, FAQ
+- [Components & Reference](docs/components.md) — full skill/command/agent/hook inventory, repository anatomy, comparisons
+- [Plugin Architecture (v3)](docs/plugin-architecture-v3.md) — contributor guide, layering, hook anatomy, testing
+- [Migration to v3](docs/migration-v3.md) — upgrade path from v2.x, known issues, rollback
+- [Telemetry claims](docs/telemetry/telemetry-claims.md) — how reported metrics are measured, and why they may not transfer
+- [Example Configs](docs/examples/) — Session Config examples for Next.js, Express, Swift
+- [CHANGELOG.md](CHANGELOG.md) — version history
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/) — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Learn the method behind it
+
+This plugin is a methodology turned into code. If you want the reasoning behind it — why execution runs in waves, why every wave ends at a verification gate, how to make an autonomous loop that actually finishes — those playbooks are taught hands-on at **[agenticbuilders.at](https://agenticbuilders.at)**:
+
+- **[Multi-Agent Orchestration](https://agenticbuilders.at/orchestrierung)** — leading several agents in coordinated waves: when parallelism pays, briefing subagents cleanly, turning failures into firm gates.
+- **[Loop Engineering](https://agenticbuilders.at/loop-engineering)** — designing autonomous loops that finish verifiably: done-conditions, verification gates, kill-switches.
+
+The plugin is free and MIT. The courses are for going deeper, not a requirement for using it.
+
+## Links
+
+- [Homepage](https://session-orchestrator.com) · [Privacy Policy](https://gotzendorfer.at/en/session-orchestrator/privacy)
+
+## License
+
+[MIT](LICENSE)

package/SECURITY.md

@@ -0,0 +1,90 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 2.0.x-alpha | Yes |
+| 1.x | No |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in Session Orchestrator, please report it responsibly.
+
+**Email:** [security@gotzendorfer.at](mailto:security@gotzendorfer.at)
+
+Please include:
+- Description of the vulnerability
+- Steps to reproduce
+- Affected files/skills
+- Potential impact
+
+**Response time:** We aim to acknowledge reports within 48 hours and provide a fix or mitigation plan within 7 days.
+
+## Scope
+
+Session Orchestrator is a **Claude Code plugin** composed entirely of Markdown instructions and shell scripts. It does not:
+- Run a web server or accept network connections
+- Store credentials or secrets
+- Execute user-provided code directly
+
+Security concerns are most likely to involve:
+- **Hook scripts** (`hooks/enforce-scope.sh`, `hooks/enforce-commands.sh`) — command injection via crafted file paths or tool input
+- **Skill instructions** — prompt injection that could bypass scope enforcement or safety constraints
+- **Agent dispatch** — unintended tool access or scope escalation during wave execution
+
+## Disclosure
+
+We follow [responsible disclosure](https://en.wikipedia.org/wiki/Responsible_disclosure). Fixes are committed with a security advisory once a patch is available.
+
+## Enforcement Architecture
+
+Session Orchestrator uses a two-layer PreToolUse hook system to constrain agent behavior during wave execution.
+
+### File scope enforcement (`enforce-scope.sh`)
+
+Intercepts **Edit** and **Write** tool calls. Validates the target `file_path` against the `allowedPaths` array in `.claude/wave-scope.json`. Paths are matched via prefix (directory), glob (`*`, `**`), or exact literal. Symlinks are resolved with `realpath` before comparison to prevent symlink bypass. Files outside the project root are always flagged.
+
+### Command enforcement (`enforce-commands.sh`)
+
+Intercepts **Bash** tool calls. Checks the command string against the `blockedCommands` array in `wave-scope.json` using word-boundary matching (prevents partial matches like "rm" matching "format"). When `blockedCommands` is empty or absent, a hardcoded fallback safety list is enforced: `rm -rf`, `git push --force`, `git reset --hard`, `DROP TABLE`, `git checkout -- .`.
+
+### Enforcement levels
+
+Both hooks read the `enforcement` field from `wave-scope.json`:
+
+| Level | Behavior | Exit code |
+|-------|----------|-----------|
+| `strict` | Deny the operation, return `permissionDecision: deny` | 2 |
+| `warn` | Allow the operation, emit stderr warning | 0 |
+| `off` | Skip all checks | 0 |
+
+**Default is `strict`** (fail-closed) when the `enforcement` field is missing from `wave-scope.json`.
+
+### Dynamic per-wave scoping
+
+The wave-executor writes `.claude/wave-scope.json` before dispatching each wave. This means scope constraints change between waves:
+
+- **Discovery waves** use empty `allowedPaths` (deny-all writes) combined with explicit read-only agent instructions (dual enforcement — hook-level + prompt-level).
+- **Quality waves** use two-phase scope: production file patterns for simplification passes, then test-only patterns (`**/*.test.*`, `**/*.spec.*`) for test/review passes.
+
+## Prerequisites
+
+- **`jq` is required** for hook enforcement. If `jq` is not installed, both enforcement hooks silently allow all operations (graceful degradation with stderr warning). The wave-executor checks for `jq` before wave dispatch and warns the user.
+- Hooks run in the Claude Code harness environment as PreToolUse interceptors, not as standalone scripts.
+
+## Known Limitations
+
+1. **No enforcement outside active waves** — when no `wave-scope.json` exists (between sessions, before the first wave, after cleanup), hooks exit 0 and allow all operations.
+
+2. **Prompt injection via VCS content** — issue titles and descriptions fetched via `glab`/`gh` are consumed in agent prompts without sanitization. A malicious issue body could inject instructions into an agent's context. Mitigated by: issues are typically user-created in controlled workflows, and wave scope enforcement limits the blast radius of any injected instructions.
+
+3. **Plugin relies on Claude Code harness** — tool-level enforcement is provided by Claude Code's PreToolUse hook system. The plugin cannot enforce restrictions if hooks are bypassed at the harness level.
+
+4. **Session Config values are not validated** — `health-endpoints`, `plan-baseline-path`, and `cross-repos` accept arbitrary string values. Do not embed credentials in these fields (see Credential Safety below).
+
+## Credential Safety
+
+- This plugin does not store, process, or transmit credentials.
+- VCS CLI tools (`glab`, `gh`) use the user's existing authentication. Credential security for these tools is the user's responsibility.
+- **Do not embed API keys, passwords, or auth tokens** in Session Config fields (especially `health-endpoints` URLs). These values are stored in `CLAUDE.md` which may be committed to version control.

package/agents/AGENTS.md

@@ -0,0 +1,136 @@
+# `agents/` — Sub-Agent Authoring Conventions
+
+> Nested instruction file for the `agents/` subtree. Claude Code / Cursor IDE
+> and Codex CLI both load this additively when working on files in this
+> directory (root `CLAUDE.md` for the big picture, this file for local
+> conventions). Resolution rule:
+> [`../skills/_shared/instruction-file-resolution.md`](../skills/_shared/instruction-file-resolution.md).
+>
+> This is **not** an agent definition — it is the authoring spec the agent
+> `*.md` definitions in this directory must follow. The plugin validator
+> (`scripts/lib/validate/check-agents.mjs`) excludes `AGENTS.md` / `CLAUDE.md`
+> from agent-frontmatter validation by name.
+>
+> Sibling spec: for `.claude/rules/*.md` frontmatter (conditional loading via
+> globs/mode/host-class/expiry, plus the never-always-on invariant for
+> auto-generated rules), see the canonical authoring spec
+> [`docs/rule-authoring.md`](../docs/rule-authoring.md).
+
+## Local Validation Commands
+
+Run from the plugin root. These are the scoped checks for any change under `agents/`:
+
+```bash
+node scripts/lib/validate/check-agents.mjs .   # Checks 6/7/8: frontmatter, output-schema, sandbox-tier
+npm run lint                                   # eslint — agent .md bodies are prose, but schemas/*.json are linted
+npm test -- tests/scripts/validate/check-agents.test.mjs tests/unit/sandbox-tier.test.mjs
+```
+
+- **test-command:** `npm test -- tests/scripts/validate/check-agents.test.mjs`
+- **lint-command:** `npm run lint`
+
+`scripts/validate-plugin.mjs` runs `check-agents.mjs` as Check 7 at plugin-distribution time, so a broken agent file fails CI fast.
+
+## Frontmatter Contract
+
+Agent files live in `agents/` as Markdown with YAML frontmatter. Required fields:
+
+```yaml
+---
+name: kebab-case-name                # 3-50 chars, lowercase + hyphens only
+description: Use this agent when [conditions]. <example>Context: ... user: "..." assistant: "..." <commentary>Why this agent is appropriate</commentary></example>
+model: inherit                        # inherit | sonnet | opus | haiku | fable — OR full ID like claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5-20251001, claude-sonnet-5, claude-fable-5
+color: blue                           # blue | cyan | green | yellow | purple | orange | pink | red | magenta
+tools: Read, Grep, Glob, Bash         # comma-separated string OR JSON array (both accepted; we prefer comma-string for consistency)
+---
+```
+
+**Frontmatter spec source:** https://code.claude.com/docs/en/sub-agents § Supported frontmatter fields. Our local validator (`scripts/lib/validate/check-agents.mjs` + `scripts/lib/agent-frontmatter.mjs`) matches the canonical spec on `tools` (both forms accepted), `color` (canonical 8-color palette + magenta for backward-compat), and `model` (aliases + full IDs).
+
+**Required vs optional:**
+- Runtime canonical doc: only `name` + `description` are required.
+- Our validator (defensive for plugin-distribution): all four of `name + description + model + color` required; `tools` optional.
+- `description` MUST be a single-line inline string, NOT a YAML block scalar (`>` or `|`). Put `<example>` blocks inline.
+- `tools` accepts BOTH comma-separated string (`Read, Edit, Write`) and JSON array (`["Read", "Edit", "Write"]`). Anthropic's own reference agents use array form; we use string form for consistency.
+
+**Body conventions** (from Anthropic's `plugins/plugin-dev/agents/*` reference set):
+- Sections: `**Your Core Responsibilities:**` → `**[X] Process:**` → `**Quality Standards:**` → `**Output Format:**` → `**Edge Cases:**`.
+- Length: 500–3000 words is the recommended range. Below 500 reads as under-specified; above 3000 reads as bloated.
+- Read-only reviewer agents: tools `Read, Grep, Glob, Bash` (no Edit/Write). Implementer agents: `Read, Edit, Write, Glob, Grep, Bash`.
+
+## Model Selection & Cost Routing (#768)
+
+`model:` is not just a compatibility field — it is a cost/quality dial per agent. Pick deliberately, don't default to `sonnet` everywhere.
+
+- **`haiku`** — cheap, fast, advisory/judge roles where the task is narrow classification or a single yes/no verdict, not open-ended reasoning. Precedent: `dialectic-deriver`, `skill-applied-judge`. Pin `haiku` when the agent's whole job is "read a short input, emit a structured verdict."
+- **`sonnet`** — the default workhorse tier. Use for implementation, test-writing, and review agents that need real reasoning over a non-trivial diff or codebase slice (code-implementer, test-writer, security-reviewer, and most of the catalog).
+- **`inherit`** — let the coordinator/session's active model tier flow through. Default for read-only reviewer/analysis agents that benefit from running at whatever tier the operator picked for the session (e.g. an Opus session should give its reviewers Opus-quality judgment too), and for agents with no strong cost/quality reason to diverge from the session.
+- **`opus`** — reserve for agents whose task genuinely needs the strongest available reasoning (e.g. `ux-evaluator`) and where the cost is justified because the agent runs rarely (dispatched solo, not fanned out across a wave).
+- **Full model-ID pinning** (`claude-opus-4-7`, `claude-sonnet-5`, `claude-fable-5-20260101`, …) — only when the agent has a demonstrated dependency on a SPECIFIC model version, e.g. a reproducibility requirement that needs a dated snapshot, or a known behavioral regression on newer models for this agent's exact prompt. Pinning trades away automatic model-family upgrades — document the reason inline as a frontmatter comment when you do this.
+
+**Resolution order** (highest precedence first): `CLAUDE_CODE_SUBAGENT_MODEL` environment variable → the invocation-time model parameter (if the dispatcher passes one explicitly) → the agent's own frontmatter `model:` value. An agent's `model:` is therefore a default, not a guarantee — a session or environment override can supersede it.
+
+## Git-Write Ban Requirement (PSA-007, #724)
+
+Every agent definition with `repo-write` sandbox-tier (i.e. `Edit`/`Write` present in `tools:`) MUST carry an explicit git-write ban line in its `## Rules` section:
+
+> Do NOT run ANY git write operation (`git add`, `git commit`, `git stash`, `git mv`, `git rm`, `git push`, `git reset`) — the git index and stash are shared session resources (PSA-007); the coordinator handles ALL VCS operations.
+
+This is deliberately more explicit than a bare "Do NOT commit" — the git index and stash are SHARED resources across concurrently-dispatched sibling agents in the same wave, and `git stash`/`git add`/`git mv`/`git rm` are index-mutating even when scoped to the agent's own files. `docs-writer.md` had NO git-write restriction at all until #724 closed the gap (its `repo-write` siblings at least carried a bare "Do NOT commit" line) — when adding a new repo-write agent, copy the ban line verbatim rather than re-deriving a weaker phrasing so this gap does not recur. See `.claude/rules/parallel-sessions.md` § PSA-007 for the full rationale and fleet evidence.
+
+## Color Allocation Strategy (#443)
+
+`color` is an **operator side-channel**, not a cosmetic field. In a `/tmux-layout` or multi-pane session, the per-agent color lets the operator tell co-running agents apart at a glance. With only a 9-color palette (`blue | cyan | green | yellow | purple | orange | pink | red | magenta`) and more than 9 agents in this directory, some colors are **deliberately shared** — but never carelessly.
+
+**Hard rule:** No two agents that CAN be dispatched in the SAME wave may share a color. Same-wave color collisions defeat the side-channel — the operator can no longer disambiguate two concurrent agents by color. The validator (`scripts/lib/validate/check-agents.mjs`) emits a **WARN** (not FAIL) when two dispatchable agents share a color, so an unintended collision surfaces in CI without blocking distribution.
+
+**Co-dispatch sets** (agents that co-run in one wave — no intra-set color may repeat):
+
+| Set | When co-run | Members (color) |
+|---|---|---|
+| **Quality wave** | end-of-impl QA pass | test-writer (orange), security-reviewer (red), session-reviewer (pink), qa-strategist (purple) |
+| **wave-reviewers (5a)** | inter-wave architecture/QA panel | architect-reviewer (blue), qa-strategist (purple), analyst (yellow) |
+| **Impl wave** | feature build | code-implementer (green), ui-developer (magenta), db-specialist (purple), test-writer (orange), docs-writer (cyan) |
+
+qa-strategist takes **purple**: it co-runs with the Quality wave (orange/red/pink) and the wave-reviewers panel (blue/yellow), but never with the Impl wave — so it safely borrows db-specialist's impl-only purple.
+
+**Deliberate-share exceptions** (a same color is acceptable ONLY when the agents can never collide on screen):
+
+- **(a) Dispatchable + non-dispatchable reference doc.** `memory-proposal-collector` carries `color: cyan` but is a coordinator-direct reference doc (its `description` begins "Reference documentation (NOT a dispatchable agent)"). It never dispatches as a subagent, so its color can never collide. The validator skips such files when aggregating collisions.
+- **(b) Mutually-exclusive-phase agents.** Two dispatchable agents that run in different, non-overlapping phases never appear in the same wave. Examples: `ux-evaluator` (blue) is dispatched **solo** by test-runner/driver skills and never co-runs with anything — it shares blue with `architect-reviewer` (inter-wave reviewer panel) harmlessly. `dialectic-deriver` (cyan, `/evolve` phase) and `docs-writer` (cyan, impl/finalization phase) run in different phases.
+
+**Instruction for new agents:** when adding an agent past the 9-color budget, do NOT pick a free-looking color blindly. Pick the color of an agent you can **never co-run with** (a different-phase or solo-dispatch agent), and record the pairing rationale in your agent's body or in this table. If you cannot find a safe share, the collision is real — fix the dispatch design, not the color.
+
+## Optional `sandbox-tier:` field (#418)
+
+Agents MAY declare their sandbox permission tier. Valid values:
+
+| Value | Meaning | Typical tools |
+|---|---|---|
+| `read-only` | observes only; no file writes, no network | `Read, Grep, Glob, Bash` |
+| `repo-write` | may create or modify files | `Read, Edit, Write, Glob, Grep, Bash` |
+| `network-allowed` | may make outbound network calls (future) | — |
+| `dangerous` | may run destructive shell commands (future) | — |
+
+Inference rule (backward-compat): agents without `sandbox-tier:` infer their tier from tools — `Edit` or `Write` present → `repo-write`; only `Read/Grep/Glob/Bash/Skill` → `read-only`. The validator emits **WARN**, not FAIL, when the field is absent, so existing agents continue to work during migration. Bash appears in all tiers — fine-grained Bash control is handled by `hooks/pre-bash-destructive-guard.mjs`, not by tier.
+
+Example:
+
+```yaml
+tools: Read, Edit, Write, Glob, Grep, Bash
+sandbox-tier: repo-write
+output-schema: schemas/code-implementer.schema.json
+```
+
+## Optional `output-schema:` field (#417)
+
+Agents MAY declare a JSON-Schema-2020-12 file under `agents/schemas/` that describes the shape of their machine-readable output (the trailing fenced ```json block in the agent's return). Example:
+
+```yaml
+tools: Read, Edit, Write, Glob, Grep, Bash
+output-schema: schemas/code-implementer.schema.json
+```
+
+When present, `scripts/lib/agent-output-schema.mjs#validateAgentOutput()` parses the agent's last fenced ```json block and validates it against the schema (AJV 2020). Agents without `output-schema:` fall through with `mode: 'unvalidated'` (backward-compatible). `scripts/validate-plugin.mjs` Check 7 compiles every declared schema at plugin-distribution time so broken schemas fail fast. Currently declared: `code-implementer`, `db-specialist`, `test-writer`, `ui-developer` (W2 of issue #417); the remaining 7 agents are scoped for a follow-up issue.
+
+Reference: https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/agent-development/SKILL.md