@fro.bot/systematic 3.12.1 → 3.12.3

package/agents/review/README.md

@@ -0,0 +1,10 @@
+# Shared Review Persona Pool
+
+`agents/review/` is a shared persona pool, not a single workflow roster.
+Workflow-specific rosters live in the relevant skill catalogs.
+
+These agents are not dispatched by `ce:review`:
+
+- `systematic:review:architecture-strategist` — dispatched by `deepen-plan` and the `ce-plan` deepening workflow.
+- `systematic:review:pattern-recognition-specialist` — dispatched by `deepen-plan`, the `ce-plan` deepening workflow, and `ce-compound`.
+- `systematic:review:code-simplicity-reviewer` — dispatched by `ce-compound`.

package/dist/cli.js

@@ -13,7 +13,7 @@ import {
   parse,
   parseFrontmatter,
   parseTree
-} from "./index-y8nc60tz.js";
+} from "./index-h26p98ny.js";
 
 // src/cli.ts
 import fs5 from "fs";

package/dist/{index-y8nc60tz.js → index-h26p98ny.js}

@@ -16782,6 +16782,9 @@ function extractBoolean(data, key) {
 // src/lib/walk-dir.ts
 import fs2 from "fs";
 import path2 from "path";
+function isDiscoverableMarkdown(fileName) {
+  return fileName.endsWith(".md") && fileName.toLowerCase() !== "readme.md";
+}
 function walkDir(rootDir, options = {}) {
   const { maxDepth = 3, filter } = options;
   const results = [];
@@ -16816,7 +16819,7 @@ function walkDir(rootDir, options = {}) {
 function findAgentsInDir(dir, maxDepth = 2) {
   const entries = walkDir(dir, {
     maxDepth,
-    filter: (e) => !e.isDirectory && e.name.endsWith(".md")
+    filter: (e) => !e.isDirectory && isDiscoverableMarkdown(e.name)
   });
   return entries.map((entry) => ({
     name: entry.name.replace(/\.md$/, ""),
@@ -16851,7 +16854,7 @@ function extractAgentFrontmatter(content) {
 function findCommandsInDir(dir, maxDepth = 2) {
   const entries = walkDir(dir, {
     maxDepth,
-    filter: (e) => !e.isDirectory && e.name.endsWith(".md")
+    filter: (e) => !e.isDirectory && isDiscoverableMarkdown(e.name)
   });
   return entries.map((entry) => {
     const baseName = entry.name.replace(/\.md$/, "");
@@ -17094,4 +17097,4 @@ function discoverSkills(options) {
   return Array.from(byName.values());
 }
 
-export { __require, parseFrontmatter, parse2 as parse, parseTree2 as parseTree, modify, applyEdits, exports_external, AgentOverlaySchema, CategoryOverlaySchema, loadConfig, loadConfigWithSources, getConfigPaths, isRecord2 as isRecord, extractString, findAgentsInDir, extractAgentFrontmatter, findCommandsInDir, extractCommandFrontmatter, findSkillsInDir, discoverSkills };
+export { __require, parseFrontmatter, parse2 as parse, parseTree2 as parseTree, modify, applyEdits, exports_external, AgentOverlaySchema, CategoryOverlaySchema, loadConfig, loadConfigWithSources, getConfigPaths, isRecord2 as isRecord, extractString, isDiscoverableMarkdown, findAgentsInDir, extractAgentFrontmatter, findCommandsInDir, extractCommandFrontmatter, findSkillsInDir, discoverSkills };

package/dist/index.js

@@ -10,11 +10,12 @@ import {
   findAgentsInDir,
   findCommandsInDir,
   findSkillsInDir,
+  isDiscoverableMarkdown,
   isRecord,
   loadConfig,
   loadConfigWithSources,
   parseFrontmatter
-} from "./index-y8nc60tz.js";
+} from "./index-h26p98ny.js";
 
 // src/index.ts
 import { createHash as createHash4 } from "crypto";
@@ -282,7 +283,7 @@ function readCategoryDirs(agentsDir) {
 }
 function readMarkdownFiles(categoryDir) {
   try {
-    return fs3.readdirSync(categoryDir, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith(".md")).map((entry) => entry.name).sort();
+    return fs3.readdirSync(categoryDir, { withFileTypes: true }).filter((entry) => entry.isFile() && isDiscoverableMarkdown(entry.name)).map((entry) => entry.name).sort();
   } catch {
     return [];
   }

package/dist/lib/walk-dir.d.ts

@@ -9,4 +9,14 @@ export interface WalkOptions {
     maxDepth?: number;
     filter?: (entry: WalkEntry) => boolean;
 }
+/**
+ * Whether a markdown filename is discoverable content rather than documentation
+ * about the directory that holds it.
+ *
+ * Agent and command discovery register every `.md` file they walk, so a plain
+ * `README.md` placed in `agents/<category>/` would otherwise be registered as a
+ * dispatchable agent named `README`. README is documentation by universal
+ * convention, so it is never content.
+ */
+export declare function isDiscoverableMarkdown(fileName: string): boolean;
 export declare function walkDir(rootDir: string, options?: WalkOptions): WalkEntry[];

package/dist/pi.js

@@ -3170,6 +3170,9 @@ function extractBoolean(data, key) {
 // src/lib/walk-dir.ts
 import fs from "node:fs";
 import path from "node:path";
+function isDiscoverableMarkdown(fileName) {
+  return fileName.endsWith(".md") && fileName.toLowerCase() !== "readme.md";
+}
 function walkDir(rootDir, options = {}) {
   const { maxDepth = 3, filter } = options;
   const results = [];
@@ -3204,7 +3207,7 @@ function walkDir(rootDir, options = {}) {
 function findAgentsInDir(dir, maxDepth = 2) {
   const entries = walkDir(dir, {
     maxDepth,
-    filter: (e) => !e.isDirectory && e.name.endsWith(".md")
+    filter: (e) => !e.isDirectory && isDiscoverableMarkdown(e.name)
   });
   return entries.map((entry) => ({
     name: entry.name.replace(/\.md$/, ""),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "3.12.1",
+  "version": "3.12.3",
   "description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
   "type": "module",
   "homepage": "https://fro.bot/systematic",

package/skills/ce-plan/references/universal-planning.md

@@ -28,7 +28,7 @@ Evaluate two things before planning:
 | Research need | Signals | Action |
 |--------------|---------|--------|
 | **None** | Generic, timeless, or conceptual plan (study curriculum methodology, project management approach, personal goal breakdown) | Skip research. Model knowledge is sufficient. After structuring the plan, offer: "I based this on general knowledge. Want me to search for [specific thing research would improve]?" — e.g., sourced recipes, current product recommendations, expert frameworks. Only if the user accepts. |
-| **Recommended** | Plan references specific locations, venues, dates, prices, schedules, seasonal availability, or current events — anything where stale information would break the plan (closed restaurants, changed prices, cancelled events, wrong seasonal dates). | Research before planning. Decompose into 2-5 focused research questions and dispatch parallel web searches. In OpenCode, use the Agent tool with `model: "haiku"` for each search to reduce cost. Collate findings before structuring the plan. |
+| **Recommended** | Plan references specific locations, venues, dates, prices, schedules, seasonal availability, or current events — anything where stale information would break the plan (closed restaurants, changed prices, cancelled events, wrong seasonal dates). | Research before planning. Decompose into 2-5 focused research questions and dispatch parallel web searches. Collate findings before structuring the plan. |
 
 When research is recommended, do it — don't just offer. Stale recommendations (closed restaurants, rethemed attractions, outdated prices) are worse than no recommendations. The user invoked `ce:plan` because they want a good plan, not a disclaimer about training data.
 

package/skills/ce-review/SKILL.md

@@ -452,9 +452,11 @@ Returning the detail tier inline increases parent context per persona. The previ
 
 ### Stage 5: Merge findings
 
+The parent-owned artifact and its reconciliation rules are defined in the [synthesis artifact contract](./references/synthesis-artifact-contract.md). The stages below describe when synthesis decisions are made.
+
 Convert multiple reviewer JSON returns into one deduplicated, confidence-gated finding set. Each persona return already contains both tiers. The parent must retain the validated payload in memory for merge and synthesis, then persist only the same validated data.
 
-Before applying the confidence gate, assign every finding in a valid return a stable parent-owned `input_id` of `<reviewer>#<1-based finding index>`. Keep an input ledger through every later stage. The ledger is the authoritative reconciliation record in the synthesis artifact; it is not part of the persona's returned payload. If a return is rejected but its parsed `findings` array can be safely enumerated, assign IDs and record every enumerated input as `rejected`. If the return is malformed JSON or has no safely enumerable findings, record no synthetic input findings; the persona-level dispatch record and its exact safe rejection reason still record the rejection.
+Before applying the confidence gate, assign every finding in a valid return a stable parent-owned `input_id` of `<reviewer>#<1-based finding index>` and keep the parent-owned ledger through every later stage. See the [synthesis artifact contract](./references/synthesis-artifact-contract.md) for the ledger's authoritative reconciliation rules.
 
 1. **Validate before any write.** Treat every persona return as untrusted input. Parse the returned text as JSON without logging the raw text, then validate the complete parsed object against `references/findings-schema.json`, including `why_it_matters` and `evidence`.
    - **Top-level required:** reviewer (string), findings (array), residual_risks (array), testing_gaps (array). Reject the entire persona return if any are missing or wrong type.
@@ -463,11 +465,11 @@ Before applying the confidence gate, assign every finding in a valid return a st
    - **Environment-value detection:** JSON Schema cannot determine where a string came from, so recursively inspect every string leaf in the parsed payload before writing. Reject the payload when a string contains a shell/environment reference (`$NAME`, `${NAME}`, `process.env.NAME`, or `os.environ[...]`), an assignment using a known environment variable (`NAME=value`), or a current environment value as an exact or embedded match. Use a conservative match set of non-empty runtime environment values; never log the matched value. This detector is an additional parent-side check, not a schema claim.
    - **Safe rejection message:** report only `Rejected persona <name> return: field <JSON path> failed <reason>.` Derive `<JSON path>` from the validator or recursive scan and use a fixed reason such as `schema validation`, `environment-value detection`, or `malformed JSON`; never include the offending value, raw return, or validator parameters.
    - **No partial writes:** do not write a per-agent record or merge any finding until the entire persona payload passes schema and environment-value validation. A valid payload is then annotated by the parent with `harness` and `dispatch_outcome` and written by the parent only. Revalidate the enriched record before persistence.
-   - **Dispatch outcome:** a valid non-empty return is `findings`; a valid empty return is `empty`; invalid JSON or a rejected schema/environment payload is `malformed`; timeout or no return is `never_returned`. Keep these outcomes separate from finding `disposition`.
-   - **Rejection policy: degrade, do not fail the whole review.** Continue merging conforming returns, record the rejected persona's `dispatch_outcome` and safe rejection reason in the synthesis artifact, and give any rejected input the `rejected` disposition in the later reconciliation. If every persona fails or times out, use the existing degraded-review behavior. This preserves partial review coverage without ever persisting a non-conforming artifact; only an orchestration/storage failure that prevents the parent from producing its required run artifact is run-fatal.
+   - **Dispatch outcome:** Record the parent-owned dispatch outcomes and ledger dispositions according to the [synthesis artifact contract](./references/synthesis-artifact-contract.md); keep dispatch outcomes separate from finding dispositions.
+   - **Rejection policy: degrade, do not fail the whole review.** Continue merging conforming returns when a persona is rejected; record the rejection according to the [synthesis artifact contract](./references/synthesis-artifact-contract.md). If every persona fails or times out, use the existing degraded-review behavior.
 2. **Confidence gate.** Suppress findings below 0.60 confidence. Exception: P0 findings at 0.50+ confidence survive the gate -- critical-but-uncertain issues must not be silently dropped. Record the suppressed finding's original confidence and an explicit reason in the input ledger. A retained P0 at 0.50+ is recorded as `surviving` unless it later participates in a deduplication merge. This matches the persona instructions and the schema's confidence thresholds.
 3. **Deduplicate.** Compute fingerprint: `normalize(file) + line_bucket(line, +/-3) + normalize(title)`. When fingerprints match, merge: keep highest severity, keep highest confidence, preserve the exact fingerprint, and retain the input IDs that produced the merged entry. A singleton that passes the gate is `surviving`; each input in a multi-input merge is provisionally `merged`.
-4. **Cross-reviewer agreement.** When 2+ independent reviewers flag the same issue (same fingerprint), boost the merged confidence by 0.10 (capped at 1.0). Cross-reviewer agreement is strong signal -- independent reviewers converging on the same issue is more reliable than any single reviewer's confidence. Preserve the distinction in the merged finding's artifact provenance: `submitters` contains only personas with an input finding in that fingerprint group; `agreement_credit` contains only personas credited by the agreement boost without an input finding in that group. A persona with zero findings never appears in `submitters`. Do not infer submission from the report's Reviewer column.
+4. **Cross-reviewer agreement.** When 2+ independent reviewers flag the same issue (same fingerprint), boost the merged confidence by 0.10 (capped at 1.0). Cross-reviewer agreement is strong signal -- independent reviewers converging on the same issue is more reliable than any single reviewer's confidence. Preserve the distinction in the merged finding's artifact provenance according to the [synthesis artifact contract](./references/synthesis-artifact-contract.md).
 5. **Separate pre-existing.** Pull out findings with `pre_existing: true` into a separate list.
 6. **Resolve disagreements.** When reviewers flag the same code region but disagree on severity, autofix_class, or owner, annotate the Reviewer column with the disagreement (e.g., "security (P0), correctness (P1) -- kept P0"). This transparency helps the user understand why a finding was routed the way it was.
 7. **Normalize routing.** For each merged finding, set the final `autofix_class`, `owner`, and `requires_verification`. If reviewers disagree, keep the most conservative route. Synthesis may narrow a finding from `safe_auto` to `gated_auto` or `manual`, but must not widen it without new evidence.
@@ -478,7 +480,7 @@ Before applying the confidence gate, assign every finding in a valid return a st
 9. **Sort.** Order by severity (P0 first) -> confidence (descending) -> file path -> line number.
 10. **Collect coverage data.** Union residual_risks and testing_gaps across reviewers.
 11. **Preserve CE agent artifacts.** Keep the learnings, agent-native, schema-drift, and deployment-verification outputs alongside the merged finding set. Do not drop unstructured agent output just because it does not match the persona JSON schema.
-12. **Keep the input ledger complete.** Every enumerated input finding has exactly one final disposition: `surviving`, `merged`, `suppressed`, `filtered`, or `rejected`, plus a reason. The ledger's disposition counts must sum to its input count. A rejected payload's reason is the exact safe rejection message produced by validation, not a bucket such as "invalid"; never include the offending value.
+12. **Keep the input ledger complete.** Every enumerated input finding must receive exactly one final disposition and reason; reconcile the ledger according to the [synthesis artifact contract](./references/synthesis-artifact-contract.md).
 
 ### Stage 5b: Validation pass
 
@@ -491,9 +493,9 @@ Run an independent validation pass over the merged finding set before synthesis.
 1. Identify all gated findings from the Stage 5 merged set.
 2. For each gated finding, spawn one validator subagent in parallel using the validator template at `references/validator-template.md`. Pass the finding fields, the intent summary, the file list, and the full diff.
 3. Collect `{validated, reason}` from each validator. Attach both fields to the finding.
-4. **Reconcile filtered inputs.** A finding with `validated: false` moves to the "Filtered (not validated)" presentation group in Stage 6, and every input ID contributing to that merged finding is updated to disposition `filtered` with the validator's exact one-sentence reason. It is not `suppressed`, `rejected`, or silently excluded from the input ledger.
-5. Findings with `validated: true` flow through to Stage 6 unchanged — they appear in the normal severity tables. Their input ledger dispositions remain `surviving` for singleton findings or `merged` for deduplicated groups.
-6. Findings outside the gating band carry no `validated` annotation and appear in Stage 6 severity tables unchanged; their input ledger dispositions remain `surviving` or `merged`.
+4. **Reconcile filtered inputs.** A finding with `validated: false` moves to the "Filtered (not validated)" presentation group in Stage 6, and every input ID contributing to that merged finding is updated to disposition `filtered` with the validator's exact one-sentence reason. Apply the remaining ledger rules from the [synthesis artifact contract](./references/synthesis-artifact-contract.md).
+5. Findings with `validated: true` flow through to Stage 6 unchanged — they appear in the normal severity tables.
+6. Findings outside the gating band carry no `validated` annotation and appear in Stage 6 severity tables unchanged.
 
 **Failure handling:** If a validator subagent fails or times out, treat the finding as `validated: true` (conservative fallback — keep it in the actioned set) and note the validator failure in the Coverage section.
 
@@ -700,15 +702,9 @@ After presenting findings and verdict (Stage 6), route the next steps by mode. R
 
 #### Step 4: Emit artifacts and downstream handoff
 
-- In interactive, autofix, and headless modes, write **`review-summary.json` unconditionally** under `.context/systematic/ce-review/<run-id>/`, including when every persona returns `empty` and there are zero surviving findings. `mode:report-only` remains exempt: it skips run-id and directory creation and writes nothing.
-- `review-summary.json` is the parent-owned synthesis artifact and must contain, at minimum:
-  - `run_id`, `mode`, `harness` (`opencode`, `pi`, or `claude-code`), and run lifecycle fields;
-  - a `dispatches` entry for every selected persona with `persona`, `dispatch_outcome` (`findings`, `empty`, `malformed`, or `never_returned`), the number of safely enumerated input findings, and the exact safe `rejection_reason` when applicable;
-  - an `input_findings` ledger with one entry per safely enumerated input, its `input_id`, reviewer, original confidence, final `disposition` (`surviving`, `merged`, `suppressed`, `filtered`, or `rejected`), and a stated reason. Its count must reconcile exactly with the sum of disposition counts. A malformed JSON return with no safely enumerable finding has zero ledger entries, not a fabricated finding;
-  - surviving synthesized findings and filtered findings, each retaining their original fields plus `input_finding_ids` and provenance. Every synthesized finding's provenance must include the exact dedup `fingerprint`, `submitters`, and `agreement_credit` arrays. `submitters` means independent input submissions; `agreement_credit` means agreement boost credit without a corresponding input submission;
-  - applied fixes, residual actionable work, advisory-only outputs, coverage data, and the harness value.
-- During the pre-dispatch setup described in Stage 4, initialize the synthesis artifact with lifecycle state `in_progress` and all selected personas initialized as `never_returned`. Update each dispatch entry as returns arrive. Finalize it as `completed` or `degraded` after synthesis; if the parent catches an abort or storage/orchestration failure, finalize it as `abnormal` with the stated termination reason. If the process dies before finalization, the pre-written `in_progress` artifact is itself an explicit incomplete run and must be counted as abnormal rather than treated as a missing or clean run. Never infer a clean run from an absent artifact.
-- Per-agent full-detail JSON files (`{reviewer_name}.json`) are written by the parent only after the persona return passes full-schema and environment-value validation. Rejected or never-returned personas do not produce a per-agent file; their dispatch outcome remains in the synthesis artifact. If a later confidence or validation stage changes an input disposition, update the parent-owned record and synthesis ledger before finalizing `review-summary.json`.
+- In interactive, autofix, and headless modes, write **`review-summary.json` unconditionally** under `.context/systematic/ce-review/<run-id>`; `mode:report-only` remains the deliberate no-write exception.
+- `review-summary.json` is the parent-owned synthesis artifact. Its lifecycle, dispatch outcomes, complete input ledger, synthesized and filtered findings with provenance, disposition counts, and downstream work are defined in the [canonical synthesis artifact contract](./references/synthesis-artifact-contract.md), whose vocabulary and bounds are executable in [`findings-schema.json`](./references/findings-schema.json).
+- Initialize the artifact before dispatch and persist only validated parent-owned records. Finalize lifecycle and reconciliation after synthesis; preserve the existing degraded and abnormal-run behavior described in the canonical contract.
 - Also write `metadata.json` alongside the findings so downstream skills can verify the artifact matches the current branch and HEAD. Minimum fields:
   ```json
   {
@@ -770,6 +766,10 @@ If the platform doesn't support parallel sub-agents, run reviewers sequentially.
 
 @./references/findings-schema.json
 
+### Synthesis Artifact Contract
+
+@./references/synthesis-artifact-contract.md
+
 ### Review Output Template
 
 @./references/review-output-template.md

package/skills/ce-review/references/review-output-template.md

@@ -125,7 +125,7 @@ This fails because: no pipe-delimited tables, no severity-grouped `###` headers,
 - **Pipe-delimited markdown tables** for findings -- never ASCII box-drawing characters or per-finding horizontal-rule separators between entries (the report-level `---` before the verdict is still required)
 - **Severity-grouped sections** -- `### P0 -- Critical`, `### P1 -- High`, `### P2 -- Moderate`, `### P3 -- Low`. Omit empty severity levels.
 - **Always include file:line location** for code review issues
-- **Reviewer column** shows which persona(s) submitted the issue. Multiple reviewers indicate independent submissions, not merely agreement credit. The machine-readable synthesis artifact keeps `submitters` separate from `agreement_credit`; do not infer submission from an agreement boost or from the display column alone.
+- **Reviewer column** shows which persona(s) submitted the issue. For the machine-readable distinction between submissions and agreement credit, see the [synthesis artifact contract](./synthesis-artifact-contract.md); do not infer submission from the display column alone.
 - **Confidence column** shows the finding's confidence score
 - **Route column** shows the synthesized handling decision as ``<autofix_class> -> <owner>``.
 - **Header includes** scope, intent, and reviewer team with per-conditional justifications
@@ -149,7 +149,7 @@ In `mode:headless`, replace the interactive pipe-delimited table report with a s
 - **No pipe-delimited tables.** Findings use `[severity][autofix_class -> owner] File: <file:line> -- <title>` line format with indented Why/Evidence/Suggested fix lines.
 - **Findings grouped by autofix_class** (gated-auto, manual, advisory) instead of severity. Within each group, findings are sorted by severity.
 - **Verdict in header** (top of output) instead of bottom, so programmatic callers get it first.
-- **`Artifact:` line** in metadata header gives callers the path to `review-summary.json`, the full run artifact with provenance, dispatch outcomes, and disposition reconciliation.
+- **`Artifact:` line** in the metadata header gives callers the path to `review-summary.json`; its full contract is defined in the [synthesis artifact contract](./synthesis-artifact-contract.md).
 - **`[needs-verification]` marker** on findings where `requires_verification: true`.
 - **Evidence lines** included per finding.
 - **"Filtered (not validated)" section** included when Stage 5b produced findings with `validated: false`. Uses `[severity][autofix_class -> owner] File: <file:line> -- <title>` format with an indented `Validator reason:` line. These findings are surfaced for human review, not removed.
@@ -157,61 +157,4 @@ In `mode:headless`, replace the interactive pipe-delimited table report with a s
 
 ## Synthesis Artifact Contract
 
-For interactive, autofix, and headless runs, the parent writes `.context/systematic/ce-review/<run-id>/review-summary.json` even when every selected persona returns `empty` and no finding survives. `mode:report-only` is the deliberate no-write exception.
-
-The artifact must preserve the following distinctions:
-
-```json
-{
-  "run_id": "<run-id>",
-  "mode": "<interactive | autofix | headless>",
-  "harness": "<opencode | pi | claude-code>",
-  "run_status": "<in_progress | completed | degraded | abnormal>",
-  "dispatches": [
-    {
-      "persona": "correctness",
-      "dispatch_outcome": "findings",
-      "input_finding_count": 2
-    },
-    {
-      "persona": "kieran-typescript",
-      "dispatch_outcome": "malformed",
-      "input_finding_count": 1,
-      "rejection_reason": "Rejected persona kieran-typescript return: field findings[0].evidence failed schema validation."
-    }
-  ],
-  "input_findings": [
-    {
-      "input_id": "correctness#1",
-      "reviewer": "correctness",
-      "confidence": 0.55,
-      "disposition": "suppressed",
-      "reason": "confidence 0.55 is below the 0.60 gate"
-    }
-  ],
-  "findings": [
-    {
-      "title": "<merged finding>",
-      "input_finding_ids": ["correctness#2", "testing#1"],
-      "provenance": {
-        "fingerprint": "<normalize(file) + line_bucket(line, +/-3) + normalize(title)>",
-        "submitters": ["correctness", "testing"],
-        "agreement_credit": []
-      }
-    }
-  ],
-  "disposition_counts": {
-    "surviving": 0,
-    "merged": 2,
-    "suppressed": 1,
-    "filtered": 0,
-    "rejected": 0
-  }
-}
-```
-
-- `dispatch_outcome` records what a persona returned: `findings`, `empty`, `malformed`, or `never_returned`. A rejection reason is preserved as the exact safe validation reason, naming persona and field without echoing the offending value.
-- `disposition` records what happened to each input finding: `surviving`, `merged`, `suppressed`, `filtered`, or `rejected`. Every safely enumerable input has exactly one disposition and stated reason; the disposition counts must equal the input-finding count.
-- `submitters` contains only personas with an input finding in the merged fingerprint group. `agreement_credit` contains only personas credited by the cross-reviewer agreement boost without an input finding in that group. A persona returning zero findings never appears in `submitters`.
-- `filtered` findings remain available for human review with the validator's stated reason, but are not part of the surviving/actioned set. A suppressed finding retains its original confidence, including the P0 exception for confidence `0.50` or higher.
-- The parent initializes the artifact as `in_progress` before dispatch. A completed run becomes `completed` or `degraded`; an interrupted or failed run is `abnormal` with its stated termination reason. An unfinished `in_progress` artifact is evidence of an abnormal run, not evidence of a clean run.
+Interactive, autofix, and headless runs write the parent-owned `review-summary.json`, while `mode:report-only` deliberately writes no artifact. Follow the [canonical synthesis artifact contract](./synthesis-artifact-contract.md); use [`findings-schema.json`](./findings-schema.json) for executable field vocabulary and bounds.

package/skills/ce-review/references/synthesis-artifact-contract.md

@@ -0,0 +1,127 @@
+# Synthesis Artifact Contract
+
+This is the canonical prose definition of the parent-owned
+`.context/systematic/ce-review/<run-id>/review-summary.json` synthesis artifact.
+The executable field vocabulary and bounds remain defined by
+[`findings-schema.json`](./findings-schema.json).
+
+## Scope and lifecycle
+
+For interactive, autofix, and headless runs, the parent writes
+`review-summary.json` even when every selected persona returns `empty` and no
+finding survives. `mode:report-only` is the deliberate no-write exception.
+
+The parent initializes the artifact as `in_progress` before dispatch, with all
+selected personas initialized as `never_returned`, and updates each dispatch
+entry as returns arrive. A completed run becomes `completed` or `degraded`. An
+interrupted or failed run becomes `abnormal` with its stated termination
+reason. An unfinished `in_progress` artifact is evidence of an abnormal run,
+not evidence of a clean run. Never infer a clean run from an absent artifact.
+
+The artifact is parent-owned. Per-agent full-detail JSON files are written
+only after the persona return passes full-schema and environment-value
+validation. Rejected or never-returned personas do not produce per-agent
+files. If a later confidence or validation stage changes an input disposition,
+the parent updates the record and synthesis ledger before finalizing the
+artifact.
+
+## Required distinctions and reconciliation
+
+The artifact must preserve these distinctions:
+
+```json
+{
+  "run_id": "<run-id>",
+  "mode": "<interactive | autofix | headless>",
+  "harness": "<opencode | pi | claude-code>",
+  "run_status": "<in_progress | completed | degraded | abnormal>",
+  "dispatches": [
+    {
+      "persona": "correctness",
+      "dispatch_outcome": "findings",
+      "input_finding_count": 2
+    },
+    {
+      "persona": "kieran-typescript",
+      "dispatch_outcome": "malformed",
+      "input_finding_count": 1,
+      "rejection_reason": "Rejected persona kieran-typescript return: field findings[0].evidence failed schema validation."
+    }
+  ],
+  "input_findings": [
+    {
+      "input_id": "correctness#1",
+      "reviewer": "correctness",
+      "confidence": 0.55,
+      "disposition": "suppressed",
+      "reason": "confidence 0.55 is below the 0.60 gate"
+    }
+  ],
+  "findings": [
+    {
+      "title": "<merged finding>",
+      "input_finding_ids": ["correctness#2", "testing#1"],
+      "provenance": {
+        "fingerprint": "<normalize(file) + line_bucket(line, +/-3) + normalize(title)>",
+        "submitters": ["correctness", "testing"],
+        "agreement_credit": []
+      }
+    }
+  ],
+  "disposition_counts": {
+    "surviving": 0,
+    "merged": 2,
+    "suppressed": 1,
+    "filtered": 0,
+    "rejected": 0
+  }
+}
+```
+
+- `dispatches` has an entry for every selected persona. `dispatch_outcome`
+  records what a persona returned: `findings`, `empty`, `malformed`, or
+  `never_returned`. A rejection reason is the exact safe validation reason,
+  naming persona and field without echoing the offending value. Dispatch
+  outcome is separate from finding disposition.
+- `input_findings` is the authoritative parent-owned ledger. Before the
+  confidence gate, every safely enumerable finding receives an `input_id` of
+  `<reviewer>#<1-based finding index>`. Every enumerated input has exactly one
+  final `disposition`: `surviving`, `merged`, `suppressed`, `filtered`, or
+  `rejected`, plus a reason. Disposition counts equal the input-finding count.
+  If a rejected return has a safely enumerable `findings` array, assign IDs and
+  record each enumerated input as `rejected`.
+  A malformed JSON return with no safely enumerable finding has zero ledger
+  entries, not a fabricated finding. A rejected payload's reason is the exact
+  safe rejection message, not a bucket such as `invalid`; never include the
+  offending value.
+- Synthesized and filtered findings retain their original fields plus
+  `input_finding_ids` and provenance. Provenance contains the exact dedup
+  fingerprint `normalize(file) + line_bucket(line, +/-3) + normalize(title)`,
+  `submitters`, and `agreement_credit` arrays.
+- `submitters` contains only personas with an input finding in the merged
+  fingerprint group. `agreement_credit` contains only personas credited by the
+  cross-reviewer agreement boost without an input finding in that group. A
+  persona returning zero findings never appears in `submitters`; do not infer
+  submission from the report's Reviewer column.
+- A `filtered` finding remains available for human review with the validator's
+  stated reason, but is not part of the surviving/actioned set. Every input ID
+  contributing to a finding with `validated: false` receives disposition
+  `filtered` with the validator's exact one-sentence reason; it is not
+  `suppressed`, `rejected`, or silently excluded. A suppressed finding retains
+  its original confidence, including the P0 exception for confidence `0.50`
+  or higher.
+
+The artifact also includes applied fixes, residual actionable work,
+advisory-only outputs, coverage data, and the harness value. Alongside the
+findings, the parent writes `metadata.json` with the run ID, branch and HEAD
+captured at dispatch time, harness, verdict, and completion timestamp. The
+branch and HEAD are captured before autofixes land; metadata is written after
+the verdict is finalized. Existing artifacts without this additive metadata
+remain valid, with downstream consumers falling back to file mtime.
+
+Validation and persistence remain parent-side: no per-agent record or finding
+is written or merged until the complete persona payload passes schema and
+environment-value validation. Rejected or malformed persona returns do not
+fail the whole review; the review degrades while conforming returns continue
+through synthesis. Only an orchestration or storage failure that prevents the
+parent from producing the required run artifact is run-fatal.