codeassembly-guidance 0.6.0 → 0.7.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 (66) hide show
  1. package/.meta/changelog.json +185 -0
  2. package/CHANGELOG.md +45 -0
  3. package/README.md +29 -51
  4. package/content/_partials/kb-unsearched-private-stores.md +6 -0
  5. package/content/codeassembly-content.yaml +2 -0
  6. package/content/guidance/rulebooks/live-worktree-policy.md +2 -2
  7. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -1
  8. package/content/guidance/shared/AGENTS.md +1 -1
  9. package/content/scripts/check-prose.mjs +1 -1
  10. package/content/scripts/describe-change.mjs +89 -89
  11. package/content/scripts/manage-jira-ticket.mjs +113 -113
  12. package/content/scripts/select-lede-exemplars.mjs +85 -85
  13. package/content/scripts/validate-preferences.mjs +38 -38
  14. package/content/skills/_data/project-stage.md +9 -5
  15. package/content/skills/_data/spike-conventions.md +9 -6
  16. package/content/skills/_partials/implementation-order-list.md +27 -0
  17. package/content/skills/_partials/next-steps-after-plan.md +2 -2
  18. package/content/skills/_partials/plan-template.md +2 -0
  19. package/content/skills/_partials/split-launch-prompts.md +1 -1
  20. package/content/skills/align-ticket-with-implementation/SKILL.md +1 -1
  21. package/content/skills/assess-code-health/SKILL.md +2 -2
  22. package/content/skills/assess-usability/SKILL.md +2 -2
  23. package/content/skills/capture-event/SKILL.md +20 -11
  24. package/content/skills/capture-event/capture-event.mjs +122 -122
  25. package/content/skills/capture-feedback/SKILL.md +2 -1
  26. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
  27. package/content/skills/create-pr/SKILL.md +11 -11
  28. package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
  29. package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
  30. package/content/skills/derive-session-context/derive-session-context.mjs +107 -107
  31. package/content/skills/design-and-plan/SKILL.md +4 -2
  32. package/content/skills/implement-plan/SKILL.md +3 -1
  33. package/content/skills/implementation-order/implementation-order.mjs +67 -0
  34. package/content/skills/investigate-spike/SKILL.md +1 -1
  35. package/content/skills/kb-add/SKILL.md +12 -3
  36. package/content/skills/kb-add/kb-add.mjs +88 -88
  37. package/content/skills/kb-curate/kb-curate.mjs +88 -88
  38. package/content/skills/kb-edit/kb-edit.mjs +90 -90
  39. package/content/skills/kb-retrieve/SKILL.md +8 -3
  40. package/content/skills/kb-retrieve/kb-retrieve.mjs +104 -104
  41. package/content/skills/kb-retrieve-events/SKILL.md +8 -3
  42. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +113 -113
  43. package/content/skills/kb-update-events/kb-update-events.mjs +92 -92
  44. package/content/skills/lesson-clusters/lesson-clusters.mjs +102 -102
  45. package/content/skills/list-implementation-order/SKILL.md +23 -0
  46. package/content/skills/merge-bb-pr/SKILL.md +31 -8
  47. package/content/skills/merge-gh-pr/SKILL.md +25 -12
  48. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
  49. package/content/skills/merge-pr/SKILL.md +55 -20
  50. package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
  51. package/content/skills/plan/SKILL.md +3 -1
  52. package/content/skills/prepare-prototype-brief/SKILL.md +3 -1
  53. package/content/skills/refine-plan/SKILL.md +2 -0
  54. package/content/skills/review-branch/SKILL.md +1 -1
  55. package/content/skills/review-criteria/SKILL.md +1 -1
  56. package/content/skills/revise-prose/revise-prose.mjs +111 -111
  57. package/content/skills/save-plan/SKILL.md +2 -0
  58. package/content/skills/streamline-guidance/streamline-guidance.mjs +76 -76
  59. package/content/skills/summarize-change/SKILL.md +17 -7
  60. package/content/skills/testing-conventions/SKILL.md +2 -2
  61. package/content/skills/triage-feedback/SKILL.md +4 -0
  62. package/content/skills/triage-spike-findings/SKILL.md +10 -5
  63. package/content/skills/wrap-up/SKILL.md +4 -0
  64. package/package.json +9 -9
  65. package/schemas/preferences.v1.json +74 -8
  66. package/schemas/work-types.v1.json +1 -1
@@ -84,7 +84,11 @@ Both are optional, and each is recorded as an override beside the consolidated r
84
84
  3. **Compose title**: Compose the change string per [`title-voice.md`](../_data/title-voice.md).
85
85
  - The change summary's own heading prefixes that string with the ticket reference for identification: `{ticket_ref} {title}`, or just `{title}` when `ticket_ref` is null.
86
86
 
87
- 4. **Compose `## Why`, and `## How to test` when the change has a surface to exercise**, per the output format below. `## What` and `## Details` both come from what step 5 draws, so neither exists until step 8. Step 6's writing-rules check reads `## Why` and `## How to test` with the drafted passages.
87
+ 4. **Compose `## Why`, `## Notes for reviewers` when a fact passes the reader test, and `## How to test` when the change has a surface to exercise**, per the output format below. `## What` and `## Details` both come from what step 5 draws, so neither exists until step 8. Step 6's writing-rules check reads the sections composed here with the drafted passages.
88
+
89
+ **The reader test.** The reader of a pull-request description is a reviewer who hasn't read the ticket. Each line of a section composed here must change what the reviewer checks or decides. A line fails the test when it states what the diff already shows, the author's own follow-ups or checklists, a step for the author rather than for a reviewer (such as the merge order), ownership or approval routing that tooling already reports, or the history of how the approach was chosen. The test applies to `## Why`, `## Notes for reviewers`, and `## How to test`; `## What` and `## Details` come from `entry-drafter` and follow its contract instead.
90
+
91
+ Write `## Notes for reviewers` only when a fact passes the test and the other sections do not state it; otherwise omit the section, heading included. Draw the facts from the diff, the commit bodies, and the ticket, and write each as a bullet. Such a fact explains, for example, why a consumer that the reviewer would expect to be affected is not, how the change was tested beyond what CI runs, or why a test runs at an expensive tier. Add a divergence from the ticket's proposal only when it changes what a reviewer checks, and state it as the current fact rather than as a departure from the ticket.
88
92
 
89
93
  Write `## How to test` only when the diff changes a surface that a person sees or operates: a page, a UI component, or a command's output. Otherwise omit the section, heading included. Compose it from the diff and the ticket as numbered steps, each stating where to go (the route, the page, or the command, and how to start the app when the repository does not make that obvious), what to do there, and what the reviewer should observe. Cover only what CI does not assert: Never list automated checks, such as formatting, linting, typechecking, or tests.
90
94
 
@@ -108,19 +112,19 @@ Both are optional, and each is recorded as an override beside the consolidated r
108
112
 
109
113
  On a first dispatch, take the drafter's `## Lede` section as it stands; step 9 makes it `## What`, and later steps do not rewrite it. A redispatch returns every replacement under `## Entries` and does not return a `## Lede` section at all, so the lede that it keeps is whichever text the placement above left in the lede's place. Parse the `## Entries` fence as YAML. Each entry declares `type`, `scopes`, `breaking`, and `text`, and `migration` when the entry calls for one. Read the `## Report` for any source that the drafter could not access. Step 6 checks each entry's `type`.
110
114
 
111
- 6. **Audit the lede and the entries.** The first three checks apply to the lede, to each entry's `text`, and to each entry's `migration` alike, except as the subject check states, and each names the rejection code that its failure raises, for which a redispatch is the repair rather than an edit of your own. The type check applies to each entry, and raises its code against the entry's `text` alone. `scopes` and `breaking` are not prose and are never rejected; `type` is corrected by the type check and never rejected. The writing-rules check runs last, and it also reads `## Why` and `## How to test`.
115
+ 6. **Audit the lede and the entries.** The first three checks apply to the lede, to each entry's `text`, and to each entry's `migration` alike, except as the subject check states, and each names the rejection code that its failure raises, for which a redispatch is the repair rather than an edit of your own. The type check applies to each entry, and raises its code against the entry's `text` alone. `scopes` and `breaking` are not prose and are never rejected; `type` is corrected by the type check and never rejected. The writing-rules check runs last, and it also reads the sections that step 4 composed.
112
116
 
113
117
  - **Verification.** Read the lede, each entry's `text`, and each `migration` against the diff from step 2. Strike a claim that the diff contradicts, and correct one that it states differently. Never add: A fact omitted from the draft was left out by the reader of the change, and supplying it here restores the weighting that the fresh-context dispatch removed. The drafter read the diff, so this check no longer supplies the draft's grounding; it catches a sentence claiming more than the diff supports, such as one that only the commit log, the ticket, or this session supports, which the diff does not contradict and which is not one to strike: `rejection: unsupported-claim`.
114
118
  - **Subject.** Read the lede's each sentence, and each entry's `text`, with "This pull request" in front of it. If that sentence is false, the verb names what the system does rather than what the change did: `rejection: subject`. This check fails most often on a change that adds something which itself acts, such as a command, a check, a rule, or a hook, because the added thing's behavior is true, interesting, and reads as a correct entry while standing in for the change. A `migration` is exempt: It is an imperative addressed to the consumer, not a sentence whose subject is the pull request.
115
119
  - **Voice.** A figurative verb, or an invented term when a plain one exists: `rejection: voice`.
116
120
  - **Type.** Apply [Work type test](#work-type-test) to the entry's outcome. When the test's type differs from the drafted `type`, or the drafted `type` does not name a key in [work-types.json](../_data/work-types.json), set `type` to the test's result and state the correction in one line with its reason. A type is a determination that you make by applying a test, not prose, so the correction is never a redispatch and never an ask. The entry's `text` is prose: When it is still written in the form that the replaced type takes, such as a `fix` entry's opening on an entry now typed `feat`, that passage fails: `rejection: type-mismatch`.
117
- - **Writing rules.** Run this check over the passages that passed every check above, and over `## Why` and `## How to test`, so that a redispatch names one code. Write them to a scratch file, created per the path rules of [gh body file](#gh-body-file) and named `prose-check-{timestamp}.md`, as bare paragraphs separated by blank lines, without headings or list markers: the lede, each entry's `text` and each `migration` as paragraphs of their own, each paragraph of `## Why`, and each step of `## How to test`. Write it with a file-writing tool rather than a shell heredoc, as step 7 does. Then run:
121
+ - **Writing rules.** Run this check over the passages that passed every check above, and over the sections that step 4 composed, so that a redispatch names one code. Write them to a scratch file, created per the path rules of [gh body file](#gh-body-file) and named `prose-check-{timestamp}.md`, as bare paragraphs separated by blank lines, without headings or list markers: the lede, each entry's `text` and each `migration` as paragraphs of their own, each paragraph of `## Why`, each note of `## Notes for reviewers`, and each step of `## How to test`. Write it with a file-writing tool rather than a shell heredoc, as step 7 does. Then run:
118
122
 
119
123
  ```bash
120
124
  node {harness_home_dir}/scripts/check-prose.mjs --file "{absolute path of the scratch file}" --json
121
125
  ```
122
126
 
123
- The helper runs every `revise-prose` detector over the file, reading it as Markdown, and prints one JSON document, `{ file, rules, candidates }`, in which each candidate names its `rule` and the `sentence` that contains the site. It exits 0 without candidates, 1 with candidates, and 2 on a usage error or when it cannot read the file. Read exit 1 as candidates found, not as a failure. Map each candidate to its passage by its `sentence`, and to every passage containing that sentence when more than one does. Judge each against the rule that it names, as your plain-speech and writing guidance states that rule; a watchlist word used in the sense that names its relation, such as a promise that holds, is not a violation. State a candidate judged legitimate in one line with its reason. A confirmed violation in the lede, an entry's `text`, or a `migration` fails that passage: `rejection: writing-rule`. Rewrite a confirmed violation in `## Why` or `## How to test` yourself, since this session wrote it. Run the check again over every replaced passage.
127
+ The helper runs every `revise-prose` detector over the file, reading it as Markdown, and prints one JSON document, `{ file, rules, candidates }`, in which each candidate names its `rule` and the `sentence` that contains the site. It exits 0 without candidates, 1 with candidates, and 2 on a usage error or when it cannot read the file. Read exit 1 as candidates found, not as a failure. Map each candidate to its passage by its `sentence`, and to every passage containing that sentence when more than one does. Judge each against the rule that it names, as your plain-speech and writing guidance states that rule; a watchlist word used in the sense that names its relation, such as a promise that holds, is not a violation. State a candidate judged legitimate in one line with its reason. A confirmed violation in the lede, an entry's `text`, or a `migration` fails that passage: `rejection: writing-rule`. When a confirmed violation is in a section that step 4 composed, rewrite it yourself, since this session wrote it. Run the check again over every replaced passage.
124
128
 
125
129
  If the helper is unavailable or the call fails, relay its error, say that the summary was saved without the writing-rules check, and continue.
126
130
 
@@ -128,7 +132,7 @@ Both are optional, and each is recorded as an override beside the consolidated r
128
132
 
129
133
  Repeat step 5 with `rejection:` set to the code that the failed check names, and with the passages that failed in the `rejected` fence that step describes.
130
134
 
131
- Redispatch at most twice. After a second redispatch fails, the passages still failing are the ones that you last sent. Present those to the developer with the code, and ask for a replacement or for an explicit acceptance of each passage as it stands; place the answer, then continue to step 7 with the verified entries. If you could never place a return, show the developer each passage as the fence contained it. Take a passage rejected by the audit past step 6 only after asking the developer. Rewrite `## Why` and `## How to test` at most twice each for the writing-rules check; a confirmed violation that remains after the second rewrite goes to the developer the same way.
135
+ Redispatch at most twice. After a second redispatch fails, the passages still failing are the ones that you last sent. Present those to the developer with the code, and ask for a replacement or for an explicit acceptance of each passage as it stands; place the answer, then continue to step 7 with the verified entries. If you could never place a return, show the developer each passage as the fence contained it. Take a passage rejected by the audit past step 6 only after asking the developer. Rewrite each section that step 4 composed at most twice for the writing-rules check; a confirmed violation that remains after the second rewrite goes to the developer the same way.
132
136
 
133
137
  7. **Consolidate the change's record from the entries.** Do this before step 8, and before the frontmatter call: Step 8 reads the entries file that this step writes, and the title and the labels read the record that it produces.
134
138
  - **Write the verified entries** to a scratch file, created per the path rules of [gh body file](#gh-body-file) and named `entries-{timestamp}.yaml`. The file is a top-level YAML list of mappings, one per entry, each declaring `type`, `scopes`, `breaking`, and `text`, and `migration` when the entry has one, as the drafter returned them, with the corrections that step 6 made. Write each `text` and `migration` double-quoted, and quote any value that the drafter returned unquoted: Unquoted, a space followed by `#` opens a YAML comment, and the parse drops the rest of the text. Write it with a file-writing tool rather than a shell heredoc: `text` and `migration` are arbitrary prose containing backticks and quotes. Keep its path; steps 8 and 10 read the same file.
@@ -206,6 +210,12 @@ The body following the frontmatter has this structure:
206
210
  Bad: "The retry helper used a fixed backoff schedule with no shared state, so concurrent requests stacked up against the upstream rate limiter."
207
211
  Good: "Heavy-upload sessions were intermittently failing as users hit the upstream API's rate limit."}
208
212
 
213
+ ## Notes for reviewers
214
+
215
+ {Only when a fact passes the reader test in step 4.}
216
+
217
+ - `kb sync` does not resolve wikilinks, so the stricter resolution leaves it unaffected.
218
+
209
219
  ## Details
210
220
 
211
221
  ### 🎉 Features
@@ -238,11 +248,11 @@ entries:
238
248
  ## Guidance
239
249
 
240
250
  - When `ticket_ref` is null (the branch does not have a ticket), omit the `{ticket_ref} ` portion of the heading and the title so that they read naturally without it.
241
- - The change summary follows **newspaper style**, progressive disclosure from most to least essential: `## What` is the lede, `## Why` is the purpose that the change serves, `## Details` is every outcome that the change contains, and `## How to test`, when present, is how a reviewer exercises the change by hand
251
+ - The change summary follows **newspaper style**, progressive disclosure from most to least essential: `## What` is the lede, `## Why` is the purpose that the change serves, `## Notes for reviewers`, when present, is what a reviewer needs that the other sections do not state, `## Details` is every outcome that the change contains, and `## How to test`, when present, is how a reviewer exercises the change by hand
242
252
  - Both `## What` and `## Details` come from the drafter, so neither is composed in this session
243
253
  - `## What` contains none of the `## Details` bullets: The two sections cover the change at different lengths rather than repeating one list
244
254
  - Ignore auto-formatter and lint-fix changes
245
- - `## What` and `## Why` are required; `## How to test` appears only when the change alters a surface that a person sees or operates, per step 4
255
+ - `## What` and `## Why` are required; `## Notes for reviewers` appears only when a fact passes the reader test, and `## How to test` only when the change alters a surface that a person sees or operates, per step 4
246
256
  - The rendered `change-record` block is the body's last element, per [the change record](../_data/change-record.md)
247
257
 
248
258
  <!-- include: ../../_partials/prose-line-breaks.md / -->
@@ -40,10 +40,10 @@ A test's **tier** is what it starts or builds to observe a behavior. The cheapes
40
40
  - **Tier placement.** Test each case at the cheapest tier that can observe it. An expensive tier covers only what a cheaper tier cannot observe: that the entry starts, parses its arguments, wires its dependencies, and reports its exit status, with one smoke example per entry or verb. A branch of logic, a message, or a field of output is a case for the cheapest tier, even when the entry is the only caller that exercises it.
41
41
  - **Consolidate before adding.** Write a new example only for a behavior that the existing examples cannot be extended to cover. Cases that share setup and action are one table-driven test, as [Test structure](#test-structure) states. When the examples do not mutate a fixture, build it once per file, not once per example.
42
42
  - **Delete what is superseded, in the same change.** A higher-tier example is superseded when cheaper coverage observes each of its assertions, apart from the entry wiring that the smoke example covers. A change that adds the cheaper coverage deletes the examples that it supersedes, once the new tests pass the second check in [When tests are required](#when-tests-are-required). A port or a rewrite follows the same rule: The change that contains the port deletes the old suite rather than keeping it to catch regressions.
43
- - **Justify each expensive addition.** A change that adds an example at an expensive tier states, in its plan or its pull-request description, why a cheaper tier cannot observe that example. The justification does not belong in a test comment.
43
+ - **Justify each expensive addition.** A change that adds an example at an expensive tier states, in its plan or in its pull-request description's `## Notes for reviewers`, why a cheaper tier cannot observe that example. The justification does not belong in a test comment.
44
44
  - **Use the cheapest setup that fits.** Give an expensive tier the cheapest setup that fits its time budget, such as an in-process engine when few files need one. Add infrastructure, such as a server, a container, or a shared test package, only after a run of the suite at CI's parallelism shows that the cheaper setup does not fit.
45
45
  - **Keep setup cost independent of the number of files.** Design expensive setup so that adding or splitting a test file does not add to it, for example by starting one engine for the suite rather than one per file.
46
- - **Fix the design, not the timeout.** When a hook, a test, or a tier needs a longer timeout, in the test or in config, treat that as a sign of bad design and make it do less work: smaller data and injected dependencies, as [Test data](#test-data) states, or setup shared across files. A raised timeout hides a cost that grows with each file and with CI load. Raise one only when none of these fixes applies, and state why in the plan or the pull-request description, not in a test comment.
46
+ - **Fix the design, not the timeout.** When a hook, a test, or a tier needs a longer timeout, in the test or in config, treat that as a sign of bad design and make it do less work: smaller data and injected dependencies, as [Test data](#test-data) states, or setup shared across files. A raised timeout hides a cost that grows with each file and with CI load. Raise one only when none of these fixes applies, and state why in the plan or in the pull-request description's `## Notes for reviewers`, not in a test comment.
47
47
 
48
48
  ## Test data
49
49
 
@@ -132,4 +132,8 @@ Run `triage-feedback validate` on the final record, then `triage-feedback render
132
132
 
133
133
  Report each filed ticket with its repository, each deferred or rated cluster, each declined cluster, the remainder line, and the artifact's path.
134
134
 
135
+ When the record names two or more filed tickets, print the list for them after the report, per [implementation-order list](#implementation-order-list). They include a ticket that an earlier run of the same record filed.
136
+
135
137
  <!-- include: ../_partials/gh-body-file.md / -->
138
+
139
+ <!-- include: ../_partials/implementation-order-list.md / -->
@@ -90,11 +90,11 @@ Compose the bodies:
90
90
 
91
91
  - **The umbrella**, when at least one item is a `ticket`: its problem (the follow-up work of the findings), its context (a link to the triage ticket, and the tickets that the findings filed without adopting them, listed and not made children), and "Every child is closed" as its acceptance criterion. It does not take a graded label.
92
92
  - **One child per `ticket` item**, in the ticket skeleton that {skill:create-ticket} step 2 states: problem, context, and acceptance criteria, with the title and reason of every `merge` item that targets it folded in. Its labels are `confidence:{grade}` and `value:{grade}`.
93
- - **One follow-up triage ticket per later batch**, when the **Batches** table has more than one row: titled `Triage batch {n} of {findings title}`, with a link to the findings artifact, its path written `~/`-relative as in the [closing post](../_data/spike-conventions.md#closing-post), a link to the triage ticket, whose dispositions comment records the earlier round, the batch's items by id and title as its **The batch** input, and `triage-spike-findings` as its next step. Read the triage ticket's parent with `gh issue view {triage ticket} --json parent`: A follow-up takes that parent when there is one, so that it sits beside its siblings, and no parent otherwise. Each follow-up is blocked by the one before it. The first is not blocked: The triage ticket stays open after this run, and this round's dispositions are posted before the next round starts. Add one line per follow-up to the record's `notes`, `Batch {n} ({item ids}) is triaged in {follow-up}`, with the follow-up's title in place of `{follow-up}` until step 7 creates it, so that the dispositions comment names every follow-up.
93
+ - **One follow-up triage ticket per later batch**, when the **Batches** table has more than one row: titled `Triage batch {n} of {findings title}`, with a link to the findings artifact, its path written `~/`-relative as in the [closing post](../_data/spike-conventions.md#closing-post), a link to the triage ticket, whose dispositions comment records the earlier round, the batch's items by id and title as its **The batch** input, and `triage-spike-findings` as its next step. Read the triage ticket's parent with `gh issue view {triage ticket} --json parent`: A follow-up takes that parent when there is one, so that it sits beside its siblings, and no parent otherwise. Each follow-up is blocked by the one before it. The first is not blocked: This round's dispositions are posted before the next round starts. Add one line per follow-up to the record's `notes`, `Batch {n} ({item ids}) is triaged in {follow-up}`, with the follow-up's title in place of `{follow-up}` until step 7 creates it, so that the dispositions comment names every follow-up.
94
94
 
95
95
  Run the helper's `render --preview` to `{ticket_dir}/triage/preview/`, which writes the dispositions comment with `(pending)` where a number is not yet known, and one comment file per issue that a `comment` disposition names.
96
96
 
97
- Show everything that step 7 will create or post in one block: every body with its title and labels, the parent relationship and the blockers of each child and each follow-up, every per-issue comment with its issue, and the dispositions comment. Confirm once in the action-items block. This confirmation is the only one: {skill:create-ticket} does not re-confirm a relationship given as an argument.
97
+ Show everything that step 7 will create or post in one block: every body with its title and labels, the parent relationship and the blockers of each child and each follow-up, every per-issue comment with its issue, the dispositions comment, and, on a run given **The batch**, the close of the triage ticket as completed. Confirm once in the action-items block. This confirmation is the only one: {skill:create-ticket} does not re-confirm a relationship given as an argument.
98
98
 
99
99
  ### 7. Write
100
100
 
@@ -115,13 +115,16 @@ Nothing before this step writes anything remote. On a failed write, stop and rep
115
115
 
116
116
  Keep the URL that `gh issue comment` prints for the dispositions comment; when the post was skipped, keep the `url` of the matching comment instead. Step 8 links it.
117
117
 
118
- 7. Save `dispositions-comment.md`, with frontmatter, as the ticket-level `dispositions` artifact per {skill:save-artifact}.
118
+ 7. On a run given **The batch**, close the triage ticket without a closing post, because its dispositions comment is its record: Read `gh issue view {triage ticket} --json state`, and run `gh issue close {triage ticket} --reason completed` only while the state is `OPEN`.
119
+ 8. Save `dispositions-comment.md`, with frontmatter, as the ticket-level `dispositions` artifact per {skill:save-artifact}.
119
120
 
120
121
  ### 8. Report
121
122
 
122
- Report the umbrella when one was created, each child with its grades and blockers in the order in which step 7 created them, each follow-up triage ticket with its batch, each issue commented on, and the artifact's path. The triage ticket stays open: Closing it is the developer's call, once they have read the record.
123
+ Report the umbrella when one was created, each child with its grades and blockers in the order in which step 7 created them, each follow-up triage ticket with its batch, each issue commented on, the close of the triage ticket on a run given **The batch**, and the artifact's path.
123
124
 
124
- The triage round ends the spike, so offer the [closing post](../_data/spike-conventions.md#closing-post) on the triage ticket in the same response's action-items block, showing its body, and post it on consent with that section's duplicate check, passing the body through a file. Do not offer it when the run was given **The batch**: A follow-up triage ticket's dispositions comment is its record. The post contains:
125
+ When the record names two or more tickets among the children and the follow-up triage tickets, print the list for them after the report, per [implementation-order list](#implementation-order-list), leaving out the umbrella. They include a ticket that an earlier run of the same record created.
126
+
127
+ The triage round ends the spike, so offer to close the triage ticket with the [closing post](../_data/spike-conventions.md#closing-post) in the same response's action-items block, showing the post's body, and on consent post it and close the ticket with that section's checks. When the developer declines the offer, the triage ticket stays open. Do not offer it when the run was given **The batch**: A follow-up triage ticket's dispositions comment is its record, and step 7 has closed the ticket. The post contains:
125
128
 
126
129
  - The answer to each question to answer and the recommendation on each decision to enable that the triage ticket's body lists, taken from the findings and the approved dispositions. A body that lists neither leaves the post with the items below alone.
127
130
  - The count of items by disposition.
@@ -130,3 +133,5 @@ The triage round ends the spike, so offer the [closing post](../_data/spike-conv
130
133
  It does not repeat the dispositions, which the dispositions comment records.
131
134
 
132
135
  <!-- include: ../_partials/gh-body-file.md / -->
136
+
137
+ <!-- include: ../_partials/implementation-order-list.md / -->
@@ -399,6 +399,8 @@ Insights, applied drive-by fixes, and devlog references do not appear in the bod
399
399
 
400
400
  Omit empty sections. The "Artifacts saved" section is omitted when the skill did not write any artifacts (Step 1 did not produce a deferred-findings artifact, and Phase 3 did not generate a devlog). Filename suffixes (`_devlog.md`, `_deferred-findings.md`) state the artifact type; the report does not need separate sub-headings. Use the item's original ID (F1, L1, I2) so that the developer can cross-reference with the inventory.
401
401
 
402
+ When "Tickets created" lists two or more tickets, print the list for them after the report, per [implementation-order list](#implementation-order-list). Pass a ticket kept in a file as `--external "{ticket-id}={title}"`; its path stays in the report line alone.
403
+
402
404
  ### Phase 5: PR prompt
403
405
 
404
406
  After the results report, check whether the branch has commits ahead of the default branch (`git log --oneline {default_branch}..HEAD`). If there are commits (whether from the session's earlier work, drive-by fixes applied in Phase 2a, or both), prompt the user to create a PR:
@@ -429,3 +431,5 @@ Compose the title of a deferred-item ticket per [`title-voice.md`](../_data/titl
429
431
  - **Conversation is primary source**: Deferred items and insights appear in the dialogue, not just in git state
430
432
  - **Graceful when empty**: If the assessment finds nothing actionable, say so and end: "No wrap-up items identified for this session."
431
433
  - **Fresh numbering**: Always assign new sequential IDs within the wrap-up; never reuse IDs from source artifacts
434
+
435
+ <!-- include: ../_partials/implementation-order-list.md / -->
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codeassembly-guidance",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
4
  "description": "The CodeAssembly library of agent guidance: rulebooks, skills, and subagents that the codeassembly CLI deploys",
5
5
  "keywords": [
6
6
  "agents",
@@ -42,14 +42,14 @@
42
42
  "devDependencies": {
43
43
  "@hyperjump/json-schema": "1.18.0",
44
44
  "@types/node": "24.19.2",
45
- "@williamthorsen/change-grammar": "0.3.0",
46
- "@williamthorsen/kb": "0.11.1",
47
- "@williamthorsen/nmr": "0.55.0",
48
- "@williamthorsen/toolbelt.errors": "0.9.0",
49
- "@williamthorsen/toolbelt.terminal": "0.3.0",
50
- "@williamthorsen/toolbelt.testing": "0.8.0",
51
- "@williamthorsen/toolbelt.vitest": "0.13.2",
52
- "codeassembly": "0.20.0",
45
+ "@williamthorsen/change-grammar": "0.4.1",
46
+ "@williamthorsen/kb": "0.12.0",
47
+ "@williamthorsen/nmr": "2.2.1",
48
+ "@williamthorsen/toolbelt.errors": "0.10.1",
49
+ "@williamthorsen/toolbelt.terminal": "0.3.1",
50
+ "@williamthorsen/toolbelt.testing": "0.8.3",
51
+ "@williamthorsen/toolbelt.vitest": "0.13.5",
52
+ "codeassembly": "0.20.2",
53
53
  "esbuild": "0.28.2",
54
54
  "eslint": "10.14.0",
55
55
  "happy-dom": "21.0.4",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "https://unpkg.com/codeassembly-guidance@0.6.0/schemas/preferences.v1.json",
3
+ "$id": "https://unpkg.com/codeassembly-guidance@0.7.0/schemas/preferences.v1.json",
4
4
  "title": "Preferences",
5
5
  "description": "Configuration read by agent skills. Resolved from .agents/preferences.yaml at the project level, with ~/.agents/preferences.yaml as a global fallback.",
6
6
  "type": "object",
@@ -109,19 +109,37 @@
109
109
  },
110
110
  "merge": {
111
111
  "type": "object",
112
- "description": "Squash-merge title rendering configuration for the `merge-pr` skill family.",
112
+ "description": "Merge configuration for the `merge-pr` skill family: approval, merge strategy, branch deletion, and squash-merge title rendering.",
113
113
  "properties": {
114
+ "approval": {
115
+ "type": "string",
116
+ "enum": [
117
+ "ask",
118
+ "auto"
119
+ ],
120
+ "description": "Whether `merge-pr` asks before merging: `ask`, or `auto` to merge without asking only when the run is clean: no notice, no decision of its own, not breaking, and a clean merge state on GitHub. Defaults to `ask`."
121
+ },
114
122
  "title_format": {
115
123
  "type": "string",
116
124
  "description": "Template string used to render the squash-merge commit title. Supports the same token vocabulary as `commit.title_format`, plus `{pr_number}`."
117
125
  },
118
126
  "strategy": {
119
127
  "type": "string",
120
- "description": "Reserved key. Not yet honored by the `merge-pr` skill family — the skill currently performs squash merges unconditionally. Recorded here so the schema does not flag the key as unknown when projects opt to set it in anticipation of future support."
128
+ "enum": [
129
+ "squash",
130
+ "merge",
131
+ "rebase"
132
+ ],
133
+ "description": "How `merge-pr` merges a pull request. Its `--strategy` flag outranks this value. Defaults to `squash`."
121
134
  },
122
- "delete_branch": {
123
- "type": "boolean",
124
- "description": "Reserved key. Not yet honored by the `merge-pr` skill family — branch deletion is currently controlled by command-line flags and platform defaults. Recorded here so the schema does not flag the key as unknown when projects opt to set it in anticipation of future support."
135
+ "deletion_strategy": {
136
+ "type": "string",
137
+ "enum": [
138
+ "both",
139
+ "remote",
140
+ "none"
141
+ ],
142
+ "description": "Which branches `merge-pr` deletes after merging: `both` (GitHub only), `remote`, or `none`. Its `--delete` flag outranks this value. Defaults to `remote`."
125
143
  }
126
144
  }
127
145
  },
@@ -153,7 +171,7 @@
153
171
  },
154
172
  "project": {
155
173
  "type": "object",
156
- "description": "Project identification configuration, and the project's declared stage (`maturity`, `sensitivity`, `audience`), which design guidance treats as premises.",
174
+ "description": "Project identification configuration, and the project's declared stage (`maturity`, `sensitivity`, `audience`, and the `stages` of its subdirectories), which design guidance treats as premises.",
157
175
  "properties": {
158
176
  "audience": {
159
177
  "type": "string",
@@ -167,11 +185,12 @@
167
185
  "maturity": {
168
186
  "type": "string",
169
187
  "enum": [
188
+ "exploration",
170
189
  "hobby",
171
190
  "early",
172
191
  "production"
173
192
  ],
174
- "description": "How far the project has come. `hobby`: built for the owner's own use or learning; breakage costs only the owner's time. `early`: in use by others, but the shape is still changing; downtime is tolerated. `production`: others depend on it; downtime and data loss have real costs. Read from the project preferences file only."
193
+ "description": "How far the project has come. `exploration`: the output's shape is still being found, and nothing depends on it yet. `hobby`: built for the owner's own use or learning; breakage costs only the owner's time. `early`: in use by others, but the shape is still changing; downtime is tolerated. `production`: others depend on it; downtime and data loss have real costs. Read from the project preferences file only."
175
194
  },
176
195
  "scopes": {
177
196
  "type": "array",
@@ -209,6 +228,53 @@
209
228
  "type": "string",
210
229
  "description": "Project identifier used for namespacing artifacts under `{base_dir}/projects/{slug}/`."
211
230
  },
231
+ "stages": {
232
+ "type": "array",
233
+ "description": "Stages that subdirectories declare, overriding the project's for work under them. Each value that an entry leaves undeclared is inherited from the project. When entries are nested, the longest containing path wins. Read from the project preferences file only.",
234
+ "items": {
235
+ "type": "object",
236
+ "properties": {
237
+ "audience": {
238
+ "type": "string",
239
+ "enum": [
240
+ "owner",
241
+ "team",
242
+ "public"
243
+ ],
244
+ "description": "Who uses the subdirectory's output, as `project.audience` defines the values."
245
+ },
246
+ "maturity": {
247
+ "type": "string",
248
+ "enum": [
249
+ "exploration",
250
+ "hobby",
251
+ "early",
252
+ "production"
253
+ ],
254
+ "description": "How far the subdirectory's work has come, as `project.maturity` defines the values."
255
+ },
256
+ "path": {
257
+ "type": "string",
258
+ "minLength": 1,
259
+ "description": "Directory relative to the repository root."
260
+ },
261
+ "sensitivity": {
262
+ "type": "string",
263
+ "enum": [
264
+ "low",
265
+ "personal",
266
+ "confidential"
267
+ ],
268
+ "description": "The most sensitive data that the subdirectory holds, as `project.sensitivity` defines the values."
269
+ }
270
+ },
271
+ "required": [
272
+ "path"
273
+ ],
274
+ "minProperties": 2,
275
+ "additionalProperties": false
276
+ }
277
+ },
212
278
  "ticket_ref_prefix": {
213
279
  "type": "string",
214
280
  "description": "Prefix that appears at the start of `ticket_ref`. Use `#` for GitHub issues (added at render time, omitted from file paths) or a Jira project key like `MAC-` (part of the canonical ticket ID)."
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "https://unpkg.com/codeassembly-guidance@0.6.0/schemas/work-types.v1.json",
3
+ "$id": "https://unpkg.com/codeassembly-guidance@0.7.0/schemas/work-types.v1.json",
4
4
  "additionalProperties": false,
5
5
  "description": "Canonical work-types taxonomy consumed by skill content and downstream changelog/release-notes tooling. Defines the work-type vocabulary, tier grouping, breaking-change policy, changelog-eligibility flags, and cross-cutting section markers (e.g., the breaking-changes indicator).",
6
6
  "properties": {