codeassembly-guidance 0.6.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.meta/changelog.json +446 -0
- package/CHANGELOG.md +107 -0
- package/README.md +47 -51
- package/bin/codeassembly-validate-preferences.js +2 -8
- package/content/_partials/diff-audit-checklist.md +1 -0
- package/content/_partials/kb-unsearched-private-stores.md +6 -0
- package/content/_partials/plain-speech.md +2 -2
- package/content/_partials/ticket-assessment.md +3 -3
- package/content/codeassembly-content.yaml +8 -0
- package/content/collections/recommended.md +6 -0
- package/content/collections/williamthorsen.md +2 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +6 -3
- package/content/guidance/rulebooks/cross-repo-migration-conventions.md +27 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +2 -2
- package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
- package/content/guidance/rulebooks/visual-design-conventions.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +3 -18
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +7 -1
- package/content/guidance/rulebooks/williamthorsen-visual-design-preferences.md +14 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +5 -3
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -20
- package/content/guidance/shared/AGENTS.md +3 -4
- package/content/scripts/README.md +1 -1
- package/content/scripts/check-branch-currency.mjs +7 -7
- package/content/scripts/check-prose.mjs +38 -38
- package/content/scripts/describe-change.mjs +89 -89
- package/content/scripts/manage-jira-ticket.mjs +162 -160
- package/content/scripts/select-lede-exemplars.mjs +85 -85
- package/content/scripts/validate-preferences.mjs +41 -41
- package/content/skills/_data/artifact-conventions.md +3 -3
- package/content/skills/_data/entry-points.md +1 -1
- package/content/skills/_data/project-stage.md +9 -5
- package/content/skills/_data/reduced-object-relatives.md +15 -0
- package/content/skills/_data/spike-conventions.md +16 -6
- package/content/skills/_data/ticket-evaluation.md +3 -0
- package/content/skills/_partials/implementation-order-list.md +27 -0
- package/content/skills/_partials/merge-settled-criterion.md +1 -0
- package/content/skills/_partials/next-steps-after-plan.md +2 -2
- package/content/skills/_partials/plan-template.md +3 -1
- package/content/skills/_partials/resolve-plan-and-ticket.md +2 -2
- package/content/skills/_partials/split-launch-prompts.md +1 -1
- package/content/skills/_partials/split-ticket-create.md +1 -1
- package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +3 -3
- package/content/skills/analyze-performance/SKILL.md +1 -1
- package/content/skills/assess-code-health/SKILL.md +4 -4
- package/content/skills/assess-code-health/assess-code-health.mjs +20 -20
- package/content/skills/assess-ticket/SKILL.md +3 -1
- package/content/skills/assess-ticket/next-steps-after-assessment.md +11 -14
- package/content/skills/assess-usability/SKILL.md +4 -4
- package/content/skills/capture-event/SKILL.md +20 -11
- package/content/skills/capture-event/capture-event.mjs +123 -123
- package/content/skills/capture-feedback/SKILL.md +2 -1
- package/content/skills/capture-lede-decision/SKILL.md +1 -1
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
- package/content/skills/collaborate/SKILL.md +1 -1
- package/content/skills/condense-branch/SKILL.md +18 -36
- package/content/skills/condense-branch/condense-branch.mjs +17 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +9 -11
- package/content/skills/create-commit/SKILL.md +1 -1
- package/content/skills/create-devlog/SKILL.md +4 -4
- package/content/skills/create-gh-pr/SKILL.md +9 -11
- package/content/skills/create-pr/SKILL.md +10 -12
- package/content/skills/create-ticket/SKILL.md +22 -15
- package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
- package/content/skills/curate-feedback/SKILL.md +2 -2
- package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
- package/content/skills/derive-session-context/derive-session-context.mjs +120 -120
- package/content/skills/design-and-plan/SKILL.md +10 -8
- package/content/skills/groom-backlog/groom-backlog.mjs +15 -15
- package/content/skills/implement-plan/SKILL.md +4 -2
- package/content/skills/implementation-order/implementation-order.mjs +67 -0
- package/content/skills/index-prototypes/SKILL.md +2 -2
- package/content/skills/investigate-spike/SKILL.md +3 -3
- package/content/skills/kb-add/SKILL.md +12 -3
- package/content/skills/kb-add/kb-add.mjs +88 -88
- package/content/skills/kb-curate/kb-curate.mjs +88 -88
- package/content/skills/kb-edit/kb-edit.mjs +90 -90
- package/content/skills/kb-retrieve/SKILL.md +8 -3
- package/content/skills/kb-retrieve/kb-retrieve.mjs +104 -104
- package/content/skills/kb-retrieve-events/SKILL.md +8 -3
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +113 -113
- package/content/skills/kb-update-events/kb-update-events.mjs +92 -92
- package/content/skills/lesson-clusters/lesson-clusters.mjs +102 -102
- package/content/skills/list-gh-progress-items/SKILL.md +36 -0
- package/content/skills/list-gh-progress-items/list-gh-progress-items.mjs +68 -0
- package/content/skills/list-implementation-order/SKILL.md +23 -0
- package/content/skills/merge-bb-pr/SKILL.md +40 -19
- package/content/skills/merge-gh-pr/SKILL.md +34 -23
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
- package/content/skills/merge-pr/SKILL.md +64 -31
- package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
- package/content/skills/plan/SKILL.md +5 -3
- package/content/skills/prepare-prototype-brief/SKILL.md +5 -3
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +22 -22
- package/content/skills/refine-plan/SKILL.md +5 -3
- package/content/skills/refine-prototype/SKILL.md +2 -1
- package/content/skills/respond-to-review/SKILL.md +4 -4
- package/content/skills/review-bb-pr/SKILL.md +1 -2
- package/content/skills/review-branch/SKILL.md +19 -14
- package/content/skills/review-criteria/SKILL.md +2 -2
- package/content/skills/review-gh-pr/SKILL.md +1 -2
- package/content/skills/review-pr/SKILL.md +2 -3
- package/content/skills/revise-prose/revise-prose.mjs +109 -109
- package/content/skills/save-artifact/SKILL.md +4 -6
- package/content/skills/save-plan/SKILL.md +4 -2
- package/content/skills/start-ticket/SKILL.md +1 -1
- package/content/skills/streamline-guidance/streamline-guidance.mjs +80 -80
- package/content/skills/summarize-change/SKILL.md +20 -9
- package/content/skills/summarize-chat/SKILL.md +2 -2
- package/content/skills/testing-conventions/SKILL.md +2 -2
- package/content/skills/triage-feedback/SKILL.md +6 -2
- package/content/skills/triage-spike-findings/SKILL.md +33 -24
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +19 -19
- package/content/skills/update-project-guidance/SKILL.md +1 -1
- package/content/skills/wrap-up/SKILL.md +8 -4
- package/content/skills/write-progress-report/SKILL.md +111 -0
- package/content/skills/write-progress-report/write-progress-report.mjs +150 -0
- package/content/subagents/disposition-challenger.md +7 -6
- package/content/subagents/entry-drafter.md +2 -0
- package/content/subagents/usability-assessor.md +3 -2
- package/package.json +13 -12
- package/schemas/preferences.v1.json +82 -8
- 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 and that have work of their own, 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, its title, and, when the conversation establishes it, the repository in which the ticket is implemented. For an umbrella, name its children as well: The list leaves the umbrella out.
|
|
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 / -->
|
|
@@ -10,16 +10,14 @@ Internal delegate that merges a pull request on Bitbucket. Called by `merge-pr`
|
|
|
10
10
|
|
|
11
11
|
## Delegate interface
|
|
12
12
|
|
|
13
|
-
| Input | Type | Description
|
|
14
|
-
| ------------------- | ------------------------------- |
|
|
15
|
-
| `pr_number` | number | PR to merge
|
|
16
|
-
| `title` | string | Pre-rendered merge-commit title
|
|
17
|
-
| `body` | string | Pre-composed merge-commit body
|
|
18
|
-
| `strategy` | `squash` \| `merge` \| `rebase` | Concrete strategy (no `prompt` sentinel)
|
|
19
|
-
| `deletion_strategy` | `both` \| `remote` \| `none` | Which branches to delete after merge
|
|
20
|
-
| `
|
|
21
|
-
| `project_slug` | string | Project slug for artifact path resolution |
|
|
22
|
-
| `artifact_base_dir` | string | Base directory for artifact storage |
|
|
13
|
+
| Input | Type | Description |
|
|
14
|
+
| ------------------- | ------------------------------- | --------------------------------------------------------- |
|
|
15
|
+
| `pr_number` | number | PR to merge |
|
|
16
|
+
| `title` | string | Pre-rendered merge-commit title |
|
|
17
|
+
| `body` | string | Pre-composed merge-commit body |
|
|
18
|
+
| `strategy` | `squash` \| `merge` \| `rebase` | Concrete strategy (no `prompt` sentinel) |
|
|
19
|
+
| `deletion_strategy` | `both` \| `remote` \| `none` | Which branches to delete after merge |
|
|
20
|
+
| `ticket_dir` | string | Ticket artifact directory, in which the artifact is saved |
|
|
23
21
|
|
|
24
22
|
## Bitbucket access
|
|
25
23
|
|
|
@@ -33,13 +31,15 @@ Make every Bitbucket call below with the tool named in [Bitbucket pull-request a
|
|
|
33
31
|
|
|
34
32
|
<!-- include: ../_partials/bitbucket-delete-both-refusal.md / -->
|
|
35
33
|
|
|
34
|
+
End the reply with the [refusal summary](#refusal-summary), with that refusal as its reason.
|
|
35
|
+
|
|
36
36
|
`remote` and `none` map to `closeSourceBranch` in step 4.
|
|
37
37
|
|
|
38
38
|
### 2. Fetch and validate PR state
|
|
39
39
|
|
|
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`.
|
|
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`, `destination.branch.name`, and `links.html.href`.
|
|
41
41
|
|
|
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."
|
|
42
|
+
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
43
|
|
|
44
44
|
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
45
|
|
|
@@ -75,7 +75,7 @@ Passing a composed title for `merge_commit` diverges from `merge-gh-pr`, which o
|
|
|
75
75
|
|
|
76
76
|
Set `closeSourceBranch` to `true` for `deletion_strategy: remote` and `false` for `none`.
|
|
77
77
|
|
|
78
|
-
Call `action: "merge"` with `prId`, `mergeStrategy`, `message` (except for `rebase_fast_forward`), and `closeSourceBranch`. If the call fails,
|
|
78
|
+
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
79
|
|
|
80
80
|
### 5. Capture the merge result
|
|
81
81
|
|
|
@@ -89,7 +89,7 @@ Success in step 4 means that the PR was merged, so a `merge_commit.hash` absent
|
|
|
89
89
|
|
|
90
90
|
Save a `merge` artifact in the ticket directory, in the same format that `merge-gh-pr` writes, so that `capture-lede-decision` reads it on this platform as it does on GitHub.
|
|
91
91
|
|
|
92
|
-
Ticket directory: `{
|
|
92
|
+
Ticket directory: `{ticket_dir}/`
|
|
93
93
|
|
|
94
94
|
`mkdir -p` the target directory before writing.
|
|
95
95
|
|
|
@@ -125,12 +125,33 @@ Branch: {source.branch.name}
|
|
|
125
125
|
|
|
126
126
|
## Completion
|
|
127
127
|
|
|
128
|
+
Report `Artifact saved: {artifact path}` on a line of its own, then print these lines as the last element of the reply:
|
|
129
|
+
|
|
128
130
|
```
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## 🔀 Merged into {destination.branch.name} · {strategy name} · {first 7 characters of merge_commit.hash, or unavailable}
|
|
134
|
+
|
|
135
|
+
{title line}
|
|
136
|
+
PR: {links.html.href}
|
|
137
|
+
Remote branch {source.branch.name}: {🗑️ Deleted for deletion_strategy: remote, ⏸️ Kept for none}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
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.
|
|
141
|
+
|
|
142
|
+
### Refusal summary
|
|
143
|
+
|
|
144
|
+
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:
|
|
145
|
+
|
|
134
146
|
```
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
## ❌ Not merged
|
|
150
|
+
|
|
151
|
+
PR: {links.html.href, or #{pr_number} when step 2 did not read it}
|
|
152
|
+
Reason: {reason}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Keep the lines single-spaced: When the reason spans several lines, drop its blank lines.
|
|
135
156
|
|
|
136
157
|
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.
|
|
@@ -10,16 +10,14 @@ Internal delegate that merges a pull request on GitHub. Called by `merge-pr` wit
|
|
|
10
10
|
|
|
11
11
|
## Delegate interface
|
|
12
12
|
|
|
13
|
-
| Input | Type | Description
|
|
14
|
-
| ------------------- | ------------------------------- |
|
|
15
|
-
| `pr_number` | number | PR to merge
|
|
16
|
-
| `title` | string | Pre-rendered merge-commit title
|
|
17
|
-
| `body` | string | Pre-composed merge-commit body
|
|
18
|
-
| `strategy` | `squash` \| `merge` \| `rebase` | Concrete strategy (no `prompt` sentinel)
|
|
19
|
-
| `deletion_strategy` | `both` \| `remote` \| `none` | Which branches to delete after merge
|
|
20
|
-
| `
|
|
21
|
-
| `project_slug` | string | Project slug for artifact path resolution |
|
|
22
|
-
| `artifact_base_dir` | string | Base directory for artifact storage |
|
|
13
|
+
| Input | Type | Description |
|
|
14
|
+
| ------------------- | ------------------------------- | --------------------------------------------------------- |
|
|
15
|
+
| `pr_number` | number | PR to merge |
|
|
16
|
+
| `title` | string | Pre-rendered merge-commit title |
|
|
17
|
+
| `body` | string | Pre-composed merge-commit body |
|
|
18
|
+
| `strategy` | `squash` \| `merge` \| `rebase` | Concrete strategy (no `prompt` sentinel) |
|
|
19
|
+
| `deletion_strategy` | `both` \| `remote` \| `none` | Which branches to delete after merge |
|
|
20
|
+
| `ticket_dir` | string | Ticket artifact directory, in which the artifact is saved |
|
|
23
21
|
|
|
24
22
|
## Process
|
|
25
23
|
|
|
@@ -28,14 +26,16 @@ Internal delegate that merges a pull request on GitHub. Called by `merge-pr` wit
|
|
|
28
26
|
Use a single `gh pr view` call to fetch every field needed for validation:
|
|
29
27
|
|
|
30
28
|
```bash
|
|
31
|
-
gh pr view {pr_number} --json state,isDraft,mergeable,mergeStateStatus,reviewDecision,headRefName,isCrossRepository,baseRefName
|
|
29
|
+
gh pr view {pr_number} --json state,isDraft,mergeable,mergeStateStatus,reviewDecision,headRefName,isCrossRepository,baseRefName,url
|
|
32
30
|
```
|
|
33
31
|
|
|
34
32
|
Parse the JSON with a real parser (`python3 -c "import sys,json; ..."` or `jq`). Do not regex-extract.
|
|
35
33
|
|
|
34
|
+
If the call fails, stop, and end the reply with the [refusal summary](#refusal-summary), with `gh`'s stderr as the reason.
|
|
35
|
+
|
|
36
36
|
### 2. Run pre-merge checks
|
|
37
37
|
|
|
38
|
-
Refuse the merge with a specific reason on any of the following. On each refusal,
|
|
38
|
+
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
39
|
|
|
40
40
|
| Field | Failure condition | Refusal reason |
|
|
41
41
|
| ------------------ | ------------------------------------------------------------ | --------------------------------------------------------------------------- |
|
|
@@ -69,13 +69,13 @@ git fetch origin
|
|
|
69
69
|
git rev-list --left-right --count "origin/{headRefName}...HEAD"
|
|
70
70
|
```
|
|
71
71
|
|
|
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."
|
|
72
|
+
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
73
|
|
|
74
74
|
### 4. Write the title and body to scratch files
|
|
75
75
|
|
|
76
76
|
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
77
|
|
|
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.
|
|
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 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
79
|
|
|
80
80
|
### 5. Merge and delete the branch
|
|
81
81
|
|
|
@@ -99,25 +99,28 @@ On success, the helper exits 0 and prints JSON on stdout:
|
|
|
99
99
|
"headRefName": "feature/cache",
|
|
100
100
|
"mergeCommit": { "oid": "abc123" },
|
|
101
101
|
"mergedAt": "2026-09-28T22:00:00Z",
|
|
102
|
+
"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
103
|
"url": "https://github.com/acme/widgets/pull/42"
|
|
103
104
|
}
|
|
104
105
|
```
|
|
105
106
|
|
|
107
|
+
`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.
|
|
108
|
+
|
|
106
109
|
`branchDeletion` is one of these values:
|
|
107
110
|
|
|
108
111
|
- `deleted`: The helper deleted the branch.
|
|
109
112
|
- `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
|
|
113
|
+
- `failed`: A warning on stderr gives the reason, which the summary's branch line repeats. The merge still succeeded, so continue.
|
|
111
114
|
- `by-gh`: The deletion strategy was `both`, and `gh pr merge --delete-branch` handled the deletion.
|
|
112
115
|
- `not-requested`: The deletion strategy was `none`.
|
|
113
116
|
|
|
114
|
-
When the helper exits non-zero,
|
|
117
|
+
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
118
|
|
|
116
119
|
### 6. Save merge artifact
|
|
117
120
|
|
|
118
121
|
Save a `merge` artifact in the ticket directory.
|
|
119
122
|
|
|
120
|
-
Ticket directory: `{
|
|
123
|
+
Ticket directory: `{ticket_dir}/`
|
|
121
124
|
|
|
122
125
|
`mkdir -p` the target directory before writing.
|
|
123
126
|
|
|
@@ -153,15 +156,23 @@ Branch: {headRefName}
|
|
|
153
156
|
|
|
154
157
|
## Completion
|
|
155
158
|
|
|
159
|
+
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.
|
|
160
|
+
|
|
161
|
+
### Refusal summary
|
|
162
|
+
|
|
163
|
+
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:
|
|
164
|
+
|
|
156
165
|
```
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## ❌ Not merged
|
|
169
|
+
|
|
170
|
+
PR: {url, or #{pr_number} when step 1 did not read it}
|
|
171
|
+
Reason: {reason}
|
|
163
172
|
```
|
|
164
173
|
|
|
174
|
+
Keep the lines single-spaced: When the reason spans several lines, drop its blank lines.
|
|
175
|
+
|
|
165
176
|
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
177
|
|
|
167
178
|
<!-- 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
|
|
4
|
-
`),!0}}o(
|
|
5
|
-
${n.stderr}
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
`);
|
|
9
|
-
`)}
|
|
10
|
-
`)
|
|
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`. | `
|
|
20
|
-
| `--delete {v}` | Override branch deletion: `both`, `remote`, or `none`. `both` is GitHub-only. | `
|
|
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
|
-
##
|
|
23
|
+
## Preference keys
|
|
23
24
|
|
|
24
|
-
|
|
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`, `
|
|
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`, `ticket_id`, `ticket_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 `
|
|
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 ??
|
|
134
|
-
resolveDeletionStrategy(cliOverride): return cliOverride ??
|
|
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.
|
|
@@ -217,10 +218,21 @@ A type that the developer named, through `--type` or in an answer at the gate, s
|
|
|
217
218
|
|
|
218
219
|
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
|
|
|
220
|
-
When asking option-style questions, follow [option format](#option-format).
|
|
221
|
+
When asking option-style questions, follow [option format](#option-format).
|
|
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,30 +333,43 @@ 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
|
|
|
320
340
|
Pass the following inputs to the selected delegate per the delegate interface:
|
|
321
341
|
|
|
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
|
-
| `
|
|
330
|
-
| `project_slug` | From session context |
|
|
331
|
-
| `artifact_base_dir` | From session context |
|
|
342
|
+
| Input | Value |
|
|
343
|
+
| ------------------- | ----------------------------------------------------------------------------------------------------- |
|
|
344
|
+
| `pr_number` | Resolved PR number |
|
|
345
|
+
| `title` | Rendered `merge_title` as step 8 last resolved and the user approved |
|
|
346
|
+
| `body` | Published body as step 8 last resolved and the user approved |
|
|
347
|
+
| `strategy` | Resolved strategy from step 4 |
|
|
348
|
+
| `deletion_strategy` | Resolved value from step 4 (`both` \| `remote` \| `none`) |
|
|
349
|
+
| `ticket_dir` | `ticket_dir` from session context, or the directory that {skill:save-artifact} states when it is null |
|
|
332
350
|
|
|
333
351
|
The orchestrator never passes a title that `defects` blocks, or a `prompt` sentinel, to the delegate: All values are concrete by this point.
|
|
334
352
|
|
|
335
|
-
If the delegate stopped or failed, stop. Otherwise continue.
|
|
353
|
+
If the delegate stopped or failed, stop: Its reply ends with its own summary. Otherwise continue.
|
|
336
354
|
|
|
337
355
|
### 11. Report the outcome
|
|
338
356
|
|
|
339
|
-
Report nothing beyond the delegate's completion report, and invoke nothing but step 12's offer to close the parent. The
|
|
357
|
+
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.
|
|
358
|
+
|
|
359
|
+
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:
|
|
360
|
+
|
|
361
|
+
```
|
|
362
|
+
---
|
|
363
|
+
|
|
364
|
+
## ❌ Not merged
|
|
365
|
+
|
|
366
|
+
PR: {url}
|
|
367
|
+
Reason: {reason}
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
`{url}` is the PR's URL from step 2. Keep the lines single-spaced: When the reason spans several lines, drop its blank lines.
|
|
371
|
+
|
|
372
|
+
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
373
|
|
|
341
374
|
### 12. Offer to close the parent
|
|
342
375
|
|
|
@@ -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 `
|
|
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
|
|
|
@@ -54,8 +54,8 @@ Run `{harness_home_dir}/scripts/resolve-frontmatter.sh --skill plan --interactiv
|
|
|
54
54
|
|
|
55
55
|
### Ticket context
|
|
56
56
|
|
|
57
|
-
1. Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `
|
|
58
|
-
2. Save as ticket-level artifact: `{
|
|
57
|
+
1. Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `ticket_dir` from the manifest JSON emitted on stdout. When it is null, use the directory that {skill:save-artifact} states.
|
|
58
|
+
2. Save as ticket-level artifact: `{ticket_dir}/{timestamp}_{slug}_plan.md`
|
|
59
59
|
3. Slug per [artifact conventions](../_data/artifact-conventions.md#naming-conventions).
|
|
60
60
|
|
|
61
61
|
Follow [artifact conventions](../_data/artifact-conventions.md).
|
|
@@ -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 / -->
|
|
@@ -61,7 +61,7 @@ The failure that this prevents: the lens paragraph reproduced as helper text und
|
|
|
61
61
|
|
|
62
62
|
### Require a salience order
|
|
63
63
|
|
|
64
|
-
Require a salience order in every working view: the current state in one place, the next thing to happen more prominent than the rest, and every action visibly an action. Name {rulebook:accessibility-conventions} and {rulebook:ui-copy-conventions} as the floor, including the accessibility rulebook's named-model, placement, toggle, glanceable-state, and button-at-rest rules, and state that usability outranks restraint: A calm or restrained direction never hides a state for which the reader scans. A builder departs from the named model only for a reason, which it reports with its distinctive ideas. Require that a status repeated on every row be a mark, a column, or a style, not a sentence.
|
|
64
|
+
Require a salience order in every working view: the current state in one place, the next thing to happen more prominent than the rest, and every action visibly an action. Name {rulebook:accessibility-conventions}, {rulebook:visual-design-conventions}, and {rulebook:ui-copy-conventions} as the floor, including the accessibility rulebook's named-model, placement, consequence-at-the-control, toggle, glanceable-state, and button-at-rest rules, and state that usability outranks restraint: A calm or restrained direction never hides a state for which the reader scans. A builder departs from the named model only for a reason, which it reports with its distinctive ideas. Require that a status repeated on every row be a mark, a column, or a style, not a sentence.
|
|
65
65
|
|
|
66
66
|
The failure that this prevents: a page in one colour, in which the operator hunts for the control, "Hidden from the players." written out on every hidden row, and an expiry column in plain text, in which the operator reads every row to find the expired ones.
|
|
67
67
|
|
|
@@ -87,7 +87,7 @@ Write the brief in this order, with these headings:
|
|
|
87
87
|
2. **Settled intent.** Bullets. Each is a decision, with its reason when the reason constrains the design.
|
|
88
88
|
3. **Deliverable.** The file and its path per {skill:index-prototypes}; the constraints (self-contained, opens from `file://`, inline CSS and JavaScript, no framework, readable with JavaScript off, phone width, every loop bounded by an iteration count or a time limit); the mechanism that must run; the demo control that plays the written scene; a full-screen mode when the product has an audience view. The demo chrome (the demo control, scene captions, the lens note, the data-model note, the API list) is in a band visibly distinct from the product surface, and every part of it is inside an element that has the `data-demo` attribute. The band's first line is the id from the dispatch block and the prototype's title, `{id} {title}`. The page's `<title>` is `{set title} - {id} {title}`, with the set title and the id from the dispatch block.
|
|
89
89
|
4. **Sections.** Numbered, each a noun phrase plus what it contains and a length bound. None asks for persuasion; one is the scene, exhibited; one is the data-model note when the product stores data; one is the API list when the product has an API.
|
|
90
|
-
5. **Quality bar.** Works, legible, accessible, and within the copy rules, with {rulebook:accessibility-conventions} and {rulebook:ui-copy-conventions} named, the design skill to invoke before markup, and the salience order required.
|
|
90
|
+
5. **Quality bar.** Works, legible, accessible, and within the copy rules, with {rulebook:accessibility-conventions}, {rulebook:visual-design-conventions}, and {rulebook:ui-copy-conventions} named, the design skill to invoke before markup, and the salience order required.
|
|
91
91
|
6. **How this round is judged.** The criteria, in the reviewer's voice, with the divergence between lenses named as the point of the round. One criterion is the copy: "Read every string on the product surface as its user opening the page for the tenth time. A string that explains the page, reassures, or repeats the brief, and any copy over the budget in {rulebook:ui-copy-conventions}, is a defect." Another is the glanceable state: "A list in which the reader must read each item to find a state for which the reader scans, such as expired or failing, is a defect, whatever restraint the lens asks for."
|
|
92
92
|
7. **Rules of engagement.** The write allowance from the inputs. The default: Write the output file and nothing else, modify nothing in the repository, install nothing. When the ask allows more, state what it allows. Then: Publish the prototype and report its artifact URL, a value for each of the set's note labels (listed here), and five lines of distinctive ideas.
|
|
93
93
|
|
|
@@ -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.
|
|
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
|
|