@lvlup-sw/exarchos 2.0.1

package/skills/refactor/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

package/skills/refactor/phases/polish-implement.md

@@ -0,0 +1,349 @@
+# Polish Track: Implement Phase
+
+## Purpose
+
+Direct implementation for small, well-scoped refactors. This phase allows the orchestrator to write code directly without delegation to subagents, reducing ceremony while maintaining quality.
+
+## Orchestrator Exception
+
+**This is the explicit exception to orchestrator constraints.**
+
+The orchestrator constraints in `rules/orchestrator-constraints.md` state the orchestrator MUST NOT write implementation code. The polish track implement phase is the one case where this rule is intentionally violated.
+
+### Why This Exception Exists
+
+| Standard Workflow | Polish Track |
+|-------------------|--------------|
+| Delegation overhead justified | Overhead exceeds value for small changes |
+| Context window preserved for coordination | Small changes fit within session |
+| Parallel execution via worktrees | Sequential execution sufficient |
+| Subagent isolation for testing | Direct testing in main branch |
+
+### When the Exception Applies
+
+The orchestrator may write code directly ONLY when ALL conditions are met:
+
+1. **Track is polish** - State file shows `.track = "polish"`
+2. **Brief is captured** - Phase has advanced to "implement"
+3. **Scope is limited** - 5 or fewer files affected
+4. **Single concern** - One refactoring goal per session
+5. **Tests exist** - Affected code has test coverage
+
+If any condition is violated, switch to overhaul track.
+
+## Entry Conditions
+
+Before starting implementation, verify prerequisites:
+
+**Check track:**
+```
+action: "get", featureId: "refactor-<slug>", query: ".track"
+```
+Must return: `"polish"`
+
+**Check phase:**
+```
+action: "get", featureId: "refactor-<slug>", query: ".phase"
+```
+Must return: `"implement"`
+
+**Check goals:**
+```
+action: "get", featureId: "refactor-<slug>", query: ".brief.goals"
+```
+Must return: populated array
+
+### State Requirements
+
+| Field | Requirement |
+|-------|-------------|
+| `.track` | "polish" |
+| `.phase` | "implement" |
+| `.brief.problem` | Non-empty string |
+| `.brief.goals` | 1-3 items |
+| `.brief.affectedAreas` | 1-5 files |
+| `.brief.successCriteria` | 2-3 items |
+| `.explore.scopeAssessment.testCoverage` | "good" or "gaps" (not "none") |
+
+## Implementation Process
+
+### Step 1: Pre-Implementation Verification
+
+Run the full test suite before making any changes:
+
+```bash
+npm run test:run
+```
+
+**Gate:** Tests must pass. If tests fail before implementation, stop and investigate. Do not implement on top of a failing test suite.
+
+**Record baseline:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "implement": {
+    "startedAt": "<ISO8601>",
+    "baselineTestsPass": true,
+    "changesLog": []
+  }
+}
+```
+
+### Step 2: Make Changes Incrementally
+
+For each logical change:
+
+1. **Understand the change** - Read affected code
+2. **Update tests first** (if behavior changes) - TDD: red then green
+3. **Make the change** - Minimal modification
+4. **Run tests** - Verify no regression
+5. **Commit** - Atomic commit for the change
+
+```bash
+# After each change
+npm run test:run
+
+# Commit via Graphite
+git add <files>
+gt create refactor/<brief-name> -m "refactor: <description>"
+```
+
+After all changes are complete:
+```bash
+gt submit --no-interactive --publish --stack
+```
+
+**NEVER use `git commit` or `git push`** — always use `gt create` and `gt submit`.
+
+**Log change:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "implement.changesLog": [{"file": "<path>", "description": "<what changed>"}]
+}
+```
+
+### Step 3: Test After Each Change
+
+**Critical:** Run tests after EVERY change, not just at the end.
+
+| Test Failure | Action |
+|--------------|--------|
+| Test fails after change | Revert and retry with smaller change |
+| Unrelated test fails | Stop, investigate, may need track switch |
+| Lint/type error | Fix before proceeding |
+
+### Step 4: Verify Goals
+
+After all changes, verify each goal from brief:
+
+```
+action: "get", featureId: "refactor-<slug>", query: ".brief.goals"
+```
+
+For each goal, confirm it's addressed. If a goal cannot be addressed within polish scope, trigger track switch.
+
+## Scope Monitoring
+
+### Red Flags During Implementation
+
+Watch for these indicators that polish is insufficient:
+
+| Signal | Description | Threshold |
+|--------|-------------|-----------|
+| File count growing | Started with 3 files, now touching 6+ | >5 files |
+| Test gaps discovered | Affected code lacks tests | Need >2 new test files |
+| Cascading changes | Change in one file requires changes in many | >3 unexpected files |
+| Architecture concerns | Structure questions beyond scope | Needs design document |
+| Duration | Implementation taking too long | >1 hour of changes |
+
+### Monitoring Commands
+
+```bash
+# Check files changed
+git diff --name-only HEAD~N  # where N = commits since implement started
+
+# Count affected files
+git diff --stat
+```
+
+### When to Stop
+
+**Stop implementation immediately if:**
+
+- More than 5 files need modification
+- You discover test coverage is "none" (not "gaps")
+- Multiple unrelated concerns emerge
+- You're writing more than 100 lines of new code
+- Changes require updates to public APIs
+
+## Track Switching
+
+### Detection
+
+If scope expands beyond polish limits during implementation:
+
+```bash
+echo "Scope has expanded beyond polish limits."
+echo "Files affected: $(git diff --name-only | wc -l)"
+echo "Switching to overhaul track recommended."
+```
+
+### Switch Protocol
+
+1. **Commit current work** - Don't lose progress
+2. **Record switch and change track:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "implement.switchReason": "<reason for switch>",
+  "implement.switchedAt": "<ISO8601>",
+  "track": "overhaul"
+}, phase: "overhaul-plan"
+```
+
+3. **Create worktree** (if not already in one)
+4. **Invoke `/exarchos:plan`** - Extract remaining work into tasks
+5. **Continue via overhaul track**
+
+### Output to User
+
+```text
+Scope has expanded beyond polish limits.
+Reason: [specific reason]
+
+Switching to overhaul track. This means:
+- Work will continue in an isolated worktree
+- Remaining changes will be delegated to subagents
+- Full review process will be applied
+
+Current progress has been committed. Continue? (Y/n)
+```
+
+## State Updates
+
+### Implementation Start
+
+**Record baseline:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "implement": {
+    "startedAt": "<ISO8601>",
+    "baselineTestsPass": true,
+    "changesLog": []
+  }
+}
+```
+
+### After Each Change
+
+**Log change:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "implement.changesLog": [
+    {"file": "<path>", "description": "<what changed>", "commitSha": "<short-sha>"}
+  ]
+}
+```
+
+Note: For array appends, the MCP tool handles merging with existing array entries.
+
+### Implementation Complete
+
+**Record completion and advance to validate:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "implement.completedAt": "<ISO8601>",
+  "implement.totalFiles": <count>,
+  "implement.totalCommits": <count>
+}, phase: "polish-validate"
+```
+
+### Track Switch (if needed)
+
+**Record switch and change track:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "implement.switchReason": "<reason>",
+  "implement.switchedAt": "<ISO8601>",
+  "track": "overhaul"
+}, phase: "overhaul-plan"
+```
+
+## Exit Conditions
+
+Implementation phase exits when:
+
+### Success Exit -> Validate Phase
+
+- All changes from brief are implemented
+- All tests pass
+- No scope expansion occurred
+- Less than or equal to 5 files changed
+
+**Advance to validate:**
+
+```
+action: "set", featureId: "refactor-<slug>", phase: "polish-validate"
+```
+
+Next action: `AUTO:refactor-validate`
+
+### Track Switch Exit -> Plan Phase
+
+- Scope expanded beyond polish limits
+- Track switched to overhaul
+- Current work committed
+
+**Switch to overhaul track:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "track": "overhaul"
+}, phase: "overhaul-plan"
+```
+
+Next action: `AUTO:overhaul-plan`
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Make all changes then test | Test after each change |
+| Skip commits for "small" changes | Commit each logical change |
+| Ignore expanding scope | Stop and switch tracks |
+| Fix unrelated issues found | Note for separate refactor |
+| Skip baseline test run | Always verify green baseline |
+| Force polish when overhaul needed | Accept track switch gracefully |
+
+## Example Implementation Session
+
+```text
+[Phase: implement]
+
+1. Running baseline tests...
+   Tests: 42 passed
+
+2. Change 1: Extract validation to UserValidator
+   - Created: src/validators/user-validator.ts
+   - Modified: src/services/user-service.ts
+   - Tests: 42 passed
+   - Committed: abc123
+
+3. Change 2: Update UserService imports
+   - Modified: src/services/user-service.ts
+   - Tests: 42 passed
+   - Committed: def456
+
+4. Verifying goals:
+   [x] Extract validation logic into separate UserValidator class
+   [x] Reduce UserService line count
+
+5. Files changed: 2 (within limit)
+
+6. Transitioning to validate phase...
+```