codeassembly-guidance 0.1.0 → 0.3.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 (165) hide show
  1. package/.meta/changelog.json +984 -0
  2. package/CHANGELOG.md +240 -0
  3. package/README.md +45 -99
  4. package/bin/codeassembly-validate-preferences.js +18 -0
  5. package/content/_partials/README.md +21 -5
  6. package/content/_partials/comment-discipline.md +1 -1
  7. package/content/_partials/diff-audit-checklist.md +1 -0
  8. package/content/_partials/kb-standard-tags.md +7 -0
  9. package/content/_partials/plain-speech-calibration.md +4 -0
  10. package/content/_partials/technical-recommendations.md +1 -0
  11. package/content/codeassembly-content.yaml +17 -1
  12. package/content/collections/all.md +2 -2
  13. package/content/collections/atlassian.md +2 -1
  14. package/content/collections/recommended.md +9 -2
  15. package/content/collections/triage.md +3 -67
  16. package/content/collections/williamthorsen.md +2 -1
  17. package/content/guidance/README.md +1 -1
  18. package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
  19. package/content/guidance/rulebooks/cli-conventions.md +206 -0
  20. package/content/guidance/rulebooks/codeassembly-content-specification.md +50 -10
  21. package/content/guidance/rulebooks/commit-conventions.md +5 -4
  22. package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
  23. package/content/guidance/rulebooks/readme-conventions.md +3 -3
  24. package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
  25. package/content/guidance/rulebooks/shell-conventions.md +17 -23
  26. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  27. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +18 -12
  28. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
  29. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
  30. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
  31. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
  32. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
  33. package/content/guidance/shared/AGENTS.md +39 -4
  34. package/content/scripts/README.md +5 -2
  35. package/content/scripts/check-branch-currency.mjs +11 -0
  36. package/content/scripts/check-prose.mjs +171 -0
  37. package/content/scripts/describe-change.mjs +98 -98
  38. package/content/scripts/manage-jira-ticket.mjs +99 -94
  39. package/content/scripts/resolve-frontmatter.sh +1 -1
  40. package/content/scripts/resolve-review-run.mjs +9 -9
  41. package/content/scripts/select-lede-exemplars.mjs +87 -87
  42. package/content/scripts/validate-preferences.mjs +146 -0
  43. package/content/skills/_data/action-items.md +2 -0
  44. package/content/skills/_data/artifact-conventions.md +64 -16
  45. package/content/skills/_data/branch-currency.md +36 -0
  46. package/content/skills/_data/change-record.md +2 -2
  47. package/content/skills/_data/complexity-classification.md +1 -1
  48. package/content/skills/_data/design-priorities.md +15 -4
  49. package/content/skills/_data/project-stage.md +32 -0
  50. package/content/skills/_data/recommendation-gradient.md +9 -7
  51. package/content/skills/_data/scope-and-deferral.md +1 -1
  52. package/content/skills/_data/spike-conventions.md +21 -6
  53. package/content/skills/_data/ticket-evaluation.md +2 -2
  54. package/content/skills/_data/ticket-source-resolution.md +36 -3
  55. package/content/skills/_data/title-templates.md +22 -12
  56. package/content/skills/_partials/action-items.md +2 -2
  57. package/content/skills/_partials/apply-guidance-edits.md +5 -0
  58. package/content/skills/_partials/commit-title-rendering.md +1 -1
  59. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  60. package/content/skills/_partials/next-steps-after-plan.md +11 -11
  61. package/content/skills/_partials/option-format.md +18 -17
  62. package/content/skills/_partials/plan-template.md +7 -5
  63. package/content/skills/_partials/split-ticket-compose.md +1 -1
  64. package/content/skills/_partials/split-ticket-create.md +1 -1
  65. package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
  66. package/content/skills/_partials/ticket-composition.md +40 -0
  67. package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
  68. package/content/skills/_partials/ticket-skeleton.md +15 -1
  69. package/content/skills/add-change-record/SKILL.md +2 -2
  70. package/content/skills/align-ticket-with-implementation/SKILL.md +3 -7
  71. package/content/skills/anti-patterns/SKILL.md +1 -1
  72. package/content/skills/assess-code-health/SKILL.md +127 -0
  73. package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
  74. package/content/skills/assess-usability/SKILL.md +98 -0
  75. package/content/skills/capture-event/SKILL.md +4 -2
  76. package/content/skills/capture-event/capture-event.mjs +89 -89
  77. package/content/skills/capture-feedback/SKILL.md +1 -1
  78. package/content/skills/capture-lede-decision/SKILL.md +4 -4
  79. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
  80. package/content/skills/collaborate/SKILL.md +3 -3
  81. package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
  82. package/content/skills/create-commit/SKILL.md +1 -1
  83. package/content/skills/create-gh-pr/SKILL.md +28 -10
  84. package/content/skills/create-pr/SKILL.md +7 -6
  85. package/content/skills/create-ticket/SKILL.md +64 -23
  86. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  87. package/content/skills/derive-session-context/derive-session-context.mjs +83 -82
  88. package/content/skills/design-and-plan/SKILL.md +17 -18
  89. package/content/skills/groom-backlog/SKILL.md +8 -6
  90. package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
  91. package/content/skills/implement-plan/SKILL.md +27 -23
  92. package/content/skills/index-prototypes/SKILL.md +86 -31
  93. package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
  94. package/content/skills/kb-add/SKILL.md +4 -1
  95. package/content/skills/kb-add/kb-add.mjs +128 -128
  96. package/content/skills/kb-curate/SKILL.md +9 -7
  97. package/content/skills/kb-curate/kb-curate.mjs +103 -103
  98. package/content/skills/kb-edit/SKILL.md +5 -3
  99. package/content/skills/kb-edit/kb-edit.mjs +94 -94
  100. package/content/skills/kb-retrieve/kb-retrieve.mjs +86 -85
  101. package/content/skills/kb-retrieve-events/SKILL.md +20 -11
  102. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +86 -85
  103. package/content/skills/kb-update-events/SKILL.md +10 -7
  104. package/content/skills/kb-update-events/kb-update-events.mjs +110 -109
  105. package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
  106. package/content/skills/merge-bb-pr/SKILL.md +1 -1
  107. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
  108. package/content/skills/merge-pr/SKILL.md +11 -11
  109. package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
  110. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
  111. package/content/skills/plan/SKILL.md +2 -2
  112. package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
  113. package/content/skills/pull-from-backlog/SKILL.md +3 -3
  114. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
  115. package/content/skills/refine-guidance/SKILL.md +97 -0
  116. package/content/skills/refine-plan/SKILL.md +7 -3
  117. package/content/skills/refine-prototype/SKILL.md +113 -0
  118. package/content/skills/respond-to-review/SKILL.md +1 -1
  119. package/content/skills/review-bb-pr/SKILL.md +1 -1
  120. package/content/skills/review-branch/SKILL.md +354 -3
  121. package/content/skills/review-criteria/SKILL.md +36 -3
  122. package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
  123. package/content/skills/revise-comments/SKILL.md +38 -5
  124. package/content/skills/revise-prose/SKILL.md +1 -1
  125. package/content/skills/revise-prose/revise-prose.mjs +119 -119
  126. package/content/skills/save-artifact/SKILL.md +3 -1
  127. package/content/skills/streamline-guidance/SKILL.md +11 -16
  128. package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
  129. package/content/skills/summarize-change/SKILL.md +23 -14
  130. package/content/skills/testing-conventions/SKILL.md +81 -8
  131. package/content/skills/triage-feedback/SKILL.md +150 -0
  132. package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
  133. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  134. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +73 -0
  135. package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
  136. package/content/skills/update-jira-ticket/SKILL.md +20 -8
  137. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
  138. package/content/skills/update-project-guidance/SKILL.md +12 -12
  139. package/content/subagents/_data/claude.yaml +6 -0
  140. package/content/subagents/_data/rovo.yaml +12 -2
  141. package/content/subagents/canary.md +2 -1
  142. package/content/subagents/code-health-assessor.md +98 -0
  143. package/content/subagents/disposition-challenger.md +78 -0
  144. package/content/subagents/entry-drafter.md +14 -10
  145. package/content/subagents/feedback-triage-challenger.md +81 -0
  146. package/content/subagents/handoff-reviewer.md +2 -2
  147. package/content/subagents/lesson-clusterer.md +68 -0
  148. package/content/subagents/plan-reviewer.md +1 -1
  149. package/content/subagents/prose-reviser.md +4 -2
  150. package/content/subagents/ticket-assessor.md +9 -6
  151. package/content/subagents/usability-assessor.md +157 -0
  152. package/package.json +21 -17
  153. package/schemas/preferences.v1.json +50 -7
  154. package/schemas/work-types.v1.json +1 -1
  155. package/content/_partials/code-descriptions.md +0 -4
  156. package/content/_partials/code-style.md +0 -7
  157. package/content/_partials/live-repo-writes.md +0 -13
  158. package/content/_partials/reduced-object-relative.md +0 -28
  159. package/content/_partials/test-structure-audit-checklist.md +0 -7
  160. package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
  161. package/content/skills/_partials/next-steps-after-review.md +0 -350
  162. package/content/skills/_partials/ticket-concision.md +0 -18
  163. package/content/skills/_partials/ticket-placement.md +0 -14
  164. package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
  165. package/content/skills/testing-conventions/mistakes.md +0 -1
@@ -50,7 +50,7 @@ The bundle does not have a shebang, so the `node` prefix is required. Each subco
50
50
  ### What stops a run and what only warns
51
51
 
52
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 carries 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).
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
54
  - Malformed YAML in a preferences file stops every subcommand that reads the templates, naming the file.
55
55
  - Malformed YAML in `pnpm-workspace.yaml` or in the project preferences file stops `resolve-scopes`, naming the file.
56
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).
@@ -58,6 +58,14 @@ The bundle does not have a shebang, so the `node` prefix is required. Each subco
58
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
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
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.
61
69
 
62
70
  ## `render-titles`
63
71
 
@@ -72,7 +80,7 @@ node {harness_home_dir}/scripts/describe-change.mjs render-titles \
72
80
  --pr-number "{pr_number}"
73
81
  ```
74
82
 
75
- Its flags are `--title`, `--scope`, `--type`, `--breaking`, `--ticket-ref`, and `--pr-number`, 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.
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.
76
84
 
77
85
  Output is JSON:
78
86
 
@@ -163,7 +171,7 @@ node {harness_home_dir}/scripts/describe-change.mjs consolidate-branch --base or
163
171
 
164
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).
165
173
 
166
- **The consolidated record ranks; it does not count.** 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.
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.
167
175
 
168
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.
169
177
 
@@ -173,7 +181,7 @@ The run refuses outright if the taxonomy cannot be read, since the entries have
173
181
 
174
182
  ## `consolidate-entries`
175
183
 
176
- `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 holding a top-level list of entry mappings, in the shape that `entry-drafter` returns.
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.
177
185
 
178
186
  ```bash
179
187
  node {harness_home_dir}/scripts/describe-change.mjs consolidate-entries --entries-file entries-20260920-223418Z.yaml
@@ -191,14 +199,16 @@ node {harness_home_dir}/scripts/describe-change.mjs consolidate-entries --entrie
191
199
  ```
192
200
 
193
201
  ```json
194
- { "consolidated_record": { "breaking": false, "scope": "agents", "type": "feat" } }
202
+ { "consolidated_record": { "breaking": false, "scope": "agents", "type": "feat" }, "defects": [] }
195
203
  ```
196
204
 
197
- **Each entry expands to one record per scope**, and an entry that does not name a scope expands to one record without a scope, which keeps a change touching nothing scoped rankable on 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.
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.
198
206
 
199
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.
200
208
 
201
- **The entries arrive in a file rather than through flags** because `text` is arbitrary prose containing backticks and quotes, which a shell argument would expand or truncate.
209
+ **`defects` lists the entry defects that [`resolve-merge`](#resolve-merge) reports for the same entries**: an `undeclared-type` or `policy-violation` whose `entry` names the entry's 0-based index, in entry order, or `[]` when every entry passes. The run reports them and continues.
210
+
211
+ **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.
202
212
 
203
213
  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.
204
214
 
@@ -315,7 +325,7 @@ The output is JSON whose `details` contains the body, without the `## Details` h
315
325
  - **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.
316
326
  - **Empty list.** An empty list yields an empty `details`, and the caller omits the section.
317
327
 
318
- The run refuses an entry whose `type` the taxonomy does not declare as a key or an alias, `feat!` included, since `breaking` carries 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.
328
+ 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.
319
329
 
320
330
  ## `resolve-merge`
321
331
 
@@ -505,11 +515,11 @@ project:
505
515
 
506
516
  **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.
507
517
 
508
- **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` holds the derived vocabulary to the `scope:` labels that `.config/release-kit.config.ts` declares. A change to the workspace discovery rule belongs upstream, in nmr.
518
+ **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.
509
519
 
510
520
  ## `resolve-labels`
511
521
 
512
- `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. Without `--body-file`, as for a ticket that does not have a body yet, the run labels the record alone.
522
+ `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.
513
523
 
514
524
  ```bash
515
525
  node {harness_home_dir}/scripts/describe-change.mjs resolve-labels \
@@ -523,7 +533,7 @@ node {harness_home_dir}/scripts/describe-change.mjs resolve-labels \
523
533
 
524
534
  **`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.
525
535
 
526
- **A key that the map does not name, and a scope of `*`, do not add a label.** 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.
536
+ **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.
527
537
 
528
538
  **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.
529
539
 
@@ -544,7 +554,7 @@ A template that omits `{title}` produces a title without the bare title text: Th
544
554
 
545
555
  A `[...]` group renders verbatim when every token directly inside it resolves non-empty. When one is empty, the whole group drops, literals included.
546
556
 
547
- 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 group decides. 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.
557
+ 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.
548
558
 
549
559
  `{breaking}` never decides a group. A non-breaking change would otherwise drop the very prefix that contains the marker.
550
560
 
@@ -1,6 +1,6 @@
1
- **Close the turn with an action-items block.** Before sending, sweep the draft for anything that invites a response: A soft offer ("let me know if", "say the word and I will", "worth knowing", "I can also") is an ask, and leaving it in the narrative is how asks get missed. A check that a command, a test, or a browser could settle is run, not asked, and a command for the developer to run is a handoff. Prose may discuss; only the block may ask. Move every ask into one labelled block at the end of the response, stated as the concrete action and punctuated as the question that it is. A turn without an ask does not have a block. When this skill defines its own canonical block for asks (a next-steps menu, an action menu, a finding-keyed question list), that block takes precedence: Add the ad-hoc ask to it, keeping the block's own identifiers, and never close a turn with two competing blocks.
1
+ **Close the turn with an action-items block.** Before sending, sweep the draft for anything that invites a response: A soft offer ("let me know if", "say the word and I will", "worth knowing", "I can also") is an ask, and leaving it in the narrative is how asks get missed. Run a check that a command, a test, or a browser could settle rather than ask for it; a command for the developer to run is a handoff. Prose may discuss; only the block may ask. Move every ask into one labelled block at the end of the response, stated as the concrete action and punctuated as the question that it is. Do not add a block to a turn without an ask. When this skill defines its own canonical block for asks (a next-steps menu, an action menu, a finding-keyed question list), use that block: Add the ad-hoc ask to it, keeping the block's own identifiers, and never close a turn with two competing blocks.
2
2
 
3
- Prefix with `A` an action that you propose to take (a "yes" makes you act) and with `Q` information or a judgment that you need (a "yes" only informs you). Number each so that the user can answer the whole block in one line. A non-ask, such as a status note, is neither and stays in the prose; prefix and marker always agree. A single-item block does not prefix its item.
3
+ Prefix with `A` an action that you propose to take (a "yes" makes you act) and with `Q` information or a judgment that you need (a "yes" only informs you). Number each so that the user can answer the whole block in one line. Leave a non-ask, such as a status note, in the prose without a prefix, and keep each prefix in agreement with its marker. Do not prefix the item of a single-item block.
4
4
 
5
5
  ```
6
6
  ---
@@ -0,0 +1,5 @@
1
+ 1. Apply each approved edit with {tool:Edit}, phrase to phrase. Stop at the first edit that does not match, and report which edit diverged.
2
+ 2. Bump the `version` of each rulebook for which an edit changed what the rulebook asks: a rulebook that an edit changed, and a rulebook that includes an edited file. Find the second kind by searching the rulebooks for an include directive that names the edited file.
3
+ 3. Run the project's quality gate as {skill:development-workflows} resolves it.
4
+ - If it fails only on a version pin or content hash that records a file edited by this run, apply the remedy that its failure message names: Update the pin to the version bumped above, or update the pin alone if the edits did not change what the rulebook asks.
5
+ - If it fails on anything else that an edit caused, restore that edit's text, report the edit, and run the gate again. If the restored edit was the only edit to change what its rulebook asks, also restore that rulebook's `version`, and its pin if this step updated it.
@@ -11,4 +11,4 @@ Pass `--ticket-ref` from the bundled session-context deriver so that a project w
11
11
 
12
12
  Parse the output with a JSON parser (`python3` above; `jq -r '.commit_title'` if `jq` is available) rather than `grep` or `cut`: A rendered title may contain backslash-escaped double quotes, which a regex extractor silently truncates.
13
13
 
14
- The pipeline prints the rendered title. Read it from the command's output and use it verbatim as the commit title, which already contains the rendered prefix, per the configured `commit.title_format`, and the bare title text. Assigning the parse instead prints nothing, and a shell variable does not survive to the commit call, so the title must be carried forward as literal text into the message file. If the script is not found, fall back to the bare `{title}`.
14
+ The pipeline prints the rendered title. Read it from the command's output and use it verbatim as the commit title, which already contains the rendered prefix, per the configured `commit.title_format`, and the bare title text. Assigning the parse instead prints nothing, and a shell variable does not survive to the commit call, so copy the title as literal text into the message file. If the script is not found, or the pipeline prints an empty title because `commit.title_format` is empty or unset, use the bare `{title}`.
@@ -0,0 +1 @@
1
+ **Flatten task lists for Markdown and HTML clients.** Before submitting a Jira description or comment through a `contentFormat` tool or an HTML tool, on creation and update alike, convert task-list syntax (`- [ ]` / `- [x]`) to plain `-` bullets. Neither Jira conversion maps it to task items: The brackets are escaped, so each line persists as a bullet reading `\[ \] ...`. The `acli` path is the exception and keeps its checkboxes, because `manage-jira-ticket.mjs` converts task-list syntax to native `taskList` / `taskItem` nodes.
@@ -12,28 +12,28 @@
12
12
 
13
13
  Present all three options as a numbered list per [option format](#option-format). Each option has a strength marker (■■■/■■□/■□□/□□□); the recommendation rules below determine which option takes the strongest marker. Pros and cons are omitted by default; add a `➕` or `➖` line only when the specific plan presents a tradeoff that survives the option-format tests bearing on which option fits (e.g., "the schema change ships and is verifiable before the reader that consumes it," "every task follows the sibling table's established pattern"). Generic option properties ("structured review pass," "longer wall time") are noise and must be omitted. Include all known paths (plan, ticket) in each option line; omit paths that are not available in the current context. Use `~/`-relative paths when possible and absolute paths otherwise. Every line subordinate to an option (invocation guidance as much as a pro or con) is a nested list item, never a whitespace-indented continuation.
14
14
 
15
- **The ticket and plan are the complete handoff.** Every option assumes that a fresh session acts on the saved artifacts alone, whether or not one does, so nothing that only this session holds distinguishes one option from another. A pro or con never cites the conversation, session-held context, or what is "already in context", and neither does the invocation guidance of any option, the spike's 🔬 Investigate included. When a fact that an option needs exists only in the session, the artifact is incomplete: Add the fact to the ticket or the plan before rendering the menu, rather than citing the session.
15
+ **The ticket and plan are the complete handoff.** Every option assumes that a fresh session acts on the saved artifacts alone, whether or not one does, so nothing that only this session knows distinguishes one option from another. A pro or con never cites the conversation, session-held context, or what is "already in context", and neither does the invocation guidance of any option, the spike's 🔬 Investigate included. When a fact that an option needs exists only in the session, the artifact is incomplete: Add the fact to the ticket or the plan before rendering the menu, rather than citing the session.
16
16
 
17
17
  **One `➕` line is mandatory rather than omitted.** When Refine plan is the selected option, it must include a `➕` line naming the specific unsettled decision that the pass would raise (rule 1). The line names an open decision, never a reassurance about work already done: "a refine pass is the cheap way to find out whether I missed something" is the shape that this requirement exists to forbid. When Split the ticket is the selected option, it must include a `➕` line naming the plan's size and the pieces (rule 2). Selecting either without its line is a defect: If the line cannot be written, the rule did not match and the cascade continues.
18
18
 
19
- **Spike plans.** A spike plan has `## Investigation steps` rather than `## Tasks` (see [spike conventions](../_data/spike-conventions.md)). It is carried out to produce findings rather than implemented to produce a diff, and `implement-plan` reads only the feature shape. Render option 3 as 🔬 Investigate, without invoking a skill; the agent works the investigation steps directly. Option 1 renders unchanged. Option 2 renders at □□□ with the `➖` that a spike produces findings rather than pieces that ship. In the recommendation rules below, rule 2 never matches on a spike plan, so Investigate is the fallthrough whenever rule 1 does not match.
19
+ **Spike plans.** A spike plan has `## Investigation steps` rather than `## Tasks` (see [spike conventions](../_data/spike-conventions.md)). It is carried out to produce findings rather than implemented to produce a diff, and `implement-plan` reads only the feature shape. Render option 3 as 🔬 Investigate, without invoking a skill; the agent works the investigation steps directly and ends the run with the plan's `## Deliverable`, which includes offering the [closing post](../_data/spike-conventions.md#closing-post) on the ticket and making it on consent. Option 1 renders unchanged. Option 2 renders at □□□ with the `➖` that a spike produces findings rather than pieces that ship. In the recommendation rules below, rule 2 never matches on a spike plan, so Investigate is the fallthrough whenever rule 1 does not match.
20
20
 
21
21
  Options that invoke a skill include context-clearing guidance:
22
22
 
23
- - **Refine plan**: Prepend "Clear context and use..." because the plan artifact is self-contained; prior conversation wastes tokens and can introduce bias.
23
+ - **Refine plan**: Prepend "Clear context, then..." because the plan artifact is self-contained; prior conversation wastes tokens and can introduce bias.
24
24
  - **Split the ticket**: No "Clear context" prefix, and no pasted invocation line; the split runs in this session because the library doesn't have a skill for it, and it cuts the pieces from the saved plan. See [Splitting the ticket](#splitting-the-ticket).
25
- - **Implement**: No "Clear context" prefix. The ticket and plan are self-contained, so `implement-plan` works the same in this session or in a fresh one, and clearing gains nothing: Unlike a refine or review pass, implementation is not harmed by sharing the planner's view. The user can also paste the same line into a fresh session or the other harness, in which the skill re-resolves the plan and ticket from the environment.
25
+ - **Implement**: No "Clear context" prefix. The ticket and plan are self-contained, so `implement-plan` works the same in this session or in a fresh one, and clearing gains nothing: Unlike a refine or review pass, implementation is not harmed by sharing the planner's view. The user can also paste the same line into a fresh session, or into the other harness with its own skill sigil, in which the skill re-resolves the plan and ticket from the environment.
26
26
 
27
27
  Example (rendered for the default case, in which the recommendation rules below select Implement):
28
28
 
29
29
  ```
30
30
  Next steps:
31
31
  1. 🧠 ■□□ Refine plan:
32
- - Clear context and use the `refine-plan` skill with plan: {plan_path}, ticket: {ticket_source}
32
+ - Clear context, then {skill?:refine-plan} with plan: {plan_path}, ticket: {ticket_source}
33
33
  2. ✂️ ■□□ Split the ticket:
34
34
  - Selection runs the split in this session
35
35
  3. 🚀 ■■□ Implement:
36
- - Use the `implement-plan` skill with plan: {plan_path}, ticket: {ticket_source}
36
+ - {skill?:implement-plan} with plan: {plan_path}, ticket: {ticket_source}
37
37
  ```
38
38
 
39
39
  Skill names for each option:
@@ -64,9 +64,9 @@ Select the recommended option by checking these rules in order and stopping at t
64
64
 
65
65
  When rule 1 matches, the rendered option must name that decision on a `➕` line. Being unable to write the line means rule 1 did not match.
66
66
 
67
- 2. **Split the ticket**: Recommend only when the plan is too large for one implement-and-review pass, and it holds two or more pieces that each ship and can be verified on their own. Both halves are required: Too large without a seam is not a match, and a seam in a plan that one pass would carry is not one either.
67
+ 2. **Split the ticket**: Recommend only when the plan is too large for one implement-and-review pass, and it contains two or more pieces that can each be merged and verified on their own. Both halves are required: Too large without a seam is not a match, and a seam in a plan that one pass would cover is not one either.
68
68
 
69
- A piece earns a ticket when it ships and can be verified on its own, not when it looks large enough to deserve one. The `➕` line names the size and the pieces, each with the tasks that it takes: `➕ eleven tasks across three packages, and two pieces ship on their own: the schema change (tasks 1–4), then the reader that consumes it (tasks 5–11)`.
69
+ A piece gets its own ticket when it can be merged and verified on its own, not when it looks large enough to deserve one. The `➕` line names the size and the pieces, each with the tasks that it takes: `➕ eleven tasks across three packages, and two pieces ship on their own: the schema change (tasks 1–4), then the reader that consumes it (tasks 5–11)`.
70
70
 
71
71
  Structural properties (new module boundaries, changed interfaces, several packages) make a plan _more likely_ to be too large. They are evidence to weigh, and none of them matches rule 2 on its own.
72
72
 
@@ -74,11 +74,11 @@ Select the recommended option by checking these rules in order and stopping at t
74
74
 
75
75
  3. **Implement**: All other cases (default), whatever the number of modules or packages that the plan touches. `implement-plan`'s closing menu re-decides the review depth from the realized diff, and it offers a split when the diff proves too large for one review pass, so a plan sent here is not committed to a single pull request.
76
76
 
77
- When the work is trivial enough that a review pass would catch nothing meaningful ([complexity levels 1–2](../_data/complexity-classification.md): a typo fix, an unused-import removal, a single-file mechanical rename), add a `➕` line noting that the follow-up review can be skipped at `implement-plan`'s closing menu. That menu decides the review from the diff that the implementation actually produced, so a plan-time triviality read is a hint to it rather than a commitment.
77
+ When the work is trivial enough that a review pass would catch nothing meaningful ([complexity levels 1–2](../_data/complexity-classification.md): a typo fix, an unused-import removal, a single-file mechanical rename), add a `➕` line noting that the follow-up review can be skipped at `implement-plan`'s closing menu. Because that menu decides the review from the diff that the implementation actually produced, a plan-time triviality read is a hint to it rather than a commitment.
78
78
 
79
79
  #### Marker strengths
80
80
 
81
- The selected option's marker follows how cleanly its rule matched: ■■■ when the rule's test is met squarely and the alternatives are worse on the criteria that decided it, ■■□ when the fit is good but an alternative stays defensible, ■□□ when little separates the options. Rule 3 is the cascade's fallthrough rather than a positive match, so its marker follows how squarely rules 1 and 2 failed: ■■■ when neither came close, ■■□ when one stayed defensible. The unselected options take ■□□ by default, and □□□ when one has a clear drawback in the current context.
81
+ The selected option's marker follows how cleanly its rule matched: ■■■ when the rule's test is met squarely and the alternatives are worse on the criteria that decided it, ■■□ when the fit is good but an alternative stays defensible, ■□□ when little separates the options. Because rule 3 is the cascade's fallthrough rather than a positive match, its marker follows how squarely rules 1 and 2 failed: ■■■ when neither came close, ■■□ when one stayed defensible. The unselected options take ■□□ by default, and □□□ when one has a clear drawback in the current context.
82
82
 
83
83
  Each skill supplies its own recommendation context (e.g., whether the plan was developed interactively, whether a review just completed). That context applies to rule 1's settled/unsettled test.
84
84
 
@@ -96,4 +96,4 @@ Each skill supplies its own recommendation context (e.g., whether the plan was d
96
96
 
97
97
  <!-- include: split-launch-prompts.md / -->
98
98
 
99
- See [`scope-and-deferral.md`](../_data/scope-and-deferral.md) for the related decision on whether a finding warrants its own ticket. That decision (do now / batch later / separate ticket) is about work that comes up alongside the plan; rule 2 is about the plan's own work, and its seam test comes from the ticketing preferences: A piece earns a ticket when it ships and can be verified on its own.
99
+ See [`scope-and-deferral.md`](../_data/scope-and-deferral.md) for the related decision on whether a finding warrants its own ticket. That decision (do now / batch later / separate ticket) is about work that comes up alongside the plan; rule 2 is about the plan's own work, and its seam test comes from the ticketing preferences: A piece gets its own ticket when it can be merged and verified on its own.
@@ -1,10 +1,10 @@
1
1
  ## Option format
2
2
 
3
- **Earn the menu before rendering it.** Mark the options first, check the leader as "Check the leader before rendering" below states, then read the markers: Render the menu only when the two strongest options are both ■■□, when the list is unmarked, or when the decision is in the gated class below. Every other field is decided: State the decision in one line with its reason, record it, and proceed. An all-■□□ field is decided too. An unmarked list is a pure-preference call, and a preference is in the gated class. The rejected alternative belongs in a clause ("X rather than Y, because Z"), never as a numbered option awaiting selection.
3
+ **Confirm that the menu is needed before rendering it.** Mark the options first, check the leader as "Check the leader before rendering" below states, then read the markers: Render the menu only when the two strongest options are both ■■□, when the list is unmarked, or when the decision is in the gated class below. Decide every other field: State the decision in one line with its reason, record it, and proceed. Decide an all-■□□ field too. An unmarked list is a pure-preference call, and a preference is in the gated class. The rejected alternative belongs in a clause ("X rather than Y, because Z"), never as a numbered option awaiting selection.
4
4
 
5
5
  A determination that has one right answer under a governing document, such as a change's work type under the work-type test, is not a fork. Resolve doubt about which answer the test yields by applying the test and picking: Two options marked ■■□ are a fork between acceptable options, not doubt about a fact. The developer holds less of the evidence than the agent, so handing the doubt back produces a worse-informed answer.
6
6
 
7
- The gated class is closed. These decisions are asked whatever the markers say:
7
+ The gated class is closed. Ask about these decisions whatever the markers say:
8
8
 
9
9
  - the shape of a public API or a contract
10
10
  - remote shared state: a ticket edit, a push, a merge, the creation of a branch or a ticket
@@ -12,13 +12,13 @@ The gated class is closed. These decisions are asked whatever the markers say:
12
12
  - spend or budget
13
13
  - a preference for which you do not hold any evidence
14
14
 
15
- Everything else is the agent's call by default. A gated action is not decided in the agent's voice: The developer authorizes it; recommend, build on the recommendation provisionally, and ask at the checkpoint. Building on it means doing the work that depends on the answer; the gated action itself waits for the developer's authorization. A templated next-steps menu is in the class, because what to do next is a preference about the developer's time, for which you do not hold any evidence. Verification is never in the gated class: A check that a command, a test, or a browser could settle is the agent's to run.
15
+ Decide everything else yourself by default. Never decide a gated action in your own voice: The developer authorizes it; recommend, build on the recommendation provisionally, and ask at the checkpoint. Building on it means doing the work that depends on the answer; hold the gated action itself until the developer authorizes it. A templated next-steps menu is in the class, because what to do next is a preference about the developer's time, for which you do not hold any evidence. Verification is never in the gated class: Run a check that a command, a test, or a browser could settle.
16
16
 
17
- **Proceed provisionally.** Do everything that does not depend on an answer first, and raise an ask only where the work is blocked or at the skill's checkpoint. When a gated decision has a strong recommendation, build on it, mark it provisional in the record, and ask at the checkpoint; revise if overruled. A skill without a phase structure treats its own approval gate, or the end of its work, as the checkpoint.
17
+ **Proceed provisionally.** Do everything that does not depend on an answer first, and raise an ask only when the work is blocked or at the skill's checkpoint. When a gated decision has a strong recommendation, build on it, mark it 🔲 as "Record what you did not ask" states, and ask at the checkpoint; revise if overruled. In a skill without a phase structure, treat the skill's own approval gate, or the end of its work, as the checkpoint.
18
18
 
19
- **Batch, never stream.** Asks that survive the gate collect into one review at the checkpoint, not one per turn.
19
+ **Batch, never stream.** Collect the asks that survive the gate into one review at the checkpoint, not one per turn.
20
20
 
21
- **Record what you did not ask.** Write every decision that the gate let you take into the plan's `## Decisions taken` section, with a one-line reason, marked `(provisional)` when it awaits the checkpoint; when the work does not have a plan, write it into the turn's summary. Recording is mandatory: A silent decision is worse than an ask.
21
+ **Record what you did not ask.** Write every decision that the gate let you take into the plan's `## Decisions taken` section, with a one-line reason; when the work does not have a plan, write it into the turn's summary. Always record: A silent decision is worse than an ask. Start each line that states a decision awaiting the checkpoint with 🔲, wherever you state it: in the record, and in a turn's narrative, such as a checkpoint summary or a list of decisions. The marker lets the developer find what they may overrule without reading every line. Drop it once the developer approves the checkpoint at which the decision was presented.
22
22
 
23
23
  **Never rank the options by your own elapsed time, round trips, or effort.** You measure these costs yourself, and that measure counts the user's context switch and review cycles as nothing. Measuring one does not make the call yours, and a more accurate measurement still cannot rank the options.
24
24
 
@@ -39,33 +39,34 @@ Render every option-style question in this form: any numbered list of 2 or more
39
39
  | ■□□ | weakly recommended | A slight edge; mostly preference. |
40
40
  | □□□ | not recommended | Clear drawbacks; included for completeness or to rule out explicitly. |
41
41
 
42
- Marking is all-or-none: Once any option has a marker, every option has one. Without a preference (a pure taste call), omit markers from every option and don't explain the omission; the absence is the signal. Mark at the strength that you actually hold: A marker that reads the same whatever the analysis found does not convey any information, and the reader must do all the work of telling a real choice from a formality. Render markers as plain text, never inside backticks; backticks shrink the glyphs and hurt readability.
42
+ Marking is all-or-none: Once any option has a marker, give every option one. Without a preference (a pure taste call), omit markers from every option and don't explain the omission; the absence is the signal. Mark at the strength that you actually hold: A marker that reads the same whatever the analysis found does not convey any information, and the reader must do all the work of telling a real choice from a formality. Render markers as plain text, never inside backticks; backticks shrink the glyphs and hurt readability.
43
43
 
44
- **Format each option** as marker, then title, then a colon. Each pro (`➕`) and con (`➖`) is a nested list item beneath its option, without terminal punctuation. Apply this even when an option has only one pro or con. Lead with the strongest argument.
44
+ **Format each option** as marker, then title, then a colon. Make each pro (`➕`) and con (`➖`) a nested list item beneath its option, without terminal punctuation. Apply this even when an option has only one pro or con. Lead with the strongest argument.
45
45
 
46
- Every line subordinate to an option (a pro, a con, invocation guidance) is a nested list item, never a whitespace-indented continuation. Indentation by spaces, ASCII or non-breaking alike, does not survive terminal rendering: The lines collapse to the left margin, and the reader cannot tell which reason belongs to which option. Markdown structure survives; whitespace does not.
46
+ Make every line subordinate to an option (a pro, a con, invocation guidance) a nested list item, never a whitespace-indented continuation. Indentation by spaces, ASCII or non-breaking alike, does not survive terminal rendering: The lines collapse to the left margin, and the reader cannot tell which reason belongs to which option. Markdown structure survives; whitespace does not.
47
47
 
48
- Nesting stops at one level. An option never contains sub-options, and a pro never contains a sub-pro. Terminal rendering stops being reliable at deeper nesting, so this contract is written never to need it.
48
+ Stop nesting at one level: Never put a sub-option in an option or a sub-pro in a pro. Terminal rendering stops being reliable at deeper nesting, so this contract is written never to need it.
49
49
 
50
50
  **Write only bullets that are real.** Bullets report the weight of each option, not a balance between the options: When the options differ in quality, an uneven menu is the accurate one, and a menu that looks balanced misreports the analysis. A `➕` or `➖` asserts that the reader should weigh it, and bullets render at equal visual weight. A manufactured one reads exactly like a load-bearing one, and it takes a round trip to discover that it was empty. Seven tests:
51
51
 
52
52
  - **Falsifiability.** A `➖` must be false for at least one other option on the menu, and a `➕` likewise. Anything that would still be true if this were the only option is a mechanic of carrying it out rather than a tradeoff; it belongs on the invocation line or nowhere.
53
53
  - **Decision weight.** Would a reader who believed this bullet choose differently? Bookkeeping, mechanically-implied, and trivially-reversible consequences (a doc line to update, a criterion to reword, a rename to propagate) are real, specific, and decision-irrelevant. Restatements of an option's inherent properties ("longer wall time", "structured review pass", "ships faster") are one instance of the same failure.
54
54
  - **Session context.** Cut a bullet that cites the conversation, what the session holds, or what is "already in context". Every handoff goes through a saved artifact, so session context does not distinguish one option from another, and a bullet that rests on it tells the reader that the artifact is incomplete. When the bullet is true, the artifact has a gap: Add the fact to the artifact rather than citing the session.
55
- - **Consequence.** A `➖` states what breaks or what it costs, and for whom, concretely enough that the reader can weigh it without investigating. Cut a con that cannot be stated that way.
55
+ - **Consequence.** State in a `➖` what breaks or what it costs, and for whom, concretely enough that the reader can weigh it without investigating. Cut a con that cannot be stated that way.
56
56
  - **The qualifier tell.** A bullet undercut by its own qualifier ("negligible", "inert", "harmless") is filler. The only repair is to cut the bullet: Deleting the qualifier leaves the same minor con, now looking weighty.
57
57
  - **One tradeoff, stated once.** When one option's `➕` restates another option's `➖`, the two options are the sides of one tradeoff. State it once, in a line above the list, rather than as bullets split between the options, which the reader counts as separate reasons.
58
58
  - **Check before you hedge.** If a cheap check would settle whether a con is real, run the check. Presenting the uncertainty as a bullet transfers the check to the user.
59
59
 
60
- Asymmetry is a report, not a defect. An option that has three real pros but lacks a real con gets three pros and does not get a con. Never add a bullet to fill a slot, reach parity between options, or avoid looking one-sided; when the honest cost is hard to find, that difficulty is itself evidence the option is strong. When every option lacks a real bullet, omit them all and let the markers alone convey the recommendation. Do not add tiebreaker text for equal-strength options; the developer picks the number.
60
+ Asymmetry is a report, not a defect. Give an option that has three real pros but lacks a real con its three pros, and do not give it a con. Never add a bullet to fill a slot, reach parity between options, or avoid looking one-sided; when the honest cost is hard to find, that difficulty is itself evidence the option is strong. When every option lacks a real bullet, omit them all and let the markers alone convey the recommendation. Do not add tiebreaker text for equal-strength options; the developer picks the number.
61
61
 
62
- A `□□□` option keeps the `➖` that explains why it was ruled out. Under the falsifiability test that bullet is real by construction, and without it the reader is left with a veto that they cannot check.
62
+ Keep on a `□□□` option the `➖` that explains why you ruled it out. Under the falsifiability test that bullet is real by construction, and without it the reader is left with a veto that they cannot check.
63
63
 
64
- **Check the leader before rendering.** Once the bullets are drafted, and before the gate reads the markers:
64
+ **Check the leader before rendering.** Once you have drafted the bullets, and before you read the markers against the gate, run this check. It applies to a gated decision as fully as to any other: The menu renders whatever the markers say, and the marker tells the developer how much deliberation the ask needs.
65
65
 
66
- 1. For each `➖` on the strongest-marked option, name the reader who would choose differently because of it. Cut the bullet if there is none.
67
- 2. Re-mark the options. When every alternative carries a disqualifying `➖`, the leader is ■■■. The observed bias is a marker set too weak, not one set too strong.
68
- 3. Re-apply the gate. Outside the gated class, a leader marked above every other option means that the field is decided: State the decision in one line, and do not render a menu.
66
+ 1. For each alternative, look for a cost that disqualifies it, including one that follows from the constraints and acceptance criteria of the work at hand. When you find one, state it as the alternative's `➖`.
67
+ 2. For each `➖` on the strongest-marked option, name the reader who would choose differently because of it. Cut the bullet if there is none.
68
+ 3. Re-mark the options. When every alternative has a disqualifying `➖`, mark the leader ■■■. The observed bias is a marker set too weak, not one set too strong.
69
+ 4. Re-apply the gate. Outside the gated class, a leader marked above every other option means that the field is decided: State the decision in one line, and do not render a menu. Inside the class, render the menu with the leader's marker as the check set it.
69
70
 
70
71
  **Identify each question** when a single response contains 2 or more option-style questions: Prefix them `Q1`, `Q2`, and so on, so that the user can reference answers unambiguously. When the underlying data already has stable identifiers (plan-review findings such as `C1` or `X2`), use those in place of `Q1`/`Q2`. For a single option-style question, omit the identifier. Inside an [action-items block](../_data/action-items.md), identifiers are mandatory whenever the block contains more than one item (or more than one independently-numbered list), and they distinguish actions (`A`) from questions (`Q`).
71
72
 
@@ -13,7 +13,7 @@
13
13
 
14
14
  ## Decisions taken
15
15
 
16
- - {A decision that the agent took without asking, with its one-line reason; append `(provisional)` when it awaits the checkpoint}
16
+ - {🔲 while it awaits the checkpoint} {A decision that the agent took without asking, with its one-line reason}
17
17
 
18
18
  ## Tasks
19
19
 
@@ -50,19 +50,21 @@
50
50
 
51
51
  `## Dependencies` (external dependencies or blockers) is the one optional section: Insert it between `## Risks` and `## Verification` only when the plan has external blockers, and omit it otherwise.
52
52
 
53
- **Per-task test criterion:** When a task creates or modifies testable behavior, its acceptance criteria must include a test criterion (e.g., "New/modified behavior is covered by tests"). Omit it when the change falls entirely within the carve-outs defined in the `testing-conventions` skill, or when the only tests it would compel are ones that fail that skill's bar for earning a place.
53
+ **Per-task test criterion:** When a task creates or modifies testable behavior, its acceptance criteria must include a test criterion that asks for coverage at the cheapest tier that observes the behavior, per the placement rules in the `testing-conventions` skill (e.g., "New/modified behavior is covered by tests at the cheapest tier that observes it"). Omit it when the change falls entirely within the carve-outs defined in the `testing-conventions` skill, or when the only tests that it would require are ones that fail that skill's bar for earning a place.
54
54
 
55
55
  **Per-task documentation criterion:** When a task adds, removes, or renames user-facing surface (CLI flags, commands, API endpoints, configuration keys, environment variables), its acceptance criteria must include updating documentation, help text, and usage examples, including removal of references to anything that no longer exists.
56
56
 
57
57
  **Per-task README guidance:** When a task writes or revises a README, consult {rulebook:readme-conventions} while planning the task. Its key decisions name the rulebook, the table row that fits the README, and what that row says the README leads with, keeps, and omits, so that the constraints are available to an implementer that cannot load the rulebook.
58
58
 
59
- **Per-task interface guidance:** When a task defines colour tokens, styles text, or builds a page, a prototype, or a UI component, consult {rulebook:accessibility-conventions} while planning the task. Its key decisions state the rulebook's contrast and size floors and the contrast check, so that the constraints are available to an implementer that cannot load the rulebook.
59
+ **Per-task documentation placement:** When a task writes or revises guidance or documentation, its key decisions name the source that defines each fact that the task documents, and the task writes a pointer to that source rather than a copy, per the "Documentation placement" section of the shared agent instructions.
60
60
 
61
- **Data-change guidance:** When the work changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions} while planning. Scope the plan to one step of the expand, migrate, contract sequence, and name that step in the key decisions of each task that touches the data. No task or verification check runs a migration or another write against shared state before merge.
61
+ **Per-task interface guidance:** When a task defines colour tokens, styles or writes interface text, or builds a page, a prototype, or a UI component, consult {rulebook:accessibility-conventions} and {rulebook:ui-copy-conventions} while planning the task. Its key decisions state the contrast and size floors and the contrast check, the interaction states that each interactive element shows, and the copy rules and the copy budget, so that the constraints are available to an implementer that cannot load the rulebooks. When the plan changes a visible component, its `## Verification` includes the rulebook's browser check of each new or changed interactive element.
62
+
63
+ **Data-change guidance:** When the work changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions} while planning. Scope the plan to one step of the expand, migrate, contract sequence, and name that step in the key decisions of each task that touches the data. A task or verification check does not run a migration or another write against shared state before merge.
62
64
 
63
65
  **Per-task invoked-skill guidance:** When a task invokes a skill, read that skill while planning the task and record in the task's key decisions what the skill declares under three headings: its ordering relative to other skills, its default target when the task does not pass an argument, and the preconditions that it states. Read every skill that the plan's tasks name, and record a skill declaring none of the three as declaring none, so that a reader can tell a completed check from an absent one. A skill that cannot be read is recorded as unread, never as declaring none. When an ordering constraint names a skill that the plan's tasks do not invoke, add the task rather than record the constraint alone.
64
66
 
65
- **Who performs a step.** Every task and every `## Verification` check names the agent as its actor. A part that only the developer can perform is written as a `**Residue:**` line under the task, after **What:** and in the same position as **Key decisions:**, in the form "**Residue:** {what the developer alone can do}: {why the agent cannot}", and the task's other parts stay the agent's. Check a resource's availability before naming it as a risk; when a step needs something that only the developer can supply, such as a credential or a running service, the step states the ask for that resource, never a degraded fallback and never the step as the developer's. A manual check is cut when an automated test or a check in `## Verification` asserts the same observable outcome, and stays, as the agent's, when it would show something that no test asserts. A check proposed against a deployed branch accounts for a `live` worktree, which runs the merged tree rather than the branch.
67
+ **Who performs a step.** Every task and every `## Verification` check names the agent as its actor. A part that only the developer can perform is written as a `**Residue:**` line under the task, after **What:** and in the same position as **Key decisions:**, in the form "**Residue:** {what the developer alone can do}: {why the agent cannot}", and the task's other parts stay the agent's. A residue that a person must perform on each machine is one script per machine, run once, which checks its own result and prints only the facts that the agent needs; the agent writes and commits the script. A record of the work, such as a log entry or a ticket comment, is never residue, and the residue is never shipped as documentation for a person to follow. Check a resource's availability before naming it as a risk; when a step needs something that only the developer can supply, such as a credential or a running service, the step states the ask for that resource, never a degraded fallback and never the step as the developer's. A manual check is cut when an automated test or a check in `## Verification` asserts the same observable outcome, and stays, as the agent's, when it would show something that the tests do not assert. A check proposed against a deployed branch accounts for a `live` worktree, which runs the merged tree rather than the branch.
66
68
 
67
69
  Before (a verification task handed to the developer):
68
70
 
@@ -1,5 +1,5 @@
1
1
  Selecting Split is the developer's consent to the split at the seam that its `➕` line names. Nothing is created before that selection, and the bodies get one confirmation before anything is created.
2
2
 
3
- **Compose.** Compose a ticket body per piece (problem, context, acceptance criteria) from the piece's work and the ticket's criteria. Compose the originating ticket's new body as well: With two pieces, rewrite it to the first piece, so that the originating ticket and one new ticket carry the split; with three or more, make it an umbrella that keeps its problem and context, lists the children, and has "Every child is closed" as its acceptance criterion. When no ticket governs the work, every piece is a new ticket and there is nothing to rewrite.
3
+ **Compose.** Compose a ticket body per piece (problem, context, acceptance criteria) from the piece's work and the ticket's criteria. Compose the originating ticket's new body as well: With two pieces, rewrite it to the first piece, so that the originating ticket and one new ticket cover the two pieces; with three or more, make it an umbrella that keeps its problem and context, lists the children, and has "Every child is closed" as its acceptance criterion. When the work does not have a governing ticket, every piece is a new ticket and there is nothing to rewrite.
4
4
 
5
5
  **Confirm once.** Show every body, every relationship, and everything that the steps below create or change in one block, and confirm once. This single confirmation stands in for the per-ticket confirmation that `{skill:create-ticket}` would otherwise raise for each piece.
@@ -1,3 +1,3 @@
1
- **Create the tickets.** Create the pieces in order with `{skill:create-ticket}`. With three or more pieces, pass `--parent` naming the originating ticket. For a piece that depends on an earlier piece landing first, pass `--blocked-by` naming that piece's reference, which exists by then.
1
+ **Create the tickets.** Create the pieces in order with `{skill:create-ticket}`. With three or more pieces, pass `--parent` naming the originating ticket. For a piece that depends on an earlier piece being merged first, pass `--blocked-by` naming that piece's reference, which exists by then.
2
2
 
3
3
  **Rewrite the originating ticket.** Write the originating ticket's new body per the platform-specific write in [ticket source resolution](../_data/ticket-source-resolution.md#platform-specific-write).
@@ -7,7 +7,7 @@ The handoff test has two halves, and each needs a different reader. The sweep ch
7
7
  **Sweep for:**
8
8
 
9
9
  - Settled decisions, including the rejected alternatives.
10
- - Decisions that the agent took without asking: Every one is in the plan's `## Decisions taken` section, with its reason, marked provisional when it awaits this checkpoint.
10
+ - Decisions that the agent took without asking: Every one is in the plan's `## Decisions taken` section, with its reason, marked 🔲 when it awaits this checkpoint.
11
11
  - Constraints and scope boundaries on which the conversation agreed.
12
12
  - Edge cases and success criteria raised in discussion but missing from the acceptance criteria.
13
13
  - Tacit context of the form "the implementer might not realize X": What the conversation established as known and the artifacts leave the reader to rediscover.
@@ -24,7 +24,7 @@ plan: {plan draft path}
24
24
  root: {repository root}
25
25
  ```
26
26
 
27
- The block contains scalars only, and only these keys. Do not compose any prose into it: A sentence written here carries the session's knowledge into the reader, and the pass is worth nothing once the reader shares what the writer knows.
27
+ The block contains scalars only, and only these keys. Do not compose any prose into it: A sentence written here gives the reader the session's knowledge, and the pass is worth nothing once the reader shares what the writer knows.
28
28
 
29
29
  **A reply that lacks the `Phase: handoff-review` return block is a reviewer stopped by its turn limit.** Resume that reviewer once, asking only for its report; on Claude Code, send it a message with `SendMessage`, addressed by the agent ID that its dispatch returned. The resumption continues the same dispatch, so it is not the second dispatch that the pass forbids. When the harness cannot resume a subagent, or the resumed reviewer still does not return a report, do not dispatch again: Save the drafts without the pass, and report that the handoff pass did not return a report, even when the sweep found nothing.
30
30
 
@@ -0,0 +1,40 @@
1
+ Start from this skeleton. Add a section only when it adds signal on which the reader must act.
2
+
3
+ - **Problem** and **Acceptance criteria (Must have)**: Always present.
4
+ - **Context**, **Proposed solution** (including "X, not Y"), and **Should have / Nice to have**: Opt-in, added only when the reader needs them. Omit empty tiers.
5
+
6
+ This applies the [concision principle](../_data/concision.md) to tickets.
7
+
8
+ **Write the tightened ticket, not a draft to be tightened later.** A ticket is the minimal contract that a reader needs, not a transcript of the design session. Compose the maximally tight version that still keeps the full meaning; length comes from content, not from a completeness instinct. (Producing the tight version up front spares the reader, and spares everyone the tighten-on-request round trip.)
9
+
10
+ State conclusions, not the journey to them. Naming a chosen approach (including "X, not Y") is a durable decision and belongs in the ticket. The _story_ of how the decision was reached does not: Drop the design back-and-forth, the false starts, restated context, and motivating episodes.
11
+
12
+ **Self-check before presenting.** For each sentence, ask: Would removing it change what the reader does or how the work gets executed? If not, cut it. State each acceptance criterion once, and do not restate it in surrounding prose.
13
+
14
+ Add a design-narrative section (rationale, alternatives explored) only when the user explicitly asks for it.
15
+
16
+ **Before** (the design journey is left in):
17
+
18
+ > We first considered extending the existing `FooAdapter`, but a spike showed it couples the cache to the transport, so after some back-and-forth we landed on a separate `CacheLayer`. The team has struggled with cache invalidation before, and this should finally fix that. Acceptance: A new `CacheLayer` module exists. It must be covered by tests so we know it works.
19
+
20
+ **After** (conclusion only, full meaning intact):
21
+
22
+ > Add a `CacheLayer` separate from the transport (not an extension of `FooAdapter`, which would couple cache to transport).
23
+ >
24
+ > - [ ] `CacheLayer` is independent of the transport.
25
+ > - [ ] New behavior is covered by tests.
26
+
27
+ **Place ticket content by kind, not by volume.** A ticket states the change's _subject_ and the _outcomes_ that it must produce; the _mechanism_ that achieves them belongs with the implementation, not the ticket. This is a separate axis from concision: A perfectly short ticket can still contain the wrong _kind_ of content.
28
+
29
+ - **Ticket**: The change's **subject** (the defect being fixed, the current structure being changed, the target contract or behavior that it exposes) and **key** non-obvious details that save the implementer real derivation (e.g. "reuse the sibling table's `getSortValue`").
30
+ - **Implementation**: The **mechanism**, meaning internal wiring, files as a diff-list, step sequences, deletion lists, and the internal props/config of a dependency consumed by the change.
31
+
32
+ The line is subject vs. mechanism, not code vs. prose: A code name is fine when it _is_ the subject. **Bug and refactoring tickets** name existing code because that code is the subject. Keep it; the fix procedure still belongs with the implementation.
33
+
34
+ **Before** (a feature ticket transcribing a reference implementation's API surface):
35
+
36
+ > Set `columnDefs`, pass `getSortedRowModel`, and wire `state.sorting`; pin the first column via `columnPinning.left: ['name']`; mock `@acme/table` in `__mocks__/@acme/table/compiled.tsx`.
37
+
38
+ **After** (the same change stated as the contract that it must honor):
39
+
40
+ > Every column sorts client-side, and the first column stays pinned during horizontal scroll. (Which props wire this up is implementation.)
@@ -1,7 +1,7 @@
1
- **Test criterion convention:** When writing a ticket that changes testable behavior, include a test criterion in its acceptance criteria (e.g., "New/modified behavior in this change is covered by tests"). Omit it when the change falls entirely within the carve-outs defined in the `testing-conventions` skill, or when the only tests it would compel are ones that fail that skill's bar for earning a place.
1
+ **Test criterion convention:** When writing a ticket that changes testable behavior, include a test criterion in its acceptance criteria that asks for coverage at the cheapest tier that observes the behavior, per the placement rules in the `testing-conventions` skill (e.g., "New/modified behavior in this change is covered by tests at the cheapest tier that observes it"). Omit it when the change falls entirely within the carve-outs defined in the `testing-conventions` skill, or when the only tests that it would require are ones that fail that skill's bar for earning a place.
2
2
 
3
3
  **Documentation criterion convention:** When writing a ticket that adds, removes, or renames user-facing surface (CLI flags, commands, API endpoints, configuration keys, environment variables), include in its acceptance criteria the corresponding updates to documentation, help text, and usage examples, including removal of references to anything that no longer exists.
4
4
 
5
- **Umbrella criterion convention:** When writing an umbrella ticket, whose children do the work, list "Every child is closed" as an acceptance criterion alongside any requirement of its own, so that what completes it is stated rather than inferred. When the split is decided, create a child for every planned piece, so that the criterion cannot hold while a planned piece remains: Link each child to the umbrella as a sub-issue, and through blocked-by relations to the pieces that must land before it. Specify the current piece fully, and keep each later piece short: its outcome, a few must-have criteria, and a note that it is refined when its work starts. Never leave a planned piece as an outline in the umbrella's body. To defer a planned piece, close its child as not planned.
5
+ **Umbrella criterion convention:** When writing an umbrella ticket, whose children do the work, list "Every child is closed" as an acceptance criterion alongside any requirement of its own, so that what completes it is stated rather than inferred. When the split is decided, create a child for every planned piece, so that the criterion cannot hold while a planned piece remains: Link each child to the umbrella as a sub-issue, and through blocked-by relations to the pieces that must be merged before it. Specify the current piece fully, and keep each later piece short: its outcome, a few must-have criteria, and a note that it is refined when its work starts. Never leave a planned piece as an outline in the umbrella's body. To defer a planned piece, close its child as not planned.
6
6
 
7
- **Data-change criterion convention:** When writing a ticket that changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions}. Scope the ticket to one step of the expand, migrate, contract sequence, and include a criterion that deployed code keeps working whichever lands first, the deploy or the migration.
7
+ **Data-change criterion convention:** When writing a ticket that changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions}. Scope the ticket to one step of the expand, migrate, contract sequence, and include a criterion that deployed code keeps working whichever happens first, the deploy or the migration.
@@ -10,4 +10,18 @@
10
10
 
11
11
  {The shape of the proposed approach: components or boundaries involved, how it fits into the existing system, and the chosen approach, including "X, not Y" when a rejected option is worth recording. Keep this section outcome-shaped per the placement doctrine below.}
12
12
 
13
- <!-- include: acceptance-criteria-scaffold.md / -->
13
+ ## Acceptance criteria
14
+
15
+ Include only the tiers that have criteria. Omit any empty tier; do not emit a "Should have" or "Nice to have" header with nothing under it.
16
+
17
+ ### Must have
18
+
19
+ - [ ] {Critical requirement}
20
+
21
+ ### Should have
22
+
23
+ - [ ] {Important but not blocking}
24
+
25
+ ### Nice to have
26
+
27
+ - [ ] {Optional enhancement}
@@ -8,9 +8,9 @@ user-invocable: true
8
8
 
9
9
  Append a `change-record` block to a pull request whose body has none, so that the merge publishes the change entries.
10
10
 
11
- The block is drafted by `{skill:summarize-change}`, which consolidates the branch, draws the entries, audits them, and renders the block. This skill lifts the rendered block from the summary that the run saved and appends it to the pull-request body; it drafts nothing of its own.
11
+ The block is drafted by `{skill:summarize-change}`, which consolidates the branch, draws the entries, audits them, and renders the block. This skill copies the rendered block from the summary that the run saved and appends it to the pull-request body; it drafts nothing of its own.
12
12
 
13
- **A block that is already written is never replaced.** A readable block, a malformed one, and one that does not record an entry are all left for the author to repair by hand, as [the change record](../_data/change-record.md#where-the-record-is-read) states. This skill adds a block only where there is none.
13
+ **A block that is already written is never replaced.** A readable block, a malformed one, and one that does not record an entry are all left for the author to repair by hand, as [the change record](../_data/change-record.md#where-the-record-is-read) states. This skill adds a block only to a body that does not contain one.
14
14
 
15
15
  ## Arguments
16
16
 
@@ -37,19 +37,15 @@ The artifact begins with YAML frontmatter conforming to the [universal artifact
37
37
  <!-- include: ../_partials/ticket-skeleton.md / -->
38
38
  ```
39
39
 
40
- <!-- include: ../_partials/ticket-skeleton-tiers.md / -->
41
-
42
40
  ## Guidance
43
41
 
44
- <!-- include: ../_partials/ticket-concision.md / -->
45
-
46
- <!-- include: ../_partials/ticket-placement.md / -->
42
+ <!-- include: ../_partials/ticket-composition.md / -->
47
43
 
48
44
  When aligning to an existing implementation, _the implementation_ is the code on the branch; describe what the code now does, and resist transcribing its mechanism back into the ticket.
49
45
 
50
46
  ### Two branches
51
47
 
52
- What the skill does turns on whether a prior ticket exists, not on how the caller scoped the call.
48
+ What the skill does depends on whether a prior ticket exists, not on how the caller scoped the call.
53
49
 
54
50
  **Generation, when a prior ticket does not exist.** The work was done on the branch without a ticket, so every section is authored now from the implementation and nothing is overwritten. The skeleton's `## Proposed solution` section is forward-looking by default; here it records the approach that the branch actually took, not a proposal still under consideration.
55
51
 
@@ -96,7 +92,7 @@ The skill writes two artifacts: the ticket of record on its platform, and a loca
96
92
 
97
93
  **`--write-target=local` writes the local artifact alone.** The ticket of record is left as it stands, however it resolved. The override selects the target and nothing else: The mode still bounds the revision, and the no-delta confirmation still precedes the write. `--write-target=remote` states the default explicitly and, when a ticket of record does not resolve, stops and reports the missing target rather than falling back to the local artifact.
98
94
 
99
- **Order and reporting.** Write the remote, then save the local artifact, then report. A remote write that fails leaves the artifact saved and is reported as a failure, naming the manual step that remains; when the remote did not resolve, or `--write-target=local` held it back, report that the remote was not updated and which of the two is the reason.
95
+ **Order and reporting.** Write the remote, then save the local artifact, then report. A remote write that fails leaves the artifact saved and is reported as a failure, naming the manual step that remains; when the remote did not resolve, or `--write-target=local` excluded it, report that the remote was not updated and which of the two is the reason.
100
96
 
101
97
  ### Path resolution
102
98
 
@@ -34,7 +34,7 @@ Common but problematic approaches that should be avoided in favor of proper solu
34
34
  ### Suppression directives
35
35
 
36
36
  - **A suppression directive (a comment that tells a linter or type checker to ignore a specific warning) is a design signal, not a workaround.** The rule flagged the code because it matched a pattern that is usually wrong.
37
- - **Try these in order before suppressing inline:** (1) change the code so that the rule no longer triggers, usually the right answer; (2) reconfigure the rule if its default is wrong for the project; (3) define a scoped exception for a whole category that is legitimately exempt. Suppress inline only as a last resort, when the case is genuinely local and none of the above fits, such as an external boundary where the real type can't be known.
37
+ - **Try these in order before suppressing inline:** (1) change the code so that the rule no longer triggers, usually the right answer; (2) reconfigure the rule if its default is wrong for the project; (3) define a scoped exception for a whole category that is legitimately exempt. Suppress inline only as a last resort, when the case is genuinely local and none of the above fits, such as an external boundary at which the real type can't be known.
38
38
  - **An `any` or a type assertion suppresses in the language what a directive suppresses in a comment.** Both silence the checker without changing what the code does, so the same ladder applies to both: Model the type that the value actually has, or return `unknown` and let the caller narrow it.
39
39
  - **Write a rationale for every suppression that you introduce**, naming the rule, why it doesn't apply here, and what alternatives you rejected. Restating the rule is not a rationale.
40
40