@rvdbreemen/adr-kit-opencode 0.52.0 → 0.53.0

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.
Files changed (83) hide show
  1. package/.claude-plugin/plugin.json +29 -29
  2. package/README.md +865 -850
  3. package/bin/adr +0 -0
  4. package/bin/adr-audit +0 -0
  5. package/bin/adr-context +0 -0
  6. package/bin/adr-discover +0 -0
  7. package/bin/adr-doctor +0 -0
  8. package/bin/adr-generate-scripts +0 -0
  9. package/bin/adr-grill-signal +0 -0
  10. package/bin/adr-guardian +0 -0
  11. package/bin/adr-index +0 -0
  12. package/bin/adr-judge +0 -0
  13. package/bin/adr-judge-precommit +0 -0
  14. package/bin/adr-lint +0 -0
  15. package/bin/adr-mcp +96 -4
  16. package/bin/adr-migrate +0 -0
  17. package/bin/adr-quality +0 -0
  18. package/bin/adr-readiness +0 -0
  19. package/bin/adr-readiness-ci +0 -0
  20. package/bin/adr-related +0 -0
  21. package/bin/adr-renumber +254 -254
  22. package/bin/adr-retire +0 -0
  23. package/bin/adr-settings +0 -0
  24. package/bin/adr-status +0 -0
  25. package/bin/adr-suggest +0 -0
  26. package/bin/adr-watch +0 -0
  27. package/bin/adr_doctor_probes.py +2 -0
  28. package/bin/bump-version +0 -0
  29. package/clients/workflows.json +229 -229
  30. package/hooks/__init__.py +1 -1
  31. package/hooks/adapters/__init__.py +13 -13
  32. package/hooks/adapters/claude.py +27 -27
  33. package/hooks/adapters/codex.py +26 -26
  34. package/hooks/adapters/copilot.py +11 -11
  35. package/hooks/adr-hook.py +128 -128
  36. package/hooks/adr_hook_core.py +843 -843
  37. package/hooks/adr_pr_guard.py +367 -367
  38. package/instructions/ADR-guide.md +101 -48
  39. package/instructions/adr.coding.md +82 -82
  40. package/instructions/adr.review.md +182 -182
  41. package/opencode/plugin.ts +1 -4
  42. package/package.json +5 -2
  43. package/schemas/adr-context-probes.schema.json +56 -56
  44. package/schemas/adr-enforcement.schema.json +57 -57
  45. package/schemas/adr-frontmatter.schema.json +144 -144
  46. package/schemas/adr-index.schema.json +276 -276
  47. package/schemas/adr-kit-config.schema.json +371 -371
  48. package/schemas/adr-readiness.schema.json +41 -41
  49. package/schemas/client-capabilities.schema.json +503 -503
  50. package/schemas/client-certification.schema.json +101 -101
  51. package/schemas/doctor-output.schema.json +92 -92
  52. package/skills/adr/SKILL.md +780 -780
  53. package/skills/audit/SKILL.md +103 -103
  54. package/skills/context/SKILL.md +77 -77
  55. package/skills/grill/SKILL.md +84 -84
  56. package/skills/grill/agents/openai.yaml +4 -4
  57. package/skills/guardian/SKILL.md +316 -316
  58. package/skills/init/SKILL.md +499 -499
  59. package/skills/install-hooks/SKILL.md +154 -154
  60. package/skills/judge/SKILL.md +168 -168
  61. package/skills/lint/SKILL.md +321 -321
  62. package/skills/migrate/SKILL.md +313 -313
  63. package/skills/related/SKILL.md +62 -62
  64. package/skills/retire/SKILL.md +41 -41
  65. package/skills/review/SKILL.md +167 -167
  66. package/skills/settings/SKILL.md +73 -73
  67. package/skills/setup/SKILL.md +128 -128
  68. package/skills/supersede/SKILL.md +136 -136
  69. package/skills/upgrade/SKILL.md +273 -273
  70. package/templates/adr-kit-guide.md +354 -354
  71. package/templates/adr-template.canonical.md +115 -115
  72. package/templates/adr-template.madr.md +131 -131
  73. package/templates/adr-template.md +131 -131
  74. package/templates/adr-template.nygard.md +111 -111
  75. package/templates/cc-settings/guardian-hook-entry.json +9 -9
  76. package/templates/githooks/pre-commit +1 -1
  77. package/templates/github-workflows/adr-audit.yml +58 -58
  78. package/templates/github-workflows/adr-guardian-audit.yml +133 -133
  79. package/templates/github-workflows/adr-index-check.yml +30 -30
  80. package/templates/github-workflows/adr-judge.yml +31 -31
  81. package/templates/github-workflows/adr-readiness.yml +18 -18
  82. package/templates/validate_adr_template.py +38 -38
  83. package/templates/validate_adr_template.sh +74 -74
@@ -1,313 +1,313 @@
1
- ---
2
- name: migrate
3
- description: "Preview or migrate ADR metadata and body profiles. Use for legacy ADRs, MADR, Nygard, canonical conversion, or migration planning."
4
- argument-hint: "[file or directory; defaults to docs/adr/]"
5
- disable-model-invocation: true
6
- allowed-tools: [Read, Edit, Glob, Grep]
7
- ---
8
-
9
- # adr-kit migrate
10
-
11
- Use `$ARGUMENTS` as the file or directory; default to `docs/adr/`. Always
12
- preview before applying a migration.
13
-
14
- You are running `/adr-kit:migrate`. The user wants to add invariant adr-kit
15
- metadata or convert between the supported `madr`, `nygard`, and `canonical`
16
- body profiles. This is a write skill: preview first, show the result, obtain
17
- confirmation, then apply it.
18
-
19
- Start with the shared read-only discovery report:
20
-
21
- ```text
22
- python bin/adr-migrate --plan <path>
23
- ```
24
-
25
- The plan detects MADR, Nygard, canonical, conservative Y-Statement,
26
- Tyree/Akerman, and arc42 markers, including recognizable files that do not yet
27
- use an `ADR-NNN-...md` filename. It reports an exact deterministic preview
28
- when metadata and filename normalization are safe. Ambiguous, hybrid, and
29
- semantically lossy formats are routed to this guided workflow. `--plan` never
30
- writes, and detection never authorizes migration.
31
-
32
- Selective-context metadata is a separate, read-only preview:
33
-
34
- ```text
35
- python bin/adr-migrate --suggest-retrieval --dry-run <path>
36
- ```
37
-
38
- It proposes topics, components, symbols, and Decision Contract candidates from
39
- existing source facts. It never writes automatically. Review every candidate
40
- against the authoritative ADR, obtain explicit human approval, apply only the
41
- approved metadata deliberately, rebuild the generated index, and run the
42
- project retrieval probes. Do not combine this mode with profile conversion.
43
-
44
- Use the deterministic CLI whenever the source is already a supported profile:
45
-
46
- ```text
47
- python bin/adr-migrate --dry-run --to-profile madr <path>
48
- python bin/adr-migrate --to-profile madr <path>
49
- python bin/adr-migrate --check --to-profile madr <path>
50
- ```
51
-
52
- Use `--from-profile` only to disambiguate an `unknown` or `hybrid` record after
53
- reading it. The same source and target is an idempotent no-op. Existing
54
- frontmatter, Status History, relationships, references, and Enforcement remain
55
- unchanged. Use the guided patterns below only for genuinely legacy shapes that
56
- cannot be converted by semantic headings alone.
57
-
58
- ## Inputs
59
-
60
- - **No argument**: migrate ADRs in `docs/adr/` (the whole tree).
61
- - **A directory path**: migrate ADRs under that directory.
62
- - **A file path**: migrate that one file.
63
-
64
- If the path does not exist or contains no ADR files, say so plainly and stop.
65
-
66
- ## Cardinal rules
67
-
68
- 1. **Read-then-confirm.** Always read every target file before proposing edits. Always show the proposed restructure (file by file, summarised) and ask for explicit confirmation before calling Edit. Silent writes are forbidden.
69
- 2. **No fabrication.** If a target-profile section is missing and the source contains no content that maps to it, do not invent a decision. The deterministic CLI inserts an explicit TODO or `None` extension; guided migration uses a `<!-- TODO: populate -->` placeholder.
70
- 3. **Preserve content.** The migration restructures shape, not substance. Bullet points, prose, examples, and links from the source must appear in the target unchanged. Reorder; do not rewrite.
71
- 4. **Idempotent.** Running migration when the record already uses the selected target profile is a no-op.
72
- 5. **Skip files that opt out.** A file with `<!-- adr-kit-lint: skip -->` is left untouched. A file with `<!-- adr-kit-lint: advisory -->` gets a warning ("this file is currently in advisory mode; migrating will make the marker meaningless") and a confirmation prompt.
73
-
74
- ## Workflow
75
-
76
- ### Step 1: read the policy
77
-
78
- Look for `docs/adr/.adr-kit.json` (relative to project root, or the directory
79
- passed). If `template.profile` is set, use it as the target unless the user
80
- selected another profile. `template.required_sections` describes a custom
81
- shape and requires guided migration. The default target is MADR. Every profile
82
- keeps `Status`, `Status History`, `Related Decisions`, `References`, and
83
- `Enforcement`. The semantic choice headings are:
84
-
85
- | Profile | Context | Alternatives | Decision |
86
- | --- | --- | --- | --- |
87
- | MADR | `Context and Problem Statement` | `Considered Options` | `Decision Outcome` |
88
- | Nygard | `Context` | `Alternatives Considered` | `Decision` |
89
- | Canonical | `Context` | `Alternatives Considered` | `Decision` |
90
-
91
- MADR also requires `Decision Drivers`. Use the shared registry and selected
92
- template as the ordering contract instead of assuming canonical headings.
93
-
94
- ### Step 2: classify each input file
95
-
96
- For each file, determine:
97
-
98
- - **Already on the selected profile** (required semantic sections present) -> skip, report as "no changes needed".
99
- - **Marker says skip** -> skip, report as "skipped per marker".
100
- - **Marker says advisory** -> ask "advisory marker is on this file; migrate anyway?"
101
- - **Migratable** -> identify which patterns apply (see next section).
102
-
103
- ### Step 3: identify patterns
104
-
105
- The skill body below documents the patterns observed in real-world legacy ADRs. Apply each pattern that fits, in this order. Do not invent new transformations.
106
-
107
- #### Pattern A: inline status promotion
108
-
109
- Source:
110
-
111
- ```markdown
112
- # ADR-NNN Title
113
-
114
- **Status:** Accepted
115
- **Date:** 2026-04-25
116
- **Supersedes:** ADR-XXX (optional)
117
- ```
118
-
119
- Target:
120
-
121
- ```markdown
122
- # ADR-NNN Title
123
-
124
- ## Status
125
-
126
- Accepted, 2026-04-25. Supersedes ADR-XXX (optional).
127
- ```
128
-
129
- If only `**Status:**` exists with no `**Date:**`, the Status section reads `Accepted` (without date).
130
-
131
- #### Pattern B: alternatives inside Context
132
-
133
- Source has a `### Alternatives considered:` (or `### Alternatives considered and rejected`) heading nested inside `## Context`. Target: lift the entire block out, change `### ` to `## `, and place the new top-level `## Alternatives Considered` heading between `## Decision` and `## Consequences`. Preserve content verbatim; only the heading level and position change.
134
-
135
- #### Pattern C: alternatives inside Consequences
136
-
137
- Same as Pattern B but the source nests alternatives inside `## Consequences`. Target: same restructure, place between Decision and Consequences.
138
-
139
- #### Pattern D: Related to Related Decisions + References split
140
-
141
- Source: a `## Related` section that mixes ADR/TASK references with file paths, PR links, vendor doc URLs, internal docs.
142
-
143
- Target: rename to `## Related Decisions`. Move pure-external references (files, URLs, PRs that are not ADR or TASK identifiers) to a new `## References` section that follows. Keep ADR-NNN and TASK-NNN entries in `## Related Decisions`.
144
-
145
- Heuristic for splitting:
146
- - Lines starting with `ADR-`, `TASK-`, or referencing those identifiers -> `## Related Decisions`.
147
- - Lines starting with backticks (file path), URL, or `PR `/`Issue ` references -> `## References`.
148
- - When ambiguous, leave in `## Related Decisions` (safer default).
149
-
150
- #### Pattern E: missing References with no inline content
151
-
152
- If after Pattern D there are no external references to populate `## References`, create the section with a placeholder:
153
-
154
- ```markdown
155
- ## References
156
-
157
- <!-- TODO: populate from inline citations or external sources cited in the body. -->
158
- ```
159
-
160
- Never invent references. The placeholder makes it clear to a human reviewer that this is a known gap.
161
-
162
- #### Pattern F: missing Alternatives Considered with no source
163
-
164
- If the source legitimately has no alternatives discussion anywhere, create the section with a placeholder:
165
-
166
- ```markdown
167
- ## Alternatives Considered
168
-
169
- <!-- TODO: document at least 2 alternatives that were considered and rejected, with reasoning. -->
170
- ```
171
-
172
- This is a real gap a human should fill, but the skill must not fabricate.
173
-
174
- #### Guided Pattern G: unsupported MADR variant
175
-
176
- Source is a MADR-shaped ADR (madr.github.io): YAML frontmatter carrying
177
- `status:` / `date:`, plus `## Context and Problem Statement`,
178
- `## Considered Options`, `## Decision Outcome`, and often
179
- `## Pros and Cons of the Options` and `### Positive Consequences` /
180
- `### Negative Consequences` subsections. Standard MADR records are supported
181
- directly and should use `bin/adr-migrate --to-profile ...`. Use this mapping
182
- only for an `unknown` or `hybrid` MADR variant that the semantic registry
183
- cannot convert safely.
184
-
185
- Mapping to semantic roles (content moves verbatim; target headings come from
186
- the selected profile):
187
-
188
- | MADR source | Semantic target |
189
- | --- | --- |
190
- | frontmatter `status:` + `date:` (or inline `* Status:` lines) | invariant `Status`; preserve and complete frontmatter |
191
- | `## Context and Problem Statement` plus `## Decision Drivers` | `context` and `drivers` roles |
192
- | `## Considered Options` plus `## Pros and Cons of the Options` | `alternatives` role; keep the chosen option marked |
193
- | `## Decision Outcome` ("Chosen option: ..., because ...") | `decision` role |
194
- | positive/negative consequence subsections or bullets | `consequences` role |
195
- | `## Links` / `## More Information` | split per Pattern D: ADR identifiers to `## Related Decisions`, external links to `## References` |
196
-
197
- If the source has no Related Decisions or References content, apply
198
- Patterns E / F TODO placeholders. Never invent rejection reasons that the
199
- Pros and Cons section does not state; if an option has no documented cons,
200
- carry it over with `<!-- TODO: state why this option was rejected -->`.
201
-
202
- #### Guided Pattern H: minimal or unsupported Nygard variant
203
-
204
- Source is a Nygard / adr-tools ADR: exactly `## Status`, `## Context`,
205
- `## Decision`, `## Consequences`, nothing else. Standard Nygard records are a
206
- supported source profile. Prefer the deterministic CLI, which preserves those
207
- four sections and adds the selected profile's explicit extension placeholders.
208
-
209
- The four sections map directly to semantic roles and their content is
210
- preserved verbatim. Missing target-profile sections are created with explicit
211
- TODO or `None` placeholders:
212
-
213
- - `## Alternatives Considered` between Decision and Consequences, via
214
- Pattern F's placeholder.
215
- - `## Related Decisions` after Consequences, with `- None.` unless the
216
- Status or Context text references other ADRs (e.g. "Supersedes ADR-9"),
217
- in which case those references move here.
218
- - `## References` last, via Pattern E's placeholder.
219
-
220
- Nygard Status sections often contain supersession links ("Superseded by
221
- [ADR-12]"). Keep them in `## Status` as prose and mirror the ADR identifier
222
- into `## Related Decisions`.
223
-
224
- ### Step 4: present the plan
225
-
226
- Before applying any edit, show the user a per-file summary:
227
-
228
- ```
229
- Proposed migration plan (3 files):
230
-
231
- ADR-007-timer-based-task-scheduling.md
232
- Pattern A: inline `**Status:**` -> `## Status` heading
233
- Pattern D: `## Related` -> `## Related Decisions` + new `## References`
234
-
235
- ADR-029-simple-xhr-ota-flash.md
236
- Pattern A: inline `**Status:**` -> `## Status` heading
237
- Pattern F: missing `## Alternatives Considered`, will create with TODO placeholder
238
-
239
- ADR-058-nonblocking-pic-command-response.md
240
- Pattern A: inline `**Status:**` -> `## Status` heading
241
- Pattern F: missing `## Alternatives Considered`, will create with TODO placeholder
242
- Pattern E: missing `## References`, will create with TODO placeholder
243
- No `## Related Decisions` content found in source; will create with `- None.`
244
-
245
- Confirm to apply (y/n)?
246
- ```
247
-
248
- If the user declines, stop without writing.
249
-
250
- ### Step 5: apply edits
251
-
252
- After confirmation, apply each transformation via Edit. One Edit per logical change, so the diff is reviewable. Report what was changed per file.
253
-
254
- ### Step 6: post-migration verification
255
-
256
- After all edits, suggest the user run `/adr-kit:lint <path>` to confirm the migrated files now PASS strictly. Do NOT run lint yourself: that is a separate skill the user invokes.
257
-
258
- ## What you do not do
259
-
260
- - You do not modify the body content of sections. Headings move; prose stays.
261
- - You do not auto-fabricate Alternatives Considered or References content. Use TODO placeholders.
262
- - You do not rename ADR files (Consistency-gate filename FAILs). Out of scope.
263
- - You do not edit ADRs that already PASS strict.
264
- - You do not invoke `/adr-kit:lint` after migration. The user decides when to verify.
265
-
266
- ## Reporting format
267
-
268
- Single-file migration:
269
-
270
- ```
271
- ADR-007-timer-based-task-scheduling.md migrated.
272
- Applied: Pattern A (Status promotion), Pattern D (Related split).
273
- Run /adr-kit:lint on this file to verify.
274
- ```
275
-
276
- Directory migration:
277
-
278
- ```
279
- Migrated 3 of 80 candidate files. 1 already on the target profile (skipped). 76 deferred (no patterns matched, manual review needed).
280
-
281
- Applied:
282
- ADR-007 (A, D)
283
- ADR-029 (A, F)
284
- ADR-058 (A, F, E, no Related content)
285
-
286
- Skipped:
287
- ADR-022 (already on the target profile)
288
-
289
- Deferred (manual review): 76 files.
290
- Reason: complex shape that did not match any of patterns A through H. Inspect by hand.
291
-
292
- Run /adr-kit:lint docs/adr/ to confirm overall result.
293
- ```
294
-
295
- The aggregate's bottom line tells the user one concrete next step (run lint), never invents a status the migration did not actually achieve.
296
-
297
- ## Edge cases
298
-
299
- - **Multiple inline metadata lines**: source has `**Status:**`, `**Date:**`, `**Supersedes:**`, `**Amended by:**`, etc. Fold all into the new `## Status` section as a comma-separated sentence. Order: Status, date, supersedes/amended.
300
- - **Empty Related section**: source has `## Related` with no body or only whitespace. Target: `## Related Decisions` with `- None.` body.
301
- - **Anchor comments inline at top**: source has a `Renumbered from ADR-XXX ...` line before `**Date:**`. Fold into the new `## Status` section as a trailing sentence: "Renumbered from ADR-XXX on YYYY-MM-DD to resolve duplicate numbering. Content unchanged."
302
- - **Body has Markdown that confuses heading-detection**: e.g. a `## ` inside a fenced code block. The skill treats only headings *outside* code fences as semantic sections. If unsure, ask the user.
303
- - **Source uses `## Pros and Cons` or `## Decision drivers`**: if the file matches the MADR shape, Pattern G consumes these (`## Pros and Cons of the Options` feeds `## Alternatives Considered`, `## Decision Drivers` folds into `## Context`). Otherwise do not rename these; they are project-specific and the user can address custom subsections in a follow-up pass.
304
-
305
- ## Anti-patterns to refuse
306
-
307
- If the migration would require any of these, refuse and explain:
308
-
309
- - Renaming ADR files. Out of scope; surfaces commit / cross-ref breakage.
310
- - Modifying body prose ("the Decision section reads better if reorganised..."). Restructure shape only.
311
- - Fabricating Alternatives or References. TODO placeholder is the answer.
312
- - Skipping the user confirmation. Read-then-confirm is non-negotiable.
313
- - Running `/adr-kit:lint` automatically after migration. The user decides.
1
+ ---
2
+ name: migrate
3
+ description: "Preview or migrate ADR metadata and body profiles. Use for legacy ADRs, MADR, Nygard, canonical conversion, or migration planning."
4
+ argument-hint: "[file or directory; defaults to docs/adr/]"
5
+ disable-model-invocation: true
6
+ allowed-tools: [Read, Edit, Glob, Grep]
7
+ ---
8
+
9
+ # adr-kit migrate
10
+
11
+ Use `$ARGUMENTS` as the file or directory; default to `docs/adr/`. Always
12
+ preview before applying a migration.
13
+
14
+ You are running `/adr-kit:migrate`. The user wants to add invariant adr-kit
15
+ metadata or convert between the supported `madr`, `nygard`, and `canonical`
16
+ body profiles. This is a write skill: preview first, show the result, obtain
17
+ confirmation, then apply it.
18
+
19
+ Start with the shared read-only discovery report:
20
+
21
+ ```text
22
+ python bin/adr-migrate --plan <path>
23
+ ```
24
+
25
+ The plan detects MADR, Nygard, canonical, conservative Y-Statement,
26
+ Tyree/Akerman, and arc42 markers, including recognizable files that do not yet
27
+ use an `ADR-NNN-...md` filename. It reports an exact deterministic preview
28
+ when metadata and filename normalization are safe. Ambiguous, hybrid, and
29
+ semantically lossy formats are routed to this guided workflow. `--plan` never
30
+ writes, and detection never authorizes migration.
31
+
32
+ Selective-context metadata is a separate, read-only preview:
33
+
34
+ ```text
35
+ python bin/adr-migrate --suggest-retrieval --dry-run <path>
36
+ ```
37
+
38
+ It proposes topics, components, symbols, and Decision Contract candidates from
39
+ existing source facts. It never writes automatically. Review every candidate
40
+ against the authoritative ADR, obtain explicit human approval, apply only the
41
+ approved metadata deliberately, rebuild the generated index, and run the
42
+ project retrieval probes. Do not combine this mode with profile conversion.
43
+
44
+ Use the deterministic CLI whenever the source is already a supported profile:
45
+
46
+ ```text
47
+ python bin/adr-migrate --dry-run --to-profile madr <path>
48
+ python bin/adr-migrate --to-profile madr <path>
49
+ python bin/adr-migrate --check --to-profile madr <path>
50
+ ```
51
+
52
+ Use `--from-profile` only to disambiguate an `unknown` or `hybrid` record after
53
+ reading it. The same source and target is an idempotent no-op. Existing
54
+ frontmatter, Status History, relationships, references, and Enforcement remain
55
+ unchanged. Use the guided patterns below only for genuinely legacy shapes that
56
+ cannot be converted by semantic headings alone.
57
+
58
+ ## Inputs
59
+
60
+ - **No argument**: migrate ADRs in `docs/adr/` (the whole tree).
61
+ - **A directory path**: migrate ADRs under that directory.
62
+ - **A file path**: migrate that one file.
63
+
64
+ If the path does not exist or contains no ADR files, say so plainly and stop.
65
+
66
+ ## Cardinal rules
67
+
68
+ 1. **Read-then-confirm.** Always read every target file before proposing edits. Always show the proposed restructure (file by file, summarised) and ask for explicit confirmation before calling Edit. Silent writes are forbidden.
69
+ 2. **No fabrication.** If a target-profile section is missing and the source contains no content that maps to it, do not invent a decision. The deterministic CLI inserts an explicit TODO or `None` extension; guided migration uses a `<!-- TODO: populate -->` placeholder.
70
+ 3. **Preserve content.** The migration restructures shape, not substance. Bullet points, prose, examples, and links from the source must appear in the target unchanged. Reorder; do not rewrite.
71
+ 4. **Idempotent.** Running migration when the record already uses the selected target profile is a no-op.
72
+ 5. **Skip files that opt out.** A file with `<!-- adr-kit-lint: skip -->` is left untouched. A file with `<!-- adr-kit-lint: advisory -->` gets a warning ("this file is currently in advisory mode; migrating will make the marker meaningless") and a confirmation prompt.
73
+
74
+ ## Workflow
75
+
76
+ ### Step 1: read the policy
77
+
78
+ Look for `docs/adr/.adr-kit.json` (relative to project root, or the directory
79
+ passed). If `template.profile` is set, use it as the target unless the user
80
+ selected another profile. `template.required_sections` describes a custom
81
+ shape and requires guided migration. The default target is MADR. Every profile
82
+ keeps `Status`, `Status History`, `Related Decisions`, `References`, and
83
+ `Enforcement`. The semantic choice headings are:
84
+
85
+ | Profile | Context | Alternatives | Decision |
86
+ | --- | --- | --- | --- |
87
+ | MADR | `Context and Problem Statement` | `Considered Options` | `Decision Outcome` |
88
+ | Nygard | `Context` | `Alternatives Considered` | `Decision` |
89
+ | Canonical | `Context` | `Alternatives Considered` | `Decision` |
90
+
91
+ MADR also requires `Decision Drivers`. Use the shared registry and selected
92
+ template as the ordering contract instead of assuming canonical headings.
93
+
94
+ ### Step 2: classify each input file
95
+
96
+ For each file, determine:
97
+
98
+ - **Already on the selected profile** (required semantic sections present) -> skip, report as "no changes needed".
99
+ - **Marker says skip** -> skip, report as "skipped per marker".
100
+ - **Marker says advisory** -> ask "advisory marker is on this file; migrate anyway?"
101
+ - **Migratable** -> identify which patterns apply (see next section).
102
+
103
+ ### Step 3: identify patterns
104
+
105
+ The skill body below documents the patterns observed in real-world legacy ADRs. Apply each pattern that fits, in this order. Do not invent new transformations.
106
+
107
+ #### Pattern A: inline status promotion
108
+
109
+ Source:
110
+
111
+ ```markdown
112
+ # ADR-NNN Title
113
+
114
+ **Status:** Accepted
115
+ **Date:** 2026-04-25
116
+ **Supersedes:** ADR-XXX (optional)
117
+ ```
118
+
119
+ Target:
120
+
121
+ ```markdown
122
+ # ADR-NNN Title
123
+
124
+ ## Status
125
+
126
+ Accepted, 2026-04-25. Supersedes ADR-XXX (optional).
127
+ ```
128
+
129
+ If only `**Status:**` exists with no `**Date:**`, the Status section reads `Accepted` (without date).
130
+
131
+ #### Pattern B: alternatives inside Context
132
+
133
+ Source has a `### Alternatives considered:` (or `### Alternatives considered and rejected`) heading nested inside `## Context`. Target: lift the entire block out, change `### ` to `## `, and place the new top-level `## Alternatives Considered` heading between `## Decision` and `## Consequences`. Preserve content verbatim; only the heading level and position change.
134
+
135
+ #### Pattern C: alternatives inside Consequences
136
+
137
+ Same as Pattern B but the source nests alternatives inside `## Consequences`. Target: same restructure, place between Decision and Consequences.
138
+
139
+ #### Pattern D: Related to Related Decisions + References split
140
+
141
+ Source: a `## Related` section that mixes ADR/TASK references with file paths, PR links, vendor doc URLs, internal docs.
142
+
143
+ Target: rename to `## Related Decisions`. Move pure-external references (files, URLs, PRs that are not ADR or TASK identifiers) to a new `## References` section that follows. Keep ADR-NNN and TASK-NNN entries in `## Related Decisions`.
144
+
145
+ Heuristic for splitting:
146
+ - Lines starting with `ADR-`, `TASK-`, or referencing those identifiers -> `## Related Decisions`.
147
+ - Lines starting with backticks (file path), URL, or `PR `/`Issue ` references -> `## References`.
148
+ - When ambiguous, leave in `## Related Decisions` (safer default).
149
+
150
+ #### Pattern E: missing References with no inline content
151
+
152
+ If after Pattern D there are no external references to populate `## References`, create the section with a placeholder:
153
+
154
+ ```markdown
155
+ ## References
156
+
157
+ <!-- TODO: populate from inline citations or external sources cited in the body. -->
158
+ ```
159
+
160
+ Never invent references. The placeholder makes it clear to a human reviewer that this is a known gap.
161
+
162
+ #### Pattern F: missing Alternatives Considered with no source
163
+
164
+ If the source legitimately has no alternatives discussion anywhere, create the section with a placeholder:
165
+
166
+ ```markdown
167
+ ## Alternatives Considered
168
+
169
+ <!-- TODO: document at least 2 alternatives that were considered and rejected, with reasoning. -->
170
+ ```
171
+
172
+ This is a real gap a human should fill, but the skill must not fabricate.
173
+
174
+ #### Guided Pattern G: unsupported MADR variant
175
+
176
+ Source is a MADR-shaped ADR (madr.github.io): YAML frontmatter carrying
177
+ `status:` / `date:`, plus `## Context and Problem Statement`,
178
+ `## Considered Options`, `## Decision Outcome`, and often
179
+ `## Pros and Cons of the Options` and `### Positive Consequences` /
180
+ `### Negative Consequences` subsections. Standard MADR records are supported
181
+ directly and should use `bin/adr-migrate --to-profile ...`. Use this mapping
182
+ only for an `unknown` or `hybrid` MADR variant that the semantic registry
183
+ cannot convert safely.
184
+
185
+ Mapping to semantic roles (content moves verbatim; target headings come from
186
+ the selected profile):
187
+
188
+ | MADR source | Semantic target |
189
+ | --- | --- |
190
+ | frontmatter `status:` + `date:` (or inline `* Status:` lines) | invariant `Status`; preserve and complete frontmatter |
191
+ | `## Context and Problem Statement` plus `## Decision Drivers` | `context` and `drivers` roles |
192
+ | `## Considered Options` plus `## Pros and Cons of the Options` | `alternatives` role; keep the chosen option marked |
193
+ | `## Decision Outcome` ("Chosen option: ..., because ...") | `decision` role |
194
+ | positive/negative consequence subsections or bullets | `consequences` role |
195
+ | `## Links` / `## More Information` | split per Pattern D: ADR identifiers to `## Related Decisions`, external links to `## References` |
196
+
197
+ If the source has no Related Decisions or References content, apply
198
+ Patterns E / F TODO placeholders. Never invent rejection reasons that the
199
+ Pros and Cons section does not state; if an option has no documented cons,
200
+ carry it over with `<!-- TODO: state why this option was rejected -->`.
201
+
202
+ #### Guided Pattern H: minimal or unsupported Nygard variant
203
+
204
+ Source is a Nygard / adr-tools ADR: exactly `## Status`, `## Context`,
205
+ `## Decision`, `## Consequences`, nothing else. Standard Nygard records are a
206
+ supported source profile. Prefer the deterministic CLI, which preserves those
207
+ four sections and adds the selected profile's explicit extension placeholders.
208
+
209
+ The four sections map directly to semantic roles and their content is
210
+ preserved verbatim. Missing target-profile sections are created with explicit
211
+ TODO or `None` placeholders:
212
+
213
+ - `## Alternatives Considered` between Decision and Consequences, via
214
+ Pattern F's placeholder.
215
+ - `## Related Decisions` after Consequences, with `- None.` unless the
216
+ Status or Context text references other ADRs (e.g. "Supersedes ADR-9"),
217
+ in which case those references move here.
218
+ - `## References` last, via Pattern E's placeholder.
219
+
220
+ Nygard Status sections often contain supersession links ("Superseded by
221
+ [ADR-12]"). Keep them in `## Status` as prose and mirror the ADR identifier
222
+ into `## Related Decisions`.
223
+
224
+ ### Step 4: present the plan
225
+
226
+ Before applying any edit, show the user a per-file summary:
227
+
228
+ ```
229
+ Proposed migration plan (3 files):
230
+
231
+ ADR-007-timer-based-task-scheduling.md
232
+ Pattern A: inline `**Status:**` -> `## Status` heading
233
+ Pattern D: `## Related` -> `## Related Decisions` + new `## References`
234
+
235
+ ADR-029-simple-xhr-ota-flash.md
236
+ Pattern A: inline `**Status:**` -> `## Status` heading
237
+ Pattern F: missing `## Alternatives Considered`, will create with TODO placeholder
238
+
239
+ ADR-058-nonblocking-pic-command-response.md
240
+ Pattern A: inline `**Status:**` -> `## Status` heading
241
+ Pattern F: missing `## Alternatives Considered`, will create with TODO placeholder
242
+ Pattern E: missing `## References`, will create with TODO placeholder
243
+ No `## Related Decisions` content found in source; will create with `- None.`
244
+
245
+ Confirm to apply (y/n)?
246
+ ```
247
+
248
+ If the user declines, stop without writing.
249
+
250
+ ### Step 5: apply edits
251
+
252
+ After confirmation, apply each transformation via Edit. One Edit per logical change, so the diff is reviewable. Report what was changed per file.
253
+
254
+ ### Step 6: post-migration verification
255
+
256
+ After all edits, suggest the user run `/adr-kit:lint <path>` to confirm the migrated files now PASS strictly. Do NOT run lint yourself: that is a separate skill the user invokes.
257
+
258
+ ## What you do not do
259
+
260
+ - You do not modify the body content of sections. Headings move; prose stays.
261
+ - You do not auto-fabricate Alternatives Considered or References content. Use TODO placeholders.
262
+ - You do not rename ADR files (Consistency-gate filename FAILs). Out of scope.
263
+ - You do not edit ADRs that already PASS strict.
264
+ - You do not invoke `/adr-kit:lint` after migration. The user decides when to verify.
265
+
266
+ ## Reporting format
267
+
268
+ Single-file migration:
269
+
270
+ ```
271
+ ADR-007-timer-based-task-scheduling.md migrated.
272
+ Applied: Pattern A (Status promotion), Pattern D (Related split).
273
+ Run /adr-kit:lint on this file to verify.
274
+ ```
275
+
276
+ Directory migration:
277
+
278
+ ```
279
+ Migrated 3 of 80 candidate files. 1 already on the target profile (skipped). 76 deferred (no patterns matched, manual review needed).
280
+
281
+ Applied:
282
+ ADR-007 (A, D)
283
+ ADR-029 (A, F)
284
+ ADR-058 (A, F, E, no Related content)
285
+
286
+ Skipped:
287
+ ADR-022 (already on the target profile)
288
+
289
+ Deferred (manual review): 76 files.
290
+ Reason: complex shape that did not match any of patterns A through H. Inspect by hand.
291
+
292
+ Run /adr-kit:lint docs/adr/ to confirm overall result.
293
+ ```
294
+
295
+ The aggregate's bottom line tells the user one concrete next step (run lint), never invents a status the migration did not actually achieve.
296
+
297
+ ## Edge cases
298
+
299
+ - **Multiple inline metadata lines**: source has `**Status:**`, `**Date:**`, `**Supersedes:**`, `**Amended by:**`, etc. Fold all into the new `## Status` section as a comma-separated sentence. Order: Status, date, supersedes/amended.
300
+ - **Empty Related section**: source has `## Related` with no body or only whitespace. Target: `## Related Decisions` with `- None.` body.
301
+ - **Anchor comments inline at top**: source has a `Renumbered from ADR-XXX ...` line before `**Date:**`. Fold into the new `## Status` section as a trailing sentence: "Renumbered from ADR-XXX on YYYY-MM-DD to resolve duplicate numbering. Content unchanged."
302
+ - **Body has Markdown that confuses heading-detection**: e.g. a `## ` inside a fenced code block. The skill treats only headings *outside* code fences as semantic sections. If unsure, ask the user.
303
+ - **Source uses `## Pros and Cons` or `## Decision drivers`**: if the file matches the MADR shape, Pattern G consumes these (`## Pros and Cons of the Options` feeds `## Alternatives Considered`, `## Decision Drivers` folds into `## Context`). Otherwise do not rename these; they are project-specific and the user can address custom subsections in a follow-up pass.
304
+
305
+ ## Anti-patterns to refuse
306
+
307
+ If the migration would require any of these, refuse and explain:
308
+
309
+ - Renaming ADR files. Out of scope; surfaces commit / cross-ref breakage.
310
+ - Modifying body prose ("the Decision section reads better if reorganised..."). Restructure shape only.
311
+ - Fabricating Alternatives or References. TODO placeholder is the answer.
312
+ - Skipping the user confirmation. Read-then-confirm is non-negotiable.
313
+ - Running `/adr-kit:lint` automatically after migration. The user decides.