codeassembly-guidance 0.0.0 → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.meta/changelog.json +563 -0
- package/CHANGELOG.md +134 -0
- package/LICENSE +7 -0
- package/README.md +165 -1
- package/content/_partials/README.md +192 -0
- package/content/_partials/code-descriptions.md +4 -0
- package/content/_partials/code-style.md +7 -0
- package/content/_partials/comment-discipline.md +89 -0
- package/content/_partials/concision.md +3 -0
- package/content/_partials/diff-audit-checklist.md +9 -0
- package/content/_partials/file-access.md +4 -0
- package/content/_partials/live-repo-writes.md +13 -0
- package/content/_partials/plain-speech-calibration.md +66 -0
- package/content/_partials/plain-speech.md +13 -0
- package/content/_partials/prose-line-breaks.md +3 -0
- package/content/_partials/record-marker.md +1 -0
- package/content/_partials/reduced-object-relative.md +28 -0
- package/content/_partials/shell-commands.md +3 -0
- package/content/_partials/target-file-set-resolution.md +22 -0
- package/content/_partials/technical-recommendations.md +5 -0
- package/content/_partials/test-structure-audit-checklist.md +7 -0
- package/content/_partials/ticket-assessment-baseline.md +12 -0
- package/content/_partials/ticket-assessment.md +202 -0
- package/content/_partials/work-type-choice.md +13 -0
- package/content/codeassembly-content.yaml +49 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +16 -0
- package/content/collections/recommended.md +34 -0
- package/content/collections/triage.md +77 -0
- package/content/collections/williamthorsen.md +25 -0
- package/content/guidance/README.md +22 -0
- package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
- package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
- package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
- package/content/guidance/rulebooks/command-output-conventions.md +14 -0
- package/content/guidance/rulebooks/commit-conventions.md +72 -0
- package/content/guidance/rulebooks/generated-content-policy.md +10 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
- package/content/guidance/rulebooks/readme-conventions.md +74 -0
- package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
- package/content/guidance/rulebooks/shell-conventions.md +279 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
- package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
- package/content/guidance/shared/AGENTS.md +43 -0
- package/content/scripts/README.md +41 -0
- package/content/scripts/describe-change.mjs +165 -0
- package/content/scripts/get-ticket-id.sh +131 -0
- package/content/scripts/manage-jira-ticket.mjs +209 -0
- package/content/scripts/resolve-frontmatter.sh +540 -0
- package/content/scripts/resolve-review-run.mjs +12 -0
- package/content/scripts/select-lede-exemplars.mjs +208 -0
- package/content/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +969 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -0
- package/content/skills/_data/branch-format.md +34 -0
- package/content/skills/_data/change-record.md +163 -0
- package/content/skills/_data/complexity-classification.md +58 -0
- package/content/skills/_data/concision.md +23 -0
- package/content/skills/_data/deployed-file-provenance.md +46 -0
- package/content/skills/_data/design-priorities.md +76 -0
- package/content/skills/_data/gh-body-file.md +30 -0
- package/content/skills/_data/git-commands.md +39 -0
- package/content/skills/_data/naming-conventions.md +50 -0
- package/content/skills/_data/pr-resolution.md +25 -0
- package/content/skills/_data/pr-source-resolution.md +36 -0
- package/content/skills/_data/recommendation-gradient.md +90 -0
- package/content/skills/_data/scope-and-deferral.md +83 -0
- package/content/skills/_data/spike-conventions.md +89 -0
- package/content/skills/_data/ticket-evaluation.md +13 -0
- package/content/skills/_data/ticket-id-extraction.md +43 -0
- package/content/skills/_data/ticket-source-resolution.md +147 -0
- package/content/skills/_data/title-templates.md +624 -0
- package/content/skills/_data/title-voice.md +17 -0
- package/content/skills/_data/work-types.json +168 -0
- package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
- package/content/skills/_partials/action-items.md +22 -0
- package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
- package/content/skills/_partials/commit-title-rendering.md +14 -0
- package/content/skills/_partials/gh-body-file.md +22 -0
- package/content/skills/_partials/nested-list-indent.md +9 -0
- package/content/skills/_partials/next-steps-after-plan.md +99 -0
- package/content/skills/_partials/next-steps-after-review.md +350 -0
- package/content/skills/_partials/option-format.md +84 -0
- package/content/skills/_partials/plan-template.md +97 -0
- package/content/skills/_partials/split-launch-prompts.md +5 -0
- package/content/skills/_partials/split-ticket-compose.md +5 -0
- package/content/skills/_partials/split-ticket-create.md +3 -0
- package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
- package/content/skills/_partials/ticket-concision.md +18 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
- package/content/skills/_partials/ticket-placement.md +14 -0
- package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
- package/content/skills/_partials/ticket-skeleton.md +13 -0
- package/content/skills/add-change-record/SKILL.md +136 -0
- package/content/skills/add-test-ids/SKILL.md +51 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
- package/content/skills/anti-patterns/SKILL.md +57 -0
- package/content/skills/assess-ticket/SKILL.md +46 -0
- package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
- package/content/skills/brainstorming/SKILL.md +107 -0
- package/content/skills/capture-event/SKILL.md +108 -0
- package/content/skills/capture-event/capture-event.mjs +216 -0
- package/content/skills/capture-feedback/SKILL.md +71 -0
- package/content/skills/capture-lede-decision/SKILL.md +163 -0
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
- package/content/skills/classify-complexity/SKILL.md +92 -0
- package/content/skills/collaborate/SKILL.md +86 -0
- package/content/skills/condense-branch/SKILL.md +83 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
- package/content/skills/create-commit/SKILL.md +65 -0
- package/content/skills/create-devlog/SKILL.md +108 -0
- package/content/skills/create-gh-pr/SKILL.md +106 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +350 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
- package/content/skills/design-and-plan/SKILL.md +194 -0
- package/content/skills/development-workflows/SKILL.md +41 -0
- package/content/skills/get-ticket-id/SKILL.md +67 -0
- package/content/skills/groom-backlog/SKILL.md +245 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
- package/content/skills/implement-plan/SKILL.md +164 -0
- package/content/skills/index-prototypes/SKILL.md +145 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
- package/content/skills/kb-add/SKILL.md +156 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +117 -0
- package/content/skills/kb-curate/kb-curate.mjs +213 -0
- package/content/skills/kb-edit/SKILL.md +128 -0
- package/content/skills/kb-edit/kb-edit.mjs +219 -0
- package/content/skills/kb-retrieve/SKILL.md +100 -0
- package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
- package/content/skills/kb-update-events/SKILL.md +77 -0
- package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
- package/content/skills/merge-bb-pr/SKILL.md +136 -0
- package/content/skills/merge-gh-pr/SKILL.md +167 -0
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
- package/content/skills/merge-pr/SKILL.md +368 -0
- package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
- package/content/skills/people-report/SKILL.md +208 -0
- package/content/skills/plan/SKILL.md +87 -0
- package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
- package/content/skills/refine-plan/SKILL.md +259 -0
- package/content/skills/respond-to-review/SKILL.md +292 -0
- package/content/skills/review-bb-pr/SKILL.md +161 -0
- package/content/skills/review-branch/SKILL.md +301 -0
- package/content/skills/review-criteria/SKILL.md +108 -0
- package/content/skills/review-gh-pr/SKILL.md +155 -0
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
- package/content/skills/review-permissions/SKILL.md +39 -0
- package/content/skills/review-pr/SKILL.md +123 -0
- package/content/skills/revise-comments/SKILL.md +115 -0
- package/content/skills/revise-prose/SKILL.md +197 -0
- package/content/skills/revise-prose/revise-prose.mjs +229 -0
- package/content/skills/save-artifact/SKILL.md +69 -0
- package/content/skills/save-plan/SKILL.md +55 -0
- package/content/skills/software-engineering/SKILL.md +74 -0
- package/content/skills/streamline-guidance/SKILL.md +174 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
- package/content/skills/summarize-change/SKILL.md +308 -0
- package/content/skills/summarize-chat/SKILL.md +100 -0
- package/content/skills/systematic-debugging/SKILL.md +308 -0
- package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
- package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
- package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
- package/content/skills/systematic-debugging/find-polluter.sh +68 -0
- package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
- package/content/skills/systematic-debugging/test-academic.md +16 -0
- package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
- package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
- package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
- package/content/skills/testing-conventions/SKILL.md +168 -0
- package/content/skills/testing-conventions/mistakes.md +1 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
- package/content/skills/update-jira-ticket/SKILL.md +245 -0
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
- package/content/skills/update-project-guidance/SKILL.md +300 -0
- package/content/skills/upgrade-dependencies/SKILL.md +139 -0
- package/content/skills/wrap-up/SKILL.md +431 -0
- package/content/subagents/_data/claude.yaml +19 -0
- package/content/subagents/_data/rovo.yaml +31 -0
- package/content/subagents/canary.md +11 -0
- package/content/subagents/entry-drafter.md +187 -0
- package/content/subagents/handoff-reviewer.md +75 -0
- package/content/subagents/plan-reviewer.md +184 -0
- package/content/subagents/plan-reviser.md +88 -0
- package/content/subagents/prose-reviser.md +130 -0
- package/content/subagents/ticket-assessor.md +139 -0
- package/package.json +70 -2
- package/schemas/preferences.v1.json +294 -0
- package/schemas/work-types.v1.json +142 -0
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: merge-bb-pr
|
|
3
|
+
description: Merge a Bitbucket pull request using the delegate interface from merge-pr
|
|
4
|
+
user-invocable: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Merge Bitbucket pull request
|
|
8
|
+
|
|
9
|
+
Internal delegate that merges a pull request on Bitbucket. Called by `merge-pr` with fully-resolved inputs: This skill does not resolve scope, type, strategy, or body; it only validates platform state and executes the merge.
|
|
10
|
+
|
|
11
|
+
## Delegate interface
|
|
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
|
+
| `ticket_id` | string | Ticket ID for artifact path resolution |
|
|
21
|
+
| `project_slug` | string | Project slug for artifact path resolution |
|
|
22
|
+
| `artifact_base_dir` | string | Base directory for artifact storage |
|
|
23
|
+
|
|
24
|
+
## Bitbucket access
|
|
25
|
+
|
|
26
|
+
Every Bitbucket call below goes through the tool named in [Bitbucket pull-request access](../_data/bitbucket-pr-access.md). Coordinates come from that document's cascade: the PR URL when `merge-pr` resolved one, and the git remote when it was handed a bare `--pr {n}` instead.
|
|
27
|
+
|
|
28
|
+
## Process
|
|
29
|
+
|
|
30
|
+
### 1. Refuse an unmappable deletion strategy
|
|
31
|
+
|
|
32
|
+
`deletion_strategy: both` does not have a Bitbucket counterpart. `closeSourceBranch` controls the remote side alone, and nothing in the tool's surface deletes a local branch. Refuse before any other step, so that nothing is published:
|
|
33
|
+
|
|
34
|
+
<!-- include: ../_partials/bitbucket-delete-both-refusal.md / -->
|
|
35
|
+
|
|
36
|
+
`remote` and `none` map to `closeSourceBranch` in step 4.
|
|
37
|
+
|
|
38
|
+
### 2. Fetch and validate PR state
|
|
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`.
|
|
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."
|
|
43
|
+
|
|
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
|
+
|
|
46
|
+
### 3. Verify branch sync
|
|
47
|
+
|
|
48
|
+
The check only makes sense when the local working copy has the branch being merged checked out. Otherwise it is unrelated to what is being merged, and the comparison would produce a spurious refusal.
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
git rev-parse --abbrev-ref HEAD
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Skip the check when **either** holds:
|
|
55
|
+
|
|
56
|
+
- The printed branch does not equal `source.branch.name`.
|
|
57
|
+
- `source.repository.full_name` does not equal the resolved `{workspace}/{repo}` pair, which makes this a fork PR. `origin/{source.branch.name}` then names a branch in the base repository, and a fork PR whose source branch happens to share that name would be compared against an unrelated ref.
|
|
58
|
+
|
|
59
|
+
Both conditions match `merge-gh-pr`'s, whose second keys on `isCrossRepository`. Otherwise:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
git fetch origin
|
|
63
|
+
git rev-list --left-right --count "origin/{source.branch.name}...HEAD"
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
If the counts differ from `0\t0`, refuse: "Local branch is out of sync with `origin/{source.branch.name}` (ahead {a}, behind {b}); push or pull before merging."
|
|
67
|
+
|
|
68
|
+
### 4. Execute the merge
|
|
69
|
+
|
|
70
|
+
Map `strategy` per [Merging a pull request](../_data/bitbucket-pr-access.md#merging-a-pull-request): `squash` to `squash`, `merge` to `merge_commit`, and `rebase` to `rebase_fast_forward`. Do not pre-check the repository's enabled strategies; the tool does not expose such a list, and for a disabled strategy the platform returns its own error naming it.
|
|
71
|
+
|
|
72
|
+
Compose `message` as `title`, a blank line, then `body`, for `squash` and `merge_commit`. Omit `message` for `rebase_fast_forward`: Rebased commits keep their own messages, so a composed merge message has nothing to attach to. This matches `merge-gh-pr`'s handling of `--rebase`.
|
|
73
|
+
|
|
74
|
+
Passing a composed title for `merge_commit` diverges from `merge-gh-pr`, which omits `--subject` and lets GitHub compose its own subject. Because Bitbucket's single `message` field covers title and body together, a caller cannot supply the body and leave the subject to the platform.
|
|
75
|
+
|
|
76
|
+
Set `closeSourceBranch` to `true` for `deletion_strategy: remote` and `false` for `none`.
|
|
77
|
+
|
|
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.
|
|
79
|
+
|
|
80
|
+
### 5. Capture the merge result
|
|
81
|
+
|
|
82
|
+
When the `action: "merge"` response contains `state`, `merge_commit.hash`, `links.html.href`, and `updated_on`, read them from it. When any is absent, issue an `action: "get"` call to obtain them. The hash must come from a response that reports `state: "MERGED"`.
|
|
83
|
+
|
|
84
|
+
`updated_on` after a successful merge is the time at which the PR was merged, and it stands in for GitHub's `mergedAt`.
|
|
85
|
+
|
|
86
|
+
Success in step 4 means that the PR was merged, so a `merge_commit.hash` absent from both the merge response and the fallback read is an anomaly rather than evidence that the merge did not happen. Report it as such: When `state` is `MERGED` and the hash is absent, say the merge succeeded and the hash is unavailable, and write `unavailable` into the artifact's `Merge commit:` line. Never report an absent hash as a merge that did not happen. `merge-pr` reads this report for whether a merge happened, so if this report treated an absent hash as a merge that did not happen, `merge-pr` would report a completed merge as one that did not happen.
|
|
87
|
+
|
|
88
|
+
### 6. Save merge artifact
|
|
89
|
+
|
|
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
|
+
|
|
92
|
+
Ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
|
|
93
|
+
|
|
94
|
+
`mkdir -p` the target directory before writing.
|
|
95
|
+
|
|
96
|
+
Filename format:
|
|
97
|
+
|
|
98
|
+
```
|
|
99
|
+
{timestamp}_{slug}_merge.md
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Use `YYYYMMDD-HHMMSSZ` for `{timestamp}` (UTC).
|
|
103
|
+
|
|
104
|
+
Follow [artifact conventions](../_data/artifact-conventions.md).
|
|
105
|
+
|
|
106
|
+
When the lede is needed and the artifact does not contain it, `capture-lede-decision` takes `--merged-lede-file`; the artifact is not edited to supply it.
|
|
107
|
+
|
|
108
|
+
Artifact content:
|
|
109
|
+
|
|
110
|
+
```markdown
|
|
111
|
+
<!-- include: ../../_partials/record-marker.md / -->
|
|
112
|
+
|
|
113
|
+
# {title}
|
|
114
|
+
|
|
115
|
+
PR: {links.html.href}
|
|
116
|
+
Merged at: {updated_on}
|
|
117
|
+
Merge commit: {merge_commit.hash}
|
|
118
|
+
Strategy: {strategy}
|
|
119
|
+
Branch: {source.branch.name}
|
|
120
|
+
|
|
121
|
+
## Body
|
|
122
|
+
|
|
123
|
+
{body as submitted, not as the pull request later reads}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
## Completion
|
|
127
|
+
|
|
128
|
+
```
|
|
129
|
+
Merged: {links.html.href}
|
|
130
|
+
Commit: {merge_commit.hash}
|
|
131
|
+
Strategy: {strategy}
|
|
132
|
+
Branch: {source.branch.name}
|
|
133
|
+
Artifact saved: {artifact path}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
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.
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: merge-gh-pr
|
|
3
|
+
description: Merge a GitHub pull request using the delegate interface from merge-pr
|
|
4
|
+
user-invocable: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Merge GitHub pull request
|
|
8
|
+
|
|
9
|
+
Internal delegate that merges a pull request on GitHub. Called by `merge-pr` with fully-resolved inputs: This skill does not resolve scope, type, strategy, or body; it only validates platform state and executes the merge.
|
|
10
|
+
|
|
11
|
+
## Delegate interface
|
|
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
|
+
| `ticket_id` | string | Ticket ID for artifact path resolution |
|
|
21
|
+
| `project_slug` | string | Project slug for artifact path resolution |
|
|
22
|
+
| `artifact_base_dir` | string | Base directory for artifact storage |
|
|
23
|
+
|
|
24
|
+
## Process
|
|
25
|
+
|
|
26
|
+
### 1. Fetch PR state
|
|
27
|
+
|
|
28
|
+
Use a single `gh pr view` call to fetch every field needed for validation:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
gh pr view {pr_number} --json state,isDraft,mergeable,mergeStateStatus,reviewDecision,headRefName,isCrossRepository,baseRefName
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Parse the JSON with a real parser (`python3 -c "import sys,json; ..."` or `jq`). Do not regex-extract.
|
|
35
|
+
|
|
36
|
+
### 2. Run pre-merge checks
|
|
37
|
+
|
|
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:
|
|
39
|
+
|
|
40
|
+
| Field | Failure condition | Refusal reason |
|
|
41
|
+
| ------------------ | ------------------------------------------------------------ | --------------------------------------------------------------------------- |
|
|
42
|
+
| `state` | not `"OPEN"` | "PR #{n} is {state} (not OPEN); cannot merge." |
|
|
43
|
+
| `isDraft` | `true` | "PR #{n} is in draft state; mark it ready first." |
|
|
44
|
+
| `mergeable` | `"CONFLICTING"` | "PR #{n} has merge conflicts; resolve and retry." |
|
|
45
|
+
| `mergeStateStatus` | `"BLOCKED"` | "PR #{n} is blocked (failing required checks or missing required reviews)." |
|
|
46
|
+
| `reviewDecision` | `"CHANGES_REQUESTED"` or `"REVIEW_REQUIRED"` (when required) | "PR #{n} has unresolved review requirements." |
|
|
47
|
+
|
|
48
|
+
**Failure-mode policy:** When a required field is missing or null in the JSON response (older `gh` versions, repository configurations that don't expose the field), **fail closed**: Refuse with "Cannot determine merge state for PR #{n}; verify and merge manually." Never proceed when state is inconclusive.
|
|
49
|
+
|
|
50
|
+
### 3. Verify branch sync
|
|
51
|
+
|
|
52
|
+
The branch-sync check only makes sense when the **local current branch is the PR's head branch**. Otherwise (the user invoked with `--pr {n}` for a different branch, or the PR is from a fork) the local working copy is unrelated to what's being merged, and the comparison would produce a spurious refusal.
|
|
53
|
+
|
|
54
|
+
Detect the case before running the check:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
git rev-parse --abbrev-ref HEAD
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Skip the sync check entirely when **either** of these is true:
|
|
61
|
+
|
|
62
|
+
- `isCrossRepository` is `true` (PR is from a fork: `gh pr view --json isCrossRepository` returns `true` when the head repo differs from the base repo).
|
|
63
|
+
- The printed branch does not equal `headRefName`.
|
|
64
|
+
|
|
65
|
+
When neither skip condition applies, run the sync check:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
git fetch origin
|
|
69
|
+
git rev-list --left-right --count "origin/{headRefName}...HEAD"
|
|
70
|
+
```
|
|
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."
|
|
73
|
+
|
|
74
|
+
### 4. Write the title and body to scratch files
|
|
75
|
+
|
|
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
|
+
|
|
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.
|
|
79
|
+
|
|
80
|
+
### 5. Merge and delete the branch
|
|
81
|
+
|
|
82
|
+
Run the bundled helper as one command. It merges the PR, confirms that the PR is `MERGED`, and deletes the head branch as `deletion_strategy` requests:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
node {harness_home_dir}/skills/merge-gh-pr/merge-gh-pr.mjs --pr {pr_number} --strategy {strategy} --delete {deletion_strategy} --title-file {absolute title path} --body-file {absolute body path}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
- Pass `--title-file` only when `strategy` is `squash`: GitHub composes its own subject for `merge` and `rebase`.
|
|
89
|
+
- Pass `--body-file` only when `strategy` is `squash` or `merge`: Rebased commits keep their own messages, so the composed body has nothing to attach to.
|
|
90
|
+
- Pass each path as the literal absolute path, unquoted, without a shell variable or a guard. The helper refuses a missing or empty file itself, and a guard or a shell composition around the command makes the harness ask for permission again.
|
|
91
|
+
|
|
92
|
+
The helper calls `gh` directly, never through a shell. It passes `--delete-branch` to `gh pr merge` when `deletion_strategy` is `both`. When it is `remote`, the helper deletes the PR's head ref on the head repository, which is the contributor's fork for a cross-repo PR, and only after `gh` reports the PR as `MERGED`.
|
|
93
|
+
|
|
94
|
+
On success, the helper exits 0 and prints JSON on stdout:
|
|
95
|
+
|
|
96
|
+
```json
|
|
97
|
+
{
|
|
98
|
+
"branchDeletion": "deleted",
|
|
99
|
+
"headRefName": "feature/cache",
|
|
100
|
+
"mergeCommit": { "oid": "abc123" },
|
|
101
|
+
"mergedAt": "2026-09-28T22:00:00Z",
|
|
102
|
+
"url": "https://github.com/acme/widgets/pull/42"
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
`branchDeletion` is one of these values:
|
|
107
|
+
|
|
108
|
+
- `deleted`: The helper deleted the branch.
|
|
109
|
+
- `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.
|
|
111
|
+
- `by-gh`: The deletion strategy was `both`, and `gh pr merge --delete-branch` handled the deletion.
|
|
112
|
+
- `not-requested`: The deletion strategy was `none`.
|
|
113
|
+
|
|
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`.
|
|
115
|
+
|
|
116
|
+
### 6. Save merge artifact
|
|
117
|
+
|
|
118
|
+
Save a `merge` artifact in the ticket directory.
|
|
119
|
+
|
|
120
|
+
Ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
|
|
121
|
+
|
|
122
|
+
`mkdir -p` the target directory before writing.
|
|
123
|
+
|
|
124
|
+
Filename format:
|
|
125
|
+
|
|
126
|
+
```
|
|
127
|
+
{timestamp}_{slug}_merge.md
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Use `YYYYMMDD-HHMMSSZ` for `{timestamp}` (UTC).
|
|
131
|
+
|
|
132
|
+
Follow [artifact conventions](../_data/artifact-conventions.md).
|
|
133
|
+
|
|
134
|
+
When the lede is needed and the artifact does not contain it, `capture-lede-decision` takes `--merged-lede-file`; the artifact is not edited to supply it.
|
|
135
|
+
|
|
136
|
+
Artifact content:
|
|
137
|
+
|
|
138
|
+
```markdown
|
|
139
|
+
<!-- include: ../../_partials/record-marker.md / -->
|
|
140
|
+
|
|
141
|
+
# {title}
|
|
142
|
+
|
|
143
|
+
PR: {url}
|
|
144
|
+
Merged at: {mergedAt}
|
|
145
|
+
Merge commit: {mergeCommit.oid}
|
|
146
|
+
Strategy: {strategy}
|
|
147
|
+
Branch: {headRefName}
|
|
148
|
+
|
|
149
|
+
## Body
|
|
150
|
+
|
|
151
|
+
{body as submitted, not as the pull request later reads}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
## Completion
|
|
155
|
+
|
|
156
|
+
```
|
|
157
|
+
Merged: {url}
|
|
158
|
+
Commit: {mergeCommit.oid}
|
|
159
|
+
Strategy: {strategy}
|
|
160
|
+
Branch: {headRefName}
|
|
161
|
+
Branch deletion: {branchDeletion}
|
|
162
|
+
Artifact saved: {artifact path}
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
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
|
+
|
|
167
|
+
<!-- include: ../_partials/gh-body-file.md / -->
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { createRequire as __cjsCreateRequire } from 'node:module';
|
|
2
|
+
const require = __cjsCreateRequire(import.meta.url);
|
|
3
|
+
var k=Object.defineProperty;var o=(e,t)=>k(e,"name",{value:t,configurable:!0});import{execFile as A}from"node:child_process";import{readFileSync as D,realpathSync as x,statSync as T}from"node:fs";import d from"node:process";import{fileURLToPath as v}from"node:url";import{promisify as O}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");function p(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=F(s,t);if(a===null)throw new Error(`unknown flag: ${s}`);let{spec:l,inlineValue:f}=a;if(!l.takesValue){if(f!==null)throw new Error(`--${l.name} does not take a value`);n.push({name:l.name,value:null});continue}if(f!==null){n.push({name:l.name,value:f});continue}let c=e[i+1]??null;if(c===null||c.startsWith("--"))throw new Error(`--${l.name} requires a value`);n.push({name:l.name,value:c}),i+=1}return{positionals:r,flags:n}}o(p,"scanFlags");function y(e){let t={};for(let{name:r,value:n}of e)n!==null&&(t[r]=n);return t}o(y,"valueFlagMap");function F(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(F,"matchFlag");function M(e,t){return b(e)&&e.code===t}o(M,"isErrorCode");function h(e){return M(e,"ENOENT")}o(h,"isEnoent");function u(e){return b(e)&&!Array.isArray(e)}o(u,"isRecord");function b(e){return typeof e=="object"&&e!==null}o(b,"isObject");var $="state,mergeCommit,url,mergedAt,headRefName,headRepository,headRepositoryOwner";async function R(e,t){let r=await t(P(e));if(r.exitCode!==0)return{ok:!1,exitCode:r.exitCode,stderr:r.stderr};let n=await t(["pr","view",String(e.prNumber),"--json",$]);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.
|
|
4
|
+
${n.stderr}`};let i=V(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.
|
|
5
|
+
`};if(i.kind==="not-merged")return{ok:!1,exitCode:1,stderr:`PR #${e.prNumber} is ${i.state} after merge; branch not deleted.
|
|
6
|
+
`};let s=[];return{ok:!0,result:{branchDeletion:await C(e.deletionStrategy,i,t,s),headRefName:i.headRefName,mergeCommit:{oid:i.oid},mergedAt:i.mergedAt,url:i.url},warnings:s}}o(R,"mergePullRequest");function P(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(P,"buildMergeArgs");async function C(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(C,"deleteHeadBranch");function V(e){let t;try{t=JSON.parse(e)}catch{return{kind:"unreadable"}}if(!u(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=u(n)?n.oid:void 0;return typeof r!="string"||typeof i!="string"||typeof a!="string"||typeof s!="string"?{kind:"unreadable"}:{kind:"merged",headOwner:w(t.headRepositoryOwner,"login"),headRefName:r,headRepo:w(t.headRepository,"name"),mergedAt:i,oid:a,url:s}}o(V,"parseMergedView");function w(e,t){if(!u(e))return;let r=e[t];return typeof r=="string"&&r.length>0?r:void 0}o(w,"readNamedField");var G=O(A),j=[{name:"body-file",takesValue:!0},{name:"delete",takesValue:!0},{name:"pr",takesValue:!0},{name:"strategy",takesValue:!0},{name:"title-file",takesValue:!0}],q=["both","none","remote"],I=["merge","rebase","squash"];async function B(){try{let e=W(U(d.argv.slice(2))),t=await R(e,H);t.ok||(d.stderr.write(t.stderr),d.exit(t.exitCode));for(let r of t.warnings)d.stderr.write(`${r}
|
|
7
|
+
`);d.stdout.write(`${JSON.stringify(t.result,null,2)}
|
|
8
|
+
`)}catch(e){d.stderr.write(`merge-gh-pr: ${g(e)}
|
|
9
|
+
`),d.exit(1)}}o(B,"main");L()&&await B();function L(){let e=d.argv[1];if(e===void 0)return!1;try{return x(v(import.meta.url))===x(e)}catch(t){return d.stderr.write(`merge-gh-pr: warning: could not determine entry point: ${g(t)}
|
|
10
|
+
`),!1}}o(L,"isEntryPoint");function N(e){try{let t=T(e);return t.isFile()&&t.size>0}catch{return!1}}o(N,"isNonEmptyFile");function U(e){let{flags:t,positionals:r}=p(e,j);if(r.length>0)throw new Error(`unexpected argument: ${r.join(" ")}`);let n=y(t),i=S(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:E(n,"delete",q),prNumber:Number(i),strategy:E(n,"strategy",I),titleFile:n["title-file"]}}o(U,"parseArgs");function W(e){let t=e.strategy!=="rebase",r=e.strategy==="squash",n;if(r&&(n=_(e.titleFile)),t){if(e.bodyFile===void 0)throw new Error(`--body-file is required for --strategy ${e.strategy}`);if(!N(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(W,"readRequest");function _(e){if(e===void 0)throw new Error("--title-file is required for --strategy squash");if(!N(e))throw new Error(`Title file missing or empty: ${e}`);let t=D(e,"utf8").replace(/\r?\n$/,"");if(t.length===0)throw new Error(`Title file missing or empty: ${e}`);return t}o(_,"readTitle");function E(e,t,r){let n=S(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(E,"requireMember");function S(e,t){let r=e[t];if(r===void 0)throw new Error(`--${t} is required`);return r}o(S,"requireValue");async function H(e){try{let{stderr:t,stdout:r}=await G("gh",e,{maxBuffer:16777216});return{exitCode:0,stderr:t,stdout:r}}catch(t){if(h(t))throw new Error("gh is not installed or not on PATH",{cause:t});if(u(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(H,"runGh");
|