@fro.bot/systematic 3.13.4 → 3.13.6

package/dist/cli.js

@@ -1988,7 +1988,10 @@ var MAX_FINDINGS = 32;
 var MAX_PERSONAS = 64;
 var REVIEW_ARTIFACT_CUSTOM_MESSAGES = [
   "severity count must match rejected finding count",
-  "filtered findings require a validation reason"
+  "filtered findings require a validation reason",
+  "risk-critical dispatches require a non-empty selection surface",
+  "satisfied risk coverage requires a citing input finding ID",
+  "unsatisfied risk coverage must not cite an input finding ID"
 ];
 var boundedText = (maxLength) => exports_external.string().min(1).max(maxLength).regex(/\S/);
 var DispatchOutcomeSchema = exports_external.enum([
@@ -2012,6 +2015,14 @@ var BranchSchema = exports_external.string().max(MAX_BRANCH_LENGTH);
 var HeadShaSchema = exports_external.string().regex(/^[0-9a-f]{40}$/);
 var CompletedAtSchema = exports_external.iso.datetime({ offset: false });
 var ReasonSchema = boundedText(MAX_REASON_LENGTH);
+var RISK_CRITICAL_PERSONAS = [
+  "security",
+  "data-migrations",
+  "api-contract",
+  "reliability",
+  "performance"
+];
+var RiskCriticalPersonaSchema = exports_external.enum(RISK_CRITICAL_PERSONAS);
 var FindingTitleSchema = boundedText(256);
 var SeveritySchema = exports_external.enum(["P0", "P1", "P2", "P3", "unknown"]);
 var FindingSeveritySchema = SeveritySchema.exclude(["unknown"]);
@@ -2098,8 +2109,18 @@ var DispatchSchema = exports_external.object({
   persona: ReviewerSchema,
   dispatch_outcome: DispatchOutcomeSchema,
   input_finding_count: exports_external.number().int().nonnegative().max(MAX_FINDINGS),
-  rejection_reason: ReasonSchema.optional()
-}).strict();
+  rejection_reason: ReasonSchema.optional(),
+  selection_surface: exports_external.array(RepoRelativePathSchema).max(MAX_FINDINGS).optional(),
+  selection_reason: ReasonSchema.optional()
+}).strict().superRefine((dispatch, ctx) => {
+  if (RISK_CRITICAL_PERSONAS.includes(dispatch.persona) && (!dispatch.selection_surface || dispatch.selection_surface.length === 0)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["selection_surface"],
+      message: REVIEW_ARTIFACT_CUSTOM_MESSAGES[2]
+    });
+  }
+});
 var DispositionCountsSchema = exports_external.object({
   surviving: exports_external.number().int().nonnegative().max(MAX_FINDINGS * MAX_PERSONAS),
   merged: exports_external.number().int().nonnegative().max(MAX_FINDINGS * MAX_PERSONAS),
@@ -2116,6 +2137,31 @@ var CoverageSchema = exports_external.object({
   validator_failures: exports_external.array(ReasonSchema).max(MAX_PERSONAS),
   intent_uncertainty: exports_external.array(ReasonSchema).max(MAX_PERSONAS)
 }).strict();
+var DeclinedMergeSchema = exports_external.object({
+  file: RepoRelativePathSchema,
+  input_finding_ids: exports_external.array(boundedText(MAX_INPUT_ID_LENGTH)).min(2).max(MAX_FINDINGS),
+  reason: ReasonSchema
+}).strict();
+var RiskCoverageSchema = exports_external.object({
+  persona: RiskCriticalPersonaSchema,
+  satisfied: exports_external.boolean(),
+  input_finding_id: boundedText(MAX_INPUT_ID_LENGTH).optional()
+}).strict().superRefine((coverage, ctx) => {
+  if (coverage.satisfied && coverage.input_finding_id === undefined) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["input_finding_id"],
+      message: REVIEW_ARTIFACT_CUSTOM_MESSAGES[3]
+    });
+  }
+  if (!coverage.satisfied && coverage.input_finding_id !== undefined) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["input_finding_id"],
+      message: REVIEW_ARTIFACT_CUSTOM_MESSAGES[4]
+    });
+  }
+});
 var ReviewArtifactSchema = exports_external.object({
   schema_version: exports_external.literal(1),
   run_id: boundedText(MAX_RUN_ID_LENGTH),
@@ -2134,6 +2180,8 @@ var ReviewArtifactSchema = exports_external.object({
   dispatches: exports_external.array(DispatchSchema).max(MAX_PERSONAS),
   input_findings: exports_external.array(InputFindingSchema).max(MAX_FINDINGS * MAX_PERSONAS),
   findings: exports_external.array(SynthesizedFindingSchema).max(MAX_FINDINGS),
+  declined_merges: exports_external.array(DeclinedMergeSchema).max(MAX_FINDINGS).optional(),
+  risk_coverage: exports_external.array(RiskCoverageSchema).max(MAX_PERSONAS).optional(),
   disposition_counts: DispositionCountsSchema,
   applied_fixes: exports_external.array(ReasonSchema).max(MAX_FINDINGS),
   residual_actionable_work: exports_external.array(ReasonSchema).max(MAX_FINDINGS),

package/dist/lib/review-artifact-schema.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-export declare const REVIEW_ARTIFACT_CUSTOM_MESSAGES: readonly ['severity count must match rejected finding count', 'filtered findings require a validation reason'];
+export declare const REVIEW_ARTIFACT_CUSTOM_MESSAGES: readonly ['severity count must match rejected finding count', 'filtered findings require a validation reason', 'risk-critical dispatches require a non-empty selection surface', 'satisfied risk coverage requires a citing input finding ID', 'unsatisfied risk coverage must not cite an input finding ID'];
 export declare const DispatchOutcomeSchema: z.ZodEnum<{
     empty: "empty";
     findings: "findings";
@@ -134,6 +134,8 @@ export declare const ReviewArtifactSchema: z.ZodObject<{
         }>;
         input_finding_count: z.ZodNumber;
         rejection_reason: z.ZodOptional<z.ZodString>;
+        selection_surface: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        selection_reason: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     input_findings: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         record_type: z.ZodLiteral<"admitted">;
@@ -218,6 +220,22 @@ export declare const ReviewArtifactSchema: z.ZodObject<{
             agreement_credit: string[];
         };
     }>>>;
+    declined_merges: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        input_finding_ids: z.ZodArray<z.ZodString>;
+        reason: z.ZodString;
+    }, z.core.$strict>>>;
+    risk_coverage: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        persona: z.ZodEnum<{
+            "api-contract": "api-contract";
+            "data-migrations": "data-migrations";
+            performance: "performance";
+            reliability: "reliability";
+            security: "security";
+        }>;
+        satisfied: z.ZodBoolean;
+        input_finding_id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
     disposition_counts: z.ZodObject<{
         surviving: z.ZodNumber;
         merged: z.ZodNumber;

package/package.json

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

package/skills/ce-review/SKILL.md

@@ -360,6 +360,10 @@ Review team:
 
 This is progress reporting, not a blocking confirmation.
 
+Record each conditional persona's selection reason and triggering file paths
+on its dispatch record; see the [synthesis artifact contract](./references/synthesis-artifact-contract.md)
+for the field semantics.
+
 ### Stage 3b: Discover project standards paths
 
 Before spawning sub-agents, find the file paths (not contents) of all relevant standards files for the `project-standards` persona. Use the native file-search/glob tool to locate:
@@ -468,8 +472,10 @@ Before applying the confidence gate, keep the parent-owned ledger through every
    - **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 according to the [synthesis artifact contract](./references/synthesis-artifact-contract.md).
+3. **Deduplicate.** Group all gated findings by `normalize(file)`. A file with two or more findings from different personas forms a candidate group. Do not use line number to form groups. Sort findings within each group by line. Adjudicate each candidate group: merge findings judged to describe the same underlying defect; keep genuinely different defects separate. Adjacency creates a candidate, not a conclusion -- findings on the same line that describe different defects must not merge. For each resulting finding, derive the fingerprint from its file and line as `normalize(file) + "|" + line`. Keep highest severity, keep highest confidence, and retain the input IDs that produced the merged entry. Record each declined merge in the artifact's optional `declined_merges` field with the normalized file, input finding IDs considered but not merged, and a brief reason. A singleton that passes the gate is `surviving`; each input in a multi-input merge is provisionally `merged`.
+
+   Worked example: at `src/lib/model-availability.ts:139`, reliability's `Config hook awaits providers API without a timeout` and adversarial's `Config startup can hang forever behind a stalled /config` describe the same underlying defect in different words, so they merge.
+4. **Cross-reviewer agreement.** When an adjudicated merge contains findings from 2+ independent reviewers, 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.
@@ -518,8 +524,8 @@ Assemble the final report using **pipe-delimited markdown tables for findings**
 8. **Learnings & Past Solutions.** Surface learnings-researcher results: if past solutions are relevant, flag them as "Known Pattern" with links to docs/solutions/ files.
 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. Apply the risk-aware degraded verdict rule from the [synthesis artifact contract](./references/synthesis-artifact-contract.md).
+11. **Coverage.** Suppressed count, residual risks, testing gaps, failed/timed-out reviewers, validator failures, risk-coverage entries with citing input finding IDs and exit conditions for blocked entries, 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. Apply the risk-aware degraded verdict rule from the [synthesis artifact contract](./references/synthesis-artifact-contract.md), including the recorded exit condition for a blocked risk-critical verdict.
 
 Do not include time estimates.
 
@@ -596,7 +602,7 @@ Review complete
 
 **Detail enrichment (headless only):** The headless envelope includes `Why:`, `Evidence:`, and `Suggested fix:` lines. After merge (Stage 5), use the validated full persona returns retained in parent memory for only the findings that survived dedup and confidence gating.
    - **Field tiers:** `Why:` and `Evidence:` are detail-tier and are already present in the validated inline return. `Suggested fix:` is also available directly from that return and survives merge as optional fix context.
-   - **In-memory matching:** For each surviving finding, look up its detail-tier fields in the validated returns of the contributing reviewers. Match on `file + line_bucket(line, +/-3)` (the same tolerance used in Stage 5 dedup). When multiple entries fall within the line bucket, apply `normalize(title)` to the merged finding's title and each candidate entry's title as a tie-breaker.
+   - **In-memory matching:** For each surviving finding, look up its detail-tier fields in the validated returns of the contributing reviewers. Use the merged finding's `input_finding_ids` (`<reviewer>#<1-based finding index>`) to identify the contributing return and source finding. When an input ID cannot be resolved or multiple candidates remain, match on normalized `file`, then use line and `normalize(title)` only as tie-breakers.
    - **Reviewer order:** Try contributing reviewers in the order they appear in the merged finding's reviewer list; use the first validated match.
    - **No-match fallback:** If no validated in-memory return contains a match, omit the `Why:` and `Evidence:` lines for that finding and note the gap in Coverage. This should indicate a synthesis/matching gap, not a failed artifact-file write. Never re-read per-agent files to recover detail.
 

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

@@ -137,7 +137,7 @@ This fails because: no pipe-delimited tables, no severity-grouped `###` headers,
 - **Learnings & Past Solutions section** -- results from learnings-researcher, with links to docs/solutions/ files
 - **Agent-Native Gaps section** -- results from agent-native-reviewer. Omit if no gaps found.
 - **Deployment Notes section** -- key checklist items from deployment-verification-agent. Omit if the agent did not run.
-- **Coverage section** -- suppressed count with original confidences, residual risks, testing gaps, failed reviewers, and disposition reconciliation
+- **Coverage section** -- suppressed count with original confidences, residual risks, testing gaps, failed reviewers, disposition reconciliation, and risk-coverage entries with their citing input finding IDs and blocked-entry exit conditions
 - **Summary uses blockquotes** for verdict, reasoning, and fix order
 - **Horizontal rule** (`---`) separates findings from verdict
 - **`###` headers** for each section -- never plain text headers

package/skills/ce-review/references/review-summary-schema.json

@@ -69,6 +69,31 @@
             "minLength": 1,
             "maxLength": 2048,
             "pattern": "\\S"
+          },
+          "selection_surface": {
+            "maxItems": 32,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 256,
+              "allOf": [
+                {
+                  "type": "string",
+                  "pattern": "\\S"
+                },
+                {
+                  "type": "string",
+                  "pattern": "^(?!\\/)(?![A-Za-z]:[\\\\/])(?!\\\\).+"
+                }
+              ]
+            }
+          },
+          "selection_reason": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2048,
+            "pattern": "\\S"
           }
         },
         "required": ["persona", "dispatch_outcome", "input_finding_count"],
@@ -374,6 +399,79 @@
         "additionalProperties": false
       }
     },
+    "declined_merges": {
+      "maxItems": 32,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "file": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256,
+            "allOf": [
+              {
+                "type": "string",
+                "pattern": "\\S"
+              },
+              {
+                "type": "string",
+                "pattern": "^(?!\\/)(?![A-Za-z]:[\\\\/])(?!\\\\).+"
+              }
+            ]
+          },
+          "input_finding_ids": {
+            "minItems": 2,
+            "maxItems": 32,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 128,
+              "pattern": "\\S"
+            }
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2048,
+            "pattern": "\\S"
+          }
+        },
+        "required": ["file", "input_finding_ids", "reason"],
+        "additionalProperties": false
+      }
+    },
+    "risk_coverage": {
+      "maxItems": 64,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "persona": {
+            "type": "string",
+            "enum": [
+              "security",
+              "data-migrations",
+              "api-contract",
+              "reliability",
+              "performance"
+            ]
+          },
+          "satisfied": {
+            "type": "boolean"
+          },
+          "input_finding_id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "pattern": "\\S"
+          }
+        },
+        "required": ["persona", "satisfied"],
+        "additionalProperties": false
+      }
+    },
     "disposition_counts": {
       "type": "object",
       "properties": {

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

@@ -78,12 +78,19 @@ The artifact must preserve these distinctions:
       "title": "<merged finding>",
       "input_finding_ids": ["correctness#2", "testing#1"],
       "provenance": {
-        "fingerprint": "<normalize(file) + line_bucket(line, +/-3) + normalize(title)>",
+        "fingerprint": "<normalize(file) + \"|\" + line>",
         "submitters": ["correctness", "testing"],
         "agreement_credit": []
       }
     }
   ],
+  "declined_merges": [
+    {
+      "file": "src/example.ts",
+      "input_finding_ids": ["correctness#3", "testing#2"],
+      "reason": "The findings concern separate validation paths."
+    }
+  ],
   "disposition_counts": {
     "surviving": 0,
     "merged": 2,
@@ -98,7 +105,10 @@ The artifact must preserve these distinctions:
   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.
+  outcome is separate from finding disposition. Conditional selections record
+  their triggering changed-file paths in `selection_surface` and the announced
+  selection explanation in `selection_reason`; always-on personas may omit
+  both fields.
 - `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
@@ -119,12 +129,24 @@ The artifact must preserve these distinctions:
   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
+  `input_finding_ids` and provenance. Provenance contains the fingerprint
+  `normalize(file) + "|" + line`, derived from the merged finding's file and
+  line, plus `submitters` and `agreement_credit` arrays.
+- `declined_merges` is optional. For each candidate group that is not merged,
+  record the normalized file, the input finding IDs considered and not merged,
+  and a brief reason. Candidate groups contain two or more findings from
+  different personas on the same normalized file; sort their findings by line.
+  Adjacency creates a candidate, not a conclusion: genuinely different
+  defects on the same line remain separate.
+- A candidate group may resolve partially. When some findings in a group merge
+  and others stay separate, record one entry per declined separation, listing
+  the input finding IDs on both sides of it. A group of three where two merge
+  and one stays separate records a single entry naming all three IDs, with a
+  reason describing why the third is a different defect. Record the separation,
+  not the merge; a fully merged group produces no entry.
+- `submitters` contains only personas with an input finding in the adjudicated
+  merge. `agreement_credit` contains only personas credited by the
+  cross-reviewer agreement boost without an input finding in that merge. 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
@@ -227,18 +249,20 @@ The risk-critical surfaces are `security`, `data-migrations`, `api-contract`,
 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
+it is blocking unless another persona covered the lost surface with validated
+evidence. For this rule, a validated finding from another persona covers a
+lost risk-critical surface if and only if the finding's `file` appears in the
+lost persona's recorded `selection_surface`; 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.
+environment-value validation. 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
+covered the lost surface with a validated finding whose `file` appears in the
+lost persona's recorded `selection_surface`. 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
@@ -246,3 +270,12 @@ 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.
+
+Record each lost risk-critical persona in the optional `risk_coverage` array
+with `satisfied: true` and `input_finding_id` set to the citing input finding
+ID when coverage is satisfied, or `satisfied: false` without an
+`input_finding_id` otherwise. A blocked verdict must name its exit condition
+in the report: re-run the lost persona, or supply a validated finding from
+another persona whose `file` appears in the lost persona's recorded
+`selection_surface`. Derive that condition from the dispatch and risk-coverage
+records, not from a coverage note.