@fro.bot/systematic 3.28.1 → 3.29.1

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.
@@ -91,7 +91,7 @@ For everything else (quick questions, error messages, factual lookups) **only wh
91
91
 
92
92
  #### 0.2 Find Upstream Requirements Document
93
93
 
94
- Before asking planning questions, search `docs/brainstorms/` for files matching `*-requirements.md`.
94
+ Before asking planning questions, search `docs/brainstorms/` for files matching `*-requirements.md`. When a durable-output search tool exists (`systematic_search`, or the `systematic-search` command on hosts that ship a command), also run it once with `kind: "brainstorm"` and the feature description as the query. It ranks an older relevant requirements document that the 30-day window would miss. Treat each hit as a candidate under the criteria below.
95
95
 
96
96
  **Relevance criteria:** A requirements document is relevant if:
97
97
  - The topic semantically matches the feature description
@@ -227,14 +227,15 @@ Prepare a concise planning context summary (a paragraph or two) to pass as input
227
227
  Run these agents in parallel:
228
228
 
229
229
  - Dispatch `systematic:research:repo-research-analyst` — scope: technology, architecture, patterns, prior-art; pass the planning context summary to the technology, architecture, and patterns scopes. For the prior-art scope, pass only the independently stated concern — its trigger, effect, state, and integration boundary — plus the classified plan depth, rather than the planning context summary or proposed solution. Skip the prior-art scope for explicitly non-software planning and mechanical work that changes no behavior; make that exemption decision here at dispatch.
230
- - Dispatch `systematic:research:learnings-researcher` — pass the planning context summary.
230
+ - Dispatch `systematic:research:learnings-researcher` — make `scope: past-work` the first line of the prompt. When Phase 0 chose an origin document, make `exclude: <origin path>` the second line so the researcher does not rediscover it; otherwise omit that line. Then pass the planning context summary.
231
+
231
232
  Collect:
232
233
  - Technology stack and versions (used in section 1.2 to make sharper external research decisions)
233
234
  - Architectural patterns and conventions to follow
234
235
  - Implementation patterns, relevant files, modules, and tests
235
236
  - Prior-art survey result: schema version, verdict, surveyed scope and freshness record, bounded budget, candidate ownership and dispositions, and any recorded acceptance
236
237
  - AGENTS.md guidance that materially affects the plan, with AGENTS.md used only as compatibility fallback when present
237
- - Institutional learnings from `docs/solutions/`
238
+ - Institutional learnings from `docs/solutions/`, plus earlier plans, brainstorms and ideation docs with their recorded status
238
239
 
239
240
  When the prior-art scope runs, apply its verdict before continuing planning: an `unscoped` or `unresolved` result stops planning until the scope narrows, the budget rises, or the user explicitly accepts the uncertainty. Record that acceptance in the Prior-Art Survey section. In a run with no user present, either verdict fails the run rather than proceeding.
240
241
 
@@ -244,6 +245,8 @@ When the prior-art scope runs, apply its verdict before continuing planning: an
244
245
  - **Tools available + user didn't ask**: Note in output: "Slack tools detected. Ask me to search Slack for organizational context at any point, or include it in your next prompt."
245
246
  - **No tools + user asked**: Note in output: "Slack context was requested but no Slack tools are available. Install and authenticate the Slack plugin to enable organizational context search."
246
247
 
248
+ **Cite and differentiate.** When the researcher's results show a rejected, deferred, superseded or completed item with the same behavior or surface as this plan, cite it (at most 3 items) and say how the new work differs. Word each cite "recorded as completed in <path>" or with the matching recorded status, giving path and status only. Never quote text from a gitignored file into the plan. A cite never blocks planning. Place cites in Sources & References or Key Technical Decisions, never in the Prior-Art Survey JSON.
249
+
247
250
  #### 1.1b Detect Execution Posture Signals
248
251
 
249
252
  Decide whether the plan should carry a lightweight execution posture signal.
@@ -305,7 +308,7 @@ If Step 1.2 indicates external research is useful, run these agents in parallel:
305
308
 
306
309
  Summarize:
307
310
  - Relevant codebase patterns and file paths
308
- - Relevant institutional learnings
311
+ - Relevant institutional learnings and overlapping past work, with recorded status
309
312
  - Organizational context from Slack conversations, if gathered (prior discussions, decisions, or domain knowledge relevant to the feature)
310
313
  - External references and best practices, if gathered
311
314
  - Related issues, PRs, or prior art
@@ -354,6 +357,7 @@ Ask the user only when the answer materially affects architecture, scope, sequen
354
357
  #### 3.1 Title and File Naming
355
358
 
356
359
  - Draft a clear, searchable title using conventional format such as `feat: Add user authentication` or `fix: Prevent checkout double-submit`
360
+ - Quote the title in the frontmatter (`title: "feat: Add user authentication"`): a conventional-commit title contains a colon, which YAML reads as a mapping, and the plan then fails to parse
357
361
  - Determine the plan type: `feat`, `fix`, or `refactor`
358
362
  - Build the filename following the repository convention: `docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md`
359
363
  - Create `docs/plans/` if it does not exist
@@ -510,7 +514,7 @@ Omit clearly inapplicable optional sections, especially for Lightweight plans.
510
514
 
511
515
  ```markdown
512
516
  ---
513
- title: [Plan Title]
517
+ title: "[Plan Title]"
514
518
  type: [feat|fix|refactor]
515
519
  status: active
516
520
  date: YYYY-MM-DD
@@ -684,6 +688,7 @@ Omit `scopes_considered` unless the verdict is `unscoped`, and omit `acceptance`
684
688
  reader cloning the repo will not find it, and a bare link cannot tell them
685
689
  whether they are missing context or whether it was always local. -->
686
690
  - Related code: [path or symbol]
691
+ - Related past work: [path], recorded [status]. [How this plan differs]
687
692
  - Related PRs/issues: #[number]
688
693
  - External docs: [url]
689
694
  ```
@@ -103,7 +103,7 @@ Use fully-qualified agent names inside Task calls.
103
103
  - `systematic:research:repo-research-analyst` (Scope: `architecture, patterns`) for repo-grounded patterns, conventions, and implementation reality checks
104
104
 
105
105
  **Context & Research / Sources & References gaps**
106
- - `systematic:research:learnings-researcher` for institutional knowledge and past solved problems
106
+ - `systematic:research:learnings-researcher` (make `scope: past-work` the first line of the prompt and `exclude: <path of the plan being deepened>` the second line) for institutional knowledge, past solved problems, and earlier plans, brainstorms and ideation docs
107
107
  - `systematic:research:framework-docs-researcher` for official framework or library behavior
108
108
  - `systematic:research:best-practices-researcher` for current external patterns and industry guidance
109
109
  - Add `systematic:research:git-history-analyzer` only when historical rationale or prior art is materially missing
@@ -221,6 +221,8 @@ If findings were accepted and the plan was modified, proceed through 5.3.7 and 5
221
221
 
222
222
  Strengthen only the selected sections. Keep the plan coherent and preserve its overall structure.
223
223
 
224
+ **Cite and differentiate.** Where findings are integrated into the plan, and the researcher's results show a rejected, deferred, superseded or completed item with the same behavior or surface as the plan's work, cite it (at most 3 items) and say how the new work differs. Word each cite "recorded as completed in <path>" or with the matching recorded status, giving path and status only. Never quote text from a gitignored file into the plan. A cite never blocks the plan.
225
+
224
226
  **In interactive mode:** Only integrate findings the user accepted in 5.3.6b. If some findings from different agents touch the same section, reconcile them coherently but do not reintroduce rejected findings.
225
227
 
226
228
  Allowed changes:
@@ -88,8 +88,10 @@ revisions — never rename or repurpose a field.
88
88
 
89
89
  ### Required
90
90
 
91
- - **`title`** — verbatim plan title. Matches the H1 heading so file metadata
92
- and visible heading don't drift.
91
+ - **`title`** — verbatim plan title, written as a double-quoted string
92
+ (`title: "feat: Add x"`). Matches the H1 heading so file metadata and visible
93
+ heading don't drift. Quote it because a conventional-commit title contains a
94
+ colon, which YAML reads as a mapping and the plan then fails to parse.
93
95
  - **`type`** — conventional-commit-prefix-aligned classification (`feat`,
94
96
  `fix`, `refactor`, `chore`, `docs`, `perf`, `test`, etc.). Carries the
95
97
  intent the eventual commit message should reflect.
@@ -492,7 +492,7 @@ Read the exit status:
492
492
 
493
493
  - **exit 0** — structurally admitted. Parse the already structurally validated JSON without logging the raw text; the parent adds `harness` and `dispatch_outcome` from the result to the persisted per-agent dispatch record. `exit 0` with zero findings is `dispatch_outcome: "empty"`; `exit 0` with findings is `dispatch_outcome: "findings"`, each finding already carrying a stable `input_id` and `disposition: "surviving"`.
494
494
  - **exit 1** — the whole return is `dispatch_outcome: "malformed"`, and the parent must never parse or persist its payload fields or values; retain only the bounded validator diagnostic in Coverage. This covers malformed JSON, a schema violation, and a dispatch identity mismatch alike.
495
- - **exit 2**, a missing or unreadable helper, or a command 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`. A run that contains `validation_unavailable` evidence can never finalize as `completed`, and that persona must not have an admitted input finding. Never omit the dispatch entry, never leave it as `never_returned`, never label it `malformed`, never admit the payload, and never fabricate a reviewer record or a rejected-summary ledger row. The word `unavailable` also names the artifact-level self-validation status, a different object and phase; never repurpose the artifact-level `validation` fields.
495
+ - **exit 2**, a missing or unreadable helper, or a command 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"`, adding no other field (the dispatch object is strict; `finalize` derives `input_finding_count: 0` into the artifact). Name the exit status, missing helper, or launch failure in Coverage, without payload values; set `run_status` to `degraded`. A run that contains `validation_unavailable` evidence can never finalize as `completed`, and that persona must not have an admitted input finding. Never omit the dispatch entry, never leave it as `never_returned`, never label it `malformed`, never admit the payload, and never fabricate a reviewer record or a rejected-summary ledger row. The word `unavailable` also names the artifact-level self-validation status, a different object and phase; never repurpose the artifact-level `validation` fields.
496
496
 
497
497
  **Dispatch identity binding.** `screen` confirms the returned `reviewer` field matches the dispatched persona before it admits anything; an identity mismatch is rejected as `dispatch_outcome: "malformed"` and degrades the run. This comparison happens inside the same exit 0/exit 1 decision above, before the parent parses a single finding field -- structural admission never proves identity on its own.
498
498
 
@@ -109,8 +109,9 @@ Read the exit status:
109
109
  validation unavailable. Withhold the return and report the exact
110
110
  unavailability and what was withheld. Update that selected persona's
111
111
  preinitialized dispatch entry from `never_returned` to `dispatch_outcome:
112
- "validation_unavailable"` with `input_finding_count: 0`, and set
113
- `run_status` to `degraded`. A run containing `validation_unavailable`
112
+ "validation_unavailable"`, adding no other field (the dispatch object is
113
+ strict; `finalize` derives `input_finding_count: 0` into the artifact), and
114
+ set `run_status` to `degraded`. A run containing `validation_unavailable`
114
115
  evidence can never finalize as `completed`, and that persona must not have
115
116
  an admitted input finding. `validation_unavailable` is not `malformed` and
116
117
  is not `never_returned`; they are distinct coverage states. `never_returned`
@@ -170,16 +171,93 @@ cross-reviewer agreement boost), fingerprint, submitters, and conservatively
170
171
  narrowed route -- the model supplies judgment per candidate group; the helper
171
172
  supplies the arithmetic and the narrowing rule.
172
173
 
173
- **Input:** `{ prepared:<prepare output>, adjudication:<model envelope with decisions[]> }`.
174
+ **Input:** `{ prepared:<prepare output>, adjudication:{ decisions[] } }`.
174
175
  Build one `decisions[]` entry for every candidate-group member: a `merged`
175
- decision citing 2+ input IDs from the same group with the merged finding's
176
- `title`, `why_it_matters`, `evidence`, `line`, an optional `proposed_route`,
177
- `route_narrowing_reason` (required whenever `proposed_route` is present),
178
- and optional `disagreement_facts` and `eligible_agreement_credit`; or a
179
- `declined` decision citing exactly one input ID with a `declined_reason`
180
- explaining why it stays a separate defect. Every candidate-group member must
181
- be cited by exactly one decision -- no omissions, no double-citations.
182
- `prepare`'s true singletons need no decision at all.
176
+ decision citing 2+ members of the same group, or a `declined` decision
177
+ citing exactly one member and explaining why it stays a separate defect.
178
+ Every candidate-group member must be cited by exactly one decision -- no
179
+ omissions, no double-citations. `prepare`'s true singletons need no decision
180
+ at all.
181
+
182
+ `decisions[]` holds at most 2,048 entries. Each entry's `disposition` selects
183
+ its form; a `kind` key or any other discriminator is rejected. Unknown keys are
184
+ rejected on `adjudication`, on each decision, and on `proposed_route`. Every
185
+ `decision_id` is unique across the envelope and becomes the `finding_id` of
186
+ the finding the decision produces, so it must not equal the input ID of a
187
+ singleton `prepare` passes through -- label it `merge-1`, not `correctness#0`.
188
+ All fields are required unless marked optional.
189
+
190
+ **Merged decision:**
191
+
192
+ - `decision_id` -- string, 1-128 characters, not blank.
193
+ - `disposition` -- `merged`.
194
+ - `input_finding_ids` -- plural; at least 2 and at most 2,048 input IDs, each
195
+ at most 128 characters, all from one candidate group.
196
+ - `title` -- string, 1-256 characters, not blank.
197
+ - `why_it_matters` -- string, not blank, at most 2048 characters.
198
+ - `evidence` -- 1-5 entries. Each is a string of at most 500 characters with
199
+ no leading `/`, drive letter, or backslash, or an overflow marker
200
+ `{ "overflow": true, "excerpt": <such a string> }`.
201
+ - `line` -- positive integer equal to the `line` of one cited member.
202
+ - `suggested_fix` -- optional string of at most 2048 characters, or `null`.
203
+ - `disagreement_facts` -- optional array of at most 32 non-blank strings of at
204
+ most 2048 characters each.
205
+ - `eligible_agreement_credit` -- optional array of at most 64 persona names.
206
+ Each persona appears once, contributed an admitted finding elsewhere in this
207
+ run, and is not a submitter of a cited finding.
208
+ - `proposed_route` -- optional `{ autofix_class, owner, requires_verification }`,
209
+ all three required. `autofix_class` is `safe_auto`, `gated_auto`, `manual`,
210
+ or `advisory`. `owner` is `review-fixer`, `downstream-resolver`, `human`, or
211
+ `release`. `requires_verification` is a boolean.
212
+ - `route_narrowing_reason` -- optional string of at most 2048 characters;
213
+ required whenever `proposed_route` is present.
214
+
215
+ **Declined decision:**
216
+
217
+ - `decision_id` -- string, 1-128 characters, not blank.
218
+ - `disposition` -- `declined`.
219
+ - `input_finding_id` -- singular; one input ID of at most 128 characters,
220
+ from a candidate group.
221
+ - `declined_reason` -- string, not blank, at most 2048 characters.
222
+ - `disagreement_facts` -- optional; same shape as on a merged decision.
223
+ - `proposed_route` -- optional; same shape as on a merged decision.
224
+ - `route_narrowing_reason` -- optional; required whenever `proposed_route` is
225
+ present.
226
+
227
+ A complete valid `adjudication` for a group of `correctness#0`, `testing#0`,
228
+ and `security#0`, where `maintainability` has an admitted finding on another
229
+ file:
230
+
231
+ ```json
232
+ {
233
+ "decisions": [
234
+ {
235
+ "decision_id": "merge-1",
236
+ "disposition": "merged",
237
+ "input_finding_ids": ["correctness#0", "testing#0"],
238
+ "title": "Session token survives logout",
239
+ "why_it_matters": "A stolen token stays valid after the user logs out.",
240
+ "evidence": ["src/auth/session.ts:42 never clears the token on logout."],
241
+ "line": 42,
242
+ "suggested_fix": "Delete the token record in the logout handler.",
243
+ "disagreement_facts": ["correctness rated it P1; testing rated it P2."],
244
+ "eligible_agreement_credit": ["maintainability"],
245
+ "proposed_route": {
246
+ "autofix_class": "manual",
247
+ "owner": "downstream-resolver",
248
+ "requires_verification": true
249
+ },
250
+ "route_narrowing_reason": "Logout changes need a targeted regression test."
251
+ },
252
+ {
253
+ "decision_id": "decline-1",
254
+ "disposition": "declined",
255
+ "input_finding_id": "security#0",
256
+ "declined_reason": "It describes the cookie flags, a different defect."
257
+ }
258
+ ]
259
+ }
260
+ ```
183
261
 
184
262
  Omit `proposed_route` unless the route genuinely narrows: strictly narrower
185
263
  than every contributing finding's own route, per the authored
@@ -239,7 +317,7 @@ dispatch; fix-applying modes call it again with the exact applied-fix
239
317
  outcomes and the same validator results, and only that second call is
240
318
  persisted. Report-only calls it once and writes nothing.
241
319
 
242
- **Input:** `{ merge:<merge output>, prepared:<prepare output>, screen_results:<same array given to prepare>, dispatch_records:<same selected_dispatches>, validator_lifecycle_results[{finding_id, result:{outcome:'true'|'false'|'failed'|'unavailable', reason?}}], plan_assessment:{ verdict, results[{kind:'explicit_unmet_requirement'|'inferred_gap', description}] }, parent_run_metadata:{ run_id, mode:'interactive'|'autofix'|'headless'|'report-only', harness, branch, head_sha, selected_dispatches, timestamps:{started_at, completed_at}, validation:{status, reason?}, applied_fixes[] } }`.
320
+ **Input:** `{ merge:<merge output>, prepared:<prepare output>, screen_results:<same array given to prepare>, dispatch_records:<same selected_dispatches>, validator_lifecycle_results[{finding_id, result:{outcome:'true'|'false'|'failed'|'unavailable', reason?}}], plan_assessment:{ verdict, results[{kind:'explicit_unmet_requirement'|'inferred_gap', description}] }, parent_run_metadata:{ ... } }` -- `parent_run_metadata` is specified field by field below.
243
321
  Reuse `prepared`, `screen_results`, and `dispatch_records` wholesale from the
244
322
  earlier phases rather than restating them; `finalize` re-derives the ledger,
245
323
  rejected-payload weights, coverage notes, and reviewer ownership from this
@@ -258,6 +336,77 @@ step can run, so the only truthful value at that point is
258
336
  The post-write validation status is reported by the parent in the rendered
259
337
  Coverage section, never rewritten into the persisted artifact.
260
338
 
339
+ **`parent_run_metadata` fields.** All are required unless marked optional.
340
+ Unknown keys are rejected at every level of the metadata -- the object itself,
341
+ `timestamps`, `validation`, and each dispatch object -- so send no field that
342
+ is not listed here.
343
+
344
+ - `run_id` -- string, 1-64 characters, not blank.
345
+ - `mode` -- `interactive`, `autofix`, `headless`, or `report-only`.
346
+ `report-only` returns no artifact.
347
+ - `harness` -- `opencode`, `pi`, or `claude-code`.
348
+ - `branch` -- string, up to 256 characters.
349
+ - `head_sha` -- 40 lowercase hex characters.
350
+ - `selected_dispatches` -- array of at most 64 dispatch objects, one per
351
+ persona, each persona once. It is the same array given to `prepare` as
352
+ `selected_dispatches`, and it must equal `dispatch_records` on every
353
+ persona's `dispatch_outcome`, `selection_surface`, and `selection_reason`.
354
+ Persona name strings are rejected.
355
+ - `timestamps` -- `{ started_at, completed_at }`, both required. Each is a UTC
356
+ ISO 8601 string ending in `Z`, such as `2026-01-01T00:05:00.000Z`. An offset
357
+ such as `+00:00` is rejected. Only `completed_at` is persisted.
358
+ - `validation` -- `{ status, reason }`. `status` must be `not_attempted` at
359
+ finalize (see above); `reason` is a non-blank string of at most 2048
360
+ characters.
361
+ - `applied_fixes` -- array of at most 2,048 non-blank strings of at most 2048
362
+ characters each. `[]` on the first call.
363
+
364
+ Each dispatch object in `selected_dispatches` and `dispatch_records` is:
365
+
366
+ - `persona` -- string, 1-64 characters, not blank. Required.
367
+ - `dispatch_outcome` -- `findings`, `empty`, `malformed`, `never_returned`, or
368
+ `validation_unavailable`. Required.
369
+ - `selection_surface` -- optional array of at most 32 unique repo-relative
370
+ paths of at most 256 characters each. No leading `/`, drive letter, or
371
+ backslash. Writing modes require a non-empty surface for `security`,
372
+ `data-migrations`, `api-contract`, `reliability`, and `performance`.
373
+ - `selection_reason` -- optional non-blank string of at most 2048 characters.
374
+
375
+ Do not send `input_finding_count` or `rejection_reason`. `finalize` derives
376
+ them into the artifact's own `dispatches` entries (input dispatch fields plus
377
+ `input_finding_count`, plus `rejection_reason` when `screen_results` carries a
378
+ rejected summary); they are not input.
379
+
380
+ A complete valid `parent_run_metadata`:
381
+
382
+ ```json
383
+ {
384
+ "run_id": "20260101-000000-a1b2c3d4",
385
+ "mode": "interactive",
386
+ "harness": "opencode",
387
+ "branch": "feature/example",
388
+ "head_sha": "0123456789abcdef0123456789abcdef01234567",
389
+ "selected_dispatches": [
390
+ { "persona": "correctness", "dispatch_outcome": "empty" },
391
+ {
392
+ "persona": "security",
393
+ "dispatch_outcome": "empty",
394
+ "selection_surface": ["src/auth/session.ts"],
395
+ "selection_reason": "Diff changes session handling."
396
+ }
397
+ ],
398
+ "timestamps": {
399
+ "started_at": "2026-01-01T00:00:00.000Z",
400
+ "completed_at": "2026-01-01T00:05:00.000Z"
401
+ },
402
+ "validation": {
403
+ "status": "not_attempted",
404
+ "reason": "Artifact validation runs after the write."
405
+ },
406
+ "applied_fixes": []
407
+ }
408
+ ```
409
+
261
410
  **Output:** `{ kind:'writing', artifact, report }` or `{ kind:'report_only', ...report }`.
262
411
  `report` carries `verdict`, `findings`, `applied_fixes`,
263
412
  `residual_actionable_work`, `advisory_outputs`, `coverage`,
@@ -282,10 +431,10 @@ Choose a fresh delimiter the same way as `screen`'s. Read the exit status:
282
431
  the report; report-only renders `report` directly and writes nothing.
283
432
  - **exit 1** -- the aggregate envelope was rejected: a shape mismatch against
284
433
  `merge`/`prepared`, a missing or extra validator-lifecycle result, an
285
- invalid plan-assessment envelope, or an artifact that failed its own
286
- internal schema check. Correct the envelope once per the never-bypass
287
- rule, then stop visibly if it is rejected again. Never hand-assemble a
288
- substitute report or artifact.
434
+ invalid plan-assessment envelope, invalid `parent_run_metadata`, or an
435
+ artifact that failed its own internal schema check. Correct the envelope
436
+ once per the never-bypass rule, then stop visibly if it is rejected again.
437
+ Never hand-assemble a substitute report or artifact.
289
438
  - **exit 2**, a missing helper, or a launch failure -- unavailable; retry
290
439
  once with identical bytes, then stop visibly.
291
440
 
@@ -220,9 +220,10 @@ structural validity, and evidence assessment separate:
220
220
  - **exit 2**, a missing or unreadable helper, or a launch failure — validation
221
221
  unavailable. Withhold the return and report the exact unavailability and what
222
222
  was withheld. Update that selected persona's preinitialized dispatch entry
223
- from `never_returned` to `dispatch_outcome: "validation_unavailable"` with
224
- `input_finding_count: 0` and, optionally, a safe `rejection_reason` naming the
225
- exit status, missing helper, or launch failure without payload values. Set
223
+ from `never_returned` to `dispatch_outcome: "validation_unavailable"`, adding
224
+ no other field: the dispatch object is strict, and `finalize` derives
225
+ `input_finding_count: 0` into the artifact. Name the exit status, missing
226
+ helper, or launch failure in Coverage, without payload values. Set
226
227
  `run_status` to `degraded`. Never omit the dispatch entry, never leave it as
227
228
  `never_returned`, never label it `malformed`, never admit the payload, and
228
229
  never fabricate a rejected-summary ledger row. `never_returned` is a
@@ -213,7 +213,7 @@ Use fully-qualified agent names inside Task calls.
213
213
  - `systematic:research:repo-research-analyst` (Scope: `architecture, patterns`) for repo-grounded patterns, conventions, and implementation reality checks
214
214
 
215
215
  **Context & Research / Sources & References gaps**
216
- - `systematic:research:learnings-researcher` for institutional knowledge and past solved problems
216
+ - `systematic:research:learnings-researcher` (make `scope: past-work` the first line of the prompt and `exclude: <path of the plan being deepened>` the second line) for institutional knowledge, past solved problems, and earlier plans, brainstorms and ideation docs
217
217
  - `systematic:research:framework-docs-researcher` for official framework or library behavior
218
218
  - `systematic:research:best-practices-researcher` for current external patterns and industry guidance
219
219
  - Add `systematic:research:git-history-analyzer` only when historical rationale or prior art is materially missing
@@ -335,6 +335,8 @@ If agent outputs conflict:
335
335
 
336
336
  Strengthen only the selected sections. Keep the plan coherent and preserve its overall structure.
337
337
 
338
+ **Cite and differentiate.** Where findings are integrated into the plan, and the researcher's results show a rejected, deferred, superseded or completed item with the same behavior or surface as the plan's work, cite it (at most 3 items) and say how the new work differs. Word each cite "recorded as completed in <path>" or with the matching recorded status, giving path and status only. Never quote text from a gitignored file into the plan. A cite never blocks the plan.
339
+
338
340
  If artifact-backed mode was used:
339
341
  - read the plan, origin document if present, and the selected section artifacts
340
342
  - also incorporate any findings already returned inline from direct-mode agents before a mid-run switch, so early results are not silently dropped