@fro.bot/systematic 3.17.0 → 3.18.0

package/skills/ce-review/references/persona-catalog.md

@@ -1,6 +1,6 @@
 # Persona Catalog
 
-13 reviewer personas organized into always-on, cross-cutting conditional, and stack-specific conditional layers, plus CE-specific agents. The orchestrator uses this catalog to select which reviewers to spawn for each review.
+13 reviewer personas organized into a three-persona core, cross-cutting conditional, and stack-specific conditional layers, plus CE-specific conditional agents. The orchestrator uses this catalog to select which reviewers to spawn for each review.
 
 ## Shared persona pool
 
@@ -10,38 +10,29 @@ The `agents/review/` directory is a shared persona pool, not `ce:review`'s roste
 - `systematic:review:pattern-recognition-specialist` — dispatched by `deepen-plan`, `ce-plan`'s deepening workflow, and `ce-compound` for consistency, duplication, and pattern analysis.
 - `systematic:review:code-simplicity-reviewer` — dispatched by `ce-compound` for code-heavy issues.
 
-## Always-on (4 personas + 2 CE agents)
+## Always-on (3 core personas)
 
-Spawned on every review regardless of diff content.
-
-**Persona agents (structured JSON output):**
+Selected on every review regardless of diff content. These three are the only reviewers with no selection condition.
 
 | Persona | Agent | Focus |
 |---------|-------|-------|
 | `correctness` | `systematic:review:correctness-reviewer` | Logic errors, edge cases, state bugs, error propagation, intent compliance |
 | `testing` | `systematic:review:testing-reviewer` | Coverage gaps, weak assertions, brittle tests, missing edge case tests |
-| `maintainability` | `systematic:review:maintainability-reviewer` | Coupling, complexity, naming, dead code, premature abstraction |
 | `project-standards` | `systematic:review:project-standards-reviewer` | AGENTS.md compliance -- frontmatter, references, naming, cross-platform portability, tool selection |
 
-**CE agents (unstructured output, synthesized separately):**
-
-| Agent | Focus |
-|-------|-------|
-| `systematic:review:agent-native-reviewer` | Verify new features are agent-accessible |
-| `systematic:research:learnings-researcher` | Search docs/solutions/ for past issues related to this PR's modules and patterns |
-
-## Conditional (8 personas)
+## Conditional (9 personas)
 
-Spawned when the orchestrator identifies relevant patterns in the diff. The orchestrator reads the full diff and reasons about selection -- this is agent judgment, not keyword matching.
+Spawned only when the orchestrator identifies a relevant surface in the diff. The orchestrator reads the full diff and reasons about selection -- this is agent judgment, not keyword matching. Record `selection_reason` and a non-empty `selection_surface` for each selected conditional persona.
 
 | Persona | Agent | Select when diff touches... |
 |---------|-------|---------------------------|
+| `maintainability` | `systematic:review:maintainability-reviewer` | Materially adds or reshapes abstractions, raises cross-module coupling, adds state/control-flow complexity, changes naming or ownership structure, removes dead code, or performs a broad refactor. Do not select it for a tiny prose or fixture correction with no structural decision and no user- or agent-facing or other specialist surface. |
 | `security` | `systematic:review:security-reviewer` | Auth middleware, public endpoints, user input handling, permission checks, secrets management |
 | `performance` | `systematic:review:performance-reviewer` | Database queries, ORM calls, loop-heavy data transforms, caching layers, async/concurrent code |
 | `api-contract` | `systematic:review:api-contract-reviewer` | Route definitions, serializer/interface changes, event schemas, exported type signatures, API versioning |
 | `data-migrations` | `systematic:review:data-migrations-reviewer` | Migration files, schema changes, backfill scripts, data transformations |
 | `reliability` | `systematic:review:reliability-reviewer` | Error handling, retry logic, circuit breakers, timeouts, background jobs, async handlers, health checks |
-| `adversarial` | `systematic:review:adversarial-reviewer` | Diff has >=50 changed lines of executable code (not prose/instruction Markdown, JSON schemas, or config), OR touches auth, payments, data mutations, external API integrations, or other high-risk domains regardless of file type |
+| `adversarial` | `systematic:review:adversarial-reviewer` | >=50 changed lines of executable production code, excluding tests, generated files, lockfiles, instruction/prose Markdown, JSON schemas, and config; OR regardless of file type for auth, payments, data mutations, external APIs, or another explicitly high-risk domain |
 | `cli-readiness` | `systematic:review:cli-readiness-reviewer` | CLI command definitions, argument parsing, CLI framework usage, command handler implementations |
 | `previous-comments` | `systematic:review:previous-comments-reviewer` | **PR-only.** Reviewing a PR that has existing review comments or review threads from prior review rounds. Skip entirely when no PR metadata was gathered in Stage 1. |
 
@@ -53,18 +44,41 @@ These reviewers keep their original opinionated lens. They are additive with the
 |---------|-------|---------------------------|
 | `kieran-typescript` | `systematic:review:kieran-typescript-reviewer` | TypeScript components, services, hooks, utilities, or shared types |
 
-## CE Conditional Agents (migration-specific)
+## CE Conditional Agents (3)
 
-These CE-native agents provide specialized analysis beyond what the persona agents cover. Spawn them when the diff includes database migrations, schema.rb, or data backfills.
+These CE-native agents provide specialized analysis beyond what the persona agents cover. Their output is unstructured and synthesized separately; they never receive a raw-return dispatch record. Announce and report their selection reason/surface in the team and Coverage instead.
 
-| Agent | Focus |
-|-------|-------|
-| `systematic:review:deployment-verification-agent` | Produces Go/No-Go deployment checklist with SQL verification queries and rollback procedures |
+| Agent | Select when diff includes... |
+|-------|------------------------------|
+| `systematic:review:agent-native-reviewer` | A user- or agent-facing UI, CLI, tool, or workflow capability, or a changed access path where agent parity or discoverability is material. Do not select it for every review. |
+| `systematic:research:learnings-researcher` | Bug, regression, or hardening work; a recurring failure class; a change to a documented solution or module; or a plan/PR that cites relevant prior art. Do not select it for every review. |
+| `systematic:review:deployment-verification-agent` | Database migrations (`db/migrate/*.rb`, `db/schema.rb`) or data backfill scripts. |
 
 ## Selection rules
 
-1. **Always spawn all 4 always-on personas** plus the 2 CE always-on agents.
-2. **For each cross-cutting conditional persona**, the orchestrator reads the diff and decides whether the persona's domain is relevant. This is a judgment call, not a keyword match.
+1. **Always select exactly the three core personas:** `correctness`, `testing`, and `project-standards`. Nothing else is always-on.
+2. **For each cross-cutting conditional persona**, read the diff and decide whether the persona's domain is relevant. This is a judgment call, not a keyword match. A tiny prose or fixture correction is core-only only when it has no structural decision and no user- or agent-facing behavior, access change, or other specialist surface; a structural refactor may add `maintainability`; an auth feature may add `security` and `reliability`.
 3. **For each stack-specific conditional persona**, use file types and changed patterns as a starting point, then decide whether the diff actually introduces meaningful work for that reviewer. Do not spawn language-specific reviewers just because one config or generated file happens to match the extension.
-4. **For CE conditional agents**, spawn when the diff includes migration files (`db/migrate/*.rb`, `db/schema.rb`) or data backfill scripts.
-5. **Announce the team** before spawning with a one-line justification per conditional reviewer selected.
+4. **For CE conditional agents**, select `agent-native-reviewer` for agent-facing capability changes, `learnings-researcher` for bug/regression/hardening or recurring-defect work, and `deployment-verification-agent` for migrations or data backfills. Their output is unstructured; report their selection reason/surface in the team and Coverage rather than a dispatch record.
+5. **Record selection metadata.** Every selected structured conditional persona records `selection_reason` and a non-empty `selection_surface`; core personas may omit both.
+6. **Announce the team** before spawning with a one-line rationale and the triggering repository-relative paths/surfaces per selected conditional. Distinguish core reviewers, selected conditionals, an explicit "no conditional selected" case, and selected-but-failed/malformed/validation-unavailable reviewers. Never label an unselected reviewer as failed.
+7. **Reviewer count is an outcome, not a target.** Never restore a fixed floor; a smaller selected set is not automatically better or worse than a larger one.
+
+## Selection scenarios
+
+| Scenario | Selected |
+|----------|----------|
+| Tiny prose or fixture correction with no structural decision and no user- or agent-facing or other specialist surface | `correctness`, `testing`, `project-standards` only; no runtime probe |
+| Structural refactor adding or reshaping abstractions, coupling, state, or control flow | core plus `maintainability` |
+| Agent-facing UI/CLI/tool/workflow capability or changed access path | core plus CE `agent-native-reviewer` |
+| Bug, regression, or hardening work; recurring failure class; documented solution/module touched; plan/PR citing prior art | core plus CE `learnings-researcher` |
+| Auth surface | core plus `security` |
+| Migration or backfill | core plus `data-migrations` and CE `deployment-verification-agent` |
+| Public API/route/serializer/type-signature change | core plus `api-contract` |
+| Error handling, retries, timeouts, background jobs | core plus `reliability` |
+| Query, loop, caching, or concurrency hot path | core plus `performance` |
+| Renderer or asset-delivery change needing runtime evidence | a focused execution probe (independent of reviewer selection); a change that separately triggers a conditional still selects that reviewer |
+
+## Execution probes (separate parent decision)
+
+A focused execution probe is independent of reviewer selection. A pure renderer or asset-delivery change with no conditional surface may be core plus a probe, but a change that separately triggers `agent-native-reviewer`, `security`, or another conditional still selects those reviewers. An execution probe is not a reviewer and never substitutes for risk-critical reviewer coverage; selecting a probe never adds `maintainability` and never restores a reviewer floor. When selected, record the probe target and its permission boundary in Coverage.

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

@@ -134,10 +134,10 @@ This fails because: no pipe-delimited tables, no severity-grouped `###` headers,
 - **Residual Actionable Work section** -- include only when unresolved actionable findings were handed off for later work
 - **Pre-existing section** -- separate table, no confidence column (these are informational)
 - **Filtered (not validated) section** -- findings where Stage 5b returned `validated: false`. Rendered as a pipe-delimited table with columns `#`, `File`, `Issue`, `Reviewer`, `Confidence`, `Validator reason`. These findings are surfaced for human review, not removed. Omit this section when Stage 5b produced no filtered findings.
-- **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.
+- **Learnings & Past Solutions section** -- render only when CE `learnings-researcher` was selected and returned relevant output; results with links to docs/solutions/ files. Omit otherwise.
+- **Agent-Native Gaps section** -- render only when CE `agent-native-reviewer` was selected and returned relevant output. Omit otherwise.
 - **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, disposition reconciliation, and risk-coverage entries with their citing input finding IDs and blocked-entry exit conditions
+- **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. For raw returns, distinguish `findings`, `empty`, `malformed`, `never_returned`, `validation_unavailable` (the persisted raw dispatch outcome, distinct from the artifact-level `validation.status: "unavailable"`), and `environment-screen` rejection, and state what was admitted or withheld
 - **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

@@ -57,7 +57,13 @@
           },
           "dispatch_outcome": {
             "type": "string",
-            "enum": ["findings", "empty", "malformed", "never_returned"]
+            "enum": [
+              "findings",
+              "empty",
+              "malformed",
+              "never_returned",
+              "validation_unavailable"
+            ]
           },
           "input_finding_count": {
             "type": "integer",

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

@@ -24,7 +24,7 @@ The supplied diff is the primary source of truth. Use the supplied paths and lin
 <output-contract>
 Return exactly one JSON payload to the parent. The payload contains the complete schema for every finding, including both the merge tier and the detail tier (`why_it_matters`, `evidence`, and `suggested_fix` when present).
 
-Do not write any file. Do not use a Run ID or an artifact path. Persistence is owned by the parent orchestrator: it validates this returned payload, adds parent-owned provenance, and writes only conforming data. This rule is the same in every supported harness.
+Do not write any file. Do not use a Run ID or an artifact path. Persistence is owned by the parent orchestrator: it structurally validates this returned payload with the packaged validator before it parses any field, adds parent-owned provenance, and writes only conforming data. Return exactly one JSON payload; never wrap it in prose, markdown, or a parent-owned annotation. This rule is the same in every supported harness.
 
 The schema below defines the payload's fields and bounds. Its transport is inline for this contract; any schema metadata describing a compact return or a separate detail artifact is superseded by this output contract.
 
@@ -53,7 +53,7 @@ Rules:
 - 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.
-- 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` and `surviving`, `merged`, `suppressed`, `filtered`, `rejected`).
+- 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.
 - Set `autofix_class` accurately -- not every finding is `advisory`. Use this decision guide:
@@ -78,6 +78,10 @@ Reviewer name: {reviewer_name}
 
 Intent: {intent_summary}
 
+Selection reason: {selection_reason}
+
+Selection surface: {selection_surface}
+
 Changed files: {file_list}
 
 Diff:
@@ -97,3 +101,5 @@ Diff:
 | `{file_list}` | Stage 1 output | List of changed files from the scope step |
 | `{diff}` | Stage 1 output | The actual diff content to review |
 | `{reviewer_name}` | Stage 3 output | Persona name used in the returned `reviewer` field |
+| `{selection_reason}` | Stage 3 output | One-line reason this conditional persona was selected. Empty for core personas, which have no selection condition |
+| `{selection_surface}` | Stage 3 output | Non-empty repository-relative paths/surfaces that triggered selection. Empty for core personas. These are bounded domain hints for the reviewer, not fields of the returned payload |

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

@@ -19,7 +19,10 @@ run artifact for a run that never started.
 
 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
+entry as returns arrive. A persona that returned but whose raw validator could
+not run is updated from `never_returned` to `dispatch_outcome:
+"validation_unavailable"`; it is never omitted and never left as
+`never_returned`. 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.
@@ -28,8 +31,8 @@ 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
+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.
 
@@ -108,8 +111,9 @@ The artifact must preserve these distinctions:
 ```
 
 - `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,
+  records what a persona returned: `findings`, `empty`, `malformed`,
+  `never_returned`, or `validation_unavailable`. 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. Conditional selections record
   their triggering changed-file paths in `selection_surface` and the announced
@@ -129,6 +133,13 @@ The artifact must preserve these distinctions:
   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.
+  New writers must emit a rejected-summary row only for `findings` or
+  `malformed`. The schema_version 1 validator deliberately continues to accept a
+  historical `empty` or `never_returned` rejected-summary row for backward
+  compatibility with existing artifacts, but that reader leniency is not
+  authoring permission to emit either. The validator rejects a rejected-summary
+  row for `validation_unavailable`, the additive outcome this contract
+  introduces, and writers must never emit it.
   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
@@ -180,6 +191,71 @@ 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.
 
+## 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 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.
+
+The parent maps the result to `dispatch_outcome`, keeping lifecycle, structural
+validity, environment screening, 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.
+- **exit 1** — `malformed`. Record bounded validator diagnostics only; do not
+  parse, screen, or persist payload fields or values.
+- **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
+  from `never_returned` to `dispatch_outcome: "validation_unavailable"` with
+  `input_finding_count: 0` and, optionally, a safe `rejection_reason` naming the
+  exit status, missing helper, or launch failure without payload values. Set
+  `run_status` to `degraded`. Never omit the dispatch entry, never leave it as
+  `never_returned`, never label it `malformed`, never admit the payload, and
+  never fabricate a rejected-summary ledger row. `never_returned` is a
+  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.
+
+`validation_unavailable` is an additive enum value: `schema_version` stays `1`,
+existing v1 artifacts remain valid, and no new field or migration is introduced.
+A run that contains `validation_unavailable` evidence records a zero
+`input_finding_count`, no admitted input finding for that persona, and a
+non-`completed` run status; unavailable evidence can never finalize as a clean,
+completed run.
+The word `unavailable` also names the artifact-level `validation.status` value;
+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
@@ -217,10 +293,18 @@ validating it. This ordering makes the artifact validatable at all: without
 a real validation result.
 
 After writing `review-summary.json`, the parent resolves and runs a validator
-in this order: the bundled `systematic-validate-review-artifact <path>` command
-first, then the npm-installed `systematic validate-review-artifact <path>`
-command. Both can be present at once. The bundled command ships beside the
-prose being executed, so it is the one whose behavior matches the contract.
+in this order: the skill-local helper first, then the bundled
+`systematic-validate-review-artifact <path>` command, then the npm-installed
+`systematic validate-review-artifact <path>` command. All can be present at
+once. The skill-local helper ships beside the prose being executed, so it is
+the one whose behavior matches the contract; the other two remain fallbacks.
+
+```bash
+# Resolve the validator relative to the skill's own directory.
+SKILL_DIR="<skill directory stated when this skill loads>";
+ARTIFACT_PATH="<review-summary.json path>";
+node "$SKILL_DIR/scripts/validate-review.mjs" artifact "$ARTIFACT_PATH"
+```
 The parent runs the first command it resolves and reads its result; it does not
 merely test whether a name is on `PATH`, because a version-manager shim can be
 present there and fail on every invocation.
@@ -296,8 +380,9 @@ against at all.
 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:
+personas has `dispatch_outcome: "malformed"`,
+`dispatch_outcome: "never_returned"`, or `dispatch_outcome:
+"validation_unavailable"`, the review verdict must not be clean:
 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