@weldr/runr 0.4.0 → 0.7.3

package/packs/pr/templates/CLAUDE.md.tmpl

@@ -0,0 +1,101 @@
+# Claude Code Integration
+
+This project uses Runr with Claude Code for agent tasks.
+
+## Quick Start
+
+1. Create feature branch: `git checkout -b feature/your-feature`
+2. Create task: `.runr/tasks/your-task.md`
+3. Run: `runr run --task .runr/tasks/your-task.md --worktree`
+4. Bundle: `runr bundle <run_id>`
+5. Create PR: `gh pr create --title "..." --body-file .runr/runs/<run_id>/bundle.md`
+
+**PR workflow is the happy path.** Proof packets make reviews faster.
+
+## How Runr Works with Claude
+
+Runr orchestrates Claude through a phase-gated workflow:
+
+1. **Plan**: Claude reads the task and plans implementation
+2. **Implement**: Worker executes the plan, making changes
+3. **Review**: Claude reviews changes against requirements
+4. **Verify**: Runr runs verification commands
+5. **Checkpoint**: If verified, create checkpoint with evidence
+
+## Configuration
+
+See `.runr/runr.config.json` for:
+
+- Worker configuration (Claude/Codex)
+- Phase assignments
+- Verification tiers
+- Scope and file patterns
+
+## Determinism & Safety Are Sacred (Non-Negotiables)
+
+These invariants are enforced by wrappers:
+
+**P0-1 Determinism (bundle):**
+- Same run_id → identical markdown output
+- Quick check: `runr bundle <id> > /tmp/a && runr bundle <id> > /tmp/b && diff /tmp/a /tmp/b`
+
+**P0-2 Dry-run safety (submit):**
+- `submit --dry-run` changes **nothing**: no branch change, no file changes, no new timeline events
+- Quick check: capture branch + status + timeline lines before/after
+
+**P0-3 Recovery (submit):**
+- Submit always restores starting branch, even on failure
+- Quick check: run forced failure, confirm branch restored
+
+**If anything violates P0 → stop and add regression test immediately.**
+
+## Concrete Commands (Copy-Paste)
+
+**Bundle proof packet:**
+```bash
+runr bundle <run_id> --output .runr/runs/<run_id>/bundle.md
+```
+
+**Create PR with proof packet:**
+```bash
+# Push feature branch
+git push -u origin feature/your-feature
+
+# Create PR with bundle as description
+gh pr create --title "Feature: X" --body-file .runr/runs/<run_id>/bundle.md
+```
+
+## What To Do When Things Go Wrong
+
+**PR conflicts:**
+- Expect: Merge conflicts when PR is merged
+- Check: GitHub PR conflict UI
+- Resolve: Rebase feature branch on main, force push
+
+**Validation fails:**
+- Expect: Can't create verified checkpoint
+- Check: Runr output for specific validation reason
+- Resolve: Fix issues, re-run verification
+
+**Any P0 violation:**
+- Stop immediately
+- Add regression test to prevent recurrence
+- Escalate to project maintainers
+
+## Tips for Claude
+
+- Always verify incrementally during implementation
+- If verification fails, fix issues before review
+- Keep changes focused on task requirements
+- Use verification results to guide decisions
+
+## Workflow: PR
+
+This project uses the **PR** pack:
+
+- Integration branch: `{{integration_branch}}` (where PRs merge to)
+- Feature branches: Create your own (e.g., `feature/add-x`)
+- Requires verification: Yes
+- Requires clean tree: Yes
+
+Only verified checkpoints should be pushed to feature branches for PR review.

package/packs/pr/templates/bundle.md.tmpl

@@ -0,0 +1,27 @@
+# Change Bundle: {{checkpoint_id}}
+
+## Summary
+
+**Task**: {{task_name}}
+**Checkpoint**: {{checkpoint_id}}
+**Timestamp**: {{timestamp}}
+
+## Changes
+
+{{changes_summary}}
+
+## Verification Evidence
+
+{{verification_evidence}}
+
+## Review Notes
+
+{{review_notes}}
+
+## Files Modified
+
+{{files_modified}}
+
+---
+
+Generated by Runr ({{pack_name}} workflow)

package/packs/solo/pack.json

@@ -0,0 +1,82 @@
+{
+  "pack_version": 1,
+  "name": "solo",
+  "display_name": "Solo Dev (dev → main, no PR)",
+  "description": "Fast local workflow with verified checkpoints, cherry-pick submit, and minimal docs.",
+  "defaults": {
+    "profile": "solo",
+    "integration_branch": "dev",
+    "release_branch": "main",
+    "submit_strategy": "cherry-pick",
+    "require_clean_tree": true,
+    "require_verification": true,
+    "protected_branches": ["main"]
+  },
+  "templates": {
+    "AGENTS.md": "templates/AGENTS.md.tmpl",
+    "CLAUDE.md": "templates/CLAUDE.md.tmpl",
+    "bundle.md": "templates/bundle.md.tmpl",
+    "claude-skill": "templates/claude-skill.md.tmpl",
+    "claude-cmd-bundle": "templates/claude-cmd-bundle.md.tmpl",
+    "claude-cmd-submit": "templates/claude-cmd-submit.md.tmpl",
+    "claude-cmd-resume": "templates/claude-cmd-resume.md.tmpl"
+  },
+  "init_actions": [
+    {
+      "type": "ensure_gitignore_entry",
+      "path": ".gitignore",
+      "line": ".runr/runs/"
+    },
+    {
+      "type": "ensure_gitignore_entry",
+      "path": ".gitignore",
+      "line": ".runr-worktrees/"
+    },
+    {
+      "type": "ensure_gitignore_entry",
+      "path": ".gitignore",
+      "line": ".runr/orchestrations/"
+    },
+    {
+      "type": "create_file_if_missing",
+      "path": "AGENTS.md",
+      "template": "AGENTS.md",
+      "mode": "0644"
+    },
+    {
+      "type": "create_file_if_missing",
+      "path": "CLAUDE.md",
+      "template": "CLAUDE.md",
+      "mode": "0644",
+      "when": { "flag": "with_claude" }
+    },
+    {
+      "type": "create_file_if_missing",
+      "path": ".claude/skills/runr-workflow/SKILL.md",
+      "template": "claude-skill",
+      "mode": "0644",
+      "when": { "flag": "with_claude" }
+    },
+    {
+      "type": "create_file_if_missing",
+      "path": ".claude/commands/runr-bundle.md",
+      "template": "claude-cmd-bundle",
+      "mode": "0644",
+      "when": { "flag": "with_claude" }
+    },
+    {
+      "type": "create_file_if_missing",
+      "path": ".claude/commands/runr-submit.md",
+      "template": "claude-cmd-submit",
+      "mode": "0644",
+      "when": { "flag": "with_claude" }
+    },
+    {
+      "type": "create_file_if_missing",
+      "path": ".claude/commands/runr-resume.md",
+      "template": "claude-cmd-resume",
+      "mode": "0644",
+      "when": { "flag": "with_claude" }
+    }
+  ]
+}

package/packs/solo/templates/AGENTS.md.tmpl

@@ -0,0 +1,80 @@
+# Agent Development Guide
+
+## Project: {{project_name}}
+
+{{project_about}}
+
+## Workflow: Solo Dev (dev → main)
+
+This project uses the **solo** workflow:
+
+- **All work lands on `dev`** (or feature branches)
+- Runr creates verified checkpoints with full test evidence
+- Submit verified changes to `main` via: **bundle → dry-run → submit → (git push)**
+- **Use wrappers, not manual steps**
+
+**Key principle**: Only trustable, verified changes land on `main`.
+
+## Verification Requirements
+
+All checkpoints must pass verification before submit:
+
+{{verification_commands}}
+
+## Working with Runr
+
+### Create a verified checkpoint
+
+```bash
+runr run --task .runr/tasks/my-task.md --worktree
+```
+
+This creates a checkpoint with full verification evidence.
+
+### Submit verified changes to main
+
+**Preferred (uses wrapper for safety):**
+```bash
+./scripts/dogfood-submit.sh <checkpoint-id> --to main
+```
+
+**Manual (escape hatch only):**
+```bash
+runr submit <checkpoint-id> --to main
+```
+
+Both cherry-pick the verified checkpoint to `main` (requires clean tree + verification evidence).
+
+### View bundle/evidence
+
+```bash
+runr bundle <checkpoint-id> --output /tmp/bundle-<checkpoint-id>.md
+```
+
+Shows the complete change bundle with verification results.
+
+## Guidelines for Agents
+
+1. **Read first**: Always read files before modifying
+2. **Verify incrementally**: Don't wait until the end to verify
+3. **Keep changes focused**: Smaller checkpoints are easier to review and submit
+4. **Trust verification**: If verification passes, the change is trustable
+5. **Document decisions**: Update this file or task files with important context
+
+## Integration Safety Rules
+
+**When to use wrapper vs manual:**
+- **Wrapper (preferred):** If your project has a submit wrapper script, use it for automated safety checks
+- **Manual (escape hatch):** Use `runr submit` directly for quick iterations or when no wrapper exists
+
+**If any invariant breaks during submit:**
+- Stop immediately
+- Add regression test to prevent recurrence
+- Fix the invariant violation before continuing
+
+**Optional friction logging:**
+- If something costs >2 minutes or happens twice, consider logging it for team discussion
+
+## Project Structure
+
+See the existing codebase for structure. Runr automatically detects verification commands from your project setup.

package/packs/solo/templates/CLAUDE.md.tmpl

@@ -0,0 +1,126 @@
+# Claude Code Integration
+
+This project uses Runr with Claude Code for agent tasks.
+
+## Quick Start
+
+1. Ensure Claude Code is installed and configured
+2. Create tasks in `.runr/tasks/`
+3. Run: `runr run --task .runr/tasks/your-task.md --worktree`
+4. Submit: `runr submit <run_id> --to {{integration_branch}}`
+
+**Runr-native workflow is the happy path.** Manual cherry-pick is the escape hatch only.
+
+**Tip:** If your project has a submit wrapper (e.g., `./scripts/submit-wrapper.sh`), use that instead for automated safety checks.
+
+## How Runr Works with Claude
+
+Runr orchestrates Claude through a phase-gated workflow:
+
+1. **Plan**: Claude reads the task and plans implementation
+2. **Implement**: Worker executes the plan, making changes
+3. **Review**: Claude reviews changes against requirements
+4. **Verify**: Runr runs verification commands
+5. **Checkpoint**: If verified, create checkpoint with evidence
+
+## Configuration
+
+See `.runr/runr.config.json` for:
+
+- Worker configuration (Claude/Codex)
+- Phase assignments
+- Verification tiers
+- Scope and file patterns
+
+## Determinism & Safety Are Sacred (Non-Negotiables)
+
+These invariants are enforced by wrappers:
+
+**P0-1 Determinism (bundle):**
+- Same run_id → identical markdown output
+- Quick check: `runr bundle <id> > /tmp/a && runr bundle <id> > /tmp/b && diff /tmp/a /tmp/b`
+
+**P0-2 Dry-run safety (submit):**
+- `submit --dry-run` changes **nothing**: no branch change, no file changes, no new timeline events
+- Quick check: capture branch + status + timeline lines before/after
+
+**P0-3 Recovery (submit):**
+- Submit always restores starting branch, even on failure
+- Quick check: run forced failure, confirm branch restored
+
+**If anything violates P0 → stop and add regression test immediately.**
+
+## Concrete Commands (Copy-Paste)
+
+**Bundle evidence:**
+```bash
+runr bundle <run_id> --output /tmp/bundle-<run_id>.md
+```
+
+**Submit to integration branch:**
+```bash
+runr submit <run_id> --to {{integration_branch}}
+```
+
+**Dry-run first (recommended):**
+```bash
+runr submit <run_id> --to {{integration_branch}} --dry-run
+```
+
+## What To Do When Things Go Wrong
+
+**Submit conflict:**
+- Expect: `submit_conflict` event written + clean tree + branch restored
+- Check: timeline.jsonl for conflicted files list
+- Resolve: manual cherry-pick or rebase checkpoint
+
+**Validation fails:**
+- Expect: `submit_validation_failed` event written, **no git mutations**
+- Check: error message for specific validation reason (dirty_tree, verification_missing, etc.)
+- Resolve: fix validation issue, retry submit
+
+**Any P0 violation:**
+- Stop immediately
+- Add regression test to prevent recurrence
+- Escalate to project maintainers
+
+## Tips for Claude
+
+- Always verify incrementally during implementation
+- If verification fails, fix issues before review
+- Keep changes focused on task requirements
+- Use verification results to guide decisions
+
+## Meta-Agent Safety Contract
+
+If you are a meta-agent driving Runr workflows, you MUST obey these rules:
+
+**Rule 1: Never delete on dirty tree**
+- Before any file deletion, check: `git status --porcelain`
+- If output is non-empty, refuse deletion with: "Working tree has uncommitted changes. Commit or stash before deletion."
+
+**Rule 2: Never delete outside `.runr/` without explicit file list**
+- If asked to "clean up" or "remove files", respond: "I can only safely delete files within `.runr/` directory. For project files, provide explicit file list."
+- Never assume what "cleanup" means
+
+**Rule 3: Must end with bundle + dry-run**
+- Every task execution must end with:
+  ```bash
+  runr bundle <run_id> --output /tmp/bundle-<run_id>.md
+  runr submit <run_id> --to {{integration_branch}} --dry-run
+  runr submit <run_id> --to {{integration_branch}}
+  ```
+- Generate review artifact even if coding manually
+
+**Violation of any rule = stop and ask user for clarification.**
+
+## Workflow: {{pack_name}}
+
+This project uses the **{{pack_name}}** pack:
+
+- Integration branch: `{{integration_branch}}`
+- Release branch: `{{release_branch}}`
+- Requires verification: Yes
+- Requires clean tree: Yes
+
+Only verified checkpoints can be submitted to production branches.

package/packs/solo/templates/bundle.md.tmpl

@@ -0,0 +1,27 @@
+# Change Bundle: {{checkpoint_id}}
+
+## Summary
+
+**Task**: {{task_name}}
+**Checkpoint**: {{checkpoint_id}}
+**Timestamp**: {{timestamp}}
+
+## Changes
+
+{{changes_summary}}
+
+## Verification Evidence
+
+{{verification_evidence}}
+
+## Review Notes
+
+{{review_notes}}
+
+## Files Modified
+
+{{files_modified}}
+
+---
+
+Generated by Runr ({{pack_name}} workflow)

package/packs/solo/templates/claude-cmd-bundle.md.tmpl

@@ -0,0 +1,40 @@
+---
+description: Generate Runr evidence bundle for review
+---
+
+# Bundle Evidence
+
+Generates a deterministic Markdown evidence packet for a Runr run.
+
+## Usage
+
+```bash
+runr bundle <run_id> --output /tmp/bundle-<run_id>.md
+```
+
+## What's in the bundle?
+
+- Checkpoint metadata
+- Milestone progression
+- Verification evidence
+- Diff statistics
+- Timeline summary
+
+## When to use
+
+- Before submitting verified work
+- When debugging why verification failed
+- When providing audit trail to team
+
+## Example
+
+```bash
+# After a successful run
+runr bundle abc123 --output /tmp/bundle-abc123.md
+
+# Review the bundle
+cat /tmp/bundle-abc123.md
+
+# Then proceed to dry-run submit
+runr submit abc123 --to {{integration_branch}} --dry-run
+```

package/packs/solo/templates/claude-cmd-resume.md.tmpl

@@ -0,0 +1,43 @@
+---
+description: Resume Runr run from last checkpoint
+---
+
+# Resume from Checkpoint
+
+Continues a stopped run from its last verified checkpoint.
+
+## Usage
+
+```bash
+runr resume <run_id>
+```
+
+## Options
+
+- `--plan` - Show resume plan without executing
+- `--force` - Resume despite environment fingerprint mismatch
+- `--auto-stash` - Automatically stash uncommitted changes
+
+## When to use
+
+- Verification failed and you fixed the issue
+- Run hit time budget
+- Run stopped due to scope violation
+- Worker timed out or stalled
+
+## Preview before resuming
+
+```bash
+# See what will happen without executing
+runr resume <run_id> --plan
+```
+
+## Auto-resume mode
+
+For transient failures (timeouts, stalls), you can use auto-resume:
+
+```bash
+runr watch <run_id> --auto-resume --max-attempts 3
+```
+
+This will automatically resume when the run stops, up to 3 times.

package/packs/solo/templates/claude-cmd-submit.md.tmpl

@@ -0,0 +1,51 @@
+---
+description: Submit verified checkpoint to integration branch
+---
+
+# Submit Verified Checkpoint
+
+Cherry-picks a verified checkpoint to the integration branch.
+
+## Usage
+
+**Always dry-run first:**
+```bash
+runr submit <run_id> --to {{integration_branch}} --dry-run
+```
+
+**Then submit:**
+```bash
+runr submit <run_id> --to {{integration_branch}}
+```
+
+**Optional: push to origin:**
+```bash
+runr submit <run_id> --to {{integration_branch}} --push
+```
+
+## Requirements
+
+- Checkpoint must exist
+- Verification evidence must be present
+- Working tree must be clean
+- Target branch must exist
+
+## If it fails
+
+Check the error:
+- `dirty_tree` → commit or stash changes
+- `verification_missing` → run wasn't verified
+- `submit_conflict` → manual resolution needed
+- `target_branch_missing` → create branch first
+
+## Recovery
+
+If submit is interrupted, the command always restores your starting branch.
+Check `git status` and retry.
+
+## Workflow
+
+This project uses the **{{pack_name}}** workflow:
+- Integration branch: `{{integration_branch}}`
+- Release branch: `{{release_branch}}`
+- Only verified checkpoints can be submitted

package/packs/solo/templates/claude-skill.md.tmpl

@@ -0,0 +1,96 @@
+---
+name: runr-workflow
+description: Safe, checkpointed Runr workflow - always verify and bundle before finish
+---
+
+# Runr Workflow Skill
+
+You are working in a repository using **Runr** for safe, verified agent work.
+
+## When to Use Runr (Decision Tree)
+
+**REQUIRED - Use `runr run` for:**
+- Any change to `src/**` (code changes)
+- New features or modules
+- Bug fixes
+- Refactoring
+- Anything that needs verification (build/tests)
+
+**OPTIONAL - Direct editing acceptable for:**
+- Documentation only (`docs/**`, `README.md`, `CHANGELOG.md`)
+- Spec files and planning artifacts
+- Config tweaks (`.runr/runr.config.json`)
+- Task file creation (`.runr/tasks/*.md`)
+
+**How to decide:** If it touches code that could break the build or tests, use Runr. If it's just words, direct edit is fine.
+
+## The Runr Loop (For Code Changes)
+
+1. **Create task file** → `.runr/tasks/your-task.md`
+2. **Run** → `runr run --task .runr/tasks/your-task.md --worktree`
+3. **Verify** → Runr handles build + tests automatically
+4. **Checkpoint** → Verified work saved as git commit
+5. **Bundle + Submit** → Evidence packet + integration
+
+## Commands You'll Use
+
+- `runr run --task .runr/tasks/<name>.md --worktree` - Start task
+- `runr status <run_id>` - Check progress
+- `runr resume <run_id>` - Continue from checkpoint
+- `runr bundle <run_id>` - Generate evidence packet
+- `runr submit <run_id> --to {{integration_branch}} --dry-run` - Preview submit
+- `runr submit <run_id> --to {{integration_branch}}` - Submit verified work
+
+## Safety Rules (CRITICAL - Never Violate)
+
+### Rule 1: Never delete on dirty tree
+- Before any file deletion, run: `git status --porcelain`
+- If output is non-empty: **REFUSE** with message:
+  "Working tree has uncommitted changes. Commit or stash before deletion."
+
+### Rule 2: Never delete outside `.runr/` without explicit file list
+- If asked to "clean up" or "remove files", respond:
+  "I can only safely delete files within `.runr/` directory.
+   For project files, provide explicit file list."
+- **Never assume** what "cleanup" means
+
+### Rule 3: Must end with bundle + dry-run
+Every task must end with:
+```bash
+runr bundle <run_id> --output /tmp/bundle.md
+runr submit <run_id> --to {{integration_branch}} --dry-run
+# Review dry-run output
+runr submit <run_id> --to {{integration_branch}}
+```
+
+### Rule 4: Trust verification, not promises
+- Verification passed = trustable change
+- No verification = not trustable
+- Never claim "tests passed" without evidence
+
+## When Things Go Wrong
+
+### Verification fails
+1. Read the error output carefully
+2. Fix the specific issue
+3. Re-verify
+4. Don't move to next milestone until verification passes
+
+### Scope violation
+1. Stop immediately
+2. Run `runr bundle <run_id>`
+3. Explain what file was outside scope
+4. Ask user to adjust scope or task
+
+### Submit conflict
+1. Expect `submit_conflict` event
+2. Check timeline.jsonl for conflicted files
+3. Inform user - they must resolve manually
+
+## Evidence Discipline
+
+- Always paste command outputs, don't paraphrase
+- If verification fails, show the error in full
+- Bundle contains the audit trail - use it
+
+**Violation of any safety rule = stop and ask user for clarification.**