Merge remote-tracking branch 'origin/main' into pr/acpx-stop-reason

# Conflicts:
#	CHANGELOG.md
#	src/provider.ts

Author: steipete

.oxfmtrc.json

@@ -1,4 +1,6 @@
 {
   "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "tabWidth": 2,
+  "useTabs": false,
   "ignorePatterns": []
 }

CHANGELOG.md

@@ -5,16 +5,38 @@
 - 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.
+- Added retries for transient acpx JSON review failures via `--prompt-retries` and `CLAWPATCH_REVIEW_RETRIES`, thanks @coletebou.
 - Hardened review ingestion so provider findings must cite included files with valid line ranges and matching evidence quotes.
+- Fixed provider review to preserve valid sibling findings when per-finding schema or evidence validation fails, recording drops in `run.errors` as non-fatal `schema-drop` or `validation-drop` entries, thanks @coletebou.
+- Improved provider schema validation failures so `run.errors[].message` shows compact one-line Zod issue summaries, thanks @coletebou.
+- Added `total` and `results` aliases on `clawpatch report --json` output while keeping the legacy `findings` count, thanks @coletebou.
 - 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`.
-- Fixed acpx provider error reporting by reading the terminal `result.stopReason` envelope and surfacing non-`end_turn` reasons as typed `ClawpatchError` codes (`agent-cancelled`, `agent-refused`, `agent-truncated`) instead of opaque `malformed-output`.
+- Fixed formatter configuration so `oxfmt` uses two-space indentation consistently across platforms.
+- Added generic package-less monorepo app-root mapping for Node/Next projects under roots such as `apps/*` and `packages/*` when positive source or framework signals are present.
+- Added Maven project mapping for root, nested, and multi-module Java/Kotlin projects with Spring role slices, Maven validation defaults, and `pom.xml` detection, thanks @julianshess.
+- Added a release-prep checklist for auditing changelog, package metadata, and dry-run package contents without publishing.
+- Improved bounded source grouping so large flat directories split repeated filename families like command, plugin, doctor, and runtime files into more coherent review slices.
+- Fixed acpx provider error reporting by reading the terminal `result.stopReason` envelope and surfacing non-`end_turn` reasons as typed `ClawpatchError` codes (`agent-cancelled`, `agent-refused`, `agent-truncated`) instead of opaque `malformed-output`, thanks @coletebou.
 - Improved OpenCode malformed JSON diagnostics with output length, event kinds, and a bounded preview, thanks @rohitjavvadi.
+- Fixed finding signatures so equivalent evidence remains stable across re-reviews, thanks @rohitjavvadi.
+- Fixed provider exit-code classification for stdout-only authentication and quota failures, thanks @rohitjavvadi.
+- Improved Node route mapping to preserve literal Express and Hono mount prefixes, thanks @rohitjavvadi.
+- Improved Flask route mapping to preserve static blueprint URL prefixes, thanks @rohitjavvadi.
+- Improved Django route mapping to preserve literal `include()` route prefixes, thanks @rohitjavvadi.
+- Added conservative Rails route mapping for literal root and HTTP verb routes, thanks @rohitjavvadi.
+- Fixed heuristic feature mapping to honor configured path include/exclude filters, thanks @schedawg74.
 - Fixed Express route mapping for aliased Router imports that follow block comment banners, thanks @rohitjavvadi.
+- Fixed Laravel route mapping to include array-style `Route::group` prefixes, thanks @rohitjavvadi.
+- Fixed Fastify route-object mapping to emit static method arrays while ignoring dynamic entries, thanks @rohitjavvadi.
+- Fixed Fastify plugin callback route mapping for typed parameters and plugin aliases, thanks @rohitjavvadi.
+- Fixed FastAPI route mapping to include static `APIRouter(prefix=...)` values, thanks @AsishKumarDalal.
+- Added `--include-dirty` to review, CI, and revalidation file filters for auditing uncommitted worktree changes, thanks @AsishKumarDalal.
 - Fixed Bun package-manager detection to recognize the text `bun.lock` lockfile, thanks @austinm911.
+- Fixed review-output schema to tolerate optional `reproduction` and `minimumFixScope` fields and zero-valued evidence line numbers (normalized to `null`), recovering 4 of 28 zod issue patterns observed in run `20260517T190759-3c9e9e` (78 errors over 1000 features) that previously dropped whole-feature output instead of the affected finding.
 
 ## 0.3.0 - 2026-05-18
 

README.md

@@ -52,10 +52,14 @@ validation commands and records a patch attempt under `.clawpatch/`.
   `lint`, `typecheck`, `format`
 - Node/TypeScript workspace packages under `apps/*`, `packages/*`, and package
   workspace patterns
+- package-less Node/TypeScript app roots under monorepo folders such as
+  `apps/*` and `packages/*` when source or positive framework signals are
+  present
 - generic extension/plugin packages under workspace roots such as `extensions/*`
   and `plugins/*`, including package metadata, source, docs, and nearby tests
 - semantic Node source groups for large packages, including runtime, commands,
-  auth, storage, monitor, webhook, setup, server, and client slices
+  auth, storage, monitor, webhook, setup, server, client, and repeated filename
+  family slices
 - Nx project metadata from `project.json`, including project-scoped validation
   targets
 - Turborepo task metadata for workspace-aware validation commands and feature
@@ -64,7 +68,8 @@ validation commands and records a patch attempt under `.clawpatch/`.
 - React Router routes and React components
 - Go package slices from `go list ./...`, including command packages
 - Go package tests and same-repo imports as review context
-- Java/Kotlin Gradle source groups and root Gradle build/test commands
+- Java/Kotlin Gradle source groups, Maven source groups, and root Gradle/Maven
+  build/test commands
 - JVM semantic roles from Java and Kotlin code evidence such as annotations,
   imports, interfaces, inheritance, supertypes, and method signatures
 - Kotlin Android semantic roles for UI entrypoints, ViewModels, data
@@ -161,6 +166,28 @@ Useful flags:
 
 Unknown flags fail fast.
 
+### `report --json` shape
+
+`clawpatch report --json` returns:
+
+```json
+{
+  "total": 12,
+  "items": [
+    /* finding summaries */
+  ],
+  "results": [
+    /* alias for items */
+  ],
+  "findings": 12,
+  "output": "/path/or/null"
+}
+```
+
+- `total` and `items` are the canonical keys.
+- `results` is an alias for `items` with the same array for parity with `{count, results}` consumers.
+- `findings: <number>` is kept for backwards compatibility but is **deprecated**. Note that in `--json` output `findings` is a _count_, not the array — use `items` (or `results`) for the array. The next breaking release (v0.4) will drop `findings: <number>` and `results`, landing on `{ total, items, output }`.
+
 ## State
 
 State is project-local by default:

docs/feature-mapping.md

@@ -31,9 +31,14 @@ Supported deterministic mappers today:
 - npm package bins
 - selected root and workspace package scripts
 - Node/TypeScript workspace packages from `package.json` workspaces, `pnpm-workspace.yaml`, and common package folders
+- package-less Node/TypeScript app roots under monorepo folders such as
+  `apps/*` and `packages/*` when source files or positive framework signals are
+  present
 - Nx project metadata from `project.json`, including project names, source roots, project types, and target names
 - Turborepo `turbo.json` metadata for workspace-aware validation commands and feature context
-- bounded Node/TypeScript source groups under `src/`, `lib/`, `app/`, `pages/`, and `scripts/`
+- bounded Node/TypeScript source groups under `src/`, `lib/`, `app/`,
+  `pages/`, `scripts/`, `server/`, and `api/`, with oversized flat
+  directories split by repeated filename families
 - React Router `<Route path element>` declarations and React components in
   root or nested frontend packages such as `frontend/`, `client/`, `web/`,
   workspaces, and packages under `apps/` or `packages/`
@@ -57,6 +62,8 @@ Supported deterministic mappers today:
 - nested SwiftPM packages
 - Apple/Xcode projects from `project.yml`, `.xcodeproj`, or `.xcworkspace`
 - Java/Kotlin Gradle modules from `settings.gradle(.kts)` and `build.gradle(.kts)`
+- Java/Kotlin Maven modules from root and nested `pom.xml` files, including
+  multi-module projects
 - Laravel/PHP projects from `composer.json` and `artisan`, including controllers
   referenced by routes, form requests, Artisan commands, jobs, services, models,
   migrations, seeders, Composer scripts, and grouped PHP test suites
@@ -95,10 +102,13 @@ and `plugins/*` are tagged as extension packages and keep package metadata,
 source, docs, and tests together as review context.
 
 In JavaScript/TypeScript monorepos, project discovery runs before framework
-mapping. Workspace packages and Nx projects are normalized into project roots,
-so framework mappers can apply the same heuristics to `apps/*` and `packages/*`
-that they apply at the repository root. Feature tags include project name and
-project root metadata, enabling commands such as:
+mapping. Workspace packages, Nx projects, and package-less app roots with source
+or positive framework signals are normalized into project roots, so framework
+mappers can apply the same heuristics to `apps/*` and `packages/*` that they
+apply at the repository root. Hoisted Next route mapping uses positive evidence
+such as local Next commands, local Next config, App Router files, or Pages API
+files instead of trying to enumerate every non-Next config file. Feature tags
+include project name and project root metadata, enabling commands such as:
 
 ```bash
 clawpatch review --project apps/web --limit 10
@@ -122,12 +132,15 @@ lazy import, and also maps page/component files under `src/pages` and
 `src/components` as UI-flow slices.
 Native app mappers use the same bounded grouping model. SwiftPM packages can be
 discovered below the repo root, Apple projects are grouped by Swift source area,
-and Gradle modules are grouped from `src/main`, `src/test`, and `src/androidTest`.
-Root Gradle projects get default `gradle`/`./gradlew` build and test commands.
-Java and Kotlin files in Gradle modules also get role-oriented review slices
-when code evidence identifies web entrypoints, services, persistence boundaries,
-external clients, configuration, framework components, extension boundaries,
-Android UI entrypoints, ViewModels, data boundaries, or dependency injection.
+Gradle modules are grouped from `src/main`, `src/test`, and `src/androidTest`,
+and Maven modules are grouped from `src/main` and `src/test`. Root Gradle
+projects get default `gradle`/`./gradlew` build and test commands; root Maven
+projects get default `mvn`/`./mvnw` compile and test commands.
+Java and Kotlin files in Gradle modules, plus Java files in Maven modules, also
+get role-oriented review slices when code evidence identifies web entrypoints,
+services, persistence boundaries, external clients, configuration, framework
+components, extension boundaries, Android UI entrypoints, ViewModels, data
+boundaries, or dependency injection.
 Kotlin dependency-injection evidence includes Hilt, Dagger, Koin, and Metro
 annotations and imports.
 
@@ -153,12 +166,13 @@ pytest files; Flask `@*.route(...)` handlers; FastAPI `@*.get(...)` /
 `re_path(...)`, and legacy `url(...)` declarations. Flask and FastAPI route
 methods are read from list, tuple, or set literals. FastAPI paths can be
 positional strings or literal `path=` keywords. Django route paths are normalized
-from literal route strings and simple named regex groups; includes are mapped as
-their own URL groups without recursively expanding imported URL configs. Default
+from literal route strings and simple named regex groups, and literal
+`include("module.urls")` routes are expanded under their mount prefixes. Default
 Python command detection covers pytest, ruff, mypy, pyright, and black.
 
 Ruby mapping covers project metadata, executables, source groups, RSpec and
-Minitest suites, and Rails app structure. Rails legacy `config/secrets.yml`,
+Minitest suites, Rails app structure, and literal Rails root and HTTP verb
+routes. Rails legacy `config/secrets.yml`,
 `config/database.yml`, and `config/initializers/secret_token.rb` are not mapped
 as reviewable config because they can contain provider-sensitive secrets.
 

docs/index.md

@@ -30,7 +30,7 @@ stderr so pipes stay parseable.
 
 ## What clawpatch does
 
-- **Semantic feature mapping.** Detects npm bins, Next.js routes, React Router routes, Python packages and Flask/FastAPI/Django routes, Ruby/Rails slices, Laravel/PHP slices, Java/Kotlin Gradle modules, C#/.NET projects and ASP.NET endpoints, Go packages, Rust crates, C/C++ build targets, SwiftPM targets, and common config files as reviewable units.
+- **Semantic feature mapping.** Detects npm bins, Next.js routes, React Router routes, Python packages and Flask/FastAPI/Django routes, Ruby/Rails slices, Laravel/PHP slices, Java/Kotlin Gradle and Maven modules, C#/.NET projects and ASP.NET endpoints, Go packages, Rust crates, C/C++ build targets, SwiftPM targets, and common config files as reviewable units.
 - **Automated code review.** Reviews features with AI providers (Codex CLI today), persists findings with severity, category, and line locations.
 - **Explicit fix workflow.** `clawpatch fix` runs validated patches for one finding at a time, never commits or pushes automatically.
 - **Stable state model.** All features, findings, patches live in `.clawpatch/` as JSON, resumable across runs.
@@ -59,6 +59,7 @@ stderr so pipes stay parseable.
 - [Validation](validation.md)
 - [Providers](providers.md)
 - [Safety](safety.md)
+- [Release Prep](release-prep.md)
 - [E2E with Gitcrawl](e2e-gitcrawl.md)
 - [Initialization](initialization.md)
 

docs/quickstart.md

@@ -47,7 +47,7 @@ This discovers reviewable features:
 - npm package bins and root/workspace scripts
 - Next.js routes
 - Go packages and commands
-- Java/Kotlin Gradle modules
+- Java/Kotlin Gradle and Maven modules
 - Python packages, console scripts, Flask/FastAPI/Django routes, and pytest suites
 - C#/.NET projects, ASP.NET endpoints, source groups, and test projects
 - JVM semantic role groups

docs/release-prep.md

@@ -0,0 +1,54 @@
+---
+title: Release Prep
+description: "No-publish checks for preparing a clawpatch release"
+---
+
+# Release Prep
+
+This checklist audits release readiness only. It does not publish, tag, create a
+GitHub release, or change the package version.
+
+## Current Snapshot
+
+As of 2026-05-18:
+
+- GitHub latest full release: `v0.3.0`
+- `package.json` version: `0.3.0`
+- npm `clawpatch` version: `0.3.0`
+- `pnpm pack:smoke` passed
+- `npm pack --dry-run --json --ignore-scripts` included expected package
+  contents such as `dist/`, `README.md`, `LICENSE`, and `package.json`
+
+Prepare the next release only after the maintainer confirms the target version
+and timing.
+
+## Audit Commands
+
+```bash
+gh release list --repo openclaw/clawpatch --limit 20 --json tagName,isPrerelease,isDraft,publishedAt,isLatest
+node -p "require('./package.json').version"
+npm view clawpatch version --json
+```
+
+## Validation Commands
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm format:check
+pnpm exec vitest run --maxWorkers=1
+pnpm build
+pnpm pack:smoke
+npm pack --dry-run --json --ignore-scripts
+```
+
+## Manual Checks
+
+- Confirm `CHANGELOG.md` has all user-visible, operational, or security-relevant
+  changes under the next unreleased version.
+- Confirm README and docs mention any new mapper behavior, commands, or safety
+  constraints.
+- Confirm the dry-run package includes built `dist/` files and excludes local
+  state, fixtures that should not ship, and private paths.
+- Confirm no release action has been run unless release timing is explicitly
+  approved.