codeassembly-guidance 0.0.0 → 0.1.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 (204) hide show
  1. package/.meta/changelog.json +563 -0
  2. package/CHANGELOG.md +134 -0
  3. package/LICENSE +7 -0
  4. package/README.md +165 -1
  5. package/content/_partials/README.md +192 -0
  6. package/content/_partials/code-descriptions.md +4 -0
  7. package/content/_partials/code-style.md +7 -0
  8. package/content/_partials/comment-discipline.md +89 -0
  9. package/content/_partials/concision.md +3 -0
  10. package/content/_partials/diff-audit-checklist.md +9 -0
  11. package/content/_partials/file-access.md +4 -0
  12. package/content/_partials/live-repo-writes.md +13 -0
  13. package/content/_partials/plain-speech-calibration.md +66 -0
  14. package/content/_partials/plain-speech.md +13 -0
  15. package/content/_partials/prose-line-breaks.md +3 -0
  16. package/content/_partials/record-marker.md +1 -0
  17. package/content/_partials/reduced-object-relative.md +28 -0
  18. package/content/_partials/shell-commands.md +3 -0
  19. package/content/_partials/target-file-set-resolution.md +22 -0
  20. package/content/_partials/technical-recommendations.md +5 -0
  21. package/content/_partials/test-structure-audit-checklist.md +7 -0
  22. package/content/_partials/ticket-assessment-baseline.md +12 -0
  23. package/content/_partials/ticket-assessment.md +202 -0
  24. package/content/_partials/work-type-choice.md +13 -0
  25. package/content/codeassembly-content.yaml +49 -0
  26. package/content/collections/all.md +11 -0
  27. package/content/collections/atlassian.md +16 -0
  28. package/content/collections/recommended.md +34 -0
  29. package/content/collections/triage.md +77 -0
  30. package/content/collections/williamthorsen.md +25 -0
  31. package/content/guidance/README.md +22 -0
  32. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  33. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  34. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  35. package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
  36. package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
  37. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  38. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  39. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  40. package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
  41. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  42. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  43. package/content/guidance/rulebooks/shell-conventions.md +279 -0
  44. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  45. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
  46. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  47. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  48. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  49. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  50. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  51. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  52. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  53. package/content/guidance/shared/AGENTS.md +43 -0
  54. package/content/scripts/README.md +41 -0
  55. package/content/scripts/describe-change.mjs +165 -0
  56. package/content/scripts/get-ticket-id.sh +131 -0
  57. package/content/scripts/manage-jira-ticket.mjs +209 -0
  58. package/content/scripts/resolve-frontmatter.sh +540 -0
  59. package/content/scripts/resolve-review-run.mjs +12 -0
  60. package/content/scripts/select-lede-exemplars.mjs +208 -0
  61. package/content/skills/_data/action-items.md +83 -0
  62. package/content/skills/_data/artifact-conventions.md +969 -0
  63. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  64. package/content/skills/_data/branch-format.md +34 -0
  65. package/content/skills/_data/change-record.md +163 -0
  66. package/content/skills/_data/complexity-classification.md +58 -0
  67. package/content/skills/_data/concision.md +23 -0
  68. package/content/skills/_data/deployed-file-provenance.md +46 -0
  69. package/content/skills/_data/design-priorities.md +76 -0
  70. package/content/skills/_data/gh-body-file.md +30 -0
  71. package/content/skills/_data/git-commands.md +39 -0
  72. package/content/skills/_data/naming-conventions.md +50 -0
  73. package/content/skills/_data/pr-resolution.md +25 -0
  74. package/content/skills/_data/pr-source-resolution.md +36 -0
  75. package/content/skills/_data/recommendation-gradient.md +90 -0
  76. package/content/skills/_data/scope-and-deferral.md +83 -0
  77. package/content/skills/_data/spike-conventions.md +89 -0
  78. package/content/skills/_data/ticket-evaluation.md +13 -0
  79. package/content/skills/_data/ticket-id-extraction.md +43 -0
  80. package/content/skills/_data/ticket-source-resolution.md +147 -0
  81. package/content/skills/_data/title-templates.md +624 -0
  82. package/content/skills/_data/title-voice.md +17 -0
  83. package/content/skills/_data/work-types.json +168 -0
  84. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  85. package/content/skills/_partials/action-items.md +22 -0
  86. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  87. package/content/skills/_partials/commit-title-rendering.md +14 -0
  88. package/content/skills/_partials/gh-body-file.md +22 -0
  89. package/content/skills/_partials/nested-list-indent.md +9 -0
  90. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  91. package/content/skills/_partials/next-steps-after-review.md +350 -0
  92. package/content/skills/_partials/option-format.md +84 -0
  93. package/content/skills/_partials/plan-template.md +97 -0
  94. package/content/skills/_partials/split-launch-prompts.md +5 -0
  95. package/content/skills/_partials/split-ticket-compose.md +5 -0
  96. package/content/skills/_partials/split-ticket-create.md +3 -0
  97. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  98. package/content/skills/_partials/ticket-concision.md +18 -0
  99. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  100. package/content/skills/_partials/ticket-placement.md +14 -0
  101. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  102. package/content/skills/_partials/ticket-skeleton.md +13 -0
  103. package/content/skills/add-change-record/SKILL.md +136 -0
  104. package/content/skills/add-test-ids/SKILL.md +51 -0
  105. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  106. package/content/skills/anti-patterns/SKILL.md +57 -0
  107. package/content/skills/assess-ticket/SKILL.md +46 -0
  108. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  109. package/content/skills/brainstorming/SKILL.md +107 -0
  110. package/content/skills/capture-event/SKILL.md +108 -0
  111. package/content/skills/capture-event/capture-event.mjs +216 -0
  112. package/content/skills/capture-feedback/SKILL.md +71 -0
  113. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  114. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  115. package/content/skills/classify-complexity/SKILL.md +92 -0
  116. package/content/skills/collaborate/SKILL.md +86 -0
  117. package/content/skills/condense-branch/SKILL.md +83 -0
  118. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  119. package/content/skills/create-commit/SKILL.md +65 -0
  120. package/content/skills/create-devlog/SKILL.md +108 -0
  121. package/content/skills/create-gh-pr/SKILL.md +106 -0
  122. package/content/skills/create-pr/SKILL.md +150 -0
  123. package/content/skills/create-ticket/SKILL.md +350 -0
  124. package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
  125. package/content/skills/design-and-plan/SKILL.md +194 -0
  126. package/content/skills/development-workflows/SKILL.md +41 -0
  127. package/content/skills/get-ticket-id/SKILL.md +67 -0
  128. package/content/skills/groom-backlog/SKILL.md +245 -0
  129. package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
  130. package/content/skills/implement-plan/SKILL.md +164 -0
  131. package/content/skills/index-prototypes/SKILL.md +145 -0
  132. package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
  133. package/content/skills/kb-add/SKILL.md +156 -0
  134. package/content/skills/kb-add/kb-add.mjs +216 -0
  135. package/content/skills/kb-curate/SKILL.md +117 -0
  136. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  137. package/content/skills/kb-edit/SKILL.md +128 -0
  138. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  139. package/content/skills/kb-retrieve/SKILL.md +100 -0
  140. package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
  141. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  142. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
  143. package/content/skills/kb-update-events/SKILL.md +77 -0
  144. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  145. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  146. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  147. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  148. package/content/skills/merge-pr/SKILL.md +368 -0
  149. package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
  150. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  151. package/content/skills/people-report/SKILL.md +208 -0
  152. package/content/skills/plan/SKILL.md +87 -0
  153. package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
  154. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  155. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
  156. package/content/skills/refine-plan/SKILL.md +259 -0
  157. package/content/skills/respond-to-review/SKILL.md +292 -0
  158. package/content/skills/review-bb-pr/SKILL.md +161 -0
  159. package/content/skills/review-branch/SKILL.md +301 -0
  160. package/content/skills/review-criteria/SKILL.md +108 -0
  161. package/content/skills/review-gh-pr/SKILL.md +155 -0
  162. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  163. package/content/skills/review-permissions/SKILL.md +39 -0
  164. package/content/skills/review-pr/SKILL.md +123 -0
  165. package/content/skills/revise-comments/SKILL.md +115 -0
  166. package/content/skills/revise-prose/SKILL.md +197 -0
  167. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  168. package/content/skills/save-artifact/SKILL.md +69 -0
  169. package/content/skills/save-plan/SKILL.md +55 -0
  170. package/content/skills/software-engineering/SKILL.md +74 -0
  171. package/content/skills/streamline-guidance/SKILL.md +174 -0
  172. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  173. package/content/skills/summarize-change/SKILL.md +308 -0
  174. package/content/skills/summarize-chat/SKILL.md +100 -0
  175. package/content/skills/systematic-debugging/SKILL.md +308 -0
  176. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  177. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  178. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  179. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  180. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  181. package/content/skills/systematic-debugging/test-academic.md +16 -0
  182. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  183. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  184. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  185. package/content/skills/testing-conventions/SKILL.md +168 -0
  186. package/content/skills/testing-conventions/mistakes.md +1 -0
  187. package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
  188. package/content/skills/update-jira-ticket/SKILL.md +245 -0
  189. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  190. package/content/skills/update-project-guidance/SKILL.md +300 -0
  191. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  192. package/content/skills/wrap-up/SKILL.md +431 -0
  193. package/content/subagents/_data/claude.yaml +19 -0
  194. package/content/subagents/_data/rovo.yaml +31 -0
  195. package/content/subagents/canary.md +11 -0
  196. package/content/subagents/entry-drafter.md +187 -0
  197. package/content/subagents/handoff-reviewer.md +75 -0
  198. package/content/subagents/plan-reviewer.md +184 -0
  199. package/content/subagents/plan-reviser.md +88 -0
  200. package/content/subagents/prose-reviser.md +130 -0
  201. package/content/subagents/ticket-assessor.md +139 -0
  202. package/package.json +70 -2
  203. package/schemas/preferences.v1.json +294 -0
  204. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,368 @@
1
+ ---
2
+ name: merge-pr
3
+ description: Merge a pull request by composing a merge-commit message, validating PR state, and delegating to the platform's merge API
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Merge pull request
8
+
9
+ Merge a pull request on the appropriate platform. `describe-change.mjs` resolves the merge-commit title and body from the PR's `change-record` block, its commits, and its curated description; this skill presents what it resolves at an approval gate, then delegates the actual merge to a platform-specific skill (`merge-gh-pr` or `merge-bb-pr`).
10
+
11
+ ## Optional arguments
12
+
13
+ | Flag | Effect | Default |
14
+ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
15
+ | `--pr {n}` | Merge PR `{n}` instead of the PR for the current branch. | PR for the current branch |
16
+ | `--scope {scope}` | Override the scope. Outranks the PR's `change-record` block and every other source; `*` merges without a scope. | resolved in step 3 |
17
+ | `--type {type}` | Override the work type, spelled bare (`feat`, not `feat!`). Outranks the PR's `change-record` block and every other source, and keeps the resolved marker. | resolved in step 3 |
18
+ | `--breaking`, `--no-breaking` | Merge as breaking, or as not breaking. Outranks the PR's `change-record` block and every other source. | resolved in step 3 |
19
+ | `--strategy {s}` | Override the merge strategy: `squash`, `merge`, or `rebase`. | `squash` |
20
+ | `--delete {v}` | Override branch deletion: `both`, `remote`, or `none`. `both` is GitHub-only. | `remote` |
21
+
22
+ ## Reserved preference keys
23
+
24
+ `merge.strategy` and `merge.deletion_strategy` are **reserved keys** in `.agents/preferences.yaml` and `~/.agents/preferences.yaml`. They are not yet honored: This iteration uses the hard-coded defaults above. Setting them in preferences does not change the merge; CLI overrides are the only way to change the values today.
25
+
26
+ ## Process
27
+
28
+ ### 1. Get session context
29
+
30
+ Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash. The bundle emits the session-context manifest JSON to stdout; extract `ticket_ref`, `branch_name`, `default_branch`, `scm`, `project_slug`, `ticket_id`, `artifact_base_dir`, and `pr_url` from it.
31
+
32
+ ### 2. Resolve the PR
33
+
34
+ Resolve the PR to merge per [PR source resolution](../_data/pr-source-resolution.md#runtime-resolution-path-add-change-record-review-pr-merge-pr): An explicit `--pr {n}` overrides; otherwise a stored `pr_url` from session context is the default; otherwise discover the PR for the current branch. Persist the resolved URL via `--set-pr-url`, and invalidate (`--clear-pr-url`) and re-resolve a stored URL that does not yield the expected PR.
35
+
36
+ Read the PR's metadata for the steps below, dispatching on `scm`:
37
+
38
+ - **`"github"`**:
39
+
40
+ ```bash
41
+ gh pr view {pr} --json number,title,body,labels,headRefName,headRefOid,baseRefName,isCrossRepository,url
42
+ ```
43
+
44
+ - **`"bitbucket"`**: Issue an `action: "get"` call per [Bitbucket pull-request access](../_data/bitbucket-pr-access.md), then map its fields onto the same names that the steps below use: `description` to `body`, `source.branch.name` to `headRefName`, `source.commit.hash` to `headRefOid`, `destination.branch.name` to `baseRefName`, `links.html.href` to `url`, and an empty array to `labels`. `isCrossRepository` is true when `source.repository.full_name` names a repository other than the PR's own.
45
+ - **Unknown or missing**: Ask the user which platform to use, matching step 7's behavior.
46
+
47
+ If this step cannot resolve or discover a PR, stop with: "No open PR found for branch `{branch_name}`. Create one with `{skill:create-pr}` first."
48
+
49
+ Capture `title` (PR title), `body` (PR body), `labels` (label objects), `number`, `headRefName` (head branch), `headRefOid` (head commit), `baseRefName` (base branch), and `isCrossRepository` from the response. The steps below use them.
50
+
51
+ Then fetch the PR's base branch and head, so that step 3 reads the PR's own commits whichever branch is checked out. `{remote}` is the remote that `default_branch` names (`origin` in `origin/main`):
52
+
53
+ ```bash
54
+ git fetch {remote} {baseRefName} {headRefName}
55
+ ```
56
+
57
+ For a GitHub PR whose `isCrossRepository` is true, fetch `pull/{number}/head` in place of `{headRefName}`. A Bitbucket fork's head cannot be fetched from `{remote}`, so fetch the base branch alone. A failed fetch does not stop the merge: Step 3 reports a head commit that it cannot read, and resolves without the commits.
58
+
59
+ ### 3. Resolve the merge
60
+
61
+ `describe-change.mjs` resolves the effective record, the merge-commit title, and the body in one run, by the rules in [Where the record is read](../_data/change-record.md#where-the-record-is-read). This step runs it and resolves nothing by itself.
62
+
63
+ Write the PR body to a scratch file per [gh body file](#gh-body-file), naming it `gh-body-pr{number}-{timestamp}.md`. On GitHub, write it from the platform, so that the file contains the body byte for byte:
64
+
65
+ ```bash
66
+ gh pr view {pr} --json body --jq '.body' > "{body_file}"
67
+ ```
68
+
69
+ On Bitbucket, write the `description` from step 2 to the file verbatim.
70
+
71
+ Then run the helper, opening with the assignment and the guard:
72
+
73
+ ```bash
74
+ body_path="{absolute path from the write step}"
75
+ [ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
76
+ node {harness_home_dir}/scripts/describe-change.mjs resolve-merge \
77
+ --base "{remote}/{baseRefName}" \
78
+ --head "{headRefOid}" \
79
+ --pr-number "{number}" \
80
+ --pr-title "{title}" \
81
+ --pr-body-file "$body_path" \
82
+ [--pr-label "{label_1}" --pr-label "{label_2}" ...] \
83
+ [--ticket-ref "{ticket_ref}"] \
84
+ [--override-scope "{scope}"] [--override-type "{type}"] [--override-breaking | --no-override-breaking] \
85
+ [--override-title "{title}"]
86
+ ```
87
+
88
+ The guard keeps a failed read out of the merge. The redirect above truncates the file before `gh` writes, so a failed read leaves it empty, and an empty body does not contain a `## What` or a `change-record` block: The helper would resolve the effective record from the labels alone, step 5 would dispatch the drafter, and the offer below would propose adding a block to a body that was never read. If the guard refuses, stop.
89
+
90
+ Pass each PR label from step 2 as a separate `--pr-label` flag. Pass `--ticket-ref` only when `ticket_ref` from session context is non-null and `headRefName` is `branch_name`, since a PR merged from another branch's checkout belongs to another ticket; the helper uses that reference only when the PR title contains none. Pass this skill's `--scope`, `--type`, `--breaking`, and `--no-breaking` as `--override-scope`, `--override-type`, `--override-breaking`, and `--no-override-breaking`, omitting each one that was not given.
91
+
92
+ If this step's first run exits non-zero, or the helper is not found, stop with its message. Do not compose a title or body without it. Step 8's re-read stops the same way, since the failure there does not come from any answer.
93
+
94
+ A re-run driven by a decision or an answer at step 6's gate does not stop the skill, and neither does a refused `amend-entry`. Report the helper's message and return to the decision or the question that produced the value: The refusal is in the value, and the resolution already in hand is still good. A type spelled with `!` is that case, which step 6 maps rather than passes through.
95
+
96
+ The helper prints one JSON object. Read it from the command's output, with python3 (or jq) when a parser helps:
97
+
98
+ - `effective_record`: the effective `title`, `scope`, `type`, `breaking`, `ticket_ref`, and `pr_number`.
99
+ - `effective_sources`: the source that supplied each field of `effective_record` apart from `pr_number`, such as `block`, `commits`, `labels`, `pr_title`, or `flags`.
100
+ - `merge_title`: the rendered merge-commit title, which includes the breaking marker.
101
+ - `body`: the PR's `## What` section, without the `change-record` block and without the `Closes` line.
102
+ - `merge_block`: the `change-record` block that the merge body contains below the lede, rendered from the PR block's change entries, or `null` when the PR block records none.
103
+ - `entry_count`: the number of change entries that `merge_block` records, `0` when it is `null`.
104
+ - `sources`: what the block, the commits, the labels, and the PR title each name, whether or not the resolution used them, each `null` if it was not read.
105
+ - `defects`: each condition that the author must settle before approval. A defect naming an `entry` is a change entry's, identified by its 0-based index, and settled by amending that entry; any other is `effective_record`'s, settled by an override.
106
+ - `notices`: what the gate shows beside the proposal.
107
+
108
+ [`resolve-merge`](../_data/title-templates.md#resolve-merge) states every field.
109
+
110
+ The overrides passed to this run are the merge's **override set**. Each later run of this step, for a choice at the gate or for step 8's re-read, passes the whole set with that run's addition, and the same `--head`.
111
+
112
+ **When the first run's `notices` contains `absent-block`, offer to add the block, if this checkout can draft it.** The pull request does not contain a change record, so the merge would not publish any change entries. `{skill:add-change-record}` drafts the entries from `{default_branch}...HEAD`, and refuses when HEAD is not the pull request's head commit, so read the local head before offering:
113
+
114
+ ```bash
115
+ git rev-parse HEAD
116
+ ```
117
+
118
+ When it is not `headRefOid`, do not make the offer: This checkout describes other commits, and the merge of a pull request from another branch's checkout is a case that this skill supports. Carry the notice to the gate at step 6 and name the checkout there as the reason for not drafting a block here.
119
+
120
+ When it is `headRefOid`, ask once, naming that consequence and saying that the offer runs `{skill:summarize-change}` to draft the entries:
121
+
122
+ ```
123
+ PR #{number} does not contain a change record, so the merge would not publish any change entries. Draft the entries and add the block? This runs `{skill:summarize-change}`. 👍🏼👎🏼
124
+ ```
125
+
126
+ On yes, invoke `{skill:add-change-record}` with `--pr {number}`. Then write a fresh body file from the platform as this step does and run the helper again, with the same override set and the same `--head`. A failure there stops the skill as the first run does, since the failure does not come from any answer.
127
+
128
+ On no, and when `{skill:add-change-record}` stopped for any of its own reasons, continue with the report that the first run produced. The gate at step 6 then reports the notice.
129
+
130
+ ### 4. Resolve strategy and deletion strategy
131
+
132
+ ```
133
+ resolveStrategy(cliOverride): return cliOverride ?? 'squash'
134
+ resolveDeletionStrategy(cliOverride): return cliOverride ?? 'remote'
135
+ ```
136
+
137
+ `--delete both|remote|none` map directly to the same string values.
138
+
139
+ Refuse here when `scm` is `"bitbucket"` and the resolved deletion strategy is `both`, before step 6 asks for anything. Stop with:
140
+
141
+ <!-- include: ../_partials/bitbucket-delete-both-refusal.md / -->
142
+
143
+ ### 5. Compose merge-commit body
144
+
145
+ The report's `body` is the merge-commit **lede** candidate. The published body is that lede followed by the report's `merge_block`, which the last part of this step composes.
146
+
147
+ A lede is **thin** if it is empty or contains fewer than 30 characters of non-whitespace content. The 30-character threshold is a default heuristic; proceed with a shorter lede if it is clearly intentional and self-contained (e.g., "Cosmetic only.", "Reverts #418.").
148
+
149
+ If the lede is thin, compose fresh content through the drafter that `summarize-change` dispatches, rather than writing it here. The drafter contains the lede doctrine.
150
+
151
+ Resolve the tier by looking up the report's `effective_record.type` in [work-types.json](../_data/work-types.json).
152
+
153
+ If `defects` contains an entry defect, settle every entry defect here as step 6 does, since an amended entry can change the effective record. Then, if `defects` shows that the effective record does not declare a type (`missing-type`, or an `undeclared-type` that does not name an `entry`), decide the type here as step 6 does rather than composing against a guess, then re-run step 3 with that type added to the override set and resolve the tier from the new report.
154
+
155
+ Dispatch the `{subagent:entry-drafter}` subagent via the {tool:Task} tool with this block:
156
+
157
+ ```dispatch
158
+ type: {resolved type}
159
+ tier: {resolved tier}
160
+ ticket-source: {ticket URL or reference}
161
+ ```
162
+
163
+ The block contains scalars only, and only these keys. Do not compose any prose into it: The drafter gathers every fact itself, and a sentence written here introduces this session's weighting into the draft. Read its `## Report` for any source that it could not access.
164
+
165
+ The lede is the drafter's `## Lede` section. The merge publishes the entries themselves in `merge_block`, so nothing here renders them.
166
+
167
+ **Compose the published body**: the lede, a blank line, and the report's `merge_block` verbatim.
168
+
169
+ ```
170
+ {lede}
171
+
172
+ {merge_block}
173
+ ```
174
+
175
+ Append `merge_block` to whichever lede is used, the drafted one included, since it comes from the PR's block rather than from the body. A report whose `merge_block` is `null` publishes the lede alone, without a blank line after it.
176
+
177
+ Do not audit the draft here: The user reads the published body at the approval gate in step 6, before anything is published.
178
+
179
+ <!-- include: ../_partials/nested-list-indent.md / -->
180
+
181
+ ### 6. Approval gate
182
+
183
+ Settle every item in `defects` before showing the proposal. Settle the entry defects first, in entry order: Amending an entry can change the effective record, and with it the record's own defects. Decide each type and each marker by the test below and the type's `breakingPolicy`, never by asking which to choose: This session holds the diff, the sources, and the test, and the gate's title shows the result before the merge.
184
+
185
+ **An entry defect** (one that names an `entry`) is settled by amending that entry in the PR body, because an override changes only the effective record, and the merge block would still publish the entry as it stands. Decide each amendment: For an `undeclared-type`, the type that the test below assigns to the entry's own text; for a `policy-violation`, the same test's type, with the marker kept when that type's `breakingPolicy` permits it and dropped otherwise. The amendments rewrite the PR body, which is remote shared state, so ask once to authorize all of them: Quote each entry's `text` from `sources.block.entries`, name its defect, and state the decided type or marker with its reason in one line. A no is a redirect, not a request for a menu: Take the type or marker that the developer names in place of the decided one.
186
+
187
+ On approval, re-read the PR body into a fresh scratch file as step 3 writes one, named `gh-body-pr{number}-amend-{timestamp}.md`: from the platform on GitHub, and on Bitbucket from a fresh read of the description through step 2's platform dispatch. The approval is human-paced, so the copy that step 3 read can be older than the PR, and writing it back would discard an edit made while the ask was pending. Then amend each entry in that file, opening each call with the assignment and the guard. Pass `--type` when the amendment changes the type, and `--breaking` or `--no-breaking` when it changes the marker:
188
+
189
+ ```bash
190
+ body_path="{absolute path from the re-read}"
191
+ [ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
192
+ node {harness_home_dir}/scripts/describe-change.mjs amend-entry \
193
+ --body-file "$body_path" \
194
+ --entry "{entry}" \
195
+ [--type "{type}"] [--breaking | --no-breaking]
196
+ ```
197
+
198
+ The helper rewrites the file in place and refuses an amendment that would leave the entry defective. [`amend-entry`](../_data/title-templates.md#amend-entry) states its refusals. Then write the amended body to the PR:
199
+
200
+ - **`"github"`**: `gh pr edit {number} --body-file "$body_path"`, in a call that opens with the same assignment and guard.
201
+ - **`"bitbucket"`**: [Bitbucket pull-request access](../_data/bitbucket-pr-access.md) does not document a description-write action. Stop, showing the amended `change-record` block from the body file and saying that the author pastes it over the description's block in the Bitbucket UI, then runs the merge again.
202
+
203
+ Then re-run step 3 with the same override set and the same `--head`. Its fresh read of the body confirms that the amendment reached the PR.
204
+
205
+ **A defect of the effective record** is settled by an override, which changes nothing outside this run, so decide it without an ask and state the decision in one line with its reason:
206
+
207
+ - **`missing-type` or `undeclared-type`**: Add `--override-type` with the type that the test below assigns to the diff.
208
+ - **`policy-violation`**: Add `--override-type` with the test's type when it differs from the record's, and `--no-override-breaking` when that type's `breakingPolicy` forbids the marker.
209
+
210
+ Decide each type by applying this test to the change, whether the diff or an entry's own text, not by how many sources name the type:
211
+
212
+ <!-- include: ../../_partials/work-type-choice.md / -->
213
+
214
+ Apply the test to the diff whether or not `defects` holds an item. Commits, labels, and a PR title that agree can agree on one wrong type, which does not raise a defect, and the merge title would then publish that type. When the test's type differs from the effective record's, add `--override-type` with the test's type to the override set and state the decision in one line with its reason; when they agree, report nothing, here or at the gate.
215
+
216
+ A type that the developer named, through `--type` or in an answer at the gate, stands: Never replace it with the test's type, here or in a record defect above: The gate shows the type so that the developer can correct it, and replacing the correction leaves the developer unable to merge under it. When the test disagrees with it, state the disagreement in one line at the gate and change nothing.
217
+
218
+ Take a type spelled with the marker, whether decided here or named by the developer, as the pair that the flags imply: `feat!` is `--override-type feat` with `--override-breaking`, and for an entry, `--type feat` with `--breaking`. The helper refuses a type spelled with `!`, so it would refuse such a type passed through unchanged, and the defect would stay unsettled.
219
+
220
+ When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
221
+
222
+ Re-run step 3 after each amendment and each override, with every override added to the override set, until `defects` is empty. Never offer the merge while `defects` contains an item. If an override or an amendment moves the effective record to another tier and step 5 drafted the body, re-run step 5's drafting against the new tier.
223
+
224
+ Render the proposed merge to the user:
225
+
226
+ ```
227
+ Proposed merge for PR #{pr_number}:
228
+
229
+ Title: ▶︎ {merge_title} ◀︎
230
+ Strategy: {strategy}
231
+ Delete: {deletion_strategy}
232
+
233
+ ▼ Body
234
+ {published body}
235
+ ▲
236
+
237
+ {notices}
238
+
239
+ {confirmation}
240
+ ```
241
+
242
+ `{published body}` is step 5's composed whole, the lede and its `change-record` block together. The triangle delimiters wrap the title and body, the parts that will actually be published, and a squash merge writes them to a protected default branch where they cannot be amended.
243
+
244
+ **Between the closing `▲` and `{confirmation}`, report only what is wrong.** A line belongs there only when it names a condition that blocks or complicates the merge: a notice, a failing or pending check, or a defect in the published body, such as a typo that the merge commit would publish verbatim. The user reads silence as a clean merge, so never report an absence: Do not write a line for an empty `defects` or `notices`, a mergeable state, passing checks, or sources that agree. An empty `{notices}` renders nothing, and a clean run shows the proposal followed directly by `{confirmation}`. Do not write a line that restates a value that the triangles already show, such as the scope, type, or breaking marker in the title.
245
+
246
+ Render each notice there as one line. When a line says where a field came from, name the source that `effective_sources` gives for that field:
247
+
248
+ - **`absent-block`**: The PR does not contain a `change-record` block, so the merge does not publish any change entries, and the effective record comes from the sources that `effective_sources` names field by field.
249
+ - **`malformed-block`**: The PR's `change-record` block cannot be read (its `defect`), so the labels and the commits resolved the effective record.
250
+ - **`commits-unavailable`**: The commits were not read (its `reason`), so when the block does not record any entries, the effective record comes from the labels alone.
251
+ - **`pr-title-divergence`**: The PR title's prefix differs from the proposal on the fields that the notice's `fields` lists. Name the prefix's values for those fields, read from `sources.pr_title`.
252
+ - **`pr-title-unparsed`**: The PR title did not parse, so the title comes from the source that `effective_sources.title` names.
253
+ - **`malformed-entries`**: The block's entry list cannot be read (its `defect`), so the block does not record any entries, and the labels and the commits resolved the base record. Its title and overrides still stand.
254
+ - **`stale-entries`**: The block's entries were derived at the commit that the notice's `entries_commit` names, `null` when the block records none, and not at the head that its `head_commit` names, so commits pushed since then may not be described by the entries, whose record still stands.
255
+
256
+ **A `stale-entries` notice is reported and nothing is re-derived.**
257
+
258
+ A `pr-title-divergence` notice names values that the user can merge under instead, and the title is theirs to replace. If the user answers the gate with such values or a new title rather than a clear approval or decline, add them to the override set (a scope as `--override-scope`, `*` to merge without a scope, a type as `--override-type`, a marker as `--override-breaking` or `--no-override-breaking`, and a title as `--override-title`), re-run step 3, settle any new defect, and render this gate again.
259
+
260
+ Render `{confirmation}` so that the ask itself names every destructive side effect that the approval authorizes. The permission auto-classifier grants only what the ask text names, so a branch deletion shown only in the `Delete:` line above is not authorized; the ask must name it too:
261
+
262
+ - `none` → `Merge PR #{pr_number}? 👍🏼👎🏼`
263
+ - `remote` → `Merge PR #{pr_number} and delete the remote branch {headRefName}? 👍🏼👎🏼`
264
+ - `both` → `Merge PR #{pr_number} and delete the local and remote branch {headRefName}? 👍🏼👎🏼`
265
+
266
+ Under a `stale-entries` notice, open the ask with `The change record is stale. ` so that the approval names what it accepts: `The change record is stale. Merge PR #{pr_number}? 👍🏼👎🏼`. Under an `absent-block` notice, open it with `The pull request does not contain a change record. ` in the same way.
267
+
268
+ If the user declines, stop without making an API call or writing an artifact. If they approve, continue.
269
+
270
+ <!-- include: ../_partials/action-items.md / -->
271
+
272
+ ### 7. Detect platform and select delegate
273
+
274
+ Read `scm` from session context:
275
+
276
+ - `"github"` → delegate to `{skill:merge-gh-pr}`
277
+ - `"bitbucket"` → delegate to `{skill?:merge-bb-pr}`
278
+ - Unknown or missing → ask the user which platform to use
279
+
280
+ ### 8. Re-read the PR and re-confirm a changed title or body
281
+
282
+ This step exists because a published merge-commit title and body cannot be amended on a protected default branch under a squash merge. The approval gate is human-paced, so an edit made to the PR while it is pending would otherwise be discarded and the merge would publish the pre-gate text irrecoverably. Do not fold this read back into step 2: A single pre-gate read leaves that window open.
283
+
284
+ Re-read the PR's `title` and `description` (or `body` on GitHub) using step 2's platform dispatch, then re-run step 3 over them: a fresh body file, the new title, the `headRefOid` read in step 2, and the override set as settled at the approval gate. Then compare the two values that the merge publishes:
285
+
286
+ - **Title**: Compare the new `merge_title` with the approved one.
287
+ - **Lede**: Compare the new report's `body` with the `body` of the report behind the body that the user most recently approved. If it changed, re-run step 5 over it in full, the thin-lede fallback included, so that a description that has since gained a real `## What` is picked up. Advance the baseline with each approval, as for the title; if it stayed at the pre-gate report, every pass would re-run the fallback and the loop would never converge.
288
+ - **Merge block**: Compare the new report's `merge_block` with the approved report's, as strings. If it changed and the lede did not, recompose the published body from the approved lede and the new `merge_block`, without dispatching the drafter, since the lede is unaffected.
289
+
290
+ If neither the lede nor the merge block changed, keep the approved body.
291
+
292
+ If the new report contains a defect, return to step 6 and settle it before comparing.
293
+
294
+ The lede comparison keys on the report's `body` rather than on the composed lede because step 5's thin-lede fallback composes fresh prose, which does not reproduce word for word from one run to the next. Comparing composed output would report a change on every pass, and the loop below would never reach a fixed point. The helper's extraction is deterministic, so it has one. Keying on the `## What` section rather than on the whole description also means an edit confined to another section raises nothing, which is correct: Nothing outside `## What` appears in the merge commit.
295
+
296
+ The merge block takes a comparison of its own because `body` excludes the `change-record` block: An edit confined to that block leaves `body` identical while changing what the merge publishes, and `merge_title` catches only the subset of such edits that move the record ranked from the entries. `merge_block` is rendered by the helper rather than drafted, so comparing it has the fixed point that the lede comparison needs `body` to supply.
297
+
298
+ The window that this step closes is an edit to the PR's title or description. New commits pushed to the branch are not in scope: The re-run reads the commits up to the head commit read in step 2, and a generated body is not recomposed on account of later commits. The delegate's own branch-sync check reports local and remote divergence.
299
+
300
+ If every re-read value matches the approved one, continue to step 9 without saying anything. If any differs, re-render step 6's gate with the new values and ask again, and repeat this step after each approval until the values stop changing. Merging the newest version silently would publish text that the user never approved, which is the same defect from the other direction. If the user declines, stop without merging or writing an artifact, exactly as step 6 does.
301
+
302
+ ### 9. Check the published body
303
+
304
+ The merge commit is the record from which release-kit reads the change entries, and it rejects a whole block on any defect, so read the approved body back before publishing it. Write the published body to a scratch file per [gh body file](#gh-body-file), naming it `gh-body-pr{pr_number}-check-{timestamp}.md`, then run the helper with the approved report's `entry_count`, opening with the assignment and the guard:
305
+
306
+ ```bash
307
+ body_path="{absolute path from the write step}"
308
+ [ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
309
+ node {harness_home_dir}/scripts/describe-change.mjs check-merge-body \
310
+ --body-file "$body_path" \
311
+ --entry-count "{entry_count}"
312
+ ```
313
+
314
+ The helper refuses a body whose block is malformed, or whose entry count differs from `--entry-count`. A count of `0` requires the body not to contain a block. [`check-merge-body`](../_data/title-templates.md#check-merge-body) states the rules.
315
+
316
+ If it exits non-zero, stop with its message. Nothing is merged.
317
+
318
+ ### 10. Call delegate
319
+
320
+ Pass the following inputs to the selected delegate per the delegate interface:
321
+
322
+ | Input | Value |
323
+ | ------------------- | -------------------------------------------------------------------- |
324
+ | `pr_number` | Resolved PR number |
325
+ | `title` | Rendered `merge_title` as step 8 last resolved and the user approved |
326
+ | `body` | Published body as step 8 last resolved and the user approved |
327
+ | `strategy` | Resolved strategy from step 4 |
328
+ | `deletion_strategy` | Resolved value from step 4 (`both` \| `remote` \| `none`) |
329
+ | `ticket_id` | From session context |
330
+ | `project_slug` | From session context |
331
+ | `artifact_base_dir` | From session context |
332
+
333
+ The orchestrator never passes a title that `defects` blocks, or a `prompt` sentinel, to the delegate: All values are concrete by this point.
334
+
335
+ If the delegate stopped or failed, stop. Otherwise continue.
336
+
337
+ ### 11. Report the outcome
338
+
339
+ Report nothing beyond the delegate's completion report, and invoke nothing but step 12's offer to close the parent. The merge flow does not record a lede decision or offer to record one; a capture is the author's own request, made whenever they choose.
340
+
341
+ ### 12. Offer to close the parent
342
+
343
+ A parent ticket stays open when its last child closes, so offer to close it when this merge closed that child. Skip this step silently when `scm` is not `"github"`, since the check reads GitHub's sub-issues, or when `effective_record.ticket_ref` from step 3 is null or is not a GitHub `#{N}` reference. Take the ticket from that field rather than from session context: It names the ticket that the merge commit closes, and session context names the current branch's ticket, which is another one when `--pr` merges another branch's PR. Otherwise read the merged ticket's parent:
344
+
345
+ ```bash
346
+ node {harness_home_dir}/skills/groom-backlog/groom-backlog.mjs parent-status --ticket {N}
347
+ ```
348
+
349
+ The command writes nothing. Act on its result:
350
+
351
+ - **`ok: false`**: Report its `message` in one line and offer nothing.
352
+ - **`offer` is false**: Say nothing. The ticket does not have a parent, the parent is closed, another child is open, or the merge left the ticket open.
353
+ - **`offer` is true**: Ask in the closing [action-items block](../_data/action-items.md): "Close parent #{P} ({title}), whose children are all closed? 👍🏼👎🏼", with `{P}` and `{title}` from the result's `parent`. When `parent.uncheckedCriteria` is not empty, list each criterion beneath the question, so that the user does not close a parent whose own criteria are unmet. Closing a ticket is remote shared state, so close nothing without a clear yes. On a clear yes, close it with a comment that names the last child and `effective_record.pr_number`:
354
+
355
+ ```bash
356
+ gh issue close {P} --reason completed --comment "Every child is closed; #{N} closed last, merged in #{pr_number}."
357
+ ```
358
+
359
+ ## Important
360
+
361
+ - The orchestrator owns every decision that it presents (PR resolution, strategy and deletion strategy, body composition, the approval gate), and `describe-change.mjs` owns the resolution of the effective record, the merge title, and the body. Delegates own only execution (platform API calls + state validation).
362
+ - Local state is intentionally untouched after the merge. The delegate deletes the branch on the remote per the resolved decision; the local working copy and current branch are not modified. In the default `remote` mode, `merge-gh-pr`'s bundled helper deletes the remote branch once the PR is merged; `both` mode passes `--delete-branch` to `gh pr merge`, which is incompatible with worktree-based workflows: `gh pr merge --delete-branch` fails when the base branch is checked out in another worktree. On Bitbucket, `both` does not have any counterpart and `merge-bb-pr` refuses it, naming `--delete remote` as the alternative.
363
+ - Never bypass branch protections. The orchestrator does not expose `--admin`; users who need that capability run `gh pr merge --admin` directly.
364
+ - Never list automated checks (formatting, linting, typechecking, unit tests) in the merge body. They run automatically in CI.
365
+
366
+ <!-- include: ../_partials/gh-body-file.md / -->
367
+
368
+ <!-- include: ../_partials/option-format.md / -->
@@ -0,0 +1,136 @@
1
+ ---
2
+ name: migrate-feedback-memories
3
+ description: Route this machine's per-project feedback memories to their proper home (capture the propagating ones as capture-feedback candidates, delete the redundant, retain the genuinely local) via a bundled enumerator with a confirm-by-default batch flow and an --auto escape hatch
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Migrate feedback memories
8
+
9
+ Route every `feedback`-type agent memory on this machine to its proper home. A bundled helper does the mechanical work: It enumerates feedback memories across every memory store, and executes deletions with `MEMORY.md` reconciliation. You do the judgment work: Classify each memory, dedup capture candidates against the knowledge base, and compose each capture.
10
+
11
+ A **memory store** is one project's memory directory under `~/.claude/projects/`. It is not a **KB store** (the `~/.agents/kb.yaml` registry entry that `capture-event` and the `kb-*` skills select with `--store`). This procedure uses both: The helper's `--memory-store` names the origin (step 1), and `capture-event`'s `--store` names the destination (step 5).
12
+
13
+ The three destinations:
14
+
15
+ - **Capture**: A generalizable lesson that should propagate is recorded as a `capture-feedback`-style candidate event in the feedback KB (the registry's `feedback_kb`), and the source memory is then removed from its store; a capture migrates the memory out, it does not copy it. A later distillation pass codifies the event into shared guidance.
16
+ - **Retain**: A genuinely local, non-propagating fact (a project-specific deadline or quirk) stays a memory, untouched.
17
+ - **Delete**: A memory already captured (including one migrated from another machine) or otherwise redundant is removed.
18
+
19
+ The split is deliberate: The helper is narrow and mechanical (it never classifies); the routing is wide and judgment-driven.
20
+
21
+ **Announce at start:** "Using migrate-feedback-memories to route this machine's feedback memories."
22
+
23
+ ## Arguments
24
+
25
+ | Argument | Description | Required |
26
+ | ----------------------- | -------------------------------------------------------------------------------------------------------- | -------- |
27
+ | `--auto` | Skip the batch-review confirmation and execute the inferred routing. Dedup still runs. | No |
28
+ | `--memory-store <name>` | Scope the run to a single memory store, by directory name or project label. Omit to process every store. | No |
29
+
30
+ You act on the `--auto` flag, which controls whether you present the routing plan before executing; the helper never receives it. `--memory-store <name>` passes through to the enumerator (both `--memory-store x` and `--memory-store=x` are accepted); use it to process one store per invocation on a machine with many memories, because you classify more accurately in a fresh, single-project context than in one run that covers every store.
31
+
32
+ ## Runtime dependencies
33
+
34
+ - **`node` ≥ 24**: The bundled helper has the same Node version floor as `@williamthorsen/kb`.
35
+
36
+ ## Modes
37
+
38
+ - **Default mode**: Enumerate, classify, dedup, present the routing plan, and execute only after confirmation.
39
+ - **Auto mode (`--auto`)**: Enumerate, classify, dedup, and execute silently, without confirmation.
40
+
41
+ ## Process
42
+
43
+ ### 1. Enumerate
44
+
45
+ Run the helper's `enumerate` subcommand (it is read-only):
46
+
47
+ ```bash
48
+ node {harness_home_dir}/skills/migrate-feedback-memories/feedback-memories.mjs enumerate [--memory-store <name>]
49
+ ```
50
+
51
+ Omit `--memory-store` to enumerate every store on the machine; pass `--memory-store <name>` to scope the run to one store. The name is either the directory name reported in each memory's `memoryStore` field, or the project label printed by the `list` subcommand (`configs-macos` rather than `-Users-me-repos-configs-macos`); prefer the directory name when you have it, since it is unambiguous. For a value that does not name a store, `enumerate` returns `{ ok: false, error: 'no-such-memory-store' }`, and for a label shared by two stores it returns `{ ok: false, error: 'ambiguous-memory-store' }` listing them, so a mistyped or ambiguous name fails loudly rather than looking like an already-clean store.
52
+
53
+ It prints `{ ok, machine, projectsRoot, memories, skipped }`. Each entry in `memories` includes `path`, `memoryStore`, `machine`, `slug`, `name`, `description`, `originSessionId`, `body`, `memoryIndexPath`, and `repoPath` (the origin project's working directory when the memory-store slug resolves to a live repo on this machine, else null). `skipped` lists memory files that have a frontmatter fence but unparseable YAML; read and route each one by hand (they are usually feedback memories whose `name:` value needs quoting).
54
+
55
+ ### 2. Classify
56
+
57
+ Work through the memories **one store at a time**, not as a single undifferentiated batch. The `memories` array is already ordered by store, so group it by the `memoryStore` field and process each group in turn. On a machine with many memories, prefer scoping each run to one store with `--memory-store <name>`: A fresh invocation per store keeps the context lean and grounded in a single project. Processing all stores in one run stays the default, and is fine when the machine has few.
58
+
59
+ Before classifying a store's memories, ground yourself in that project: When `repoPath` is set, read that repo's root `AGENTS.md` and any project guidance to which it points, so that the routing calls match what the project already codifies. When `repoPath` is null (the store's slug does not resolve to a working repo on this machine), classify that store's memories ungrounded. Grounding is best-effort, never a blocker.
60
+
61
+ Then decide one destination per memory:
62
+
63
+ - **Capture** when the lesson generalizes beyond its origin project (a behavior, correction, or convention that should propagate). This is the default for behavioral feedback.
64
+ - **Retain** when the fact is genuinely local and non-propagating (a project-specific deadline, a one-off quirk).
65
+ - **Delete** only when the memory _restates_ a rule that shared guidance, a prior capture, or the origin project's own guidance already codifies, without adding any signal that the guidance does not already state. Redundancy here is of signal, not topic. A memory that **narrates a violation** of already-existing guidance is not redundant: An agent breaking a codified rule is fresh evidence the guidance is not taking effect, so route it to **Capture** with `,mistake`, never Delete. When a body is ambiguous between restatement and violation, prefer Capture; a needless capture dedups away on the next run, but a deleted violation is gone for good. The redirect memory `feedback-capture-feedback-in-kb-not-memory` is a delete like any other, because it is a pure restatement (`shared/AGENTS.md` now states its rule).
66
+
67
+ ### 3. Dedup capture candidates by origin
68
+
69
+ For each capture candidate, invoke the {skill:kb-retrieve-events} skill on the memory's topic. That skill finds candidates by term and tag overlap, so a hit may share only a tag (e.g. `feedback`) with the memory rather than its actual lesson; treat every hit as a _candidate_ duplicate, not a confirmed one. For each returned event, read the `Origin: project …, machine …, session …` line that each migration writes into an event body (step 5), when present.
70
+
71
+ An event is this memory (already captured) only when **both** conditions hold: Its topic records the memory's lesson **and** its origin matches. A session id does not uniquely identify a source memory: One working session routinely emits several feedback memories and/or captured events, each on a different topic. A shared `originSessionId` (or `memoryStore`) establishes common origin, not common lesson.
72
+
73
+ - **Delete** the candidate only when a returned event both records the memory's lesson and shares its origin (origin matched on the `originSessionId` when the memory has one, else on the origin `memoryStore` by judgment). Such an event _is_ this memory, already captured on an earlier run or migrated from another machine. Re-capturing would double-count. This rule makes a re-run, and a second machine's run, converge.
74
+ - **Keep the capture** when a returned event's topic _diverges_ from the memory's, even if the origins match. Deleting on the origin match alone would remove the memory without ever capturing its lesson, an unrecoverable loss.
75
+ - **Keep the capture** when an equivalent event has a _different_ origin. A lesson that recurred in separate projects is genuine recurrence, and the KB counts and ranks events by it (see {skill:kb-retrieve-events}), so each occurrence is captured as its own event; do not collapse distinct origins into one.
76
+
77
+ The lone exception is a memory _deliberately replicated_ as scaffolding (one rule copied verbatim into many stores rather than arising independently in each), which is one rule in many copies, not many occurrences. Collapse those to a single capture by judgment.
78
+
79
+ > **Worked example.** During the node-monorepo-tools migration, the retrieval for memory `merge-title-multiscope-bare-type` (origin session `187b2cdd`) returned a same-session event about an unrelated gradient-marker mistake. The session ids matched; the topics did not. Deleting on the session-id match would have removed the memory without capturing its merge-title lesson; only reading the matched event's topic revealed the collision.
80
+
81
+ ### 4. Present the routing plan (default mode)
82
+
83
+ Show every memory with its destination, and for each capture the proposed `--tags`, `--skill`, and `--impact`. Present it as one batch for review: Per-item confirmation is impractical at this scale. Wait for approval or adjustments. In auto mode, skip this step.
84
+
85
+ <!-- include: ../_partials/action-items.md / -->
86
+
87
+ ### 5. Execute
88
+
89
+ On approval, run all captures first, then a single deletion pass:
90
+
91
+ 1. **Capture**: For each memory routed to capture, compose the arguments and body per the {skill:capture-event} contract and pipe the body to its bundled helper directly (a per-item skill invocation is too expensive for a batch of this size). Run the capture from the memory's origin repo, so that `capture-event`'s auto-filled `cwd` and `repo` resolve to the origin rather than this migration run: Wrap the invocation in a subshell that changes to the memory's `repoPath` first. The subshell contains the `cd`, keeping the origin directory out of the deletion pass and the next capture.
92
+
93
+ ```bash
94
+ (cd "<repoPath>" && cat <<'EOF' | node {harness_home_dir}/skills/capture-event/capture-event.mjs \
95
+ --summary "<one-line lesson>" \
96
+ --store @feedback \
97
+ --harness {harness_id} \
98
+ --tags feedback \
99
+ [--skill <slug>] [--impact <level>]
100
+ <the generalized lesson>
101
+
102
+ Origin: project <memoryStore>, machine <machine>, session <originSessionId>.
103
+ EOF
104
+ )
105
+ ```
106
+
107
+ `--store @feedback` here names the **KB store** (the capture's destination, not the memory store from which it came). It resolves to the `feedback_kb` of `~/.agents/kb.yaml` independently of the working directory, so the capture writes the event to the same store wherever it runs. When the memory's `repoPath` is null (the memory-store slug does not resolve to a live repo on this machine), omit the `(cd "<repoPath>" && … )` wrapper and run the capture from the current directory as today; `capture-event` then stamps this run's `cwd`/`repo`, and the body's `Origin:` line still records the origin.
108
+
109
+ Only when `capture-event` returns `ok: true`, add that memory's source `path` to the deletion batch: Because a capture migrates the memory out of its store, its source is removed once the event is recorded. When a capture fails, leave the source in place and report the failure; never delete a memory whose capture did not succeed.
110
+
111
+ 2. **Delete**: Pipe every deletion path, newline-separated, to the helper's `delete` subcommand in a single call. The batch is the union of the memories routed to delete-as-redundant and the sources of successful captures, so that each store's `MEMORY.md` is reconciled once:
112
+
113
+ ```bash
114
+ printf '%s\n' "<path>" "<path>" … | node {harness_home_dir}/skills/migrate-feedback-memories/feedback-memories.mjs delete
115
+ ```
116
+
117
+ It removes each file and reconciles its `MEMORY.md`, printing a per-path outcome (`deleted`, `indexUpdated`, and a `note` for any already-absent file or unmatched index line).
118
+
119
+ 3. **Retain**: No action.
120
+
121
+ ### Composing a capture
122
+
123
+ - `--store @feedback`: The feedback KB is configured in the registry, not chosen per memory.
124
+ - `--tags feedback` always; add `,mistake` (i.e. `--tags feedback,mistake`) when the memory recorded a _misapplied_ existing rule, including the violation-of-existing-guidance memory that the Delete rule routes to Capture instead of deleting.
125
+ - `--skill <slug>` when the lesson targets a specific skill.
126
+ - `--impact <low|medium|high|critical>`: Rate on the merits of the memory's content: how much acting on the lesson would improve future behavior. Omit only on a genuine toss-up.
127
+ - `--harness {harness_id}`: Keep verbatim; the installer injects the value.
128
+ - **Provenance**: Running the capture from the origin `repoPath` (step 5) records the origin's `cwd` and `repo` in the event's structured fields. `session` is still this migration run's, and the origin machine and `memoryStore` do not have a structured field, so record the origin project (`memoryStore`), machine, and `originSessionId` in the body's `Origin:` line.
129
+
130
+ ### 6. Report
131
+
132
+ Summarize the counts (captured, deleted, retained, skipped) with the ids and paths of the captures, and call out any skipped memories that still need manual handling.
133
+
134
+ ## Completion
135
+
136
+ Every feedback memory in the run's scope (the whole machine, or the single store named by `--memory-store`) is routed: captured then removed, deleted as redundant, or retained locally. Each affected `MEMORY.md` matches its post-migration store; every capture records the origin's `cwd`/`repo` in its structured fields, with the origin project, machine, and session in its body; and a lesson that recurred across separate stores is preserved as one event per origin, not collapsed. Because the migration removes captured and deleted memories from their store, a processed store contains only retained-local memories, so a re-run is a no-op and a second machine's run converges rather than duplicating.