@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.
- package/ATTRIBUTIONS.md +2 -2
- package/HARNESSES.md +23 -8
- package/agents/research/learnings-researcher.md +82 -80
- package/dist/index.js +20 -2
- package/dist/lib/bootstrap.d.ts +17 -2
- package/dist/lib/pi-subagents-personas.d.ts +1 -1
- package/dist/pi.js +23 -5
- package/package.json +5 -5
- package/skills/ce-compound/SKILL.md +13 -11
- package/skills/ce-compound/references/schema.yaml +99 -15
- package/skills/ce-compound/references/yaml-schema.md +36 -7
- package/skills/ce-compound-refresh/SKILL.md +33 -16
- package/skills/ce-compound-refresh/references/schema.yaml +99 -15
- package/skills/ce-compound-refresh/references/yaml-schema.md +36 -7
- package/skills/ce-review/SKILL.md +5 -5
- package/skills/ce-review/references/review-output-template.md +1 -1
- package/skills/compound-docs/SKILL.md +75 -124
- package/skills/compound-docs/assets/resolution-template.md +65 -68
- package/skills/compound-docs/references/schema.yaml +331 -0
- package/skills/compound-docs/references/yaml-schema.md +122 -54
- package/skills/git-clean-gone-branches/SKILL.md +17 -7
- package/skills/git-worktree/SKILL.md +33 -309
- package/skills/git-worktree/scripts/worktree-manager.sh +568 -391
- package/skills/orchestrating-subagents/SKILL.md +1 -1
- package/skills/using-systematic/references/worktree-placement.md +1 -0
- package/skills/compound-docs/assets/critical-pattern-template.md +0 -34
- package/skills/compound-docs/schema.yaml +0 -176
|
@@ -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
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
-
- "
|
|
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 `
|
|
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 `
|
|
41
|
-
-
|
|
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
|
-
##
|
|
65
|
+
## Lifecycle Fields (both tracks, optional)
|
|
60
66
|
|
|
61
|
-
- **
|
|
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. `
|
|
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
|