feat(ce-review): add compact returns to reduce orchestrator context during merge (#535)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

plugins/compound-engineering/skills/ce-review/references/findings-schema.json

@@ -124,6 +124,11 @@
       "downstream-resolver": "Turn this into residual work for later resolution.",
       "human": "A person must make a judgment call before code changes should continue.",
       "release": "Operational or rollout follow-up; do not convert into code-fix work automatically."
+    },
+    "return_tiers": {
+      "description": "Finding fields are split into two tiers. The full schema (with all required fields) applies to the artifact file on disk. The compact return to the orchestrator omits detail-tier fields. Both are valid uses of this schema in different contexts.",
+      "merge_tier": "Returned to orchestrator: title, severity, file, line, confidence, autofix_class, owner, requires_verification, pre_existing, suggested_fix (optional). Plus top-level reviewer, residual_risks, testing_gaps.",
+      "detail_tier": "Required in artifact file, omitted from compact return: why_it_matters, evidence. The artifact file must pass full schema validation including all required fields. Headless output depends on why_it_matters and evidence being present in the artifact."
     }
   }
 }

plugins/compound-engineering/skills/ce-review/references/persona-catalog.md

@@ -33,7 +33,7 @@ Spawned when the orchestrator identifies relevant patterns in the diff. The orch
 | `api-contract` | `compound-engineering:review:api-contract-reviewer` | Route definitions, serializer/interface changes, event schemas, exported type signatures, API versioning |
 | `data-migrations` | `compound-engineering:review:data-migrations-reviewer` | Migration files, schema changes, backfill scripts, data transformations |
 | `reliability` | `compound-engineering:review:reliability-reviewer` | Error handling, retry logic, circuit breakers, timeouts, background jobs, async handlers, health checks |
-| `adversarial` | `compound-engineering:review:adversarial-reviewer` | Diff has >=50 changed non-test, non-generated, non-lockfile lines, OR touches auth, payments, data mutations, external API integrations, or other high-risk domains |
+| `adversarial` | `compound-engineering:review:adversarial-reviewer` | Diff has >=50 changed lines of executable code (not prose/instruction Markdown, JSON schemas, or config), OR touches auth, payments, data mutations, external API integrations, or other high-risk domains regardless of file type |
 | `cli-readiness` | `compound-engineering:review:cli-readiness-reviewer` | CLI command definitions, argument parsing, CLI framework usage, command handler implementations |
 | `previous-comments` | `compound-engineering:review:previous-comments-reviewer` | **PR-only.** Reviewing a PR that has existing review comments or review threads from prior review rounds. Skip entirely when no PR metadata was gathered in Stage 1. |
 

plugins/compound-engineering/skills/ce-review/references/subagent-template.md

@@ -18,7 +18,23 @@ You are a specialist code reviewer.
 </scope-rules>
 
 <output-contract>
-Return ONLY valid JSON matching the findings schema below. No prose, no markdown, no explanation outside the JSON object.
+You produce up to two outputs depending on whether a run ID was provided:
+
+1. **Artifact file (when run ID is present).** If a Run ID appears in <review-context> below, WRITE your full analysis (all schema fields, including why_it_matters, evidence, and suggested_fix) as JSON to:
+   .context/compound-engineering/ce-review/{run_id}/{reviewer_name}.json
+   This is the ONE write operation you are permitted to make. Use the platform's file-write tool.
+   If the write fails, continue -- the compact return still provides everything the merge needs.
+   If no Run ID is provided (the field is empty or absent), skip this step entirely -- do not attempt any file write.
+
+2. **Compact return (always).** RETURN compact JSON to the parent with ONLY merge-tier fields per finding:
+   title, severity, file, line, confidence, autofix_class, owner, requires_verification, pre_existing, suggested_fix.
+   Do NOT include why_it_matters or evidence in the returned JSON.
+   Include reviewer, residual_risks, and testing_gaps at the top level.
+
+The full file preserves detail for downstream consumers (headless output, debugging).
+The compact return keeps the orchestrator's context lean for merge and synthesis.
+
+The schema below describes the **full artifact file format** (all fields required). For the compact return, follow the field list above -- omit why_it_matters and evidence even though the schema marks them as required.
 
 {schema}
 
@@ -42,9 +58,9 @@ False-positive categories to actively suppress:
 
 Rules:
 - You are a leaf reviewer inside an already-running compound-engineering review workflow. Do not invoke compound-engineering skills or agents unless this template explicitly instructs you to. Perform your analysis directly and return findings in the required output format only.
-- Every finding MUST include at least one evidence item grounded in the actual code.
+- Every finding in the full artifact file MUST include at least one evidence item grounded in the actual code. The compact return omits evidence -- the evidence requirement applies to the disk artifact only.
 - Set pre_existing to true ONLY for issues in unchanged code that are unrelated to this diff. If the diff makes the issue newly relevant, it is NOT pre-existing.
-- You are operationally read-only. You may use non-mutating inspection commands, including read-oriented `git` / `gh` commands, to gather evidence. Do not edit files, change branches, commit, push, create PRs, or otherwise mutate the checkout or repository state.
+- You are operationally read-only. The one permitted exception is writing your full analysis to the `.context/` artifact path when a run ID is provided. You may also use non-mutating inspection commands, including read-oriented `git` / `gh` commands, to gather evidence. Do not edit project files, change branches, commit, push, create PRs, or otherwise mutate the checkout or repository state.
 - Set `autofix_class` accurately -- not every finding is `advisory`. Use this decision guide:
   - `safe_auto`: The fix is local and deterministic — the fixer can apply it mechanically without design judgment. Examples: extracting a duplicated helper, adding a missing nil/null check, fixing an off-by-one, adding a missing test for an untested code path, removing dead code.
   - `gated_auto`: A concrete fix exists but it changes contracts, permissions, or crosses a module boundary in a way that deserves explicit approval. Examples: adding authentication to an unprotected endpoint, changing a public API response shape, switching from soft-delete to hard-delete.
@@ -63,6 +79,9 @@ Rules:
 </pr-context>
 
 <review-context>
+Run ID: {run_id}
+Reviewer name: {reviewer_name}
+
 Intent: {intent_summary}
 
 Changed files: {file_list}
@@ -83,3 +102,5 @@ Diff:
 | `{pr_metadata}` | Stage 1 output | PR title, body, and URL when reviewing a PR. Empty string when reviewing a branch or standalone checkout |
 | `{file_list}` | Stage 1 output | List of changed files from the scope step |
 | `{diff}` | Stage 1 output | The actual diff content to review |
+| `{run_id}` | Stage 4 output | Unique review run identifier for the artifact directory |
+| `{reviewer_name}` | Stage 3 output | Persona or agent name used as the artifact filename stem |