diff --git a/.beads/formulas/mol-polecat-code-review.formula.toml b/.beads/formulas/mol-polecat-code-review.formula.toml new file mode 100644 index 00000000..b4379e16 --- /dev/null +++ b/.beads/formulas/mol-polecat-code-review.formula.toml @@ -0,0 +1,318 @@ +description = """ +Review code and file beads for issues found. + +This molecule guides a polecat through a code review task - examining a portion +of the codebase for bugs, security issues, code quality problems, or improvement +opportunities. The output is a set of beads capturing actionable findings. + +## Polecat Contract (Self-Cleaning Model) + +You are a self-cleaning worker. You: +1. Receive work via your hook (pinned molecule + review scope) +2. Work through molecule steps using `bd ready` / `bd close ` +3. Complete and self-clean via `gt done` (submit findings + nuke yourself) +4. You are GONE - your findings are recorded in beads + +**Self-cleaning:** When you run `gt done`, you submit your findings, nuke your +sandbox, and exit. There is no idle state. Done means gone. + +**Important:** This formula defines the template. Your molecule already has step +beads created from it. Use `bd ready` to find them - do NOT read this file directly. + +**You do NOT:** +- Fix the issues yourself (file beads, let other polecats fix) +- Scope creep into unrelated areas +- Wait for someone to act on findings (you're done after filing) + +## Variables + +| Variable | Source | Description | +|----------|--------|-------------| +| scope | hook_bead | What to review (file path, directory, or description) | +| issue | hook_bead | The tracking issue for this review task | +| focus | hook_bead | Optional focus area (security, performance, etc.) | + +## Failure Modes + +| Situation | Action | +|-----------|--------| +| Scope too broad | Mail Witness, request narrower scope | +| Can't understand code | Mail Witness for context | +| Critical issue found | Mail Witness immediately, then continue |""" +formula = "mol-polecat-code-review" +version = 1 + +[[steps]] +id = "load-context" +title = "Load context and understand the review scope" +description = """ +Initialize your session and understand what you're reviewing. + +**1. Prime your environment:** +```bash +gt prime # Load role context +bd prime # Load beads context +``` + +**2. Check your hook:** +```bash +gt hook # Shows your pinned molecule and hook_bead +``` + +The hook_bead describes your review scope. Read the tracking issue: +```bash +bd show {{issue}} # Full issue details +``` + +**3. Understand the scope:** +- What files/directories are in scope? +- Is there a specific focus (security, performance, correctness)? +- What's the context - why is this review happening? + +**4. Locate the code:** +```bash +# If scope is a path: +ls -la {{scope}} +head -100 {{scope}} # Quick look at the code + +# If scope is a directory: +find {{scope}} -type f -name "*.go" | head -20 +``` + +**5. Check for recent changes:** +```bash +git log --oneline -10 -- {{scope}} +``` + +**Exit criteria:** You understand what you're reviewing and why.""" + +[[steps]] +id = "survey-code" +title = "Survey the code structure" +needs = ["load-context"] +description = """ +Get a high-level understanding before diving into details. + +**1. Understand the structure:** +```bash +# For a directory: +tree {{scope}} -L 2 + +# For a file: +wc -l {{scope}} # How big is it? +``` + +**2. Identify key components:** +- What are the main types/structs? +- What are the public functions? +- What are the dependencies? + +**3. Read the tests (if any):** +```bash +find {{scope}} -name "*_test.go" | xargs head -50 +``` +Tests often reveal intended behavior. + +**4. Note initial impressions:** +- Is the code well-organized? +- Are there obvious patterns or anti-patterns? +- What areas look risky? + +**Exit criteria:** You have a mental map of the code structure.""" + +[[steps]] +id = "detailed-review" +title = "Perform detailed code review" +needs = ["survey-code"] +description = """ +Systematically review the code for issues. + +**Review checklist:** + +| Category | Look For | +|----------|----------| +| **Correctness** | Logic errors, off-by-one, nil handling, race conditions | +| **Security** | Injection, auth bypass, secrets in code, unsafe operations | +| **Error handling** | Swallowed errors, missing checks, unclear error messages | +| **Performance** | N+1 queries, unnecessary allocations, blocking calls | +| **Maintainability** | Dead code, unclear naming, missing comments on complex logic | +| **Testing** | Untested paths, missing edge cases, flaky tests | + +**Focus on {{focus}} if specified.** + +**1. Read through the code:** +```bash +cat {{scope}} # For single file +# Or read files systematically for a directory +``` + +**2. For each issue found, note:** +- File and line number +- Category (bug, security, performance, etc.) +- Severity (critical, high, medium, low) +- Description of the issue +- Suggested fix (if obvious) + +**3. Don't fix issues yourself:** +Your job is to find and report, not fix. File beads. + +**Exit criteria:** You've reviewed all code in scope and noted issues.""" + +[[steps]] +id = "prioritize-findings" +title = "Prioritize and categorize findings" +needs = ["detailed-review"] +description = """ +Organize your findings by priority and category. + +**Priority levels:** + +| Priority | Description | Action | +|----------|-------------|--------| +| P0 | Security vulnerability, data loss risk | Mail Witness immediately | +| P1 | Bug affecting users, broken functionality | File as bug, high priority | +| P2 | Code quality issue, potential future bug | File as task | +| P3 | Improvement opportunity, nice-to-have | File as task, low priority | + +**1. Sort your findings:** +Group by priority, then by category. + +**2. For P0 issues:** +```bash +gt mail send {{rig}}/witness -s "CRITICAL: Security issue found" -m "Scope: {{scope}} +Issue: {{issue}} +Finding: +Location: " +``` + +**3. Prepare bead descriptions:** +For each finding, prepare: +- Clear title +- File/line location +- Description of the issue +- Why it matters +- Suggested fix (if known) + +**Exit criteria:** Findings prioritized and ready to file.""" + +[[steps]] +id = "file-beads" +title = "File beads for all findings" +needs = ["prioritize-findings"] +description = """ +Create beads for each finding. + +**1. For bugs (P0, P1):** +```bash +bd create --type=bug --priority=1 \ + --title="" \ + --description="Found during code review of {{scope}}. + +Location: + +Issue: + + +Impact: + + +Suggested fix: +" +``` + +**2. For code quality issues (P2, P3):** +```bash +bd create --type=task --priority=2 \ + --title="" \ + --description="Found during code review of {{scope}}. + +Location: + +Issue: + + +Suggestion: +" +``` + +**3. Track filed beads:** +Note each bead ID as you create them. + +**4. If no issues found:** +That's a valid outcome! Note that the code review passed. + +**Exit criteria:** All findings filed as beads.""" + +[[steps]] +id = "summarize-review" +title = "Summarize review results" +needs = ["file-beads"] +description = """ +Update the tracking issue with review summary. + +**1. Create summary:** +```bash +bd update {{issue}} --notes "Code review complete. + +Scope: {{scope}} +Focus: {{focus}} + +Findings: +- P0 (critical): +- P1 (high): +- P2 (medium): +- P3 (low): + +Beads filed: + + +Overall assessment: +" +``` + +**2. Sync beads:** +```bash +bd sync +``` + +**Exit criteria:** Tracking issue updated with summary.""" + +[[steps]] +id = "complete-and-exit" +title = "Complete review and self-clean" +needs = ["summarize-review"] +description = """ +Signal completion and clean up. You cease to exist after this step. + +**Self-Cleaning Model:** +Once you run `gt done`, you're gone. The command: +1. Syncs beads (final sync) +2. Nukes your sandbox +3. Exits your session immediately + +**Run gt done:** +```bash +gt done +``` + +**What happens next (not your concern):** +- Other polecats may be assigned to fix the issues you found +- Witness may escalate critical findings +- The codebase improves based on your findings + +You are NOT involved in any of that. You're gone. Done means gone. + +**Exit criteria:** Beads synced, sandbox nuked, session exited.""" + +[vars] +[vars.scope] +description = "What to review - file path, directory, or description" +required = true + +[vars.issue] +description = "The tracking issue for this review task" +required = true + +[vars.focus] +description = "Optional focus area (security, performance, correctness, etc.)" +required = false diff --git a/.beads/formulas/mol-polecat-review-pr.formula.toml b/.beads/formulas/mol-polecat-review-pr.formula.toml new file mode 100644 index 00000000..d789152f --- /dev/null +++ b/.beads/formulas/mol-polecat-review-pr.formula.toml @@ -0,0 +1,283 @@ +description = """ +Review an external PR and decide on merge/reject/revise. + +This molecule guides a polecat through reviewing a pull request from an external +contributor. The polecat reviews code quality, tests, and alignment with project +standards, then approves, requests changes, or files followup beads. + +## Polecat Contract (Self-Cleaning Model) + +You are a self-cleaning worker. You: +1. Receive work via your hook (pinned molecule + PR reference) +2. Work through molecule steps using `bd ready` / `bd close ` +3. Complete and self-clean via `gt done` (submit findings + nuke yourself) +4. You are GONE - your review is recorded in beads + +**Self-cleaning:** When you run `gt done`, you submit your findings, nuke your +sandbox, and exit. There is no idle state. Done means gone. + +**Important:** This formula defines the template. Your molecule already has step +beads created from it. Use `bd ready` to find them - do NOT read this file directly. + +**You do NOT:** +- Merge the PR yourself (maintainer or Refinery does that) +- Push to the PR branch (it's external) +- Wait for contributor response (you're done after review) + +## Variables + +| Variable | Source | Description | +|----------|--------|-------------| +| pr_url | hook_bead | The PR URL to review | +| issue | hook_bead | The tracking issue for this review task | + +## Failure Modes + +| Situation | Action | +|-----------|--------| +| PR is stale/unmergeable | Note in review, request rebase | +| Tests fail | Note in review, request fixes | +| Major issues found | File followup beads, request changes | +| Unclear requirements | Mail Witness for guidance |""" +formula = "mol-polecat-review-pr" +version = 1 + +[[steps]] +id = "load-context" +title = "Load context and understand the PR" +description = """ +Initialize your session and understand the PR you're reviewing. + +**1. Prime your environment:** +```bash +gt prime # Load role context +bd prime # Load beads context +``` + +**2. Check your hook:** +```bash +gt hook # Shows your pinned molecule and hook_bead +``` + +The hook_bead references the PR to review. Read the tracking issue: +```bash +bd show {{issue}} # Full issue details including PR URL +``` + +**3. Fetch the PR:** +```bash +gh pr view {{pr_url}} --json title,body,author,files,commits +gh pr diff {{pr_url}} # See the actual changes +``` + +**4. Understand the PR:** +- What is the PR trying to accomplish? +- What files are changed? +- Is there a linked issue? +- Does the PR description explain the "why"? + +**5. Check PR status:** +```bash +gh pr checks {{pr_url}} # CI status +gh pr view {{pr_url}} --json mergeable,reviewDecision +``` + +**Exit criteria:** You understand the PR's purpose and scope.""" + +[[steps]] +id = "review-code" +title = "Review the code changes" +needs = ["load-context"] +description = """ +Perform a thorough code review of the PR. + +**1. Review the diff systematically:** +```bash +gh pr diff {{pr_url}} +``` + +**2. Check for common issues:** + +| Category | Look For | +|----------|----------| +| Correctness | Logic errors, edge cases, null handling | +| Security | Injection, auth bypass, exposed secrets | +| Style | Naming, formatting, consistency with codebase | +| Tests | Are changes tested? Do tests cover edge cases? | +| Docs | Are docs updated if needed? | +| Scope | Does PR stay focused? Any scope creep? | + +**3. For each file changed:** +- Does the change make sense? +- Is it consistent with existing patterns? +- Are there any red flags? + +**4. Note issues found:** +Keep a running list of: +- Blocking issues (must fix before merge) +- Suggestions (nice to have) +- Questions (need clarification) + +**Exit criteria:** You have reviewed all changes and noted issues.""" + +[[steps]] +id = "check-tests" +title = "Verify tests and CI" +needs = ["review-code"] +description = """ +Ensure tests pass and coverage is adequate. + +**1. Check CI status:** +```bash +gh pr checks {{pr_url}} +``` + +All required checks should pass. If not, note which are failing. + +**2. Review test changes:** +- Are there new tests for new functionality? +- Do tests cover edge cases? +- Are tests readable and maintainable? + +**3. If tests are missing:** +Note this as a blocking issue - new code should have tests. + +**4. Check for test-only changes:** +If PR is test-only, ensure tests are meaningful and not just +padding coverage numbers. + +**Exit criteria:** You've verified test status and coverage.""" + +[[steps]] +id = "make-decision" +title = "Decide: approve, request changes, or needs discussion" +needs = ["check-tests"] +description = """ +Make your review decision. + +**Decision matrix:** + +| Situation | Decision | +|-----------|----------| +| Clean code, tests pass, good scope | APPROVE | +| Minor issues, easily fixed | REQUEST_CHANGES (with specific feedback) | +| Major issues, needs rework | REQUEST_CHANGES (with detailed explanation) | +| Unclear requirements or scope | NEEDS_DISCUSSION (mail Witness) | +| Security concern | BLOCK (mail Witness immediately) | + +**1. If APPROVE:** +The PR is ready to merge. Note any minor suggestions as comments +but don't block on them. + +**2. If REQUEST_CHANGES:** +Be specific about what needs to change. Provide examples if helpful. +The contributor should be able to act on your feedback. + +**3. If NEEDS_DISCUSSION:** +```bash +gt mail send {{rig}}/witness -s "PR review needs discussion" -m "PR: {{pr_url}} +Issue: {{issue}} +Question: " +``` + +**4. If BLOCK (security):** +```bash +gt mail send {{rig}}/witness -s "SECURITY: PR blocked" -m "PR: {{pr_url}} +Issue: {{issue}} +Concern: " +``` + +**Exit criteria:** You've made a clear decision with rationale.""" + +[[steps]] +id = "submit-review" +title = "Submit the review on GitHub" +needs = ["make-decision"] +description = """ +Submit your review via GitHub. + +**1. Submit the review:** +```bash +# For APPROVE: +gh pr review {{pr_url}} --approve --body "LGTM. " + +# For REQUEST_CHANGES: +gh pr review {{pr_url}} --request-changes --body "" + +# For COMMENT (needs discussion): +gh pr review {{pr_url}} --comment --body "" +``` + +**2. Add inline comments if needed:** +If you have specific line-by-line feedback, add those via GitHub UI +or additional `gh pr comment` calls. + +**Exit criteria:** Review submitted on GitHub.""" + +[[steps]] +id = "file-followups" +title = "File beads for any followup work" +needs = ["submit-review"] +description = """ +Create beads for any followup work discovered during review. + +**1. For issues found that are outside PR scope:** +```bash +bd create --type=bug --title="Found during PR review: " \ + --description="Discovered while reviewing {{pr_url}}. + +
" +``` + +**2. For improvements suggested but not required:** +```bash +bd create --type=task --title="Improvement: " \ + --description="Suggested during review of {{pr_url}}. + +
" +``` + +**3. Update the tracking issue:** +```bash +bd update {{issue}} --notes "Review complete. Decision: +Followups filed: " +``` + +**Exit criteria:** All followup work captured as beads.""" + +[[steps]] +id = "complete-and-exit" +title = "Complete review and self-clean" +needs = ["file-followups"] +description = """ +Signal completion and clean up. You cease to exist after this step. + +**Self-Cleaning Model:** +Once you run `gt done`, you're gone. The command: +1. Syncs beads +2. Nukes your sandbox +3. Exits your session immediately + +**Run gt done:** +```bash +bd sync +gt done +``` + +**What happens next (not your concern):** +- Maintainer or Refinery acts on your review +- Contributor responds to feedback +- PR gets merged, revised, or closed + +You are NOT involved in any of that. You're gone. Done means gone. + +**Exit criteria:** Beads synced, sandbox nuked, session exited.""" + +[vars] +[vars.pr_url] +description = "The PR URL to review" +required = true + +[vars.issue] +description = "The tracking issue for this review task" +required = true diff --git a/.beads/formulas/mol-polecat-work.formula.toml b/.beads/formulas/mol-polecat-work.formula.toml index 3992f502..442e23d6 100644 --- a/.beads/formulas/mol-polecat-work.formula.toml +++ b/.beads/formulas/mol-polecat-work.formula.toml @@ -1,26 +1,29 @@ description = """ -Full polecat work lifecycle from assignment through MR submission. +Full polecat work lifecycle from assignment through completion. This molecule guides a polecat through a complete work assignment. Each step has clear entry/exit criteria and specific commands to run. A polecat can crash after any step and resume from the last completed step. -## Polecat Contract (Ephemeral Model) +## Polecat Contract (Self-Cleaning Model) -You are an ephemeral worker. You: +You are a self-cleaning worker. You: 1. Receive work via your hook (pinned molecule + issue) 2. Work through molecule steps using `bd ready` / `bd close ` -3. Submit to merge queue via `gt done` -4. Become recyclable - Refinery handles the rest +3. Complete and self-clean via `gt done` (submit + nuke yourself) +4. You are GONE - Refinery merges from MQ + +**Self-cleaning:** When you run `gt done`, you push your work, submit to MQ, +nuke your sandbox, and exit. There is no idle state. Done means gone. **Important:** This formula defines the template. Your molecule already has step beads created from it. Use `bd ready` to find them - do NOT read this file directly. **You do NOT:** -- Push directly to main (Refinery merges) +- Push directly to main (Refinery merges from MQ) - Close your own issue (Refinery closes after merge) -- Wait for merge (you're done at MR submission) -- Handle rebase conflicts (Refinery dispatches fresh polecats for that) +- Wait for merge (you're gone after `gt done`) +- Handle rebase conflicts (Refinery spawns fresh polecats for that) ## Variables @@ -407,30 +410,23 @@ bd sync [[steps]] id = "submit-and-exit" -title = "Submit to merge queue and exit" +title = "Submit work and self-clean" needs = ["prepare-for-review"] description = """ -Submit your work to the merge queue. You become recyclable after this. +Submit your work and clean up. You cease to exist after this step. -**Ephemeral Polecat Model:** -Once you submit, you're done. The Refinery will: -1. Process your merge request -2. Handle rebasing (mechanical rebases done automatically) -3. Close your issue after successful merge -4. Create conflict-resolution tasks if needed (fresh polecat handles those) +**Self-Cleaning Model:** +Once you run `gt done`, you're gone. The command: +1. Pushes your branch to origin +2. Creates an MR bead in the merge queue +3. Nukes your sandbox (worktree removal) +4. Exits your session immediately -**1. Submit with gt done:** +**Run gt done:** ```bash gt done ``` -This single command: -- Creates an MR bead in the merge queue -- Notifies the Witness (POLECAT_DONE) -- Updates your agent state to 'done' -- Reports cleanup status (ZFC compliance) - -**2. Verify submission:** You should see output like: ``` ✓ Work submitted to merge queue @@ -438,20 +434,19 @@ You should see output like: Source: polecat/ Target: main Issue: {{issue}} +✓ Sandbox nuked +✓ Session exiting ``` -**3. You're recyclable:** -Your work is in the queue. The Witness knows you're done. -Your sandbox can be cleaned up - all work is pushed to origin. +**What happens next (not your concern):** +- Refinery processes your MR from the queue +- Refinery rebases and merges to main +- Refinery closes the issue +- If conflicts: Refinery spawns a FRESH polecat to re-implement -If you have context remaining, you may: -- Pick up new work from `bd ready` -- Or use `gt handoff` to cycle to a fresh session +You are NOT involved in any of that. You're gone. Done means gone. -If the Refinery needs conflict resolution, it will dispatch a fresh polecat. -You do NOT need to wait around. - -**Exit criteria:** MR submitted, Witness notified, polecat recyclable.""" +**Exit criteria:** Work submitted, sandbox nuked, session exited.""" [vars] [vars.issue] diff --git a/docs/polecat-lifecycle.md b/docs/polecat-lifecycle.md index 79483013..faeb925a 100644 --- a/docs/polecat-lifecycle.md +++ b/docs/polecat-lifecycle.md @@ -5,9 +5,36 @@ ## Overview Polecats have three distinct lifecycle layers that operate independently. Confusing -these layers leads to heresies like "idle polecats" and misunderstanding when +these layers leads to bugs like "idle polecats" and misunderstanding when recycling occurs. +## The Self-Cleaning Polecat Model + +**Polecats are responsible for their own cleanup.** When a polecat completes its +work unit, it: + +1. Signals completion via `gt done` +2. Exits its session immediately (no idle waiting) +3. Requests its own nuke (self-delete) + +This removes dependency on the Witness/Deacon for cleanup and ensures polecats +never sit idle. The simple model: **sandbox dies with session**. + +### Why Self-Cleaning? + +- **No idle polecats** - There's no state where a polecat exists without work +- **Reduced watchdog overhead** - Deacon doesn't need to patrol for zombies +- **Faster turnover** - Resources freed immediately on completion +- **Simpler mental model** - Done means gone + +### What About Pending Merges? + +The Refinery owns the merge queue. Once `gt done` submits work: +- The branch is pushed to origin +- Work exists in the MQ, not in the polecat +- If rebase fails, Refinery re-implements on new baseline (fresh polecat) +- The original polecat is already gone - no sending work "back" + ## The Three Layers | Layer | Component | Lifecycle | Persistence | @@ -92,19 +119,23 @@ The slot: │ ▼ ┌─────────────────────────────────────────────────────────────┐ -│ gt done │ -│ → Polecat signals completion to Witness │ -│ → Session exits (no idle waiting) │ -│ → Witness receives POLECAT_DONE event │ +│ gt done (self-cleaning) │ +│ → Push branch to origin │ +│ → Submit work to merge queue (MR bead) │ +│ → Request self-nuke (sandbox + session cleanup) │ +│ → Exit immediately │ +│ │ +│ Work now lives in MQ, not in polecat. │ +│ Polecat is GONE. No idle state. │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ -│ Witness: gt polecat nuke │ -│ → Verify work landed (merged or in MQ) │ -│ → Delete sandbox (remove worktree) │ -│ → Kill tmux session │ -│ → Release slot back to pool │ +│ Refinery: merge queue │ +│ → Rebase and merge to main │ +│ → Close the issue │ +│ → If conflict: spawn FRESH polecat to re-implement │ +│ (never send work back to original polecat - it's gone) │ └─────────────────────────────────────────────────────────────┘ ``` @@ -210,13 +241,40 @@ All except `gt done` result in continued work. Only `gt done` signals completion The Witness monitors polecats but does NOT: - Force session cycles (polecats self-manage via handoff) - Interrupt mid-step (unless truly stuck) -- Recycle sandboxes between steps +- Nuke polecats (polecats self-nuke via `gt done`) The Witness DOES: - Respawn crashed sessions - Nudge stuck polecats -- Nuke completed polecats (after verification) - Handle escalations +- Clean up orphaned polecats (crash before `gt done`) + +## Polecat Identity + +**Key insight:** Polecat *identity* is long-lived; only sessions and sandboxes are ephemeral. + +In the HOP model, every entity has a chain (CV) that tracks: +- What work they've done +- Success/failure rates +- Skills demonstrated +- Quality metrics + +The polecat *name* (Toast, Shadow, etc.) is a slot from a pool - truly ephemeral. +But the *agent identity* that executes as that polecat accumulates a work history. + +``` +POLECAT IDENTITY (persistent) SESSION (ephemeral) SANDBOX (ephemeral) +├── CV chain ├── Claude instance ├── Git worktree +├── Work history ├── Context window ├── Branch +├── Skills demonstrated └── Dies on handoff └── Dies on gt done +└── Credit for work or gt done +``` + +This distinction matters for: +- **Attribution** - Who gets credit for the work? +- **Skill routing** - Which agent is best for this task? +- **Cost accounting** - Who pays for inference? +- **Federation** - Agents having their own chains in a distributed world ## Related Documentation diff --git a/internal/formula/formulas/mol-polecat-code-review.formula.toml b/internal/formula/formulas/mol-polecat-code-review.formula.toml new file mode 100644 index 00000000..b4379e16 --- /dev/null +++ b/internal/formula/formulas/mol-polecat-code-review.formula.toml @@ -0,0 +1,318 @@ +description = """ +Review code and file beads for issues found. + +This molecule guides a polecat through a code review task - examining a portion +of the codebase for bugs, security issues, code quality problems, or improvement +opportunities. The output is a set of beads capturing actionable findings. + +## Polecat Contract (Self-Cleaning Model) + +You are a self-cleaning worker. You: +1. Receive work via your hook (pinned molecule + review scope) +2. Work through molecule steps using `bd ready` / `bd close ` +3. Complete and self-clean via `gt done` (submit findings + nuke yourself) +4. You are GONE - your findings are recorded in beads + +**Self-cleaning:** When you run `gt done`, you submit your findings, nuke your +sandbox, and exit. There is no idle state. Done means gone. + +**Important:** This formula defines the template. Your molecule already has step +beads created from it. Use `bd ready` to find them - do NOT read this file directly. + +**You do NOT:** +- Fix the issues yourself (file beads, let other polecats fix) +- Scope creep into unrelated areas +- Wait for someone to act on findings (you're done after filing) + +## Variables + +| Variable | Source | Description | +|----------|--------|-------------| +| scope | hook_bead | What to review (file path, directory, or description) | +| issue | hook_bead | The tracking issue for this review task | +| focus | hook_bead | Optional focus area (security, performance, etc.) | + +## Failure Modes + +| Situation | Action | +|-----------|--------| +| Scope too broad | Mail Witness, request narrower scope | +| Can't understand code | Mail Witness for context | +| Critical issue found | Mail Witness immediately, then continue |""" +formula = "mol-polecat-code-review" +version = 1 + +[[steps]] +id = "load-context" +title = "Load context and understand the review scope" +description = """ +Initialize your session and understand what you're reviewing. + +**1. Prime your environment:** +```bash +gt prime # Load role context +bd prime # Load beads context +``` + +**2. Check your hook:** +```bash +gt hook # Shows your pinned molecule and hook_bead +``` + +The hook_bead describes your review scope. Read the tracking issue: +```bash +bd show {{issue}} # Full issue details +``` + +**3. Understand the scope:** +- What files/directories are in scope? +- Is there a specific focus (security, performance, correctness)? +- What's the context - why is this review happening? + +**4. Locate the code:** +```bash +# If scope is a path: +ls -la {{scope}} +head -100 {{scope}} # Quick look at the code + +# If scope is a directory: +find {{scope}} -type f -name "*.go" | head -20 +``` + +**5. Check for recent changes:** +```bash +git log --oneline -10 -- {{scope}} +``` + +**Exit criteria:** You understand what you're reviewing and why.""" + +[[steps]] +id = "survey-code" +title = "Survey the code structure" +needs = ["load-context"] +description = """ +Get a high-level understanding before diving into details. + +**1. Understand the structure:** +```bash +# For a directory: +tree {{scope}} -L 2 + +# For a file: +wc -l {{scope}} # How big is it? +``` + +**2. Identify key components:** +- What are the main types/structs? +- What are the public functions? +- What are the dependencies? + +**3. Read the tests (if any):** +```bash +find {{scope}} -name "*_test.go" | xargs head -50 +``` +Tests often reveal intended behavior. + +**4. Note initial impressions:** +- Is the code well-organized? +- Are there obvious patterns or anti-patterns? +- What areas look risky? + +**Exit criteria:** You have a mental map of the code structure.""" + +[[steps]] +id = "detailed-review" +title = "Perform detailed code review" +needs = ["survey-code"] +description = """ +Systematically review the code for issues. + +**Review checklist:** + +| Category | Look For | +|----------|----------| +| **Correctness** | Logic errors, off-by-one, nil handling, race conditions | +| **Security** | Injection, auth bypass, secrets in code, unsafe operations | +| **Error handling** | Swallowed errors, missing checks, unclear error messages | +| **Performance** | N+1 queries, unnecessary allocations, blocking calls | +| **Maintainability** | Dead code, unclear naming, missing comments on complex logic | +| **Testing** | Untested paths, missing edge cases, flaky tests | + +**Focus on {{focus}} if specified.** + +**1. Read through the code:** +```bash +cat {{scope}} # For single file +# Or read files systematically for a directory +``` + +**2. For each issue found, note:** +- File and line number +- Category (bug, security, performance, etc.) +- Severity (critical, high, medium, low) +- Description of the issue +- Suggested fix (if obvious) + +**3. Don't fix issues yourself:** +Your job is to find and report, not fix. File beads. + +**Exit criteria:** You've reviewed all code in scope and noted issues.""" + +[[steps]] +id = "prioritize-findings" +title = "Prioritize and categorize findings" +needs = ["detailed-review"] +description = """ +Organize your findings by priority and category. + +**Priority levels:** + +| Priority | Description | Action | +|----------|-------------|--------| +| P0 | Security vulnerability, data loss risk | Mail Witness immediately | +| P1 | Bug affecting users, broken functionality | File as bug, high priority | +| P2 | Code quality issue, potential future bug | File as task | +| P3 | Improvement opportunity, nice-to-have | File as task, low priority | + +**1. Sort your findings:** +Group by priority, then by category. + +**2. For P0 issues:** +```bash +gt mail send {{rig}}/witness -s "CRITICAL: Security issue found" -m "Scope: {{scope}} +Issue: {{issue}} +Finding: +Location: " +``` + +**3. Prepare bead descriptions:** +For each finding, prepare: +- Clear title +- File/line location +- Description of the issue +- Why it matters +- Suggested fix (if known) + +**Exit criteria:** Findings prioritized and ready to file.""" + +[[steps]] +id = "file-beads" +title = "File beads for all findings" +needs = ["prioritize-findings"] +description = """ +Create beads for each finding. + +**1. For bugs (P0, P1):** +```bash +bd create --type=bug --priority=1 \ + --title="" \ + --description="Found during code review of {{scope}}. + +Location: + +Issue: + + +Impact: + + +Suggested fix: +" +``` + +**2. For code quality issues (P2, P3):** +```bash +bd create --type=task --priority=2 \ + --title="" \ + --description="Found during code review of {{scope}}. + +Location: + +Issue: + + +Suggestion: +" +``` + +**3. Track filed beads:** +Note each bead ID as you create them. + +**4. If no issues found:** +That's a valid outcome! Note that the code review passed. + +**Exit criteria:** All findings filed as beads.""" + +[[steps]] +id = "summarize-review" +title = "Summarize review results" +needs = ["file-beads"] +description = """ +Update the tracking issue with review summary. + +**1. Create summary:** +```bash +bd update {{issue}} --notes "Code review complete. + +Scope: {{scope}} +Focus: {{focus}} + +Findings: +- P0 (critical): +- P1 (high): +- P2 (medium): +- P3 (low): + +Beads filed: + + +Overall assessment: +" +``` + +**2. Sync beads:** +```bash +bd sync +``` + +**Exit criteria:** Tracking issue updated with summary.""" + +[[steps]] +id = "complete-and-exit" +title = "Complete review and self-clean" +needs = ["summarize-review"] +description = """ +Signal completion and clean up. You cease to exist after this step. + +**Self-Cleaning Model:** +Once you run `gt done`, you're gone. The command: +1. Syncs beads (final sync) +2. Nukes your sandbox +3. Exits your session immediately + +**Run gt done:** +```bash +gt done +``` + +**What happens next (not your concern):** +- Other polecats may be assigned to fix the issues you found +- Witness may escalate critical findings +- The codebase improves based on your findings + +You are NOT involved in any of that. You're gone. Done means gone. + +**Exit criteria:** Beads synced, sandbox nuked, session exited.""" + +[vars] +[vars.scope] +description = "What to review - file path, directory, or description" +required = true + +[vars.issue] +description = "The tracking issue for this review task" +required = true + +[vars.focus] +description = "Optional focus area (security, performance, correctness, etc.)" +required = false diff --git a/internal/formula/formulas/mol-polecat-review-pr.formula.toml b/internal/formula/formulas/mol-polecat-review-pr.formula.toml new file mode 100644 index 00000000..d789152f --- /dev/null +++ b/internal/formula/formulas/mol-polecat-review-pr.formula.toml @@ -0,0 +1,283 @@ +description = """ +Review an external PR and decide on merge/reject/revise. + +This molecule guides a polecat through reviewing a pull request from an external +contributor. The polecat reviews code quality, tests, and alignment with project +standards, then approves, requests changes, or files followup beads. + +## Polecat Contract (Self-Cleaning Model) + +You are a self-cleaning worker. You: +1. Receive work via your hook (pinned molecule + PR reference) +2. Work through molecule steps using `bd ready` / `bd close ` +3. Complete and self-clean via `gt done` (submit findings + nuke yourself) +4. You are GONE - your review is recorded in beads + +**Self-cleaning:** When you run `gt done`, you submit your findings, nuke your +sandbox, and exit. There is no idle state. Done means gone. + +**Important:** This formula defines the template. Your molecule already has step +beads created from it. Use `bd ready` to find them - do NOT read this file directly. + +**You do NOT:** +- Merge the PR yourself (maintainer or Refinery does that) +- Push to the PR branch (it's external) +- Wait for contributor response (you're done after review) + +## Variables + +| Variable | Source | Description | +|----------|--------|-------------| +| pr_url | hook_bead | The PR URL to review | +| issue | hook_bead | The tracking issue for this review task | + +## Failure Modes + +| Situation | Action | +|-----------|--------| +| PR is stale/unmergeable | Note in review, request rebase | +| Tests fail | Note in review, request fixes | +| Major issues found | File followup beads, request changes | +| Unclear requirements | Mail Witness for guidance |""" +formula = "mol-polecat-review-pr" +version = 1 + +[[steps]] +id = "load-context" +title = "Load context and understand the PR" +description = """ +Initialize your session and understand the PR you're reviewing. + +**1. Prime your environment:** +```bash +gt prime # Load role context +bd prime # Load beads context +``` + +**2. Check your hook:** +```bash +gt hook # Shows your pinned molecule and hook_bead +``` + +The hook_bead references the PR to review. Read the tracking issue: +```bash +bd show {{issue}} # Full issue details including PR URL +``` + +**3. Fetch the PR:** +```bash +gh pr view {{pr_url}} --json title,body,author,files,commits +gh pr diff {{pr_url}} # See the actual changes +``` + +**4. Understand the PR:** +- What is the PR trying to accomplish? +- What files are changed? +- Is there a linked issue? +- Does the PR description explain the "why"? + +**5. Check PR status:** +```bash +gh pr checks {{pr_url}} # CI status +gh pr view {{pr_url}} --json mergeable,reviewDecision +``` + +**Exit criteria:** You understand the PR's purpose and scope.""" + +[[steps]] +id = "review-code" +title = "Review the code changes" +needs = ["load-context"] +description = """ +Perform a thorough code review of the PR. + +**1. Review the diff systematically:** +```bash +gh pr diff {{pr_url}} +``` + +**2. Check for common issues:** + +| Category | Look For | +|----------|----------| +| Correctness | Logic errors, edge cases, null handling | +| Security | Injection, auth bypass, exposed secrets | +| Style | Naming, formatting, consistency with codebase | +| Tests | Are changes tested? Do tests cover edge cases? | +| Docs | Are docs updated if needed? | +| Scope | Does PR stay focused? Any scope creep? | + +**3. For each file changed:** +- Does the change make sense? +- Is it consistent with existing patterns? +- Are there any red flags? + +**4. Note issues found:** +Keep a running list of: +- Blocking issues (must fix before merge) +- Suggestions (nice to have) +- Questions (need clarification) + +**Exit criteria:** You have reviewed all changes and noted issues.""" + +[[steps]] +id = "check-tests" +title = "Verify tests and CI" +needs = ["review-code"] +description = """ +Ensure tests pass and coverage is adequate. + +**1. Check CI status:** +```bash +gh pr checks {{pr_url}} +``` + +All required checks should pass. If not, note which are failing. + +**2. Review test changes:** +- Are there new tests for new functionality? +- Do tests cover edge cases? +- Are tests readable and maintainable? + +**3. If tests are missing:** +Note this as a blocking issue - new code should have tests. + +**4. Check for test-only changes:** +If PR is test-only, ensure tests are meaningful and not just +padding coverage numbers. + +**Exit criteria:** You've verified test status and coverage.""" + +[[steps]] +id = "make-decision" +title = "Decide: approve, request changes, or needs discussion" +needs = ["check-tests"] +description = """ +Make your review decision. + +**Decision matrix:** + +| Situation | Decision | +|-----------|----------| +| Clean code, tests pass, good scope | APPROVE | +| Minor issues, easily fixed | REQUEST_CHANGES (with specific feedback) | +| Major issues, needs rework | REQUEST_CHANGES (with detailed explanation) | +| Unclear requirements or scope | NEEDS_DISCUSSION (mail Witness) | +| Security concern | BLOCK (mail Witness immediately) | + +**1. If APPROVE:** +The PR is ready to merge. Note any minor suggestions as comments +but don't block on them. + +**2. If REQUEST_CHANGES:** +Be specific about what needs to change. Provide examples if helpful. +The contributor should be able to act on your feedback. + +**3. If NEEDS_DISCUSSION:** +```bash +gt mail send {{rig}}/witness -s "PR review needs discussion" -m "PR: {{pr_url}} +Issue: {{issue}} +Question: " +``` + +**4. If BLOCK (security):** +```bash +gt mail send {{rig}}/witness -s "SECURITY: PR blocked" -m "PR: {{pr_url}} +Issue: {{issue}} +Concern: " +``` + +**Exit criteria:** You've made a clear decision with rationale.""" + +[[steps]] +id = "submit-review" +title = "Submit the review on GitHub" +needs = ["make-decision"] +description = """ +Submit your review via GitHub. + +**1. Submit the review:** +```bash +# For APPROVE: +gh pr review {{pr_url}} --approve --body "LGTM. " + +# For REQUEST_CHANGES: +gh pr review {{pr_url}} --request-changes --body "" + +# For COMMENT (needs discussion): +gh pr review {{pr_url}} --comment --body "" +``` + +**2. Add inline comments if needed:** +If you have specific line-by-line feedback, add those via GitHub UI +or additional `gh pr comment` calls. + +**Exit criteria:** Review submitted on GitHub.""" + +[[steps]] +id = "file-followups" +title = "File beads for any followup work" +needs = ["submit-review"] +description = """ +Create beads for any followup work discovered during review. + +**1. For issues found that are outside PR scope:** +```bash +bd create --type=bug --title="Found during PR review: " \ + --description="Discovered while reviewing {{pr_url}}. + +
" +``` + +**2. For improvements suggested but not required:** +```bash +bd create --type=task --title="Improvement: " \ + --description="Suggested during review of {{pr_url}}. + +
" +``` + +**3. Update the tracking issue:** +```bash +bd update {{issue}} --notes "Review complete. Decision: +Followups filed: " +``` + +**Exit criteria:** All followup work captured as beads.""" + +[[steps]] +id = "complete-and-exit" +title = "Complete review and self-clean" +needs = ["file-followups"] +description = """ +Signal completion and clean up. You cease to exist after this step. + +**Self-Cleaning Model:** +Once you run `gt done`, you're gone. The command: +1. Syncs beads +2. Nukes your sandbox +3. Exits your session immediately + +**Run gt done:** +```bash +bd sync +gt done +``` + +**What happens next (not your concern):** +- Maintainer or Refinery acts on your review +- Contributor responds to feedback +- PR gets merged, revised, or closed + +You are NOT involved in any of that. You're gone. Done means gone. + +**Exit criteria:** Beads synced, sandbox nuked, session exited.""" + +[vars] +[vars.pr_url] +description = "The PR URL to review" +required = true + +[vars.issue] +description = "The tracking issue for this review task" +required = true diff --git a/internal/formula/formulas/mol-polecat-work.formula.toml b/internal/formula/formulas/mol-polecat-work.formula.toml index 3992f502..442e23d6 100644 --- a/internal/formula/formulas/mol-polecat-work.formula.toml +++ b/internal/formula/formulas/mol-polecat-work.formula.toml @@ -1,26 +1,29 @@ description = """ -Full polecat work lifecycle from assignment through MR submission. +Full polecat work lifecycle from assignment through completion. This molecule guides a polecat through a complete work assignment. Each step has clear entry/exit criteria and specific commands to run. A polecat can crash after any step and resume from the last completed step. -## Polecat Contract (Ephemeral Model) +## Polecat Contract (Self-Cleaning Model) -You are an ephemeral worker. You: +You are a self-cleaning worker. You: 1. Receive work via your hook (pinned molecule + issue) 2. Work through molecule steps using `bd ready` / `bd close ` -3. Submit to merge queue via `gt done` -4. Become recyclable - Refinery handles the rest +3. Complete and self-clean via `gt done` (submit + nuke yourself) +4. You are GONE - Refinery merges from MQ + +**Self-cleaning:** When you run `gt done`, you push your work, submit to MQ, +nuke your sandbox, and exit. There is no idle state. Done means gone. **Important:** This formula defines the template. Your molecule already has step beads created from it. Use `bd ready` to find them - do NOT read this file directly. **You do NOT:** -- Push directly to main (Refinery merges) +- Push directly to main (Refinery merges from MQ) - Close your own issue (Refinery closes after merge) -- Wait for merge (you're done at MR submission) -- Handle rebase conflicts (Refinery dispatches fresh polecats for that) +- Wait for merge (you're gone after `gt done`) +- Handle rebase conflicts (Refinery spawns fresh polecats for that) ## Variables @@ -407,30 +410,23 @@ bd sync [[steps]] id = "submit-and-exit" -title = "Submit to merge queue and exit" +title = "Submit work and self-clean" needs = ["prepare-for-review"] description = """ -Submit your work to the merge queue. You become recyclable after this. +Submit your work and clean up. You cease to exist after this step. -**Ephemeral Polecat Model:** -Once you submit, you're done. The Refinery will: -1. Process your merge request -2. Handle rebasing (mechanical rebases done automatically) -3. Close your issue after successful merge -4. Create conflict-resolution tasks if needed (fresh polecat handles those) +**Self-Cleaning Model:** +Once you run `gt done`, you're gone. The command: +1. Pushes your branch to origin +2. Creates an MR bead in the merge queue +3. Nukes your sandbox (worktree removal) +4. Exits your session immediately -**1. Submit with gt done:** +**Run gt done:** ```bash gt done ``` -This single command: -- Creates an MR bead in the merge queue -- Notifies the Witness (POLECAT_DONE) -- Updates your agent state to 'done' -- Reports cleanup status (ZFC compliance) - -**2. Verify submission:** You should see output like: ``` ✓ Work submitted to merge queue @@ -438,20 +434,19 @@ You should see output like: Source: polecat/ Target: main Issue: {{issue}} +✓ Sandbox nuked +✓ Session exiting ``` -**3. You're recyclable:** -Your work is in the queue. The Witness knows you're done. -Your sandbox can be cleaned up - all work is pushed to origin. +**What happens next (not your concern):** +- Refinery processes your MR from the queue +- Refinery rebases and merges to main +- Refinery closes the issue +- If conflicts: Refinery spawns a FRESH polecat to re-implement -If you have context remaining, you may: -- Pick up new work from `bd ready` -- Or use `gt handoff` to cycle to a fresh session +You are NOT involved in any of that. You're gone. Done means gone. -If the Refinery needs conflict resolution, it will dispatch a fresh polecat. -You do NOT need to wait around. - -**Exit criteria:** MR submitted, Witness notified, polecat recyclable.""" +**Exit criteria:** Work submitted, sandbox nuked, session exited.""" [vars] [vars.issue] diff --git a/templates/polecat-CLAUDE.md b/templates/polecat-CLAUDE.md index 1bbf340b..debac2f3 100644 --- a/templates/polecat-CLAUDE.md +++ b/templates/polecat-CLAUDE.md @@ -46,8 +46,16 @@ pinned molecule (steps poured from `mol-polecat-work`) and signal completion to You: 1. Receive work via your hook (pinned molecule + issue) 2. Work through molecule steps using `bd ready` / `bd close ` -3. Signal completion and exit (`gt done --exit`) -4. Witness handles cleanup, Refinery merges +3. Complete and self-clean (`gt done`) - you exit AND nuke yourself +4. Refinery merges your work from the MQ + +**Self-cleaning model:** When you run `gt done`, you: +- Push your branch to origin +- Submit work to the merge queue +- Nuke your own sandbox and session +- Exit immediately + +There is no idle state. Done means gone. **Important:** Your molecule already has step beads. Use `bd ready` to find them. Do NOT read formula files directly - formulas are templates, not instructions. @@ -150,17 +158,18 @@ When your work is done, follow this EXACT checklist: [ ] 1. Tests pass: go test ./... [ ] 2. Commit changes: git add && git commit -m "msg (issue-id)" [ ] 3. Sync beads: bd sync -[ ] 4. Exit session: gt done --exit +[ ] 4. Self-clean: gt done ``` -**Note**: No push needed - your branch stays local. Refinery accesses it -via shared .repo.git and merges to main. +The `gt done` command (self-cleaning): +- Pushes your branch to origin +- Creates a merge request bead in the MQ +- Nukes your sandbox (worktree cleanup) +- Exits your session immediately -The `gt done --exit` command: -- Creates a merge request bead -- Notifies the Witness -- Exits your session immediately (no idle waiting) -- Witness handles cleanup, Refinery merges your branch +**You are gone after `gt done`.** No idle waiting. The Refinery will merge +your work from the MQ. If conflicts arise, a fresh polecat re-implements - +work is never sent back to you (you don't exist anymore). ### No PRs in Maintainer Repos