@lvlup-sw/exarchos 2.4.3 → 2.6.0

package/skills/cursor/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 `prune` command
+- User says "prune workflows", "clean stale workflows", "pipeline cleanup"
+- `mcp__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__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__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__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
+
+```
+> 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
+
+```
+> 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
+
+```
+> prune
+
+No stale workflows to prune. Pipeline is clean.
+```
+
+## Schema Discovery
+
+For the canonical argument schema and any future fields, use:
+
+```typescript
+mcp__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/cursor/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.