@lvlup-sw/exarchos 2.4.3 → 2.6.0

package/skills/claude/quality-review/references/axiom-integration.md

@@ -0,0 +1,135 @@
+# Axiom Plugin Integration
+
+How the exarchos quality review integrates general backend quality checks — through MCP-served check catalogs (platform-agnostic) and optional companion plugins (platform-dependent). Axiom and impeccable are optional skill libraries that enhance depth when available.
+
+## Architecture
+
+Quality checks are layered across three tiers, each progressively more platform-dependent:
+
+- **Tier 1** (MCP gates): Automated checks via `exarchos_orchestrate` actions. Platform-agnostic.
+- **Tier 2** (MCP-served catalog): `prepare_review` returns structured check patterns that any LLM agent executes. Platform-agnostic.
+- **Tier 3** (Companion skills): `axiom:audit` and `impeccable:critique` provide deeper qualitative analysis. Platform-dependent (Claude Code, Cursor).
+
+```text
+Any MCP client (Claude Code, Cursor, generic)
+    │
+    ├── Tier 1: MCP Gates (always, automated)
+    │   ├── check_static_analysis (D2 gate)
+    │   ├── check_security_scan (D1 gate)
+    │   ├── check_context_economy (D3 gate — advisory)
+    │   ├── check_workflow_determinism (D5 gate — advisory)
+    │   └── Test Desiderata evaluation
+    │
+    ├── Tier 2: MCP-Served Check Catalog (always, agent-executed)
+    │   ├── prepare_review → returns catalog as structured data
+    │   │   ├── Grep patterns (error handling, type safety, test quality, ...)
+    │   │   ├── Structural checks (nesting depth, function length, ...)
+    │   │   └── Heuristic instructions (LLM-guided checks)
+    │   ├── Agent executes checks against codebase
+    │   └── Findings fed as pluginFindings to check_review_verdict
+    │
+    ├── Tier 3: Companion Plugin Skills (platform-dependent, optional)
+    │   ├── axiom:audit — deeper qualitative backend analysis (7 dimensions)
+    │   ├── impeccable:critique — design quality analysis
+    │   └── Findings fed as additional pluginFindings to verdict
+    │
+    └── Verdict: check_review_verdict merges ALL findings → APPROVED | NEEDS_FIXES
+```
+
+## Dimension Ownership Split
+
+The quality review draws from three independent sources. Each source owns distinct quality dimensions with no overlap:
+
+| Concern | Owner | Rationale |
+|---------|-------|-----------|
+| DIM-1: Topology | Axiom plugin (optional) | General backend quality |
+| DIM-2: Observability | Axiom plugin (optional) | General backend quality |
+| DIM-3: Contracts | Axiom plugin (optional) | General backend quality |
+| DIM-4: Test Fidelity | Axiom plugin (optional) | General backend quality |
+| DIM-5: Hygiene | Axiom plugin (optional) | General backend quality |
+| DIM-6: Architecture | Axiom plugin (optional) | General backend quality |
+| DIM-7: Resilience | Axiom plugin (optional) | General backend quality |
+| D1: Spec Fidelity & TDD | Exarchos (always runs) | Requires workflow state (design, plan, implementation traceability) |
+| D2-domain: Event Sourcing / CQRS / HSM / Saga | Exarchos (always runs) | Domain-specific to event-sourced systems |
+| D3: Context Economy | Exarchos (always runs) | Specific to AI-agent skill systems |
+| D5: Workflow Determinism | Exarchos (always runs) | Specific to workflow orchestration |
+| Design Quality (UI, accessibility, design system, responsive) | Impeccable plugin (optional) | Design-specific concerns |
+
+**Key distinction:** Axiom's DIM-1 through DIM-7 are general backend quality dimensions. Exarchos's D1-D5 are workflow-specific dimensions that require access to workflow state. These are complementary, not overlapping.
+
+## Detection and Invocation Protocol
+
+Plugin detection and invocation is performed by the **orchestrator** (commands/review.md), not by the quality-review subagent. The subagent does not have Skill tool access and should not attempt plugin invocation.
+
+### Step 1: Detect Plugin Availability (Orchestrator)
+
+After the quality-review subagent returns its verdict, the orchestrator checks for companion plugins in its available skills list:
+
+- `axiom:audit` — general backend quality (7 dimensions)
+- `impeccable:critique` — design quality (UI, accessibility, design system, responsive)
+
+### Step 2: Check Configuration Override (Orchestrator)
+
+Read the project's `.exarchos.yml` for explicit plugin toggles:
+
+```yaml
+# .exarchos.yml — plugin overrides
+plugins:
+  axiom:
+    enabled: true    # default when key is absent
+  impeccable:
+    enabled: true    # default when key is absent
+```
+
+A plugin is invoked only when BOTH conditions are met:
+1. The skill is present in the available skills list (plugin is installed)
+2. The config does not set `plugins.<name>.enabled: false`
+
+If the `plugins` key or any sub-key is absent from `.exarchos.yml`, the default is `enabled: true`.
+
+### Step 3: Invoke and Merge (Orchestrator)
+
+**axiom:audit invocation:**
+1. `Skill({ skill: "axiom:audit" })` with the diff content and list of changed files
+2. axiom returns findings in Standard Finding Format (`severity`, `dimension`, `file`, `line`, `message`)
+3. Map axiom findings to the unified list:
+   - `dimension` (DIM-1 through DIM-7) becomes the category prefix (e.g., `axiom:DIM-1-topology`)
+   - `severity` maps directly (HIGH, MEDIUM, LOW)
+   - axiom HIGH findings are treated identically to exarchos-native HIGH findings
+
+**impeccable:critique invocation:**
+1. `Skill({ skill: "impeccable:critique" })` with the diff content
+2. impeccable returns design quality findings (`severity`, `category`, `file`, `line`, `message`)
+3. Map all impeccable findings under the `design-quality` category
+
+**Merge:** Append all plugin findings to the subagent's findings list. The merged list informs verdict escalation.
+
+### Step 4: Verdict Escalation (Orchestrator)
+
+Compare plugin findings against the subagent's verdict:
+
+- If the subagent returned **APPROVED** but plugins found HIGH-severity issues → escalate to **NEEDS_FIXES**
+- If the subagent returned **NEEDS_FIXES** → preserve (plugins may add more findings but verdict is already failing)
+- If no plugins ran → preserve subagent verdict as-is
+
+## Graceful Degradation
+
+When a plugin is not installed or is disabled, the orchestrator skips it and the review proceeds with exarchos-native checks only. The orchestrator logs a "Plugin Coverage" note in the review output:
+
+- **Not installed:** Suggests the install command (`claude plugin install axiom@lvlup-sw` or `claude plugin marketplace add pbakaus/impeccable && claude plugin install impeccable@impeccable`)
+- **Disabled via config:** Notes the config key to re-enable
+- **Active:** Reports the number of dimensions checked and findings produced
+
+The subagent's verdict is unaffected by plugin absence — it operates on exarchos-native findings. Plugins can only escalate (APPROVED → NEEDS_FIXES), never downgrade.
+
+## Verdict Mapping
+
+The verdict uses the merged findings from all sources. The logic is the same regardless of which plugins contributed:
+
+| Merged Findings | Verdict |
+|----------------|---------|
+| No HIGH findings, acceptable MEDIUM/LOW | APPROVED |
+| Any HIGH findings in blocking dimensions | NEEDS_FIXES |
+| Critical architectural or security issues | BLOCKED |
+
+axiom HIGH findings and exarchos-native HIGH findings carry equal weight — both trigger NEEDS_FIXES when present in blocking dimensions.

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

@@ -91,6 +91,16 @@ Activate this skill when:
 | Documentation | Mandatory update phase | Mandatory update phase |
 | Human Checkpoints | 0 | 1 (merge) |
 
+## Characterization Testing (Both Tracks)
+
+Before modifying any existing code behavior, capture current behavior as characterization tests. This is a mandatory pre-step for both tracks:
+
+1. **Before changes:** Write tests that document what the code **currently does** (not what it should do). Exercise the code through the most appropriate observable seam (API, CLI, integration boundary, or function) with representative inputs and assert on actual outputs/effects.
+2. **During changes:** Any characterization test failure means behavior changed. Evaluate: intentional or accidental?
+3. **After changes:** Document which characterization test failures were expected. Remaining characterization tests become regression tests.
+
+This aligns with Michael Feathers' approach in *Working Effectively with Legacy Code* — understand behavior before changing it.
+
 ## Polish Track
 
 Fast path for small, contained refactors (<=5 files, single concern). Orchestrator may write code directly (exception to orchestrator constraints). No worktree, no delegation.
@@ -114,45 +124,28 @@ Initialize refactor workflow:
 action: "init", featureId: "refactor-<slug>", workflowType: "refactor"
 ```
 
-Full state schema:
-```json
-{
-  "version": "1.1",
-  "featureId": "refactor-<slug>",
-  "workflowType": "refactor",
-  "track": "polish | overhaul",
-  "phase": "explore | brief | polish-implement | polish-validate | polish-update-docs | overhaul-plan | overhaul-plan-review | overhaul-delegate | overhaul-review | overhaul-update-docs | synthesize | completed | cancelled | blocked",
-  "explore": {
-    "startedAt": "ISO8601",
-    "completedAt": "ISO8601 | null",
-    "scopeAssessment": {
-      "filesAffected": ["string"],
-      "modulesAffected": ["string"],
-      "testCoverage": "good | gaps | none",
-      "recommendedTrack": "polish | overhaul"
-    }
-  },
-  "brief": {  // See references/brief-template.md for field descriptions
-    "problem": "string",
-    "goals": ["string"],
-    "approach": "string",
-    "affectedAreas": ["string"],
-    "outOfScope": ["string"],
-    "successCriteria": ["string"],
-    "docsToUpdate": ["string"]
-  },
-  "artifacts": {
-    "plan": "string | null",
-    "pr": "string | null",
-    "updatedDocs": ["string"]
-  },
-  "validation": {
-    "testsPass": "boolean",
-    "goalsVerified": ["string"],
-    "docsUpdated": "boolean"
-  }
-}
-```
+Use `describe` to discover the full state schema at runtime: `exarchos_workflow({ action: "describe", actions: ["init"] })`.
+
+### Phase Transitions and Guards
+
+> **Sequential traversal required.** Every phase MUST be traversed in order — you cannot skip phases, even if you have all the data for a later phase ready. For example, `explore` must transition to `brief` before `overhaul-plan` — attempting `explore` → `overhaul-plan` directly will be rejected by the HSM. From `brief` you must go to `polish-implement` or `overhaul-plan`, not directly to `completed`. Each transition requires its guard to be satisfied via `updates` sent alongside the `phase` parameter in a single `set` call. See `@skills/refactor/references/polish-track.md` or `@skills/refactor/references/overhaul-track.md` for the exact tool call at each step.
+
+Every phase transition has a guard that must be satisfied. Before transitioning, consult `@skills/workflow-state/references/phase-transitions.md` for the exact prerequisite for each guard.
+
+The pattern for every transition: send the guard prerequisite in `updates` and the target in `phase` in a single `set` call.
+
+### Schema Discovery
+
+Use `exarchos_workflow({ action: "describe", actions: ["set", "init"] })` for
+parameter schemas and `exarchos_workflow({ action: "describe", playbook: "refactor" })`
+for phase transitions, guards, and playbook guidance.
+
+### Decision Runbooks
+
+For track-selection criteria at the explore phase, query the decision runbook:
+`exarchos_orchestrate({ action: "runbook", id: "scope-decision" })`
+
+This runbook provides structured criteria for choosing between polish and overhaul tracks based on file count, structural impact, and PR scope.
 
 ## Track Switching
 

package/skills/{refactor → claude/refactor}/references/doc-update-checklist.md

@@ -59,9 +59,8 @@ After updating documentation, run automated link verification:
 
 ```typescript
 exarchos_orchestrate({
-  action: "run_script",
-  script: "verify-doc-links.sh",
-  args: ["--docs-dir", "docs/"]
+  action: "verify_doc_links",
+  docsDir: "docs/"
 })
 ```
 

package/skills/{refactor → claude/refactor}/references/explore-checklist.md

@@ -48,15 +48,13 @@ Run the scope assessment script for a deterministic track recommendation:
 
 ```typescript
 exarchos_orchestrate({
-  action: "run_script",
-  script: "assess-refactor-scope.sh",
-  args: ["--files", "<file1,file2,...>"]
+  action: "assess_refactor_scope",
+  files: ["<file1>", "<file2>", "..."]
 })
 // or
 exarchos_orchestrate({
-  action: "run_script",
-  script: "assess-refactor-scope.sh",
-  args: ["--state-file", "<path>"]
+  action: "assess_refactor_scope",
+  stateFile: "<path>"
 })
 ```
 

package/skills/{refactor → claude/refactor}/references/overhaul-track.md

@@ -33,40 +33,21 @@ Thorough scope assessment using `@skills/refactor/references/explore-checklist.m
 action: "init", featureId: "refactor-<slug>", workflowType: "refactor"
 ```
 
-**Set track and scope assessment:**
-```
-action: "set", featureId: "refactor-<slug>", updates: {
-  "track": "overhaul",
-  "explore": {
-    "startedAt": "<ISO8601>",
-    "scopeAssessment": {
-      "filesAffected": ["<paths>"],
-      "modulesAffected": ["<modules>"],
-      "testCoverage": "good | gaps | none",
-      "recommendedTrack": "overhaul"
-    }
-  }
-}, phase: "brief"
+**Set track and scope assessment, then transition to brief:**
+
+Before calling `set`, query the required guard shape:
+```
+exarchos_workflow({ action: "describe", playbook: "refactor" })
 ```
+Use the returned guard requirements for the `explore → brief` transition to construct your `set` call with the correct fields.
 
 ### 2. Brief Phase
 
 Detailed capture of refactor intent (more thorough than polish).
 
-**Save brief and advance:**
-```
-action: "set", featureId: "refactor-<slug>", updates: {
-  "brief": {
-    "problem": "<problem statement>",
-    "goals": ["<goal1>", "<goal2>"],
-    "approach": "<approach>",
-    "affectedAreas": ["<areas>"],
-    "outOfScope": ["<items>"],
-    "successCriteria": ["<criteria>"],
-    "docsToUpdate": ["<doc paths>"]
-  }
-}, phase: "overhaul-plan"
-```
+**Save brief and advance to overhaul-plan:**
+
+Call `exarchos_workflow({ action: "describe", playbook: "refactor" })` for the `brief → overhaul-plan` guard requirements, then `set` the required fields and phase.
 
 Then auto-invoke plan:
 ```typescript
@@ -88,12 +69,8 @@ The `/exarchos:plan` skill:
 - Dependency order matters more for refactors
 
 **Save plan and advance to plan-review:**
-```
-action: "set", featureId: "refactor-<slug>", updates: {
-  "artifacts": { "plan": "<plan-file-path>" },
-  "tasks": [{ "id": "001", "title": "...", "status": "pending", "branch": "...", "blockedBy": [] }, ...]
-}, phase: "overhaul-plan-review"
-```
+
+Call `exarchos_workflow({ action: "describe", playbook: "refactor" })` for the `overhaul-plan → overhaul-plan-review` guard requirements, then `set` the required fields (plan artifact, tasks array) and phase.
 
 **Human checkpoint:** Plan-review verifies plan coverage against the brief before committing to delegation. The orchestrator compares design sections against planned tasks.
 - Gaps found → set `.planReview.gaps`, auto-loop back to `/exarchos:plan --revise`
@@ -120,9 +97,8 @@ The `/exarchos:delegate` skill:
 - Tracks progress in state file
 
 **Advance to review:**
-```
-action: "set", featureId: "refactor-<slug>", phase: "overhaul-review"
-```
+
+Call `exarchos_workflow({ action: "describe", playbook: "refactor" })` for the `overhaul-delegate → overhaul-review` guard requirements, then `set` the phase.
 
 Then auto-invoke review:
 ```typescript
@@ -143,9 +119,8 @@ The `/exarchos:review` skill:
 - Verifies structure matches brief goals
 
 **Advance to doc updates:**
-```
-action: "set", featureId: "refactor-<slug>", phase: "overhaul-update-docs"
-```
+
+Call `exarchos_workflow({ action: "describe", playbook: "refactor" })` for the `overhaul-review → overhaul-update-docs` guard requirements, then `set` the phase.
 
 ### 6. Update Docs Phase
 
@@ -155,9 +130,8 @@ Verify all documentation links are valid:
 
 ```typescript
 exarchos_orchestrate({
-  action: "run_script",
-  script: "verify-doc-links.sh",
-  args: ["--docs-dir", "docs/"]
+  action: "verify_doc_links",
+  docsDir: "docs/"
 })
 ```
 
@@ -170,13 +144,9 @@ For overhaul, typically includes:
 - Migration guides if public interfaces changed
 - Updated diagrams
 
-**Mark docs updated and advance:**
-```
-action: "set", featureId: "refactor-<slug>", updates: {
-  "validation": { "docsUpdated": true },
-  "artifacts": { "updatedDocs": ["<doc paths>"] }
-}, phase: "synthesize"
-```
+**Mark docs updated and advance to synthesize:**
+
+Call `exarchos_workflow({ action: "describe", playbook: "refactor" })` for the `overhaul-update-docs → synthesize` guard requirements, then `set` the required fields (validation, artifacts) and phase.
 
 Then auto-invoke synthesize:
 ```typescript

package/skills/{refactor → claude/refactor/references}/phases/polish-implement.md

@@ -45,7 +45,7 @@ Must return: `"polish"`
 ```
 action: "get", featureId: "refactor-<slug>", query: ".phase"
 ```
-Must return: `"implement"`
+Must return: `"polish-implement"`
 
 **Check goals:**
 ```
@@ -58,7 +58,7 @@ Must return: populated array
 | Field | Requirement |
 |-------|-------------|
 | `.track` | "polish" |
-| `.phase` | "implement" |
+| `.phase` | "polish-implement" |
 | `.brief.problem` | Non-empty string |
 | `.brief.goals` | 1-3 items |
 | `.brief.affectedAreas` | 1-5 files |

package/skills/{refactor → claude/refactor/references}/phases/polish-validate.md

@@ -143,7 +143,7 @@ action: "set", featureId: "refactor-<slug>", updates: {
 action: "set", featureId: "refactor-<slug>", updates: {
   "validation.testsPass": false,
   "validation.failureReason": "<reason>"
-}, phase: "implement"
+}, phase: "polish-implement"
 ```
 
 ## Pass/Fail Handling

package/skills/{refactor → claude/refactor}/references/polish-track.md

@@ -34,21 +34,13 @@ Use `@skills/refactor/references/explore-checklist.md` to assess:
 action: "init", featureId: "refactor-<slug>", workflowType: "refactor"
 ```
 
-**Set track and scope assessment:**
+**Set track and scope assessment, then transition to brief:**
+
+Before calling `set`, query the required guard shape:
 ```
-action: "set", featureId: "refactor-<slug>", updates: {
-  "track": "polish",
-  "explore": {
-    "startedAt": "<ISO8601>",
-    "scopeAssessment": {
-      "filesAffected": ["<paths>"],
-      "modulesAffected": ["<modules>"],
-      "testCoverage": "good | gaps | none",
-      "recommendedTrack": "polish"
-    }
-  }
-}, phase: "brief"
+exarchos_workflow({ action: "describe", playbook: "refactor" })
 ```
+Use the returned guard requirements for the `explore → brief` transition to construct your `set` call with the correct fields.
 
 ### 2. Brief Phase
 
@@ -62,20 +54,9 @@ Use `@skills/refactor/references/brief-template.md` to structure:
 - Success criteria
 - Docs to update
 
-**Save brief and advance:**
-```
-action: "set", featureId: "refactor-<slug>", updates: {
-  "brief": {
-    "problem": "<problem statement>",
-    "goals": ["<goal1>", "<goal2>"],
-    "approach": "<approach>",
-    "affectedAreas": ["<areas>"],
-    "outOfScope": ["<items>"],
-    "successCriteria": ["<criteria>"],
-    "docsToUpdate": ["<doc paths>"]
-  }
-}, phase: "polish-implement"
-```
+**Save brief and advance to polish-implement:**
+
+Call `exarchos_workflow({ action: "describe", playbook: "refactor" })` for the `brief → polish-implement` guard requirements, then `set` the required fields (brief) and phase.
 
 ### 3. Implement Phase
 
@@ -94,9 +75,8 @@ git push -u origin refactor/<brief-name>
 ```
 
 **Advance to validation:**
-```
-action: "set", featureId: "refactor-<slug>", phase: "polish-validate"
-```
+
+Call `exarchos_workflow({ action: "describe", playbook: "refactor" })` for the `polish-implement → polish-validate` guard requirements, then `set` the phase.
 
 ### 4. Validate Phase
 
@@ -104,16 +84,15 @@ Verify scope hasn't expanded beyond polish limits:
 
 ```typescript
 mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
-  action: "run_script",
-  script: "check-polish-scope.sh",
-  args: ["--repo-root", "<path>"]
+  action: "check_polish_scope",
+  repoRoot: "<path>"
 })
 ```
 
 **On `passed: true`:** Scope OK — stay on polish track.
 **On `passed: false`:** Scope expanded — switch to overhaul track.
 
-Then run the refactor validation via the static analysis gate (which has no timeout constraint, unlike `run_script`'s 30s limit):
+Then run the refactor validation via the static analysis gate:
 
 ```typescript
 mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
@@ -126,12 +105,9 @@ mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
 **On `passed: true`:** All static analysis checks pass (lint, typecheck).
 **On `passed: false`:** One or more static analysis checks failed — fix before proceeding.
 
-**Save validation results and advance:**
-```
-action: "set", featureId: "refactor-<slug>", updates: {
-  "validation": { "testsPass": true, "goalsVerified": ["<verified goals>"] }
-}, phase: "polish-update-docs"
-```
+**Save validation results and advance to polish-update-docs:**
+
+Call `exarchos_workflow({ action: "describe", playbook: "refactor" })` for the `polish-validate → polish-update-docs` guard requirements, then `set` the required fields (validation) and phase.
 
 ### 5. Update Docs Phase
 
@@ -146,12 +122,8 @@ Use `@skills/refactor/references/doc-update-checklist.md` to update:
 If `docsToUpdate` is empty, verify no docs need updating.
 
 **Mark docs updated and complete:**
-```
-action: "set", featureId: "refactor-<slug>", updates: {
-  "validation": { "docsUpdated": true },
-  "artifacts": { "updatedDocs": ["<doc paths>"] }
-}, phase: "completed"
-```
+
+Call `exarchos_workflow({ action: "describe", playbook: "refactor" })` for the `polish-update-docs → completed` guard requirements, then `set` the required fields (validation, artifacts) and phase.
 
 > **Note:** The HSM transitions directly from `polish-update-docs` to `completed`. There is no `synthesize` phase for polish track.
 

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:
@@ -36,6 +40,10 @@ Activate when:
 
 ## Process
 
+> **Runbook:** Each shepherd iteration follows the shepherd-iteration runbook:
+> `exarchos_orchestrate({ action: "runbook", id: "shepherd-iteration" })`
+> If runbook unavailable, use `describe` to retrieve action schemas: `exarchos_orchestrate({ action: "describe", actions: ["assess_stack"] })`
+
 The shepherd loop repeats until all PRs are healthy or escalation criteria are met. Default: 5 iterations.
 
 ### Step 0 — Surface Quality Signals
@@ -183,18 +191,34 @@ mcp__plugin_exarchos_exarchos__exarchos_workflow({
 
 **After each iteration:** Update `currentIteration`, record assessment summary and actions taken. On approval: set `approvalRequested: true` with timestamp and approver list.
 
+### Phase Transitions and Guards
+
+For the full transition table, consult `@skills/workflow-state/references/phase-transitions.md`.
+
+The shepherd skill operates within the `synthesize` phase and does not drive phase transitions directly.
+
+### 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_event({ action: "describe", eventTypes: ["shepherd.iteration", "ci.status", "remediation.attempted"] })`
+for event data schemas before emitting events.
+
 ## Event Emission
 
-| Event | Required Fields (`data`) | When | Purpose |
-|-------|--------------------------|------|---------|
-| `shepherd.started` | `prUrl` (string), `stackSize` (number), `ciStatus` (string) | On skill start | Audit trail |
-| `shepherd.iteration` | `iteration` (number), `prsAssessed` (number), `fixesApplied` (number), `status` (string) | After each assess cycle | Track progress |
-| `gate.executed` | `gateName`, `layer`, `passed`, `details` | Per CI check (emitted by `assess_stack`) | CodeQualityView — gate pass rates |
-| `ci.status` | `pr` (number), `status` (string) | Per CI check result | ShepherdStatusView — PR health tracking |
-| `remediation.attempted` | `taskId` (string), `skill` (string), `gateName` (string), `attemptNumber` (number), `strategy` (string) | Before applying a fix | selfCorrectionRate metric |
-| `remediation.succeeded` | `taskId` (string), `skill` (string), `gateName` (string), `totalAttempts` (number), `finalStrategy` (string) | After fix confirmed | avgRemediationAttempts metric |
-| `shepherd.approval_requested` | `prUrl` (string), `reviewers` (string[]) | On requesting review | Audit trail |
-| `shepherd.completed` | `prUrl` (string), `totalIterations` (number), `outcome` (string) | On completion | Audit trail |
+Before emitting any shepherd events, consult `references/shepherd-event-schemas.md` for full Zod schemas, type constraints, and example payloads. Use `exarchos_event({ action: "describe", eventTypes: ["shepherd.iteration", "ci.status"] })` to discover required fields at runtime.
+
+| Event | When | Purpose |
+|-------|------|---------|
+| `shepherd.started` | On skill start (emitted by `assess_stack`) | Audit trail |
+| `shepherd.iteration` | After each assess cycle | Track progress |
+| `gate.executed` | Per CI check (emitted by `assess_stack`) | CodeQualityView -- gate pass rates |
+| `ci.status` | Per CI check result | ShepherdStatusView -- PR health tracking |
+| `remediation.attempted` | Before applying a fix | selfCorrectionRate metric |
+| `remediation.succeeded` | After fix confirmed | avgRemediationAttempts metric |
+| `shepherd.approval_requested` | On requesting review | Audit trail |
+| `shepherd.completed` | On merge detected (emitted by `assess_stack`) | Audit trail |
 
 ## Domain Knowledge
 
@@ -202,6 +226,14 @@ Consult these references for detailed guidance:
 - `references/fix-strategies.md` — Fix approaches per issue type, response templates, remediation event emission details
 - `references/escalation-criteria.md` — When to stop iterating and escalate to the user
 - `references/gate-event-emission.md` — Event format for `gate.executed` (now emitted by `assess_stack`)
+- `references/shepherd-event-schemas.md` — Full Zod-aligned schemas for all four shepherd lifecycle events
+
+### Decision Runbooks
+
+When iteration limits are reached or CI repeatedly fails, consult the escalation runbook:
+`exarchos_orchestrate({ action: "runbook", id: "shepherd-escalation" })`
+
+This runbook provides structured criteria for deciding whether to keep iterating, escalate to the user, or abort the shepherd loop based on iteration count, CI stability, and review status.
 
 ## Anti-Patterns
 

package/skills/{shepherd → claude/shepherd}/references/fix-strategies.md

@@ -237,8 +237,7 @@ git push --force-with-lease
 If the stack is in a broken state:
 ```typescript
 exarchos_orchestrate({
-  action: "run_script",
-  script: "reconstruct-stack.sh"
+  action: "reconstruct_stack"
 })
 ```