@lvlup-sw/exarchos 2.4.3 → 2.6.0

package/skills/cursor/synthesis/references/github-native-stacking.md

@@ -0,0 +1,135 @@
+---
+name: github-native-stacking
+---
+
+# GitHub-Native PR Stacking
+
+PR stacking creates a chain of dependent pull requests that merge bottom-up into `main`. Each PR targets the previous PR's branch as its base, forming a reviewable sequence of incremental changes.
+
+## 1. PR Chain Creation
+
+Create PRs that chain together by setting each PR's `--base` to the previous branch:
+
+```bash
+# First PR in chain targets main
+gh pr create --base main --head feat/step-1 --title "feat: step 1" --body "..."
+
+# Subsequent PRs target the previous PR's branch
+gh pr create --base feat/step-1 --head feat/step-2 --title "feat: step 2" --body "..."
+gh pr create --base feat/step-2 --head feat/step-3 --title "feat: step 3" --body "..."
+```
+
+The resulting chain looks like:
+
+```text
+main <- feat/step-1 <- feat/step-2 <- feat/step-3
+```
+
+Each PR shows only the diff between its branch and its base, keeping reviews focused.
+
+## 2. Merge Ordering
+
+Stacked PRs must merge **bottom-up** (base-first):
+
+1. Merge PR 1 (`feat/step-1` into `main`)
+2. GitHub auto-retargets PR 2's base from `feat/step-1` to `main`
+3. Merge PR 2 (`feat/step-2` into `main`)
+4. Continue until all PRs are merged
+
+Merging out of order causes conflicts because later branches contain commits from earlier branches that have not yet landed on the target.
+
+## 3. Auto-Retargeting
+
+When a PR's base branch is merged and deleted, GitHub automatically retargets dependent PRs:
+
+- PR 1 merges `feat/step-1` into `main`, branch `feat/step-1` is deleted
+- GitHub detects that PR 2's base (`feat/step-1`) no longer exists
+- GitHub retargets PR 2's base to `main` automatically
+- No manual intervention is needed
+
+This behavior is built into GitHub and requires no configuration. It works as long as the merged branch is deleted (which is the default repository setting for most projects).
+
+## 4. Branch Updates
+
+Keep branches up to date after upstream changes:
+
+```bash
+# Rebase current branch on its updated base (via GitHub API)
+gh pr update-branch --rebase
+
+# Or rebase locally
+git fetch origin && git rebase origin/main
+git push --force-with-lease
+
+# For mid-stack branches, rebase on the base branch
+git fetch origin && git rebase origin/feat/step-1
+git push --force-with-lease
+```
+
+After rebasing a mid-stack branch, all downstream branches in the stack must also be rebased in order.
+
+## 5. Stack Visualization
+
+View the current PR chain and its state:
+
+```bash
+# List all open PRs with base/head branch relationships
+gh pr list --json number,baseRefName,headRefName,title,state \
+  --jq '.[] | "\(.number): \(.baseRefName) <- \(.headRefName) [\(.state)]"'
+
+# Example output:
+# 101: main <- feat/step-1 [OPEN]
+# 102: feat/step-1 <- feat/step-2 [OPEN]
+# 103: feat/step-2 <- feat/step-3 [OPEN]
+```
+
+To validate stack integrity, use the `validate_pr_stack` action via orchestrate:
+
+```typescript
+exarchos_orchestrate({
+  action: "validate_pr_stack",
+  baseBranch: "main"
+})
+```
+
+## 6. Merge Queue
+
+GitHub's native merge queue ensures PRs pass CI before merging:
+
+- **Enable:** Repository Settings > Rules > Branch protection > Require merge queue
+- **Auto-merge:** `gh pr merge --auto --squash` enables auto-merge once checks pass
+- **For stacks:** Enable auto-merge on each PR, then merge bottom-up
+
+```bash
+# Enable auto-merge on all PRs in the stack
+gh pr merge 101 --auto --squash
+gh pr merge 102 --auto --squash
+gh pr merge 103 --auto --squash
+
+# Merge the first PR to start the cascade
+gh pr merge 101 --squash
+```
+
+After PR 101 merges and its branch is deleted, GitHub retargets PR 102 to `main`. If auto-merge is enabled on PR 102, it merges automatically once CI passes.
+
+## 7. Graphite to GitHub-Native Equivalents
+
+| Graphite Command | GitHub-Native Equivalent |
+|---|---|
+| `gt create <branch> -m "feat: ..."` | `git checkout -b <branch> && git commit -m "feat: ..." && git push -u origin <branch>` |
+| `gt submit --no-interactive --publish --stack` | `gh pr create --base <base> --title "..." --body "..."` (per PR) |
+| `gt log` | `gh pr list --json number,baseRefName,headRefName` |
+| `gt modify -m "..."` | `git commit --amend -m "..." && git push --force-with-lease` |
+| `gt sync` | `git fetch --prune && git rebase origin/main` |
+| `gt restack` | `git rebase origin/<base-branch>` per branch in stack |
+| `mcp__graphite__run_gt_cmd` | `gh` CLI directly via Bash tool |
+
+## 8. Error Handling
+
+| Scenario | Resolution |
+|---|---|
+| **Auto-retargeting fails** | Manually retarget: `gh pr edit <number> --base <new-base>` |
+| **Merge conflicts** | Rebase on updated base: `git fetch origin && git rebase origin/<base>`, resolve conflicts, then `git push --force-with-lease` |
+| **Out-of-order merge** | Bottom-up ordering is critical. If PR 2 merges before PR 1, PR 1 now has conflicts against `main`. Manually retarget and resolve. |
+| **CI failure mid-stack** | Fix the failing branch, push the fix. Downstream PRs remain queued until the fix lands. |
+| **Stale branch** | Update with `gh pr update-branch --rebase` or local rebase + force-push. |

package/skills/cursor/synthesis/references/merge-ordering.md

@@ -0,0 +1,50 @@
+# Merge Ordering Strategy
+
+## Overview
+
+GitHub-native stacked PRs merge bottom-up: the base branch merges first, then each dependent branch in sequence. This ordering is enforced by creating PRs with correct base branches and enabling auto-merge (`gh pr merge --auto --squash`).
+
+## Stack Ordering Rules
+
+1. **Foundation branches merge first** -- Types, interfaces, and shared utilities form the stack base
+2. **Implementation branches follow** -- Feature code depends on foundation types
+3. **Test-only branches merge last** -- Integration tests depend on all implementation branches
+
+## Merge Ordering in Practice
+
+The merge order is determined by the branch stack structure established during delegation. The PR list shows the exact merge order (bottom-up):
+
+```text
+main
+ ├── task/001-types         ← merges first
+ ├── task/002-core          ← merges second
+ └── task/003-integration   ← merges last
+```
+
+## State Tracking
+
+Record the merge order in workflow state after PR submission:
+```typescript
+action: "set", featureId: "<id>", updates: {
+  "synthesis": {
+    "mergeOrder": ["task/001-types", "task/002-core", "task/003-integration"],
+    "prUrl": ["<url1>", "<url2>", "<url3>"]
+  }
+}
+```
+
+## Handling Merge Failures
+
+If a branch fails CI in the merge queue:
+1. The entire stack pauses until the failure is resolved
+2. Fix the failing branch, push the fix
+3. After the fix merges, retarget dependent PRs: `gh pr edit <number> --base <new-base>`
+
+## Common Issues
+
+| Issue | Resolution |
+|-------|------------|
+| Middle branch fails CI | Fix and push; retarget dependent PRs with `gh pr edit` |
+| Branch needs rebase | Run `git rebase origin/<base>` for each branch in order |
+| Merge conflict on trunk | Rebase stack onto latest trunk with `git rebase origin/main` |
+| Wrong merge order | Retarget PRs with `gh pr edit <number> --base <correct-base>` |

package/skills/cursor/synthesis/references/pr-descriptions.md

@@ -0,0 +1,87 @@
+# PR Description Guidelines
+
+Write PR descriptions that help reviewers understand the change quickly. Aim for ~120-200 words. CodeRabbit adds detailed analysis—focus on motivation and high-level changes.
+
+## Title Format
+
+`<type>: <what>` (max 72 chars)
+
+Examples:
+- `feat: Add knowledge ingestion workflow`
+- `fix: Resolve null state in workflow steps`
+- `refactor: Simplify token ledger interface`
+
+## Body Structure
+
+### Summary (required)
+2-3 sentences explaining what changed and why it matters. Include the motivation—what problem does this solve?
+
+### Changes (required)
+Scannable list of key changes. Use `**Bold**` for component names and `—` (em-dash) as separator.
+
+### Test Plan (required)
+Brief description of testing approach. What was tested and how?
+
+### Footer (required)
+Separated by `---`. Contains results, design doc, and related PRs.
+
+## Template
+
+```markdown
+## Summary
+
+[2-3 sentences: What changed, why it matters, what problem it solves]
+
+## Changes
+
+- **Component 1** — Brief description of what changed
+- **Component 2** — Brief description of what changed
+- **Component 3** — Brief description of what changed
+
+## Test Plan
+
+[1-2 sentences: Testing approach and coverage summary]
+
+---
+
+**Results:** Tests X ✓ · Build 0 errors
+**Design:** [design-doc.md](docs/path/design-doc.md)
+**Related:** #123, Continues #456
+```
+
+## Example
+
+```markdown
+## Summary
+
+Completes the Knowledge System foundation for RAG-based agent workflows. The platform needs to ingest documents, extract semantic concepts, and build a linked knowledge graph—this PR delivers that infrastructure.
+
+## Changes
+
+- **LLM Inference** — vLLM client with streaming SSE and LoRA adapter support
+- **Token Accounting** — Multi-dimensional ledger tracking usage across categories
+- **Vector Collections** — Registry with schema versioning for embedding spaces
+- **Knowledge Models** — Core types for representing extracted knowledge
+- **Ingestion Workflow** — 11-step pipeline from parsing to knowledge graph commit
+
+## Test Plan
+
+Added ~180 unit tests covering all new components. Integration tests verify the complete workflow with mocked dependencies.
+
+---
+
+**Results:** Tests 3462 ✓ · Build 0 errors
+**Design:** [shared-infrastructure.md](docs/adrs/workflow-designs/shared-infrastructure.md)
+**Related:** Continues #5
+```
+
+## Anti-Patterns
+
+Avoid these—they bloat descriptions without adding value:
+
+- Bullet lists of every file changed
+- Repeating commit messages in the body
+- Low-level implementation details (class names, method signatures)
+- "Generated with..." footers
+- Phase-by-phase breakdowns
+- Detailed test counts by project

package/skills/cursor/synthesis/references/synthesis-steps.md

@@ -0,0 +1,145 @@
+---
+name: synthesis-steps
+---
+
+# Synthesis Process
+
+## Step 1: Verify Readiness
+
+Call the `prepare_synthesis` composite action to validate all preconditions in a single operation:
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
+  action: "prepare_synthesis",
+  featureId: "<featureId>"
+})
+```
+
+The composite action validates all readiness conditions:
+- All delegated tasks complete (from state file)
+- All reviews passed (from state file)
+- No outstanding fix requests (from state file)
+- Task branches exist and are pushed to remote
+- All tests pass (`npm run test:run && npm run typecheck`)
+- Stack integrity verified
+
+**On `passed: true`:** All checks passed -- proceed to Step 2.
+**On `passed: false`:** Output identifies the failing check. Return to `/exarchos:review` or `/exarchos:delegate` as appropriate.
+
+## Step 2: Verify Branch Stack
+
+Run the stack reconstruction script to detect and fix any broken branch state:
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
+  action: "reconstruct_stack",
+  repoRoot: "<repo-root>",
+  stateFile: "~/.claude/workflow-state/<featureId>.state.json"
+})
+```
+
+The script has three phases:
+1. **Detection** -- Checks for diverged branches, missing task branches, or broken parent chains
+2. **Reconstruction** -- If issues detected: resets branch pointers, removes blocking worktrees, rebases with correct parent chain
+3. **Validation** -- Confirms all task branches are present with correct ancestry
+
+**On `passed: true`:** Stack is healthy (or was successfully reconstructed) -- proceed to Step 3.
+**On `passed: false`:** Reconstruction failed validation. Manual intervention required -- inspect branch state and resolve conflicts.
+
+Use `--dry-run` arg to preview reconstruction actions without making changes.
+
+## Step 3: Quick Test Verification
+
+Run tests from the top of the branch stack to confirm everything works:
+```bash
+npm run test:run
+npm run typecheck
+```
+
+If these fail, return to `/exarchos:review` or `/exarchos:delegate` to resolve.
+
+## Step 4: Check CodeRabbit Review State
+
+Get PR numbers from the branch stack, then run the CodeRabbit review check:
+```typescript
+// Check CodeRabbit review state via orchestrate
+mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
+  action: "check_coderabbit",
+  owner: "<owner>",
+  repo: "<repo>",
+  prNumbers: ["<pr-number-1>", "<pr-number-2>"]
+})
+```
+
+The script queries GitHub's PR reviews API for each PR, filters for CodeRabbit reviews, and classifies the latest review state.
+
+**On `passed: true`:** All PRs are APPROVED or have no CodeRabbit review -- proceed to Step 5.
+**On `passed: false`:** At least one PR has CHANGES_REQUESTED or PENDING. The output identifies which PRs need attention. Route to fix cycle:
+```typescript
+Skill({ skill: "exarchos:delegate", args: "--pr-fixes [PR_URL]" })
+```
+After fixes are applied, return to Step 4 to re-check.
+
+## Step 5: Write PR Descriptions
+
+For each PR in the stack, write a structured description following `references/pr-descriptions.md`:
+
+1. **Title:** `<type>: <what>` (max 72 chars)
+2. **Body:** Summary → Changes → Test Plan → Footer
+
+Update each PR body via GitHub MCP or CLI (run this before or after PR creation in Step 6):
+```bash
+gh pr edit <number> --body "$(cat <<'EOF'
+## Summary
+[2-3 sentences]
+
+## Changes
+- **Component** — Description
+
+## Test Plan
+[1-2 sentences]
+
+---
+**Results:** Tests X ✓ · Build 0 errors
+**Design:** [doc](path)
+**Related:** #issue
+EOF
+)"
+```
+
+**Validation:** Run `mcp__plugin_exarchos_exarchos__exarchos_orchestrate({ action: "validate_pr_body", pr: "<number>" })` to verify the body passes.
+CI enforces this via the `PR Body Check` workflow — PRs missing required sections will fail.
+
+**Custom templates:** If the project has a `.exarchos/pr-template.md`, pass it via `--template`:
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
+  action: "validate_pr_body",
+  pr: "<number>",
+  template: ".exarchos/pr-template.md"
+})
+```
+
+## Step 6: Create PRs and Enable Auto-Merge
+
+Create PRs for each branch in the stack (bottom-up) and enable auto-merge:
+
+```bash
+# For each branch in the stack (bottom-up):
+gh pr create --base <parent-branch> --head <branch> --title "<type>: <what>" --body "<pr-body>"
+gh pr merge <number> --auto --squash
+```
+
+After creation, use `gh pr list --json number,url,headRefName` to get the PR URLs for each stack entry.
+
+## Step 7: Cleanup After Merge
+
+After PRs are merged, sync and clean up:
+```bash
+git fetch --prune
+git branch -d <merged-branch-1> <merged-branch-2> ...
+```
+
+Then remove worktrees if they exist:
+```bash
+# Remove worktrees used during delegation
+git worktree list | grep ".worktrees/" | awk '{print $1}' | xargs -I{} git worktree remove {}
+git worktree prune
+```

package/skills/cursor/synthesis/references/troubleshooting.md

@@ -0,0 +1,115 @@
+# Troubleshooting
+
+## Handling Failures
+
+### Test Failure (Unexpected)
+
+If tests fail during synthesis (they passed in review):
+
+1. Return to review phase to investigate
+2. Re-run `/exarchos:review` to diagnose
+3. Dispatch fixes via `/exarchos:delegate --fixes`
+4. Return to synthesis after review passes
+
+### PR Checks Fail
+
+1. Wait for CI feedback
+2. Create fix task for failures
+3. Push fixes to the stack branches
+4. Re-run synthesis verification
+
+### Merge Queue Rejection
+
+If the merge queue rejects a PR:
+1. Check CI status via `gh pr checks <number>` (or GitHub MCP `pull_request_read` with method `get_status` if available)
+2. Fix failing checks
+3. Push fixes and re-enqueue
+
+## Handling PR Feedback
+
+If the user receives PR review comments:
+
+1. Offer to address feedback:
+   ```typescript
+   Skill({ skill: "exarchos:delegate", args: "--pr-fixes [PR_URL]" })
+   ```
+
+2. Delegate reads PR comments via gh CLI:
+   ```bash
+   gh pr view <number> --json reviews,comments
+   ```
+   > Or use GitHub MCP `pull_request_read` if available.
+
+3. Creates fix tasks from review comments
+4. After fixes, amend the commit with `git commit --amend -m "fix: <description>"` and push with `git push --force-with-lease`
+5. Return to merge confirmation
+
+## Final Report Template
+
+```markdown
+## Synthesis Complete
+
+### Pull Requests
+[PR URLs from gh pr list]
+
+### Stack Branches
+- task/001-types
+- task/002-api
+- task/003-tests
+
+### Test Results
+- Unit tests: PASS
+- Type check: PASS
+- Lint: PASS
+- Build: PASS
+
+### Next Steps
+1. Wait for CI/CD checks
+2. Request code review (if required)
+3. Merge when approved
+4. Worktrees will be cleaned up after merge
+
+### Documentation
+- Design: docs/designs/YYYY-MM-DD-feature.md
+- Plan: docs/plans/YYYY-MM-DD-feature.md
+```
+
+## MCP Tool Call Failed
+If an Exarchos MCP tool returns an error:
+1. Check the error message -- it usually contains specific guidance
+2. Verify the workflow state exists: call `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "get"` and the featureId
+3. If "version mismatch": another process updated state -- retry the operation
+4. If state is corrupted: call `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "cancel"` and `dryRun: true`
+
+## State Desync
+If workflow state doesn't match git reality:
+1. The SessionStart hook runs reconciliation automatically on resume
+2. If manual check needed: compare state file with `git log` and branch state
+3. Update state via `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"` to match git truth
+
+## PR Creation Failed
+If `gh pr create` fails:
+1. Check the error output for specific guidance
+2. Run `gh pr list --json number,baseRefName,headRefName` to verify the branch state
+3. If rebase conflict: run `git rebase origin/<base>` to resolve
+4. If authentication issue: check GitHub token permissions
+
+## Stack Rebase Conflict
+If `git rebase` encounters conflicts:
+1. Resolve conflicts manually in each affected file
+2. Run `git add <resolved-files>` then `git rebase --continue`
+3. After resolution, push with `git push --force-with-lease`
+
+## Exarchos Integration
+
+When Exarchos MCP tools are available:
+
+1. **After stack submission:** Call `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` with event type `stack.enqueued` including PR numbers from `gh pr list --json number`
+2. **Monitor merge status:** Use `gh pr list --json number,state,mergedAt` to check stack/PR status
+3. **On successful merge:** Call `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` with event type `phase.transitioned` to mark workflow complete
+
+## Performance Notes
+
+- Complete each step fully before advancing -- quality over speed
+- Do not skip validation checks even when the change appears trivial
+- Verify all tests pass before creating PR. Do not skip the pre-submit validation step.