@lvlup-sw/exarchos 2.4.3 → 2.6.0

package/skills/copilot/quality-review/references/code-quality-checklist.md

@@ -0,0 +1,171 @@
+# Code Quality Checklist
+
+Detailed review criteria for code quality, SOLID principles, DRY enforcement, and structural standards. Used during Step 2 of the quality review process.
+
+## Adversarial Review Posture
+
+You are an ADVERSARIAL reviewer. Your job is to find quality issues, not rubber-stamp passing code.
+
+- Do NOT trust that "tests pass" means the code is well-structured
+- Do NOT accept "it works" as sufficient quality evidence
+- Do NOT assume the implementer followed SOLID principles without verifying
+- Independently check each quality dimension against the actual code
+- Treat every claim of quality as unverified until you see the evidence yourself
+
+Consult `references/rationalization-refutation.md` when you feel tempted to accept a rationalization for skipping quality checks.
+
+## 1. Code Quality
+
+| Aspect | Check For |
+|--------|-----------|
+| Readability | Clear variable/function names |
+| Complexity | Functions <30 lines, single responsibility |
+| Duplication | DRY - no copy-paste code |
+| Comments | Only where logic isn't self-evident |
+| Formatting | Consistent with project style |
+
+## 1.1 DRY Enforcement
+
+| Pattern | Threshold | Priority |
+|---------|-----------|----------|
+| Identical code blocks | 3+ occurrences OR 5+ lines | HIGH (3+), MEDIUM (2) |
+| Similar code (literals differ) | 3+ occurrences | MEDIUM |
+| Repeated validation logic | 2+ locations | HIGH |
+| Repeated business rules | 2+ locations | HIGH |
+| Copy-pasted tests | 3+ similar tests | LOW |
+| Magic literals | Same value 3+ times | MEDIUM |
+
+**Detection approach (prefer MCP tools):**
+- Use `search_for_pattern` to find duplicate code blocks
+- Use `find_referencing_symbols` to trace dependency usage
+- Use `get_symbols_overview` to understand module structure
+
+**Detection checklist:**
+- [ ] Search for identical multi-line blocks (5+ lines duplicated)
+- [ ] Flag validation code outside designated validation layer
+- [ ] Trace business rule conditionals - must have single source
+- [ ] Check for repeated string/number literals without constants
+
+## 2. SOLID Principles
+
+| Principle | Verify | Specific Checks |
+|-----------|--------|-----------------|
+| **S**RP | One reason to change | Max 1 public type/file; class name matches responsibility |
+| **O**CP | Extensible without modification | No switch/if-else on types; uses strategy/polymorphism |
+| **L**SP | Subtypes substitutable | No `NotImplementedException`; no precondition strengthening |
+| **I**SP | No forced dependencies | Interface <= 5 methods; no empty implementations |
+| **D**IP | Depend on abstractions | No `new` for services; constructor injection only |
+
+### ISP Violation Patterns
+
+| Pattern | Detection | Priority |
+|---------|-----------|----------|
+| Fat interface (> 5 methods) | Count methods on interface | MEDIUM |
+| Mixed read/write interface | Check for getters + mutators together | MEDIUM |
+| Empty/throw implementations | Scan for `NotImplementedException`, empty bodies | HIGH |
+| Vague interface names | `IService`, `IManager`, `IHandler` without qualifier | LOW |
+| Partial interface usage | Client uses < 50% of interface methods | MEDIUM |
+
+**ISP Checklist:**
+- [ ] No interface has more than 5 methods
+- [ ] Interfaces are role-specific (IReadable, IWritable, not IDataAccess)
+- [ ] No classes implement interfaces with NotImplementedException
+- [ ] Interface names describe a single capability
+
+## 2.1 Control Flow Standards
+
+| Standard | Check For |
+|----------|-----------|
+| Guard clauses | Validate at method entry, not nested |
+| Early returns | Exit as soon as result is known |
+| No arrow code | Deeply nested if/else is a smell |
+| Conditional abstraction | Large switch/if-else extracted to helper |
+
+### Guard Clause Pattern
+
+**Preferred:**
+```typescript
+if (input == null) return;
+// Main logic flat
+```
+
+**Avoid:**
+```typescript
+if (input != null) {
+  // Entire body nested
+}
+```
+
+## 2.2 Structural Standards
+
+| Standard | Check For | Priority |
+|----------|-----------|----------|
+| One responsibility per file | Public types in dedicated files | HIGH |
+| Composition over inheritance | See checklist below | MEDIUM-HIGH |
+| Sealed by default | `sealed` unless designed for extension | LOW |
+
+### Composition Over Inheritance Checklist
+
+| Smell | Detection | Priority | Fix |
+|-------|-----------|----------|-----|
+| Inheritance depth > 2 | Count hierarchy levels | MEDIUM | Refactor to delegation |
+| Base class, multiple concerns | Base has unrelated methods | MEDIUM | Split into interfaces + composition |
+| `protected` for code sharing | Many protected methods (> 2/class) | MEDIUM | Extract to utility or inject strategy |
+| Override that only extends | `super.method()` + additions | MEDIUM | Use decorator pattern |
+| Inherit for one method | Extends to reuse single method | HIGH | Compose with delegation |
+
+**Composition Checklist:**
+- [ ] Inheritance represents true "is-a" relationship, not code reuse
+- [ ] Class hierarchy depth <= 2
+- [ ] `protected` methods rare (< 2 per class)
+- [ ] No override methods that just call super + add logic
+
+**Language-specific rules:** See `~/.claude/rules/coding-standards-{language}.md`
+
+## 3. Error Handling
+
+| Check | Verify |
+|-------|--------|
+| Errors caught | Try/catch where needed |
+| Errors meaningful | Clear error messages |
+| Errors propagated | Proper error bubbling |
+| No silent failures | All errors handled or logged |
+| Input validation | At system boundaries |
+
+## 4. Test Quality
+
+| Aspect | Verify |
+|--------|--------|
+| Arrange-Act-Assert | Clear test structure |
+| Test isolation | No shared state issues |
+| Meaningful assertions | Not just "expect(true)" |
+| Edge cases | Boundary conditions tested |
+| Error paths | Failure scenarios covered |
+
+## 5. Performance
+
+| Check | Verify |
+|-------|--------|
+| No N+1 queries | Batch operations used |
+| Efficient algorithms | No obvious O(n^2) when O(n) works |
+| Memory management | No leaks, proper cleanup |
+| Async patterns | Proper await usage |
+
+## 6. Frontend Aesthetics (if applicable)
+
+For frontend code (React, Vue, HTML/CSS, etc.), verify distinctive design:
+
+| Check | Verify |
+|-------|--------|
+| Distinctive typography | Not using Inter, Roboto, Arial, or system defaults |
+| Intentional color palette | CSS variables defined, not ad-hoc colors |
+| Purposeful motion | Orchestrated animations, not scattered micro-interactions |
+| Atmospheric backgrounds | Layered/textured, not flat solid colors |
+| Overall distinctiveness | Doesn't exhibit "AI slop" patterns |
+
+**Anti-patterns to flag:**
+- Purple gradients on white backgrounds
+- Perfectly centered symmetric layouts
+- Generic font choices
+- Flat #f5f5f5 or pure white/black backgrounds
+- Animation without purpose

package/skills/copilot/quality-review/references/convergence-and-verdict.md

@@ -0,0 +1,48 @@
+# Convergence Check & Verdict Determination
+
+## Check Convergence
+
+Before computing the verdict, query the convergence view for the aggregate D1-D5 status from all gate events emitted during the pipeline:
+
+```typescript
+exarchos_orchestrate({
+  action: "check_convergence",
+  featureId: "<id>"
+})
+```
+
+The handler returns:
+- `passed: true` — all five dimensions (D1-D5) have at least one gate result and all gates passed
+- `passed: false` — one or more dimensions have failing gates or no gate coverage yet
+- `uncheckedDimensions` — dimensions with no gate events (cold pipeline)
+- `dimensions` — per-dimension summary with gate counts and convergence status
+
+Use the convergence result as structured input to the verdict:
+- If `uncheckedDimensions` is non-empty, note which dimensions lack gate coverage in the review report
+- If a dimension has `converged: false`, include it as a finding in the verdict input
+- If `passed: true`, it provides strong evidence for APPROVED (pending qualitative assessment)
+
+## Determine Verdict
+
+Classify review findings into a routing verdict via orchestrate:
+
+```typescript
+exarchos_orchestrate({
+  action: "check_review_verdict",
+  featureId: "<id>",
+  high: <N>,
+  medium: <N>,
+  low: <N>,
+  dimensionResults: {
+    "D1": { passed: true, findingCount: 0 },
+    "D2": { passed: true, findingCount: 0 },
+    // ... include results from each gate run above
+  }
+})
+```
+
+The handler automatically emits per-dimension and summary `gate.executed` events. No manual event emission needed.
+
+**On `verdict: "APPROVED"`:** Proceed to synthesis.
+**On `verdict: "NEEDS_FIXES"`:** Route to `/exarchos:delegate --fixes`.
+**On `verdict: "BLOCKED"`:** Return to design phase.

package/skills/copilot/quality-review/references/gate-execution.md

@@ -0,0 +1,60 @@
+# Gate Execution Details
+
+## Step 1: Static Analysis
+
+Run the static analysis gate via orchestrate:
+
+```typescript
+exarchos_orchestrate({
+  action: "check_static_analysis",
+  featureId: "<id>",
+  repoRoot: "<repo-root>"
+})
+```
+
+The handler runs lint, typecheck, and quality-check (if available), distinguishing errors from warnings. It automatically emits a `gate.executed` event with dimension D2.
+
+**On `passed: true`:** All analysis passes — proceed to Step 2.
+**On `passed: false`:** Errors found — fix before continuing review.
+
+## Step 2: Code Walkthrough
+
+Assess each modified file against the quality checklists:
+- Consult `code-quality-checklist.md` for code quality, SOLID, DRY, and structural criteria
+- Consult `security-checklist.md` for security review criteria
+- Consult `typescript-standards.md` for TypeScript-specific conventions (file organization, naming, patterns)
+
+## Step 2.5: Security Scan (Automated)
+
+Run automated security pattern detection via orchestrate:
+
+```typescript
+exarchos_orchestrate({
+  action: "check_security_scan",
+  featureId: "<id>",
+  repoRoot: "<repo-root>",
+  baseBranch: "main"
+})
+```
+
+The handler automatically emits a `gate.executed` event with dimension D1.
+
+**On `passed: true`:** No security patterns detected.
+**On `passed: false`:** Potential security issues found — include in review report.
+
+## Step 2.6: Extended Quality Gates (Optional)
+
+When available, run additional quality gates for D3-D5 dimensions:
+
+```typescript
+// D3: Context Economy — code complexity impacting LLM context
+exarchos_orchestrate({ action: "check_context_economy", featureId: "<id>", repoRoot: "<repo-root>", baseBranch: "main" })
+
+// D4: Operational Resilience — empty catches (excluding intentional fire-and-forget telemetry), swallowed errors, console.log
+exarchos_orchestrate({ action: "check_operational_resilience", featureId: "<id>", repoRoot: "<repo-root>", baseBranch: "main" })
+
+// D5: Workflow Determinism — .only/.skip, non-deterministic time/random, debug artifacts
+exarchos_orchestrate({ action: "check_workflow_determinism", featureId: "<id>", repoRoot: "<repo-root>", baseBranch: "main" })
+```
+
+Each handler automatically emits `gate.executed` events with the appropriate dimension. Findings from these checks are advisory and feed into the convergence view but do not independently block the review.

package/skills/copilot/quality-review/references/rationalization-refutation.md

@@ -0,0 +1,13 @@
+# Rationalization Refutation — Quality Review
+
+Common rationalizations that undermine quality review rigor, with counter-arguments and correct actions.
+
+| Rationalization | Counter-argument | What to do instead |
+|-----------------|------------------|--------------------|
+| "The code works so quality doesn't matter" | Working code that violates SOLID, DRY, or readability standards becomes unmaintainable code. "Works" is the minimum bar, not the quality bar. Technical debt from low-quality code costs more to fix later than to prevent now. | Evaluate every quality dimension independently: readability, SOLID compliance, DRY, error handling, test quality. Working code that fails quality review goes back for fixes. |
+| "This is temporary code" | There is no such thing as temporary code in production. Temporary code survives because removing it requires understanding it, and low-quality temporary code resists understanding. | Apply the same quality standards to all code. If the code is truly temporary, it should have a removal plan with a deadline and a tracking issue. |
+| "Refactoring later is fine" | "Later" never comes. Every deferred refactor adds to a backlog that grows faster than it shrinks. The code you defer today becomes the legacy code someone struggles with tomorrow. | Require the refactor now if it addresses a HIGH or MEDIUM quality finding. Only defer LOW-priority items, and only with an explicit tracking issue. |
+| "The tests cover it" | Test coverage does not equal code quality. Tests can cover 100% of poorly structured, duplicated, insecure code. Coverage measures execution paths, not maintainability, readability, or security. | Review the code on its own merits: structure, naming, SOLID, DRY, error handling. Then review the tests for quality too — tests are code and deserve the same scrutiny. |
+| "It's just a style issue" | Consistent style is a quality issue. Style inconsistencies increase cognitive load, slow onboarding, and introduce subtle bugs when developers misread unfamiliar patterns. | Enforce project style standards. Flag style violations as LOW priority but still require them to be fixed. Style is not optional — it is part of maintainability. |
+| "The implementer is more experienced, they know best" | Experience does not prevent quality lapses. Even expert developers write code with SOLID violations, missing error handling, and unnecessary complexity — especially under time pressure. | Apply the checklist uniformly regardless of author experience. Quality standards are objective criteria, not subjective opinions. Trust the checklist, not the reputation. |
+| "It's too late to change the architecture" | If the architecture has quality issues, approving it locks them in permanently. The cost of fixing architecture now is high; the cost of living with broken architecture forever is higher. | Flag architectural quality issues as HIGH priority. If they truly cannot be fixed in this cycle, document them as accepted technical debt with an explicit remediation plan. |

package/skills/copilot/quality-review/references/review-report-template.md

@@ -0,0 +1,65 @@
+# Quality Review Report Template
+
+Use this template to structure the output of Step 3 (Generate Report) in the quality review process.
+
+## Template
+
+```markdown
+## Quality Review Report
+
+### Summary
+- Status: [APPROVED | NEEDS_FIXES | BLOCKED]
+- Reviewed: [timestamp]
+- Reviewer: Claude Code
+
+### Findings Summary
+
+| Severity | Category | File:Line | Issue |
+|----------|----------|-----------|-------|
+| HIGH | [category] | `path/to/file.ts:42` | [Brief description] |
+| MEDIUM | [category] | `path/to/file.ts:88` | [Brief description] |
+| LOW | [category] | `path/to/file.ts:15` | [Brief description] |
+
+### Findings Detail
+
+#### HIGH-Priority
+1. [Finding title]
+   - File: `path/to/file.ts:42`
+   - Category: [security | correctness | performance | maintainability]
+   - Current: [What the code does now]
+   - Fix: [Required change]
+
+#### MEDIUM-Priority
+1. [Finding title]
+   - File: `path/to/file.ts:88`
+   - Category: [security | correctness | performance | maintainability]
+   - Current: [What the code does now]
+   - Suggestion: [Recommended change]
+
+#### LOW-Priority
+1. [Finding title]
+   - File: `path/to/file.ts:15`
+   - Category: [style | documentation | optimization]
+   - Note: [Observation]
+
+### Verdict
+[APPROVED] Ready for synthesis
+[NEEDS_FIXES] Fix HIGH-priority items, then re-review
+[BLOCKED] Critical issues require design discussion
+```
+
+## Verdict Criteria
+
+| Verdict | Condition |
+|---------|-----------|
+| **APPROVED** | No HIGH-priority findings; MEDIUM/LOW acceptable |
+| **NEEDS_FIXES** | One or more HIGH-priority findings that must be resolved |
+| **BLOCKED** | Critical architectural or security issues requiring design discussion |
+
+## Report Guidelines
+
+- List every finding with file path and line number
+- HIGH-priority findings must include a concrete fix description
+- MEDIUM priority findings should include a suggested approach
+- LOW priority findings are observations for future improvement
+- The verdict drives the next workflow transition (synthesize, fix loop, or redesign)

package/skills/copilot/quality-review/references/security-checklist.md

@@ -0,0 +1,79 @@
+# Security Review Checklist
+
+Security review criteria based on OWASP Top 10 patterns. Used during Step 2 of the quality review process.
+
+## Security Basics
+
+| Check | Verify |
+|-------|--------|
+| Input sanitization | User input validated |
+| No secrets in code | Use environment variables |
+| SQL injection | Parameterized queries |
+| XSS prevention | Output encoding |
+
+## OWASP Top 10 (2021) Patterns
+
+When reviewing code that handles user input, authentication, or data access, check for these common vulnerability patterns:
+
+### Broken Access Control (A01)
+- Authorization checks on every endpoint
+- No direct object references without access validation
+- Default deny for permissions
+
+### Cryptographic Failures (A02)
+- No secrets, API keys, or credentials in source code
+- Sensitive data encrypted at rest and in transit
+- PII properly handled per data classification
+
+### Injection (A03)
+- SQL queries use parameterized statements, never string concatenation
+- Shell commands use safe APIs, never template strings with user input
+- Output encoding applied to all user-controlled data (XSS)
+- Content Security Policy headers set
+
+### Insecure Design (A04)
+- Threat modeling performed for critical flows
+- Business logic validated server-side
+- Rate limiting and resource controls in place
+
+### Security Misconfiguration (A05)
+- No debug mode in production config
+- Error messages don't leak stack traces or internal details
+- Security headers configured (CORS, CSP, HSTS)
+
+### Vulnerable and Outdated Components (A06)
+- Dependencies checked for known vulnerabilities
+- No end-of-life frameworks or libraries
+- Component versions tracked and updated
+
+### Identification and Authentication Failures (A07)
+- Passwords are hashed with bcrypt/argon2, never stored in plaintext
+- Session tokens have sufficient entropy
+- Rate limiting on authentication endpoints
+
+### Software and Data Integrity Failures (A08)
+- User input is validated before deserialization
+- Type checking enforced on deserialized objects
+- No eval() or equivalent on untrusted data
+- CI/CD pipeline integrity verified
+
+### Security Logging and Monitoring Failures (A09)
+- Security-relevant events are logged
+- Logs do not contain sensitive data
+- Alerting configured for suspicious activity
+
+### Server-Side Request Forgery (A10)
+- URL inputs validated against allowlists
+- Internal network access restricted from user-controlled requests
+- DNS rebinding protections in place
+
+## Detection Checklist
+
+- [ ] No hardcoded secrets or API keys
+- [ ] All user input validated at system boundaries
+- [ ] SQL/NoSQL queries use parameterized statements
+- [ ] Output encoding applied for XSS prevention
+- [ ] Authentication uses secure hashing algorithms
+- [ ] Authorization checks present on all endpoints
+- [ ] Error messages do not expose internal details
+- [ ] Dependencies checked for known vulnerabilities

package/skills/copilot/quality-review/references/typescript-standards.md

@@ -0,0 +1,24 @@
+# TypeScript Standards
+
+## File Organization
+
+- **One primary export per file**: Main class/function/component as default or named export
+- **Barrel exports OK**: `index.ts` can re-export from module
+- **Co-locate tests**: `component.test.ts` alongside `component.ts`
+
+## Type Design
+
+| Rule | Standard |
+|------|----------|
+| Interfaces over type aliases | For object shapes that might be extended |
+| Discriminated unions | For type-safe variant handling |
+| `readonly` by default | For properties that shouldn't change |
+| No `any` | Use `unknown` with type guards or proper generics |
+| Strict mode | `strict: true` in tsconfig required |
+
+## Modern TypeScript
+
+- **Const assertions**: Use `as const` for literal types
+- **Template literal types**: For string pattern validation
+- **No assertions without guards**: `as` requires prior type check
+- **Satisfies operator**: For type checking without widening

package/skills/copilot/refactor/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: refactor
+description: "Code improvement workflow with polish and overhaul tracks. Triggers: 'refactor', 'clean up', 'restructure', 'reorganize', or /refactor. Phases: explore, brief, implement, validate. Existing code only — Do NOT use for bug fixes (/debug) or new features (/ideate)."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  mcp-server: exarchos
+  category: workflow
+  phase-affinity:
+    - explore
+    - brief
+    - polish-implement
+    - polish-validate
+    - polish-update-docs
+    - overhaul-plan
+    - overhaul-plan-review
+    - overhaul-delegate
+    - overhaul-review
+    - overhaul-update-docs
+    - synthesize
+---
+
+# Refactor Workflow Skill
+
+## Overview
+
+Two-track workflow for improving existing code. Polish track for small, contained refactors; overhaul track for architectural changes and migrations. Both tracks emphasize exploration before commitment and mandatory documentation updates.
+
+## Triggers
+
+Activate this skill when:
+- User runs `/refactor` command
+- User wants to improve existing code structure
+- User mentions "refactor", "restructure", "clean up", "migrate"
+- User asks to "move", "extract", "rename", or "reorganize" code
+
+**Disambiguation:** If the user says "fix" or "clean up" — use `/refactor` when the code *works* but needs structural improvement. Use `/debug` when something is *broken* (error, crash, wrong behavior).
+
+## Workflow Overview
+
+```
+                              /refactor
+                                  |
+                            +-----+-----+
+                            |  Explore  |
+                            +-----+-----+
+                                  |
+                   +--------------+--------------+
+                   |                             |
+              --polish                       (default)
+                   |                             |
+                   v                             v
+          +--------------+              +--------------+
+          |    Polish    |              |   Overhaul   |
+          |    Track     |              |    Track     |
+          +--------------+              +--------------+
+```
+
+## Command Interface
+
+### Start Refactor Workflow
+
+```bash
+# Default: overhaul track
+/refactor "Description of what needs refactoring"
+
+# Fast path: polish track
+/refactor --polish "Small contained refactor description"
+
+# Explore first, then decide track
+/refactor --explore "Unsure of scope, explore first"
+```
+
+### Mid-Workflow Commands
+
+```bash
+# Switch from polish to overhaul (during explore/brief)
+/refactor --switch-overhaul
+
+# Resume after context compaction
+/rehydrate
+```
+
+## Track Comparison
+
+| Aspect | Polish | Overhaul |
+|--------|--------|----------|
+| Scope | <=5 files, single concern | No limit |
+| Worktree | No (direct) | Yes (isolated) |
+| Delegation | No | Yes (full workflow) |
+| 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.
+
+HSM phases: `explore` → `brief` → `polish-implement` → `polish-validate` → `polish-update-docs` → `completed`
+
+For detailed phase instructions, state management, and auto-chain behavior, see `@skills/refactor/references/polish-track.md`.
+
+## Overhaul Track
+
+Rigorous path for architectural changes, migrations, and multi-file restructuring. Uses full delegation model with worktree isolation.
+
+HSM phases: `explore` → `brief` → `overhaul-plan` → `overhaul-plan-review` → `overhaul-delegate` → `overhaul-review` → `overhaul-update-docs` → `synthesize` → `completed`
+
+For detailed phase instructions, skill invocations, and auto-chain behavior, see `@skills/refactor/references/overhaul-track.md`.
+
+## State Management
+
+Initialize refactor workflow:
+```
+action: "init", featureId: "refactor-<slug>", workflowType: "refactor"
+```
+
+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
+
+If scope expands beyond polish limits during explore or brief phase, use `mcp__exarchos__exarchos_workflow` with `action: "set"` to set `track` to "overhaul" and update `explore.scopeAssessment.recommendedTrack`.
+
+**Scope thresholds:** If >5 files affected OR changes cross module boundaries -> recommend overhaul track.
+
+**Indicators to switch:**
+- More than 5 files affected
+- Multiple concerns identified
+- Cross-module changes needed
+- Test coverage gaps require new tests
+
+Output: "Scope expanded beyond polish limits. Switching to overhaul track."
+
+## Integration Points
+
+**CRITICAL:** All skill invocations MUST use explicit `Skill()` tool calls:
+
+| Skill | Invocation | Usage |
+|-------|------------|-------|
+| `/plan` | `[Invoke the exarchos:plan skill with args: --refactor <state-file>]` | Task extraction from brief |
+| `/delegate` | `[Invoke the exarchos:delegate skill with args: <state-file>]` | Subagent dispatch for TDD |
+| `/review` | `[Invoke the exarchos:review skill with args: <state-file>]` | Quality review |
+| `/synthesize` | `[Invoke the exarchos:synthesize skill with args: <feature>]` | PR creation |
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Skip exploration | Always assess scope first (see `references/explore-checklist.md`) |
+| Use polish for large changes | Switch to overhaul when scope expands |
+| Skip doc updates | Documentation is mandatory (see `references/doc-update-checklist.md`) |
+| Add features during refactor | Scope creep - stick to brief goals |
+| Skip tests because "just moving code" | Refactors need test verification |
+| Create design document for polish | Use brief in state file instead |
+| Work in main for overhaul | Use worktree isolation |
+
+## Exarchos Integration
+
+When Exarchos MCP tools are available, emit events throughout the refactor workflow:
+
+1. **At workflow start (explore):** `mcp__exarchos__exarchos_event` with `action: "append"` → `workflow.started` with workflowType "refactor"
+2. **On track selection:** Auto-emitted by `exarchos_workflow` `set` when `phase` is provided — emits `workflow.transition` with selected track (polish/overhaul)
+3. **On each phase transition:** Auto-emitted by `exarchos_workflow` `set` when `phase` is provided — emits `workflow.transition` with from/to/trigger/featureId
+4. **Overhaul track stacking:** Handled by `/delegate` (subagents use `git commit` + `git push` per implementer prompt)
+5. **Polish track commit:** Single `git commit -m "refactor: <description>"` + `git push` — no multi-branch stacking needed
+6. **On complete:** Auto-emitted by `exarchos_workflow` `set` when transitioning to terminal state — emits `workflow.transition` to "completed"