@fro.bot/systematic 3.26.1 → 3.26.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -77,23 +77,33 @@ required_fields:
77
77
  component:
78
78
  type: enum
79
79
  values:
80
+ - backend
81
+ - frontend
82
+ - api
83
+ - database
84
+ - background_job
85
+ - authentication
86
+ - infrastructure
87
+ - configuration
88
+ - dependencies
89
+ - tooling
90
+ - development_workflow
91
+ - testing_framework
92
+ - documentation
93
+ - assistant
94
+ # Accepted by validators and refresh, never offered to writers. Existing
95
+ # docs that carry these values keep passing; do not rewrite them. Only new
96
+ # docs read `values` above.
97
+ legacy_values:
80
98
  - rails_model
81
99
  - rails_controller
82
100
  - rails_view
83
101
  - service_object
84
- - background_job
85
- - database
86
102
  - frontend_stimulus
87
103
  - hotwire_turbo
88
104
  - email_processing
89
105
  - brief_system
90
- - assistant
91
- - authentication
92
106
  - payments
93
- - development_workflow
94
- - testing_framework
95
- - documentation
96
- - tooling
97
107
  description: "Component involved"
98
108
 
99
109
  severity:
@@ -117,7 +127,6 @@ track_rules:
117
127
  root_cause:
118
128
  type: enum
119
129
  values:
120
- - missing_association
121
130
  - missing_include
122
131
  - missing_index
123
132
  - wrong_api
@@ -134,7 +143,12 @@ track_rules:
134
143
  - inadequate_documentation
135
144
  - missing_tooling
136
145
  - incomplete_setup
137
- description: "Fundamental technical cause of the problem"
146
+ legacy_values:
147
+ - missing_association
148
+ description: >-
149
+ Fundamental technical cause of the problem.
150
+ missing_include: a missing eager load or an N+1 query.
151
+ wrong_api: an API used in a way that does not fit the situation.
138
152
  resolution_type:
139
153
  type: enum
140
154
  values:
@@ -147,6 +161,7 @@ track_rules:
147
161
  - workflow_improvement
148
162
  - documentation_update
149
163
  - tooling_addition
164
+ legacy_values:
150
165
  - seed_data_update
151
166
  description: "Type of fix applied"
152
167
 
@@ -163,7 +178,6 @@ track_rules:
163
178
  root_cause:
164
179
  type: enum
165
180
  values:
166
- - missing_association
167
181
  - missing_include
168
182
  - missing_index
169
183
  - wrong_api
@@ -180,7 +194,12 @@ track_rules:
180
194
  - inadequate_documentation
181
195
  - missing_tooling
182
196
  - incomplete_setup
183
- description: "Underlying cause, if there is a specific one (optional for knowledge track)"
197
+ legacy_values:
198
+ - missing_association
199
+ description: >-
200
+ Underlying cause, if there is a specific one (optional for knowledge track).
201
+ missing_include: a missing eager load or an N+1 query.
202
+ wrong_api: an API used in a way that does not fit the situation.
184
203
  resolution_type:
185
204
  type: enum
186
205
  values:
@@ -193,6 +212,7 @@ track_rules:
193
212
  - workflow_improvement
194
213
  - documentation_update
195
214
  - tooling_addition
215
+ legacy_values:
196
216
  - seed_data_update
197
217
  description: "Type of change, if applicable (optional for knowledge track)"
198
218
 
@@ -207,12 +227,66 @@ optional_fields:
207
227
  max_items: 8
208
228
  description: "Search keywords, lowercase and hyphen-separated"
209
229
 
230
+ title:
231
+ type: string
232
+ description: "Human-readable title of the learning"
233
+
234
+ environment:
235
+ type: string
236
+ description: "Runtime, platform, or toolchain the learning applies to (free text)"
237
+
238
+ category:
239
+ type: string
240
+ description: "Directory name under docs/solutions/ the doc is filed in (matches the category mapping)"
241
+
242
+ last_updated:
243
+ type: string
244
+ pattern: '^\d{4}-\d{2}-\d{2}$'
245
+ description: "Date the doc was last edited (YYYY-MM-DD)"
246
+
247
+ last_refreshed:
248
+ type: string
249
+ pattern: '^\d{4}-\d{2}-\d{2}$'
250
+ description: "Date the doc was last verified against the codebase (YYYY-MM-DD)"
251
+
252
+ # Lifecycle fields. A missing status means active. Writers keep these
253
+ # consistent: updating or verifying a doc clears status: stale together with
254
+ # stale_reason and stale_date. Superseding is a manual edit; nothing writes it.
255
+ status:
256
+ type: enum
257
+ values:
258
+ - active
259
+ - stale
260
+ - superseded
261
+ description: "Lifecycle state. Missing means active."
262
+
263
+ superseded_by:
264
+ type: string
265
+ description: >-
266
+ Repo-root path of the doc that replaces this one, for example
267
+ docs/solutions/best-practices/example.md. Required when status is superseded.
268
+ The target must exist and must not itself be superseded.
269
+
270
+ superseded_date:
271
+ type: string
272
+ pattern: '^\d{4}-\d{2}-\d{2}$'
273
+ description: "Date the doc was superseded (YYYY-MM-DD)"
274
+
275
+ stale_reason:
276
+ type: string
277
+ description: "Why the doc is marked stale. Present only while status is stale."
278
+
279
+ stale_date:
280
+ type: string
281
+ pattern: '^\d{4}-\d{2}-\d{2}$'
282
+ description: "Date the doc was marked stale (YYYY-MM-DD). Present only while status is stale."
283
+
210
284
  # --- Fields optional for bug track only -------------------------------------
211
285
  bug_optional_fields:
212
286
  rails_version:
213
287
  type: string
214
288
  pattern: '^\d+\.\d+\.\d+$'
215
- description: "Rails version in X.Y.Z format. Only relevant for bug-track docs."
289
+ description: "LEGACY. Rails version in X.Y.Z format. Preserved on existing bug-track docs, never offered to writers. Documentation only: the validator does not read it."
216
290
 
217
291
  # --- Backward compatibility --------------------------------------------------
218
292
  # Docs created before the track system was introduced may have bug-track
@@ -221,6 +295,13 @@ bug_optional_fields:
221
295
  # - Bug-track fields present on a knowledge-track doc are harmless. Do not
222
296
  # strip them during refresh unless the doc is being rewritten for other reasons.
223
297
  # - When creating NEW docs, follow the track rules above.
298
+ #
299
+ # Legacy vocabulary. Older docs may carry Rails and product-specific values:
300
+ # component values listed under `legacy_values`, the root_cause
301
+ # missing_association, the resolution_type seed_data_update, and the
302
+ # rails_version field. Validators and refresh accept them. Update paths
303
+ # preserve them and never rewrite them. Only new docs read `values`, so writers
304
+ # are never offered a legacy value.
224
305
 
225
306
  # --- Validation rules --------------------------------------------------------
226
307
  validation_rules:
@@ -230,10 +311,13 @@ validation_rules:
230
311
  - "Knowledge-track docs have no additional required fields beyond the shared ones"
231
312
  - "Bug-track fields on existing knowledge-track docs are harmless (see backward compatibility note)"
232
313
  - "Track-specific optional fields may be included but are not required"
233
- - "Enum fields must match allowed values exactly"
314
+ - "Enum fields must match allowed values exactly; legacy_values are accepted but never offered to writers"
315
+ - "status, if present, must be one of active, stale, superseded; missing means active"
316
+ - "A doc with status superseded must carry superseded_by naming an existing doc that is not itself superseded"
317
+ - "Clearing status: stale also clears stale_reason and stale_date"
234
318
  - "Array fields must respect min_items/max_items when specified"
235
319
  - "date must match YYYY-MM-DD format"
236
- - "rails_version, if provided, must match X.Y.Z format and only applies to bug-track docs"
320
+ - "Legacy fields and values (see the backward compatibility note) are preserved on update and never offered to writers"
237
321
  - "tags should be lowercase and hyphen-separated"
238
322
  - |-
239
323
  YAML quoting: scalar values that contain ' #' (space-hash) must be
@@ -30,15 +30,16 @@ Prefer the narrowest applicable value. `best_practice` is the fallback when no n
30
30
  - **module**: Module or area affected
31
31
  - **date**: ISO date in `YYYY-MM-DD`
32
32
  - **problem_type**: One of the values listed in the Tracks table above
33
- - **component**: One of `rails_model`, `rails_controller`, `rails_view`, `service_object`, `background_job`, `database`, `frontend_stimulus`, `hotwire_turbo`, `email_processing`, `brief_system`, `assistant`, `authentication`, `payments`, `development_workflow`, `testing_framework`, `documentation`, `tooling`
33
+ - **component**: One of `backend`, `frontend`, `api`, `database`, `background_job`, `authentication`, `infrastructure`, `configuration`, `dependencies`, `tooling`, `development_workflow`, `testing_framework`, `documentation`, `assistant`
34
34
  - **severity**: One of `critical`, `high`, `medium`, `low`
35
35
 
36
36
  ## Bug Track Fields
37
37
 
38
38
  Required:
39
39
  - **symptoms**: YAML array with 1-5 observable symptoms (errors, broken behavior)
40
- - **root_cause**: One of `missing_association`, `missing_include`, `missing_index`, `wrong_api`, `scope_issue`, `thread_violation`, `async_timing`, `memory_leak`, `config_error`, `logic_error`, `test_isolation`, `missing_validation`, `missing_permission`, `missing_workflow_step`, `inadequate_documentation`, `missing_tooling`, `incomplete_setup`
41
- - **resolution_type**: One of `code_fix`, `migration`, `config_change`, `test_fix`, `dependency_update`, `environment_setup`, `workflow_improvement`, `documentation_update`, `tooling_addition`, `seed_data_update`
40
+ - **root_cause**: One of `missing_include`, `missing_index`, `wrong_api`, `scope_issue`, `thread_violation`, `async_timing`, `memory_leak`, `config_error`, `logic_error`, `test_isolation`, `missing_validation`, `missing_permission`, `missing_workflow_step`, `inadequate_documentation`, `missing_tooling`, `incomplete_setup`
41
+ - `missing_include` is a missing eager load or an N+1 query. `wrong_api` is an API used in a way that does not fit the situation.
42
+ - **resolution_type**: One of `code_fix`, `migration`, `config_change`, `test_fix`, `dependency_update`, `environment_setup`, `workflow_improvement`, `documentation_update`, `tooling_addition`
42
43
 
43
44
  ## Knowledge Track Fields
44
45
 
@@ -55,10 +56,25 @@ No additional required fields beyond the shared ones. All fields below are optio
55
56
 
56
57
  - **related_components**: Other components involved
57
58
  - **tags**: Search keywords, lowercase and hyphen-separated
59
+ - **title**: Human-readable title of the learning
60
+ - **environment**: Runtime, platform, or toolchain the learning applies to (free text)
61
+ - **category**: Directory name under `docs/solutions/` the doc is filed in (see Category Mapping)
62
+ - **last_updated**: Date the doc was last edited, `YYYY-MM-DD`
63
+ - **last_refreshed**: Date the doc was last verified against the codebase, `YYYY-MM-DD`
58
64
 
59
- ## Optional Fields (bug track only)
65
+ ## Lifecycle Fields (both tracks, optional)
60
66
 
61
- - **rails_version**: Rails version in `X.Y.Z` format
67
+ - **status**: One of `active`, `stale`, `superseded`. A missing `status` means `active`. An explicit empty value is invalid.
68
+ - **superseded_by**: Repo-root path of the doc that replaces this one, for example `docs/solutions/best-practices/example.md`. Required when `status` is `superseded`. The target must be an existing doc under `docs/solutions/` (not `README.md`) that is not itself superseded. A bare filename or any other path form does not resolve.
69
+ - **superseded_date**: Date the doc was superseded, `YYYY-MM-DD`
70
+ - **stale_reason**: Why the doc is marked stale. Present only while `status` is `stale`.
71
+ - **stale_date**: Date the doc was marked stale, `YYYY-MM-DD`. Present only while `status` is `stale`.
72
+
73
+ Writers keep these fields consistent. Updating or verifying a doc clears `status: stale` together with `stale_reason` and `stale_date`. Nothing writes `status: superseded`: superseding is a manual edit. A `superseded_by` on a doc that is not superseded is ignored.
74
+
75
+ ## Optional Fields (bug track only, legacy)
76
+
77
+ - **rails_version**: Legacy. Rails version in `X.Y.Z` format. Preserved on existing bug-track docs, never offered to writers. Documentation only: the validator does not check it.
62
78
 
63
79
  ## Backward Compatibility
64
80
 
@@ -67,6 +83,18 @@ Docs created before the track system may have `symptoms`/`root_cause`/`resolutio
67
83
  - Bug-track fields present on a knowledge-track doc are harmless. Do not strip them during refresh unless the doc is being rewritten for other reasons.
68
84
  - When creating **new** docs, follow the track rules above.
69
85
 
86
+ ## Legacy Values
87
+
88
+ Older docs may carry Rails and product-specific values. Validators and refresh accept them, update paths preserve them and never rewrite them, and writers are never offered them. Only new docs read the offered values above.
89
+
90
+ | Field | Legacy values |
91
+ |-------|---------------|
92
+ | `component` | `rails_model`, `rails_controller`, `rails_view`, `service_object`, `frontend_stimulus`, `hotwire_turbo`, `email_processing`, `brief_system`, `payments` |
93
+ | `root_cause` | `missing_association` |
94
+ | `resolution_type` | `seed_data_update` |
95
+
96
+ `schema.yaml` lists these under `legacy_values`, beside `values`, on the bug-required and knowledge-optional lists alike.
97
+
70
98
  ## Category Mapping
71
99
 
72
100
  - `build_error` -> `docs/solutions/build-errors/`
@@ -98,7 +126,8 @@ directories that fragment search.
98
126
  3. Bug-track required fields (`symptoms`, `root_cause`, `resolution_type`) must be present on bug-track docs.
99
127
  4. Knowledge-track docs have no additional required fields beyond the shared ones.
100
128
  5. Bug-track fields on existing knowledge-track docs are harmless (see Backward Compatibility).
101
- 6. Enum fields must match the allowed values exactly.
129
+ 6. Enum fields must match the allowed values exactly. Legacy values are accepted too (see Legacy Values).
102
130
  7. Array fields must respect min/max item counts.
103
131
  8. `date` must match `YYYY-MM-DD`.
104
- 9. `rails_version`, if present, must match `X.Y.Z` and only applies to bug-track docs.
132
+ 9. `status`, if present, must be `active`, `stale` or `superseded`.
133
+ 10. A `superseded` doc must carry a `superseded_by` that names an existing doc which is not itself superseded.
@@ -57,7 +57,7 @@ All tokens are optional. Each one present means one less thing to infer. When ab
57
57
  - **Never edit files or externalize work.** Do not write `.context/systematic/ce-review/<run-id>/`, do not create todo files, and do not commit, push, or create a PR.
58
58
  - **Report-only runs in memory.** Run raw-return structural validation, synthesis, and reporting without writing a run directory, artifact, or ignore file.
59
59
  - **Safe for parallel read-only verification.** `mode:report-only` is the only mode that is safe to run concurrently with browser testing on the same checkout.
60
- - **Do not switch the shared checkout.** If the caller passes an explicit PR or branch target, `mode:report-only` must run in an isolated checkout/worktree or stop instead of running `gh pr checkout` / `git checkout`.
60
+ - **Do not switch the shared checkout.** If the caller passes an explicit PR or branch target, `mode:report-only` must run in an isolated checkout/worktree or stop instead of running `gh pr checkout` / `git checkout`. Create that worktree with the `git-worktree` skill, which places it at `.worktrees/<branch>` under the main repository root.
61
61
  - **Do not overlap mutating review with browser testing on the same checkout.** If a future orchestrator wants fixes, run the mutating review phase after browser testing or in an isolated checkout/worktree.
62
62
 
63
63
  ### Headless mode rules
@@ -68,7 +68,7 @@ All tokens are optional. Each one present means one less thing to infer. When ab
68
68
  - **Return all non-auto findings as structured text output.** Use the headless output envelope format (see Stage 6 below) preserving severity, autofix_class, owner, requires_verification, confidence, pre_existing, and suggested_fix per finding. Enrich with detail-tier fields (why_it_matters, evidence[]) from the validated inline persona returns (see Detail enrichment in Stage 6).
69
69
  - **Write a run artifact** under `.context/systematic/ce-review/<run-id>/` summarizing findings, applied fixes, and advisory outputs. Include the artifact path in the structured output.
70
70
  - **Do not create todo files.** The caller receives structured findings and routes downstream work itself.
71
- - **Do not switch the shared checkout.** If the caller passes an explicit PR or branch target, `mode:headless` must run in an isolated checkout/worktree or stop instead of running `gh pr checkout` / `git checkout`. When stopping, emit `Review failed (headless mode). Reason: cannot switch shared checkout. Re-invoke with base:<ref> to review the current checkout, or run from an isolated worktree.`
71
+ - **Do not switch the shared checkout.** If the caller passes an explicit PR or branch target, `mode:headless` must run in an isolated checkout/worktree or stop instead of running `gh pr checkout` / `git checkout`. Create that worktree with the `git-worktree` skill, which places it at `.worktrees/<branch>` under the main repository root. When stopping, emit `Review failed (headless mode). Reason: cannot switch shared checkout. Re-invoke with base:<ref> to review the current checkout, or run from an isolated worktree.`
72
72
  - **Not safe for concurrent use on a shared checkout.** Unlike `mode:report-only`, headless mutates files (applies `safe_auto` fixes). Callers must not run headless concurrently with other mutating operations on the same checkout.
73
73
  - **Never commit, push, or create a PR** from headless mode. The caller owns those decisions.
74
74
  - **End with "Review complete" as the terminal signal** so callers can detect completion. If all reviewers fail or time out, emit `Code review degraded (headless mode). Reason: 0 of N reviewers returned results.` followed by "Review complete".
@@ -181,7 +181,7 @@ This path works with any ref — a SHA, `origin/main`, a branch name. Automated
181
181
 
182
182
  **If a PR number or GitHub URL is provided as an argument:**
183
183
 
184
- If `mode:report-only` or `mode:headless` is active, do **not** run `gh pr checkout <number-or-url>` on the shared checkout. For `mode:report-only`, tell the caller: "mode:report-only cannot switch the shared checkout to review a PR target. Run it from an isolated worktree/checkout for that PR, or run report-only with no target argument on the already checked out branch." For `mode:headless`, emit `Review failed (headless mode). Reason: cannot switch shared checkout. Re-invoke with base:<ref> to review the current checkout, or run from an isolated worktree.` Stop here unless the review is already running in an isolated checkout.
184
+ If `mode:report-only` or `mode:headless` is active, do **not** run `gh pr checkout <number-or-url>` on the shared checkout. For `mode:report-only`, tell the caller: "mode:report-only cannot switch the shared checkout to review a PR target. Run it from an isolated worktree/checkout for that PR, or run report-only with no target argument on the already checked out branch." For `mode:headless`, emit `Review failed (headless mode). Reason: cannot switch shared checkout. Re-invoke with base:<ref> to review the current checkout, or run from an isolated worktree.` Stop here unless the review is already running in an isolated checkout. Create that worktree with the `git-worktree` skill, which places it at `.worktrees/<branch>` under the main repository root.
185
185
 
186
186
  First, verify the worktree is clean before switching branches:
187
187
 
@@ -235,7 +235,7 @@ Extract PR title/body, base branch, and PR URL from `gh pr view`, then extract t
235
235
 
236
236
  Check out the named branch, then diff it against the base branch. Substitute the provided branch name (shown here as `<branch>`).
237
237
 
238
- If `mode:report-only` or `mode:headless` is active, do **not** run `git checkout <branch>` on the shared checkout. For `mode:report-only`, tell the caller: "mode:report-only cannot switch the shared checkout to review another branch. Run it from an isolated worktree/checkout for `<branch>`, or run report-only on the current checkout with no target argument." For `mode:headless`, emit `Review failed (headless mode). Reason: cannot switch shared checkout. Re-invoke with base:<ref> to review the current checkout, or run from an isolated worktree.` Stop here unless the review is already running in an isolated checkout.
238
+ If `mode:report-only` or `mode:headless` is active, do **not** run `git checkout <branch>` on the shared checkout. For `mode:report-only`, tell the caller: "mode:report-only cannot switch the shared checkout to review another branch. Run it from an isolated worktree/checkout for `<branch>`, or run report-only on the current checkout with no target argument." For `mode:headless`, emit `Review failed (headless mode). Reason: cannot switch shared checkout. Re-invoke with base:<ref> to review the current checkout, or run from an isolated worktree.` Stop here unless the review is already running in an isolated checkout. Create that worktree with the `git-worktree` skill, which places it at `.worktrees/<branch>` under the main repository root.
239
239
 
240
240
  First, verify the worktree is clean before switching branches:
241
241
 
@@ -548,7 +548,7 @@ Assemble the final report using **pipe-delimited markdown tables for findings**
548
548
  5. **Residual Actionable Work.** Render `report.queues.residual` as a table of findings whose owner is `downstream-resolver`, using `report.input_dispositions` to resolve each entry's fields.
549
549
  6. **Pre-existing.** Render `report.pre_existing_findings`. Separate section, does not count toward verdict.
550
550
  7. **Filtered (not validated).** Include when `report.findings` contains any entry with `validated: false`. Render as a pipe-delimited table with columns `#`, `File`, `Issue`, `Reviewer`, `Confidence`, `Validator reason`. These findings are surfaced for human review — they are not removed from the report. The validator found evidence that the issue may not be real in the code as written, was not introduced by this diff, or is already handled elsewhere; the human reviewer makes the final call. Omit this section when no findings were filtered.
551
- 8. **Learnings & Past Solutions.** Render only when CE `learnings-researcher` was selected and returned relevant output: if past solutions are relevant, flag them as "Known Pattern" with links to docs/solutions/ files. Omit the section otherwise.
551
+ 8. **Learnings & Past Solutions.** Render only when CE `learnings-researcher` was selected and returned relevant output: if past solutions are relevant, flag them as "Known Pattern" with links to docs/solutions/ files, and carry any `Supersedes:`, `Caution:` and `Skipped:` lines from the researcher output into the Known Pattern entry. Omit the section otherwise.
552
552
  9. **Agent-Native Gaps.** Render only when CE `agent-native-reviewer` was selected and returned relevant output. Omit the section otherwise.
553
553
  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.
554
554
  11. **Coverage.** Render `report.coverage` directly: suppressed count, residual risks, testing gaps, failed/timed-out reviewers, validator lifecycle failures (`failed`/`unavailable` outcomes from Stage 5b), risk-coverage entries with citing input finding IDs and exit conditions for blocked entries, and any intent uncertainty carried by non-interactive modes. For raw returns, state each selected persona's admission state — `findings`, `empty`, `malformed`, `never_returned`, `validation_unavailable` (the persisted raw dispatch outcome; distinct from the artifact-level `validation.status: "unavailable"`) — and what was admitted or withheld. Report admission states here only; do not add fields to `review-summary.v1`. Distinguish core reviewers, each selected conditional with its one-line rationale and triggering repository-relative paths, an explicit "no conditional selected" case, and any selected-but-failed/malformed/validation-unavailable reviewer; never label an unselected reviewer as failed.
@@ -135,7 +135,7 @@ This fails because: no pipe-delimited tables, no severity-grouped `###` headers,
135
135
  - **Residual Actionable Work section** -- include only when unresolved actionable findings were handed off for later work
136
136
  - **Pre-existing section** -- separate table, no confidence column (these are informational)
137
137
  - **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.
138
- - **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.
138
+ - **Learnings & Past Solutions section** -- render only when CE `learnings-researcher` was selected and returned relevant output; results with links to docs/solutions/ files; carry any `Supersedes:`, `Caution:` and `Skipped:` lines from the researcher output into each Known Pattern entry. Omit otherwise.
139
139
  - **Agent-Native Gaps section** -- render only when CE `agent-native-reviewer` was selected and returned relevant output. Omit otherwise.
140
140
  - **Deployment Notes section** -- key checklist items from deployment-verification-agent. Omit if the agent did not run.
141
141
  - **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`, and `validation_unavailable` (the persisted raw dispatch outcome, distinct from the artifact-level `validation.status: "unavailable"`), and state what was admitted or withheld