@lvlup-sw/exarchos 2.5.0 → 2.6.1

package/skills/claude/prune-workflows/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: prune-workflows
+description: "Interactively prune stale non-terminal workflows from the pipeline. Use when the user says 'prune workflows', 'clean stale workflows', 'pipeline cleanup', or runs /prune. Runs a dry-run preview, displays candidates with staleness and safeguard skips, prompts the user to proceed/abort/force, then bulk-cancels approved workflows with a workflow.pruned audit event. Safeguards skip workflows with open PRs or recent commits unless force is set."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  mcp-server: exarchos
+  category: maintenance
+---
+
+# Prune Workflows Skill
+
+## Overview
+
+Bulk-cancel stale non-terminal workflows that have accumulated in the pipeline. Wraps the `prune_stale_workflows` orchestrate action with an interactive dry-run-then-confirm UX so the user always sees the candidate set before any state mutates.
+
+Pruning is a maintenance operation -- not a workflow phase. It produces `workflow.pruned` events alongside the standard `workflow.cancelled` events emitted by the underlying cancel path, so downstream views can distinguish user-intent cancellations from batch cleanup.
+
+## Triggers
+
+Activate this skill when:
+- User runs `/exarchos:prune` command
+- User says "prune workflows", "clean stale workflows", "pipeline cleanup"
+- `mcp__plugin_exarchos_exarchos__exarchos_view({ action: "pipeline" })` shows many inactive workflows the user wants to clear in bulk
+
+## Prerequisites
+
+- An exarchos state directory with one or more non-terminal workflows
+- For safeguard checks against live PRs: `gh` available in PATH (the orchestrate handler shells out)
+- For safeguard checks against branch activity: `git` available in PATH
+
+## Process
+
+### Step 1: Dry-Run Preview
+
+Always start with `dryRun: true`. This call performs candidate selection and safeguard evaluation but does not mutate any workflow state.
+
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
+  action: "prune_stale_workflows",
+  args: {
+    dryRun: true
+  }
+})
+```
+
+The response shape is:
+
+```ts
+{
+  candidates: [
+    { featureId: string, phase: string, workflowType: string, stalenessMinutes: number }
+  ],
+  skipped: [
+    { featureId: string, reason: "open-pr" | "active-branch" }
+  ]
+}
+```
+
+Optional args:
+- `thresholdMinutes` -- staleness cutoff. Default is 10080 (7 days).
+- `includeOneShot` -- whether to include `oneshot` workflows in the candidate set. Default `true`.
+- `force` -- not relevant in dry-run; only honored in apply mode (Step 4).
+
+### Step 2: Display Candidate Table
+
+Render a table to the user so they can review what would be pruned. Use this format:
+
+```markdown
+## Prune Candidates (3)
+
+| Feature ID | Type | Phase | Stale (min) |
+|---|---|---|---|
+| feat-old-experiment | feature | implementing | 14430 |
+| oneshot-typo-fix | oneshot | plan | 9120 |
+| debug-flaky-test | debug | investigate | 8650 |
+
+## Skipped by Safeguards (2)
+
+| Feature ID | Reason |
+|---|---|
+| feat-active-pr | open-pr |
+| feat-recent-work | active-branch |
+```
+
+If `candidates.length === 0` AND `skipped.length === 0`, output:
+
+> No stale workflows to prune. Pipeline is clean.
+
+Then exit -- no further action.
+
+### Step 3: Prompt for Confirmation
+
+Ask the user one of three choices:
+
+> **proceed** -- prune the listed candidates (skipped workflows stay)
+> **abort** -- exit without changes
+> **force** -- bypass safeguards and prune skipped workflows too
+
+Wait for explicit user input. Do **not** auto-proceed.
+
+### Step 4a: Apply (proceed)
+
+On `proceed`, invoke the same action with `dryRun: false`. Pass through `thresholdMinutes` and `includeOneShot` if the user set them in Step 1.
+
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
+  action: "prune_stale_workflows",
+  args: {
+    dryRun: false
+  }
+})
+```
+
+The response now includes a `pruned` array:
+
+```ts
+{
+  candidates: [...],
+  skipped: [...],
+  pruned: [
+    { featureId: string, previousPhase: string }
+  ]
+}
+```
+
+Each entry in `pruned` corresponds to a workflow that transitioned to `cancelled` and emitted a `workflow.pruned` event.
+
+### Step 4b: Apply (force)
+
+On `force`, set `force: true`. Safeguards are bypassed but the bypass is recorded in the `workflow.pruned` event payload as `skippedSafeguards: [...]` so the audit trail is intact.
+
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
+  action: "prune_stale_workflows",
+  args: {
+    dryRun: false,
+    force: true
+  }
+})
+```
+
+In force mode, workflows that were in the `skipped` list during dry-run are now eligible for pruning.
+
+### Step 4c: Apply (abort)
+
+On `abort`, exit without invoking the action a second time. The dry-run has not mutated any state.
+
+### Step 5: Report Results
+
+After the apply call returns, summarize the outcome:
+
+```markdown
+## Prune Complete
+
+**Pruned:** 3 workflows transitioned to cancelled
+**Skipped:** 2 workflows preserved by safeguards
+**Force bypass:** no
+
+### Pruned Workflows
+- feat-old-experiment (was: implementing)
+- oneshot-typo-fix (was: plan)
+- debug-flaky-test (was: investigate)
+```
+
+If `force` was used, also list any safeguards that were bypassed:
+
+```markdown
+### Safeguards Bypassed
+- feat-active-pr: open-pr
+- feat-recent-work: active-branch
+```
+
+## Safeguards Explained
+
+Two safeguards run automatically in the orchestrate handler before each cancel:
+
+| Safeguard | Behavior | Reason key |
+|---|---|---|
+| **Open PR** | Skip if `gh pr list --head <branch> --state open` returns any results | `open-pr` |
+| **Recent commits** | Skip if `git log --since "24 hours ago" origin/<branch>` shows commits | `active-branch` |
+
+A workflow without a `branchName` in state (e.g., abandoned at ideate/plan before delegation) cannot have a PR or branch activity, so safeguards short-circuit and the workflow is eligible for pruning.
+
+`force: true` bypasses both checks but does not bypass the audit -- the bypassed safeguard names are recorded in the `workflow.pruned` event payload.
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|---|---|
+| Skip the dry-run step | Always start with `dryRun: true` so the user sees candidates first |
+| Auto-confirm without showing the table | Render the candidate table and wait for explicit user input |
+| Use `force: true` by default | Reserve `force` for cases where the user has explicitly opted in |
+| Manually call `cancel` for each stale workflow | Use this skill -- it batches the cancel loop and emits the `workflow.pruned` audit event |
+| Run on every session | Pruning is a maintenance operation; run when pipeline accumulation is observable |
+
+## Examples
+
+### Example 1: Clean dry-run, user proceeds
+
+```
+> /exarchos:prune
+
+## Prune Candidates (2)
+
+| Feature ID | Type | Phase | Stale (min) |
+|---|---|---|---|
+| feat-old-spike | feature | plan | 12880 |
+| oneshot-readme-tweak | oneshot | implementing | 9700 |
+
+## Skipped by Safeguards (0)
+
+(none)
+
+Proceed? (proceed/abort/force)
+
+> proceed
+
+## Prune Complete
+
+**Pruned:** 2 workflows transitioned to cancelled
+**Skipped:** 0
+**Force bypass:** no
+
+### Pruned Workflows
+- feat-old-spike (was: plan)
+- oneshot-readme-tweak (was: implementing)
+```
+
+### Example 2: Safeguard skip, user forces
+
+```
+> /exarchos:prune
+
+## Prune Candidates (1)
+
+| Feature ID | Type | Phase | Stale (min) |
+|---|---|---|---|
+| feat-stale-no-pr | feature | implementing | 11200 |
+
+## Skipped by Safeguards (1)
+
+| Feature ID | Reason |
+|---|---|
+| feat-stale-with-pr | open-pr |
+
+Proceed? (proceed/abort/force)
+
+> force
+
+## Prune Complete
+
+**Pruned:** 2 workflows transitioned to cancelled
+**Skipped:** 0
+**Force bypass:** yes
+
+### Pruned Workflows
+- feat-stale-no-pr (was: implementing)
+- feat-stale-with-pr (was: implementing)
+
+### Safeguards Bypassed
+- feat-stale-with-pr: open-pr
+```
+
+### Example 3: Empty pipeline
+
+```
+> /exarchos:prune
+
+No stale workflows to prune. Pipeline is clean.
+```
+
+## Schema Discovery
+
+For the canonical argument schema and any future fields, use:
+
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
+  action: "describe",
+  actions: ["prune_stale_workflows"]
+})
+```
+
+## Exarchos Integration
+
+The `prune_stale_workflows` action emits two events per pruned workflow:
+- `workflow.cancelled` (auto-emitted by the underlying `handleCancel` path)
+- `workflow.pruned` (emitted by this handler with `triggeredBy: 'manual'` and optional `skippedSafeguards`)
+
+Both are projected into the workflow state's `_events` array by the standard projection. Downstream views can filter on `workflow.pruned` to identify batch cleanups versus user-initiated cancels.

package/skills/claude/prune-workflows/references/safeguards.md

@@ -0,0 +1,74 @@
+---
+name: prune-safeguards
+---
+
+# Prune Safeguards
+
+The `prune_stale_workflows` orchestrate action runs two safeguards on each
+candidate before it will actually cancel the workflow. Both must pass for
+the candidate to be pruned, unless the caller passes `force: true` to
+bypass them.
+
+## Safeguard 1: `hasOpenPR`
+
+Checks whether there's an open pull request targeting the workflow's
+branch. Implementation: `gh pr list --state open --head <branchName>` —
+if the list is non-empty, the safeguard fails and the candidate is
+skipped with reason `open-pr`.
+
+Rationale: an open PR means human work is still in-flight on this feature.
+Cancelling the workflow would orphan the PR from its event-sourced state,
+which makes it invisible to `exarchos_view` and breaks auto-merge gates.
+We refuse to prune workflows with open PRs by default.
+
+## Safeguard 2: `hasRecentCommits` (user-facing: `active-branch`)
+
+Checks whether any commits landed on the workflow's branch within a
+24-hour window. Implementation: `git log --since="24 hours ago"
+<branchName>` — if the output is non-empty, the safeguard fails and the
+candidate is skipped with reason `active-branch`.
+
+Rationale: commits on the branch mean the workflow isn't actually stale,
+it just missed the last event checkpoint. The underlying branch is the
+ground truth for "is this work still alive?" — if someone is committing,
+we don't care what the checkpoint timestamp says.
+
+The window is locked at 24 hours for v1. It's exposed as a module
+constant (`RECENT_COMMITS_WINDOW_HOURS` in `prune-stale-workflows.ts`)
+so tests can see the contract, but it's not yet configurable through
+the public handler args.
+
+## Short-circuit: missing `branchName`
+
+If the workflow state has no top-level `branchName` field, both
+safeguards are skipped entirely (they have nothing to look up). The
+candidate still proceeds to cancel. This is safe because a workflow
+without a branch can't have an open PR or recent commits by definition.
+
+## `force: true` bypass semantics
+
+Passing `force: true` skips safeguard evaluation for every candidate.
+The handler still does everything else — the cancel, the event emission,
+the audit trail — but `hasOpenPR` and `hasRecentCommits` are never
+called.
+
+Every `workflow.pruned` event emitted during a `force: true` run carries
+a `skippedSafeguards: ['open-pr', 'active-branch']` marker on its payload.
+This makes forced prunes distinguishable in the audit stream from
+safeguard-approved ones, so operators reviewing the event log can see
+exactly which workflows were cancelled despite having open PRs or active
+branches.
+
+The marker list is intentionally hardcoded to *all* safeguards, not just
+the ones that would have failed. Running `force: true` is a blanket
+"I know what I'm doing" override — we want the audit trail to reflect
+that the user chose to bypass the whole safeguard layer, not to imply
+selective bypassing.
+
+## See also
+
+- `servers/exarchos-mcp/src/orchestrate/prune-safeguards.ts` — the
+  default implementations (gh/git backends) and the `PruneSafeguards`
+  interface for DI.
+- `servers/exarchos-mcp/src/orchestrate/prune-stale-workflows.ts` —
+  the handler that composes safeguards with selection and cancel.

package/skills/{quality-review → claude/quality-review}/SKILL.md

@@ -264,6 +264,8 @@ If an issue spans multiple tasks:
 
 ## State Management
 
+> **Key format:** The review key MUST be kebab-case `reviews["quality-review"]`, not camelCase `reviews.qualityReview`. The guard matches on the exact key string.
+
 **On review complete:**
 ```text
 action: "set", featureId: "<id>", updates: {

package/skills/{shepherd → claude/shepherd}/SKILL.md

@@ -21,6 +21,10 @@ Iterative loop that shepherds published PRs through CI checks and code reviews t
               ^^^^^^^^^ runs within synthesize phase
 ```
 
+## Pipeline Hygiene
+
+When `mcp__plugin_exarchos_exarchos__exarchos_view pipeline` accumulates stale workflows (inactive > 7 days), run `@skills/prune-workflows/SKILL.md` to bulk-cancel abandoned workflows before starting a new shepherd cycle. Safeguards skip workflows with open PRs or recent commits, so active shepherd targets are never touched. A clean pipeline makes shepherd iteration reporting easier to read and reduces noise in the stale-count view.
+
 ## Triggers
 
 Activate when:

package/skills/{spec-review → claude/spec-review}/SKILL.md

@@ -249,6 +249,8 @@ Before invoking quality-review:
 1. Verify `reviews["spec-review"].status === "pass"` in workflow state (all tasks passed)
 2. If not: "Spec review did not pass, cannot proceed to quality review"
 
+> **Guard shape:** The `all-reviews-passed` guard requires `reviews["spec-review"]` to be an object with a `status` field set to a passing value (`pass`, `passed`, `approved`, `fixes-applied`). Flat strings like `reviews: { "spec-review": "pass" }` are silently ignored and will block the `review → synthesize` transition.
+
 ### If PASS:
 1. Record results — the reviews value MUST be an object with a `status` field, not a flat string:
    ```

package/skills/{synthesis → claude/synthesis}/SKILL.md

@@ -22,12 +22,22 @@ Submit stacked PRs after review phase completes. The `prepare_synthesis` composi
 
 Do NOT proceed if either review is incomplete or failed -- return to `/exarchos:review` first.
 
+**Entry points:** Synthesis is normally reached from the `review` phase of
+feature / debug / refactor workflows. It is also reachable from `oneshot`
+workflows via the opt-in path — when a user signals "let's open a PR for
+this" during `plan` or `implementing`, the `request_synthesize` event is
+appended, and `finalize_oneshot` then resolves the choice state and
+transitions the workflow to `synthesize`. See
+`@skills/oneshot-workflow/SKILL.md` for the opt-in mechanics and
+`synthesisPolicy` semantics.
+
 ## Triggers
 
 Activate this skill when:
 - User runs `/exarchos:synthesize` command
 - All reviews have passed successfully
 - Ready to submit PRs
+- Oneshot workflow resolved to `synthesize` via `finalize_oneshot`
 
 ## Process
 
@@ -128,6 +138,36 @@ For merge ordering strategy, see `references/merge-ordering.md`.
 - **'feedback'** -- Route to `/exarchos:delegate --pr-fixes [PR_URL]` to address comments, then return here
 - **'no'** -- Pause workflow; resume later with `/exarchos:rehydrate`
 
+### Event Emissions (REQUIRED)
+
+After PRs are created and auto-merge is enabled, emit the `stack.submitted` event:
+
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_event({ action: "append", stream: "<featureId>", event: {
+  type: "stack.submitted",
+  data: {
+    branches: ["task-001-branch", "task-002-branch"],
+    prNumbers: [101, 102]
+  }
+}})
+```
+
+During shepherd iterations (CI monitoring loop), emit after each assessment:
+
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_event({ action: "append", stream: "<featureId>", event: {
+  type: "shepherd.iteration",
+  data: {
+    iteration: 1,
+    prsAssessed: 2,
+    fixesApplied: 0,
+    status: "all-green"
+  }
+}})
+```
+
+These events are checked by `check-event-emissions` during workflow validation. Missing emissions will trigger warnings.
+
 ### Post-Merge Cleanup
 
 After PRs merge, invoke cleanup:

package/skills/{workflow-state → claude/workflow-state}/SKILL.md

@@ -38,7 +38,10 @@ Valid transitions, guards, and prerequisites for all workflow types are document
 
 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. Use
+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.
 
@@ -54,9 +57,25 @@ For full MCP tool signatures, error handling, and anti-patterns, see `references
 
 At the start of `/exarchos:ideate`, use `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "init"` with:
 - `featureId`: the workflow identifier (e.g., `"user-authentication"`)
-- `workflowType`: one of `"feature"`, `"debug"`, `"refactor"`
+- `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 state file with phase "ideate".
+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
 
@@ -117,6 +136,23 @@ exarchos_orchestrate({
 | 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:
@@ -154,7 +190,7 @@ 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", or "refactor"
+- `workflowType`: Required. One of "feature", "debug", "refactor", or "oneshot"
 - `phase`: Current workflow phase
 - `artifacts`: Paths to design, plan, PR
 - `tasks`: Task list with status

package/skills/{workflow-state → claude/workflow-state}/references/phase-transitions.md

@@ -118,6 +118,28 @@ explore → brief → [polish-track | overhaul-track] → completed
 
 **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.