@lvlup-sw/exarchos 2.0.1

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

@@ -0,0 +1,218 @@
+# Polish Track Validate Phase
+
+## Purpose
+
+Verify the refactor succeeded without regressions. This phase confirms all goals from the brief are achieved, tests pass, and no unintended changes were introduced.
+
+## Entry Conditions
+
+- Polish implement phase complete
+- Phase is `validate`
+- Implementation commits are ready
+
+## Validation Checklist
+
+### 1. Test Suite Verification
+
+Run the full test suite to ensure no regressions:
+
+```bash
+npm run test:run
+```
+
+**Requirements:**
+- [ ] All existing tests pass
+- [ ] No new test failures introduced
+- [ ] Test count has not decreased (no deleted tests)
+
+If tests fail:
+1. Identify which tests fail
+2. Determine if failure is due to refactor or pre-existing issue
+3. Fix refactor-related failures before proceeding
+4. Return to implement phase if significant fixes needed
+
+### 2. Goal Achievement
+
+Review each goal from the brief and verify completion:
+
+**Read goals:**
+
+```
+action: "get", featureId: "refactor-<slug>", query: ".brief.goals"
+```
+
+**For each goal:**
+- [ ] Goal is fully addressed
+- [ ] Evidence of completion is clear (code change, metric improvement, etc.)
+- [ ] Goal was not partially implemented
+
+**Record verified goals:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "validation.goalsVerified": ["<goal text>"]
+}
+```
+
+Note: For array values, subsequent calls can append additional goals.
+
+### 3. Regression Check
+
+Verify no unintended changes outside refactor scope:
+
+**Review affected areas:**
+- [ ] Changes are limited to `affectedAreas` from brief
+- [ ] No unexpected files modified
+- [ ] No unrelated behavior changes
+
+**Check git diff:**
+```bash
+git diff --stat HEAD~<n>  # Review files changed
+git diff HEAD~<n> -- <unexpected-file>  # Investigate unexpected changes
+```
+
+If unintended changes found:
+1. Determine if they should be reverted
+2. If intentional, update brief's `affectedAreas`
+3. If accidental, revert and re-run validation
+
+### 4. Lint and Type Check
+
+Run linting and type checking to ensure code quality:
+
+```bash
+npm run lint
+npm run typecheck  # For TypeScript projects
+```
+
+**Requirements:**
+- [ ] No new lint errors introduced
+- [ ] No new type errors introduced
+- [ ] Any disabled rules are justified
+
+If errors found:
+1. Fix lint/type errors
+2. Commit fixes separately
+3. Re-run validation
+
+### 5. Code Quality Spot Check
+
+Manual review of key changes:
+
+**Structure verification:**
+- [ ] New code follows project conventions
+- [ ] Naming is consistent and clear
+- [ ] No obvious code smells introduced
+
+**Brief alignment:**
+- [ ] Implementation matches stated approach
+- [ ] Out-of-scope items were not touched
+- [ ] Success criteria are met
+
+## State Updates
+
+### Record Validation Start
+
+**Initialize validation state:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "validation": {
+    "startedAt": "<ISO8601>",
+    "testsPass": null,
+    "goalsVerified": [],
+    "docsUpdated": false
+  }
+}
+```
+
+### Record Validation Results
+
+**On successful validation:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "validation.testsPass": true,
+  "validation.completedAt": "<ISO8601>"
+}, phase: "polish-update-docs"
+```
+
+**On failed validation:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "validation.testsPass": false,
+  "validation.failureReason": "<reason>"
+}, phase: "implement"
+```
+
+## Pass/Fail Handling
+
+### Validation Passed
+
+All criteria met:
+1. Update state with successful validation results
+2. Transition to `update-docs` phase
+3. Auto-chain continues workflow
+
+### Validation Failed
+
+If any criteria not met:
+
+| Failure Type | Action |
+|--------------|--------|
+| Tests fail | Return to implement phase, fix issues |
+| Goals not achieved | Return to implement phase, complete goals |
+| Unintended changes | Revert changes, return to implement |
+| Lint/type errors | Fix errors, re-run validation |
+| Quality issues | Return to implement phase, address issues |
+
+**Important:** Do not skip to update-docs with validation failures. All issues must be resolved first.
+
+## Exit Conditions
+
+Transition to `update-docs` phase when ALL conditions are met:
+
+- [ ] All tests pass
+- [ ] Each goal from brief is verified as complete
+- [ ] No unintended changes outside scope
+- [ ] No new lint or type errors
+- [ ] Code quality spot check passed
+- [ ] State updated with validation results
+
+## Auto-Chain Behavior
+
+On successful validation:
+- Next action: `AUTO:refactor-update-docs`
+- Automatically proceeds to update documentation
+
+On failed validation:
+- Next action: `AUTO:polish-implement` (return to fix issues)
+- Does not proceed until validation passes
+
+## Common Issues
+
+| Issue | Resolution |
+|-------|------------|
+| Flaky tests | Run tests multiple times, investigate intermittent failures |
+| Pre-existing failures | Document in state, don't block on unrelated issues |
+| Scope creep discovered | Either revert extra changes or update brief (prefer revert) |
+| Missing test coverage | Add tests for changed behavior before proceeding |
+
+## Validation Output
+
+Summarize validation results for the user:
+
+```text
+Validation Results:
+- Tests: All 47 tests pass
+- Goals: 3/3 verified
+  - Extract validation logic into separate UserValidator class
+  - Reduce UserService to <200 lines
+  - Improve test isolation for validation tests
+- Regressions: None detected
+- Lint/Type: No new errors
+- Quality: Spot check passed
+
+Proceeding to update-docs phase...
+```

package/skills/refactor/phases/update-docs.md

@@ -0,0 +1,234 @@
+# Update Docs Phase
+
+## Purpose
+
+Ensure all documentation remains accurate after refactoring. This phase updates affected documentation to reflect the new code structure, APIs, and architecture.
+
+## MANDATORY REQUIREMENT
+
+**Documentation updates are NOT optional for refactors.**
+
+Every refactor changes existing code structure. If documentation exists for that code, it MUST be updated. Skipping this phase results in documentation drift, which compounds over time and misleads future developers.
+
+The `docsToUpdate` field in the brief identifies documents requiring updates. If this field is empty, the phase still runs to VERIFY no documentation needs updating.
+
+## Entry Conditions
+
+### Polish Track
+
+- `validate` phase complete
+- All tests passing
+- Goals verified
+
+### Overhaul Track
+
+- `review` phase complete
+- All quality checks passed
+- Code merged to feature branch
+
+## Process
+
+### Step 1: Review Documentation List
+
+**Read docs list:**
+
+```
+action: "get", featureId: "refactor-<slug>", query: ".brief.docsToUpdate"
+```
+
+If the list is empty, proceed to Step 4 (Verification).
+
+### Step 2: Read Each Document
+
+For each document in the list:
+
+1. Read the current content
+2. Identify sections affected by the refactor
+3. Note what needs to change
+
+```typescript
+Read({ file_path: "/path/to/affected-doc.md" })
+```
+
+### Step 3: Update Affected Sections
+
+Update each document to reflect the new code structure:
+
+| Change Type | Documentation Update |
+|-------------|---------------------|
+| Renamed file/class | Update all references |
+| Moved location | Update paths and imports |
+| Changed API | Update signatures and examples |
+| New architecture | Add/update diagrams |
+| Removed code | Remove obsolete references |
+
+**Update Guidelines:**
+
+- Keep updates minimal and focused
+- Match the existing document style
+- Update code examples if affected
+- Verify links still work
+
+### Step 4: Verification
+
+Verify documentation accuracy against the new code:
+
+| Check | How to Verify |
+|-------|---------------|
+| File paths | Confirm paths in docs exist |
+| Code examples | Examples compile/run correctly |
+| API signatures | Match actual implementation |
+| Diagrams | Reflect current architecture |
+| Links | All internal links resolve |
+
+If `docsToUpdate` was empty, verify:
+- Search for references to changed code
+- Confirm no documentation references outdated patterns
+- If documentation gaps found, update immediately
+
+## Documentation Types
+
+### Architecture Documentation
+
+Update when:
+- Module structure changes
+- Dependencies change
+- Component relationships change
+
+Typical locations:
+- `docs/architecture/*.md`
+- `docs/adrs/*.md`
+- `README.md` architecture sections
+
+### API Documentation
+
+Update when:
+- Function signatures change
+- Types/interfaces change
+- Endpoints change
+
+Typical locations:
+- Inline JSDoc/TSDoc comments
+- `docs/api/*.md`
+- OpenAPI/Swagger specs
+
+### README Files
+
+Update when:
+- Setup process changes
+- Usage patterns change
+- Dependencies change
+
+Typical locations:
+- Project root `README.md`
+- Module-level `README.md` files
+
+### Inline Comments
+
+Update when:
+- Complex logic moves
+- Algorithms change
+- Important context relocates
+
+**Note:** Avoid over-commenting. Only update comments that explain WHY, not WHAT.
+
+## State Updates
+
+**Record docs and advance (polish track):**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "artifacts.updatedDocs": ["docs/architecture/modules.md"],
+  "validation.docsUpdated": true
+}, phase: "completed"
+```
+
+**Record docs and advance (overhaul track):**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "artifacts.updatedDocs": ["docs/architecture/modules.md"],
+  "validation.docsUpdated": true
+}, phase: "synthesize"
+```
+
+## Exit Conditions
+
+### Polish Track
+
+After completing documentation updates:
+
+1. All listed documents updated
+2. Verification complete
+3. State updated with `docsUpdated = true`
+4. **CHECKPOINT: Human approval required**
+
+Present summary to user:
+```text
+Documentation Update Complete
+-----------------------------
+Updated docs:
+- docs/architecture/modules.md (updated paths)
+- README.md (updated examples)
+
+Verification: All links and examples verified
+
+Ready to complete refactor? [Approve / Request changes]
+```
+
+### Overhaul Track
+
+After completing documentation updates:
+
+1. All listed documents updated
+2. Verification complete
+3. State updated with `docsUpdated = true`
+4. **Auto-chain to synthesize phase**
+
+**Advance to synthesize:**
+
+```
+action: "set", featureId: "refactor-<slug>", phase: "synthesize"
+```
+
+5. Auto-invoke synthesize immediately:
+```typescript
+Skill({ skill: "exarchos:synthesize", args: "<feature-name>" })
+```
+
+This is NOT a human checkpoint - workflow continues autonomously.
+
+## Common Issues
+
+### No Documentation Exists
+
+If refactored code has no documentation:
+- This is acceptable for refactors
+- Creating new documentation is a separate task
+- Note the gap in the state for future reference
+
+### Documentation Scope Creep
+
+If updating one document reveals many need updates:
+- Update only what's necessary for this refactor
+- Note other gaps for future work
+- Stay focused on the brief's scope
+
+### Conflicting Documentation
+
+If documentation conflicts with new code:
+- Trust the code (you just validated it)
+- Update documentation to match
+- Add clarifying notes if needed
+
+## Checklist
+
+Before exiting this phase:
+
+- [ ] Reviewed all documents in `docsToUpdate`
+- [ ] Updated affected sections in each document
+- [ ] Verified file paths and links
+- [ ] Verified code examples work
+- [ ] Updated state with `artifacts.updatedDocs` list
+- [ ] Set `docsUpdated = true`
+- [ ] Transitioned to next phase (completed or synthesize)

package/skills/refactor/references/brief-template.md

@@ -0,0 +1,81 @@
+# Refactor Brief Template
+
+## Purpose
+
+The brief captures refactor intent without the overhead of a full design document. Store in workflow state, not as a separate file.
+
+## Brief Fields
+
+### Problem (Required)
+What's wrong with the current code? Be specific.
+
+**Polish example:** "The UserService class has grown to 500 lines with mixed responsibilities"
+
+**Overhaul example:** "The authentication module uses callbacks throughout, making error handling inconsistent and testing difficult"
+
+### Goals (Required)
+List specific, measurable goals. Each goal should be verifiable.
+
+**Good goals:**
+- Extract validation logic into separate UserValidator class
+- Convert callback-based auth to async/await pattern
+- Reduce cyclomatic complexity of processOrder from 15 to <5
+
+**Bad goals:**
+- Make the code better
+- Clean things up
+- Improve performance (without metrics)
+
+### Approach (Required)
+High-level description of how you'll achieve the goals.
+
+**Polish approach:** "Extract validation methods to new class, update callers, run tests"
+
+**Overhaul approach:** "Phase 1: Create async wrapper around existing callbacks. Phase 2: Convert internal methods to async. Phase 3: Update public API. Phase 4: Remove callback support."
+
+### Affected Areas (Required)
+List specific paths/modules that will change.
+
+### Out of Scope (Required)
+Explicitly state what you're NOT changing. Prevents scope creep.
+
+### Success Criteria (Required)
+How will you know the refactor is complete?
+
+- All existing tests pass
+- [Specific goal] is achieved
+- [Metric] is improved by [amount]
+- Documentation reflects new structure
+
+### Docs to Update (Required)
+List documentation files that need updating after refactor.
+
+## State Update
+
+**Save brief and advance:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "brief": {
+    "problem": "<problem statement>",
+    "goals": ["<goal 1>", "<goal 2>"],
+    "approach": "<approach description>",
+    "affectedAreas": ["<area 1>", "<area 2>"],
+    "outOfScope": ["<exclusion 1>", "<exclusion 2>"],
+    "successCriteria": ["<criterion 1>", "<criterion 2>"],
+    "docsToUpdate": ["<doc 1>", "<doc 2>"]
+  }
+}, phase: "polish-implement | overhaul-plan"
+```
+
+## Polish vs Overhaul Brief Depth
+
+| Field | Polish | Overhaul |
+|-------|--------|----------|
+| Problem | 1-2 sentences | Paragraph with context |
+| Goals | 1-3 items | 3-5 items |
+| Approach | 1 sentence | Paragraph with phases |
+| Affected Areas | File paths | Module/package paths |
+| Out of Scope | 1-2 items | 3+ items |
+| Success Criteria | 2-3 items | 4+ items |
+| Docs to Update | 0-2 files | 2+ files |

package/skills/refactor/references/doc-update-checklist.md

@@ -0,0 +1,110 @@
+# Documentation Update Checklist
+
+## Purpose
+
+Every refactor MUST update affected documentation. This is not optional. Code without accurate documentation creates technical debt.
+
+## Before Starting
+
+1. Review `docsToUpdate` list from brief
+2. Read each document to understand current state
+3. Note specific sections that need changes
+
+## Documentation Types
+
+### Architecture Documentation
+
+**When to update:** Structure, module organization, or dependencies changed
+
+**What to check:**
+- [ ] Component diagrams accurate
+- [ ] Module descriptions current
+- [ ] Dependency arrows correct
+- [ ] Technology choices documented
+
+### API Documentation
+
+**When to update:** Public interfaces, method signatures, or behavior changed
+
+**What to check:**
+- [ ] Function/method signatures match code
+- [ ] Parameter descriptions accurate
+- [ ] Return value documentation correct
+- [ ] Examples still work
+- [ ] Error cases documented
+
+### README Files
+
+**When to update:** Setup, usage, or configuration changed
+
+**What to check:**
+- [ ] Installation steps current
+- [ ] Configuration examples valid
+- [ ] Usage examples work
+- [ ] Prerequisites listed
+
+### Inline Comments
+
+**When to update:** Complex logic moved or rewritten
+
+**What to check:**
+- [ ] Comments explain "why" not "what"
+- [ ] No stale comments referring to old code
+- [ ] Complex algorithms documented
+- [ ] TODO items addressed or updated
+
+## Verification
+
+After updating documentation, run automated link verification:
+
+```bash
+bash scripts/verify-doc-links.sh --docs-dir docs/
+```
+
+**On Exit 0:** All links valid.
+**On Exit 1:** Broken links found — fix before proceeding.
+
+Additionally:
+
+1. [ ] Read each updated doc fresh
+2. [ ] Verify code references are accurate
+3. [ ] Test any code examples
+
+## State Update
+
+**Record updated docs:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "validation.docsUpdated": true,
+  "artifacts.updatedDocs": ["<doc1>", "<doc2>"]
+}
+```
+
+## If No Docs Need Updating
+
+If `docsToUpdate` is empty, verify this is correct:
+
+1. Review affected areas
+2. Confirm no public interfaces changed
+3. Confirm no architectural changes made
+4. Document verification in state:
+
+**Confirm no docs needed:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "validation.docsUpdated": true,
+  "artifacts.updatedDocs": []
+}
+```
+
+## Common Mistakes
+
+| Mistake | Correction |
+|---------|------------|
+| "Docs don't need updating" | Always verify; code changes usually need doc updates |
+| Update code examples only | Also update prose descriptions |
+| Skip architecture docs | These are often most important |
+| Leave TODO comments | Address or remove them |
+| Assume readers know context | Document the "why" |

package/skills/refactor/references/explore-checklist.md

@@ -0,0 +1,73 @@
+---
+name: explore-checklist
+---
+
+# Refactor Exploration Checklist
+
+## Scope Assessment
+
+### Files Analysis
+- [ ] List all files that will be modified
+- [ ] Count total files affected
+- [ ] Identify file types (source, test, config, docs)
+
+### Module Analysis
+- [ ] List modules/packages affected
+- [ ] Identify cross-module dependencies
+- [ ] Check for circular dependencies that might complicate refactor
+
+### Test Coverage
+- [ ] Check test coverage of affected code
+- [ ] Identify test gaps
+- [ ] Note tests that will need updating
+
+### Documentation Impact
+- [ ] List documentation that references affected code
+- [ ] Identify architecture docs that may need updates
+- [ ] Check for API documentation impacts
+
+## Track Selection
+
+### Polish Track Indicators (all must be true)
+- [ ] <=5 files affected
+- [ ] Single concern being addressed
+- [ ] No cross-module changes
+- [ ] Good test coverage exists
+- [ ] Documentation changes are minor
+
+### Overhaul Track Indicators (any one triggers)
+- [ ] >5 files affected
+- [ ] Multiple concerns being addressed
+- [ ] Cross-module changes required
+- [ ] Test coverage gaps exist
+- [ ] Architectural documentation needs updating
+
+## Deterministic Scope Assessment
+
+Run the scope assessment script for a deterministic track recommendation:
+
+```bash
+bash scripts/assess-refactor-scope.sh --files <file1,file2,...>
+# or
+bash scripts/assess-refactor-scope.sh --state-file <path>
+```
+
+**On Exit 0:** Polish recommended — scope is contained (<=5 files, single module).
+**On Exit 1:** Overhaul recommended — scope exceeds polish limits (>5 files or cross-module).
+
+## Output
+
+**Save assessment and advance to brief:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "explore.scopeAssessment": {
+    "filesAffected": ["<list>"],
+    "modulesAffected": ["<list>"],
+    "testCoverage": "good | gaps | none",
+    "recommendedTrack": "polish | overhaul"
+  },
+  "track": "<selected-track>",
+  "explore.completedAt": "<ISO8601>"
+}, phase: "brief"
+```