@weldr/runr 0.3.1 → 0.7.2

package/CHANGELOG.md

@@ -7,6 +7,152 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-01-06
+
+**Hybrid Workflow Foundation** - Productivity + Auditability together.
+
+### Added
+
+- **runr intervene** - Record manual work with provenance
+  - SHA anchoring with `--since` for retroactive attribution
+  - Commit linking with `--commit` and `--amend-last`
+  - Command output capture with redaction
+  - Flow/Ledger mode awareness
+
+- **runr audit** - View project history by classification
+  - Classifications: CHECKPOINT, INTERVENTION, INFERRED, ATTRIBUTED, GAP
+  - Coverage reporting with `--coverage`
+  - CI thresholds with `--fail-under` and `--fail-under-with-inferred`
+  - Strict mode with `--strict`
+
+- **runr mode** - Switch between Flow and Ledger modes
+  - Flow mode: productivity-first, flexible interventions
+  - Ledger mode: audit-first, stricter controls
+
+- **Redaction** - Automatic secret removal from receipts
+  - Detects tokens, API keys, passwords, credentials
+  - Pattern-based with configurable behavior
+
+- **Review Loop Diagnostics** - Actionable guidance when runs stop
+  - Explains why review loops were detected
+  - Suggests specific fixes based on timeline analysis
+  - Identifies unmet verification requirements
+
+- **Inferred Attribution** - Reduce audit gaps automatically
+  - Commits within intervention SHA ranges classified as inferred
+  - Both explicit and inferred coverage tracked
+
+### Changed
+
+- Intervention receipts now include SHA anchors (base_sha, head_sha)
+- Audit shows dual coverage: explicit vs with-inferred
+- Config schema extended for receipts and workflow mode
+
+### Documentation
+
+- New: Hybrid Workflow Guide (`docs/hybrid-workflow-guide.md`)
+- New: Intervention Patterns (`docs/examples/intervention-patterns.md`)
+
+## [0.6.0] - 2026-01-06
+
+**Meta-Agent UX Sprint** — Smoother onboarding and smarter defaults.
+
+### Added
+
+- **Runr Meta-Agent**: Built-in `runr meta` helper for agent workflow guidance
+- **Claude Auto-Setup**: `--with-claude` flag wires CLAUDE.md scaffolding during init
+- **Claude Templates**: `.claude/` template library for repeatable agent prompts
+- **Enhanced Doctor**: Deeper diagnostics and clearer remediation in `runr doctor`
+
+## [0.5.0] - 2026-01-05
+
+**Solo Workflow** — Effortless dev→main checkpoints with automated safety.
+
+### Added
+
+- **Workflow System**: Three profiles (solo/pr/trunk) with bundle→submit integration
+  - `runr bundle <run_id>` — Generate deterministic markdown evidence packet
+  - `runr submit <run_id> --to <branch>` — Cherry-pick verified checkpoint to target branch
+  - Submit validation: clean tree, terminal state, verification evidence required
+  - Conflict handling: clean abort with diagnostic timeline event
+  - `--dry-run` mode for safe preview before integration
+
+- **Workflow Packs**: One-command scaffolding for complete workflow setup
+  - `runr init --pack solo` — Dev branch workflow (dev → main, no PR)
+  - `runr init --pack trunk` — Trunk-based development (main only)
+  - `runr init --pack pr` — Pull request workflow (feature → main via PR)
+  - `runr packs` — List available packs
+  - Auto-generated `AGENTS.md` and `CLAUDE.md` with workflow-specific guidance
+  - Pack templates with variable substitution (project name, verification commands, branches)
+
+- **Auto .gitignore Setup**: Packs automatically add runtime artifact entries
+  - `.runr/runs/` (runtime state)
+  - `.runr-worktrees/` (isolated worktrees)
+  - `.runr/orchestrations/` (orchestration artifacts)
+  - Keeps `.runr/runr.config.json` and `.runr/tasks/*.md` tracked
+
+- **Meta-Agent Safety Contract**: Behavioral guardrails for agents driving Runr
+  - Rule 1: Never delete on dirty tree
+  - Rule 2: Never delete outside `.runr/` without explicit file list
+  - Rule 3: Must end with bundle + dry-run
+  - Embedded in pack templates (`CLAUDE.md`)
+
+- **90-Second Demo**: `dogfood/hello-world/` minimal example
+  - Complete walkthrough in README
+  - Shows full workflow: init → run → bundle → submit
+  - Pre-initialized with solo pack
+
+### Documentation
+
+- **Solo Workflow Example**: Canonical copy-paste reference ([docs/examples/solo-workflow.md](docs/examples/solo-workflow.md))
+  - Complete 6-step workflow loop
+  - Meta-agent integration patterns (Mode A/B)
+  - .gitignore policy explained
+  - Troubleshooting section
+  - Quick reference card
+
+- **Comprehensive Documentation Overhaul**:
+  - [Workflow Guide](docs/workflow-guide.md) — Bundle/submit/integration workflows
+  - [Packs User Guide](docs/packs-user-guide.md) — Choosing and using packs
+  - [Safety Guide](docs/safety-guide.md) — All guard mechanisms documented
+  - Updated [CLI Reference](docs/cli.md) with bundle/submit/packs commands
+  - Updated [Configuration](docs/configuration.md) with workflow config section
+
+### Changed
+
+- `runr init` with pack now creates workflow-ready project instead of minimal config
+- Pack templates replace legacy example task files
+- README.md now features 90-second demo and solo workflow reference
+
+### Fixed
+
+- Documentation gaps: bundle/submit/packs were shipped but undocumented
+- Legacy `.agent/` references throughout documentation
+- Missing .gitignore guidance caused confusion about what to commit
+
+## [0.4.0] - 2026-01-03
+
+**Case Files** — Every run leaves a machine-readable journal.
+
+### Added
+
+- **Case Files**: Auto-generated `journal.md` + `journal.json` for every run
+  - Schema v1.0 with immutable facts (timestamps, milestones, verification attempts)
+  - Living data (append-only notes)
+  - Secret redaction in error excerpts
+  - Warnings array captures all extraction issues
+- **CLI Commands**:
+  - `runr journal [run_id]` — Generate and display journal (defaults to latest)
+  - `runr note <message> [--run-id]` — Add timestamped note (defaults to latest)
+  - `runr open [run_id]` — Open journal in $EDITOR (defaults to latest)
+- **Auto-generation**: Journals written on run completion (stop or finish)
+- **Non-interactive safety**: `runr open` fails cleanly in CI or when $EDITOR unset
+
+### Fixed
+
+- **Package bloat**: Excluded test files from npm package (81 → 69 files)
+- **Deprecation warnings**: Replaced deprecated `getRunsRoot()` with `getRunrPaths().runs_dir`
+
 ## [0.3.0] - 2026-01-01
 
 **Renamed to Runr.** New identity, same reliability-first mission.
@@ -208,7 +354,10 @@ Initial stable release with full dual-LLM orchestration and autonomy features.
 - Worktree strategy documentation
 - CLI reference
 
-[Unreleased]: https://github.com/vonwao/runr/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/vonwao/runr/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/vonwao/runr/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/vonwao/runr/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/vonwao/runr/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/vonwao/runr/compare/v0.2.2...v0.3.0
 [0.2.2]: https://github.com/vonwao/runr/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/vonwao/runr/compare/v0.2.0...v0.2.1

package/README.md

@@ -1,27 +1,80 @@
 # Runr
 
-**Stop losing 30 minutes when the agent derails.**
+> Autopilot for AI-driven dev work: run tasks end-to-end, and when something breaks, stop cleanly with the next 3 best actions.
 
 ![Failure Recovery](demo/failure-checkpoint.gif)
 
-*When verification fails after 3 checkpoints, progress isn't lost — Runr saves verified work as git commits.*
+## Try it (2 minutes)
 
-## Quickstart
+```bash
+npm install -g @weldr/runr
+runr init --demo
+cd runr-demo
+npm install
+
+# Task 1: success
+runr run --task .runr/tasks/00-success.md
+runr report latest
+
+# Task 2: failure + recovery
+runr run --task .runr/tasks/01-intentional-fail.md
+runr                 # shows STOPPED + 3 next actions
+runr continue
+runr report latest
+
+# Task 3: scope guard (expected to stop)
+runr run --task .runr/tasks/02-scope-violation.md
+# STOPPED: scope guard. Runr tells you what to do.
+```
+
+The demo creates a self-contained TypeScript project with three tasks: success, a failure that stops with next actions (then `continue`), and a scope guard stop.
+
+**Runr is language-agnostic.** The demo is JS/TS because it's the fastest proof. Other languages work by swapping verification commands (e.g., `pytest -q` for Python, `go test ./...` for Go).
+
+---
+
+## In your own repo
 
 ```bash
 npm install -g @weldr/runr
-cd your-repo
-runr init
-runr run --task .runr/tasks/your-task.md --worktree
+runr init --pack solo
+
+# Start work
+runr run --task .runr/tasks/example-task.md
+
+# If it stops, do the obvious next thing
+runr continue
+
+# Inspect what happened
+runr report latest
 ```
 
-**If it stops:** Run the suggested command in `.runr/runs/<run_id>/handoffs/stop.json`
+## What happens when it fails
+
+Runr doesn't "keep going and hope." It stops with receipts and 3 next actions you can trust:
+
+- **continue** — auto-fix what's safe, then resume
+- **report** — open the run receipt: diffs + logs + timeline
+- **intervene** — record manual fixes so they don't become black holes
+
+That's the whole UX: keep momentum, keep receipts, never lose your place.
 
-![Next Action](demo/next-action.gif)
+## The mental model
 
-*Runr writes a stop handoff so agents know exactly what to do next — no guessing, no hallucinating.*
+- **Autopilot:** run work in milestones with phase gates (plan → implement → verify → review)
+- **Recovery:** save checkpoints so you can resume from the last verified state
+- **Runs:** capture diffs, verification logs, and interventions automatically
 
-## How It Works
+## Quick links
+
+- [Why Runr?](docs/why-runr.md)
+- [Hybrid Workflow](docs/hybrid-workflow-guide.md)
+- [CLI Reference](docs/cli.md)
+- [Configuration](docs/configuration.md)
+
+---
+
+## How it works
 
 Runr orchestrates AI workers through phase gates with checkpoints:
 
@@ -30,93 +83,72 @@ PLAN → IMPLEMENT → VERIFY → REVIEW → CHECKPOINT → done
          ↑___________|  (retry if verification fails)
 ```
 
-- **Phase gates** — Agent can't skip verification or claim false success
-- **Checkpoints** — Verified milestones saved as git commits
-- **Stop handoffs** — Structured diagnostics with next actions
-- **Scope guards** — Files outside scope are protected
+- **Phase gates:** the agent can't skip verification or claim false success
+- **Checkpoints:** verified milestones are saved as git commits
+- **Stop handoffs:** structured diagnostics with next actions
+- **Scope guards:** files outside scope are protected
 
-> **Status**: v0.3.0 — Renamed from `agent-runner`. Early, opinionated, evolving.
+> **Status**: v0.7.x — Hybrid workflow with provenance tracking. Early, opinionated, evolving.
 
-## Meta-Agent Quickstart (Recommended)
-
-**The easiest way to use Runr:** Let your coding agent drive it.
-
-Runr works as a **reliable execution backend**. Instead of learning CLI commands, your agent (Claude Code, Codex, etc.) operates Runr for you — handling runs, interpreting failures, and resuming from checkpoints.
+---
 
-### Setup (One-Time)
+## Try it: Hello World
 
 ```bash
-# 1. Install Runr
-npm install -g @weldr/runr
-
-# 2. Verify environment
-runr doctor
-
-# 3. Create minimal config
-mkdir -p .runr/tasks
-cat > .runr/runr.config.json << 'EOF'
-{
-  "agent": { "name": "my-project", "version": "1" },
-  "scope": {
-    "presets": ["typescript", "vitest"]
-  },
-  "verification": {
-    "tier0": ["npm run typecheck"],
-    "tier1": ["npm test"]
-  }
-}
-EOF
+cd dogfood/hello-world
+npm install
+runr run --task .runr/tasks/add-farewell.md --worktree
 ```
 
-### Usage
+Complete walkthrough in [dogfood/hello-world/README.md](dogfood/hello-world/README.md).
 
-Just tell your coding agent:
+---
+
+## Meta-Agent Mode
 
-> "Use Runr to add user authentication with OAuth2. Create checkpoints after each milestone."
+**The easiest way to use Runr:** one command, zero ceremony.
 
-The agent will:
-1. Create a task file (`.runr/tasks/add-auth.md`)
-2. Run `runr run --task ... --worktree`
-3. Monitor progress with `runr status`
-4. Handle failures, resume from checkpoints
-5. Report results with commit links
+Best for: longer tasks, multiple milestones, and hands-off recovery.
 
-**See [RUNR_OPERATOR.md](./RUNR_OPERATOR.md)** for the complete agent integration guide.
+Runr works as a **reliable execution backend** for meta-agents (Claude Code, Codex CLI). The meta-agent operates Runr for you — handling runs, interpreting failures, and resuming from checkpoints.
 
-### Why This Works
+```bash
+# Initialize with Claude Code integration
+runr init --pack solo --with-claude
 
-Most devs already have a coding agent open. Telling them:
-- "Drop this in your agent, and it'll drive Runr for you"
+# Launch meta-agent with workflow context
+runr meta
+```
 
-…has near-zero friction compared to:
-- "Learn these CLI commands, create config files, understand phase gates"
+The agent will automatically:
+- Follow workflow rules from `AGENTS.md`
+- Use safety playbooks from `.claude/skills/runr-workflow`
+- Have `/runr-bundle`, `/runr-submit`, `/runr-resume` slash commands available
 
-The agent becomes your operator. Runr stays the reliable execution layer.
+Tip: start from a clean tree. `runr meta` blocks if you have uncommitted changes.
 
 ---
 
-## Quick Start (Direct CLI)
+## Direct CLI Usage
+
+Tip: start from a clean tree (commit or stash first).
 
 ```bash
 # Install
 npm install -g @weldr/runr
 
-# Initialize in your project
+# Initialize
 cd /your/project
-runr init
+runr init --pack solo
 
 # Run a task
 runr run --task .runr/tasks/example-feature.md --worktree
 
-# If it fails, resume from last checkpoint
-runr resume <run_id>
-
-# Get machine-readable diagnostics
-runr summarize <run_id>
-# Output: .runr/runs/<run_id>/handoffs/stop.json
+# Submit verified checkpoint
+runr submit <run_id> --to dev
 ```
 
-> Prefer source install? See [Development](#development).
+---
 
 ## Configuration
 
@@ -132,13 +164,15 @@ Create `.runr/runr.config.json`:
   },
   "verification": {
     "tier0": ["npm run typecheck"],
-    "tier1": ["npm run build"],
-    "tier2": ["npm test"]
+    "tier1": ["npm test"],
+    "tier2": ["npm run build"]
   }
 }
 ```
 
-### Scope Presets
+Tiers run from fast → slow. Keep `tier0` as a quick sanity check.
+
+### Scope presets
 
 Don't write patterns by hand:
 
@@ -152,30 +186,25 @@ Don't write patterns by hand:
 
 Available: `nextjs`, `react`, `drizzle`, `prisma`, `vitest`, `jest`, `playwright`, `typescript`, `tailwind`, `eslint`, `env`
 
+---
+
 ## CLI Reference
 
 | Command | What it does |
 |---------|--------------|
-| `runr init` | Initialize config (auto-detect verify commands) |
+| `runr` | Show status and next actions |
 | `runr run --task <file>` | Start a task |
-| `runr resume <id>` | Continue from checkpoint |
-| `runr watch <id> --auto-resume` | Watch run + auto-resume on failure |
-| `runr status [id]` | Show run state |
-| `runr follow [id]` | Tail run progress |
-| `runr report <id>` | Generate run report (includes next_action) |
-| `runr gc` | Clean up old runs |
-| `runr doctor` | Check environment |
+| `runr continue` | Do the next obvious thing |
+| `runr report <id>` | View run receipt: diffs, logs, timeline |
+| `runr resume <id>` | Resume from checkpoint |
+| `runr intervene <id>` | Record manual work |
+| `runr submit <id> --to <branch>` | Submit verified checkpoint |
+| `runr meta` | Launch meta-agent with workflow context |
+| `runr init` | Initialize Runr in a repo |
+| `runr runs bundle <id>` | Generate evidence bundle |
+| `runr tools doctor` | Check environment health |
 
-### Aliases
-
-Same functionality, different vibe:
-
-```bash
-runr summon --task task.md   # run
-runr resurrect <id>          # resume
-runr scry <id>               # status
-runr banish                  # gc
-```
+---
 
 ## Task Files
 
@@ -197,6 +226,8 @@ OAuth2 login with Google.
 - Session persists across refreshes
 ```
 
+---
+
 ## Stop Reasons
 
 When Runr stops, it tells you why:
@@ -209,7 +240,9 @@ When Runr stops, it tells you why:
 | `review_loop_detected` | Reviewer kept requesting same changes |
 | `time_budget_exceeded` | Ran out of time |
 
-Every stop produces `stop.json` + `stop.md` with diagnostics.
+Every stop produces structured diagnostics with next actions.
+
+---
 
 ## Philosophy
 
@@ -221,15 +254,7 @@ This isn't a code generator. It orchestrates generators.
 
 Agents lie. Logs don't. If it can't prove it, it didn't do it.
 
-## Migrating from agent-runner
-
-| Old | New |
-|-----|-----|
-| `agent` CLI | `runr` CLI |
-| `.agent/` directory | `.runr/` directory |
-| `agent.config.json` | `runr.config.json` |
-| `.agent-worktrees/` | `.runr-worktrees/` |
-Old paths still work for now, with deprecation warnings.
+---
 
 ## Development
 
@@ -239,18 +264,6 @@ npm test         # run tests
 npm run dev -- run --task task.md  # run from source
 ```
 
-## Release History
-
-| Version | Date | Highlights |
-|---------|------|------------|
-| v0.3.0 | **Renamed to Runr**, new CLI, new directory structure |
-| v0.2.2 | Worktree location fix, guard diagnostics |
-| v0.2.1 | Scope presets, review digest |
-| v0.2.0 | Review loop detection |
-| v0.1.0 | Initial stable release |
-
-See [CHANGELOG.md](CHANGELOG.md) for details.
-
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).
@@ -261,4 +274,4 @@ Apache 2.0 — See [LICENSE](LICENSE).
 
 ---
 
-<sub>Existence is pain, but shipping is relief.</sub>
+<sub>Shipping beats rerunning the same milestone twice.</sub>