codeassembly-guidance 0.7.0 → 0.8.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 (101) hide show
  1. package/.meta/changelog.json +261 -0
  2. package/CHANGELOG.md +62 -0
  3. package/README.md +47 -29
  4. package/bin/codeassembly-validate-preferences.js +2 -8
  5. package/content/_partials/diff-audit-checklist.md +1 -0
  6. package/content/_partials/plain-speech.md +2 -2
  7. package/content/_partials/ticket-assessment.md +3 -3
  8. package/content/codeassembly-content.yaml +6 -0
  9. package/content/collections/recommended.md +6 -0
  10. package/content/collections/williamthorsen.md +2 -1
  11. package/content/guidance/rulebooks/accessibility-conventions.md +6 -3
  12. package/content/guidance/rulebooks/cross-repo-migration-conventions.md +27 -0
  13. package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
  14. package/content/guidance/rulebooks/visual-design-conventions.md +58 -0
  15. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +3 -18
  16. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +6 -2
  17. package/content/guidance/rulebooks/williamthorsen-visual-design-preferences.md +14 -0
  18. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +5 -3
  19. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -20
  20. package/content/guidance/shared/AGENTS.md +2 -3
  21. package/content/scripts/README.md +1 -1
  22. package/content/scripts/check-branch-currency.mjs +7 -7
  23. package/content/scripts/check-prose.mjs +38 -38
  24. package/content/scripts/describe-change.mjs +32 -32
  25. package/content/scripts/manage-jira-ticket.mjs +148 -146
  26. package/content/scripts/validate-preferences.mjs +9 -9
  27. package/content/skills/_data/artifact-conventions.md +3 -3
  28. package/content/skills/_data/entry-points.md +1 -1
  29. package/content/skills/_data/reduced-object-relatives.md +15 -0
  30. package/content/skills/_data/spike-conventions.md +9 -2
  31. package/content/skills/_data/ticket-evaluation.md +3 -0
  32. package/content/skills/_partials/implementation-order-list.md +4 -4
  33. package/content/skills/_partials/merge-settled-criterion.md +1 -0
  34. package/content/skills/_partials/plan-template.md +1 -1
  35. package/content/skills/_partials/resolve-plan-and-ticket.md +2 -2
  36. package/content/skills/_partials/split-ticket-create.md +1 -1
  37. package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
  38. package/content/skills/align-ticket-with-implementation/SKILL.md +2 -2
  39. package/content/skills/analyze-performance/SKILL.md +1 -1
  40. package/content/skills/assess-code-health/SKILL.md +4 -4
  41. package/content/skills/assess-code-health/assess-code-health.mjs +20 -20
  42. package/content/skills/assess-ticket/SKILL.md +3 -1
  43. package/content/skills/assess-ticket/next-steps-after-assessment.md +11 -14
  44. package/content/skills/assess-usability/SKILL.md +4 -4
  45. package/content/skills/capture-event/capture-event.mjs +30 -30
  46. package/content/skills/capture-lede-decision/SKILL.md +1 -1
  47. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +37 -37
  48. package/content/skills/collaborate/SKILL.md +1 -1
  49. package/content/skills/condense-branch/SKILL.md +18 -36
  50. package/content/skills/condense-branch/condense-branch.mjs +17 -0
  51. package/content/skills/create-bitbucket-pr/SKILL.md +9 -11
  52. package/content/skills/create-commit/SKILL.md +1 -1
  53. package/content/skills/create-devlog/SKILL.md +4 -4
  54. package/content/skills/create-gh-pr/SKILL.md +9 -11
  55. package/content/skills/create-pr/SKILL.md +9 -11
  56. package/content/skills/create-ticket/SKILL.md +22 -15
  57. package/content/skills/curate-feedback/SKILL.md +2 -2
  58. package/content/skills/derive-session-context/derive-session-context.mjs +103 -103
  59. package/content/skills/design-and-plan/SKILL.md +6 -6
  60. package/content/skills/groom-backlog/groom-backlog.mjs +15 -15
  61. package/content/skills/implement-plan/SKILL.md +1 -1
  62. package/content/skills/implementation-order/implementation-order.mjs +29 -29
  63. package/content/skills/index-prototypes/SKILL.md +2 -2
  64. package/content/skills/investigate-spike/SKILL.md +3 -3
  65. package/content/skills/list-gh-progress-items/SKILL.md +36 -0
  66. package/content/skills/list-gh-progress-items/list-gh-progress-items.mjs +68 -0
  67. package/content/skills/list-implementation-order/SKILL.md +2 -2
  68. package/content/skills/merge-bb-pr/SKILL.md +9 -11
  69. package/content/skills/merge-gh-pr/SKILL.md +9 -11
  70. package/content/skills/merge-pr/SKILL.md +10 -12
  71. package/content/skills/plan/SKILL.md +2 -2
  72. package/content/skills/prepare-prototype-brief/SKILL.md +2 -2
  73. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +22 -22
  74. package/content/skills/refine-plan/SKILL.md +3 -3
  75. package/content/skills/refine-prototype/SKILL.md +2 -1
  76. package/content/skills/respond-to-review/SKILL.md +4 -4
  77. package/content/skills/review-bb-pr/SKILL.md +1 -2
  78. package/content/skills/review-branch/SKILL.md +18 -13
  79. package/content/skills/review-criteria/SKILL.md +1 -1
  80. package/content/skills/review-gh-pr/SKILL.md +1 -2
  81. package/content/skills/review-pr/SKILL.md +2 -3
  82. package/content/skills/revise-prose/revise-prose.mjs +52 -52
  83. package/content/skills/save-artifact/SKILL.md +4 -6
  84. package/content/skills/save-plan/SKILL.md +2 -2
  85. package/content/skills/start-ticket/SKILL.md +1 -1
  86. package/content/skills/streamline-guidance/streamline-guidance.mjs +24 -24
  87. package/content/skills/summarize-change/SKILL.md +5 -4
  88. package/content/skills/summarize-chat/SKILL.md +2 -2
  89. package/content/skills/triage-feedback/SKILL.md +2 -2
  90. package/content/skills/triage-spike-findings/SKILL.md +26 -22
  91. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +19 -19
  92. package/content/skills/update-project-guidance/SKILL.md +1 -1
  93. package/content/skills/wrap-up/SKILL.md +4 -4
  94. package/content/skills/write-progress-report/SKILL.md +111 -0
  95. package/content/skills/write-progress-report/write-progress-report.mjs +150 -0
  96. package/content/subagents/disposition-challenger.md +7 -6
  97. package/content/subagents/entry-drafter.md +2 -0
  98. package/content/subagents/usability-assessor.md +3 -2
  99. package/package.json +11 -10
  100. package/schemas/preferences.v1.json +9 -1
  101. package/schemas/work-types.v1.json +1 -1
@@ -1,4 +1,265 @@
1
1
  [
2
+ {
3
+ "version": "0.8.0",
4
+ "date": "2026-11-20",
5
+ "sections": [
6
+ {
7
+ "title": "🎉 Features",
8
+ "audience": "all",
9
+ "items": [
10
+ {
11
+ "description": "Changes `review-branch` to reflow each comment line that the diff adds or modifies and that exceeds the `max_line_length` set by `.editorconfig`, commit the reflow with `create-commit`, and list it in a new \"Applied reflows\" section of the review, rather than report it as a finding; a review of a pull request, or of a file with uncommitted changes, still reports the line as a finding. (#196)",
12
+ "hash": "8a5c2a662f539e576aed2da1034bab779cfa6b77",
13
+ "entry": 1
14
+ },
15
+ {
16
+ "description": "Adds a width item to the diff-audit checklist used by `implement-plan`, `respond-to-review`, and `revise-comments`, which directs the agent to reflow each comment line in its own hunks that exceeds the `.editorconfig` `max_line_length`, changing only whitespace. (#196)",
17
+ "hash": "8a5c2a662f539e576aed2da1034bab779cfa6b77",
18
+ "entry": 2
19
+ },
20
+ {
21
+ "description": "Adds to the `recommended` collection the `cross-repo-migration-conventions` rulebook, which covers the umbrella ticket and its one child per repository, shared runtimes moved before the repositories that use them, contract changes decided before any child acts, and a comment on the umbrella that each child posts before merge. (#197)",
22
+ "hash": "5e8a4d7f278cf5b61c87741fbf9d8452e220ba91",
23
+ "entry": 1
24
+ },
25
+ {
26
+ "description": "Adds to `williamthorsen-ticketing-preferences` a reference to `cross-repo-migration-conventions` for a change that migrates many repositories to a new version or convention. (#197)",
27
+ "hash": "5e8a4d7f278cf5b61c87741fbf9d8452e220ba91",
28
+ "entry": 2
29
+ },
30
+ {
31
+ "description": "Adds a requirement to the `williamthorsen-ticketing-preferences` rulebook to estimate the layers, subsystems, and approximate source and test lines of work that spans several layers or adds a new subsystem before its ticket count is decided, and to recommend the split when each piece can be merged and verified on its own, and has the `design-and-plan` ticket checkpoint present that split as the recommended option of a menu. (#202)",
32
+ "hash": "576597d420cc994035242d478d1af6bab3cdffb3",
33
+ "entry": 1
34
+ },
35
+ {
36
+ "description": "Directs `list-implementation-order` to pass the repository in which a ticket outside GitHub is implemented, through the helper's new `--external \"[REPOSITORY:]KEY=Title\"` form, which the helper uses to label that ticket with the repository's prefix, such as `mc.MAC-7`. (#206)",
37
+ "hash": "ac868de813bcc018619ed68c3b3d0947ddb18515",
38
+ "entry": 1
39
+ },
40
+ {
41
+ "description": "Lower-cases the repository prefixes in the implementation-order list, such as `cg.12` in place of `CG.12`, to set them apart from an upper-case Jira key. (#206)",
42
+ "hash": "ac868de813bcc018619ed68c3b3d0947ddb18515",
43
+ "entry": 2
44
+ },
45
+ {
46
+ "description": "Adds a durability check to `summarize-change` that rejects a lede, entry, or migration stating the change's delivery state in a main or subordinate clause, and adds a step that the change needs in order to take effect, such as a deploy or a sync, to the facts that `## Notes for reviewers` contains. (#207)",
47
+ "hash": "67476f398e10c9936af78dca7bef03492c6b7ef6",
48
+ "entry": 2
49
+ },
50
+ {
51
+ "description": "Adds a convention to `create-ticket`, `design-and-plan`, and `align-ticket-with-implementation` that limits a code ticket's acceptance criteria to those that its pull request's tests, checks, or review can show to hold or fail at merge, and directs the agent to move a criterion that depends on elapsed time, deployed state, or a run against shared data to the ticket that consumes the change. (#208)",
52
+ "hash": "0af73fb2285962ad29ae43315926613ab2c7d6ea",
53
+ "entry": 1
54
+ },
55
+ {
56
+ "description": "Adds a criterion-settleability facet to the ticket evaluation used by `design-and-plan` and by the advisability dimension of `assess-ticket`, which reports each acceptance criterion of a code ticket that its pull request cannot show to hold or fail at merge, together with the ticket to which the criterion moves. (#208)",
57
+ "hash": "0af73fb2285962ad29ae43315926613ab2c7d6ea",
58
+ "entry": 2
59
+ },
60
+ {
61
+ "description": "Adds the `write-progress-report` skill, which writes a customer-facing progress report from a tracker or an `--items` file, with one section per workstream that states its health and lists the items that need the customer's input, are done, are in progress, or are planned. (#213)",
62
+ "hash": "57e86c0026c03c7cc0aaf7910cefcea5e0e11968",
63
+ "entry": 1
64
+ },
65
+ {
66
+ "description": "Adds `list-gh-progress-items`, which `write-progress-report` calls for `--source github` to read a repository's GitHub issues as report items, treating each parent issue as a workstream and each issue labeled `needs-input` as an ask of the customer. (#213)",
67
+ "hash": "57e86c0026c03c7cc0aaf7910cefcea5e0e11968",
68
+ "entry": 2
69
+ },
70
+ {
71
+ "description": "Adds `confluence` to the values of the `write-progress-report` skill's `--format` argument, which renders the report in Confluence storage format (the XML that Confluence stores as a page body), with health and statuses as status lozenges and dates as date elements that Confluence shows in the reader's locale. (#215)",
72
+ "hash": "b5ab073bc60964f3f312a9c7b21fb567475fda46",
73
+ "entry": 1
74
+ },
75
+ {
76
+ "description": "Adds `project_artifact_dir` (`{artifact_base_dir}/projects/{project_slug}`) and `ticket_dir` (`{project_artifact_dir}/tickets/{ticket_id}`, or `null` when the branch does not name a ticket) to the session-context manifest that `derive-session-context` emits. (#219)",
77
+ "hash": "34edc29acdf9512685e7f0a5744d7fc38a43e17c",
78
+ "entry": 1
79
+ },
80
+ {
81
+ "description": "Changes `save-artifact` and every other skill that saves or reads artifacts to take the artifact directories from the manifest, with `save-artifact` stating the fallback for a `null` `ticket_dir`, which generates a ticket ID and saves under `{project_artifact_dir}/tickets/{generated id}`. (#219)",
82
+ "hash": "34edc29acdf9512685e7f0a5744d7fc38a43e17c",
83
+ "entry": 2
84
+ },
85
+ {
86
+ "description": "Adds to the `recommended` collection the `visual-design-conventions` rulebook, which states the visual-design rules that hold whatever the style: padding inside a bordered or filled container, alignment with another block, marks only on the exception, colour as a way to tell kinds and states apart, an appearance that follows each element's role, the product's own name and favicon, and a browser check of each changed view. (#220)",
87
+ "hash": "017980bb12b8013681740e866e26e73606e5e686",
88
+ "entry": 1
89
+ },
90
+ {
91
+ "description": "Adds to the `williamthorsen` collection the `williamthorsen-visual-design-preferences` rulebook, which prefers a quiet colour scheme, with muted hues on neutral surfaces that each encode a kind or a state, to a monochrome one. (#220)",
92
+ "hash": "017980bb12b8013681740e866e26e73606e5e686",
93
+ "entry": 2
94
+ },
95
+ {
96
+ "description": "Adds `visual-design-conventions` beside `accessibility-conventions` to the floor that the planning, building, assessment, and review skills and the `usability-assessor` subagent set for an interface, including the rulebook's browser check of each changed view. (#220)",
97
+ "hash": "017980bb12b8013681740e866e26e73606e5e686",
98
+ "entry": 3
99
+ },
100
+ {
101
+ "description": "Adds the \"Consequence at the control\" rule to `accessibility-conventions`, which requires the explanation of an action that cannot be undone to be visible at rest, allows a toggletip for one that can be undone, and never accepts a hover-only tooltip as the only explanation. (#221)",
102
+ "hash": "1eda2181589f8ba6e19b955ded94b4e150db44e2",
103
+ "entry": 1
104
+ },
105
+ {
106
+ "description": "Opens `accessibility-conventions` with a statement that its rules are floors, and directs agents to aim beyond them by following an established model, as the named-model rule describes. (#221)",
107
+ "hash": "1eda2181589f8ba6e19b955ded94b4e150db44e2",
108
+ "entry": 2
109
+ },
110
+ {
111
+ "description": "Extends the helper-text rule of `ui-copy-conventions` to say what an action's consequence explanation states, and counts that explanation toward the copy budget's one line of helper text. (#221)",
112
+ "hash": "1eda2181589f8ba6e19b955ded94b4e150db44e2",
113
+ "entry": 3
114
+ },
115
+ {
116
+ "description": "Adds the consequence-at-the-control rule to the skills and the subagent that list the accessibility rules that they apply, among them `review-criteria`, `prepare-prototype-brief`, and the `usability-assessor` per-screen checklist. (#221)",
117
+ "hash": "1eda2181589f8ba6e19b955ded94b4e150db44e2",
118
+ "entry": 4
119
+ },
120
+ {
121
+ "description": "Adds a `close` subcommand to `manage-jira-ticket.mjs`, which posts a Markdown body as a comment unless an existing comment opens with the body's first line, then transitions the work item to the status that the new `integrations.jira.done_status` preference names (default `Done`) unless its status category is already done. (#225)",
122
+ "hash": "c9dad124c542ea2dc9206866e594c6730fa3c3fd",
123
+ "entry": 1
124
+ },
125
+ {
126
+ "description": "Extends the closing post of the spike skills and the close of the triage ticket in `triage-spike-findings` to Jira tickets through `manage-jira-ticket.mjs close`; the guidance previously named only `gh issue close`, which does not close a Jira ticket. (#225)",
127
+ "hash": "c9dad124c542ea2dc9206866e594c6730fa3c3fd",
128
+ "entry": 2
129
+ },
130
+ {
131
+ "description": "Extends `triage-spike-findings` to run on Jira as well as GitHub, adding a `platform` field to the dispositions record so that the record accepts work item keys such as `PROJ-123`, and creating each Jira ticket under the triage ticket's parent in place of an umbrella. (#227)",
132
+ "hash": "73f7d6f6f790f8c1127a8b8b3937ac6e9099ed6f",
133
+ "entry": 1
134
+ },
135
+ {
136
+ "description": "Makes `analyze-performance`, `assess-code-health`, `assess-usability`, and `investigate-spike` name `triage-spike-findings` as the next step only for a ticket on GitHub or Jira, and name the findings left for disposal by hand for a ticket on any other platform. (#227)",
137
+ "hash": "73f7d6f6f790f8c1127a8b8b3937ac6e9099ed6f",
138
+ "entry": 2
139
+ },
140
+ {
141
+ "description": "Adds a rule to the `williamthorsen-ticketing-preferences` rulebook that splits adding a package to a monorepo into two tickets: an empty scaffold with its documentation and package references that passes the repository's checks on its own, and the package's functionality, blocked by the scaffold. (#229)",
142
+ "hash": "a098104295002a9eba5773e7810b80533eb03451",
143
+ "entry": 1
144
+ },
145
+ {
146
+ "description": "Changes `create-commit` to record a scaffold that passes the repository's checks and is fully wired as a commit of its own, while a scaffold that a later change fills in still goes into that change. (#229)",
147
+ "hash": "a098104295002a9eba5773e7810b80533eb03451",
148
+ "entry": 2
149
+ },
150
+ {
151
+ "description": "Requires in the `visual-design-conventions` rulebook that text and elements within a block be start-aligned and a column of numbers end-aligned, limits centring to a viewport-centred dialog, a single-line label in a button or a tag, and an icon in a square control, and adds a matching item to the rulebook's browser check. (#231)",
152
+ "hash": "20fe892fe4444395510fe4cc3f0c5c6df874d78d",
153
+ "entry": 1
154
+ },
155
+ {
156
+ "description": "Adds the `--umbrella` flag to `create-ticket`, which on Jira creates the ticket at the issue type that the new `integrations.jira.umbrella_issue_type` preference sets, `Epic` by default, so that Jira accepts it as the parent of its child tickets. (#232)",
157
+ "hash": "7adea702846e20e626db2b7dd60e5ffe334242a2",
158
+ "entry": 2
159
+ }
160
+ ]
161
+ },
162
+ {
163
+ "title": "🐛 Bug fixes",
164
+ "audience": "all",
165
+ "items": [
166
+ {
167
+ "description": "Fixes the issue that `assess-ticket` prescribed a plain numbered list of next-step actions, which the ambient option format overrode on every run, by including the shared option format and marking each action at the strength that the evidence behind its verdict supports. (#193)",
168
+ "hash": "a86f92f7f832c43f80087150da2a50dcfff978e6",
169
+ "entry": 1
170
+ },
171
+ {
172
+ "description": "Fixes the issue that `condense-branch` left uncommitted changes in a stash shared by every worktree of the repository, or folded them into the condensed commit through `git add --all` when the stash was skipped. (#195)",
173
+ "hash": "e9f5f9b3e0086fb406a3bcdcaec9b72f0419a3c2",
174
+ "entry": 1
175
+ },
176
+ {
177
+ "description": "Fixes the issue that `review-pr` passed its session-context values only to `review-branch`'s steps 4–9, which left out the step that saves the review. (#196)",
178
+ "hash": "8a5c2a662f539e576aed2da1034bab779cfa6b77",
179
+ "entry": 3
180
+ },
181
+ {
182
+ "description": "Fixes the issue that `list-implementation-order` listed an umbrella ticket, one that has sub-issues, as a ticket to implement, although its children do its work. (#199)",
183
+ "hash": "7db2b098233dddb213ec4cf4bcc45346ce44935e",
184
+ "entry": 1
185
+ },
186
+ {
187
+ "description": "Fixes the issue that `entry-drafter` could write a change's delivery state, such as \"takes effect once deployed\", into the lede or an entry, which the merge commit keeps after the statement becomes false. (#207)",
188
+ "hash": "67476f398e10c9936af78dca7bef03492c6b7ef6",
189
+ "entry": 1
190
+ },
191
+ {
192
+ "description": "Fixes the issue that `williamthorsen-workflow-preferences` did not stop a session from creating a branch, a worktree, or commits in a repository or ticket other than its own, and that its cross-repo sequencing rule told the session to make the upstream change itself. (#214)",
193
+ "hash": "38817a1523f1ccb3a58023dc4a0c5cb125eb104e",
194
+ "entry": 1
195
+ },
196
+ {
197
+ "description": "Fixes the issue that `create-ticket` reversed a Jira blocked-by link by putting the blocker in the `--out` option of `acli jira workitem link create`, when `--in` is the option that names the blocker. (#227)",
198
+ "hash": "73f7d6f6f790f8c1127a8b8b3937ac6e9099ed6f",
199
+ "entry": 3
200
+ },
201
+ {
202
+ "description": "Fixes the issue that `triage-spike-findings` did not create an umbrella on Jira and parented each new ticket to the triage ticket's parent, by having it create the umbrella on Jira as on GitHub and parent each child ticket to it. (#232)",
203
+ "hash": "7adea702846e20e626db2b7dd60e5ffe334242a2",
204
+ "entry": 1
205
+ },
206
+ {
207
+ "description": "Fixes the issue that `create-ticket` gave a Jira child of a level-0 parent, such as a `Task`, the child's own issue type, which Jira rejects under that parent, and makes `create-ticket` create the child as a subtask at the type that the new `integrations.jira.subtask_issue_type` setting declares (`Subtask` by default). (#233)",
208
+ "hash": "c7d89d68a51daaa5187df82f9676918733f35d1f",
209
+ "entry": 1
210
+ }
211
+ ]
212
+ },
213
+ {
214
+ "title": "⚡ Performance",
215
+ "audience": "all",
216
+ "items": [
217
+ {
218
+ "description": "Cuts about 110 words from the shared `AGENTS.md` and the plain-speech partial, both loaded into every session, by removing a redundant example, a sentence of rationale, a repeated repair, and three sentences that describe skills or tickets without directing the agent. (#190)",
219
+ "hash": "c7776a100d7c8bd092d85302109cd9e57b9ecb6f",
220
+ "entry": 1
221
+ },
222
+ {
223
+ "description": "Cuts the prompt-formatting rules that the option-format and action-items guidance already states from the ambient `williamthorsen-collaboration-preferences` rulebook, which shrinks from 11,919 to 6,031 bytes in every session that loads it. (#191)",
224
+ "hash": "34a5760788c19ad9f96604f1e9b164156384d990",
225
+ "entry": 1
226
+ },
227
+ {
228
+ "description": "Removes the note \"(Reinforces the rule in `AGENTS.md`: intentional redundancy.)\" from the option-format directive in the skills that link to the option format, because the rulebook no longer states that rule. (#191)",
229
+ "hash": "34a5760788c19ad9f96604f1e9b164156384d990",
230
+ "entry": 2
231
+ },
232
+ {
233
+ "description": "Cuts the `williamthorsen-writing-preferences` rulebook from 9,234 to 7,246 bytes by moving three rarely needed reduced-object-relative cases into `skills/_data/reduced-object-relatives.md`, which the rule links to, and by removing passages that the remaining rules already direct. (#192)",
234
+ "hash": "1b5fc588292711ce63d38af5a7e8509eb01ea6db",
235
+ "entry": 1
236
+ }
237
+ ]
238
+ },
239
+ {
240
+ "title": "♻️ Refactoring",
241
+ "audience": "dev",
242
+ "items": [
243
+ {
244
+ "description": "Replaces the inline `error instanceof Error ? error.message : String(error)` expression in the guidance helpers with `describeError` from `@williamthorsen/toolbelt.errors`, and moves the error report of the `codeassembly-validate-preferences` bin into a new `runValidatePreferencesCommand` function, which the bin and the helper's entry point both call. (#201)",
245
+ "hash": "32e94300de37e89f9ae13f24a038d36c6e6564c4",
246
+ "entry": 2
247
+ }
248
+ ]
249
+ },
250
+ {
251
+ "title": "⚙️ Tooling",
252
+ "audience": "dev",
253
+ "items": [
254
+ {
255
+ "description": "Regenerates the tracked `revise-prose.mjs` bundle from its current source, a rebuild that changes only identifiers renamed by the minifier. (#219)",
256
+ "hash": "34edc29acdf9512685e7f0a5744d7fc38a43e17c",
257
+ "entry": 3
258
+ }
259
+ ]
260
+ }
261
+ ]
262
+ },
2
263
  {
3
264
  "version": "0.7.0",
4
265
  "date": "2026-11-14",
package/CHANGELOG.md CHANGED
@@ -2,6 +2,68 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## 0.8.0 — 2026-11-20
6
+
7
+ ### 🎉 Features
8
+
9
+ - Changes `review-branch` to reflow each comment line that the diff adds or modifies and that exceeds the `max_line_length` set by `.editorconfig`, commit the reflow with `create-commit`, and list it in a new "Applied reflows" section of the review, rather than report it as a finding; a review of a pull request, or of a file with uncommitted changes, still reports the line as a finding. (#196)
10
+ - Adds a width item to the diff-audit checklist used by `implement-plan`, `respond-to-review`, and `revise-comments`, which directs the agent to reflow each comment line in its own hunks that exceeds the `.editorconfig` `max_line_length`, changing only whitespace. (#196)
11
+ - Adds to the `recommended` collection the `cross-repo-migration-conventions` rulebook, which covers the umbrella ticket and its one child per repository, shared runtimes moved before the repositories that use them, contract changes decided before any child acts, and a comment on the umbrella that each child posts before merge. (#197)
12
+ - Adds to `williamthorsen-ticketing-preferences` a reference to `cross-repo-migration-conventions` for a change that migrates many repositories to a new version or convention. (#197)
13
+ - Adds a requirement to the `williamthorsen-ticketing-preferences` rulebook to estimate the layers, subsystems, and approximate source and test lines of work that spans several layers or adds a new subsystem before its ticket count is decided, and to recommend the split when each piece can be merged and verified on its own, and has the `design-and-plan` ticket checkpoint present that split as the recommended option of a menu. (#202)
14
+ - Directs `list-implementation-order` to pass the repository in which a ticket outside GitHub is implemented, through the helper's new `--external "[REPOSITORY:]KEY=Title"` form, which the helper uses to label that ticket with the repository's prefix, such as `mc.MAC-7`. (#206)
15
+ - Lower-cases the repository prefixes in the implementation-order list, such as `cg.12` in place of `CG.12`, to set them apart from an upper-case Jira key. (#206)
16
+ - Adds a durability check to `summarize-change` that rejects a lede, entry, or migration stating the change's delivery state in a main or subordinate clause, and adds a step that the change needs in order to take effect, such as a deploy or a sync, to the facts that `## Notes for reviewers` contains. (#207)
17
+ - Adds a convention to `create-ticket`, `design-and-plan`, and `align-ticket-with-implementation` that limits a code ticket's acceptance criteria to those that its pull request's tests, checks, or review can show to hold or fail at merge, and directs the agent to move a criterion that depends on elapsed time, deployed state, or a run against shared data to the ticket that consumes the change. (#208)
18
+ - Adds a criterion-settleability facet to the ticket evaluation used by `design-and-plan` and by the advisability dimension of `assess-ticket`, which reports each acceptance criterion of a code ticket that its pull request cannot show to hold or fail at merge, together with the ticket to which the criterion moves. (#208)
19
+ - Adds the `write-progress-report` skill, which writes a customer-facing progress report from a tracker or an `--items` file, with one section per workstream that states its health and lists the items that need the customer's input, are done, are in progress, or are planned. (#213)
20
+ - Adds `list-gh-progress-items`, which `write-progress-report` calls for `--source github` to read a repository's GitHub issues as report items, treating each parent issue as a workstream and each issue labeled `needs-input` as an ask of the customer. (#213)
21
+ - Adds `confluence` to the values of the `write-progress-report` skill's `--format` argument, which renders the report in Confluence storage format (the XML that Confluence stores as a page body), with health and statuses as status lozenges and dates as date elements that Confluence shows in the reader's locale. (#215)
22
+ - Adds `project_artifact_dir` (`{artifact_base_dir}/projects/{project_slug}`) and `ticket_dir` (`{project_artifact_dir}/tickets/{ticket_id}`, or `null` when the branch does not name a ticket) to the session-context manifest that `derive-session-context` emits. (#219)
23
+ - Changes `save-artifact` and every other skill that saves or reads artifacts to take the artifact directories from the manifest, with `save-artifact` stating the fallback for a `null` `ticket_dir`, which generates a ticket ID and saves under `{project_artifact_dir}/tickets/{generated id}`. (#219)
24
+ - Adds to the `recommended` collection the `visual-design-conventions` rulebook, which states the visual-design rules that hold whatever the style: padding inside a bordered or filled container, alignment with another block, marks only on the exception, colour as a way to tell kinds and states apart, an appearance that follows each element's role, the product's own name and favicon, and a browser check of each changed view. (#220)
25
+ - Adds to the `williamthorsen` collection the `williamthorsen-visual-design-preferences` rulebook, which prefers a quiet colour scheme, with muted hues on neutral surfaces that each encode a kind or a state, to a monochrome one. (#220)
26
+ - Adds `visual-design-conventions` beside `accessibility-conventions` to the floor that the planning, building, assessment, and review skills and the `usability-assessor` subagent set for an interface, including the rulebook's browser check of each changed view. (#220)
27
+ - Adds the "Consequence at the control" rule to `accessibility-conventions`, which requires the explanation of an action that cannot be undone to be visible at rest, allows a toggletip for one that can be undone, and never accepts a hover-only tooltip as the only explanation. (#221)
28
+ - Opens `accessibility-conventions` with a statement that its rules are floors, and directs agents to aim beyond them by following an established model, as the named-model rule describes. (#221)
29
+ - Extends the helper-text rule of `ui-copy-conventions` to say what an action's consequence explanation states, and counts that explanation toward the copy budget's one line of helper text. (#221)
30
+ - Adds the consequence-at-the-control rule to the skills and the subagent that list the accessibility rules that they apply, among them `review-criteria`, `prepare-prototype-brief`, and the `usability-assessor` per-screen checklist. (#221)
31
+ - Adds a `close` subcommand to `manage-jira-ticket.mjs`, which posts a Markdown body as a comment unless an existing comment opens with the body's first line, then transitions the work item to the status that the new `integrations.jira.done_status` preference names (default `Done`) unless its status category is already done. (#225)
32
+ - Extends the closing post of the spike skills and the close of the triage ticket in `triage-spike-findings` to Jira tickets through `manage-jira-ticket.mjs close`; the guidance previously named only `gh issue close`, which does not close a Jira ticket. (#225)
33
+ - Extends `triage-spike-findings` to run on Jira as well as GitHub, adding a `platform` field to the dispositions record so that the record accepts work item keys such as `PROJ-123`, and creating each Jira ticket under the triage ticket's parent in place of an umbrella. (#227)
34
+ - Makes `analyze-performance`, `assess-code-health`, `assess-usability`, and `investigate-spike` name `triage-spike-findings` as the next step only for a ticket on GitHub or Jira, and name the findings left for disposal by hand for a ticket on any other platform. (#227)
35
+ - Adds a rule to the `williamthorsen-ticketing-preferences` rulebook that splits adding a package to a monorepo into two tickets: an empty scaffold with its documentation and package references that passes the repository's checks on its own, and the package's functionality, blocked by the scaffold. (#229)
36
+ - Changes `create-commit` to record a scaffold that passes the repository's checks and is fully wired as a commit of its own, while a scaffold that a later change fills in still goes into that change. (#229)
37
+ - Requires in the `visual-design-conventions` rulebook that text and elements within a block be start-aligned and a column of numbers end-aligned, limits centring to a viewport-centred dialog, a single-line label in a button or a tag, and an icon in a square control, and adds a matching item to the rulebook's browser check. (#231)
38
+ - Adds the `--umbrella` flag to `create-ticket`, which on Jira creates the ticket at the issue type that the new `integrations.jira.umbrella_issue_type` preference sets, `Epic` by default, so that Jira accepts it as the parent of its child tickets. (#232)
39
+
40
+ ### 🐛 Bug fixes
41
+
42
+ - Fixes the issue that `assess-ticket` prescribed a plain numbered list of next-step actions, which the ambient option format overrode on every run, by including the shared option format and marking each action at the strength that the evidence behind its verdict supports. (#193)
43
+ - Fixes the issue that `condense-branch` left uncommitted changes in a stash shared by every worktree of the repository, or folded them into the condensed commit through `git add --all` when the stash was skipped. (#195)
44
+ - Fixes the issue that `review-pr` passed its session-context values only to `review-branch`'s steps 4–9, which left out the step that saves the review. (#196)
45
+ - Fixes the issue that `list-implementation-order` listed an umbrella ticket, one that has sub-issues, as a ticket to implement, although its children do its work. (#199)
46
+ - Fixes the issue that `entry-drafter` could write a change's delivery state, such as "takes effect once deployed", into the lede or an entry, which the merge commit keeps after the statement becomes false. (#207)
47
+ - Fixes the issue that `williamthorsen-workflow-preferences` did not stop a session from creating a branch, a worktree, or commits in a repository or ticket other than its own, and that its cross-repo sequencing rule told the session to make the upstream change itself. (#214)
48
+ - Fixes the issue that `create-ticket` reversed a Jira blocked-by link by putting the blocker in the `--out` option of `acli jira workitem link create`, when `--in` is the option that names the blocker. (#227)
49
+ - Fixes the issue that `triage-spike-findings` did not create an umbrella on Jira and parented each new ticket to the triage ticket's parent, by having it create the umbrella on Jira as on GitHub and parent each child ticket to it. (#232)
50
+ - Fixes the issue that `create-ticket` gave a Jira child of a level-0 parent, such as a `Task`, the child's own issue type, which Jira rejects under that parent, and makes `create-ticket` create the child as a subtask at the type that the new `integrations.jira.subtask_issue_type` setting declares (`Subtask` by default). (#233)
51
+
52
+ ### ⚡ Performance
53
+
54
+ - Cuts about 110 words from the shared `AGENTS.md` and the plain-speech partial, both loaded into every session, by removing a redundant example, a sentence of rationale, a repeated repair, and three sentences that describe skills or tickets without directing the agent. (#190)
55
+ - Cuts the prompt-formatting rules that the option-format and action-items guidance already states from the ambient `williamthorsen-collaboration-preferences` rulebook, which shrinks from 11,919 to 6,031 bytes in every session that loads it. (#191)
56
+ - Removes the note "(Reinforces the rule in `AGENTS.md`: intentional redundancy.)" from the option-format directive in the skills that link to the option format, because the rulebook no longer states that rule. (#191)
57
+ - Cuts the `williamthorsen-writing-preferences` rulebook from 9,234 to 7,246 bytes by moving three rarely needed reduced-object-relative cases into `skills/_data/reduced-object-relatives.md`, which the rule links to, and by removing passages that the remaining rules already direct. (#192)
58
+
59
+ ### ♻️ Refactoring
60
+
61
+ - Replaces the inline `error instanceof Error ? error.message : String(error)` expression in the guidance helpers with `describeError` from `@williamthorsen/toolbelt.errors`, and moves the error report of the `codeassembly-validate-preferences` bin into a new `runValidatePreferencesCommand` function, which the bin and the helper's entry point both call. (#201)
62
+
63
+ ### ⚙️ Tooling
64
+
65
+ - Regenerates the tracked `revise-prose.mjs` bundle from its current source, a rebuild that changes only identifiers renamed by the minifier. (#219)
66
+
5
67
  ## 0.7.0 — 2026-11-14
6
68
 
7
69
  ### 🎉 Features
package/README.md CHANGED
@@ -5,41 +5,59 @@
5
5
  The CodeAssembly library of agent guidance: rulebooks, skills, and subagents for coding harnesses, which the [`codeassembly`](https://github.com/williamthorsen/codeassembly/blob/main/packages/agents/README.md) CLI deploys into Claude Code and Rovo Dev.
6
6
 
7
7
  <!-- section:release-notes -->
8
- ## Release notes — v0.7.0 (2026-11-14)
8
+ ## Release notes — v0.8.0 (2026-11-20)
9
9
 
10
10
  ### 🎉 Features
11
11
 
12
- - Makes `prepare-prototype-brief` post the approved brief on the ticket as a comment without asking a second time, with a summary line that names the lenses and the brief artifact and the full brief in a collapsed `<details>` block, and skips the post when an earlier run already posted it. (#145)
13
- - Adds the `merge.approval` preference, whose value `auto` makes `merge-pr` merge without its approval gate when the pull request is on GitHub and not breaking, its merge state is `CLEAN` or `HAS_HOOKS`, and the run neither reports a notice nor makes a decision of its own. (#147)
14
- - Adds the `--confirm` option to `merge-pr`, which shows the approval gate for one run when `merge.approval` is `auto`. (#147)
15
- - Adds the `project.stages` key to `.agents/preferences.yaml`, which declares the maturity, sensitivity, or audience of one subdirectory, and which `derive-session-context` reports as `project_stages` with each inherited value filled in, so that `plan` and `design-and-plan` apply the stage of the subdirectory that contains the work. (#150)
16
- - Adds `exploration` as a `project.maturity` value, below `hobby`, for work whose output is still taking shape and that nothing depends on yet. (#150)
17
- - Directs `plan` and `design-and-plan` to verify unsettled output, such as output at the `exploration` maturity or from a prototype, through a round in which the developer reads it on real inputs, and to plan golden references, answer keys, and evals only as tasks that follow the developer's approval of an output. (#150)
18
- - Adds an optional `## Notes for reviewers` section to the change summary written by `summarize-change`, along with a reader test that each line of that section, `## Why`, and `## How to test` must pass by changing what a reviewer who hasn't read the ticket checks or decides. (#151)
19
- - Directs `create-pr` to include `## Notes for reviewers` in the pull-request body and not to add a section, a note, or a test plan of its own. (#151)
20
- - Narrows the instruction in the shared `AGENTS.md`, `align-ticket-with-implementation`, and `review-branch` that had an agent report every divergence from the ticket's proposal in the pull-request description: It now names `## Notes for reviewers` and applies only to a divergence that changes what a reviewer checks. (#151)
21
- - Replaces the key-value completion lines at the end of `merge-pr`, `merge-gh-pr`, and `merge-bb-pr` replies with an outcome summary under a heading that states whether the PR was merged. (#158)
22
- - Adds a `summary` field to the JSON that `merge-gh-pr.mjs` prints after a confirmed merge, and changes the script to print a JSON object containing only `summary` on stdout when the merge is refused, fails, or cannot be confirmed. (#158)
23
- - Adds the ticket's close to the closing-post offer that ends a spike, so that one consent from the developer posts the conclusion and closes the ticket as completed, and a rerun skips whichever of the two writes is already done. (#159)
24
- - Makes `merge-pr` take its merge strategy and branch deletion from the `merge.strategy` (`squash`, `merge`, or `rebase`) and `merge.deletion_strategy` (`both`, `remote`, or `none`) preferences, which `derive-session-context` reports as `merge_strategy` and `merge_deletion_strategy` and which the `--strategy` and `--delete` flags override for one run. (#160)
25
- - Makes `derive-session-context` name the preferences file that contains an invalid value when it rejects one, in addition to the key and the accepted values. (#160)
26
- - Adds the `list-implementation-order` skill, which prints the conversation's open tickets as a tree in implementation order for a narrow column, with each ticket indented under its blocker, the blockers that the indent does not show, and a line for each change that must be published and upgraded in a consuming repository before a blocked ticket can start. (#163)
27
- - Changes the merged summary of `merge-gh-pr` and `merge-bb-pr` to a heading that names the target branch, the strategy, and the short merge commit hash, followed by labelled lines for the commit title, the PR link, and the remote branch deletion, with `merge-gh-pr` reading the commit title from GitHub after the merge and falling back to the submitted title, or to `unavailable`, when the read fails. (#164)
28
- - Changes the refusal summary of `merge-pr`, `merge-gh-pr`, and `merge-bb-pr` to a `## ❌ Not merged` heading followed by `PR:` and `Reason:` lines, and gives the unconfirmed-merge summary of `merge-gh-pr` the same layout under `## ⚠️ Merge not confirmed`. (#164)
29
- - Adds the implementation-order list, which shows the order, the blockers, and the publish gates of the tickets, to the output of a split's launch prompts and of the `triage-spike-findings`, `triage-feedback`, and `wrap-up` reports whenever the run creates two or more tickets. (#165)
30
- - Adds each `kb.yaml` registry entry that declares `in_default_scope: true` to the default scope of `kb-retrieve` and `kb-retrieve-events`, which previously searched only the discovered `.kb/` and the registry's `default_kb` unless `--all-kbs` was passed. (#172)
31
- - Makes `kb-add` refuse a write into a KB whose `visibility` is `shared` with a `shared-kb` error unless the invocation passes the new `--shared` flag, refuse a write with `invalid-config` when the KB's `.kb/config.yaml` is malformed, and report the KB's `visibility` in the `--survey` result. (#173)
32
- - Makes `capture-event` refuse a fresh capture into a store whose `visibility` is `shared` with a `shared-store` error unless the invocation passes the new `--shared` flag, and with `invalid-config` when the store's `.kb/config.yaml` is malformed, while leaving `--amend` exempt. (#173)
33
- - Adds a rule to the `capture-feedback` and `migrate-feedback-memories` skills that permits `--shared` only on a retry after a `shared-store` refusal and only for a record that contains nothing unfit for the store's collaborators, and that leaves any other record uncaptured rather than redirected to another store. (#173)
34
- - Adds `unsearchedPrivateStores` to the output of the `kb-retrieve` and `kb-retrieve-events` helpers, listing each registered store whose visibility is `private` and that the recall did not search, and directs the agent in both skills to report such a recall as partial and to name, for each store, the `--store` or `--all-kbs` flag that would include it, or that its path needs fixing. (#174)
35
- - Adds a rule to the `williamthorsen-ticketing-preferences` rulebook that limits a ticket to work in one repository and directs that a change needing two or more repositories get one ticket per repository, with the merge order, upstream first, recorded as blocked-by relations. (#179)
36
- - Makes `triage-spike-findings`, on a run given a batch, close the follow-up triage ticket as completed without a closing post once it posts the dispositions comment, and lists that close in the run's single confirmation and in its report. (#180)
12
+ - Changes `review-branch` to reflow each comment line that the diff adds or modifies and that exceeds the `max_line_length` set by `.editorconfig`, commit the reflow with `create-commit`, and list it in a new "Applied reflows" section of the review, rather than report it as a finding; a review of a pull request, or of a file with uncommitted changes, still reports the line as a finding. (#196)
13
+ - Adds a width item to the diff-audit checklist used by `implement-plan`, `respond-to-review`, and `revise-comments`, which directs the agent to reflow each comment line in its own hunks that exceeds the `.editorconfig` `max_line_length`, changing only whitespace. (#196)
14
+ - Adds to the `recommended` collection the `cross-repo-migration-conventions` rulebook, which covers the umbrella ticket and its one child per repository, shared runtimes moved before the repositories that use them, contract changes decided before any child acts, and a comment on the umbrella that each child posts before merge. (#197)
15
+ - Adds to `williamthorsen-ticketing-preferences` a reference to `cross-repo-migration-conventions` for a change that migrates many repositories to a new version or convention. (#197)
16
+ - Adds a requirement to the `williamthorsen-ticketing-preferences` rulebook to estimate the layers, subsystems, and approximate source and test lines of work that spans several layers or adds a new subsystem before its ticket count is decided, and to recommend the split when each piece can be merged and verified on its own, and has the `design-and-plan` ticket checkpoint present that split as the recommended option of a menu. (#202)
17
+ - Directs `list-implementation-order` to pass the repository in which a ticket outside GitHub is implemented, through the helper's new `--external "[REPOSITORY:]KEY=Title"` form, which the helper uses to label that ticket with the repository's prefix, such as `mc.MAC-7`. (#206)
18
+ - Lower-cases the repository prefixes in the implementation-order list, such as `cg.12` in place of `CG.12`, to set them apart from an upper-case Jira key. (#206)
19
+ - Adds a durability check to `summarize-change` that rejects a lede, entry, or migration stating the change's delivery state in a main or subordinate clause, and adds a step that the change needs in order to take effect, such as a deploy or a sync, to the facts that `## Notes for reviewers` contains. (#207)
20
+ - Adds a convention to `create-ticket`, `design-and-plan`, and `align-ticket-with-implementation` that limits a code ticket's acceptance criteria to those that its pull request's tests, checks, or review can show to hold or fail at merge, and directs the agent to move a criterion that depends on elapsed time, deployed state, or a run against shared data to the ticket that consumes the change. (#208)
21
+ - Adds a criterion-settleability facet to the ticket evaluation used by `design-and-plan` and by the advisability dimension of `assess-ticket`, which reports each acceptance criterion of a code ticket that its pull request cannot show to hold or fail at merge, together with the ticket to which the criterion moves. (#208)
22
+ - Adds the `write-progress-report` skill, which writes a customer-facing progress report from a tracker or an `--items` file, with one section per workstream that states its health and lists the items that need the customer's input, are done, are in progress, or are planned. (#213)
23
+ - Adds `list-gh-progress-items`, which `write-progress-report` calls for `--source github` to read a repository's GitHub issues as report items, treating each parent issue as a workstream and each issue labeled `needs-input` as an ask of the customer. (#213)
24
+ - Adds `confluence` to the values of the `write-progress-report` skill's `--format` argument, which renders the report in Confluence storage format (the XML that Confluence stores as a page body), with health and statuses as status lozenges and dates as date elements that Confluence shows in the reader's locale. (#215)
25
+ - Adds `project_artifact_dir` (`{artifact_base_dir}/projects/{project_slug}`) and `ticket_dir` (`{project_artifact_dir}/tickets/{ticket_id}`, or `null` when the branch does not name a ticket) to the session-context manifest that `derive-session-context` emits. (#219)
26
+ - Changes `save-artifact` and every other skill that saves or reads artifacts to take the artifact directories from the manifest, with `save-artifact` stating the fallback for a `null` `ticket_dir`, which generates a ticket ID and saves under `{project_artifact_dir}/tickets/{generated id}`. (#219)
27
+ - Adds to the `recommended` collection the `visual-design-conventions` rulebook, which states the visual-design rules that hold whatever the style: padding inside a bordered or filled container, alignment with another block, marks only on the exception, colour as a way to tell kinds and states apart, an appearance that follows each element's role, the product's own name and favicon, and a browser check of each changed view. (#220)
28
+ - Adds to the `williamthorsen` collection the `williamthorsen-visual-design-preferences` rulebook, which prefers a quiet colour scheme, with muted hues on neutral surfaces that each encode a kind or a state, to a monochrome one. (#220)
29
+ - Adds `visual-design-conventions` beside `accessibility-conventions` to the floor that the planning, building, assessment, and review skills and the `usability-assessor` subagent set for an interface, including the rulebook's browser check of each changed view. (#220)
30
+ - Adds the "Consequence at the control" rule to `accessibility-conventions`, which requires the explanation of an action that cannot be undone to be visible at rest, allows a toggletip for one that can be undone, and never accepts a hover-only tooltip as the only explanation. (#221)
31
+ - Opens `accessibility-conventions` with a statement that its rules are floors, and directs agents to aim beyond them by following an established model, as the named-model rule describes. (#221)
32
+ - Extends the helper-text rule of `ui-copy-conventions` to say what an action's consequence explanation states, and counts that explanation toward the copy budget's one line of helper text. (#221)
33
+ - Adds the consequence-at-the-control rule to the skills and the subagent that list the accessibility rules that they apply, among them `review-criteria`, `prepare-prototype-brief`, and the `usability-assessor` per-screen checklist. (#221)
34
+ - Adds a `close` subcommand to `manage-jira-ticket.mjs`, which posts a Markdown body as a comment unless an existing comment opens with the body's first line, then transitions the work item to the status that the new `integrations.jira.done_status` preference names (default `Done`) unless its status category is already done. (#225)
35
+ - Extends the closing post of the spike skills and the close of the triage ticket in `triage-spike-findings` to Jira tickets through `manage-jira-ticket.mjs close`; the guidance previously named only `gh issue close`, which does not close a Jira ticket. (#225)
36
+ - Extends `triage-spike-findings` to run on Jira as well as GitHub, adding a `platform` field to the dispositions record so that the record accepts work item keys such as `PROJ-123`, and creating each Jira ticket under the triage ticket's parent in place of an umbrella. (#227)
37
+ - Makes `analyze-performance`, `assess-code-health`, `assess-usability`, and `investigate-spike` name `triage-spike-findings` as the next step only for a ticket on GitHub or Jira, and name the findings left for disposal by hand for a ticket on any other platform. (#227)
38
+ - Adds a rule to the `williamthorsen-ticketing-preferences` rulebook that splits adding a package to a monorepo into two tickets: an empty scaffold with its documentation and package references that passes the repository's checks on its own, and the package's functionality, blocked by the scaffold. (#229)
39
+ - Changes `create-commit` to record a scaffold that passes the repository's checks and is fully wired as a commit of its own, while a scaffold that a later change fills in still goes into that change. (#229)
40
+ - Requires in the `visual-design-conventions` rulebook that text and elements within a block be start-aligned and a column of numbers end-aligned, limits centring to a viewport-centred dialog, a single-line label in a button or a tag, and an icon in a square control, and adds a matching item to the rulebook's browser check. (#231)
41
+ - Adds the `--umbrella` flag to `create-ticket`, which on Jira creates the ticket at the issue type that the new `integrations.jira.umbrella_issue_type` preference sets, `Epic` by default, so that Jira accepts it as the parent of its child tickets. (#232)
37
42
 
38
43
  ### 🐛 Bug fixes
39
44
 
40
- - Fixes the issue that the `live-worktree-policy` rulebook's example of the `{path}.live` naming gave `~/repos/projects/codeassembly` paths, when the repository is cloned under `~/repos/oss/`. (#157)
41
- - Fixes the issue that `--store` in `kb-retrieve` and `kb-retrieve-events` resolved a name against the user-level `kb.yaml` alone and did not find a store registered only in the project's `kb.yaml`. (#174)
42
- - Fixes the issue that the Split rule in the `next-steps-after-plan` partial never recommended splitting a small plan that touches two or more repositories, because the rule required every plan to be too large for one implement-and-review pass. (#179)
45
+ - Fixes the issue that `assess-ticket` prescribed a plain numbered list of next-step actions, which the ambient option format overrode on every run, by including the shared option format and marking each action at the strength that the evidence behind its verdict supports. (#193)
46
+ - Fixes the issue that `condense-branch` left uncommitted changes in a stash shared by every worktree of the repository, or folded them into the condensed commit through `git add --all` when the stash was skipped. (#195)
47
+ - Fixes the issue that `review-pr` passed its session-context values only to `review-branch`'s steps 4–9, which left out the step that saves the review. (#196)
48
+ - Fixes the issue that `list-implementation-order` listed an umbrella ticket, one that has sub-issues, as a ticket to implement, although its children do its work. (#199)
49
+ - Fixes the issue that `entry-drafter` could write a change's delivery state, such as "takes effect once deployed", into the lede or an entry, which the merge commit keeps after the statement becomes false. (#207)
50
+ - Fixes the issue that `williamthorsen-workflow-preferences` did not stop a session from creating a branch, a worktree, or commits in a repository or ticket other than its own, and that its cross-repo sequencing rule told the session to make the upstream change itself. (#214)
51
+ - Fixes the issue that `create-ticket` reversed a Jira blocked-by link by putting the blocker in the `--out` option of `acli jira workitem link create`, when `--in` is the option that names the blocker. (#227)
52
+ - Fixes the issue that `triage-spike-findings` did not create an umbrella on Jira and parented each new ticket to the triage ticket's parent, by having it create the umbrella on Jira as on GitHub and parent each child ticket to it. (#232)
53
+ - Fixes the issue that `create-ticket` gave a Jira child of a level-0 parent, such as a `Task`, the child's own issue type, which Jira rejects under that parent, and makes `create-ticket` create the child as a subtask at the type that the new `integrations.jira.subtask_issue_type` setting declares (`Subtask` by default). (#233)
54
+
55
+ ### ⚡ Performance
56
+
57
+ - Cuts about 110 words from the shared `AGENTS.md` and the plain-speech partial, both loaded into every session, by removing a redundant example, a sentence of rationale, a repeated repair, and three sentences that describe skills or tickets without directing the agent. (#190)
58
+ - Cuts the prompt-formatting rules that the option-format and action-items guidance already states from the ambient `williamthorsen-collaboration-preferences` rulebook, which shrinks from 11,919 to 6,031 bytes in every session that loads it. (#191)
59
+ - Removes the note "(Reinforces the rule in `AGENTS.md`: intentional redundancy.)" from the option-format directive in the skills that link to the option format, because the rulebook no longer states that rule. (#191)
60
+ - Cuts the `williamthorsen-writing-preferences` rulebook from 9,234 to 7,246 bytes by moving three rarely needed reduced-object-relative cases into `skills/_data/reduced-object-relatives.md`, which the rule links to, and by removing passages that the remaining rules already direct. (#192)
43
61
  <!-- /section:release-notes -->
44
62
 
45
63
  ## Using the library
@@ -5,14 +5,8 @@
5
5
  import path from 'node:path';
6
6
  import process from 'node:process';
7
7
 
8
- import { runValidatePreferences } from '../content/scripts/validate-preferences.mjs';
8
+ import { runValidatePreferencesCommand } from '../content/scripts/validate-preferences.mjs';
9
9
 
10
10
  const programName = path.basename(process.argv[1] ?? 'codeassembly-validate-preferences', '.js');
11
11
 
12
- try {
13
- process.exitCode = await runValidatePreferences(process.argv.slice(2), process.cwd(), programName);
14
- } catch (error) {
15
- const message = error instanceof Error ? error.message : String(error);
16
- process.stderr.write(`${programName}: ${message}\n`);
17
- process.exitCode = 1;
18
- }
12
+ process.exitCode = await runValidatePreferencesCommand(process.argv.slice(2), process.cwd(), programName);
@@ -5,6 +5,7 @@ Before reporting what a change did, read the change back, and repair what you fi
5
5
  - **Claims.** Every statement about the change is read from the diff, not from what you set out to do. A claim that something was left unchanged needs the same evidence as a claim that something changed, and it is the one most often written from memory.
6
6
  - **Reach.** What the edit moved beyond its target: a parallel enumeration of the same list elsewhere, such as a README mirroring the edited source doc; sibling wording invalidated by a rename or re-framing, in a test title, a function header, or a neighboring doc; declaration ordering after an insertion; and adjacent behavior that a changed guard now covers or stops covering.
7
7
  - **Placement.** Each hunk that writes guidance or documentation states a fact only where the fact is defined, such as the config that declares it, the code, its owning README section, or a rulebook, and elsewhere points to that source. A list copied from a config, or a paragraph that restates a rulebook, is a copy that drifts.
8
+ - **Width.** Each comment line in your hunks fits the `max_line_length` that `.editorconfig` sets for its file. Reflow a line that exceeds it, from that line to the end of its paragraph, changing only whitespace. A line that whitespace changes cannot bring within the width, such as one holding a long URL, stays as it is.
8
9
  - **Class.** When the change corrects a defect, the site that you were pointed at is a sample of its class. Audit the other members before reporting, or the next reviewer finds the one that you left.
9
10
 
10
11
  A green gate is not this audit: A suite that passes reports that nothing broke, not that the record which you are about to write is true.
@@ -2,12 +2,12 @@ Speak plainly in practical documentation, in code comments, and in chat. The one
2
2
 
3
3
  Write for a reader who does not share the author's first language, and test each sentence by asking whether that reader parses it on one pass. The test is about structure, not vocabulary: A domain term stays. Use the clearest verb: A file **contains** a section (not "bears" or "carries"), a function **returns** a result (not "the function answers with the result"), a tool **reports** its findings (not "the findings arrive").
4
4
 
5
- A sentence can pass that test and still be **mannered prose**: a figure built for the sentence when a direct statement would do. "a dial worth turning" becomes "a parameter worth varying"; "this point earns its keep" becomes "this point still matters". A figure also adds connotations that the writer did not choose and cannot control. When a literal phrase is available, use it.
5
+ A sentence can pass that test and still be **mannered prose**: a figure built for the sentence when a direct statement would do. "a dial worth turning" becomes "a parameter worth varying". When a literal phrase is available, use it.
6
6
 
7
7
  A verb that fits any subject and object does not state any relation between them. "The file carries a section", "the record carries a version", "the change carries a flag": One verb covers three relations and therefore names none of them. Write the verb that names this one: contains, declares, sets. Such a verb passes both tests above, because it is common rather than built for the sentence; therefore, test for it separately.
8
8
 
9
9
  When a sentence makes data, a file, or a part of a document the subject of an action that an agent or a command performs, the reader cannot tell who acts: "the roots join the recorded ones", "the body reaches the approval gate". A passive that omits an actor that the reader needs hides the actor in the same way. Make the actor the subject. In instructions to an agent, the actor is usually the agent, and the sentence is an imperative: "Show the body to the user at the approval gate." In a document that describes code, the actor is the command or function that acts: "`record` adds the roots to the recorded ones"; an imperative there would give the action to the reader. A subject stays when it performs its verb, animate or not, or when its verb states a relation: A function returns a result, and a file contains a section.
10
10
 
11
- "No" used as a determiner, in any position, leaves the reader unable to tell whether the thing does not exist or exists and fails the condition, and it hides where the absence was observed: "There's no Vercel CLI" was meant as "the Vercel CLI isn't installed on this machine" and read as "the Vercel CLI doesn't exist". As the subject of a relative clause, it also hides the actor and states a claim about every actor when the sentence is about one. Negate the verb, and name the scope in which the absence was observed: "the Vercel CLI isn't installed on this machine", "doesn't publish any build output", "a field not covered by any of the tests", "a condition that the user could not observe". Swapping in another negative quantifier is not a repair, because "a field that none of the tests names" keeps the construction. When existence is itself in question, state it separately: "the package doesn't have any tests". A site stays when it is a fixed idiom, such as "no longer", "no matter", or "no more than"; the pronoun "no one"; a hyphenated compound, such as "no-op"; a verbless label, heading, or table cell, which does not contain a verb to negate; or code, a quotation, or a marked exhibit.
11
+ "No" used as a determiner, in any position, leaves the reader unable to tell whether the thing does not exist or exists and fails the condition, and it hides where the absence was observed: "There's no Vercel CLI" was meant as "the Vercel CLI isn't installed on this machine" and read as "the Vercel CLI doesn't exist". As the subject of a relative clause, it also hides the actor and states a claim about every actor when the sentence is about one. Negate the verb, and name the scope in which the absence was observed: "doesn't publish any build output", "a field not covered by any of the tests", "a condition that the user could not observe". Swapping in another negative quantifier is not a repair, because "a field that none of the tests names" keeps the construction. When existence is itself in question, state it separately: "the package doesn't have any tests". A site stays when it is a fixed idiom, such as "no longer", "no matter", or "no more than"; the pronoun "no one"; a hyphenated compound, such as "no-op"; a verbless label, heading, or table cell, which does not contain a verb to negate; or code, a quotation, or a marked exhibit.
12
12
 
13
13
  This rule takes precedence over the register of the surrounding documents, this guidance included.
@@ -60,9 +60,9 @@ Determine whether the described work has been implemented. The output format dep
60
60
 
61
61
  ### Advisability
62
62
 
63
- Determine whether the ticket should be implemented as written. Synthesize the four facets defined in `{harness_home_dir}/skills/_data/ticket-evaluation.md` (problem reality, scope correctness, solution soundness, title accuracy) against the codebase and ticket text.
63
+ Determine whether the ticket should be implemented as written. Synthesize the five facets defined in `{harness_home_dir}/skills/_data/ticket-evaluation.md` (problem reality, scope correctness, solution soundness, criterion settleability, title accuracy) against the codebase and ticket text.
64
64
 
65
- 1. Apply each facet in turn. Does the underlying observation hold? Is scope right at the appropriate class? Does the proposed solution treat the cause? Does the title accurately describe the work?
65
+ 1. Apply each facet in turn. Does the underlying observation hold? Is scope right at the appropriate class? Does the proposed solution treat the cause? Can the pull request of a code ticket show each criterion to hold or fail at merge? Does the title accurately describe the work?
66
66
  2. Synthesize a verdict from the facet results.
67
67
  3. Emit one prose evidence bullet per concern raised by the facets. Do not prefix a bullet with its facet name. Omit bullets entirely when the verdict is `advisable`.
68
68
 
@@ -70,7 +70,7 @@ Bias toward `advisable`: For a recommendation dimension, false-positive concerns
70
70
 
71
71
  **Verdicts:**
72
72
 
73
- - 🟢 `advisable`: Recommend implementing as written; all four facets pass scrutiny
73
+ - 🟢 `advisable`: Recommend implementing as written; all five facets pass scrutiny
74
74
  - 🟠 `questionable`: Recommend with concerns; one or more facets raise issues warranting human review
75
75
  - 🔴 `inadvisable`: Recommend against implementing as written; rework needed before proceeding
76
76
 
@@ -69,3 +69,9 @@ helpers:
69
69
  out: scripts/check-branch-currency.mjs
70
70
  - entry: ../src/check-prose/cli.ts
71
71
  out: scripts/check-prose.mjs
72
+ - entry: ../src/condense-branch/cli.ts
73
+ out: skills/condense-branch/condense-branch.mjs
74
+ - entry: ../src/write-progress-report/cli.ts
75
+ out: skills/write-progress-report/write-progress-report.mjs
76
+ - entry: ../src/list-gh-progress-items/cli.ts
77
+ out: skills/list-gh-progress-items/list-gh-progress-items.mjs