codeassembly-guidance 0.0.0 → 0.2.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 (219) hide show
  1. package/.meta/changelog.json +1320 -0
  2. package/CHANGELOG.md +315 -0
  3. package/LICENSE +7 -0
  4. package/README.md +195 -1
  5. package/bin/codeassembly-validate-preferences.js +18 -0
  6. package/content/_partials/README.md +192 -0
  7. package/content/_partials/code-descriptions.md +4 -0
  8. package/content/_partials/code-style.md +7 -0
  9. package/content/_partials/comment-discipline.md +89 -0
  10. package/content/_partials/concision.md +3 -0
  11. package/content/_partials/diff-audit-checklist.md +9 -0
  12. package/content/_partials/file-access.md +4 -0
  13. package/content/_partials/live-repo-writes.md +13 -0
  14. package/content/_partials/plain-speech-calibration.md +70 -0
  15. package/content/_partials/plain-speech.md +13 -0
  16. package/content/_partials/prose-line-breaks.md +3 -0
  17. package/content/_partials/record-marker.md +1 -0
  18. package/content/_partials/reduced-object-relative.md +28 -0
  19. package/content/_partials/shell-commands.md +3 -0
  20. package/content/_partials/target-file-set-resolution.md +22 -0
  21. package/content/_partials/technical-recommendations.md +6 -0
  22. package/content/_partials/test-structure-audit-checklist.md +7 -0
  23. package/content/_partials/ticket-assessment-baseline.md +12 -0
  24. package/content/_partials/ticket-assessment.md +202 -0
  25. package/content/_partials/work-type-choice.md +13 -0
  26. package/content/codeassembly-content.yaml +59 -0
  27. package/content/collections/all.md +11 -0
  28. package/content/collections/atlassian.md +17 -0
  29. package/content/collections/recommended.md +41 -0
  30. package/content/collections/triage.md +13 -0
  31. package/content/collections/williamthorsen.md +26 -0
  32. package/content/guidance/README.md +22 -0
  33. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  34. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  35. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  36. package/content/guidance/rulebooks/accessibility-conventions.md +38 -0
  37. package/content/guidance/rulebooks/cli-conventions.md +192 -0
  38. package/content/guidance/rulebooks/codeassembly-content-specification.md +184 -0
  39. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  40. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  41. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  42. package/content/guidance/rulebooks/live-worktree-policy.md +19 -0
  43. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  44. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  45. package/content/guidance/rulebooks/shell-conventions.md +273 -0
  46. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  47. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  48. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +60 -0
  49. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  50. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  51. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  52. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  53. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  54. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  55. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  56. package/content/guidance/shared/AGENTS.md +51 -0
  57. package/content/scripts/README.md +44 -0
  58. package/content/scripts/check-branch-currency.mjs +11 -0
  59. package/content/scripts/check-prose.mjs +171 -0
  60. package/content/scripts/describe-change.mjs +165 -0
  61. package/content/scripts/get-ticket-id.sh +131 -0
  62. package/content/scripts/manage-jira-ticket.mjs +214 -0
  63. package/content/scripts/resolve-frontmatter.sh +540 -0
  64. package/content/scripts/resolve-review-run.mjs +12 -0
  65. package/content/scripts/select-lede-exemplars.mjs +208 -0
  66. package/content/scripts/validate-preferences.mjs +146 -0
  67. package/content/skills/_data/action-items.md +83 -0
  68. package/content/skills/_data/artifact-conventions.md +1001 -0
  69. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  70. package/content/skills/_data/branch-currency.md +36 -0
  71. package/content/skills/_data/branch-format.md +34 -0
  72. package/content/skills/_data/change-record.md +163 -0
  73. package/content/skills/_data/complexity-classification.md +58 -0
  74. package/content/skills/_data/concision.md +23 -0
  75. package/content/skills/_data/deployed-file-provenance.md +46 -0
  76. package/content/skills/_data/design-priorities.md +76 -0
  77. package/content/skills/_data/gh-body-file.md +30 -0
  78. package/content/skills/_data/git-commands.md +39 -0
  79. package/content/skills/_data/naming-conventions.md +50 -0
  80. package/content/skills/_data/pr-resolution.md +25 -0
  81. package/content/skills/_data/pr-source-resolution.md +36 -0
  82. package/content/skills/_data/project-stage.md +32 -0
  83. package/content/skills/_data/recommendation-gradient.md +92 -0
  84. package/content/skills/_data/scope-and-deferral.md +83 -0
  85. package/content/skills/_data/spike-conventions.md +89 -0
  86. package/content/skills/_data/ticket-evaluation.md +13 -0
  87. package/content/skills/_data/ticket-id-extraction.md +43 -0
  88. package/content/skills/_data/ticket-source-resolution.md +180 -0
  89. package/content/skills/_data/title-templates.md +632 -0
  90. package/content/skills/_data/title-voice.md +17 -0
  91. package/content/skills/_data/work-types.json +168 -0
  92. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  93. package/content/skills/_partials/action-items.md +22 -0
  94. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  95. package/content/skills/_partials/commit-title-rendering.md +14 -0
  96. package/content/skills/_partials/gh-body-file.md +22 -0
  97. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  98. package/content/skills/_partials/nested-list-indent.md +9 -0
  99. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  100. package/content/skills/_partials/next-steps-after-review.md +350 -0
  101. package/content/skills/_partials/option-format.md +85 -0
  102. package/content/skills/_partials/plan-template.md +97 -0
  103. package/content/skills/_partials/split-launch-prompts.md +5 -0
  104. package/content/skills/_partials/split-ticket-compose.md +5 -0
  105. package/content/skills/_partials/split-ticket-create.md +3 -0
  106. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  107. package/content/skills/_partials/ticket-concision.md +18 -0
  108. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  109. package/content/skills/_partials/ticket-placement.md +14 -0
  110. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  111. package/content/skills/_partials/ticket-skeleton.md +13 -0
  112. package/content/skills/add-change-record/SKILL.md +136 -0
  113. package/content/skills/add-test-ids/SKILL.md +51 -0
  114. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  115. package/content/skills/anti-patterns/SKILL.md +57 -0
  116. package/content/skills/assess-ticket/SKILL.md +46 -0
  117. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  118. package/content/skills/assess-usability/SKILL.md +96 -0
  119. package/content/skills/brainstorming/SKILL.md +107 -0
  120. package/content/skills/capture-event/SKILL.md +108 -0
  121. package/content/skills/capture-event/capture-event.mjs +216 -0
  122. package/content/skills/capture-feedback/SKILL.md +71 -0
  123. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  124. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  125. package/content/skills/classify-complexity/SKILL.md +92 -0
  126. package/content/skills/collaborate/SKILL.md +86 -0
  127. package/content/skills/condense-branch/SKILL.md +83 -0
  128. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  129. package/content/skills/create-commit/SKILL.md +65 -0
  130. package/content/skills/create-devlog/SKILL.md +108 -0
  131. package/content/skills/create-gh-pr/SKILL.md +121 -0
  132. package/content/skills/create-pr/SKILL.md +150 -0
  133. package/content/skills/create-ticket/SKILL.md +395 -0
  134. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  135. package/content/skills/derive-session-context/derive-session-context.mjs +149 -0
  136. package/content/skills/design-and-plan/SKILL.md +197 -0
  137. package/content/skills/development-workflows/SKILL.md +41 -0
  138. package/content/skills/get-ticket-id/SKILL.md +67 -0
  139. package/content/skills/groom-backlog/SKILL.md +247 -0
  140. package/content/skills/groom-backlog/groom-backlog.mjs +108 -0
  141. package/content/skills/implement-plan/SKILL.md +168 -0
  142. package/content/skills/index-prototypes/SKILL.md +200 -0
  143. package/content/skills/index-prototypes/index-prototypes.mjs +388 -0
  144. package/content/skills/kb-add/SKILL.md +157 -0
  145. package/content/skills/kb-add/kb-add.mjs +216 -0
  146. package/content/skills/kb-curate/SKILL.md +119 -0
  147. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  148. package/content/skills/kb-edit/SKILL.md +128 -0
  149. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  150. package/content/skills/kb-retrieve/SKILL.md +100 -0
  151. package/content/skills/kb-retrieve/kb-retrieve.mjs +207 -0
  152. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  153. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +207 -0
  154. package/content/skills/kb-update-events/SKILL.md +77 -0
  155. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  156. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  157. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  158. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  159. package/content/skills/merge-pr/SKILL.md +368 -0
  160. package/content/skills/migrate-feedback-memories/SKILL.md +137 -0
  161. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  162. package/content/skills/people-report/SKILL.md +208 -0
  163. package/content/skills/plan/SKILL.md +87 -0
  164. package/content/skills/prepare-prototype-brief/SKILL.md +178 -0
  165. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  166. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +209 -0
  167. package/content/skills/refine-plan/SKILL.md +263 -0
  168. package/content/skills/refine-prototype/SKILL.md +113 -0
  169. package/content/skills/respond-to-review/SKILL.md +292 -0
  170. package/content/skills/review-bb-pr/SKILL.md +161 -0
  171. package/content/skills/review-branch/SKILL.md +303 -0
  172. package/content/skills/review-criteria/SKILL.md +141 -0
  173. package/content/skills/review-gh-pr/SKILL.md +155 -0
  174. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  175. package/content/skills/review-permissions/SKILL.md +39 -0
  176. package/content/skills/review-pr/SKILL.md +123 -0
  177. package/content/skills/revise-comments/SKILL.md +148 -0
  178. package/content/skills/revise-prose/SKILL.md +197 -0
  179. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  180. package/content/skills/save-artifact/SKILL.md +71 -0
  181. package/content/skills/save-plan/SKILL.md +55 -0
  182. package/content/skills/software-engineering/SKILL.md +74 -0
  183. package/content/skills/streamline-guidance/SKILL.md +174 -0
  184. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  185. package/content/skills/summarize-change/SKILL.md +317 -0
  186. package/content/skills/summarize-chat/SKILL.md +100 -0
  187. package/content/skills/systematic-debugging/SKILL.md +308 -0
  188. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  189. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  190. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  191. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  192. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  193. package/content/skills/systematic-debugging/test-academic.md +16 -0
  194. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  195. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  196. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  197. package/content/skills/testing-conventions/SKILL.md +235 -0
  198. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  199. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
  200. package/content/skills/typescript-testing-conventions/SKILL.md +178 -0
  201. package/content/skills/update-jira-ticket/SKILL.md +257 -0
  202. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  203. package/content/skills/update-project-guidance/SKILL.md +300 -0
  204. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  205. package/content/skills/wrap-up/SKILL.md +431 -0
  206. package/content/subagents/_data/claude.yaml +25 -0
  207. package/content/subagents/_data/rovo.yaml +41 -0
  208. package/content/subagents/canary.md +12 -0
  209. package/content/subagents/disposition-challenger.md +78 -0
  210. package/content/subagents/entry-drafter.md +191 -0
  211. package/content/subagents/handoff-reviewer.md +75 -0
  212. package/content/subagents/plan-reviewer.md +184 -0
  213. package/content/subagents/plan-reviser.md +88 -0
  214. package/content/subagents/prose-reviser.md +132 -0
  215. package/content/subagents/ticket-assessor.md +142 -0
  216. package/content/subagents/usability-assessor.md +157 -0
  217. package/package.json +74 -2
  218. package/schemas/preferences.v1.json +321 -0
  219. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,632 @@
1
+ # Title templates
2
+
3
+ Commit titles, ticket titles, PR titles, and squash-merge titles are produced from declarative templates. Each surface has its own template, configured per repository and per user, and rendered by `describe-change.mjs` from a small set of named tokens. One compiled template serves both directions: The same template that renders a title reads a rendered title back into its parts.
4
+
5
+ This file states how a title is rendered and read; [`title-voice.md`](./title-voice.md) states how the `{title}` text fed to these templates is composed.
6
+
7
+ ## Configuring the templates
8
+
9
+ The bundle reads `commit.title_format`, `ticket.title_format`, `pr.title_format`, and `merge.title_format` from `.agents/preferences.yaml` at the repository root, then from `~/.agents/preferences.yaml`, falling back to the empty string. Resolution is per key, so a project file naming `commit.title_format` alone still inherits the other three from the global file, and a key present with an empty value opts that surface out.
10
+
11
+ ```yaml
12
+ commit:
13
+ title_format: '[[{scope}|]{type}: ]{title}'
14
+ ticket:
15
+ title_format: '{title}'
16
+ pr:
17
+ title_format: '[{ticket_ref} ]{title}'
18
+ merge:
19
+ title_format: '[{ticket_ref} ][[{scope}|]{type}: ]{title}[ (#{pr_number})]'
20
+ ```
21
+
22
+ Quote every `title_format` value, single or double quotes alike. Without quotes, YAML reads `{title}` as a flow mapping rather than a token, and a space followed by `#` opens a comment.
23
+
24
+ ## Invoking the bundle
25
+
26
+ `describe-change.mjs` takes a subcommand as its first argument, followed by that subcommand's arguments:
27
+
28
+ ```bash
29
+ node {harness_home_dir}/scripts/describe-change.mjs <subcommand> [flags]
30
+ ```
31
+
32
+ The bundle does not have a shebang, so the `node` prefix is required. Each subcommand accepts only the flags that its section below lists and refuses any other as unknown, including a flag that another subcommand takes. A run with a missing or unknown subcommand exits non-zero with a usage error that lists the subcommands. A run that succeeds writes one JSON object to stdout, and warnings and errors go to stderr.
33
+
34
+ | Subcommand | Reports | Reads |
35
+ | ------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------- |
36
+ | [`render-titles`](#render-titles) | Each surface's title, rendered from one record | The templates, and the taxonomy when it is readable |
37
+ | [`parse-title`](#parse-title) | A rendered title, read back into its record | The templates and the taxonomy |
38
+ | [`consolidate-branch`](#consolidate-branch) | A commit range's entries and their consolidated record | The templates, the taxonomy, and the commits |
39
+ | [`consolidate-entries`](#consolidate-entries) | The record to which a change's entries consolidate | The taxonomy and the entries file |
40
+ | [`resolve-ticket-type`](#resolve-ticket-type) | The work type that a ticket's labels name | The label map |
41
+ | [`resolve-effective-record`](#resolve-effective-record) | A record with its overrides applied, and its defects | The taxonomy |
42
+ | [`render-block`](#render-block) | The `change-record` block that ends a pull-request body | Nothing |
43
+ | [`render-details`](#render-details) | The `## Details` body of a change summary | The taxonomy and the entries file |
44
+ | [`resolve-merge`](#resolve-merge) | What a pull request merges as | The templates, the taxonomy, the label map, and the commits |
45
+ | [`check-merge-body`](#check-merge-body) | The entry count that a composed merge body records | The body file |
46
+ | [`amend-entry`](#amend-entry) | One change entry, amended in a pull-request body | The taxonomy and the body file, which it rewrites |
47
+ | [`resolve-scopes`](#resolve-scopes) | The scope that owns each given path | The workspace layout and the project preferences file |
48
+ | [`resolve-labels`](#resolve-labels) | The labels for a change | The label map, and the body file when given |
49
+
50
+ ### What stops a run and what only warns
51
+
52
+ - A configured template that the engine cannot invert stops every subcommand that reads the templates, naming the surface, the template, and the defect. `resolve-ticket-type`, `resolve-effective-record`, `render-block`, `render-details`, `consolidate-entries`, `check-merge-body`, `amend-entry`, `resolve-scopes`, and `resolve-labels` read none, so a defective template does not stop them. See [What the grammar refuses](#what-the-grammar-refuses).
53
+ - A configured template that renders a subject it cannot read back, for some record shape that has a type, causes a warning on stderr from every subcommand that reads the templates, naming the surface, the template, and the record shape. The run continues and its output is unchanged. See [Optional groups](#optional-groups).
54
+ - Malformed YAML in a preferences file stops every subcommand that reads the templates, naming the file.
55
+ - Malformed YAML in `pnpm-workspace.yaml` or in the project preferences file stops `resolve-scopes`, naming the file.
56
+ - A `project.scopes` entry that `resolve-scopes` cannot honor causes a warning naming the entry's index and fault, and the run skips that entry and resolves the rest. See [`resolve-scopes`](#resolve-scopes).
57
+ - A malformed `change-record` block in the body file causes a warning from `resolve-labels`, which then labels the change from the flags alone.
58
+ - An unreadable taxonomy causes a warning from `render-titles`, which then renders from templates that nothing verified or checked for a lost token, and stops `parse-title`, `consolidate-branch`, `consolidate-entries`, `render-details`, `resolve-effective-record`, `resolve-merge`, and `amend-entry`.
59
+ - Outside a repository, a subcommand that anchors at the repository root warns on stderr and anchors at the working directory instead: the `.agents/` and `.meta/label-map.json` lookups, so the global templates still render, and `resolve-scopes`'s discovery of workspace and declared scope directories.
60
+ - A `title_format` resolving to anything but a string causes a warning on stderr, and the next source supplies the template.
61
+ - A type or scope that a configured label map does not define causes a warning from `resolve-labels`, naming the key and the map. A repository that does not configure a map does not cause any.
62
+ - A `--project-root` that does not name a readable directory stops `render-titles` and `resolve-labels`, naming the path.
63
+
64
+ ## Reading another repository's configuration
65
+
66
+ `render-titles` and `resolve-labels` take `--project-root <dir>`, which names the directory to read in place of the invoking repository's root: its `.agents/preferences.yaml` and its `.meta/label-map.json`. A relative path resolves against the invoking directory. The global preferences file still supplies a template that the directory's file omits. The run skips git's root resolution, so it does not warn outside a repository. Every other subcommand refuses the flag.
67
+
68
+ `create-ticket` uses it to resolve the title and the labels of a ticket filed in another repository, from a directory into which that repository's configuration has been fetched.
69
+
70
+ ## `render-titles`
71
+
72
+ `render-titles` renders every surface's title from one record. Run it with every input that is available; templates control which tokens are required:
73
+
74
+ ```bash
75
+ node {harness_home_dir}/scripts/describe-change.mjs render-titles \
76
+ --title "{title}" \
77
+ --scope "{scope}" \
78
+ --type "{type}" \
79
+ --ticket-ref "{ticket_ref}" \
80
+ --pr-number "{pr_number}"
81
+ ```
82
+
83
+ Its flags are `--title`, `--scope`, `--type`, `--breaking`, `--ticket-ref`, `--pr-number`, and [`--project-root`](#reading-another-repositorys-configuration), and all are optional. Each missing flag means the corresponding token resolves to the empty string. Always quote `--title` so that titles with spaces or shell-special characters are passed intact. Add `--breaking` for a breaking change; `--type feat!` is also accepted and splits into the bare type and the marker. A `--scope` of `*` normalizes to an empty scope, so the sentinel never appears in a rendered title.
84
+
85
+ Output is JSON:
86
+
87
+ ```json
88
+ {
89
+ "commit_title": "agents|feat: Add script installer",
90
+ "ticket_title": "Add script installer",
91
+ "pr_title": "#466 Add script installer",
92
+ "merge_title": "#466 agents|feat: Add script installer (#470)"
93
+ }
94
+ ```
95
+
96
+ Use `commit_title` for commit titles, `ticket_title` for issue titles, `pr_title` for pull-request titles, and `merge_title` for the squash-merge title shown in the merge UI. Each value is the fully rendered title; do not concatenate it with the bare `title`.
97
+
98
+ If the bundle is not found, fall back to the bare `--title` value.
99
+
100
+ ## `parse-title`
101
+
102
+ `parse-title` inverts one surface's template, so a rendered subject reads back into the record that produced it. It takes the surface (`commit`, `ticket`, `pr`, or `merge`) and then the subject as positional arguments, and it does not take any flags:
103
+
104
+ ```bash
105
+ node {harness_home_dir}/scripts/describe-change.mjs parse-title commit "agents|feat: Add foo"
106
+ ```
107
+
108
+ The output names every field, with `null` for any field that the record lacks:
109
+
110
+ ```json
111
+ {
112
+ "breaking": false,
113
+ "matched": true,
114
+ "pr_number": null,
115
+ "scope": "agents",
116
+ "ticket_ref": null,
117
+ "title": "Add foo",
118
+ "type": "feat"
119
+ }
120
+ ```
121
+
122
+ For a subject not matched by the template, the run reports `{"matched":false}` and exits 0. A hand-written subject is an ordinary result rather than an error, so a caller reads `matched` rather than the exit status.
123
+
124
+ **A type is required.** A template naming `{type}` reads a subject that does not contain a declared type as unmatched, whatever else the subject contains. Under `[[{scope}|]{type}: ]{title}`, both `agents|Add foo` and `Support a|b: syntax` are unmatched, the second because `b` is not a declared type.
125
+
126
+ **Under a template that does not name `{ticket_ref}`, the bundle strips one first.** The bundle removes three leading forms before the match: `## `, `#123 ` (with an optional `.1` or `-1` suffix), and `ABC-123 `. These are the forms that release-kit strips, which lets a commit template that does not name `{ticket_ref}` read a subject that contains one.
127
+
128
+ **When a parse could read a group as present or absent, present wins.** This is release-kit's reading, and it makes `agents|feat: Add foo` parse as scoped and typed rather than as a bare title. See [What the grammar does not support](#what-the-grammar-does-not-support) for the cost.
129
+
130
+ The run refuses a surface whose template is empty, since there is nothing to read the subject through, and refuses if the taxonomy cannot be read.
131
+
132
+ ## `consolidate-branch`
133
+
134
+ `consolidate-branch` reads a range of commits through `commit.title_format` and reports the branch's entries and their [consolidated record](./change-record.md#terms). Its one flag, `--base`, is required and names the base ref; the range is `{base-ref}..HEAD`.
135
+
136
+ ```bash
137
+ node {harness_home_dir}/scripts/describe-change.mjs consolidate-branch --base origin/main
138
+ ```
139
+
140
+ ```json
141
+ {
142
+ "entries": [
143
+ {
144
+ "breaking": false,
145
+ "change": "agents|feat: Add the parser",
146
+ "commit": "63d2173",
147
+ "scope": "agents",
148
+ "title": "Add the parser",
149
+ "type": "feat"
150
+ },
151
+ {
152
+ "breaking": true,
153
+ "change": "agents|refactor!: Restructure the guard",
154
+ "commit": "8d2227d",
155
+ "scope": "agents",
156
+ "title": "Restructure the guard",
157
+ "type": "refactor"
158
+ }
159
+ ],
160
+ "consolidated_record": { "breaking": true, "scope": "agents", "type": "refactor" },
161
+ "unmatched": [{ "commit": "b5ce73f", "subject": "wip" }],
162
+ "violations": [{ "commit": "8d2227d", "policy": "forbidden", "type": "refactor" }]
163
+ }
164
+ ```
165
+
166
+ **`entries` runs oldest first**, in the order the branch was built, and a commit's own trailers keep the order in which they were written. One order therefore holds across the whole list, whether an entry came from a subject or from a trailer.
167
+
168
+ **Each entry's `change` is the entry rendered back through `commit.title_format`.** It is the form that a `Change:` trailer and the change summary's `changes` field take verbatim, and it reads back to the same entry. A ticket reference stripped from the subject does not reappear in it.
169
+
170
+ **A merge commit does not contribute an entry.** Its subject does not match any template, and its author cannot rewrite it, so reporting it as unmatched would train a reader to skim a list that exists to be read. The commits brought in by a merge stay in the range on their own.
171
+
172
+ **A commit with `Change:` trailers contributes those entries and not its subject.** Because a condensed commit's subject renders the record to which its trailers already consolidate, reading both would count the branch's entries twice. See [The `Change:` trailer](./change-record.md#the-change-trailer).
173
+
174
+ **Consolidation ranks the entries; it does not count them.** One `feat` outranks three `fix` commits on the same branch, breaking outranks non-breaking, and the tier and listing order in [`work-types.json`](./work-types.json) settle the rest. Every field of `consolidated_record` is `null` when the run did not find any entry, which is how a caller distinguishes a branch without entries from one whose consolidated record does not name a scope. The consolidated record does not name a title: A caller takes that from the change summary.
175
+
176
+ **A subject that does not match any template is listed in `unmatched` rather than dropped**, so a mistyped prefix stays visible instead of silently shrinking the set that the consolidated record is derived from.
177
+
178
+ **A violation is reported and the run continues.** A `refactor!` disagrees with the type's `breakingPolicy`. Because the commit is already written, refusing here would block the work until a rebase; the entry is reported as written and never normalized.
179
+
180
+ The run refuses outright if the taxonomy cannot be read, since the entries have nothing to rank against, and if `commit.title_format` is empty, since an empty template does not match any subject.
181
+
182
+ ## `consolidate-entries`
183
+
184
+ `consolidate-entries` reports the record to which a change's [change entries](./change-record.md#terms) consolidate. Its one flag, `--entries-file`, is required and names a YAML file containing a top-level list of entry mappings, in the shape that `entry-drafter` returns.
185
+
186
+ ```bash
187
+ node {harness_home_dir}/scripts/describe-change.mjs consolidate-entries --entries-file entries-20260920-223418Z.yaml
188
+ ```
189
+
190
+ ```yaml
191
+ - type: feat
192
+ scopes: [agents, kb]
193
+ breaking: false
194
+ text: "Adds the store-qualified wikilink `[[store:Note title]]`, which `kb check` resolves against the named store."
195
+ - type: fix
196
+ scopes: [agents]
197
+ breaking: false
198
+ text: "Stops the sync from deleting a subagent that the run had just written."
199
+ ```
200
+
201
+ ```json
202
+ { "consolidated_record": { "breaking": false, "scope": "agents", "type": "feat" } }
203
+ ```
204
+
205
+ **Each entry expands to one record per scope**, and an entry that does not name a scope expands to one record without a scope, so that a change that does not touch any scope can still be ranked by its type. The expanded list is then ranked exactly as `consolidate-branch` ranks the commit entries, so one rule serves both sources: breaking outranks non-breaking, then the tier and listing order in [`work-types.json`](./work-types.json), and exactly one distinct scope survives.
206
+
207
+ **An entry whose `type` the taxonomy does not declare is left as written and is unrankable**, so it does not contribute a type, as an unrankable commit entry does. Every field of `consolidated_record` is `null` for an empty list, which is how a caller distinguishes a change without entries from one whose consolidated record does not name a scope.
208
+
209
+ **The run reads the entries from a file rather than from flags** because `text` is arbitrary prose containing backticks and quotes, which a shell argument would expand or truncate.
210
+
211
+ The run refuses an entries file that cannot be read, that is not valid YAML, or that is malformed, naming the defect: a value that is not a list, an item that is not a mapping, a missing or blank `type` or `text`, a `breaking` that is not a boolean, a `scopes` that is not a list of strings, and a `migration` that is not a string or spans more than one line, and a `text` or `migration` cut short by a YAML comment, which a space followed by `#` opens in an unquoted value; the error names the entry, the field, and the dropped text. A blank or null `migration` reads as absent, and a key that the grammar does not declare is ignored. It also refuses outright if the taxonomy cannot be read, since the entries have nothing to rank against.
212
+
213
+ ## `resolve-ticket-type`
214
+
215
+ `resolve-ticket-type` reports the work type that a ticket's labels name. `--ticket-label` is its one flag, repeatable and optional, and takes the linked ticket's labels. The bundle reverse-looks-up the repository's `.meta/label-map.json` to report which work type they name, so it fetches nothing itself.
216
+
217
+ ```bash
218
+ node {harness_home_dir}/scripts/describe-change.mjs resolve-ticket-type \
219
+ --ticket-label feature --ticket-label scope:agents
220
+ ```
221
+
222
+ ```json
223
+ { "ticket_type": "feat" }
224
+ ```
225
+
226
+ **`ticket_type` is `null` when the labels do not name a type and when they name more than one.** Two type labels on one ticket say that nobody has decided which it is. Because a repository whose label map is absent or unparseable does not name a type, its `ticket_type` is `null` as well.
227
+
228
+ ## `resolve-effective-record`
229
+
230
+ `resolve-effective-record` applies a change summary's overrides to its consolidated record and reports the [effective record](./change-record.md#the-effective-record) with its defects. The record comes from `--title`, `--scope`, `--type`, and `--breaking`, and the author's overrides from `--override-scope`, `--override-type`, and `--override-breaking`. Every flag is optional.
231
+
232
+ ```bash
233
+ node {harness_home_dir}/scripts/describe-change.mjs resolve-effective-record \
234
+ --scope agents --type feat --title "Add the parser" \
235
+ --override-type sec --override-breaking
236
+ ```
237
+
238
+ ```json
239
+ {
240
+ "effective_record": {
241
+ "title": "Add the parser",
242
+ "scope": "agents",
243
+ "type": "sec",
244
+ "breaking": true,
245
+ "ticket_ref": null,
246
+ "pr_number": null
247
+ },
248
+ "defects": []
249
+ }
250
+ ```
251
+
252
+ **`effective_record` contains every field of a record.** `ticket_ref` and `pr_number` are always `null`, since only a merge supplies them. Any other field that neither the record nor an override sets is `null`, apart from `breaking`, which is then `false`.
253
+
254
+ **`defects` lists what would block approval of the effective record**:
255
+
256
+ | Kind | Meaning |
257
+ | ------------------ | ---------------------------------------------------------------------------------------- |
258
+ | `missing-type` | The effective record does not name a type. |
259
+ | `undeclared-type` | `work-types.json` does not declare the effective type; `type` names it. |
260
+ | `policy-violation` | The breaking marker disagrees with the type's `breakingPolicy`; `policy` names the rule. |
261
+
262
+ `--type feat!` is accepted and splits into the bare type and the marker. `--override-type` takes a bare type and refuses one spelled with `!`; pass `--override-breaking` for a breaking override. An override flag whose value is blank does not set an override. The run does not read a title template or the repository, so a defective template does not stop it, and it refuses if the taxonomy cannot be read.
263
+
264
+ ## `render-block`
265
+
266
+ `render-block` renders the fenced `change-record` block that ends a pull-request body. `--title` is required. The author's overrides come from `--override-scope`, `--override-type`, and `--override-breaking`. The change entries come from `--entries-file`, naming the same YAML file that [`consolidate-entries`](#consolidate-entries) takes, and `--entries-commit` names the commit at which they were derived. Each of these is optional.
267
+
268
+ ```bash
269
+ node {harness_home_dir}/scripts/describe-change.mjs render-block \
270
+ --title "Add the parser" \
271
+ --override-type sec --override-breaking \
272
+ --entries-file entries-20260920-223418Z.yaml --entries-commit e5029924
273
+ ```
274
+
275
+ The output is JSON whose `block` contains the fenced block, fences included:
276
+
277
+ ````json
278
+ {
279
+ "block": "```change-record\ntitle: Add the parser\noverrides:\n type: sec\n breaking: true\nentries_commit: e5029924\nentries:\n - type: feat\n scopes: [agents]\n text: Adds the parser\n```"
280
+ }
281
+ ````
282
+
283
+ **The run does not read the taxonomy.** The block records the entries rather than a record ranked from them; [`resolve-merge`](#resolve-merge) ranks them at merge.
284
+
285
+ The run refuses a missing or blank `--title`, and a blank `--entries-file` or `--entries-commit`. It refuses `--entries-commit` without `--entries-file`, since a derivation commit with nothing derived at it records a claim about nothing, and it refuses an entries file that cannot be read, that is not valid YAML, or that is malformed, exactly as `consolidate-entries` does. `--override-type` takes a bare type and refuses one spelled with `!`; pass `--override-breaking` for a breaking override. [The `change-record` block](./change-record.md#the-change-record-block) states the block's grammar, and [The effective record](./change-record.md#the-effective-record) states how a reader applies the overrides.
286
+
287
+ ## `render-details`
288
+
289
+ `render-details` renders the body of a change summary's `## Details` section from the change entries. Its one flag, `--entries-file`, is required and names the same YAML file that [`consolidate-entries`](#consolidate-entries) takes.
290
+
291
+ ```bash
292
+ node {harness_home_dir}/scripts/describe-change.mjs render-details --entries-file entries-20260920-223418Z.yaml
293
+ ```
294
+
295
+ ```yaml
296
+ - type: fix
297
+ scopes: [kb]
298
+ breaking: true
299
+ text: "Stops `kb check` resolving a bare wikilink against every store."
300
+ migration: "Qualify each wikilink that names a note outside its own store as `[[store:Note title]]`."
301
+ - type: feat
302
+ scopes: [agents, kb]
303
+ breaking: false
304
+ text: "Adds the store-qualified wikilink `[[store:Note title]]`."
305
+ ```
306
+
307
+ The output is JSON whose `details` contains the body, without the `## Details` heading. Decoded, it reads:
308
+
309
+ ```markdown
310
+ ### 🎉 Features
311
+
312
+ - Adds the store-qualified wikilink `[[store:Note title]]`. #agents, #kb
313
+
314
+ ### 🐛 Bug fixes
315
+
316
+ - 🚨 **Breaking:** Stops `kb check` resolving a bare wikilink against every store. #kb
317
+ - Migration: Qualify each wikilink that names a note outside its own store as `[[store:Note title]]`.
318
+ ```
319
+
320
+ - **Subsections.** One `###` subsection per distinct type among the entries, headed `{emoji} {label}` from that type's entry in [`work-types.json`](./work-types.json). An entry typed by an alias falls under its canonical type. The subsections are ordered by tier, then in the order that the taxonomy lists the types, and a type without an entry does not get one.
321
+ - **Bullets.** One bullet per entry, in the order of the file. A breaking entry's bullet opens with the prefix rendered from `markers.breaking` as `{emoji} **{label}:** `, followed by the entry's `text`.
322
+ - **Migration.** An entry's `migration` is nested under its bullet as `Migration: {migration}`, indented 4 spaces, which Bitbucket Cloud requires to read it as a child rather than a sibling. The scope tags stay on the bullet's own line.
323
+ - **Scope tags.** When the entries do not all name the same set of scopes, each bullet ends with one space and its scopes as bare `#scope` tags, comma-separated and each named once. An entry without scopes does not end with a tag. When every entry names the same set, whatever its order, the bullets do not end with tags, since the consolidated record already names that scope.
324
+ - **Empty list.** An empty list yields an empty `details`, and the caller omits the section.
325
+
326
+ The run refuses an entry whose `type` the taxonomy does not declare as a key or an alias, `feat!` included, since `breaking` records the marker; and an entry whose `text` spans more than one line, which would break its bullet. It refuses an entries file exactly as `consolidate-entries` does, and refuses outright if the taxonomy cannot be read or does not declare an `emoji` and a `label` for `markers.breaking` and every type.
327
+
328
+ ## `resolve-merge`
329
+
330
+ `resolve-merge` reports what a pull request merges as. `--base` names the base ref of the pull request's range, the pull request supplies the rest, and the author's choices at the approval gate are passed as overrides.
331
+
332
+ ```bash
333
+ node {harness_home_dir}/scripts/describe-change.mjs resolve-merge \
334
+ --base origin/main \
335
+ --head 63d2173e5f0c9a7b1d4e8f2a6c0b3d5e7f9a1c2b \
336
+ --pr-number 470 \
337
+ --pr-title "#466 Add the parser" \
338
+ --pr-body-file {body_file} \
339
+ --pr-label feature --pr-label scope:agents \
340
+ --ticket-ref "#466"
341
+ ```
342
+
343
+ `--base`, `--head`, `--pr-number`, `--pr-title`, and `--pr-body-file` are required. `--head` is the pull request's head commit. The commits are read from the local repository, so the head commit must be there for them to be read, and it need not be checked out. `--pr-number` takes digits alone. `--pr-body-file` names a file containing the pull-request body, which is multi-line Markdown. `--pr-label` is repeatable. `--ticket-ref` is the ticket reference to be used when the pull-request title does not contain one. The overrides are `--override-scope`, `--override-type`, `--override-breaking` or `--no-override-breaking`, and `--override-title`.
344
+
345
+ ````json
346
+ {
347
+ "effective_record": {
348
+ "title": "Add the parser",
349
+ "scope": "agents",
350
+ "type": "feat",
351
+ "breaking": false,
352
+ "ticket_ref": "#466",
353
+ "pr_number": "470"
354
+ },
355
+ "effective_sources": {
356
+ "title": "pr_title",
357
+ "scope": "block",
358
+ "type": "block",
359
+ "breaking": "block",
360
+ "ticket_ref": "pr_title"
361
+ },
362
+ "merge_title": "#466 agents|feat: Add the parser (#470)",
363
+ "body": "- Adds the parser.",
364
+ "merge_block": "```change-record\npr_number: 470\nticket_ref: \"#466\"\nentries:\n - type: feat\n scopes: [agents]\n text: Adds the parser\n```",
365
+ "entry_count": 1,
366
+ "sources": {
367
+ "block": {
368
+ "title": "Add the parser",
369
+ "overrides": {},
370
+ "entries_commit": "e5029924",
371
+ "entries": [{ "type": "feat", "scopes": ["agents"], "breaking": false, "text": "Adds the parser" }]
372
+ },
373
+ "commits": { "scope": "agents", "type": "fix", "breaking": false },
374
+ "labels": { "scope": "agents", "type": "feat", "breaking": false },
375
+ "pr_title": { "title": "Add the parser", "ticket_ref": "#466", "scope": null, "type": null, "breaking": null }
376
+ },
377
+ "defects": [],
378
+ "notices": []
379
+ }
380
+ ````
381
+
382
+ **`effective_record` is the [effective record](./change-record.md#terms) that the merge settles on**, resolved as [Where the record is read](./change-record.md#where-the-record-is-read) states. It contains every field of a record, since `merge_title` renders from it. A field that nothing sets is `null`, apart from `breaking`, which is then `false`.
383
+
384
+ **`effective_sources` names what supplied each field of `effective_record`**, apart from `pr_number`, which `--pr-number` supplies:
385
+
386
+ | Value | Supplied by |
387
+ | ------------------- | ------------------------------------------------------------------------------------------------ |
388
+ | `block` | The record ranked from the block's entries, or the block's title, when the title does not invert |
389
+ | `block_overrides` | An override that the block records |
390
+ | `commits` | The record to which the commits consolidate |
391
+ | `flags` | The invocation's overrides, and `--ticket-ref` |
392
+ | `labels` | The pull request's labels |
393
+ | `pr_title` | The pull-request title, inverted through `pr.title_format` |
394
+ | `pr_title_verbatim` | The pull-request title as given, when it does not invert and a readable block is absent |
395
+
396
+ Each field names the step that set it last, as [Where the record is read](./change-record.md#where-the-record-is-read) orders the steps, so a field that an override sets names the override even when it repeats the value that it replaces. A field is `null` when nothing supplied it: a `ticket_ref` that neither the title nor `--ticket-ref` names, and, without entries to rank, a field that the labels do not resolve while the commits cannot be read.
397
+
398
+ **`sources` reports what each source names**, whether or not the resolution used it. A source is `null` only when it was not read: `block` when the body does not contain a block or contains a malformed one, `commits` when the commits cannot be read, and `pr_title` when the title does not invert. Within a record, a field that the source does not determine is `null`, `breaking` included.
399
+
400
+ - `block` mirrors the block as read: its `title`, its `overrides`, which lists only the keys that are set, its `entries`, each with `type`, `scopes`, `breaking`, `text`, and any `migration`, and its `entries_commit`. `entries` is empty when the block records none and when they were malformed; `entries_commit` is `null` when the block records none.
401
+ - `commits` is the record to which the commits between `--base` and `--head` consolidate. Every field is `null` when the range does not contain any entry.
402
+ - `labels` is the record that the labels name, and is never `null`. `type` and `scope` each resolve when exactly one label of their section names a key. `breaking` is `true` with the `breaking` label, `false` when a type label resolves without it, and `null` otherwise.
403
+ - `pr_title` is the record that the pull-request title contains: the bare `title` and the `ticket_ref`, and the `scope`, `type`, and `breaking` of any typed prefix, each `null` when the title does not contain a prefix. It is read under `--override-title` too.
404
+
405
+ **The bare title** comes from `--override-title`, then from the pull-request title inverted through `pr.title_format`, then from the block's title, then from the pull-request title as given. A scope and type read from the pull-request title, through `pr.title_format` when it names `{type}` and otherwise through `commit.title_format`, never stay in the bare title. `ticket_ref` comes from the pull-request title, then from `--ticket-ref`. `merge_title` is `effective_record` rendered through `merge.title_format`, the marker included, or the bare title when that template is empty.
406
+
407
+ **`body` is the merge body**: the `## What` section, without any `change-record` block and without the trailing lines that contain only a closing keyword (`close`, `fix`, `resolve`, and their inflections) and ticket references.
408
+
409
+ **`merge_block` is the block's change entries in the [merge-commit form](./change-record.md#the-merge-commit-form)**, fences included, with `pr_number` from `--pr-number` as an integer and `ticket_ref` from `effective_record`, left out when that is `null`. The entries keep the order in which the block records them. **`entry_count`** is the number of entries that `merge_block` records.
410
+
411
+ The entries render whether or not they are fresh: a merge re-derives nothing, and a `stale-entries` notice reports staleness instead. `merge_block` is `null`, and `entry_count` is `0`, when the block is absent, malformed, or does not record any entry. `merge_block` is separate from `body`, so a consumer that replaces a thin body keeps it.
412
+
413
+ **`defects` block approval.** Each names a condition that the author must settle before the merge is offered, with the kinds that [`resolve-effective-record`](#resolve-effective-record) lists. The block's change entries are checked first, fresh or stale, since the merge block publishes them either way: Each entry whose type `work-types.json` does not declare, or whose marker breaks its type's `breakingPolicy`, yields an `undeclared-type` or `policy-violation` whose `entry` names the entry's 0-based index, in entry order. The effective record's defect follows, without `entry`. An entry defect is settled by [`amend-entry`](#amend-entry), since an override changes only the effective record; the record's defect is settled by an override.
414
+
415
+ ```json
416
+ [
417
+ { "entry": 1, "kind": "undeclared-type", "type": "feature" },
418
+ { "kind": "missing-type" }
419
+ ]
420
+ ```
421
+
422
+ **The block's entries decide the record.** `resolve-merge` ranks them into a scope, type, and marker by the rule that [`consolidate-entries`](#consolidate-entries) applies, and that record stands whether or not the entries are fresh. The entries are fresh when the block records some, records the commit at which they were derived, and the head that `--head` names starts with that commit, compared case-insensitively: The block records a short SHA and the pull request reports a full one. Stale entries raise `stale-entries`. A block that does not record any entries, or whose entries are malformed, resolves its base record from the labels and the commits as a body without a block does, and its overrides still apply.
423
+
424
+ **`notices` inform the gate** and block nothing:
425
+
426
+ | Kind | Meaning |
427
+ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
428
+ | `absent-block` | The body does not contain a block, so the merge does not publish any change entries. `effective_sources` names what supplied each field in the block's place. The `add-change-record` skill adds a block to a body that has none. |
429
+ | `malformed-block` | The body's last block cannot be read; `defect` names why, and the merge resolves as though the body did not contain a block. |
430
+ | `commits-unavailable` | The commits cannot be read; `reason` names why, and without entries to rank, the record resolves from the labels alone. |
431
+ | `pr-title-divergence` | The pull-request title's typed prefix differs from `effective_record`; `fields` lists the fields on which they differ. It is raised under `--override-title` too. |
432
+ | `pr-title-unparsed` | The pull-request title does not invert through `pr.title_format`; `effective_sources.title` names what stands in. |
433
+ | `malformed-entries` | The block's `entries` list cannot be read; `defect` names why. The entries are reported as absent, the base record resolves from the labels and the commits, and the block's title and overrides stay in use. |
434
+ | `stale-entries` | The block records entries that were not derived at the pull request's head. `entries_commit` names the commit at which they were derived, `null` when the block records none, and `head_commit` names the head against which it was compared. |
435
+
436
+ **Each override outranks every source on its own field**, as [The effective record](./change-record.md#the-effective-record) states; `--no-override-breaking` removes the marker. `--override-title` replaces the bare title, and the pull-request title's prefix is still read and compared.
437
+
438
+ **A head commit that the local repository lacks is not an error.** The run reports `commits-unavailable` and resolves from the block or the labels alone, so fetch the head commit before resolving. Any other git failure stops the run.
439
+
440
+ The run refuses if the taxonomy cannot be read and if the body file cannot be read. With an empty `commit.title_format`, the run reports `commits-unavailable` rather than refusing. `--override-type` refuses a type spelled with `!`, and the run refuses `--override-breaking` together with `--no-override-breaking`.
441
+
442
+ ## `check-merge-body`
443
+
444
+ `check-merge-body` reads a composed merge body back as release-kit reads the merge commit, and refuses a body that would not yield the expected entries.
445
+
446
+ ```bash
447
+ node {harness_home_dir}/scripts/describe-change.mjs check-merge-body \
448
+ --body-file {body_file} \
449
+ --entry-count 2
450
+ ```
451
+
452
+ Both flags are required. `--body-file` names a file containing the whole merge body, and `--entry-count` takes the `entry_count` that [`resolve-merge`](#resolve-merge) reported, as a non-negative integer.
453
+
454
+ ```json
455
+ { "entry_count": 2 }
456
+ ```
457
+
458
+ The body's last `change-record` block is read under the rules of the [merge-commit form](./change-record.md#the-merge-commit-form): Any defect makes the whole block malformed. The run exits non-zero, naming the defect or both counts, when the file cannot be read, when the block is malformed, and when the number of entries that it records differs from `--entry-count`. A body that does not contain a block does not record any entries, so it passes only with `--entry-count 0`, and a body containing a block fails with `--entry-count 0`.
459
+
460
+ ## `amend-entry`
461
+
462
+ `amend-entry` rewrites one change entry in the last `change-record` block of a pull-request body file, and writes the body back to the same file.
463
+
464
+ ```bash
465
+ node {harness_home_dir}/scripts/describe-change.mjs amend-entry \
466
+ --body-file {body_file} \
467
+ --entry 1 \
468
+ --type feat \
469
+ --no-breaking
470
+ ```
471
+
472
+ `--body-file` and `--entry` are required. `--entry` takes the entry's 0-based index, as a defect's `entry` names it. `--type` sets the entry's type, and `--breaking` or `--no-breaking` sets its marker; at least one of the three is required, and a field that the invocation leaves out keeps the entry's value.
473
+
474
+ ```json
475
+ {
476
+ "entry": { "breaking": false, "scopes": ["agents"], "text": "Adds the parser", "type": "feat" },
477
+ "entry_count": 2
478
+ }
479
+ ```
480
+
481
+ The run re-renders the whole block as [`render-block`](#render-block) renders one, keeping its `title`, `overrides`, and `entries_commit` and dropping any key that the grammar does not declare. The block's formatting is normalized, so the body's diff shows the whole block changing. Text outside the block is unchanged byte for byte, and the block takes the line ending of the body around it.
482
+
483
+ The run exits non-zero, naming the cause and leaving the file untouched, when the body does not contain a block or contains a malformed one, when the block's entries are malformed, when `--entry` is out of range, when `--type` is spelled with `!` (pass `--breaking`), when the taxonomy does not declare the amended type, and when the amended marker breaks the type's `breakingPolicy`. An amendment that succeeds therefore clears the entry's defect. It also refuses `--breaking` together with `--no-breaking`, a file that cannot be read or written, and a taxonomy that cannot be read.
484
+
485
+ ## `resolve-scopes`
486
+
487
+ `resolve-scopes` reports the scope that owns each given path, so a consumer can attribute a set of changed files to the scopes that own them. `--path` is its one flag, repeatable and optional.
488
+
489
+ ```bash
490
+ node {harness_home_dir}/scripts/describe-change.mjs resolve-scopes \
491
+ --path packages/kb/src/index.ts --path AGENTS.md
492
+ ```
493
+
494
+ ```json
495
+ { "path_scopes": { "packages/kb/src/index.ts": "kb", "AGENTS.md": "root" }, "scopes": ["kb", "root"] }
496
+ ```
497
+
498
+ **`path_scopes` maps each path as given to its scope**, under the spelling that the invocation passed, so a caller can look a result up by the path that it asked about. **`scopes` is the sorted set** of the scopes that those paths name between them.
499
+
500
+ **The derivation**: `@williamthorsen/nmr/workspace` resolves the repository root's workspace directories, honoring the `packages` patterns that `pnpm-workspace.yaml` declares, negative patterns included; each is named by its basename. The repository adds scope directories of its own under `project.scopes` in its `.agents/preferences.yaml`, each named by its `name` or else by its basename. A path's scope is the name of the longest of those directories that contains it, so a nested directory wins over the one enclosing it, whether either is a package or a declared directory. A path outside every scope directory resolves to `root`.
501
+
502
+ ```yaml
503
+ project:
504
+ scopes:
505
+ - path: apps/devopticon
506
+ - path: tools/ios-shell
507
+ name: ios
508
+ ```
509
+
510
+ **A declared directory owns a scope without becoming a workspace**, so a deliverable that is not a Node package, such as a SwiftPM app, can own one without a placeholder manifest that nmr and release-kit would then act on. A declared directory that is also a package directory takes its declared name. Only the project preferences file declares scopes; `project.scopes` in the global file does not have any effect. An entry that is not a mapping, that does not have a string `path`, that has a `name` that is not a non-empty string, or whose path is absolute, outside the repository, missing, or not a directory is skipped with a warning, and a `project.scopes` that is not a list is ignored with one.
511
+
512
+ **A repository without scope directories yields `root` for every path.** A root that is not a pnpm workspace and does not declare scopes discovers none, as does one whose patterns do not match any directory, and this is how a consumer detects that the repository does not have a scope vocabulary. A repository on another package manager reads the same way unless it declares scopes.
513
+
514
+ **A path is read relative to the repository root**, which git resolves from the invoking directory, so an absolute path and a root-relative one resolve alike whatever subdirectory the caller ran from. A path outside the root resolves to `root`. When git does not resolve a repository root, the run warns and anchors at the invoking directory.
515
+
516
+ **The subcommand does not define a workspace rule of its own.** It delegates workspace discovery to `@williamthorsen/nmr/workspace`, whose resolver reads the same `pnpm-workspace.yaml` patterns that release-kit reads to name the workspaces it builds changelogs under. The resolver is bundled into the deployed script, which therefore needs nothing installed in the repository that it runs in. `scope-labels.unit.test.ts` in `packages/guidance` checks the derived vocabulary against the `scope:` labels that `.config/release-kit.config.ts` declares. A change to the workspace discovery rule belongs upstream, in nmr.
517
+
518
+ ## `resolve-labels`
519
+
520
+ `resolve-labels` reports the labels for a change, from the effective record that the flags pass and, when `--body-file` names a body, from the entries in its last `change-record` block. Every flag is optional, [`--project-root`](#reading-another-repositorys-configuration) included. Without `--body-file`, as for a ticket that does not have a body yet, the run labels the record alone.
521
+
522
+ ```bash
523
+ node {harness_home_dir}/scripts/describe-change.mjs resolve-labels \
524
+ --body-file {change_summary_path} \
525
+ --scope agents --type feat
526
+ ```
527
+
528
+ ```json
529
+ { "labels": ["feature", "fix", "breaking", "scope:agents", "scope:kb"] }
530
+ ```
531
+
532
+ **`labels` is the union of what the record and the entries name**, each mapped through the repository's `.meta/label-map.json`: the type label of every type, `breaking` when the record or any entry is breaking, and the scope label of every scope. Type labels come first, then `breaking`, then scope labels. Within each group the record's label leads, followed by the entries' labels in the order in which the entries name them, and each label appears once.
533
+
534
+ **A key that the map does not name, and a scope of `*`, do not add a label.** The run warns on stderr for each such key except `*`, naming it and the map. The run does not read the taxonomy, so an undeclared type is labeled only when the map names it. A label map that is absent, unparseable, or empty does not yield any labels at all, `breaking` included, and does not cause any warning.
535
+
536
+ **The body file may be the change summary itself**, since only its last `change-record` block is read and the frontmatter is ignored. A body that does not contain a block, or a block without entries, is labeled from the flags alone. The run warns and does the same for a malformed block or entry list, and it refuses a body file that cannot be read. `--type feat!` is accepted and splits into the bare type and the marker.
537
+
538
+ ## Supported tokens
539
+
540
+ | Token | Resolves to |
541
+ | -------------- | ------------------------------------------------------------------------------------------------------------------- |
542
+ | `{scope}` | Change scope (workspace, package, module), one name or several joined by commas. `*` normalizes to empty. |
543
+ | `{type}` | Work type (`feat`, `fix`, `docs`, …). Renders as `feat!` when the template lacks `{breaking}` to render the marker. |
544
+ | `{breaking}` | The breaking marker `!`; empty for a change that is not breaking. |
545
+ | `{title}` | Bare title text. Required in every template that should produce a non-empty title. |
546
+ | `{ticket_ref}` | Rendered ticket reference (`#466`, `MAC-147`, …); empty for a change without a ticket. |
547
+ | `{pr_number}` | PR number; empty when not yet known. Only meaningful in `merge.title_format`. |
548
+
549
+ A template that omits `{title}` produces a title without the bare title text: The renderer does not insert it implicitly. Any other `{...}` run is literal text, so a typo such as `{titel}` shows up in the rendered output rather than vanishing.
550
+
551
+ ## Optional groups
552
+
553
+ A `[...]` group renders verbatim when every token directly inside it resolves non-empty. When one is empty, the whole group drops, literals included.
554
+
555
+ A group containing both `{scope}` and `{type}` therefore drops the type along with an absent scope, and a `*` scope is absent by the time the renderer decides whether to keep the group. When preferences load, the bundle warns of such a template, naming the record shape that loses the type; it warns in the same way of a group that drops `{breaking}`. When the type should stay in the title of a change without a scope, nest the scope in a group of its own, as the piped-scope convention does.
556
+
557
+ `{breaking}` never decides a group. A non-breaking change would otherwise drop the very prefix that contains the marker.
558
+
559
+ Groups nest, and a nested group is kept or dropped on its own. Under `[[{scope}|]{type}: ]{title}`, a change that does not name a scope keeps its type prefix and renders `feat: Add foo`, while a change naming neither scope nor type renders the bare title.
560
+
561
+ Write `\[` and `\]` for a literal bracket, and `\\` for a literal backslash.
562
+
563
+ **The renderer does not run a whitespace pass.** Output is exactly what the template describes, so each group contains its own separators: Write `[{ticket_ref} ]{title}`, not `[{ticket_ref}] {title}`. That exactness lets `parse-title` invert what the renderer produced.
564
+
565
+ ## The catalogue
566
+
567
+ Four conventions, each of which round-trips.
568
+
569
+ | Convention | Template |
570
+ | -------------------- | ----------------------------------------- |
571
+ | Bracketed scope | `[\[{scope}\] ]{type}{breaking}: {title}` |
572
+ | Conventional commits | `{type}[({scope})]{breaking}: {title}` |
573
+ | Piped scope | `[[{scope}\|]{type}: ]{title}` |
574
+ | Type only | `{type}{breaking}: {title}` |
575
+
576
+ Piped scope places the marker on the type, since it does not name `{breaking}`; the other three place the marker immediately before the colon. Piped scope also nests its scope group inside its type group, so a change that does not name a scope keeps its type prefix.
577
+
578
+ How they render across the cases that separate them:
579
+
580
+ | Record | Bracketed scope | Conventional commits | Piped scope | Type only |
581
+ | ------------------------------------- | --------------------------------------- | -------------------------------------- | -------------------------------------- | ------------------------------ |
582
+ | scope `agents`, type `feat` | `[agents] feat: Add foo` | `feat(agents): Add foo` | `agents\|feat: Add foo` | `feat: Add foo` |
583
+ | type `feat`, no scope | `feat: Add foo` | `feat: Add foo` | `feat: Add foo` | `feat: Add foo` |
584
+ | scope `agents`, type `drop`, breaking | `[agents] drop!: Remove the legacy API` | `drop(agents)!: Remove the legacy API` | `agents\|drop!: Remove the legacy API` | `drop!: Remove the legacy API` |
585
+ | title only | `: Add foo` | `: Add foo` | `Add foo` | `: Add foo` |
586
+
587
+ Because three of the four name `{type}` outside any group, a record without a type renders a subject opening with a bare colon. Supply a type, or choose piped scope, whose type is inside a group and drops with it.
588
+
589
+ ## Constraints from release-kit
590
+
591
+ Because release-kit reads merge subjects to build the changelog, a template whose subjects it must read is bound by what its parser accepts:
592
+
593
+ - Any ticket reference comes first, in one of the three stripped forms above.
594
+ - A pipe separates the scope from the type (`agents|feat:`), or parentheses follow it (`feat(agents):`). The parser does not read a bracketed scope, so `[agents] feat: Add foo` is unmatched.
595
+ - The breaking marker is immediately before the colon: `feat!:`, `feat(agents)!:`.
596
+ - Because the type is a run of word characters, a type with a hyphen or a dot goes unread. The parser lowercases the type before matching the taxonomy. Case does not decide the match, and the canonical spelling stays lowercase.
597
+
598
+ ## What the grammar refuses
599
+
600
+ The bundle checks each configured template when preferences load, and a template that cannot round-trip stops the run, naming the surface, the template, and the defect. It refuses four structural defects:
601
+
602
+ - **Adjacent tokens.** Two tokens without a literal between them, such as `{scope}{type}`, leave a parse without a boundary to split on. `{breaking}` beside another token is exempt, since the marker is a single known character.
603
+ - **A repeated token.** A token named twice leaves a parse without a way to decide which occurrence a value belongs to.
604
+ - **A group boundary that repeats.** An optional group whose opening literal repeats the text before it hides where the group begins.
605
+ - **An indistinguishable marker.** `{breaking}` placed beside free text, or beside a literal that spells `!`, leaves the marker unrecognizable.
606
+
607
+ A render-and-parse pass over well-formed values then acts as a fallback for the four checks, so that it catches a defect that a later extension to the grammar introduces and the checks miss.
608
+
609
+ A template that round-trips every well-formed record but loses a token for some record shape, such as a flat `[{scope}|{type}: ]` prefix for a change without a scope, is not refused. The bundle warns of it instead; see [Optional groups](#optional-groups).
610
+
611
+ ## What the grammar does not support
612
+
613
+ **Value-dependent ambiguity passes the check.** The check runs over well-formed values, so it accepts a template whose ambiguity depends on what a value happens to contain. Under `[{ticket_ref} ]{title}`, the title `#466 Add foo` reads back as ticket reference `#466` and title `Add foo`. Because that matches how release-kit reads it, the behavior is compatibility rather than a defect, but a caller that keeps both halves separately should not rely on a round trip to recover them.
614
+
615
+ The same cost applies to the piped-scope convention, in which a present group wins. `Rename kb|docs: the shared layer` reads back as scope `Rename kb`, type `docs`, title `the shared layer`. The type check prevents the misreading when the type is nonsense, so `Support a|b: syntax` is unmatched, but not when the type is real.
616
+
617
+ ## Scope values
618
+
619
+ The `{scope}` token expects a value that identifies the part of the codebase affected. Surface-defined values:
620
+
621
+ - In a monorepo, the scope is typically the workspace name or abbreviation.
622
+ - Use `root` when the change touches only files at the monorepo root.
623
+ - A change to root and exactly one workspace takes that workspace, since the root files support its work.
624
+ - Use `*` when the change spans multiple workspaces, with or without root. It normalizes to an empty scope, so the rendered title does not have a scope prefix.
625
+
626
+ **A scope may name several workspaces, joined by commas**, which is how one commit entry that spans two workspaces renders as one `Change:` trailer: `agents,kb|feat: Add the store-qualified wikilink`. Normalization trims each name and drops the empty ones, the `*` ones, and the duplicates, keeping first-occurrence order; `agents,*` therefore names `agents`, and a value that leaves nothing behind does not name any scope, exactly as a whole-value `*` does.
627
+
628
+ A rendered list reads back as the same value, since the scope run is bounded by the delimiter that the template itself places after it and the catalogue does not contain a convention that delimits the scope with a comma. A template that does is refused as one that cannot round-trip.
629
+
630
+ **Consolidation counts each named workspace separately.** One entry naming `agents,kb` contributes both, exactly as two entries naming one apiece do, so its consolidated record does not name a scope. Consolidation first sets aside the scopes of entries in the taxonomy's last tier (`process` in the bundled taxonomy) whenever an entry of a higher tier names a scope, because process work such as a catalog move supports the branch's change rather than describing it: A `feat` scoped `img-promoter` and a `deps` scoped `web` consolidate to `img-promoter`. It then sets `root` aside whenever the remaining scopes also name a workspace, and keeps a scope only when exactly one remains: `agents` and `root` consolidate to `agents`, and `root` alone to `root`. The scope labels omit `root` beside a workspace in the same way but keep a process-tier entry's workspace, since a label names every workspace that the branch changed.
631
+
632
+ Per-surface guidance on when to apply each value (e.g., what to count as `root` for a commit) is stated by the consuming skill; see the `consult-commit-conventions` skill for the commit-side rules.