@lvlup-sw/exarchos 2.5.0 → 2.6.0

package/skills/cursor/refactor/references/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/cursor/refactor/references/polish-track.md

@@ -0,0 +1,152 @@
+---
+name: polish-track
+---
+
+# Polish Track — Detailed Phase Guide
+
+## Purpose
+
+Fast path for small, contained refactors. Single session, minimal ceremony. Orchestrator may write implementation code directly (exception to orchestrator constraints).
+
+## Phases
+
+```
+explore -> brief -> polish-implement -> polish-validate -> polish-update-docs -> completed
+   |         |          |                    |                    |
+   |         |          |                    |                    +-- Update affected documentation
+   |         |          |                    +-- Run tests, verify goals met
+   |         |          +-- Direct implementation (no worktree)
+   |         +-- Capture goals and approach in state
+   +-- Quick scope assessment, confirm polish-appropriate
+```
+
+### 1. Explore Phase
+
+Use `@skills/refactor/references/explore-checklist.md` to assess:
+- Current code structure
+- Files/modules affected (must be <=5 for polish)
+- Test coverage of affected areas
+- Documentation that needs updates
+- Confirm polish is appropriate
+
+**Initialize workflow:**
+```
+action: "init", featureId: "refactor-<slug>", workflowType: "refactor"
+```
+
+**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
+
+Capture refactor intent and approach in state (not separate document).
+
+Use `@skills/refactor/references/brief-template.md` to structure:
+- Problem statement (2-3 sentences)
+- Specific goals (bulleted list)
+- High-level approach
+- Out of scope items
+- Success criteria
+- Docs to update
+
+**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
+
+**Orchestrator may write code directly** (polish track exception).
+
+Constraints:
+- Follow TDD (write/update test first if behavior changes)
+- Commit after each logical change
+- Stop if scope expands beyond brief
+
+When done, commit and push:
+```bash
+git add <files>
+git commit -m "refactor: <description>"
+git push -u origin refactor/<brief-name>
+```
+
+**Advance to validation:**
+
+Call `exarchos_workflow({ action: "describe", playbook: "refactor" })` for the `polish-implement → polish-validate` guard requirements, then `set` the phase.
+
+### 4. Validate Phase
+
+Verify scope hasn't expanded beyond polish limits:
+
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
+  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:
+
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
+  action: "check_static_analysis",
+  featureId: "refactor-<slug>",
+  repoRoot: "<path>"
+})
+```
+
+**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 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
+
+**Mandatory** - documentation must reflect new architecture.
+
+Use `@skills/refactor/references/doc-update-checklist.md` to update:
+- Architecture docs if structure changed
+- API docs if interfaces changed
+- README if setup/usage changed
+- Inline comments if complex logic moved
+
+If `docsToUpdate` is empty, verify no docs need updating.
+
+**Mark docs updated and complete:**
+
+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.
+
+## Auto-Chain
+
+```
+explore -> brief -> polish-implement -> polish-validate -> polish-update-docs -> completed
+           (auto)   (auto)              (auto)             (auto)                (auto)
+```
+
+**Next actions:**
+- `AUTO:brief` after explore
+- `AUTO:polish-implement` after brief
+- `AUTO:polish-validate` after polish-implement
+- `AUTO:polish-update-docs` after polish-validate
+- `AUTO:completed` after polish-update-docs
+
+## Completion Criteria
+
+- [ ] Scope assessment completed (<=5 files)
+- [ ] Brief goals captured
+- [ ] Implementation complete
+- [ ] All tests pass
+- [ ] Each goal verified
+- [ ] Documentation updated
+- [ ] User confirmed completion

package/skills/cursor/shepherd/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: shepherd
+description: "Shepherd PRs through CI and reviews to merge readiness. Operates as an iteration loop within the synthesize phase (not a separate HSM phase). Uses assess_stack to check PR health, fix failures, and request approval. Triggers: 'shepherd', 'tend PRs', 'check CI', or /shepherd."
+metadata:
+  author: exarchos
+  version: 2.0.0
+  mcp-server: exarchos
+  category: workflow
+  phase-affinity: synthesize
+---
+
+# Shepherd Skill
+
+Iterative loop that shepherds published PRs through CI checks and code reviews to merge readiness. Uses the `assess_stack` composite action for all PR health checks, fixing failures and addressing feedback until the stack is green.
+
+> **Note:** Shepherd is not a separate HSM phase. It operates as a loop within the `synthesize` phase. The workflow phase remains `synthesize` throughout the shepherd iteration cycle. Events (`shepherd.iteration`, `ci.status`) and the `shepherd_status` view track loop progress without requiring a phase transition.
+
+**Position in workflow:**
+```text
+synthesize → shepherd (assess → fix → resubmit → loop) → cleanup
+              ^^^^^^^^^ runs within synthesize phase
+```
+
+## Pipeline Hygiene
+
+When `mcp__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:
+- User runs `shepherd` or says "shepherd", "tend PRs", "check CI"
+- PRs are published and need monitoring through the CI/review gauntlet
+- After `synthesize` completes and PRs are enqueued
+
+## Prerequisites
+
+- Active workflow with PRs published (PR URLs in `synthesis.prUrl` or `artifacts.pr`)
+- PRs created and pushed (`gh pr create` already ran)
+- GitHub MCP tools available (preferred) or `gh` CLI authenticated
+
+## 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
+
+At the start of each iteration, query quality hints to inform the assessment:
+```
+mcp__exarchos__exarchos_view({ action: "code_quality", workflowId: "<featureId>" })
+```
+- If `regressions` is non-empty, include regression context in the status report
+- If any hint has `confidenceLevel: 'actionable'`, surface the `suggestedAction` in the iteration summary
+- If `gatePassRate < 0.80` for any skill, flag degrading quality trends
+
+This step ensures the agent acts on accumulated quality intelligence before polling individual PRs.
+
+### Step 1 — Assess
+
+Invoke the `assess_stack` composite action to check all PR dimensions at once:
+```
+mcp__exarchos__exarchos_orchestrate({
+  action: "assess_stack",
+  featureId: "<id>",
+  prNumbers: [123, 124, 125]
+})
+```
+
+The composite action internally handles:
+- CI status checking for all PRs
+- Formal review status (APPROVED / CHANGES_REQUESTED)
+- Inline review comment polling and thread resolution (Sentry, CodeRabbit, humans)
+- Stack health verification
+- Event emission: `gate.executed` events per CI check (feeds CodeQualityView) and `ci.status` events per PR (feeds ShepherdStatusView). See `references/gate-event-emission.md` for the event format.
+
+Review the returned `actionItems` and `recommendation`:
+
+| Recommendation | Action |
+|----------------|--------|
+| `request-approval` | Skip to Step 4 |
+| `fix-and-resubmit` | Proceed to Step 2 |
+| `wait` | Inform user, pause, re-assess after delay |
+| `escalate` | See `references/escalation-criteria.md` |
+
+### Step 2 — Fix
+
+Address each blocking action item from the assessment. Consult `references/fix-strategies.md` for detailed strategies per issue type.
+
+**Remediation event protocol (FLYWHEEL):**
+
+1. **BEFORE applying a fix**, emit `remediation.attempted`:
+   ```typescript
+   mcp__exarchos__exarchos_event({
+     action: "append",
+     stream: "<featureId>",
+     event: {
+       type: "remediation.attempted",
+       data: { taskId: "<taskId>", skill: "shepherd", gateName: "<failing-gate>", attemptNumber: <N>, strategy: "direct-fix" }
+     }
+   })
+   ```
+
+2. Apply the fix (CI failure, review comment response, stack restack).
+
+3. **AFTER the next assess confirms the fix resolved the gate**, emit `remediation.succeeded`:
+   ```
+   mcp__exarchos__exarchos_event({
+     action: "append",
+     stream: "<featureId>",
+     event: {
+       type: "remediation.succeeded",
+       data: { taskId: "<taskId>", skill: "shepherd", gateName: "<gate>", totalAttempts: <N>, finalStrategy: "direct-fix" }
+     }
+   })
+   ```
+
+These events feed `selfCorrectionRate` and `avgRemediationAttempts` metrics in CodeQualityView.
+
+**Action item types:**
+
+| Type | Strategy |
+|------|----------|
+| `ci-fix` | Read logs, reproduce locally, fix, commit to stack branch |
+| `comment-reply` | Read context from `actionItem.context`, compose response, post via GitHub MCP |
+| `review-address` | Fix code for CHANGES_REQUESTED, reply to each thread |
+| `restack` | Run `git rebase origin/<base>`, verify with `gh pr list` |
+| `escalate` | Consult `references/escalation-criteria.md` |
+
+Every inline review comment must get a reply. The goal is that a human scanning the PR sees every thread has a response.
+
+### Step 3 — Resubmit
+
+After fixes are applied, resubmit the stack:
+```bash
+git push --force-with-lease
+# Re-enable auto-merge if needed:
+gh pr merge <number> --auto --squash
+```
+
+Return to Step 1 for the next iteration. Track iteration count against the limit (default 5). If the limit is reached without reaching `request-approval`, escalate per `references/escalation-criteria.md`.
+
+### Step 4 — Request Approval
+
+When `assess_stack` returns `recommendation: 'request-approval'` (all checks green, all comments addressed):
+
+1. Request review via GitHub MCP:
+   ```
+   mcp__plugin_github_github__update_pull_request({
+     owner: "<owner>", repo: "<repo>", pullNumber: <number>,
+     reviewers: ["<approver>"]
+   })
+   ```
+   Fallback (if MCP token lacks write scope): `gh pr edit <number> --add-reviewer <approver>`
+
+2. Report to user:
+   ```markdown
+   ## Ready for Approval
+
+   All CI checks pass. All review comments addressed.
+   Approval requested from: <approvers>
+
+   PRs:
+   - #123: <url>
+   - #124: <url>
+
+   Run `cleanup` after merge completes.
+   ```
+
+## State Management
+
+Track shepherd progress via workflow state:
+
+**Initialize:**
+```
+mcp__exarchos__exarchos_workflow({
+  action: "set",
+  featureId: "<id>",
+  updates: {
+    "shepherd": {
+      "startedAt": "<ISO8601>",
+      "currentIteration": 0,
+      "maxIterations": 5,
+      "approvalRequested": false
+    }
+  }
+})
+```
+
+**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
+
+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
+
+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
+
+| Don't | Do Instead |
+|-------|------------|
+| Poll CI/reviews directly | Use `assess_stack` composite action |
+| Force-merge with failing CI | Fix the failures first |
+| Ignore inline comments | Address every thread with a reply |
+| Loop indefinitely | Respect iteration limits, escalate |
+| Skip remediation events | Emit `remediation.attempted` / `remediation.succeeded` for every fix |
+| Push directly to main | All fixes go through stack branches |
+
+## Transition
+
+After approval is granted and PRs merge, run `cleanup` to resolve the workflow to completed state.