@lvlup-sw/exarchos 2.4.3 → 2.6.0

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

@@ -31,7 +31,7 @@ Activate this skill when:
 
 This skill runs in a SUBAGENT spawned by the orchestrator, not inline.
 
-The orchestrator provides the state file path, diff output from `exarchos_orchestrate({ action: "run_script", script: "review-diff.sh" })`, task ID, and spec review results (must be PASS).
+The orchestrator provides the state file path, diff output from `exarchos_orchestrate({ action: "review_diff" })`, task ID, and spec review results (must be PASS).
 
 The subagent reads the state file for artifact paths, uses the diff output instead of full files, runs static analysis, performs a code walkthrough, generates a report, and returns the verdict.
 
@@ -69,6 +69,12 @@ git diff main...integration-branch > /tmp/integration-diff.patch
 
 This reduces context consumption by 80-90% while providing the complete picture.
 
+### Pre-Review Schema Discovery
+
+Before evaluating, query the review strategy runbook to determine the appropriate evaluation approach:
+
+- **Evaluation strategy:** `exarchos_orchestrate({ action: "runbook", id: "review-strategy" })` to determine single-pass vs two-pass evaluation strategy based on diff size and task count.
+
 ### Review Scope: Combined Changes
 
 After delegation completes, quality review examines:
@@ -126,9 +132,8 @@ If this review follows a delegation phase, verify triage routing:
 
 ```typescript
 exarchos_orchestrate({
-  action: "run_script",
-  script: "verify-review-triage.sh",
-  args: ["--state-file", "<state-file>"]
+  action: "verify_review_triage",
+  stateFile: "<state-file>"
 })
 ```
 
@@ -136,12 +141,31 @@ exarchos_orchestrate({
 
 ### Step 1: Static Analysis + Security + Extended Gates
 
+> **Runbook:** Run quality evaluation gates via runbook:
+> `exarchos_orchestrate({ action: "runbook", id: "quality-evaluation" })`
+> If runbook unavailable, use `describe` to retrieve gate schemas: `exarchos_orchestrate({ action: "describe", actions: ["check_static_analysis", "check_security_scan", "check_convergence", "check_review_verdict"] })`
+
 Run automated gates via orchestrate actions. See `references/gate-execution.md` for orchestrate action signatures and response handling.
 
 1. `check_static_analysis` — lint, typecheck, quality-check (D2). **Must pass** before continuing.
 2. `check_security_scan` — security pattern detection (D1). Include findings in report.
 3. Optional D3-D5 gates: `check_context_economy`, `check_operational_resilience`, `check_workflow_determinism` — advisory, feed convergence view.
 
+### Step 2: Test Desiderata Evaluation
+
+Evaluate agent-generated tests against Kent Beck's Test Desiderata. Four properties are critical for agentic code:
+
+| Property | What to check | Flag when |
+|---|---|---|
+| **Behavioral** | Tests assert on observable behavior, not implementation details | Mock call count assertions, internal state inspection, testing private methods |
+| **Structure-insensitive** | Tests survive refactoring without behavioral change | Tests coupled to internal helper method signatures, tests that break when internals are renamed |
+| **Deterministic** | Tests produce the same result every run | Uncontrolled `Date.now()`, `Math.random()`, `setTimeout` race conditions, network-dependent tests |
+| **Specific** | Test failures pinpoint the cause | `toBeTruthy()` / `toBeDefined()` without additional specific assertions, catch-all tests with vague descriptions |
+
+**Test layer mismatch detection:** Flag unit tests with >3 mocked dependencies as potential layer mismatches — unit tests with many mocks often indicate the test is asserting integration concerns rather than unit logic. Advisory finding: suggest re-classifying as integration test with real collaborators.
+
+Include Test Desiderata findings in the quality review report under a "Test Quality" section. **Output format:** Report Test Desiderata violations as entries in the `issues` array with `category: "test-quality"`.
+
 ### Step 3: Generate Report
 
 Use the template from `references/review-report-template.md` to structure the review output.
@@ -204,7 +228,7 @@ The subagent MUST return results as structured JSON. The orchestrator parses thi
   "issues": [
     {
       "severity": "HIGH | MEDIUM | LOW",
-      "category": "security | solid | dry | perf | naming | other",
+      "category": "security | solid | dry | perf | naming | test-quality | other",
       "file": "path/to/file",
       "line": 123,
       "description": "Issue description",
@@ -240,10 +264,12 @@ 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: {
-  "reviews": { "quality": { "status": "pass", "summary": "...", "issues": [...] } }
+  "reviews": { "quality-review": { "status": "pass", "summary": "...", "issues": [...] } }
 }
 ```
 
@@ -252,6 +278,22 @@ action: "set", featureId: "<id>", updates: {
 action: "set", featureId: "<id>", phase: "synthesize"
 ```
 
+### Phase Transitions and Guards
+
+For the full transition table, consult `@skills/workflow-state/references/phase-transitions.md`.
+
+**Quick reference:**
+- `review` → `synthesize` requires guard `all-reviews-passed` — all `reviews.{name}.status` must be passing
+- `review` → `delegate` requires guard `any-review-failed` — triggers fix cycle when any review fails
+
+### Schema Discovery
+
+Use `exarchos_workflow({ action: "describe", actions: ["set", "init"] })` for
+parameter schemas and `exarchos_workflow({ action: "describe", playbook: "feature" })`
+for phase transitions, guards, and playbook guidance. Use
+`exarchos_orchestrate({ action: "describe", actions: ["check_static_analysis", "check_security_scan", "check_review_verdict"] })`
+for orchestrate action schemas.
+
 ## Completion Criteria
 
 - [ ] Static analysis passes
@@ -261,16 +303,69 @@ action: "set", featureId: "<id>", phase: "synthesize"
 - [ ] Code is maintainable
 - [ ] State file updated with review results
 
+### Decision Runbooks
+
+For review verdict routing, query the decision runbook:
+`exarchos_orchestrate({ action: "runbook", id: "review-escalation" })`
+
+This runbook provides structured criteria for routing between APPROVED and NEEDS_FIXES verdicts based on finding severity and fix cycle count. APPROVED transitions to synthesize; NEEDS_FIXES transitions back to delegate for a fix cycle. (BLOCKED routing is only relevant in plan-review, not here.)
+
+## MCP-Served Quality Check Catalog (Tier 2)
+
+After Tier 1 MCP gates complete, execute the quality check catalog. This provides deterministic quality checks (grep patterns, structural analysis) that run on **any MCP platform** — no companion plugins required.
+
+### Step 2.5: Execute Check Catalog
+
+```typescript
+exarchos_orchestrate({ action: "prepare_review", featureId: "<id>" })
+```
+
+The response contains:
+- `catalog` — structured check dimensions with grep patterns, structural thresholds, and heuristic instructions
+- `findingFormat` — the TypeScript interface for submitting findings
+- `pluginStatus` — which companion plugins are configured in `.exarchos.yml`
+
+Execute each check in the catalog against the codebase:
+- **grep checks:** Run the `pattern` against files matching `fileGlob`
+- **structural checks:** Evaluate against the `threshold` (e.g., nesting depth, function length)
+- **heuristic checks:** Use judgment guided by the `description`
+
+Collect all matches as findings in the format specified by `findingFormat`, then pass them as `pluginFindings` to `check_review_verdict`.
+
+### Companion Plugin Enhancement (Tier 3 — Platform-Dependent)
+
+On platforms with skill support (Claude Code, Cursor), the orchestrator may additionally invoke `axiom:audit` and `impeccable:critique` for deeper qualitative analysis. These findings are also passed as `pluginFindings`. See `references/axiom-integration.md` for the full three-tiered architecture.
+
 ## Convergence & Verdict
 
 Query convergence status and compute verdict via orchestrate. See `references/convergence-and-verdict.md` for full orchestrate calls, response fields, and verdict routing logic.
 
-Summary: `check_convergence` returns per-dimension D1-D5 status. `check_review_verdict` takes finding counts and dimension results, emits gate events, and returns APPROVED/NEEDS_FIXES/BLOCKED.
+Summary: `check_convergence` returns per-dimension D1-D5 status. `check_review_verdict` takes finding counts and optional `pluginFindings` array (from catalog execution and companion plugins), emits gate events, and returns APPROVED or NEEDS_FIXES.
 
 ## Auto-Transition
 
 All transitions are automatic — no user confirmation. See `references/auto-transition.md` for per-verdict transition details, Skill invocations, and integration notes.
 
-- **APPROVED** → set phase `synthesize`, invoke `/exarchos:synthesize`
-- **NEEDS_FIXES** → invoke `/exarchos:delegate --fixes`
-- **BLOCKED** → set phase `blocked`, invoke `/exarchos:ideate --redesign`
+### Recording Results
+
+Before transitioning, record the review verdict. The reviews value MUST be an object with a `status` field, not a flat string:
+
+**APPROVED:**
+```
+exarchos_workflow({ action: "set", featureId: "<id>", updates: {
+  reviews: { "quality-review": { status: "pass", summary: "...", issues: [] } }
+}, phase: "synthesize" })
+```
+Then invoke `/exarchos:synthesize`.
+
+**NEEDS_FIXES:**
+```
+exarchos_workflow({ action: "set", featureId: "<id>", updates: {
+  reviews: { "quality-review": { status: "fail", summary: "...", issues: [{ severity: "HIGH", file: "...", description: "..." }] } }
+}})
+```
+Then invoke `/exarchos:delegate --fixes`.
+
+> **Gate events:** Do NOT manually emit `gate.executed` events via `exarchos_event`. Gate events are automatically emitted by the `check_review_verdict` orchestrate handler. Manual emission causes duplicates.
+
+> **Guard shape:** The `all-reviews-passed` guard requires `reviews.{name}.status` to be a passing value (`pass`, `passed`, `approved`, `fixes-applied`). Flat strings like `reviews: { "quality-review": "pass" }` are silently ignored and will block the `review → synthesize` transition.

package/skills/{quality-review → claude/quality-review}/references/auto-transition.md

@@ -13,7 +13,7 @@ All transitions happen **immediately** without user confirmation:
    ```
 
 ### If NEEDS_FIXES:
-1. Update state: `action: "set", featureId: "<id>", updates: { "reviews": { "quality": { "status": "fail", "issues": [...] } } }`
+1. Update state: `action: "set", featureId: "<id>", updates: { "reviews": { "quality-review": { "status": "fail", "issues": [...] } } }`
 2. Output: "Quality review found [N] HIGH-priority issues. Auto-continuing to fixes..."
 3. Auto-invoke delegate with fix tasks:
    ```typescript