@lvlup-sw/exarchos 2.4.3 → 2.6.0

package/skills/cursor/workflow-state/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: workflow-state
+description: "Checkpoint and resume workflow state for context persistence across sessions. Use when the user says 'save progress', 'checkpoint', 'I need to stop', or runs /checkpoint or /rehydrate. Saves current workflow phase, task progress, and artifacts for later resumption. Do NOT use for workflow initialization (handled by ideate/debug/refactor commands)."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  mcp-server: exarchos
+  category: utility
+  phase-affinity:
+    - ideate
+    - plan
+    - delegate
+    - review
+    - synthesize
+---
+
+# Workflow State Management Skill
+
+## Overview
+
+Manage persistent workflow state that survives context auto-summarization.
+
+State files store: task details, worktree locations, PR URLs, and review status.
+
+## Triggers
+
+Activate this skill when:
+- Starting a new workflow (`ideate`)
+- Transitioning between workflow phases
+- Restoring context after summarization (`rehydrate`)
+- Saving progress for later continuation (`checkpoint`)
+
+## Phase Transitions
+
+Valid transitions, guards, and prerequisites for all workflow types are documented in `references/phase-transitions.md`. **CRITICAL:** When a transition has a guard, send the prerequisite `updates` and `phase` in a single `set` call — updates apply before guards evaluate.
+
+### Schema Discovery
+
+Use `exarchos_workflow({ action: "describe", actions: ["set", "init", "get"] })` for
+parameter schemas and `exarchos_workflow({ action: "describe", playbook: "feature" })`
+for phase transitions, guards, and playbook guidance. For the lightweight
+oneshot variant (with its `implementing → synthesize|completed` choice state
+driven by `synthesisPolicy`), call `exarchos_workflow({ action: "describe", playbook: "oneshot" })`
+— oneshot is a first-class playbook alongside feature/debug/refactor. Use
+`exarchos_event({ action: "describe", eventTypes: ["workflow.transition", "task.completed"] })`
+for event data schemas.
+
+## State Location
+
+Workflow state lives in the **MCP event store**, not the filesystem. Use `exarchos_workflow get` to read state and `exarchos_view pipeline` to discover active workflows. Do **not** scan `~/.claude/workflow-state/*.state.json` — that path is legacy and may be stale or empty.
+
+## State Operations
+
+For full MCP tool signatures, error handling, and anti-patterns, see `references/mcp-tool-reference.md`.
+
+### Initialize State
+
+At the start of `ideate`, use `mcp__exarchos__exarchos_workflow` with `action: "init"` with:
+- `featureId`: the workflow identifier (e.g., `"user-authentication"`)
+- `workflowType`: one of `"feature"`, `"debug"`, `"refactor"`, `"oneshot"`
+- `synthesisPolicy` *(optional, oneshot only)*: one of `"always"`, `"never"`, `"on-request"` (default `"on-request"`) — silently ignored for non-oneshot types
+
+This creates a new workflow state entry. The initial phase depends on
+`workflowType`:
+
+- `feature` → starts in `ideate`
+- `debug` → starts in `triage`
+- `refactor` → starts in `explore`
+- `oneshot` → starts in `plan` (skips ideate entirely)
+
+### Workflow Types at a Glance
+
+- `feature` — full `ideate → plan → delegate → review → synthesize` for real features with subagent dispatch and two-stage review
+- `debug` — `triage → investigate → (thorough | hotfix)` for bug workflows with track selection
+- `refactor` — `explore → brief → (polish | overhaul)` for code improvements, polish for small and overhaul for multi-task
+- `oneshot` — `plan → implementing → (completed | synthesize)` for trivial changes; direct-commit by default with an opt-in PR path resolved via a choice-state guard driven by `synthesisPolicy` and the `synthesize.requested` event
+
+See `@skills/oneshot-workflow/SKILL.md` for the lightweight variant's full prose, including the choice-state mechanics and `finalize_oneshot` trigger.
+
+### Read State
+
+Use `mcp__exarchos__exarchos_workflow` with `action: "get"` and `featureId`:
+
+- **Full state**: Call with just `featureId`
+- **Specific field**: Add `query` for dot-path lookup (e.g., `query: "phase"`, `query: "tasks"`)
+- **Multiple fields**: Add `fields` array for projection (e.g., `fields: ["phase", "featureId", "tasks"]`)
+
+Field projection via `fields` returns only the requested top-level keys, reducing token cost.
+
+### Update State
+
+Use `mcp__exarchos__exarchos_workflow` with `action: "set"` with `featureId` and either `updates`, `phase`, or both:
+
+- **Update phase**: `phase: "delegate"`
+- **Set artifact path**: `updates: { "artifacts.design": "docs/designs/2026-01-05-feature.md" }`
+- **Mark task complete**: `updates: { "tasks[id=001].status": "complete", "tasks[id=001].completedAt": "<timestamp>" }`
+- **Add worktree**: `updates: { "worktrees.wt-001": { "branch": "feature/001-types", "taskId": "001", "status": "active" } }`
+- **Phase + updates together**: `phase: "delegate"`, `updates: { "artifacts.plan": "docs/plans/plan.md" }`
+
+Worktree status values: `'active' | 'merged' | 'removed'`
+
+### Get Summary
+
+For context restoration after summarization, use `mcp__exarchos__exarchos_workflow` with `action: "get"` and `featureId`. This outputs a minimal summary suitable for rebuilding orchestrator context.
+
+### Reconcile State
+
+To verify state matches git reality, the SessionStart hook automatically reconciles on resume. For manual verification, run the reconciliation script:
+
+```typescript
+exarchos_orchestrate({
+  action: "reconcile_state",
+  stateFile: "<state-file>",
+  repoRoot: "<repo-root>"
+})
+```
+
+**On `passed: true`:** State is consistent.
+**On `passed: false`:** Discrepancies found — review output and resolve.
+
+## Integration Points
+
+### When to Update State
+
+| Event | State Update |
+|-------|--------------|
+| `ideate` starts | Create state file |
+| Design saved | Set `artifacts.design`, phase = "plan" |
+| Plan saved | Set `artifacts.plan`, populate tasks, phase = "plan-review" |
+| Plan-review gaps found | Set `planReview.gaps`, auto-loop to plan |
+| Plan-review approved | Set `planReview.approved = true`, phase = "delegate" |
+| Task dispatched | Set task `status = "in_progress"`, `startedAt` |
+| Task complete | Set task `status = "complete"`, `completedAt` |
+| Worktree created | Add to `worktrees` object |
+| Review complete | Update `reviews` object |
+| PR created | Set `artifacts.pr`, `synthesis.prUrl` |
+| PR feedback | Append to `synthesis.prFeedback` |
+
+#### Oneshot-specific state updates
+
+Oneshot is a first-class workflow type with a compressed lifecycle and an
+opt-in PR path. The rows below mirror the feature-workflow table above.
+
+| Phase | State updates | Events emitted |
+|-------|---------------|----------------|
+| `plan` (oneshot) | `oneshot.planSummary`, `artifacts.plan`, optional `oneshot.synthesisPolicy` | `workflow.transition` |
+| `implementing` (oneshot) | `tasks[].status`, `artifacts.tests` | `task.*`, optional `synthesize.requested` (via `request_synthesize`) |
+| `synthesize` (oneshot) | `synthesis.prUrl`, `artifacts.pr` | `workflow.transition`, `stack.submitted` |
+| `completed` (oneshot) | — | `workflow.transition` (to `completed`) |
+
+The `implementing → synthesize | completed` fork is a choice state resolved
+by `finalize_oneshot`, which reads the `synthesisOptedIn` guard
+(`synthesisPolicy` + `synthesize.requested` events). See
+`@skills/oneshot-workflow/SKILL.md` for the full opt-in mechanics.
+
+### Automatic State Updates
+
+Skills should update state at key moments:
+
+**brainstorming/SKILL.md:**
+```markdown
+After saving design:
+1. Update state: `.artifacts.design = "<path>"`
+2. Update state: `.phase = "plan"`
+```
+
+**implementation-planning/SKILL.md:**
+```markdown
+After saving plan:
+1. Update state: `.artifacts.plan = "<path>"`
+2. Populate `.tasks` from plan
+3. Update state: `.phase = "delegate"`
+```
+
+**delegation/SKILL.md:**
+```markdown
+On task dispatch:
+- Update task status to "in_progress"
+- Add worktree to state if created
+
+On task complete:
+- Update task status to "complete"
+- Check if all tasks done, suggest checkpoint
+```
+
+## State Schema
+
+See `docs/schemas/workflow-state.schema.json` for full schema.
+
+Key sections:
+- `version`: Schema version (currently "1.1")
+- `featureId`: Unique workflow identifier
+- `workflowType`: Required. One of "feature", "debug", "refactor", or "oneshot"
+- `phase`: Current workflow phase
+- `artifacts`: Paths to design, plan, PR
+- `tasks`: Task list with status
+- `worktrees`: Active git worktrees
+- `planReview`: Plan-review delta analysis results (`gaps`, `approved`)
+- `reviews`: Review results
+- `synthesis`: Merge/PR state
+
+## Best Practices
+
+1. **Update often** - State should reflect reality at all times
+2. **Use MCP tools** - Prefer workflow-state MCP tools over manual JSON editing
+3. **Reconcile on resume** - Always verify state matches git state
+4. **Checkpoint at boundaries** - Save state before likely context exhaustion
+5. **Read state, don't remember** - After summarization, read from state file
+
+## Troubleshooting
+
+### MCP Tool Call Failed
+If an Exarchos MCP tool returns an error:
+1. Check the error message — it usually contains specific guidance
+2. Verify the workflow state exists: call `mcp__exarchos__exarchos_workflow` with `action: "get"` and the featureId
+3. If "version mismatch": another process updated state — retry the operation
+4. If state is corrupted: call `mcp__exarchos__exarchos_workflow` with `action: "cancel"` and `dryRun: true`
+
+### State Desync
+If workflow state doesn't match git reality:
+1. The SessionStart hook runs reconciliation automatically on resume
+2. If manual check needed: compare state file with `git log` and branch state
+3. Update state via `mcp__exarchos__exarchos_workflow` with `action: "set"` to match git truth
+
+### Checkpoint File Missing
+If the PreCompact hook can't find state to checkpoint:
+1. Verify a workflow is active: call `mcp__exarchos__exarchos_workflow` with `action: "get"` and the featureId
+2. If no active workflow: the hook will silently skip (expected behavior)
+3. If workflow exists but checkpoint fails: check disk space and permissions
+
+### Resume Finds Stale State
+If state references branches or worktrees that no longer exist:
+1. The SessionStart hook handles reconciliation automatically
+2. It updates state to reflect current git reality
+3. Missing branches are flagged in the session-start output
+
+### Multiple Active Workflows
+If multiple workflow state files exist:
+1. The system uses the most recently updated active (non-completed) workflow
+2. Use `mcp__exarchos__exarchos_workflow` with `action: "cancel"` and `dryRun: true` on stale workflows to preview cleanup
+3. Cancel stale workflows before starting new ones
+
+## Example Workflow
+
+1. **Start new workflow**: Use `mcp__exarchos__exarchos_workflow` with `action: "init"` with `featureId: "user-authentication"`, `workflowType: "feature"`
+
+2. **After design phase**: Use `mcp__exarchos__exarchos_workflow` with `action: "set"` with:
+   - `featureId: "user-authentication"`
+   - `phase: "plan"`
+   - `updates: { "artifacts.design": "docs/designs/2026-01-05-user-auth.md" }`
+
+3. **Check state**: Use `mcp__exarchos__exarchos_workflow` with `action: "get"` with `featureId: "user-authentication"`
+
+4. **Resume after context loss**: Use `mcp__exarchos__exarchos_workflow` with `action: "get"` with `featureId: "user-authentication"` to get context restoration output

package/skills/cursor/workflow-state/references/mcp-tool-reference.md

@@ -0,0 +1,89 @@
+# MCP Tool Reference
+
+Detailed tool usage, methods, and anti-patterns for all installed MCP servers.
+
+## Exarchos (`mcp__plugin_exarchos_exarchos__*`)
+
+Unified MCP server for workflow orchestration, event sourcing, CQRS views, and task coordination. **Always use for workflow tracking.** Exposes 5 composite tools with action discriminators. Note: inter-agent messaging uses Claude Code's native Agent Teams, not Exarchos.
+
+### Composite Tools
+
+| Tool | Actions | When to Use |
+|------|---------|-------------|
+| `mcp__plugin_exarchos_exarchos__exarchos_workflow` | `init`, `get`, `set`, `cancel`, `cleanup` | Workflow CRUD: starting workflows, reading/updating state, cancelling abandoned workflows, resolving merged workflows |
+| `mcp__plugin_exarchos_exarchos__exarchos_event` | `append`, `query` | Event sourcing: recording workflow events, reading event history |
+| `mcp__plugin_exarchos_exarchos__exarchos_orchestrate` | `task_claim`, `task_complete`, `task_fail` | Task coordination and lifecycle |
+| `mcp__plugin_exarchos_exarchos__exarchos_view` | `pipeline`, `tasks`, `workflow_status`, `stack_status`, `stack_place` | CQRS materialized views for read-optimized queries |
+| `mcp__plugin_exarchos_exarchos__exarchos_sync` | `now` | Force sync of materialized views |
+
+### Workflow Tool Actions
+
+| Action | When to Use |
+|--------|-------------|
+| `init` | Starting any `/exarchos:ideate`, `/exarchos:debug`, or `/exarchos:refactor` workflow |
+| `get` | Restoring context, checking phase, reading task details. Use `query` for dot-path lookup (e.g., `query: "phase"`), or `fields` array for projection (e.g., `fields: ["phase", "tasks"]`) to reduce token cost |
+| `set` | Updating phase (`phase: "delegate"`), recording artifacts, marking tasks complete. Use `updates` for field changes and `phase` for transitions |
+| `cancel` | Cleaning up abandoned workflows. Supports `dryRun: true` to preview cleanup actions |
+| `cleanup` | Resolve a merged workflow to completed. Verifies merge, backfills synthesis metadata, force-resolves reviews, transitions to completed. Requires `mergeVerified: true` — pass after verifying PRs are merged via GitHub API |
+
+**Hooks (automatic, no tool call needed):**
+- **SessionStart hook** — Discovers active workflows, restores context, determines next action, and verifies state on resume (replaces former `workflow_list`, `workflow_summary`, `workflow_next_action`, `workflow_reconcile` tools)
+- **PreCompact hook** — Saves checkpoints before context exhaustion (replaces former `workflow_checkpoint` tool)
+- Valid phase transitions are documented in `references/phase-transitions.md` (replaces former `workflow_transitions` tool). `INVALID_TRANSITION` errors include valid targets with guard descriptions.
+
+### Event Tool Actions
+
+| Action | When to Use |
+|--------|-------------|
+| `append` | Recording workflow events (task.assigned, gate.executed, etc.). Use `expectedSequence` for optimistic concurrency |
+| `query` | Reading event history. Use `filter` for type/time filtering, `limit`/`offset` for pagination |
+
+### Orchestrate Tool Actions
+
+| Action | When to Use |
+|--------|-------------|
+| `task_claim` | Claim a task for execution. Returns `ALREADY_CLAIMED` if previously claimed — handle gracefully |
+| `task_complete` | Mark a task complete with optional `result` (artifacts, duration) |
+| `task_fail` | Mark a task failed with `error` message and optional `diagnostics` |
+
+### View Tool Actions
+
+| Action | When to Use |
+|--------|-------------|
+| `pipeline` | Aggregated view of all workflows with stack positions. Use `limit`/`offset` for pagination |
+| `tasks` | Task detail view with filtering and projection. Use `workflowId` to scope, `filter` for property matching, `fields` for projection (e.g., `fields: ["taskId", "status", "title"]`), `limit`/`offset` for pagination |
+| `workflow_status` | Workflow phase, task counts, and metadata. Use `workflowId` to scope |
+| `stack_status` | Get current stack positions from events. Use `streamId` to scope |
+| `stack_place` | Record a stack position with `position`, `taskId`, `branch`, optional `prUrl` |
+
+## GitHub (`mcp__plugin_github_github__*`)
+> Optional companion (`npx create-exarchos`). Fallback: use `gh` CLI.
+
+## Serena (`mcp__plugin_serena_serena__*`)
+> Optional companion (`npx create-exarchos`). Fallback: use Grep/Read/Glob.
+
+## Context7 (`mcp__plugin_context7_context7__*`)
+> Optional companion (`npx create-exarchos`). Fallback: use WebSearch.
+
+## Microsoft Learn (`mcp__microsoft-learn__*`)
+> Optional companion (`npx create-exarchos`). Fallback: use WebSearch.
+
+## Workflow Transition Errors
+
+### INVALID_TRANSITION
+No path exists from current phase to target. Check `validTargets` in the error — it lists reachable phases with guard descriptions. You may need to step through intermediate phases.
+
+### GUARD_FAILED
+The transition exists but the guard condition is unmet. Send prerequisite `updates` and `phase` in a **single** `set` call — updates apply before guards evaluate. See `references/phase-transitions.md` for guard prerequisites.
+
+### CIRCUIT_OPEN
+A compound state's fix cycle limit was reached. Escalate to user or cancel the workflow.
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Manually edit workflow state JSON | Use `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"` |
+| Skip state reconciliation on resume | The SessionStart hook handles reconciliation automatically |
+
+> See companion documentation for additional tool anti-patterns (Serena, GitHub MCP, Context7). Install companions: `npx create-exarchos`.

package/skills/cursor/workflow-state/references/phase-transitions.md

@@ -0,0 +1,206 @@
+# Phase Transitions Reference
+
+All valid HSM phase transitions for each workflow type. Every transition listed here is the **only** way to move between phases — the HSM rejects unlisted transitions with `INVALID_TRANSITION`.
+
+## Combined Updates + Phase Pattern
+
+**CRITICAL:** When a transition has a guard that requires prerequisite state, send `updates` and `phase` in a single `set` call. Updates are applied BEFORE guards evaluate:
+
+```
+action: "set"
+featureId: "my-feature"
+phase: "delegate"
+updates: { "planReview.approved": true }
+```
+
+This satisfies the `planReviewComplete` guard in one call. Two separate calls (set data, then transition) also work but waste a tool call.
+
+## Universal Transitions
+
+Available from **any non-final** phase in all workflow types:
+
+| To | Guard | How to Trigger |
+|----|-------|----------------|
+| `cancelled` | None | `exarchos_workflow cancel` (not `set`) — runs saga compensation |
+| `completed` | `merge-verified` | `exarchos_workflow cleanup` with `mergeVerified: true` — for post-merge resolution |
+
+## Feature Workflow
+
+```
+ideate → plan → plan-review → delegate ⇄ review → synthesize → completed
+                     ↓
+                    plan (gaps found)
+```
+
+| From | To | Guard | Prerequisite |
+|------|----|-------|-------------|
+| `ideate` | `plan` | `design-artifact-exists` | Set `artifacts.design` |
+| `plan` | `plan-review` | `plan-artifact-exists` | Set `artifacts.plan` |
+| `plan-review` | `delegate` | `plan-review-complete` | Set `planReview.approved = true` |
+| `plan-review` | `plan` | `plan-review-gaps-found` | Set `planReview.gapsFound = true` |
+| `delegate` | `review` | `all-tasks-complete` | All `tasks[].status = "complete"` |
+| `review` | `synthesize` | `all-reviews-passed` | All `reviews.{name}.status` in `["pass", "passed", "approved"]` |
+| `review` | `delegate` | `any-review-failed` | Any `reviews.{name}.status` in `["fail", "failed", "needs_fixes"]` (fix cycle) |
+| `synthesize` | `completed` | `pr-url-exists` | Set `synthesis.prUrl` or `artifacts.pr` |
+| `blocked` | `delegate` | `human-unblocked` | Set `unblocked = true` |
+
+**Compound state:** `implementation` contains `delegate` and `review`. Max 3 fix cycles before circuit breaker opens.
+
+## Debug Workflow
+
+```
+triage → investigate → [hotfix-track | thorough-track] → synthesize → completed
+```
+
+| From | To | Guard | Prerequisite |
+|------|----|-------|-------------|
+| `triage` | `investigate` | `triage-complete` | Set `triage.symptom` |
+| `investigate` | `rca` | `thorough-track-selected` | Set `track = "thorough"` |
+| `investigate` | `hotfix-implement` | `hotfix-track-selected` | Set `track = "hotfix"` |
+
+### Thorough Track
+
+| From | To | Guard | Prerequisite |
+|------|----|-------|-------------|
+| `rca` | `design` | `rca-document-complete` | Set `artifacts.rca` |
+| `design` | `debug-implement` | `fix-design-complete` | Set `artifacts.fixDesign` |
+| `debug-implement` | `debug-validate` | `implementation-complete` | Always passes |
+| `debug-validate` | `debug-review` | `validation-passed` | Set `validation.testsPass = true` |
+| `debug-review` | `synthesize` | `review-passed` | All `reviews.{name}.status` passing |
+
+**Compound state:** `thorough-track` contains `rca` through `debug-review`. Max 2 fix cycles.
+
+### Hotfix Track
+
+| From | To | Guard | Prerequisite |
+|------|----|-------|-------------|
+| `hotfix-implement` | `hotfix-validate` | `implementation-complete` | Always passes |
+| `hotfix-validate` | `completed` | `validation-passed` | Set `validation.testsPass = true` |
+
+### Shared
+
+| From | To | Guard | Prerequisite |
+|------|----|-------|-------------|
+| `synthesize` | `completed` | `pr-url-exists` | Set `synthesis.prUrl` or `artifacts.pr` |
+
+## Refactor Workflow
+
+```
+explore → brief → [polish-track | overhaul-track] → completed
+```
+
+| From | To | Guard | Prerequisite |
+|------|----|-------|-------------|
+| `explore` | `brief` | `scope-assessment-complete` | Set `explore.scopeAssessment` |
+| `brief` | `polish-implement` | `polish-track-selected` | Set `track = "polish"` |
+| `brief` | `overhaul-plan` | `overhaul-track-selected` | Set `track = "overhaul"` |
+
+### Polish Track
+
+| From | To | Guard | Prerequisite |
+|------|----|-------|-------------|
+| `polish-implement` | `polish-validate` | `implementation-complete` | Always passes |
+| `polish-validate` | `polish-update-docs` | `goals-verified` | Set `validation.testsPass = true` |
+| `polish-update-docs` | `completed` | `docs-updated` | Set `validation.docsUpdated = true` |
+
+### Overhaul Track
+
+| From | To | Guard | Prerequisite |
+|------|----|-------|-------------|
+| `overhaul-plan` | `overhaul-plan-review` | `plan-artifact-exists` | Set `artifacts.plan` |
+| `overhaul-plan-review` | `overhaul-delegate` | `plan-review-complete` | Plan approved |
+| `overhaul-plan-review` | `overhaul-plan` | `plan-review-gaps-found` | Revise plan |
+| `overhaul-delegate` | `overhaul-review` | `all-tasks-complete` | All `tasks[].status = "complete"` |
+| `overhaul-review` | `overhaul-update-docs` | `all-reviews-passed` | All `reviews.{name}.status` passing |
+| `overhaul-review` | `overhaul-delegate` | `any-review-failed` | Any `reviews.{name}.status` failing (fix cycle) |
+| `overhaul-update-docs` | `synthesize` | `docs-updated` | Set `validation.docsUpdated = true` |
+| `synthesize` | `completed` | `pr-url-exists` | Set `synthesis.prUrl` or `artifacts.pr` |
+
+**Compound state:** `overhaul-track` contains `overhaul-plan`, `overhaul-plan-review`, `overhaul-delegate`, `overhaul-review`, and `overhaul-update-docs`. Max 3 fix cycles.
+
+## Oneshot Workflow
+
+```
+plan → implementing ─┬→ completed              (direct-commit path)
+                     └→ synthesize → completed (PR path, opt-in)
+```
+
+| From | To | Guard | Prerequisite |
+|------|----|-------|-------------|
+| `plan` | `implementing` | `oneshot-plan-set` | Set `artifacts.plan` (non-empty string; `oneshot.planSummary` is optional metadata but does **not** satisfy the guard) |
+| `implementing` | `synthesize` | `synthesis-opted-in` | Policy `always` OR (`on-request` + `synthesize.requested` event) |
+| `implementing` | `completed` | `synthesis-opted-out` | Policy `never` OR (`on-request` + no event) |
+| `synthesize` | `completed` | `pr-url-exists` | Set `synthesis.prUrl` or `artifacts.pr` |
+
+**Choice state (end of `implementing`).** The fork after `implementing` is a UML choice state, implemented as two mutually-exclusive HSM transitions whose guards are pure functions of `state.oneshot.synthesisPolicy` and the `synthesize.requested` event count on the stream. At init, the user declares intent via `synthesisPolicy` (`always`, `never`, or `on-request` — default). During implementing, the user can opt in at any time by calling `exarchos_orchestrate request_synthesize`, which appends a `synthesize.requested` event without changing the phase. The decision is only evaluated when `finalize_oneshot` is called: the handler hydrates events, runs the guards, and calls `handleSet` with the resolved target. **Policy wins over event** — if policy is `never`, any `synthesize.requested` event is ignored and the guard routes to `completed`. Policy `always` short-circuits the event check and always routes to `synthesize`.
+
+**How to trigger:** `exarchos_orchestrate finalize_oneshot { featureId }` — this is the only way to exit `implementing`. The handler evaluates the choice state and calls `handleSet` with the correct target phase. The HSM re-evaluates the guard at the transition boundary, so any race between read and transition is caught safely.
+
+**No compound state.** Oneshot has no multi-agent loop, no review-fix cycle, and therefore no circuit breaker. If the in-session TDD loop gets stuck, cancel via `exarchos_workflow cancel` and restart with a different approach (or escalate to the full `feature` workflow).
+
+See `@skills/oneshot-workflow/SKILL.md` for the full prose walkthrough including worked examples.
+
+## Circuit Breaker
+
+Compound states enforce a maximum number of fix cycles to prevent infinite review-fix loops. When the limit is exceeded, the HSM rejects the transition with a `CIRCUIT_OPEN` error and emits a `workflow.circuit-open` event.
+
+### What Triggers It
+
+A fix cycle occurs when a review phase transitions back to a delegate/implement phase (a `isFixCycle: true` transition). Each such transition increments the fix cycle counter for the enclosing compound state. The circuit breaker opens when the count reaches `maxFixCycles`.
+
+For example, in the feature workflow: `review` -> `delegate` is a fix cycle within the `implementation` compound state. After 3 such cycles, the fourth attempt is blocked.
+
+### Max Fix Cycles Per Workflow
+
+| Workflow | Compound State | Contains | Max Fix Cycles |
+|----------|---------------|----------|----------------|
+| Feature | `implementation` | `delegate`, `review` | 3 |
+| Debug | `thorough-track` | `rca`, `design`, `debug-implement`, `debug-validate`, `debug-review` | 2 |
+| Refactor | `overhaul-track` | `overhaul-plan`, `overhaul-delegate`, `overhaul-review`, `overhaul-update-docs` | 3 |
+
+Note: `polish-track` (refactor) and `hotfix-track` (debug) have no fix cycle transitions, so no circuit breaker applies.
+
+### What Happens When It Opens
+
+1. The HSM emits a `circuit-open` event with metadata:
+   - `compoundStateId` — the compound state that exceeded its limit
+   - `fixCycleCount` — current count
+   - `maxFixCycles` — the configured limit
+2. The transition is **rejected** — the workflow stays in the current phase
+3. The error response contains `errorCode: "CIRCUIT_OPEN"` with a descriptive message
+4. The workflow effectively enters a stuck state requiring human intervention
+
+### How to Recover
+
+When a circuit breaker opens, the agent should:
+
+1. **Report to the user** with the iteration history and persistent failures
+2. **Set `unblocked = true`** after the user provides guidance — this allows the `blocked` → implementing phase transition (e.g., `delegate` for Feature, `debug-implement` for Debug thorough-track, `overhaul-delegate` for Refactor overhaul-track)
+3. Alternatively, **cancel the workflow** via `exarchos_workflow cancel` and restart with a different approach
+
+The circuit breaker count is tracked via `fix-cycle` events in the workflow's `_events` array. These events persist across sessions, so the count survives context compaction and session restarts.
+
+## Troubleshooting
+
+### INVALID_TRANSITION Error
+
+The HSM rejected the transition because no path exists from the current phase to the target.
+
+1. Check `validTargets` in the error response — it lists all reachable phases with their guards
+2. You may need to step through intermediate phases (no phase skipping)
+
+### GUARD_FAILED Error
+
+The transition exists but the guard condition is not met.
+
+1. Check `expectedShape` in the error response — it shows exactly what state the guard needs
+2. Set the prerequisite state via `updates` in the same `set` call as the `phase`
+3. Refer to the "Prerequisite" column in the tables above
+4. **Proactive discovery:** Before transitioning, use `exarchos_workflow describe playbook="<workflowType>"` to see guard requirements for each phase
+
+### CIRCUIT_OPEN Error
+
+A compound state's fix cycle limit has been reached (e.g., review -> delegate looped too many times). See the **Circuit Breaker** section above for full details on limits per workflow, what happens, and recovery steps.
+
+1. Report persistent failures to the user with iteration history
+2. After user guidance, set `unblocked = true` to proceed, or cancel and restart