@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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fro.bot/systematic",
3
- "version": "3.26.1",
3
+ "version": "3.26.3",
4
4
  "description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
5
5
  "type": "module",
6
6
  "homepage": "https://fro.bot/systematic",
@@ -105,14 +105,14 @@
105
105
  "devDependencies": {
106
106
  "@biomejs/biome": "2.6.2",
107
107
  "@earendil-works/pi-coding-agent": "1.4.0",
108
- "@opencode-ai/plugin": "1.19.3",
109
- "@opencode-ai/sdk": "1.19.3",
108
+ "@opencode-ai/plugin": "1.19.4",
109
+ "@opencode-ai/sdk": "1.19.4",
110
110
  "@semantic-release/exec": "7.1.0",
111
111
  "@tintinweb/pi-subagents": "0.22.0",
112
112
  "@types/bun": "latest",
113
113
  "@types/js-yaml": "4.0.9",
114
114
  "@types/node": "26.6.5",
115
- "agent-browser": "0.39.1",
115
+ "agent-browser": "0.39.2",
116
116
  "ajv": "8.20.0",
117
117
  "ajv-formats": "3.0.1",
118
118
  "conventional-changelog-conventionalcommits": "10.4.1",
@@ -120,7 +120,7 @@
120
120
  "rimraf": "6.1.3",
121
121
  "semantic-release": "25.0.9",
122
122
  "semantic-release-export-data": "1.2.0",
123
- "typebox": "1.4.2",
123
+ "typebox": "1.4.3",
124
124
  "typescript": "7.0.2"
125
125
  },
126
126
  "dependencies": {
@@ -112,7 +112,7 @@ Launch research subagents. Each returns text data to the orchestrator.
112
112
  - **What Didn't Work**: Failed investigation attempts and why they failed
113
113
  - **Solution**: The actual fix with code examples (before/after when applicable)
114
114
  - **Why This Works**: Root cause explanation and why the solution addresses it
115
- - **Prevention**: Strategies to avoid recurrence, best practices, and test cases. Include concrete code examples where applicable (e.g., gem configurations, test assertions, linting rules)
115
+ - **Prevention**: Strategies to avoid recurrence, best practices, and test cases. Include concrete code examples where applicable (e.g., dependency configurations, test assertions, linting rules)
116
116
 
117
117
  **Knowledge track output sections:**
118
118
 
@@ -176,9 +176,11 @@ The orchestrating agent (main conversation) performs these steps:
176
176
 
177
177
  When updating an existing doc, preserve its file path and frontmatter structure. Update the solution, code examples, prevention tips, and any stale references. Add a `last_updated: YYYY-MM-DD` field to the frontmatter. Do not change the title unless the problem framing has materially shifted.
178
178
 
179
+ Keep the doc's lifecycle fields consistent. If it carries `status: stale`, remove `status`, `stale_reason` and `stale_date`, because the update just refreshed it. Never touch `status: superseded` or `superseded_by`. Existing legacy values (older `component`, `root_cause` and `resolution_type` values listed under `legacy_values` in `references/schema.yaml`, and the version field the schema marks LEGACY) are preserved and never rewritten; only new docs read the offered `values`.
180
+
179
181
  3. Assemble complete markdown file from the collected pieces, reading `assets/resolution-template.md` for the section structure of new docs
180
182
  4. Validate YAML frontmatter against `references/schema.yaml`
181
- 5. Create directory if needed: `mkdir -p docs/solutions/[category]/`
183
+ 5. Create the category directory on first use: `mkdir -p docs/solutions/[category]/`, where `[category]` is the directory the mapping in `references/yaml-schema.md` gives for the `problem_type`
182
184
  6. Write the file: either the updated existing doc or the new `docs/solutions/[category]/[filename].md`
183
185
 
184
186
  When creating a new doc, preserve the section order from `assets/resolution-template.md` unless the user explicitly asks for a different structure.
@@ -218,14 +220,14 @@ When invoking or recommending `ce:compound-refresh`, be explicit about the argum
218
220
  - **Specific file** when one learning or pattern doc is the likely stale artifact
219
221
  - **Module or component name** when several related docs may need review
220
222
  - **Category name** when the drift is concentrated in one solutions area
221
- - **Pattern filename or pattern topic** when the stale guidance lives in `docs/solutions/patterns/`
223
+ - **Pattern topic** when the stale guidance is a broad pattern or convention doc
222
224
 
223
225
  Examples:
224
226
 
225
227
  - `/ce:compound-refresh plugin-versioning-requirements`
226
- - `/ce:compound-refresh payments`
228
+ - `/ce:compound-refresh authentication`
227
229
  - `/ce:compound-refresh performance-issues`
228
- - `/ce:compound-refresh critical-patterns`
230
+ - `/ce:compound-refresh api-conventions`
229
231
 
230
232
  A single scope hint may still expand to multiple related docs when the change is cross-cutting within one domain, category, or pattern area.
231
233
 
@@ -298,7 +300,7 @@ The orchestrator (main conversation) performs ALL of the following in one sequen
298
300
 
299
301
  1. **Extract from conversation**: Identify the problem and solution from conversation history. Also scan the "user's auto-memory" block injected into your system prompt, if present (OpenCode only) -- use any relevant notes as supplementary context alongside conversation history. Tag any memory-sourced content incorporated into the final doc with "(auto memory [claude])"
300
302
  2. **Classify**: Read `references/schema.yaml` and `references/yaml-schema.md`, then determine track (bug vs knowledge), category, and filename
301
- 3. **Write minimal doc**: Create `docs/solutions/[category]/[filename].md` using the appropriate track template from `assets/resolution-template.md`, with:
303
+ 3. **Write minimal doc**: Create the category directory on first use (`mkdir -p`), then create `docs/solutions/[category]/[filename].md` using the appropriate track template from `assets/resolution-template.md`, with:
302
304
  - YAML frontmatter with track-appropriate fields
303
305
  - Bug track: Problem, root cause, solution with key code snippets, one prevention tip
304
306
  - Knowledge track: Context, guidance with key examples, one applicability note
@@ -391,7 +393,7 @@ Knowledge track:
391
393
  Auto memory: 2 relevant entries used as supplementary evidence
392
394
 
393
395
  Subagent Results:
394
- ✓ Context Analyzer: Identified performance_issue in brief_system, category: performance-issues/
396
+ ✓ Context Analyzer: Identified performance_issue in report_service, category: performance-issues/
395
397
  ✓ Solution Extractor: 3 code fixes, prevention strategies
396
398
  ✓ Related Docs Finder: 2 related issues
397
399
  ✓ Session History: 3 prior sessions on same branch, 2 failed approaches surfaced
@@ -402,10 +404,10 @@ Specialized Agent Reviews (Auto-Triggered):
402
404
  ✓ code-simplicity-reviewer: Solution is appropriately minimal
403
405
 
404
406
  File created:
405
- - docs/solutions/performance-issues/n-plus-one-brief-generation.md
407
+ - docs/solutions/performance-issues/n-plus-one-report-generation.md
406
408
 
407
409
  This documentation will be searchable for future reference when similar
408
- issues occur in the Email Processing or Brief System modules.
410
+ issues occur in the Report Service or Export modules.
409
411
 
410
412
  What's next?
411
413
  1. Continue workflow (recommended)
@@ -435,8 +437,8 @@ File updated:
435
437
 
436
438
  This creates a compounding knowledge system:
437
439
 
438
- 1. First time you solve "N+1 query in brief generation" → Research (30 min)
439
- 2. Document the solution → docs/solutions/performance-issues/n-plus-one-briefs.md (5 min)
440
+ 1. First time you solve "N+1 query in report generation" → Research (30 min)
441
+ 2. Document the solution → docs/solutions/performance-issues/n-plus-one-report-queries.md (5 min)
440
442
  3. Next time similar issue occurs → Quick lookup (2 min)
441
443
  4. Knowledge compounds → Team gets smarter
442
444
 
@@ -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.
@@ -23,7 +23,7 @@ Check if `$ARGUMENTS` contains `mode:autofix`. If present, strip it from argumen
23
23
  - **Skip all user questions.** Never pause for input.
24
24
  - **Process all docs in scope.** No scope narrowing questions — if no scope hint was provided, process everything.
25
25
  - **Attempt all safe actions:** Keep (no-op), Update (fix references), Consolidate (merge and delete subsumed doc), auto-Delete (unambiguous criteria met), Replace (when evidence is sufficient). If a write succeeds, record it as **applied**. If a write fails (e.g., permission denied), record the action as **recommended** in the report and continue — do not stop or ask for permissions.
26
- - **Mark as stale when uncertain.** If classification is genuinely ambiguous (Update vs Replace vs Consolidate vs Delete) or Replace evidence is insufficient, mark as stale with `status: stale`, `stale_reason`, and `stale_date` in the frontmatter. If even the stale-marking write fails, include it as a recommendation.
26
+ - **Mark as stale when uncertain.** If classification is genuinely ambiguous (Update vs Replace vs Consolidate vs Delete) or Replace evidence is insufficient, mark as stale with `status: stale`, `stale_reason`, and `stale_date` in the frontmatter (subject to the stale guard in Lifecycle Consistency). If even the stale-marking write fails, include it as a recommendation.
27
27
  - **Use conservative confidence.** In interactive mode, borderline cases get a user question. In autofix mode, borderline cases get marked stale. Err toward stale-marking over incorrect action.
28
28
  - **Always generate a report.** The report is the primary deliverable. It has two sections: **Applied** (actions that were successfully written) and **Recommended** (actions that could not be written, with full rationale so a human can apply them or run the skill interactively). The report structure is the same regardless of what permissions were granted — the only difference is which section each action lands in.
29
29
 
@@ -82,9 +82,10 @@ For each candidate artifact, classify it into one of five outcomes:
82
82
  - the user has provided enough concrete replacement context to document the successor honestly, or
83
83
  - the codebase investigation found the current approach and can document it as the successor, or
84
84
  - newer docs, pattern docs, PRs, or issues provide strong successor evidence.
85
- 8. **Delete when the code is gone.** If the referenced code, controller, or workflow no longer exists in the codebase and no successor can be found, delete the file — don't default to Keep just because the general advice is still "sound." A learning about a deleted feature misleads readers into thinking that feature still exists. When in doubt between Keep and Delete, ask the user (in interactive mode) or mark as stale (in autofix mode). But missing referenced files with no matching code is **not** a doubt case — it is strong, unambiguous Delete evidence. Auto-delete it.
85
+ 8. **Delete when the code is gone.** If the referenced code, module, or workflow no longer exists in the codebase and no successor can be found, delete the file — don't default to Keep just because the general advice is still "sound." A learning about a deleted feature misleads readers into thinking that feature still exists. When in doubt between Keep and Delete, ask the user (in interactive mode) or mark as stale (in autofix mode). But missing referenced files with no matching code is **not** a doubt case — it is strong, unambiguous Delete evidence. Auto-delete it.
86
86
  9. **Evaluate document-set design, not just accuracy.** In addition to checking whether each doc is accurate, evaluate whether it is still the right unit of knowledge. If two or more docs overlap heavily, determine whether they should remain separate, be cross-scoped more clearly, or be consolidated into one canonical document. Redundant docs are dangerous because they drift silently — two docs saying the same thing will eventually say different things.
87
87
  10. **Delete, don't archive.** There is no `_archived/` directory. When a doc is no longer useful, delete it. Git history preserves every deleted file — that is the archive. A dedicated archive directory creates problems: archived docs accumulate, pollute search results, and nobody reads them. If someone needs a deleted doc, `git log --diff-filter=D -- docs/solutions/` will find it.
88
+ 11. **Preserve legacy values.** Existing docs may carry values that `references/schema.yaml` lists under `legacy_values` (older `component` values, the `root_cause` and `resolution_type` values listed there) and the version field that the schema marks LEGACY. They are valid. Do not report them as off-vocabulary and do not rewrite them. Only a new doc, such as a Replace successor, reads the offered `values`.
88
89
 
89
90
  ## Scope Selection
90
91
 
@@ -195,7 +196,7 @@ Three guidelines that are easy to get wrong:
195
196
 
196
197
  ## Phase 1.5: Investigate Pattern Docs
197
198
 
198
- After reviewing the underlying learning docs, investigate any relevant pattern docs under `docs/solutions/patterns/`.
199
+ After reviewing the underlying learning docs, investigate any relevant pattern docs under `docs/solutions/patterns/` **only if that directory exists**. It is a legacy location: no writer creates it, so most repos never have one. Treat it as read-only. Use it as evidence and report findings about it, but do not edit, delete or create files there, and do not create the directory. If it does not exist, skip this phase.
199
200
 
200
201
  Pattern docs are high-leverage — a stale pattern is more dangerous than a stale individual learning because future work may treat it as broadly applicable guidance. Evaluate whether the generalized rule still holds given the refreshed state of the learnings it depends on.
201
202
 
@@ -290,7 +291,7 @@ After gathering evidence, assign one recommended action.
290
291
 
291
292
  ### Keep
292
293
 
293
- The learning is still accurate and useful. Do not edit the file — report that it was reviewed and remains trustworthy. Only add `last_refreshed` if you are already making a meaningful update for another reason.
294
+ The learning is still accurate and useful. Do not edit the file — report that it was reviewed and remains trustworthy. Only add `last_refreshed` if you are already making a meaningful update for another reason. The one exception is a doc that carries a stale marker: see Lifecycle Consistency.
294
295
 
295
296
  ### Update
296
297
 
@@ -328,7 +329,7 @@ By the time you identify a Replace candidate, Phase 1 investigation has already
328
329
 
329
330
  - **Sufficient evidence** — you understand both what the old learning recommended AND what the current approach is. The investigation found the current code patterns, the new file locations, the changed architecture. → Proceed to write the replacement (see Phase 4 Replace Flow).
330
331
  - **Insufficient evidence** — the drift is so fundamental that you cannot confidently document the current approach. The entire subsystem was replaced, or the new architecture is too complex to understand from a file scan alone. → Mark as stale in place:
331
- - Add `status: stale`, `stale_reason: [what you found]`, `stale_date: YYYY-MM-DD` to the frontmatter
332
+ - Add `status: stale`, `stale_reason: [what you found]`, `stale_date: YYYY-MM-DD` to the frontmatter (subject to the stale guard in Lifecycle Consistency)
332
333
  - Report what evidence you found and what is missing
333
334
  - Recommend the user run `ce:compound` after their next encounter with that area, when they have fresh problem-solving context
334
335
 
@@ -347,7 +348,7 @@ Action: delete the file. No archival directory, no metadata — just delete it.
347
348
 
348
349
  When a learning's referenced files are gone, that is strong evidence — but only that the **implementation** is gone. Before deleting, reason about whether the **problem the learning solves** is still a concern in the codebase:
349
350
 
350
- - A learning about session token storage where `auth_token.rb` is gone — does the application still handle session tokens? If so, the concept persists under a new implementation. That is Replace, not Delete.
351
+ - A learning about session token storage where `src/auth/auth-token.ts` is gone — does the application still handle session tokens? If so, the concept persists under a new implementation. That is Replace, not Delete.
351
352
  - A learning about a deprecated API endpoint where the entire feature was removed — the problem domain is gone. That is Delete.
352
353
 
353
354
  Do not search mechanically for keywords from the old learning. Instead, understand what problem the learning addresses, then investigate whether that problem domain still exists in the codebase. The agent understands concepts — use that understanding to look for where the problem lives now, not where the old code used to be.
@@ -358,13 +359,13 @@ Do not search mechanically for keywords from the old learning. Instead, understa
358
359
  - the learning is fully superseded by a clearly better successor AND the old doc adds no distinct value
359
360
  - the document is plainly redundant and adds nothing the canonical doc doesn't already say
360
361
 
361
- If the implementation is gone but the problem domain persists (the app still does auth, still processes payments, still handles migrations), classify as **Replace** — the problem still matters and the current approach should be documented.
362
+ If the implementation is gone but the problem domain persists (the app still does auth, still sends notifications, still handles migrations), classify as **Replace** — the problem still matters and the current approach should be documented.
362
363
 
363
364
  Do not keep a learning just because its general advice is "still sound" — if the specific code it references is gone, the learning misleads readers. But do not delete a learning whose problem domain is still active — that knowledge gap should be filled with a replacement.
364
365
 
365
366
  ## Pattern Guidance
366
367
 
367
- Apply the same five outcomes (Keep, Update, Consolidate, Replace, Delete) to pattern docs, but evaluate them as **derived guidance** rather than incident-level learnings. Key differences:
368
+ Apply the same five outcomes (Keep, Update, Consolidate, Replace, Delete) to pattern docs, but evaluate them as **derived guidance** rather than incident-level learnings. This covers broad pattern or convention docs filed anywhere under `docs/solutions/` by the canonical category mapping. It does not cover a legacy `docs/solutions/patterns/` directory, which stays read-only (see Phase 1.5). Key differences:
368
369
 
369
370
  - **Keep**: the underlying learnings still support the generalized rule and examples remain representative
370
371
  - **Update**: the rule holds but examples, links, scope, or supporting references drifted
@@ -469,7 +470,7 @@ Apply in-place edits only when the solution is still substantively correct.
469
470
 
470
471
  Examples of valid in-place updates:
471
472
 
472
- - Rename `app/models/auth_token.rb` reference to `app/models/session_token.rb`
473
+ - Rename `src/auth/auth-token.ts` reference to `src/auth/session-token.ts`
473
474
  - Update `module: AuthToken` to `module: SessionToken`
474
475
  - Fix outdated links to related docs
475
476
  - Refresh implementation notes after a directory move
@@ -485,6 +486,8 @@ Examples that should **not** be in-place updates:
485
486
 
486
487
  Those cases require **Replace**, not Update.
487
488
 
489
+ An Update also clears any stale marker on the doc: see Lifecycle Consistency. Preserve legacy values (Core Rule 11).
490
+
488
491
  ### Consolidate Flow
489
492
 
490
493
  The orchestrator handles consolidation directly (no subagent needed — the docs are already read and the merge is a focused edit). Process Consolidate candidates by topic cluster. For each cluster identified in Phase 1.75:
@@ -492,8 +495,8 @@ The orchestrator handles consolidation directly (no subagent needed — the docs
492
495
  1. **Confirm the canonical doc** — the broader, more current, more accurate doc in the cluster.
493
496
  2. **Extract unique content** from the subsumed doc(s) — anything the canonical doc does not already cover. This might be specific edge cases, additional prevention rules, or alternative debugging approaches.
494
497
  3. **Merge unique content** into the canonical doc in a natural location. Do not just append — integrate it where it logically belongs. If the unique content is small (a bullet point, a sentence), inline it. If it is a substantial sub-topic, add it as a clearly labeled section.
495
- 4. **Update cross-references** — if any other docs reference the subsumed doc, update those references to point to the canonical doc.
496
- 5. **Delete the subsumed doc.** Do not archive it, do not add redirect metadata — just delete the file. Git history preserves it.
498
+ 4. **Update cross-references** — if any other docs reference the subsumed doc, update those references to point to the canonical doc. Retarget any `superseded_by` pointer to the subsumed doc as described in Lifecycle Consistency.
499
+ 5. **Delete the subsumed doc**, but only once the safeguards in Lifecycle Consistency ("Retarget before removing") hold. Do not archive it, do not add redirect metadata — just delete the file. Git history preserves it.
497
500
 
498
501
  If a doc cluster has 3+ overlapping docs, process pairwise: consolidate the two most overlapping docs first, then evaluate whether the merged result should be consolidated with the next doc.
499
502
 
@@ -516,14 +519,14 @@ Do not let replacement subagents invent frontmatter fields, enum values, or sect
516
519
  1. Spawn a single subagent to write the replacement learning. Pass it:
517
520
  - The old learning's full content
518
521
  - A summary of the investigation evidence (what changed, what the current code does, why the old guidance is misleading)
519
- - The target path and category (same category as the old learning unless the category itself changed)
522
+ - The target path. File the new learning in the directory that the category mapping in `references/yaml-schema.md` gives for its `problem_type`, not simply the old learning's directory. Create that directory on first use (`mkdir -p`).
520
523
  - The relevant contents of the three support files listed above
521
- 2. The subagent writes the new learning using the support files as the source of truth: `references/schema.yaml` for frontmatter fields and enum values, `references/yaml-schema.md` for category mapping, and `assets/resolution-template.md` for section order. It should use dedicated file search and read tools if it needs additional context beyond what was passed.
522
- 3. After the subagent completes, the orchestrator deletes the old learning file. The new learning's frontmatter may include `supersedes: [old learning filename]` for traceability, but this is optional — the git history and commit message provide the same information.
524
+ 2. The subagent writes the new learning using the support files as the source of truth, and uses only the offered `values` for enum fields, never a `legacy_values` entry: `references/schema.yaml` for frontmatter fields and enum values, `references/yaml-schema.md` for category mapping, and `assets/resolution-template.md` for section order. It should use dedicated file search and read tools if it needs additional context beyond what was passed.
525
+ 3. After the subagent completes, the orchestrator retargets any `superseded_by` pointer to the old learning at the new one, then deletes the old learning file, subject to the safeguards in Lifecycle Consistency ("Retarget before removing"). Do not write a `supersedes` field or any other back-pointer into the new learning — the git history and commit message record the replacement.
523
526
 
524
527
  **When evidence is insufficient:**
525
528
 
526
- 1. Mark the learning as stale in place:
529
+ 1. Mark the learning as stale in place (subject to the stale guard in Lifecycle Consistency):
527
530
  - Add to frontmatter: `status: stale`, `stale_reason: [what you found]`, `stale_date: YYYY-MM-DD`
528
531
  2. Report what evidence was found and what is missing
529
532
  3. Recommend the user run `ce:compound` after their next encounter with that area
@@ -532,6 +535,17 @@ Do not let replacement subagents invent frontmatter fields, enum values, or sect
532
535
 
533
536
  Delete only when a learning is clearly obsolete, redundant (with no unique content to merge), or its problem domain is gone. Do not delete a document just because it is old — age alone is not a signal.
534
537
 
538
+ Before deleting, apply the Delete cascade in Lifecycle Consistency.
539
+
540
+ ### Lifecycle Consistency
541
+
542
+ The lifecycle fields (`status`, `stale_reason`, `stale_date`, `superseded_by`, `superseded_date`) must stay consistent after every action. In a user repo this prose is the only protection, since the validator runs only in Systematic's own CI. Find pointers with a content search for `superseded_by:` under `docs/solutions/`. A `superseded_by` value is a repo-root path such as `docs/solutions/best-practices/example.md`.
543
+
544
+ - **Clear stale markers.** A Keep or Update on a doc with `status: stale` removes `status`, `stale_reason` and `stale_date` from its frontmatter. The review just showed the doc is accurate, so the marker would mislead. This is the one case where Keep writes to the file. Leave a doc with no stale marker untouched.
545
+ - **Stale guard.** Never overwrite `status: superseded` with `status: stale`. A superseded doc is already retired. Skip every stale-marking write for it, leave its fields unchanged, and list it in the report as superseded and left unchanged.
546
+ - **Retarget before removing.** Before Consolidate or Replace deletes a file, find every doc whose `superseded_by` names that file and set it to the surviving doc's repo-root path (the canonical doc for Consolidate, the new learning for Replace). Retarget first, then delete, so no pointer is ever left dangling. Remove the old or subsumed doc only after the survivor file exists and every merge, retarget and cross-reference write succeeded. If any of those failed, delete nothing, leave the pointers as they are, and list the action under Recommended with the reason; this overrides autofix's general record-and-continue rule. Name each retargeted doc in the report.
547
+ - **Delete cascade.** A plain Delete leaves no surviving doc, so a superseded doc pointing at the deleted file would be retired with its replacement gone. Collect every doc whose `superseded_by` names the file being deleted, then every doc that names those docs, and so on. Keep a set of paths already handled in this run and skip any path already in it, which ends cycles. The search must cover every match, so page it if the tool caps its output. Defer the whole Delete if any pointing doc must remain: a pointing doc outside the run's scope, or, in interactive mode, one the user declines to delete. Deferring means deleting nothing and listing the Delete under Recommended, naming the pointing docs that blocked it. Otherwise delete the farthest dependents first, working back toward the target, and the target last, naming each in the Delete action. If a delete fails, stop that cascade and report which files were removed and which remain. Because every remaining doc's pointer names a doc that is still present, this leaves no dangling pointer. In interactive mode, show the full list and ask the user to confirm before deleting anything. In autofix mode, delete when nothing blocks it and list the deletions under the Delete entry in the report.
548
+
535
549
  ## Output Format
536
550
 
537
551
  **The full report MUST be printed as markdown output.** Do not summarize findings internally and then output a one-liner. The report is the deliverable — print every section in full, formatted as readable markdown with headers, tables, and bullet points.
@@ -558,6 +572,9 @@ Then for EVERY file processed, list:
558
572
  - What evidence was found -- tag any memory-sourced findings with "(auto memory [claude])" to distinguish them from codebase-sourced evidence
559
573
  - What action was taken (or recommended)
560
574
  - For Consolidate: which doc was canonical, what unique content was merged, what was deleted
575
+ - For Consolidate and Replace: any docs whose `superseded_by` was retargeted to the surviving doc
576
+ - For Delete: any superseded docs deleted with it
577
+ - For a superseded doc skipped by the stale guard: its path, listed as superseded and left unchanged
561
578
 
562
579
  For **Keep** outcomes, list them under a reviewed-without-edits section so the result is visible without creating git churn.
563
580
 
@@ -571,7 +588,7 @@ Split actions into two sections:
571
588
  - For each **Updated** file: the file path, what references were fixed, and why
572
589
  - For each **Consolidated** cluster: the canonical doc, what unique content was merged from each subsumed doc, and the subsumed docs that were deleted
573
590
  - For each **Replaced** file: what the old learning recommended vs what the current code does, and the path to the new successor
574
- - For each **Deleted** file: the file path and why it was removed (problem domain gone, fully redundant, etc.)
591
+ - For each **Deleted** file: the file path, why it was removed (problem domain gone, fully redundant, etc.), and the superseded docs deleted with it
575
592
  - For each **Marked stale** file: the file path, what evidence was found, and why it was ambiguous
576
593
 
577
594
  **Recommended** (actions that could not be written — e.g., permission denied):