@fro.bot/systematic 3.18.3 → 3.18.4

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

@@ -0,0 +1,391 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Code Review Pipeline Envelopes",
+  "description": "Structured output schemas for the model-authored envelopes of the ce:review synthesis pipeline (adjudication decisions, validator lifecycle results, and plan assessment). Helper-produced internal phase state (screen output, prepared state, merge output, finalize output) is intentionally excluded: it is TypeScript/Zod-only and never authored by a model.",
+  "definitions": {
+    "adjudicationEnvelope": {
+      "type": "object",
+      "properties": {
+        "decisions": {
+          "maxItems": 32,
+          "type": "array",
+          "items": {
+            "oneOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "decision_id": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 128,
+                    "pattern": "\\S"
+                  },
+                  "disposition": {
+                    "type": "string",
+                    "const": "merged"
+                  },
+                  "input_finding_ids": {
+                    "minItems": 2,
+                    "maxItems": 32,
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 128,
+                      "pattern": "\\S"
+                    }
+                  },
+                  "title": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 256,
+                    "pattern": "\\S",
+                    "description": "Short, specific issue title. 10 words or fewer."
+                  },
+                  "why_it_matters": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 2048,
+                    "pattern": "\\S",
+                    "description": "Non-empty impact and failure mode -- not 'what is wrong' but 'what breaks'"
+                  },
+                  "evidence": {
+                    "minItems": 1,
+                    "maxItems": 5,
+                    "type": "array",
+                    "items": {
+                      "anyOf": [
+                        {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 500,
+                          "allOf": [
+                            {
+                              "type": "string",
+                              "pattern": "\\S"
+                            },
+                            {
+                              "type": "string",
+                              "pattern": "^(?!\\/)(?![A-Za-z]:[\\\\/])(?!\\\\).+"
+                            }
+                          ],
+                          "description": "Bounded code-grounded evidence; absolute POSIX, drive-letter, and UNC paths are rejected"
+                        },
+                        {
+                          "type": "object",
+                          "properties": {
+                            "overflow": {
+                              "type": "boolean",
+                              "const": true,
+                              "description": "Explicit marker that the complete evidence did not fit in one bounded entry"
+                            },
+                            "excerpt": {
+                              "type": "string",
+                              "minLength": 1,
+                              "maxLength": 500,
+                              "allOf": [
+                                {
+                                  "type": "string",
+                                  "pattern": "\\S"
+                                },
+                                {
+                                  "type": "string",
+                                  "pattern": "^(?!\\/)(?![A-Za-z]:[\\\\/])(?!\\\\).+"
+                                }
+                              ],
+                              "description": "Bounded excerpt retained when evidence must be shortened"
+                            }
+                          },
+                          "required": ["overflow", "excerpt"],
+                          "additionalProperties": false
+                        }
+                      ]
+                    },
+                    "description": "Code-grounded evidence. At least 1 and at most 5 bounded entries; split evidence across entries or use an explicit overflow marker rather than silently truncating it."
+                  },
+                  "suggested_fix": {
+                    "description": "Concrete minimal fix. Omit or null if no good fix is obvious -- a bad suggestion is worse than none.",
+                    "anyOf": [
+                      {
+                        "type": "string",
+                        "maxLength": 2048
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "line": {
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991,
+                    "description": "Primary line number of the issue"
+                  },
+                  "disagreement_facts": {
+                    "maxItems": 32,
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 2048,
+                      "pattern": "\\S"
+                    }
+                  },
+                  "eligible_agreement_credit": {
+                    "maxItems": 64,
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 64,
+                      "pattern": "\\S",
+                      "description": "Persona name that produced this output (e.g., 'correctness', 'security')"
+                    }
+                  },
+                  "proposed_route": {
+                    "type": "object",
+                    "properties": {
+                      "autofix_class": {
+                        "type": "string",
+                        "enum": [
+                          "safe_auto",
+                          "gated_auto",
+                          "manual",
+                          "advisory"
+                        ],
+                        "description": "Reviewer's conservative recommendation for how this issue should be handled after synthesis"
+                      },
+                      "owner": {
+                        "type": "string",
+                        "enum": [
+                          "review-fixer",
+                          "downstream-resolver",
+                          "human",
+                          "release"
+                        ],
+                        "description": "Who should own the next action for this finding after synthesis"
+                      },
+                      "requires_verification": {
+                        "type": "boolean",
+                        "description": "Whether any fix for this finding must be re-verified with targeted tests or a follow-up review pass"
+                      }
+                    },
+                    "required": [
+                      "autofix_class",
+                      "owner",
+                      "requires_verification"
+                    ],
+                    "additionalProperties": false
+                  },
+                  "route_narrowing_reason": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 2048,
+                    "pattern": "\\S"
+                  }
+                },
+                "required": [
+                  "decision_id",
+                  "disposition",
+                  "input_finding_ids",
+                  "title",
+                  "why_it_matters",
+                  "evidence",
+                  "line"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "decision_id": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 128,
+                    "pattern": "\\S"
+                  },
+                  "disposition": {
+                    "type": "string",
+                    "const": "declined"
+                  },
+                  "input_finding_id": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 128,
+                    "pattern": "\\S"
+                  },
+                  "declined_reason": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 2048,
+                    "pattern": "\\S"
+                  },
+                  "disagreement_facts": {
+                    "maxItems": 32,
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 2048,
+                      "pattern": "\\S"
+                    }
+                  },
+                  "proposed_route": {
+                    "type": "object",
+                    "properties": {
+                      "autofix_class": {
+                        "type": "string",
+                        "enum": [
+                          "safe_auto",
+                          "gated_auto",
+                          "manual",
+                          "advisory"
+                        ],
+                        "description": "Reviewer's conservative recommendation for how this issue should be handled after synthesis"
+                      },
+                      "owner": {
+                        "type": "string",
+                        "enum": [
+                          "review-fixer",
+                          "downstream-resolver",
+                          "human",
+                          "release"
+                        ],
+                        "description": "Who should own the next action for this finding after synthesis"
+                      },
+                      "requires_verification": {
+                        "type": "boolean",
+                        "description": "Whether any fix for this finding must be re-verified with targeted tests or a follow-up review pass"
+                      }
+                    },
+                    "required": [
+                      "autofix_class",
+                      "owner",
+                      "requires_verification"
+                    ],
+                    "additionalProperties": false
+                  },
+                  "route_narrowing_reason": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 2048,
+                    "pattern": "\\S"
+                  }
+                },
+                "required": [
+                  "decision_id",
+                  "disposition",
+                  "input_finding_id",
+                  "declined_reason"
+                ],
+                "additionalProperties": false
+              }
+            ]
+          }
+        }
+      },
+      "required": ["decisions"],
+      "additionalProperties": false
+    },
+    "validatorLifecycleResult": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "outcome": {
+              "type": "string",
+              "const": "true"
+            }
+          },
+          "required": ["outcome"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "outcome": {
+              "type": "string",
+              "const": "false"
+            },
+            "reason": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 2048,
+              "pattern": "\\S"
+            }
+          },
+          "required": ["outcome", "reason"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "outcome": {
+              "type": "string",
+              "const": "failed"
+            },
+            "reason": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 2048,
+              "pattern": "\\S"
+            }
+          },
+          "required": ["outcome", "reason"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "outcome": {
+              "type": "string",
+              "const": "unavailable"
+            },
+            "reason": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 2048,
+              "pattern": "\\S"
+            }
+          },
+          "required": ["outcome", "reason"],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "planAssessmentEnvelope": {
+      "type": "object",
+      "properties": {
+        "verdict": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "pattern": "\\S"
+        },
+        "results": {
+          "maxItems": 32,
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "type": "string",
+                "enum": ["explicit_unmet_requirement", "inferred_gap"]
+              },
+              "description": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 2048,
+                "pattern": "\\S"
+              }
+            },
+            "required": ["kind", "description"],
+            "additionalProperties": false
+          }
+        }
+      },
+      "required": ["verdict", "results"],
+      "additionalProperties": false
+    }
+  }
+}

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

@@ -52,7 +52,7 @@ Rules:
 - You are a leaf reviewer inside an already-running systematic review workflow. Do not invoke systematic skills or agents unless this template explicitly instructs you to. Perform your analysis directly and return findings in the required output format only.
 - Every returned finding MUST include at least one evidence item grounded in the actual code. Detail fields are part of the returned payload, not a second output.
 - Evidence is bounded to at most 5 entries of at most 500 characters each. Split a longer trail across entries when it fits; otherwise retain a bounded `excerpt` with `{ "overflow": true, "excerpt": "..." }`. Never silently truncate evidence.
-- Finding paths MUST be repository-relative. The schema rejects absolute paths, while the parent-side validator in Unit 3 detects environment values because JSON Schema cannot infer where a string came from.
+- Finding paths MUST be repository-relative. The schema rejects absolute paths. Do not reproduce credential literals (API keys, tokens, passwords) in a finding's title, evidence, or fix; a source-level environment-variable reference (`process.env.API_KEY`, `${SECRET_TOKEN}`, and similar) is valid evidence and should be cited as such.
 - The parent adds `harness`, `dispatch_outcome`, and `disposition` after validating the return. Do not invent those parent-owned fields. The parent uses only the canonical values defined by the schema (`findings`, `empty`, `malformed`, `never_returned`, `validation_unavailable` and `surviving`, `merged`, `suppressed`, `filtered`, `rejected`).
 - Set pre_existing to true ONLY for issues in unchanged code that are unrelated to this diff. If the diff makes the issue newly relevant, it is NOT pre-existing.
 - You are operationally read-only. You may use non-mutating inspection commands, including read-oriented `git` / `gh` commands, to gather evidence. Do not write files, edit project files, change branches, commit, push, create PRs, or otherwise mutate the checkout or repository state.

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

@@ -28,11 +28,11 @@ 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, never-returned, or
-validation-unavailable persona, does not produce a per-agent file. If a later confidence or validation stage
+only for findings admitted after the parent completes schema validation. A
+finding rejected by schema validation is not persisted; other findings from
+the same return may proceed. A payload rejected at top level, or a rejected,
+never-returned, or validation-unavailable 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.
 
@@ -131,7 +131,7 @@ The artifact must preserve these distinctions:
   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
+  assign them input IDs. A finding-level schema rejection uses the same
   summary entry while admitted findings from that return continue normally.
   New writers must emit a rejected-summary row only for `findings` or
   `malformed`. The schema_version 1 validator deliberately continues to accept a
@@ -183,8 +183,8 @@ is finalized; consumers can therefore tell whether the artifact describes the
 current checkout.
 
 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
+is written or merged until that finding passes schema 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
@@ -193,37 +193,30 @@ required run artifact is run-fatal.
 
 ## Raw-return admission and validation availability
 
-Before a persona return is parsed into fields, screened for environment values,
-assessed for evidence, synthesized, or persisted, the parent admits it with the
-packaged structural validator:
-
-```bash
-# Resolve the validator relative to the skill's own directory.
-SKILL_DIR="<skill directory stated when this skill loads>";
-node "$SKILL_DIR/scripts/validate-review.mjs" return <<'REVIEW_RETURN_A1B2C3D4'
-<the persona's returned JSON payload, copied verbatim>
-REVIEW_RETURN_A1B2C3D4
-```
+Before a persona return is parsed into fields, assessed for evidence,
+synthesized, or persisted, the parent admits it with the packaged structural
+validator's `screen` phase, which structurally admits the return and binds it
+to the dispatched persona in one call, replacing the former separate
+raw-return-admission and dispatch-identity-binding steps. The full envelope,
+the invocation block, and the never-bypass rule are canonically defined in
+[pipeline invocation: screen](./pipeline-invocation.md#screen); this section
+states the resulting contract.
 
 Before each invocation, choose a fresh delimiter for that exact raw payload from
 a safe token alphabet (`A-Z`, `0-9`, `_`), verify the delimiter is absent as a
 complete line in that exact payload, and never reuse a fixed delimiter. The
-`REVIEW_RETURN_A1B2C3D4` token above is only an illustration. Open the heredoc
-with a single-quoted heredoc opener (`<<'DELIM'`) and close it with a line
-containing exactly that delimiter. The payload travels on stdin, never in argv;
-never use unquoted interpolation or command substitution, and never write the
-payload to a temp file.
+payload travels on stdin, never in argv, command substitution, or a temp file.
 
-The parent maps the result to `dispatch_outcome`, keeping lifecycle, structural
-validity, environment screening, and evidence assessment separate:
+The parent maps the result to `dispatch_outcome`, keeping lifecycle,
+structural validity, and evidence assessment separate:
 
 - **exit 0** — structurally admitted. Parse the already structurally validated
-  JSON without logging the raw text, then run the existing environment-value
-  screen over that parsed object before persistence. Zero findings is `empty`;
-  one or more findings is `findings`. Admission is structural only: it never
-  asserts that a finding's claims or cited evidence are true.
+  JSON without logging the raw text. Zero findings is `empty`; one or more
+  findings is `findings`. Admission is structural only: it never asserts that
+  a finding's claims or cited evidence are true.
 - **exit 1** — `malformed`. Record bounded validator diagnostics only; do not
-  parse, screen, or persist payload fields or values.
+  parse or persist payload fields or values. This covers malformed JSON, a
+  schema violation, and a dispatch identity mismatch alike.
 - **exit 2**, a missing or unreadable helper, or a launch failure — validation
   unavailable. Withhold the return and report the exact unavailability and what
   was withheld. Update that selected persona's preinitialized dispatch entry
@@ -236,14 +229,15 @@ validity, environment screening, and evidence assessment separate:
   task-lifecycle fact for a task that did not return. Validation unavailable is
   not malformed and is not never_returned.
 
-**Dispatch identity binding.** Structural admission does not prove who produced a
-return. Immediately after `exit 0` and before the environment-value screen,
-persistence, or synthesis, the parent parses the admitted return's `reviewer`
-field and confirms it equals the dispatched persona. A return whose `reviewer`
-does not match the dispatched persona is an identity mismatch: reject the whole
-return as `dispatch_outcome: "malformed"`, record only a bounded rejection reason
-naming the expected persona, set `run_status` to `degraded`, and do not admit,
-screen, persist, or synthesize its payload.
+**Dispatch identity binding** is folded into `screen`: it confirms the
+returned `reviewer` field matches the dispatched persona before it returns
+`exit 0`. A return whose `reviewer` does not match the dispatched persona is
+an identity mismatch: `screen` rejects the whole return as `dispatch_outcome:
+"malformed"`, and the parent records only a bounded rejection reason naming
+the expected persona, sets `run_status` to `degraded`, and does not admit,
+persist, or synthesize its payload. The stdin-only, flag-scoped validator
+cannot see dispatch context beyond `--reviewer`/`--harness`, so this
+comparison is `screen`'s own responsibility, not a separate parent step.
 
 `validation_unavailable` is an additive enum value: `schema_version` stays `1`,
 existing v1 artifacts remain valid, and no new field or migration is introduced.
@@ -256,34 +250,29 @@ that is a different object and phase, and these fields are never repurposed for
 raw-dispatch availability. These admission states are surfaced in the report's
 Coverage, which reports the exact unavailability and what was withheld.
 
-## 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`):
+## Sensitive-evidence handling
+
+Review artifacts may contain sensitive source-derived information. They are
+not certified secret-free.
+
+Reviewers must describe credential and secret-handling defects without
+reproducing credential values. Cite repository-relative locations and
+behavioral evidence instead of the value itself. An environment-variable
+reference appearing in reviewed source (`process.env.API_KEY`,
+`${SECRET_TOKEN}`, and similar) is valid evidence and is never rejected for
+being a reference.
+
+The parent must not deliberately log, cache, or write a raw return to a
+temporary file. Diagnostics stay allowlisted to persona name, JSON path, and a
+fixed reason (`schema validation` or `malformed JSON`):
 `Rejected persona <name> return: field <JSON path> failed <reason>.` Never
-echo the matched value.
+exception text, raw validation-library issue objects, candidate values, or
+variable names.
+
+These are handling instructions that reduce accidental disclosure, not
+technical containment. Real containment would require restricting reviewer
+inputs and capabilities at the harness boundary, which this portable Node
+helper does not provide.
 
 ## Artifact validation
 
@@ -387,8 +376,8 @@ 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. A coverage note alone cannot satisfy this rule;
+one finding from that other persona's return passed complete schema
+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