feat: add clawpatch operating loop surfaces

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## 0.3.1 - Unreleased
 
+- Added `clawpatch ci` to initialize, map, review, write a report, and append a GitHub Actions step summary in one CI-friendly command.
+- Added `clawpatch open-pr --patch <id>` to turn an applied patch attempt into an explicit GitHub pull request.
+- Added review prompt provenance and budget accounting for included files, omitted files, prompt bytes, and approximate tokens.
+- Hardened review ingestion so provider findings must cite included files with valid line ranges and matching evidence quotes.
+- Fixed `clawpatch open-pr` so repositories without default-branch metadata use a dedicated patch branch and let GitHub choose the PR base.
+- Fixed `clawpatch open-pr` retries to push the recorded patch commit instead of any later local branch tip.
+- Fixed first-time `clawpatch open-pr` branch creation to start from the recorded patch base.
+- Fixed command execution so providers that exit before reading stdin do not surface benign `EPIPE` errors.
+- Fixed `clawpatch ci --since` empty-review output so it reports `reviewed: 0`.
 - Improved OpenCode malformed JSON diagnostics with output length, event kinds, and a bounded preview, thanks @rohitjavvadi.
 - Fixed Express route mapping for aliased Router imports that follow block comment banners, thanks @rohitjavvadi.
 - Fixed Bun package-manager detection to recognize the text `bun.lock` lockfile, thanks @austinm911.

README.md

@@ -31,11 +31,13 @@ clawpatch init
 clawpatch map
 clawpatch review --limit 3 --jobs 3
 clawpatch review --mode deslopify --limit 3
+clawpatch ci --since origin/main --output clawpatch-report.md
 clawpatch report
 clawpatch next
 clawpatch show --finding <id>
 clawpatch triage --finding <id> --status false-positive --note "covered by tests"
 clawpatch fix --finding <id>
+clawpatch open-pr --patch <patchAttemptId> --draft
 clawpatch revalidate --finding <id>
 clawpatch revalidate --all --status open
 ```
@@ -122,11 +124,13 @@ Supported provider names today:
 - `clawpatch status`: show project, dirty state, feature/finding counts
 - `clawpatch review`: review pending or selected features
 - `clawpatch review --mode deslopify`: review only for locally provable slop cleanup
+- `clawpatch ci`: initialize if needed, map, review, write a report, and append a GitHub step summary
 - `clawpatch report`: print or write a Markdown findings report
 - `clawpatch next`: print the next actionable finding
 - `clawpatch show --finding <id>`: inspect one finding with evidence and suggested validation
 - `clawpatch triage --finding <id> --status <status>`: mark a finding with optional history note
 - `clawpatch fix --finding <id>`: run the explicit patch loop for one finding
+- `clawpatch open-pr --patch <id>`: commit an applied patch attempt and open a GitHub PR
 - `clawpatch revalidate --finding <id>`: re-check one finding
 - `clawpatch revalidate --all`: re-check open findings with report-style filters
 - `clawpatch doctor`: check provider availability
@@ -180,7 +184,8 @@ to features so runs can resume and be audited.
 - Review does not edit files.
 - Fix is explicit and selected by finding ID.
 - Fix refuses a dirty source worktree by default.
-- Clawpatch never commits, pushes, opens PRs, or lands changes today.
+- Clawpatch commits, pushes, and opens PRs only from explicit patch commands such as `open-pr`.
+- Clawpatch does not land changes today.
 - Provider output is parsed through strict schemas.
 - Symlinked directories and generated build output are skipped during mapping.
 

docs/code-review.md

@@ -23,10 +23,15 @@ Current behavior:
 - reviews with a bounded worker pool; default `--jobs` is `10`
 - emits progress to stderr unless `--quiet` is set
 - builds bounded prompt context from owned files, context files, and tests
+- includes a prompt context manifest with included files, omitted files, byte
+  counts, and truncation status
 - calls the configured provider
 - requires strict JSON output
+- rejects findings whose evidence cites files outside the prompt context, stale
+  line ranges, or quotes that do not match current file contents
 - writes findings under `.clawpatch/findings/`
 - appends analysis history to the feature record
+- records prompt byte and approximate token counts in feature analysis history
 - releases the feature lock
 
 ## Flags
@@ -47,6 +52,19 @@ If no features are touched by the diff, `review` exits cleanly with no findings.
 The same flag is available on `revalidate`; revalidation scopes open findings to
 features whose owned files changed.
 
+### CI command
+
+Use `clawpatch ci` when a GitHub Actions job should run the whole read-only
+review loop:
+
+```bash
+clawpatch ci --since origin/main --limit 20 --jobs 4 --output clawpatch-report.md
+```
+
+The command initializes `.clawpatch/` if needed, maps features, reviews the
+selected feature set, writes a Markdown report when `--output` is provided, and
+appends a compact summary to `GITHUB_STEP_SUMMARY` when that file is available.
+
 Progress uses stderr so `--json` stdout remains machine-readable. The worker
 pool is per-process, and lock files under `.clawpatch/locks/` prevent
 overlapping review processes from claiming the same feature. Interrupted runs

docs/patching.md

@@ -34,10 +34,23 @@ Status updates:
 The CLI does not currently mark a finding `fixed` from the patch pass alone.
 Use `clawpatch revalidate --finding <id>` for a second pass.
 
+## Opening a PR
+
+After reviewing the applied worktree changes, create a GitHub PR explicitly:
+
+```bash
+clawpatch open-pr --patch <patchAttemptId> --draft
+```
+
+`open-pr` requires an applied or validated patch attempt with recorded changed
+files. It refuses failed validation unless `--force` is passed, commits only the
+recorded patch files, pushes the branch, and calls the GitHub CLI. Use
+`--dry-run` to preview the branch, title, body, and commands without touching
+git.
+
 Not implemented yet:
 
 - fixing by severity or category
 - batching multiple findings
 - auto-commit
-- PR creation
 - rollback snapshots

docs/spec.md

@@ -330,10 +330,8 @@ Behavior:
 - Requires existing patch attempt with changed files.
 - Requires clean validation state unless `--force`.
 - Creates branch/commit/PR only after explicit command.
-- Uses repo-native commit helper if configured.
-- PR body includes findings, tests, revalidation, and links to state report.
-
-Post-v0.
+- Uses the GitHub CLI to create the PR after committing the recorded patch files.
+- PR body includes linked findings, changed files, validation output, and the patch plan.
 
 ### `clawpatch land`