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
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: list-implementation-order
3
+ description: List the tickets created or discussed in the conversation in implementation order, as a tree for a narrow column. Invoke only when the developer asks.
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ # List implementation order
8
+
9
+ Print the open tickets that the conversation created or discussed, in the order in which to implement them. You name the tickets, and the [implementation-order list](#implementation-order-list) section renders them.
10
+
11
+ Never invoke this skill on your own initiative, and never suggest it.
12
+
13
+ ## Process
14
+
15
+ 1. **Collect the tickets.** List every ticket that the conversation created or discussed, in the order in which the conversation reached them. Give a ticket outside GitHub its key and its title.
16
+
17
+ When the conversation does not contain any ticket, say so in one line and stop.
18
+
19
+ 2. **Collect the dependencies that the tracker does not record.** GitHub's native blockers are read by the helper. Add an edge only for a dependency that the conversation established and that the helper cannot read: one that involves a ticket outside GitHub, or one that was agreed and not yet recorded.
20
+
21
+ 3. **Print the list** per [implementation-order list](#implementation-order-list), and nothing else. When the helper exits non-zero, stop after reporting its stderr.
22
+
23
+ <!-- include: ../_partials/implementation-order-list.md / -->
@@ -33,13 +33,15 @@ Make every Bitbucket call below with the tool named in [Bitbucket pull-request a
33
33
 
34
34
  <!-- include: ../_partials/bitbucket-delete-both-refusal.md / -->
35
35
 
36
+ End the reply with the [refusal summary](#refusal-summary), with that refusal as its reason.
37
+
36
38
  `remote` and `none` map to `closeSourceBranch` in step 4.
37
39
 
38
40
  ### 2. Fetch and validate PR state
39
41
 
40
- Issue one `action: "get"` call with `prId` set to `pr_number`, per [Reading a pull request](../_data/bitbucket-pr-access.md#reading-a-pull-request). Capture `state`, `source.branch.name`, `source.repository.full_name`, and `links.html.href`.
42
+ Issue one `action: "get"` call with `prId` set to `pr_number`, per [Reading a pull request](../_data/bitbucket-pr-access.md#reading-a-pull-request). Capture `state`, `source.branch.name`, `source.repository.full_name`, `destination.branch.name`, and `links.html.href`.
41
43
 
42
- Refuse the merge when `state` is not `OPEN`, naming the state: "PR #{n} is {state} (not OPEN); cannot merge." The refusal covers `MERGED`, `DECLINED`, and `SUPERSEDED`. When `state` is missing from the response, **fail closed**: Refuse with "Cannot determine merge state for PR #{n}; verify and merge manually."
44
+ On each refusal in this step and in step 3, stop, and end the reply with the [refusal summary](#refusal-summary), with the refusal's text as its reason. Refuse the merge when `state` is not `OPEN`, naming the state: "PR #{n} is {state} (not OPEN); cannot merge." The refusal covers `MERGED`, `DECLINED`, and `SUPERSEDED`. When `state` is missing from the response, **fail closed**: Refuse with "Cannot determine merge state for PR #{n}; verify and merge manually."
43
45
 
44
46
  Bitbucket does not expose a counterpart to GitHub's `mergeable` or `mergeStateStatus`, and this step does not invent one. The merge call in step 4 reports a conflict, a failing required check, or a missing required approval as its own error, before anything is published.
45
47
 
@@ -75,7 +77,7 @@ Passing a composed title for `merge_commit` diverges from `merge-gh-pr`, which o
75
77
 
76
78
  Set `closeSourceBranch` to `true` for `deletion_strategy: remote` and `false` for `none`.
77
79
 
78
- Call `action: "merge"` with `prId`, `mergeStrategy`, `message` (except for `rebase_fast_forward`), and `closeSourceBranch`. If the call fails, report the tool's error and exit non-zero. Do not retry, and do not fall back to another strategy.
80
+ Call `action: "merge"` with `prId`, `mergeStrategy`, `message` (except for `rebase_fast_forward`), and `closeSourceBranch`. If the call fails, stop, and end the reply with the [refusal summary](#refusal-summary), with the tool's error as its reason. Do not retry, and do not fall back to another strategy.
79
81
 
80
82
  ### 5. Capture the merge result
81
83
 
@@ -125,12 +127,33 @@ Branch: {source.branch.name}
125
127
 
126
128
  ## Completion
127
129
 
130
+ Report `Artifact saved: {artifact path}` on a line of its own, then print these lines as the last element of the reply:
131
+
128
132
  ```
129
- Merged: {links.html.href}
130
- Commit: {merge_commit.hash}
131
- Strategy: {strategy}
132
- Branch: {source.branch.name}
133
- Artifact saved: {artifact path}
133
+ ---
134
+
135
+ ## 🔀 Merged into {destination.branch.name} · {strategy name} · {first 7 characters of merge_commit.hash, or unavailable}
136
+
137
+ {title line}
138
+ PR: {links.html.href}
139
+ Remote branch {source.branch.name}: {🗑️ Deleted for deletion_strategy: remote, ⏸️ Kept for none}
140
+ ```
141
+
142
+ The strategy name is the result's name: `squash`, `merge commit` for `merge`, and `rebase`. The title line is `Commit title: {title}` for `squash` and `merge`, whose `message` step 4 composes from `title`, and `Last commit title: unavailable` for `rebase`, which submits no message; the tool does not expose a read of the commit. Separate the lines with single newlines, and keep the blank line below the rule and the one below the heading. Print the lines exactly as this template renders them, and do not write any sentence before them that restates the outcome: The heading states it, and the bottom of the reply is the part that the terminal shows first. `merge-pr` places them directly above an action-items block when its turn has an ask.
143
+
144
+ ### Refusal summary
145
+
146
+ A refusal in steps 1 to 4 means that the PR was not merged. End the reply with these lines, in place of the summary above:
147
+
134
148
  ```
149
+ ---
150
+
151
+ ## ❌ Not merged
152
+
153
+ PR: {links.html.href, or #{pr_number} when step 2 did not read it}
154
+ Reason: {reason}
155
+ ```
156
+
157
+ Keep the lines single-spaced: When the reason spans several lines, drop its blank lines.
135
158
 
136
159
  Local state is intentionally left untouched; removing the merged branch is left to the user. Do not append local-branch cleanup steps or advice. Do not report this state to the user.
@@ -28,14 +28,16 @@ Internal delegate that merges a pull request on GitHub. Called by `merge-pr` wit
28
28
  Use a single `gh pr view` call to fetch every field needed for validation:
29
29
 
30
30
  ```bash
31
- gh pr view {pr_number} --json state,isDraft,mergeable,mergeStateStatus,reviewDecision,headRefName,isCrossRepository,baseRefName
31
+ gh pr view {pr_number} --json state,isDraft,mergeable,mergeStateStatus,reviewDecision,headRefName,isCrossRepository,baseRefName,url
32
32
  ```
33
33
 
34
34
  Parse the JSON with a real parser (`python3 -c "import sys,json; ..."` or `jq`). Do not regex-extract.
35
35
 
36
+ If the call fails, stop, and end the reply with the [refusal summary](#refusal-summary), with `gh`'s stderr as the reason.
37
+
36
38
  ### 2. Run pre-merge checks
37
39
 
38
- Refuse the merge with a specific reason on any of the following. On each refusal, exit non-zero and print the reason on stderr:
40
+ Refuse the merge with a specific reason on any of the following. On each refusal, stop, and end the reply with the [refusal summary](#refusal-summary), with the reason below as its reason:
39
41
 
40
42
  | Field | Failure condition | Refusal reason |
41
43
  | ------------------ | ------------------------------------------------------------ | --------------------------------------------------------------------------- |
@@ -69,13 +71,13 @@ git fetch origin
69
71
  git rev-list --left-right --count "origin/{headRefName}...HEAD"
70
72
  ```
71
73
 
72
- If the counts differ from `0\t0`, refuse: "Local branch is out of sync with `origin/{headRefName}` (ahead {a}, behind {b}); push or pull before merging."
74
+ If the counts differ from `0\t0`, refuse with the [refusal summary](#refusal-summary): "Local branch is out of sync with `origin/{headRefName}` (ahead {a}, behind {b}); push or pull before merging."
73
75
 
74
76
  ### 4. Write the title and body to scratch files
75
77
 
76
78
  Write `body` to a scratch file per [gh body file](#gh-body-file), naming it for the PR (`gh-body-pr{pr_number}-{timestamp}.md`). When `strategy` is `squash`, also write `title` to `gh-title-pr{pr_number}-{timestamp}.txt` in the same directory. Do not inline either into a command.
77
79
 
78
- **Read both files back before step 5.** Read each path that step 5 is about to pass, with the {tool:Read} tool rather than a shell command, and compare its content against the `body` and `title` received by this delegate; a single trailing newline in the title file is ignored. Refuse when either differs, naming the PR and the path: "Body file for PR #{n} at {path} is not the approved merge body." or "Title file for PR #{n} at {path} is not the approved merge title." A squash merge onto a protected default branch publishes a commit message that cannot be amended, so this is the last point at which a wrong message can be caught. Read the paths being passed rather than the ones written earlier in this step, so that a path left over from another PR is caught rather than confirmed.
80
+ **Read both files back before step 5.** Read each path that step 5 is about to pass, with the {tool:Read} tool rather than a shell command, and compare its content against the `body` and `title` received by this delegate; a single trailing newline in the title file is ignored. Refuse with the [refusal summary](#refusal-summary) when either differs, naming the PR and the path: "Body file for PR #{n} at {path} is not the approved merge body." or "Title file for PR #{n} at {path} is not the approved merge title." A squash merge onto a protected default branch publishes a commit message that cannot be amended, so this is the last point at which a wrong message can be caught. Read the paths being passed rather than the ones written earlier in this step, so that a path left over from another PR is caught rather than confirmed.
79
81
 
80
82
  ### 5. Merge and delete the branch
81
83
 
@@ -99,19 +101,22 @@ On success, the helper exits 0 and prints JSON on stdout:
99
101
  "headRefName": "feature/cache",
100
102
  "mergeCommit": { "oid": "abc123" },
101
103
  "mergedAt": "2026-09-28T22:00:00Z",
104
+ "summary": "---\n\n## 🔀 Merged into main · squash · abc1234\n\nCommit title: widgets|feat: Cache the lookup (#42)\nPR: https://github.com/acme/widgets/pull/42\nRemote branch feature/cache: 🗑️ Deleted",
102
105
  "url": "https://github.com/acme/widgets/pull/42"
103
106
  }
104
107
  ```
105
108
 
109
+ `summary` contains the outcome lines that [Completion](#completion) prints. Its commit-title line contains the subject of the commit that the merge created, which the helper reads from GitHub after the merge. When it cannot read the subject, it writes a warning on stderr and shows the submitted title, or `unavailable` for `merge` and `rebase`, which do not submit one; the merge still succeeded, so continue.
110
+
106
111
  `branchDeletion` is one of these values:
107
112
 
108
113
  - `deleted`: The helper deleted the branch.
109
114
  - `already-deleted`: The branch or its fork was already gone, for example because the repository deletes branches on merge.
110
- - `failed`: A warning on stderr gives the reason. The merge still succeeded, so relay the warning and continue.
115
+ - `failed`: A warning on stderr gives the reason, which the summary's branch line repeats. The merge still succeeded, so continue.
111
116
  - `by-gh`: The deletion strategy was `both`, and `gh pr merge --delete-branch` handled the deletion.
112
117
  - `not-requested`: The deletion strategy was `none`.
113
118
 
114
- When the helper exits non-zero, print its stderr to the user and stop. This covers a refused input file, a failed `gh pr merge` (whose stderr the helper passes on), and a PR that is not `MERGED` after `gh` accepted the merge, such as a PR placed in a merge queue. Do not retry, and do not bypass with `--admin`.
119
+ When the helper exits non-zero, it still prints JSON on stdout, containing only `summary`. Stop, and end the reply with that `summary`, printed verbatim. Its reason contains the helper's stderr, so do not print the stderr as well. This covers a refused input file, a failed `gh pr merge` (whose stderr the helper passes on), a PR that is not `MERGED` after `gh` accepted the merge, such as a PR placed in a merge queue, and a PR whose state cannot be read after `gh` accepted the merge, whose summary is headed `## ⚠️ Merge not confirmed`. Do not retry, and do not bypass with `--admin`.
115
120
 
116
121
  ### 6. Save merge artifact
117
122
 
@@ -153,15 +158,23 @@ Branch: {headRefName}
153
158
 
154
159
  ## Completion
155
160
 
161
+ Report `Artifact saved: {artifact path}` on a line of its own, then print the helper's `summary` verbatim, as the last element of the reply. Do not write any sentence before it that restates the outcome: The summary's heading states it, and the bottom of the reply is the part that the terminal shows first. `merge-pr` places the summary directly above an action-items block when its turn has an ask.
162
+
163
+ ### Refusal summary
164
+
165
+ A refusal in steps 1 to 4 means that the PR was not merged. End the reply with these lines, in place of the summary that the helper would have printed:
166
+
156
167
  ```
157
- Merged: {url}
158
- Commit: {mergeCommit.oid}
159
- Strategy: {strategy}
160
- Branch: {headRefName}
161
- Branch deletion: {branchDeletion}
162
- Artifact saved: {artifact path}
168
+ ---
169
+
170
+ ## ❌ Not merged
171
+
172
+ PR: {url, or #{pr_number} when step 1 did not read it}
173
+ Reason: {reason}
163
174
  ```
164
175
 
176
+ Keep the lines single-spaced: When the reason spans several lines, drop its blank lines.
177
+
165
178
  Local state is intentionally left untouched; removing the merged branch is left to the user. Do not append local-branch cleanup steps or advice. Do not report this state to the user.
166
179
 
167
180
  <!-- include: ../_partials/gh-body-file.md / -->
@@ -1,10 +1,15 @@
1
1
  import { createRequire as __cjsCreateRequire } from 'node:module';
2
2
  const require = __cjsCreateRequire(import.meta.url);
3
- var M=Object.defineProperty;var o=(e,t)=>M(e,"name",{value:t,configurable:!0});import{execFile as v}from"node:child_process";import{readFileSync as O,statSync as G}from"node:fs";import d from"node:process";import{promisify as j}from"node:util";function m(e){return e instanceof Error||Object.prototype.toString.call(e)==="[object Error]"}o(m,"isError");function g(e){try{return m(e)&&typeof e.message=="string"&&e.message!==""?e.message:String(e)}catch{return"[unstringifiable value]"}}o(g,"describeError");import{realpathSync as p}from"node:fs";import y from"node:process";import{fileURLToPath as $}from"node:url";function h(e,t){let r=y.argv[1];if(r===void 0)return!1;try{return p($(e))===p(r)}catch(n){return y.stderr.write(`${t}: warning: could not determine entry point: ${g(n)}
4
- `),!0}}o(h,"isEntryPoint");function b(e,t){let r=[],n=[];for(let i=0;i<e.length;i+=1){let s=e[i];if(s===void 0)continue;if(!s.startsWith("--")){r.push(s);continue}let a=P(s,t);if(a===null)throw new Error(`unknown flag: ${s}`);let{spec:u,inlineValue:f}=a;if(!u.takesValue){if(f!==null)throw new Error(`--${u.name} does not take a value`);n.push({name:u.name,value:null});continue}if(f!==null){n.push({name:u.name,value:f});continue}let c=e[i+1]??null;if(c===null||c.startsWith("--"))throw new Error(`--${u.name} requires a value`);n.push({name:u.name,value:c}),i+=1}return{positionals:r,flags:n}}o(b,"scanFlags");function w(e){let t={};for(let{name:r,value:n}of e)n!==null&&(t[r]=n);return t}o(w,"valueFlagMap");function P(e,t){for(let r of t)for(let n of[r.name,...r.aliases??[]]){let i=`--${n}`;if(e===i)return{spec:r,inlineValue:null};if(e.startsWith(`${i}=`))return{spec:r,inlineValue:e.slice(i.length+1)}}return null}o(P,"matchFlag");function C(e,t){return x(e)&&e.code===t}o(C,"isErrorCode");function R(e){return C(e,"ENOENT")}o(R,"isEnoent");function l(e){return x(e)&&!Array.isArray(e)}o(l,"isRecord");function x(e){return typeof e=="object"&&e!==null}o(x,"isObject");var V="state,mergeCommit,url,mergedAt,headRefName,headRepository,headRepositoryOwner";async function N(e,t){let r=await t(A(e));if(r.exitCode!==0)return{ok:!1,exitCode:r.exitCode,stderr:r.stderr};let n=await t(["pr","view",String(e.prNumber),"--json",V]);if(n.exitCode!==0)return{ok:!1,exitCode:n.exitCode,stderr:`PR #${e.prNumber} merge ran, but its state could not be read; branch not deleted.
5
- ${n.stderr}`};let i=T(n.stdout);if(i.kind==="unreadable")return{ok:!1,exitCode:1,stderr:`PR #${e.prNumber} merge ran, but its state could not be read; branch not deleted.
6
- `};if(i.kind==="not-merged")return{ok:!1,exitCode:1,stderr:`PR #${e.prNumber} is ${i.state} after merge; branch not deleted.
7
- `};let s=[];return{ok:!0,result:{branchDeletion:await D(e.deletionStrategy,i,t,s),headRefName:i.headRefName,mergeCommit:{oid:i.oid},mergedAt:i.mergedAt,url:i.url},warnings:s}}o(N,"mergePullRequest");function A(e){let t=["pr","merge",String(e.prNumber),`--${e.strategy}`];return e.strategy==="squash"&&e.title!==void 0&&t.push("--subject",e.title),e.strategy!=="rebase"&&e.bodyPath!==void 0&&t.push("--body-file",e.bodyPath),e.deletionStrategy==="both"&&t.push("--delete-branch"),t}o(A,"buildMergeArgs");async function D(e,t,r,n){if(e==="none")return"not-requested";if(e==="both")return"by-gh";if(t.headOwner===void 0||t.headRepo===void 0)return"already-deleted";let i=t.headRefName.split("/").map(encodeURIComponent).join("/"),s=`repos/${encodeURIComponent(t.headOwner)}/${encodeURIComponent(t.headRepo)}/git/refs/heads/${i}`,a=await r(["api","-X","DELETE",s]);return a.exitCode===0?"deleted":a.stderr.includes("HTTP 422")&&a.stderr.includes("Reference does not exist")?"already-deleted":(n.push(`warning: Failed to delete remote branch '${t.headRefName}': ${a.stderr.trim()}`),"failed")}o(D,"deleteHeadBranch");function T(e){let t;try{t=JSON.parse(e)}catch{return{kind:"unreadable"}}if(!l(t)||typeof t.state!="string")return{kind:"unreadable"};if(t.state!=="MERGED")return{kind:"not-merged",state:t.state};let{headRefName:r,mergeCommit:n,mergedAt:i,url:s}=t,a=l(n)?n.oid:void 0;return typeof r!="string"||typeof i!="string"||typeof a!="string"||typeof s!="string"?{kind:"unreadable"}:{kind:"merged",headOwner:E(t.headRepositoryOwner,"login"),headRefName:r,headRepo:E(t.headRepository,"name"),mergedAt:i,oid:a,url:s}}o(T,"parseMergedView");function E(e,t){if(!l(e))return;let r=e[t];return typeof r=="string"&&r.length>0?r:void 0}o(E,"readNamedField");var q=j(v),I=[{name:"body-file",takesValue:!0},{name:"delete",takesValue:!0},{name:"pr",takesValue:!0},{name:"strategy",takesValue:!0},{name:"title-file",takesValue:!0}],B=["both","none","remote"],L=["merge","rebase","squash"];async function U(){try{let e=_(W(d.argv.slice(2))),t=await N(e,J);t.ok||(d.stderr.write(t.stderr),d.exit(t.exitCode));for(let r of t.warnings)d.stderr.write(`${r}
8
- `);d.stdout.write(`${JSON.stringify(t.result,null,2)}
9
- `)}catch(e){d.stderr.write(`merge-gh-pr: ${g(e)}
10
- `),d.exit(1)}}o(U,"main");h(import.meta.url,"merge-gh-pr")&&await U();function k(e){try{let t=G(e);return t.isFile()&&t.size>0}catch{return!1}}o(k,"isNonEmptyFile");function W(e){let{flags:t,positionals:r}=b(e,I);if(r.length>0)throw new Error(`unexpected argument: ${r.join(" ")}`);let n=w(t),i=F(n,"pr");if(!/^[1-9]\d*$/.test(i))throw new Error(`--pr must be a positive integer, got '${i}'`);return{bodyFile:n["body-file"],deletionStrategy:S(n,"delete",B),prNumber:Number(i),strategy:S(n,"strategy",L),titleFile:n["title-file"]}}o(W,"parseArgs");function _(e){let t=e.strategy!=="rebase",r=e.strategy==="squash",n;if(r&&(n=H(e.titleFile)),t){if(e.bodyFile===void 0)throw new Error(`--body-file is required for --strategy ${e.strategy}`);if(!k(e.bodyFile))throw new Error(`Body file missing or empty: ${e.bodyFile}`)}return{bodyPath:t?e.bodyFile:void 0,deletionStrategy:e.deletionStrategy,prNumber:e.prNumber,strategy:e.strategy,title:n}}o(_,"readRequest");function H(e){if(e===void 0)throw new Error("--title-file is required for --strategy squash");if(!k(e))throw new Error(`Title file missing or empty: ${e}`);let t=O(e,"utf8").replace(/\r?\n$/,"");if(t.length===0)throw new Error(`Title file missing or empty: ${e}`);return t}o(H,"readTitle");function S(e,t,r){let n=F(e,t),i=r.find(s=>s===n);if(i===void 0)throw new Error(`--${t} must be one of ${r.join(", ")}, got '${n}'`);return i}o(S,"requireMember");function F(e,t){let r=e[t];if(r===void 0)throw new Error(`--${t} is required`);return r}o(F,"requireValue");async function J(e){try{let{stderr:t,stdout:r}=await q("gh",e,{maxBuffer:16777216});return{exitCode:0,stderr:t,stdout:r}}catch(t){if(R(t))throw new Error("gh is not installed or not on PATH",{cause:t});if(l(t)&&typeof t.code=="number"&&typeof t.stderr=="string"&&typeof t.stdout=="string")return{exitCode:t.code,stderr:t.stderr,stdout:t.stdout};throw t}}o(J,"runGh");
3
+ var V=Object.defineProperty;var o=(e,t)=>V(e,"name",{value:t,configurable:!0});import{execFile as X}from"node:child_process";import{readFileSync as Y,statSync as Q}from"node:fs";import m from"node:process";import{promisify as Z}from"node:util";function w(e){return e instanceof Error||Object.prototype.toString.call(e)==="[object Error]"}o(w,"isError");function l(e){try{return w(e)&&typeof e.message=="string"&&e.message!==""?e.message:String(e)}catch{return"[unstringifiable value]"}}o(l,"describeError");import{realpathSync as E}from"node:fs";import x from"node:process";import{fileURLToPath as v}from"node:url";function N(e,t){let r=x.argv[1];if(r===void 0)return!1;try{return E(v(e))===E(r)}catch(n){return x.stderr.write(`${t}: warning: could not determine entry point: ${l(n)}
4
+ `),!0}}o(N,"isEntryPoint");function $(e,t){let r=[],n=[];for(let i=0;i<e.length;i+=1){let s=e[i];if(s===void 0)continue;if(!s.startsWith("--")){r.push(s);continue}let a=I(s,t);if(a===null)throw new Error(`unknown flag: ${s}`);let{spec:d,inlineValue:u}=a;if(!d.takesValue){if(u!==null)throw new Error(`--${d.name} does not take a value`);n.push({name:d.name,value:null});continue}if(u!==null){n.push({name:d.name,value:u});continue}let f=e[i+1]??null;if(f===null||f.startsWith("--"))throw new Error(`--${d.name} requires a value`);n.push({name:d.name,value:f}),i+=1}return{positionals:r,flags:n}}o($,"scanFlags");function S(e){let t={};for(let{name:r,value:n}of e)n!==null&&(t[r]=n);return t}o(S,"valueFlagMap");function I(e,t){for(let r of t)for(let n of[r.name,...r.aliases??[]]){let i=`--${n}`;if(e===i)return{spec:r,inlineValue:null};if(e.startsWith(`${i}=`))return{spec:r,inlineValue:e.slice(i.length+1)}}return null}o(I,"matchFlag");function j(e,t){return k(e)&&e.code===t}o(j,"isErrorCode");function M(e){return j(e,"ENOENT")}o(M,"isEnoent");function c(e){return k(e)&&!Array.isArray(e)}o(c,"isRecord");function k(e){return typeof e=="object"&&e!==null}o(k,"isObject");var D=["both","none","remote"],F=["merge","rebase","squash"];var L="state,mergeCommit,url,mergedAt,baseRefName,headRefName,headRepository,headRepositoryOwner";function g(e,t){let r=e===void 0?[]:[`PR: ${e}`];return y("## \u274C Not merged",[...r,`Reason: ${h(t)}`])}o(g,"formatRefusalSummary");async function C(e,t){let r=await t(q(e));if(r.exitCode!==0){let u=r.stderr.trim()||`\`gh pr merge\` exited with code ${r.exitCode}.`;return{ok:!1,exitCode:r.exitCode,stderr:r.stderr,summary:g(`#${e.prNumber}`,u)}}let n=await b(t,["pr","view",String(e.prNumber),"--json",L]);if(n.exitCode!==0)return{ok:!1,exitCode:n.exitCode,stderr:`PR #${e.prNumber} merge ran, but its state could not be read; branch not deleted.
5
+ ${n.stderr}`,summary:T(e.prNumber,n.stderr)};let i=z(n.stdout);if(i.kind==="unreadable")return{ok:!1,exitCode:1,stderr:`PR #${e.prNumber} merge ran, but its state could not be read; branch not deleted.
6
+ `,summary:T(e.prNumber,"")};if(i.kind==="not-merged"){let u=`PR #${e.prNumber} is ${i.state} after the merge command, so a merge queue may hold it. The branch was not deleted.`;return{ok:!1,exitCode:1,stderr:`PR #${e.prNumber} is ${i.state} after merge; branch not deleted.
7
+ `,summary:g(i.url??`#${e.prNumber}`,u)}}let s=[],a=await U(e.deletionStrategy,i,t,s),d=await K(e,i.oid,t,s);return{ok:!0,result:{branchDeletion:a.branchDeletion,headRefName:i.headRefName,mergeCommit:{oid:i.oid},mergedAt:i.mergedAt,summary:J(e,i,a,d),url:i.url},warnings:s}}o(C,"mergePullRequest");var _="repos/{owner}/{repo}/commits",B={merge:"merge commit",rebase:"rebase",squash:"squash"};function q(e){let t=["pr","merge",String(e.prNumber),`--${e.strategy}`];return e.strategy==="squash"&&e.title!==void 0&&t.push("--subject",e.title),e.strategy!=="rebase"&&e.bodyPath!==void 0&&t.push("--body-file",e.bodyPath),e.deletionStrategy==="both"&&t.push("--delete-branch"),t}o(q,"buildMergeArgs");async function U(e,t,r,n){if(e==="none")return{branchDeletion:"not-requested"};if(e==="both")return{branchDeletion:"by-gh"};if(t.headOwner===void 0||t.headRepo===void 0)return{branchDeletion:"already-deleted"};let i=t.headRefName.split("/").map(encodeURIComponent).join("/"),s=`repos/${encodeURIComponent(t.headOwner)}/${encodeURIComponent(t.headRepo)}/git/refs/heads/${i}`,a=await b(r,["api","-X","DELETE",s]);if(a.exitCode===0)return{branchDeletion:"deleted"};if(a.stderr.includes("HTTP 422")&&a.stderr.includes("Reference does not exist"))return{branchDeletion:"already-deleted"};let d=a.stderr.trim();return n.push(`warning: Failed to delete remote branch '${t.headRefName}': ${d}`),{branchDeletion:"failed",reason:d}}o(U,"deleteHeadBranch");function W(e,t){return`${t.branchDeletion==="by-gh"?`Local and remote branch ${e}`:`Remote branch ${e}`}: ${H(t)}`}o(W,"formatDeletionLine");function H(e){switch(e.branchDeletion){case"already-deleted":return"\u{1F5D1}\uFE0F Already deleted";case"by-gh":case"deleted":return"\u{1F5D1}\uFE0F Deleted";case"failed":return`\u26A0\uFE0F Not deleted: ${h(e.reason??"unknown error")}`;case"not-requested":return"\u23F8\uFE0F Kept"}}o(H,"formatDeletionState");function J(e,t,r,n){let i=t.baseRefName===void 0?"":` into ${t.baseRefName}`,s=e.strategy==="rebase"?"Last commit title":"Commit title";return y(`## \u{1F500} Merged${i} \xB7 ${B[e.strategy]} \xB7 ${t.oid.slice(0,7)}`,[`${s}: ${n}`,`PR: ${t.url}`,W(t.headRefName,r)])}o(J,"formatMergedSummary");function y(e,t){return["---","",e,"",...t].join(`
8
+ `)}o(y,"formatSummary");function T(e,t){let r="The merge command succeeded, but the PR's state could not be read. The branch was not deleted.",n=t.trim();return y("## \u26A0\uFE0F Merge not confirmed",[`PR: #${e}`,`Reason: ${n.length>0?`${r}
9
+ ${h(n)}`:r}`])}o(T,"formatUnconfirmedSummary");function h(e){return e.trim().replaceAll(/\n(?:[\t ]*\n)+/g,`
10
+ `)}o(h,"normalizeBlock");function z(e){let t;try{t=JSON.parse(e)}catch{return{kind:"unreadable"}}if(!c(t)||typeof t.state!="string")return{kind:"unreadable"};if(t.state!=="MERGED")return{kind:"not-merged",state:t.state,url:p(t.url)};let{headRefName:r,mergeCommit:n,mergedAt:i,url:s}=t,a=c(n)?n.oid:void 0;return typeof r!="string"||typeof i!="string"||typeof a!="string"||typeof s!="string"?{kind:"unreadable"}:{kind:"merged",baseRefName:p(t.baseRefName),headOwner:P(t.headRepositoryOwner,"login"),headRefName:r,headRepo:P(t.headRepository,"name"),mergedAt:i,oid:a,url:s}}o(z,"parseMergedView");async function K(e,t,r,n){let i=await b(r,["api",`${_}/${t}`,"--jq",".commit.message"]),s=i.exitCode===0?(i.stdout.trim().split(`
11
+ `,1)[0]??"").trim():"";if(s.length>0)return s;let a=i.exitCode===0?"empty commit message":i.stderr.trim()||`\`gh api\` exited with code ${i.exitCode}.`;return n.push(`warning: Could not read the subject of merge commit ${t}: ${a}`),e.title??"unavailable"}o(K,"readCommitTitle");function P(e,t){return c(e)?p(e[t]):void 0}o(P,"readNamedField");function p(e){return typeof e=="string"&&e.length>0?e:void 0}o(p,"readNonEmptyString");async function b(e,t){try{return await e(t)}catch(r){return{exitCode:1,stderr:`${l(r)}
12
+ `,stdout:""}}}o(b,"runGhAfterMerge");var ee=Z(X),te=[{name:"body-file",takesValue:!0},{name:"delete",takesValue:!0},{name:"pr",takesValue:!0},{name:"strategy",takesValue:!0},{name:"title-file",takesValue:!0}];async function re(){let e=m.argv.slice(2);try{let t=ie(ne(e)),r=await C(t,se);r.ok||(m.stderr.write(r.stderr),R({summary:r.summary}),m.exit(r.exitCode));for(let n of r.warnings)m.stderr.write(`${n}
13
+ `);R(r.result)}catch(t){let r=l(t);m.stderr.write(`merge-gh-pr: ${r}
14
+ `);let n=ae(e);R({summary:g(n===void 0?void 0:`#${n}`,r)}),m.exit(1)}}o(re,"main");N(import.meta.url,"merge-gh-pr")&&await re();function G(e){try{let t=Q(e);return t.isFile()&&t.size>0}catch{return!1}}o(G,"isNonEmptyFile");function ne(e){let{flags:t,positionals:r}=$(e,te);if(r.length>0)throw new Error(`unexpected argument: ${r.join(" ")}`);let n=S(t),i=O(n,"pr");if(!/^[1-9]\d*$/.test(i))throw new Error(`--pr must be a positive integer, got '${i}'`);return{bodyFile:n["body-file"],deletionStrategy:A(n,"delete",D),prNumber:Number(i),strategy:A(n,"strategy",F),titleFile:n["title-file"]}}o(ne,"parseArgs");function ie(e){let t=e.strategy!=="rebase",r=e.strategy==="squash",n;if(r&&(n=oe(e.titleFile)),t){if(e.bodyFile===void 0)throw new Error(`--body-file is required for --strategy ${e.strategy}`);if(!G(e.bodyFile))throw new Error(`Body file missing or empty: ${e.bodyFile}`)}return{bodyPath:t?e.bodyFile:void 0,deletionStrategy:e.deletionStrategy,prNumber:e.prNumber,strategy:e.strategy,title:n}}o(ie,"readRequest");function oe(e){if(e===void 0)throw new Error("--title-file is required for --strategy squash");if(!G(e))throw new Error(`Title file missing or empty: ${e}`);let t=Y(e,"utf8").replace(/\r?\n$/,"");if(t.length===0)throw new Error(`Title file missing or empty: ${e}`);return t}o(oe,"readTitle");function A(e,t,r){let n=O(e,t),i=r.find(s=>s===n);if(i===void 0)throw new Error(`--${t} must be one of ${r.join(", ")}, got '${n}'`);return i}o(A,"requireMember");function O(e,t){let r=e[t];if(r===void 0)throw new Error(`--${t} is required`);return r}o(O,"requireValue");async function se(e){try{let{stderr:t,stdout:r}=await ee("gh",e,{maxBuffer:16777216});return{exitCode:0,stderr:t,stdout:r}}catch(t){if(M(t))throw new Error("gh is not installed or not on PATH",{cause:t});if(c(t)&&typeof t.code=="number"&&typeof t.stderr=="string"&&typeof t.stdout=="string")return{exitCode:t.code,stderr:t.stderr,stdout:t.stdout};throw t}}o(se,"runGh");function ae(e){for(let[t,r]of e.entries()){let n=r==="--pr"?e[t+1]:r.startsWith("--pr=")?r.slice(5):void 0;if(n!==void 0)return/^[1-9]\d*$/.test(n)?Number(n):void 0}}o(ae,"scanPrNumber");function R(e){m.stdout.write(`${JSON.stringify(e,null,2)}
15
+ `)}o(R,"writeJson");
@@ -10,24 +10,25 @@ Merge a pull request on the appropriate platform. `describe-change.mjs` resolves
10
10
 
11
11
  ## Optional arguments
12
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` |
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`. | per `merge_strategy` |
20
+ | `--delete {v}` | Override branch deletion: `both`, `remote`, or `none`. `both` is GitHub-only. | per `merge_deletion_strategy` |
21
+ | `--confirm` | Show the approval gate even when `merge.approval` is `auto`. | per `merge_approval` |
21
22
 
22
- ## Reserved preference keys
23
+ ## Preference keys
23
24
 
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
+ Three keys in `.agents/preferences.yaml` and `~/.agents/preferences.yaml` set this skill's defaults: `merge.approval` (step 6), `merge.strategy`, and `merge.deletion_strategy` (step 4). Each value resolves from the CLI flag, then the project file, then the user file, then the built-in default (`ask`, `squash`, `remote`). `derive-session-context` resolves the files and reports `merge_approval`, `merge_strategy`, and `merge_deletion_strategy`; it fails on a value outside the accepted set, naming the file, the key, and the accepted values, which stops the run at step 1. The guidance package's `docs/preferences.md` lists the accepted values.
25
26
 
26
27
  ## Process
27
28
 
28
29
  ### 1. Get session context
29
30
 
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
+ 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`, `pr_url`, `merge_approval`, `merge_strategy`, and `merge_deletion_strategy` from it.
31
32
 
32
33
  ### 2. Resolve the PR
33
34
 
@@ -38,15 +39,15 @@ Read the PR's metadata for the steps below, dispatching on `scm`:
38
39
  - **`"github"`**:
39
40
 
40
41
  ```bash
41
- gh pr view {pr} --json number,title,body,labels,headRefName,headRefOid,baseRefName,isCrossRepository,url
42
+ gh pr view {pr} --json number,title,body,labels,headRefName,headRefOid,baseRefName,isCrossRepository,mergeStateStatus,url
42
43
  ```
43
44
 
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
+ - **`"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. Bitbucket does not report a counterpart to `mergeStateStatus`, so leave it unset.
45
46
  - **Unknown or missing**: Ask the user which platform to use, matching step 7's behavior.
46
47
 
47
48
  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
 
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
+ Capture `title` (PR title), `body` (PR body), `labels` (label objects), `number`, `headRefName` (head branch), `headRefOid` (head commit), `baseRefName` (base branch), `isCrossRepository`, and `mergeStateStatus` from the response. The steps below use them.
50
51
 
51
52
  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
 
@@ -89,7 +90,7 @@ The guard keeps a failed read out of the merge. The redirect above truncates the
89
90
 
90
91
  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
 
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
+ 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, and ends the reply with the [refusal summary](#11-report-the-outcome).
93
94
 
94
95
  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
 
@@ -130,8 +131,8 @@ On no, and when `{skill:add-change-record}` stopped for any of its own reasons,
130
131
  ### 4. Resolve strategy and deletion strategy
131
132
 
132
133
  ```
133
- resolveStrategy(cliOverride): return cliOverride ?? 'squash'
134
- resolveDeletionStrategy(cliOverride): return cliOverride ?? 'remote'
134
+ resolveStrategy(cliOverride): return cliOverride ?? merge_strategy
135
+ resolveDeletionStrategy(cliOverride): return cliOverride ?? merge_deletion_strategy
135
136
  ```
136
137
 
137
138
  `--delete both|remote|none` map directly to the same string values.
@@ -221,6 +222,17 @@ When asking option-style questions, follow [option format](#option-format). (Rei
221
222
 
222
223
  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
 
225
+ **Decide whether to ask.** The gate asks unless every one of these holds, in which case the run merges without asking:
226
+
227
+ - `merge_approval` is `auto`, and `--confirm` was not passed.
228
+ - `scm` is `"github"`. Bitbucket does not report merge state, so the gate fails closed there.
229
+ - The report's `notices` is empty.
230
+ - The run did not decide anything of its own: It did not amend an entry in this step, did not add an override in this step on its own decision, and step 5 did not dispatch the drafter. An override passed as a flag and an answer that the developer gave are not the run's decisions, and a work-type test that agrees with the record adds nothing.
231
+ - `effective_record.breaking` is false.
232
+ - `mergeStateStatus` is `CLEAN` or `HAS_HOOKS`. Any other value, or a missing one, means that a check is pending or failing, or that the state is unknown.
233
+
234
+ When the gate asks because one of these failed, do not add a line saying which: The notice, the decision, the `!` in the title, or the merge state already appears in the report.
235
+
224
236
  Render the proposed merge to the user:
225
237
 
226
238
  ```
@@ -263,6 +275,12 @@ Render `{confirmation}` so that the ask itself names every destructive side effe
263
275
  - `remote` → `Merge PR #{pr_number} and delete the remote branch {headRefName}? 👍🏼👎🏼`
264
276
  - `both` → `Merge PR #{pr_number} and delete the local and remote branch {headRefName}? 👍🏼👎🏼`
265
277
 
278
+ When the run merges without asking, render the authorization line in place of the ask, naming the same side effects, and continue to step 7:
279
+
280
+ - `none` → `Merging PR #{pr_number} without confirmation, as merge.approval: auto authorizes.`
281
+ - `remote` → `Merging PR #{pr_number} and deleting the remote branch {headRefName} without confirmation, as merge.approval: auto authorizes.`
282
+ - `both` → `Merging PR #{pr_number} and deleting the local and remote branch {headRefName} without confirmation, as merge.approval: auto authorizes.`
283
+
266
284
  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
285
 
268
286
  If the user declines, stop without making an API call or writing an artifact. If they approve, continue.
@@ -297,6 +315,8 @@ The merge block takes a comparison of its own because `body` excludes the `chang
297
315
 
298
316
  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
317
 
318
+ When step 6 merged without asking, the approved values are the ones that it rendered: its `merge_title`, the report's `body` and `merge_block`, and the published body. A change then shows the gate, and the rest of the run proceeds as if `merge_approval` were `ask`.
319
+
300
320
  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
321
 
302
322
  ### 9. Check the published body
@@ -313,7 +333,7 @@ node {harness_home_dir}/scripts/describe-change.mjs check-merge-body \
313
333
 
314
334
  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
335
 
316
- If it exits non-zero, stop with its message. Nothing is merged.
336
+ If it exits non-zero, stop, and end the reply with the [refusal summary](#11-report-the-outcome), with its message as the reason. Nothing is merged.
317
337
 
318
338
  ### 10. Call delegate
319
339
 
@@ -332,11 +352,26 @@ Pass the following inputs to the selected delegate per the delegate interface:
332
352
 
333
353
  The orchestrator never passes a title that `defects` blocks, or a `prompt` sentinel, to the delegate: All values are concrete by this point.
334
354
 
335
- If the delegate stopped or failed, stop. Otherwise continue.
355
+ If the delegate stopped or failed, stop: Its reply ends with its own summary. Otherwise continue.
336
356
 
337
357
  ### 11. Report the outcome
338
358
 
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.
359
+ Report nothing beyond the delegate's completion report, and invoke nothing but step 12's offer to close the parent. The completion report ends with the delegate's outcome summary, a rule followed by a heading that states the outcome. Print the summary verbatim, as the last element of the reply, or directly above step 12's action-items block when the turn has an ask. Do not write any sentence of your own before it that restates the outcome: The heading states it, and the bottom of the reply is the part that the terminal shows first.
360
+
361
+ Every stop after the merge is approved, at step 6's gate or by `merge_approval: auto`, ends the reply the same way. When the delegate did not produce the summary, because the run stopped at step 8 or step 9, end the reply with the refusal summary:
362
+
363
+ ```
364
+ ---
365
+
366
+ ## ❌ Not merged
367
+
368
+ PR: {url}
369
+ Reason: {reason}
370
+ ```
371
+
372
+ `{url}` is the PR's URL from step 2. Keep the lines single-spaced: When the reason spans several lines, drop its blank lines.
373
+
374
+ A decline at step 6's gate, or at the gate that step 8 re-renders, is the developer's own choice, and keeps the form that those steps state. 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
375
 
341
376
  ### 12. Offer to close the parent
342
377
 
@@ -122,6 +122,7 @@ On approval, run all captures first, then a single deletion pass:
122
122
  ### Composing a capture
123
123
 
124
124
  - `--store @feedback`: The feedback KB is configured in the registry, not chosen per memory.
125
+ - `--shared`: Only after a `shared-store` refusal, and only for a capture that passes the check in `{skill:capture-event}`'s shared-stores rule. A capture that fails the check, or for which the check is not conclusive, is a failed capture: Its memory stays in place, per step 5.
125
126
  - `--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.
126
127
  - `--skill <slug>` when the lesson targets a specific skill.
127
128
  - `--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.
@@ -17,7 +17,7 @@ Create an implementation plan from a ticket or task. `plan` is the standalone pl
17
17
 
18
18
  ## Resolve the task source
19
19
 
20
- Resolve the task source using the [ticket source resolution](../_data/ticket-source-resolution.md) table, then read the resolved ticket or description and plan against it. When the source resolves to a URL, persist it to the branch manifest per [Stored ticket URL](../_data/ticket-source-resolution.md#stored-ticket-url) so that a later session does not need a ticket argument. Report the ticket's open blockers per [Open blockers](../_data/ticket-source-resolution.md#open-blockers), and continue: A blocker does not stop planning. Then check the branch per [branch currency](../_data/branch-currency.md), reading `branch_name` and `default_branch` from the manifest that `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` emits, and passing the paths that the ticket names. `plan` does not run the staleness check or interactive design Q&A; that ceremony belongs to `design-and-plan`. The one exception is the project's declared stage: Read `project_maturity`, `project_sensitivity`, and `project_audience` from the manifest that `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` emits, treat them as the premises of every security, availability, and infrastructure decision per [project stage](../_data/project-stage.md), and ask for each undeclared value at the plan checkpoint, adding a task that declares each answered value. When the source is a free-form description rather than a ticket, plan directly from the description.
20
+ Resolve the task source using the [ticket source resolution](../_data/ticket-source-resolution.md) table, then read the resolved ticket or description and plan against it. When the source resolves to a URL, persist it to the branch manifest per [Stored ticket URL](../_data/ticket-source-resolution.md#stored-ticket-url) so that a later session does not need a ticket argument. Report the ticket's open blockers per [Open blockers](../_data/ticket-source-resolution.md#open-blockers), and continue: A blocker does not stop planning. Then check the branch per [branch currency](../_data/branch-currency.md), reading `branch_name` and `default_branch` from the manifest that `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` emits, and passing the paths that the ticket names. `plan` does not run the staleness check or interactive design Q&A; that ceremony belongs to `design-and-plan`. The one exception is the project's declared stage: Read `project_maturity`, `project_sensitivity`, `project_audience`, and `project_stages` from the manifest that `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` emits, take the stage that governs the work's paths, and treat it as the premise of every security, availability, infrastructure, and verification decision per [project stage](../_data/project-stage.md), and ask for each undeclared value at the plan checkpoint, adding a task that declares each answered value. When the source is a free-form description rather than a ticket, plan directly from the description.
21
21
 
22
22
  When the resolved source is a local artifact, read its `provenance.skill`: `design-and-plan` means an interactive design phase ran; another skill means the ticket was authored without one. Remote issues and free-form descriptions do not have provenance.
23
23
 
@@ -85,3 +85,5 @@ Follow the options, output format, and recommendation rules in [next-steps optio
85
85
  <!-- include: ../_partials/next-steps-after-plan.md / -->
86
86
 
87
87
  <!-- include: ../_partials/option-format.md / -->
88
+
89
+ <!-- include: ../_partials/implementation-order-list.md / -->
@@ -145,7 +145,9 @@ Report what the check changed, in one line per rule that fired.
145
145
 
146
146
  ### 4. Checkpoint
147
147
 
148
- Save the brief with {skill:save-artifact} as a ticket-level `brief` artifact, and show it to the developer. Do not post it to the ticket without their approval: Posting is remote state. Ask in one action-items block: approve the brief, and post it as a ticket comment or not.
148
+ Save the brief with {skill:save-artifact} as a ticket-level `brief` artifact, and show it to the developer. Ask for approval in one confirmation whose wording says that approval also posts the brief on the ticket as a comment: Posting is remote state, and the approval is the developer's consent to it. When the developer redirects, revise the brief, save it again, and show it again; post only the version that the developer approves.
149
+
150
+ Once the developer approves the brief, post it on the ticket without a further ask. The comment opens with a one-line summary that names the lenses and the brief artifact's path, written `~/`-relative as in the [closing post](../_data/spike-conventions.md#closing-post), and contains the full brief in a `<details>` block below the summary, so that the ticket stays readable. Pass the body through a file, per [gh body file](../_data/ticket-source-resolution.md#gh-body-file). Before posting, read the ticket's comments, and skip the post when a comment already opens with the summary line, so that a rerun does not post the brief twice. When the session does not have a remote ticket, skip the post and say so in one line. When the post fails, report the failure and continue with step 5.
149
151
 
150
152
  <!-- include: ../_partials/action-items.md / -->
151
153
 
@@ -264,3 +264,5 @@ Follow the options, output format, and recommendation rules in [next-steps optio
264
264
  <!-- include: ../_partials/next-steps-after-plan.md / -->
265
265
 
266
266
  <!-- include: ../_partials/option-format.md / -->
267
+
268
+ <!-- include: ../_partials/implementation-order-list.md / -->
@@ -318,7 +318,7 @@ Ticket and PR-description deltas render as a flat list, one line per change. Sou
318
318
 
319
319
  **Notation.** The preview is a delta. It never restates the ticket, the PR description, or a finding's Recommendation, which would duplicate the artifact in the terminal, and it contains one entry per change:
320
320
 
321
- - **Ticket targets** derive their delta from the in-conflict criteria rows of `## Specification compliance`'s ticket subsection, and from nothing else. Unplanned work is never a source: Implementation that goes beyond the criteria is not a deviation, so it does not yield a line. Because a ticket's `## Problem`, `## Context`, and `## Proposed solution` record what was known and proposed when it was written, this menu does not offer an edit that changes them; a divergence between one of them and the implementation is reported in the PR description instead.
321
+ - **Ticket targets** derive their delta from the in-conflict criteria rows of `## Specification compliance`'s ticket subsection, and from nothing else. Unplanned work is never a source: Implementation that goes beyond the criteria is not a deviation, so it does not yield a line. Because a ticket's `## Problem`, `## Context`, and `## Proposed solution` record what was known and proposed when it was written, this menu does not offer an edit that changes them; a divergence between one of them and the implementation goes into the PR description's `## Notes for reviewers` instead, and only when it changes what a reviewer checks, per the reader test that `summarize-change` states.
322
322
  - `Reword: {old} → {new}` for a criterion whose direction the implementation deliberately contradicts
323
323
  - `Drop: {criterion}` for a criterion that the implementation deliberately abandoned, never for one that it has not yet met
324
324
  - **PR-description targets** render the concrete claim changes, each keyed to the divergent `D{n}` row from which it came: `D2: {claim as written} → {claim as built}`.
@@ -101,7 +101,7 @@ The same defects in tests that the change does not add, split, or modify are Leg
101
101
 
102
102
  Two defects against the test-data and timeout rules in the `testing-conventions` skill are Warnings:
103
103
 
104
- - **A raised timeout.** The change raises a hook's, a test's, or a tier's timeout, in a test or in config. The proposed change reduces the work by the fixes that the skill names. A reason stated in the plan or the pull-request description does not exempt the raise: Check the reason against those fixes, and report the finding when one of them still applies.
104
+ - **A raised timeout.** The change raises a hook's, a test's, or a tier's timeout, in a test or in config. The proposed change reduces the work by the fixes that the skill names. A reason stated in the plan or in the pull-request description's `## Notes for reviewers` does not exempt the raise: Check the reason against those fixes, and report the finding when one of them still applies.
105
105
  - **A test that renders or builds production-scale data.** The proposed change passes the smallest data that proves the behavior, and makes the data injectable when the code under test reads it from a module-level singleton, even when the singleton is in code that the change does not touch. The diff does not show the data's size, so read what the code under test imports.
106
106
 
107
107
  The same defects in tests and config that the change does not add or modify are Legacy.