chore(report): add total/results aliases for json output, document deprecation

CHANGELOG.md

@@ -7,6 +7,7 @@
 - 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.
+- 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.

README.md

@@ -164,6 +164,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:

src/app.ts

@@ -499,10 +499,13 @@ export async function reportCommand(
     await writeFile(outputPath, output, "utf8");
   }
   if (context.options.json) {
+    const items = findingSummaries(filtered, scopedFeatures);
     return {
       findings: filtered.length,
+      total: filtered.length,
       output: outputPath,
-      items: findingSummaries(filtered, scopedFeatures),
+      items,
+      results: items,
     };
   }
   return {

src/workflow.test.ts

@@ -426,6 +426,7 @@ describe("workflow", () => {
     });
     expect(jsonReport).toMatchObject({
       findings: 1,
+      total: 1,
       items: [
         {
           id: expect.stringMatching(/^fnd_/u),
@@ -439,6 +440,15 @@ describe("workflow", () => {
       ],
     });
     expect(reviewedFeature?.analysisHistory.at(-1)?.summary).toContain("prompt=");
+    const aliased = jsonReport as {
+      findings: number;
+      total: number;
+      items: unknown[];
+      results: unknown[];
+    };
+    expect(aliased.total).toBe(aliased.findings);
+    expect(aliased.total).toBe(aliased.items.length);
+    expect(aliased.results).toBe(aliased.items);
     delete process.env["CLAWPATCH_PROVIDER"];
   });