@lvlup-sw/exarchos 2.4.3 → 2.6.0

package/skills/generic/refactor/references/phases/overhaul-plan.md

@@ -0,0 +1,312 @@
+# Overhaul Track: Plan Phase
+
+## Purpose
+
+Create detailed implementation plans for large refactors with emphasis on incremental, working-state changes. This phase integrates with the existing `/exarchos:plan` skill while adding refactor-specific constraints that ensure safety and reversibility.
+
+**Key principle:** Every task leaves the codebase in a working state. No task should break tests or functionality.
+
+## Entry Conditions
+
+- Track is `overhaul`
+- Brief phase complete with scope assessment
+- State file has `.track = "overhaul"` and `.phase = "brief"` complete
+- Refactoring goals documented in brief
+
+## Integration with /exarchos:plan
+
+The overhaul track leverages the existing `/exarchos:plan` skill with additional refactor context.
+
+### Invocation
+
+```bash
+# Auto-invocation from brief phase
+Skill({ skill: "exarchos:plan", args: "--refactor ~/.claude/workflow-state/<feature>.state.json" })
+```
+
+### Context Passing
+
+The `/exarchos:plan` skill receives refactor context from the brief:
+
+1. **Scope boundaries** - Which files/modules are affected
+2. **Refactoring goals** - What improvements are targeted
+3. **Constraints** - Working state requirements, rollback needs
+4. **Test baseline** - Current test status to maintain
+
+### Plan Modifications
+
+When `/exarchos:plan` receives refactor context, it applies these additional rules:
+
+| Standard Plan | Refactor Plan |
+|---------------|---------------|
+| Tasks can be feature-incomplete | Each task must leave code functional |
+| Tests verify new behavior | Tests verify existing + new behavior |
+| Dependencies between tasks | Explicit rollback points identified |
+| Parallel execution focus | Sequential safety emphasis |
+
+## Refactor-Specific Emphasis
+
+### 1. Incremental Changes (Working State Guarantee)
+
+**Every task MUST leave code in a working state.**
+
+Requirements per task:
+- [ ] Code compiles after task completion
+- [ ] All existing tests pass
+- [ ] New tests (if added) pass
+- [ ] No temporary broken states
+
+Anti-patterns to avoid:
+- "Part 1 of 3" tasks that break until Part 3
+- Renaming without updating all references
+- Interface changes without adapter layers
+- Deleting before replacing
+
+**Incremental Strategy Examples:**
+
+| Refactor Type | Safe Approach |
+|---------------|---------------|
+| Rename | Add alias -> Update references -> Remove old |
+| Extract | Create new -> Duplicate logic -> Redirect calls -> Delete original |
+| Replace | Add new alongside -> Toggle between -> Verify -> Remove old |
+| Restructure | Scaffold new -> Copy behavior -> Redirect -> Clean up |
+
+### 2. Rollback Points
+
+Identify explicit points where the refactor can be safely paused or abandoned.
+
+**Rollback Point Criteria:**
+- All tests pass
+- No temporary code remains
+- Could ship to production if needed
+- Clear documentation of state
+
+**Template:**
+
+```markdown
+## Rollback Points
+
+### After Task 003
+**State:** Old API deprecated, new API available
+**Can ship:** Yes
+**To resume:** Continue with Task 004
+**To abandon:** Remove deprecation warnings, new API becomes optional
+
+### After Task 007
+**State:** Migration complete, old code marked for deletion
+**Can ship:** Yes
+**To resume:** Continue with Task 008 (cleanup)
+**To abandon:** Keep both implementations, document tech debt
+```
+
+### 3. Test Strategy Per Task
+
+Each task specifies verification requirements:
+
+```markdown
+### Task 005: Extract validation logic to shared module
+
+**Test Requirements:**
+1. **Existing tests:** All unit tests in `auth.test.ts` must pass unchanged
+2. **New tests:** Add `validation.test.ts` with same coverage
+3. **Integration:** Run `npm run test:integration` to verify no regressions
+4. **Manual verification:** N/A (pure refactor)
+
+**Verification Command:**
+npm run test:run -- --coverage
+# Coverage must not decrease
+```
+
+### 4. Working State Guarantee
+
+After every task completion, verify:
+
+```bash
+# Compilation check
+npm run build
+
+# Unit tests
+npm run test:run
+
+# Integration tests (if applicable)
+npm run test:integration
+
+# Lint (code quality)
+npm run lint
+```
+
+**State tracking in workflow file:**
+
+```json
+{
+  "tasks": [
+    {
+      "id": "001",
+      "title": "Add new interface",
+      "status": "complete",
+      "working_state_verified": true,
+      "test_results": {
+        "passed": 145,
+        "failed": 0,
+        "coverage": "87%"
+      }
+    }
+  ]
+}
+```
+
+## Plan Structure Template
+
+Save to: `docs/plans/YYYY-MM-DD-<refactor-name>.md`
+
+```markdown
+# Implementation Plan: [Refactor Name]
+
+## Source
+- **Brief:** `~/.claude/workflow-state/<feature>.state.json`
+- **Track:** Overhaul
+- **Affected scope:** [Files/modules from brief]
+
+## Goals Mapping
+
+| Brief Goal | Task ID(s) | Verification |
+|------------|------------|--------------|
+| [Goal 1] | 001, 002 | [How verified] |
+| [Goal 2] | 003-005 | [How verified] |
+| [Goal 3] | 006 | [How verified] |
+
+## Working State Strategy
+
+**Approach:** [Describe overall incremental approach]
+
+**Key constraints:**
+- [Constraint 1 from brief]
+- [Constraint 2 from brief]
+
+## Task Breakdown
+
+### Task 001: [Title]
+
+**Phase:** [RED | GREEN | REFACTOR]
+
+**TDD Steps:**
+1. [RED] Write test: `TestName_Scenario_ExpectedOutcome`
+   - File: `path/to/test.ts`
+   - Expected failure: [Reason]
+   - Run: `npm run test:run` - MUST FAIL
+
+2. [GREEN] Implement minimum code
+   - File: `path/to/implementation.ts`
+   - Changes: [Description]
+   - Run: `npm run test:run` - MUST PASS
+
+3. [REFACTOR] Clean up (if needed)
+   - Apply: [Improvement]
+   - Run: `npm run test:run` - MUST STAY GREEN
+
+**Working State Check:**
+- [ ] Code compiles
+- [ ] All tests pass (existing + new)
+- [ ] No temporary hacks remain
+
+**Rollback point:** [Yes/No - if Yes, document in Rollback section]
+
+**Dependencies:** [Task IDs or "None"]
+
+---
+
+[Repeat for each task]
+
+## Rollback Points
+
+### After Task [N]
+**State:** [Description of codebase state]
+**Can ship:** [Yes/No]
+**To resume:** [Instructions]
+**To abandon:** [Cleanup instructions]
+
+## Verification Checklist
+
+After all tasks complete:
+- [ ] All original tests still pass
+- [ ] New tests added for new code
+- [ ] Code coverage maintained or improved
+- [ ] No TODO/FIXME comments left behind
+- [ ] Brief goals all achieved
+- [ ] Ready for review
+
+## Deferred Items
+
+[Any scope items explicitly deferred, with rationale]
+```
+
+## State Updates
+
+### On Plan Completion
+
+**Save plan artifact and tasks:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "artifacts.plan": "docs/plans/YYYY-MM-DD-<refactor>.md",
+  "tasks": [
+    {"id": "001", "title": "Task description", "status": "pending", "working_state_verified": false},
+    {"id": "002", "title": "Task 2 description", "status": "pending", "working_state_verified": false}
+  ]
+}
+```
+
+**Advance to delegate:**
+
+```
+action: "set", featureId: "refactor-<slug>", phase: "delegate"
+```
+
+### Task State Structure
+
+```json
+{
+  "id": "001",
+  "title": "Extract validation to shared module",
+  "status": "pending",
+  "working_state_verified": false,
+  "rollback_point": true,
+  "dependencies": [],
+  "branch": "refactor/001-extract-validation"
+}
+```
+
+## Exit Conditions
+
+Transition to `delegate` phase when:
+
+- [ ] Plan document created at `docs/plans/`
+- [ ] All brief goals mapped to tasks
+- [ ] Every task has working state verification criteria
+- [ ] Rollback points identified (minimum 1)
+- [ ] Test strategy defined per task
+- [ ] State file updated with plan path and tasks
+- [ ] Phase set to `delegate`
+
+## Transition to Delegate
+
+After plan completion, auto-continue to delegate:
+
+1. Update state with plan path and tasks (see State Updates above)
+2. Output: "Refactor plan created with [N] tasks and [M] rollback points. Auto-continuing to delegation..."
+3. Invoke immediately:
+   ```typescript
+   Skill({ skill: "exarchos:delegate", args: "~/.claude/workflow-state/<feature>.state.json" })
+   ```
+
+This is NOT a human checkpoint - workflow continues autonomously.
+
+## Anti-Patterns
+
+| Avoid | Instead |
+|-------|---------|
+| Big-bang refactors | Break into working-state increments |
+| Skipping tests | Each task verifies existing + new |
+| Hidden dependencies | Explicit rollback points |
+| "Will fix later" tasks | Every task self-contained |
+| Assuming tests pass | Verify after each task |

package/skills/generic/refactor/references/phases/overhaul-review.md

@@ -0,0 +1,304 @@
+# Overhaul Track: Review Phase
+
+## Purpose
+
+Quality review with refactor-specific criteria for behavior preservation, regression detection, and goal verification.
+
+## Entry Conditions
+
+- Track is `overhaul`
+- Delegation phase complete
+- All tasks complete
+- Ready for review
+
+## Refactor-Specific Review Emphasis
+
+Refactors require additional scrutiny beyond standard quality review because:
+- Behavior must be preserved exactly (unless intentionally changed)
+- Regressions are easy to introduce and hard to detect
+- Brief goals must be explicitly verified
+
+## Behavior Preservation Checks
+
+### 1. Method Signature Analysis
+
+| Check | Verify | Priority |
+|-------|--------|----------|
+| Parameter types unchanged | Same types or compatible widening | HIGH |
+| Return types unchanged | Same type or compatible narrowing | HIGH |
+| Parameter order preserved | No accidental reordering | HIGH |
+| Optional parameters | Same defaults, same optionality | MEDIUM |
+| Overloads preserved | All overloads still present | HIGH |
+
+**Detection:**
+```bash
+# Compare method signatures before/after
+git diff main...HEAD -- "*.ts" | grep -E "^[+-].*function|^[+-].*class|^[+-].*interface"
+```
+
+### 2. Return Value Equivalence
+
+| Aspect | Check For |
+|--------|-----------|
+| Same values | Identical return for same inputs |
+| Same types | No implicit type changes |
+| Same null behavior | Null/undefined handling unchanged |
+| Same error conditions | Same inputs cause same errors |
+
+**Verification approach:**
+- Review test assertions for return values
+- Check edge case handling
+- Verify null/undefined paths unchanged
+
+### 3. Side Effect Preservation
+
+| Side Effect | Verify Unchanged |
+|-------------|-----------------|
+| State mutations | Same state changes occur |
+| Event emissions | Same events fired in same order |
+| External calls | Same API/DB calls made |
+| Logging | Same log outputs (unless intentional) |
+| File operations | Same I/O patterns |
+
+### 4. Error Handling Consistency
+
+| Check | Verify |
+|-------|--------|
+| Exception types | Same exceptions thrown |
+| Exception conditions | Same inputs trigger errors |
+| Error messages | Equivalent messaging |
+| Catch behavior | Same errors caught/propagated |
+
+## Intentional Changes Documentation
+
+If behavior changes are intentional, they MUST be:
+1. Documented in the brief goals
+2. Covered by updated tests
+3. Explicitly noted in review
+
+**Intentional change checklist:**
+- [ ] Change documented in brief
+- [ ] Old behavior tests updated
+- [ ] New behavior tests added
+- [ ] Breaking change noted (if public API)
+
+## Regression Risk Assessment
+
+Evaluate each area touched by refactor:
+
+| Risk Level | Criteria | Action |
+|------------|----------|--------|
+| **HIGH** | Public API changes, core logic, data handling | Extra scrutiny, explicit test verification |
+| **MEDIUM** | Internal interfaces, shared utilities | Verify dependent code paths |
+| **LOW** | Private methods, isolated modules | Standard review |
+
+### Area-by-Area Assessment
+
+For each file/component changed:
+
+```markdown
+## Regression Risk: <Component>
+
+**Files touched:** `path/to/files`
+**Risk level:** [HIGH | MEDIUM | LOW]
+
+**Changed behavior (intentional):**
+- [List any intentional changes]
+
+**Regression indicators:**
+- [ ] All existing tests pass
+- [ ] No test assertions changed unexpectedly
+- [ ] Dependent components verified
+- [ ] Edge cases still covered
+```
+
+## Performance Considerations
+
+Refactors should not degrade performance:
+
+| Check | Verify |
+|-------|--------|
+| Algorithm complexity | No O(n) to O(n^2) regressions |
+| Memory allocation | No excessive new allocations |
+| Loop iterations | No added unnecessary iterations |
+| Async patterns | No blocking where async expected |
+| Database queries | No N+1 introductions |
+
+**Red flags:**
+- New loops inside existing loops
+- Removed caching/memoization
+- Added synchronous I/O
+- Removed batching
+
+## Goal Verification
+
+Every goal from the brief must be verified as achieved.
+
+### Goal Verification Matrix
+
+| Brief Goal | Evidence | Status |
+|------------|----------|--------|
+| <goal 1> | <test/code reference> | [PASS/FAIL] |
+| <goal 2> | <test/code reference> | [PASS/FAIL] |
+| <goal 3> | <test/code reference> | [PASS/FAIL] |
+
+**Goal verification process:**
+1. Re-read brief goals
+2. Find implementation of each
+3. Verify test coverage for each
+4. Document evidence
+
+## Review Checklist
+
+### Pre-Review
+- [ ] Integration tests pass
+- [ ] All tasks marked complete
+- [ ] Brief goals accessible
+
+### Behavior Preservation
+- [ ] Method signatures analyzed
+- [ ] Return value equivalence checked
+- [ ] Side effects reviewed
+- [ ] Error handling verified
+- [ ] Intentional changes documented
+
+### Regression Assessment
+- [ ] Each component risk-assessed
+- [ ] All existing tests pass (unchanged)
+- [ ] No unexpected test changes
+- [ ] Dependent code paths verified
+
+### Performance
+- [ ] No obvious complexity regressions
+- [ ] No removed optimizations
+- [ ] Memory patterns acceptable
+- [ ] Async patterns preserved
+
+### Goal Achievement
+- [ ] All brief goals mapped to implementation
+- [ ] Each goal has test coverage
+- [ ] No goals left unaddressed
+
+### Quality Standards
+- [ ] Standard quality review criteria (see quality-review/SKILL.md)
+- [ ] SOLID principles maintained or improved
+- [ ] Code readability maintained or improved
+
+## Report Template
+
+```markdown
+## Overhaul Review Report
+
+### Summary
+- Status: [APPROVED | NEEDS_FIXES | BLOCKED]
+- Track: overhaul
+- Brief: <brief-name>
+- Reviewed: [timestamp]
+
+### Behavior Preservation
+| Area | Status | Notes |
+|------|--------|-------|
+| Method signatures | [OK | CHANGED] | |
+| Return values | [OK | CHANGED] | |
+| Side effects | [OK | CHANGED] | |
+| Error handling | [OK | CHANGED] | |
+
+### Intentional Changes
+[List any intentional behavior changes with justification]
+
+### Regression Risk Assessment
+| Component | Risk | Status |
+|-----------|------|--------|
+| <component> | [HIGH | MED | LOW] | [PASS | CONCERN] |
+
+### Goal Verification
+| Brief Goal | Achieved | Evidence |
+|------------|----------|----------|
+| <goal 1> | [YES | NO] | <reference> |
+
+### Findings
+
+#### HIGH Priority (Must Fix)
+1. [Finding title]
+   - File: `path/to/file.ts:42`
+   - Issue: [Description]
+   - Fix: [Required change]
+
+#### MEDIUM Priority (Should Fix)
+1. [Finding title]
+   - Issue: [Description]
+   - Suggestion: [Recommended change]
+
+### Verdict
+[APPROVED] Refactor goals achieved, behavior preserved
+[NEEDS_FIXES] Issues found, return to delegate
+[BLOCKED] Fundamental problem requires brief revision
+```
+
+## State Updates
+
+### On Review Complete
+
+**Record review results:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "reviews.overhaul": {
+    "status": "approved",
+    "behaviorPreserved": true,
+    "goalsVerified": true,
+    "regressionRisk": "low",
+    "timestamp": "<timestamp>"
+  }
+}
+```
+
+### On Approval
+
+**Advance to synthesize:**
+
+```
+action: "set", featureId: "refactor-<slug>", phase: "synthesize"
+```
+
+### On Needs Fixes
+
+**Record issues for fix cycle:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "reviews.overhaul.status": "needs_fixes",
+  "reviews.overhaul.issues": ["<issue1>", "<issue2>"]
+}
+```
+
+## Transition
+
+### If APPROVED:
+1. Update state: `.phase = "synthesize"`
+2. Output: "Overhaul review passed. All goals achieved, behavior preserved. Auto-continuing to synthesis..."
+3. Auto-invoke:
+   ```typescript
+   Skill({ skill: "exarchos:synthesize", args: "<feature-name>" })
+   ```
+
+### If NEEDS_FIXES:
+1. Update state with issues
+2. Output: "Overhaul review found issues. Auto-continuing to fixes..."
+3. Auto-invoke:
+   ```typescript
+   Skill({ skill: "exarchos:delegate", args: "--fixes <plan-path>" })
+   ```
+
+### If BLOCKED:
+1. Update state: `.phase = "blocked"`
+2. Output: "Overhaul review blocked: [issue]. Returning to brief..."
+3. Prompt for brief revision
+
+## Exit Conditions
+
+- [ ] All behavior preservation checks pass
+- [ ] Regression risk assessed and acceptable
+- [ ] All brief goals verified achieved
+- [ ] Standard quality review criteria met
+- [ ] State updated with review results