@fro.bot/systematic 3.12.2 → 3.12.4

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.2",
+  "version": "3.12.4",
   "description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
   "type": "module",
   "homepage": "https://fro.bot/systematic",

package/skills/ce-review/SKILL.md

@@ -452,22 +452,24 @@ 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, keep the parent-owned ledger through every later stage. See the [synthesis artifact contract](./references/synthesis-artifact-contract.md) for the input-ID and 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.
    - **Per-finding required:** title, severity, file, line, why_it_matters, confidence, evidence, autofix_class, owner, requires_verification, pre_existing.
    - **Schema constraints:** enforce every enum, type, confidence, line, path, evidence count, evidence length, and explicit overflow-marker bound from the schema. Empty evidence, absolute paths, and over-bound evidence are rejection cases, not truncation cases.
-   - **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.
+   - **Environment-value detection:** JSON Schema cannot determine where a string came from, so recursively inspect every string leaf in the parsed payload before writing. Apply the environment-value matching, structural-detector, and finding-granularity rules in the [synthesis artifact contract](./references/synthesis-artifact-contract.md). This detector is an additional parent-side check, not a schema claim.
+   - **Safe rejection message:** Use the safe rejection message rule in the [synthesis artifact contract](./references/synthesis-artifact-contract.md); never include the offending value, raw return, or validator parameters.
+   - **No partial writes:** Do not write or merge a finding until it passes the parent-side validation rules. Apply the admitted-finding persistence and rejected-payload ledger rules in the [synthesis artifact contract](./references/synthesis-artifact-contract.md). A valid admitted finding 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:** 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 or finding is rejected; record the rejection and apply the risk-aware verdict 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.** Reconcile admitted findings and rejected-payload summaries 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.
 
@@ -517,7 +519,7 @@ Assemble the final report using **pipe-delimited markdown tables for findings**
 9. **Agent-Native Gaps.** Surface agent-native-reviewer results. Omit section if no gaps found.
 10. **Deployment Notes.** If deployment-verification-agent ran, surface the key Go/No-Go items: blocking pre-deploy checks, the most important verification queries, rollback caveats, and monitoring focus areas. Keep the checklist actionable rather than dropping it into Coverage.
 11. **Coverage.** Suppressed count, residual risks, testing gaps, failed/timed-out reviewers, validator failures, and any intent uncertainty carried by non-interactive modes.
-12. **Verdict.** Ready to merge / Ready with fixes / Not ready. Fix order if applicable. When an `explicit` plan has unaddressed requirements, the verdict must reflect it — a PR that's code-clean but missing planned requirements is "Not ready" unless the omission is intentional. When an `inferred` plan has unaddressed requirements, note it in the verdict reasoning but do not block on it alone.
+12. **Verdict.** Ready to merge / Ready with fixes / Not ready. Fix order if applicable. When an `explicit` plan has unaddressed requirements, the verdict must reflect it — a PR that's code-clean but missing planned requirements is "Not ready" unless the omission is intentional. When an `inferred` plan has unaddressed requirements, note it in the verdict reasoning but do not block on it alone. Apply the risk-aware degraded verdict rule from the [synthesis artifact contract](./references/synthesis-artifact-contract.md).
 
 Do not include time estimates.
 
@@ -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,208 @@
+# 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 for findings admitted after the parent completes schema and
+environment-value validation. A finding rejected by environment-value
+detection is not persisted; other findings from the same return may proceed.
+A payload rejected at top level, or a rejected or never-returned persona,
+does not produce a per-agent file. 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": "testing",
+      "dispatch_outcome": "findings",
+      "input_finding_count": 1
+    },
+    {
+      "persona": "kieran-typescript",
+      "dispatch_outcome": "malformed",
+      "input_finding_count": 2,
+      "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"
+    },
+    {
+      "reviewer": "kieran-typescript",
+      "dispatch_outcome": "malformed",
+      "rejected_finding_count": 2,
+      "rejected_severities": ["P2", "P3"],
+      "disposition": "rejected",
+      "reason": "Rejected persona kieran-typescript return: field findings[0].evidence failed schema validation."
+    }
+  ],
+  "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": 2
+  }
+}
+```
+
+- `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 admitted finding receives an `input_id` of
+  `<reviewer>#<1-based finding index>`. Every admitted input has exactly one
+  final `disposition`: `surviving`, `merged`, `suppressed`, or `filtered`, plus
+  a reason. A rejected payload is represented by one summary ledger entry,
+  carrying the persona name, its `dispatch_outcome`, the
+  `rejected_finding_count` of findings not admitted, `disposition: "rejected"`,
+  `rejected_severities`, a list of the severities of the findings not
+  admitted as parsed from the payload, and the exact safe rejection message.
+  When a rejected finding's severity is absent, malformed, or not a valid
+  severity value, record it as `unknown`. Severity is metadata; recording it
+  never includes the offending value. Do not enumerate rejected findings or
+  assign them input IDs. A finding-level environment rejection uses the same
+  summary entry while admitted findings from that return continue normally.
+  Disposition counts are weighted by `rejected_finding_count` for that summary
+  entry, so their sum equals the total number of findings observed, not the
+  number of ledger rows. A malformed JSON return with no safely enumerable
+  finding has zero ledger entries, not a fabricated finding. Never include the
+  offending value in a rejection reason.
+- 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 that finding passes schema and environment-value
+validation. Rejected findings are recorded through the single rejected-payload
+ledger summary; admitted findings from the same return remain eligible for
+synthesis. 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.
+
+## Environment-value validation
+
+The parent recursively inspects every string leaf without logging the raw
+return or any matched value. Structural environment detectors remain
+unbounded and unchanged: `$NAME`, `${NAME}`, `process.env.NAME`,
+`os.environ[...]`, and `NAME=value` assignments using a known environment
+variable name are shape-based checks.
+
+Value-based matching uses only non-empty runtime environment values that are
+at least 16 characters long and are not composed solely of digits, dots,
+dashes, or path-separator characters (forward slash or backslash). A
+value is also eligible regardless of length when
+its variable name contains one of `TOKEN`, `SECRET`, `KEY`, `PASSWORD`,
+`PASSWD`, `CREDENTIAL`, `AUTH`, `SESSION`, `COOKIE`, `PRIVATE`, `_PASS`,
+`_PWD`, `PASSPHRASE`, or `_SALT`, matched as a case-insensitive substring.
+Entries containing an underscore are matched against the variable name as
+written; the underscore is deliberate and prevents matching benign names that
+merely contain the bare word. Values that satisfy neither condition are not
+matched. A match is an exact or embedded match.
+
+If the offending string is inside one finding, drop that finding and record it
+through the rejected-payload summary entry; the remaining findings continue
+through validation and synthesis. If the offending string is outside any
+finding, reject the whole payload. Every rejection uses only the persona name,
+JSON path, and a fixed reason (`schema validation`, `environment-value
+detection`, or `malformed JSON`):
+`Rejected persona <name> return: field <JSON path> failed <reason>.` Never
+echo the matched value.
+
+## Risk-aware degraded verdict
+
+The risk-critical surfaces are `security`, `data-migrations`, `api-contract`,
+`reliability`, and `performance`. They are the conditional personas selected
+specifically for the matching diff shape in Stage 3. If one of those selected
+personas has `dispatch_outcome: "malformed"` or
+`dispatch_outcome: "never_returned"`, the review verdict must not be clean:
+it is blocking unless another persona covered the same surface and returned
+validated evidence for it. For this rule, validated evidence means at least
+one finding from that other persona's return passed complete schema and
+environment-value validation and is relevant to the same surface. A coverage
+note alone cannot satisfy this rule; the verdict must reflect the missing
+risk-critical evidence.
+
+Finding-level rejection is keyed by the severities in
+`rejected_severities`. A selected risk-critical persona whose rejected
+findings include any `P0`, `P1`, or `unknown` severity is treated exactly as a
+rejected persona for this verdict rule: blocking unless another persona
+covered the same surface with validated evidence. A selected risk-critical
+persona whose rejected findings are only `P2` or `P3` does not block on that
+basis alone; record it in the Coverage section instead. Unknown severity is
+treated as blocking as deliberate fail-closed behavior because the parent
+could not determine what was lost. Admitted findings and verdict blocking
+are independent: surviving findings from the same return continue through
+synthesis normally. Partial return is not partial coverage when the lost
+part was critical.