@martinffx/atelier 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [1.3.0](https://github.com/martinffx/atelier/compare/v1.2.2...v1.3.0) (2026-07-17)
+
+
+### Features
+
+* **code-pull-request:** add comment and merge workflows with progressive disclosure ([53e8957](https://github.com/martinffx/atelier/commit/53e89574ae1c37d0c3e868c7bbecee560e38c573))
+* **code:** add code-pull-request skill for PR creation ([62e32a6](https://github.com/martinffx/atelier/commit/62e32a6373be02cfad5fd3cb3fa248efcf3cc06c))
+* **code:** add code-pull-request skill for PR creation ([e4d2475](https://github.com/martinffx/atelier/commit/e4d24752f610177d6706cf382f3db3c9f5406355))
+* **skills:** split oracle-grillme into oracle-grill-me and oracle-domain-modelling ([#40](https://github.com/martinffx/atelier/issues/40)) ([e373c12](https://github.com/martinffx/atelier/commit/e373c12d05d9cde3ddb02fb0fc26ee770fb959a2))
+* **spec-brainstorm:** add section-by-section design approval ([f66eb62](https://github.com/martinffx/atelier/commit/f66eb6275780768300218d329bff8882b6d20e5d))
+* **spec-brainstorm:** add section-by-section design approval ([9cfb7e7](https://github.com/martinffx/atelier/commit/9cfb7e732fe20c546c2465218a8392dcba7859ad))
+
+
+### Bug Fixes
+
+* **code-pull-request:** correct description contract and base-branch detection ([73d48c6](https://github.com/martinffx/atelier/commit/73d48c6652f14bcc5224d91e546d219816d27e03))
+* **code-pull-request:** resolve code-review findings ([fda9086](https://github.com/martinffx/atelier/commit/fda90860b99ef7ed2fd0731785af0b27251e5d1f))
+* **skills:** address review findings from skill consolidation ([cccb1f8](https://github.com/martinffx/atelier/commit/cccb1f8430de7b699900c70d1b33207d771ac664))
+
 ## [1.2.2](https://github.com/martinffx/atelier/compare/v1.2.1...v1.2.2) (2026-05-23)
 
 

package/README.md

@@ -14,13 +14,13 @@ Install Atelier with a single command. It auto-detects your AI harness (Claude C
 
 ```bash
 # Initialize atelier in your project
-bunx atelier@latest init
+bunx @martinffx/atelier@latest init
 
 # Or install everything including skills
-bunx atelier@latest init --all
+bunx @martinffx/atelier@latest init --all
 
 # Non-interactive mode (CI/CD)
-bunx atelier@latest init --yes
+bunx @martinffx/atelier@latest init --yes
 ```
 
 That's it. Your project is now configured for spec-driven development.
@@ -29,7 +29,7 @@ That's it. Your project is now configured for spec-driven development.
 
 Atelier sets up three things in your project:
 
-### 1. Skills (34 available)
+### 1. Skills (28 available)
 
 Specialized knowledge modules that auto-invoke based on context. Install them via the CLI (`--all` flag) or separately:
 
@@ -93,7 +93,7 @@ Single source of truth in `.atelier/config.json`:
 Initialize atelier in the current project.
 
 ```bash
-bunx atelier@latest init [options]
+bunx @martinffx/atelier@latest init [options]
 ```
 
 **Options:**
@@ -109,7 +109,7 @@ bunx atelier@latest init [options]
 Refresh hooks and agents from the latest templates without touching skills:
 
 ```bash
-bunx atelier@latest update
+bunx @martinffx/atelier@latest update
 ```
 
 ### `remove`
@@ -117,14 +117,14 @@ bunx atelier@latest update
 Remove all atelier-generated files from the project:
 
 ```bash
-bunx atelier@latest remove
+bunx @martinffx/atelier@latest remove
 ```
 
 Skills remain installed. Run `npx skills remove martinffx/atelier` to remove them separately.
 
 ## Skills
 
-This repository includes 34 skills that enhance AI agents with specialized knowledge and workflows.
+This repository includes 28 skills that enhance AI agents with specialized knowledge and workflows.
 
 ### Installing Skills
 
@@ -148,7 +148,7 @@ Skills fall into four categories based on what they do:
 
 Process-oriented skills that guide you through structured development workflows. These produce artifacts and should be followed step-by-step.
 
-- `spec-brainstorm` → `spec.md` — Discovery, requirements, architecture
+- `spec-brainstorm` → `design.md` — Discovery, requirements, architecture
 - `spec-plan` → `plan.json` — Break spec into implementable tasks
 - `spec-implement` — Execute tasks with TDD
 - `spec-finish` — Validate, review, prepare for PR
@@ -158,13 +158,9 @@ Process-oriented skills that guide you through structured development workflows.
 
 Analytical skills that provide patterns, principles, and deep reasoning. These adapt to your specific situation.
 
-- `oracle-architect` — DDD, hexagonal architecture, component design
-- `oracle-challenge` — Challenge assumptions, validate decisions
-- `oracle-doubt` — Adversarial review of non-trivial decisions
-- `oracle-grillme` — Socratic interrogation of plans against domain model
-- `oracle-security` — Security architecture and threat modeling
-- `oracle-testing` — Stub-driven TDD, layer boundary testing
-- `oracle-thinkdeep` — Extended sequential reasoning for complex problems
+- `oracle-debug` — Systematic debugging, root cause before fixes
+- `oracle-grill-me` — Socratic interrogation of plans against domain model
+- `oracle-domain-modelling` — Build and sharpen the project's domain model
 
 #### Domain Knowledge (`python:*`, `typescript:*`)
 
@@ -195,9 +191,8 @@ Technology-specific patterns and best practices. These are like having a senior
 Task-specific tools you invoke when you need them.
 
 - `code-commit` — Generate and validate conventional commits
-- `code-debug` — Systematic debugging workflow
-- `code-docs` — README, API docs, changelog generation
 - `code-handoff` — Compact conversation into handoff document
+- `code-pull-request` — Create, comment on, and merge GitHub pull requests or GitLab merge requests
 - `code-review` — Multi-agent code review with specialized reviewers
 - `code-subagents` — Dispatch patterns for parallel implementation
 
@@ -227,9 +222,10 @@ Skills are organized into four categories based on their role:
 
 ```mermaid
 graph LR
-    A[spec-brainstorm] -->|spec.md| B[spec-plan]
+    A[spec-brainstorm] -->|design.md| B[spec-plan]
     B -->|plan.json| C[spec-implement]
     C --> D[spec-finish]
+    D -.->|invokes| E[code-pull-request]
     
     B -.->|design flaw| A
     C -.->|missing tasks| B
@@ -238,10 +234,10 @@ graph LR
 ```
 
 **Standard flow:**
-1. **Research** - Discovery + research + architecture → `spec.md`
+1. **Research** - Discovery + research + architecture → `design.md`
 2. **Plan** - Break into tasks → `plan.json`
 3. **Implement** - Execute with TDD
-4. **Finish** - Validate and review
+4. **Finish** - Validate, review, and open the PR
 
 **Iteration is normal** - Backflows (dotted lines) are expected when:
 - Planning reveals design flaws → back to research
@@ -257,9 +253,11 @@ graph LR
 | "Write a plan" | spec-plan |
 | "Implement this" | spec-implement |
 | "Review this code" | code-review |
-| "Debug this" | code-debug |
-| "How should I test this" | oracle-testing |
-| "What's the architecture" | oracle-architect |
+| "Open a PR" | code-pull-request |
+| "Merge this PR" | code-pull-request |
+| "Read PR comments" | code-pull-request |
+| "Leave a comment on the PR" | code-pull-request |
+| "Debug this" | oracle-debug |
 
 ## Development
 

package/agents/architect.md

@@ -25,7 +25,7 @@ Before finishing, confirm you have:
 - [ ] Specified API endpoints with methods, paths, and request/response contracts
 - [ ] Listed error cases and handling strategy
 - [ ] Broken work into dependency-ordered tasks (entity → repository → service → router)
-- [ ] Written or updated the Technical Design section in `spec.md`
+- [ ] Written or updated the Technical Design section in `design.md`
 - [ ] Written or updated `plan.json` with the task breakdown
 
 ## Boundaries

package/agents/oracle.md

@@ -28,7 +28,7 @@ Before finishing, confirm you have:
 - [ ] Documented business rules, validations, and limits
 - [ ] Defined scope—what is included and what is explicitly out of scope
 - [ ] Generated 2–3 alternative approaches with trade-offs if the problem is complex
-- [ ] Written or updated the Requirements section in `spec.md`
+- [ ] Written or updated the Requirements section in `design.md`
 
 ## Boundaries
 

package/dist/atelier.js

@@ -25484,24 +25484,22 @@ var providerModels = {
     "opencode/claude-sonnet-4-6",
     "opencode/claude-sonnet-4-5",
     "opencode/claude-haiku-4-5",
+    "opencode/deepseek-v4-pro",
+    "opencode/deepseek-v4-flash",
     "opencode/qwen3.6-plus",
-    "opencode/minimax-m2.7",
-    "opencode/kimi-k2.6",
-    "opencode/glm-5.1",
+    "opencode/minimax-m3",
+    "opencode/kimi-k2.7-code",
+    "opencode/glm-5.2",
     "opencode/gemini-3.1-pro",
     "opencode/gemini-3-flash"
   ],
   "opencode-go": [
-    "opencode-go/glm-5.1",
-    "opencode-go/glm-5",
-    "opencode-go/kimi-k2.5",
-    "opencode-go/kimi-k2.6",
     "opencode-go/deepseek-v4-pro",
     "opencode-go/deepseek-v4-flash",
-    "opencode-go/minimax-m2.7",
-    "opencode-go/minimax-m2.5",
-    "opencode-go/qwen3.5-plus",
+    "opencode-go/kimi-k2.7-code",
+    "opencode-go/glm-5.2",
     "opencode-go/qwen3.6-plus",
+    "opencode-go/minimax-m3",
     "opencode-go/mimo-v2.5",
     "opencode-go/mimo-v2.5-pro"
   ],
@@ -25518,15 +25516,15 @@ var defaultModels = {
     architect: "opus"
   },
   "opencode-zen": {
-    recon: "opencode/minimax-m2.7",
-    oracle: "opencode/kimi-k2.6",
+    recon: "opencode/deepseek-v4-flash",
+    oracle: "opencode/kimi-k2.7-code",
     architect: "opencode/deepseek-v4-pro",
     build: "opencode/deepseek-v4-flash",
     plan: "opencode/deepseek-v4-pro"
   },
   "opencode-go": {
-    recon: "opencode-go/minimax-m2.7",
-    oracle: "opencode-go/kimi-k2.6",
+    recon: "opencode-go/deepseek-v4-flash",
+    oracle: "opencode-go/kimi-k2.7-code",
     architect: "opencode-go/deepseek-v4-pro",
     build: "opencode-go/deepseek-v4-flash",
     plan: "opencode-go/deepseek-v4-pro"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martinffx/atelier",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Personal development toolkit - spec-driven development, code quality, deep thinking, and ecosystem patterns",
   "type": "module",
   "bin": {

package/skills/code-commit/SKILL.md

@@ -76,20 +76,12 @@ When user asks to validate or check a commit message:
 4. Check subject follows rules (lowercase, imperative, no period)
 5. Flag any issues found
 
-### 3. Create Pull Request
+### Delegated: Pull Request Creation
 
-When user wants to open a PR or after finishing commits on a feature branch:
-
-1. Verify on a feature branch (not main): `git branch --show-current`
-2. Check for project PR template: `ls .github/PULL_REQUEST_TEMPLATE.md`
-3. Push branch if needed: `git push -u origin <branch>`
-4. Create PR via `gh pr create`:
-   - Use `--fill` if commits are clean (auto-populates title/body)
-   - Use `--draft` for work-in-progress
-   - Use interactive mode if body needs custom content
-5. Show the PR URL to the user
-
-See [references/pr-workflow.md](references/pr-workflow.md) for full workflow details.
+If the user wants to create a PR after committing, invoke the
+[code-pull-request](../code-pull-request/SKILL.md) skill. It detects the platform
+(GitHub/GitLab), finds a template, generates the body, and opens the PR via `gh`
+or `glab`.
 
 ## Input Methods
 

package/skills/code-pull-request/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: code-pull-request
+description: >
+  Manage GitHub pull requests or GitLab merge requests: create, read/leave/respond to
+  comments, and merge. Triggers on "open a PR", "make a PR", "merge this PR", "merge the
+  MR", "read PR comments", "leave a comment on the PR", "respond to a comment", "ship this",
+  or when a feature branch is ready for review.
+user-invocable: true
+---
+
+# Pull Request / Merge Request Skill
+
+Create, comment on, and merge GitHub pull requests or GitLab merge requests for the
+current branch. Assumes the relevant CLI (`gh` or `glab`) is installed and authenticated.
+
+This skill is **create/read + write-gated**. Every write action (create PR, leave
+comment, respond to comment, merge) requires explicit human confirmation before running.
+
+---
+
+## Start Here
+
+1. Detect the platform and find the current branch's open PR/MR — see
+   [references/common.md](references/common.md).
+2. Pick a workflow:
+
+| Workflow | Reference | Trigger phrases |
+|----------|-----------|------------------|
+| Create PR/MR | [create-pr.md](references/create-pr.md) | "open a PR", "make a PR", "submit for review" |
+| Read comments | [read-comments.md](references/read-comments.md) | "read PR comments", "show MR comments" |
+| Leave a comment | [leave-comment.md](references/leave-comment.md) | "leave a comment", "comment on the PR" |
+| Respond to a comment | [respond-to-comment.md](references/respond-to-comment.md) | "respond to a comment", "reply on the PR" |
+| Merge PR/MR | [merge-pr.md](references/merge-pr.md) | "merge this PR", "ship it", "merge the MR" |
+
+Both GitHub (`gh`) and GitLab (`glab`) are first-class. Every write step pauses for
+human approval before running the CLI command.

package/skills/code-pull-request/references/common.md

@@ -0,0 +1,76 @@
+# Common: Platform Detection and PR Lookup
+
+Shared steps used by every workflow. Run these first.
+
+---
+
+## Detect Platform
+
+```bash
+git remote -v
+```
+
+Scan the push URLs for the platform host — don't assume the remote is named
+`origin` (forks and multi-remote setups often use `upstream` or other names):
+
+- Contains `github.com` → use `gh` (GitHub PR)
+- Contains `gitlab` → use `glab` (GitLab MR)
+- Multiple or no matches → ask the human which remote to use.
+
+---
+
+## Determine the Base Branch
+
+```bash
+base=$(git symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
+if [ -z "$base" ]; then
+  for candidate in main master; do
+    git rev-parse --verify --quiet "origin/$candidate" >/dev/null && base=$candidate && break
+  done
+fi
+echo "$base"
+```
+
+If that's still empty, ask the human what the base branch is.
+
+---
+
+## Preflight the CLI
+
+Confirm the relevant CLI is installed and authenticated before any write:
+
+```bash
+gh auth status     # GitHub
+glab auth status   # GitLab
+```
+
+If not authenticated, stop and tell the human. Don't proceed with writes.
+
+---
+
+## Find the Open PR/MR for the Current Branch
+
+GitHub:
+
+```bash
+gh pr view --json state,number,url,headRefName
+```
+
+GitLab:
+
+```bash
+glab mr view --json state,iid,web_url,source_branch
+```
+
+- **Open** → use this PR/MR number/URL for comment and merge workflows.
+- **Closed/merged** → for merge workflow: check for new commits
+  (`git log --oneline origin/<base>..HEAD`); otherwise stop and tell the human.
+- **None** → for merge workflow: run [create-pr.md](create-pr.md), then continue.
+  For comment workflows: stop — nothing to comment on.
+
+---
+
+## Safety Guard
+
+Refuse to operate from the default branch — that's almost always a mistake. Ask the
+human to switch to a feature branch first.

package/skills/code-pull-request/references/create-pr.md

@@ -0,0 +1,122 @@
+# Workflow: Create PR/MR
+
+Create a pull request (GitHub) or merge request (GitLab) for the current branch.
+
+Start with [common.md](common.md) (platform detection, base branch, preflight).
+
+---
+
+## Step 1: Check for Existing PR/MR
+
+GitHub:
+```bash
+gh pr view --json state,number,url
+```
+
+GitLab:
+```bash
+glab mr view --json state,iid,web_url
+```
+
+- **Open** → show the URL, stop. Don't create a duplicate.
+- **Closed/merged** → check for new commits since the PR was closed:
+  ```bash
+  git log --oneline origin/<base>..HEAD
+  ```
+  New commits exist → proceed to create a new PR.
+  No new commits → tell the human, stop.
+- **None** → proceed to create.
+
+---
+
+## Step 2: Find a Template
+
+Look for the repo's PR/MR template:
+
+GitHub:
+```bash
+ls .github/PULL_REQUEST_TEMPLATE.md 2>/dev/null
+ls .github/PULL_REQUEST_TEMPLATE/*.md 2>/dev/null
+```
+
+GitLab:
+```bash
+ls .gitlab/merge_request_templates/*.md 2>/dev/null
+ls .gitlab/merge_request_template.md 2>/dev/null
+```
+
+Also check common locations:
+```bash
+ls docs/PULL_REQUEST_TEMPLATE.md 2>/dev/null
+ls PULL_REQUEST_TEMPLATE.md 2>/dev/null
+```
+
+- **Template found** → use it. The CLI will auto-apply it in interactive mode, or
+  fill each section from the commits and diff for inline mode.
+- **No template** → use the fallback template at
+  [default-template.md](default-template.md).
+
+---
+
+## Step 3: Generate Title and Body
+
+```bash
+git log --oneline origin/<base>..HEAD            # commit list
+git log origin/<base>..HEAD --format='%H %s%n%b'  # full commit messages
+git diff --stat origin/<base>...HEAD             # changed files summary
+```
+
+Derive the title from the most significant conventional commit. If commits are
+messy, synthesize from the diff:
+
+```
+<type>(<scope>): <description>
+```
+
+Fill the body (template sections or fallback) from the commits and diff:
+- **Summary** — what and why, one or two sentences
+- **Changes** — bulleted, grouped by area
+- **Testing** — how it was verified (if known)
+- **Checklist** — tests pass, conventional commits, docs updated
+- **Linked issues** — extract `Closes #N`, `Fixes #N`, `Relates to #N` from commit
+  footers
+
+---
+
+## Step 4: Create the PR
+
+Push the branch first if it isn't on the remote:
+
+```bash
+git push -u origin <branch-name>
+```
+
+**Show the human the generated title and body before creating.** Ask for confirmation,
+or proceed if they said "just do it" up front.
+
+### GitHub
+
+| Mode | Command |
+|------|---------|
+| Auto-fill | `gh pr create --fill` |
+| Inline | `gh pr create --title "<title>" --body-file -` (body via stdin) |
+| Draft | `gh pr create --draft --title "<title>" --body-file -` (body via stdin) |
+
+### GitLab
+
+| Mode | Command |
+|------|---------|
+| Auto-fill | `glab mr create --fill` |
+| Inline | `glab mr create --title "<title>" --description "$(cat <body-file>)"` |
+| Draft | `glab mr create --draft --title "<title>" --description "$(cat <body-file>)"` |
+
+Default to inline with the generated body. **Never pass a multi-line body directly
+in the command string** (`--body "<body>"`) — quotes, backticks, and `$` in
+Markdown break shell quoting. Write the body to a temp file first, then pass it
+via stdin (`gh --body-file -`) or command substitution (`glab` has no
+description-file flag). Reserve direct inline strings for one-line bodies.
+
+Use `--fill` when commits are clean and the body would be redundant. Use `--draft`
+when the human signals work in progress.
+
+After creation, show the PR/MR URL to the human. Done.

package/skills/code-pull-request/references/default-template.md

@@ -0,0 +1,25 @@
+# Default PR/MR Template
+
+Fallback body template when the repository has no `.github/PULL_REQUEST_TEMPLATE.md`
+or `.gitlab/merge_request_template.md`. Fill each section from the conventional
+commits and diff.
+
+```markdown
+## Summary
+<!-- One or two sentences: what and why -->
+
+## Changes
+<!-- Bulleted, grouped by area. Each bullet self-contained. -->
+-
+
+## Testing
+<!-- How it was verified: test commands run, manual steps, edge cases checked -->
+
+## Checklist
+- [ ] Tests pass
+- [ ] Commits follow conventional format
+- [ ] Documentation updated (if needed)
+
+## Linked Issues
+<!-- Closes #123, Fixes #456, Relates to #789 -->
+```

package/skills/code-pull-request/references/leave-comment.md

@@ -0,0 +1,53 @@
+# Workflow: Leave a Comment
+
+Post a new top-level comment on the current branch's open PR/MR.
+
+Start with [common.md](common.md) (platform detection, find the open PR/MR).
+
+---
+
+## Step 1: Find the Open PR/MR
+
+Run the lookup in [common.md](common.md#find-the-open-prmr-for-the-current-branch).
+If none is open, stop — nothing to comment on.
+
+---
+
+## Step 2: Compose the Comment
+
+Ask the human for the comment body. Accept either:
+
+- Their exact text, or
+- A draft you generate (e.g., a status update, summary, or question) that they edit.
+
+Prefer passing the body via stdin or a temp file to avoid shell-escaping issues with
+quotes, backticks, or `$` in the message:
+
+```bash
+gh pr comment <number> --body-file -
+glab mr note <iid> --message-file -   # if supported; otherwise --message
+```
+
+---
+
+## Step 3: Confirm and Post
+
+**Show the human the final comment text and target PR/MR. Ask for confirmation
+before running the write command.**
+
+### GitHub
+```bash
+gh pr comment <number> --body "<body>"
+```
+Or via stdin to avoid escaping:
+```bash
+echo "$body" | gh pr comment <number> --body-file -
+```
+
+### GitLab
+```bash
+glab mr note <iid> --message "<body>"
+```
+
+After posting, show the human the comment URL or the updated PR/MR URL. Done. Do not
+merge or make further changes unless the human asks for another workflow.

package/skills/code-pull-request/references/merge-pr.md

@@ -0,0 +1,94 @@
+# Workflow: Merge PR/MR
+
+Merge the current branch's open PR/MR after confirming CI is green.
+
+Defaults: **squash merge + delete the source branch**. If CI is pending, abort and
+report — don't block waiting unless the human says otherwise.
+
+Start with [common.md](common.md) (platform detection, base branch, preflight).
+
+---
+
+## Step 1: Find or Create the Open PR/MR
+
+Run the lookup in [common.md](common.md#find-the-open-prmr-for-the-current-branch).
+
+- **Open** → continue to Step 2.
+- **None** → run [create-pr.md](create-pr.md) first, then continue.
+- **Closed/merged** → check for new commits since it was closed
+  (`git log --oneline origin/<base>..HEAD`); stop if none.
+
+---
+
+## Step 2: Check CI Is Green
+
+### GitHub
+```bash
+gh pr checks <number>            # all checks
+gh pr checks <number> --required # the merge gate
+```
+Exit codes for `--required`: 0 = all required checks pass; non-zero includes the
+pending case (exit 8). Use `gh pr checks <number> --watch` to wait if the human
+asks for it.
+
+`--required` only shows required checks. If the full run shows failing **optional**
+checks (lint, coverage, etc.), warn the human before proceeding — don't silently
+ignore them.
+
+### GitLab
+```bash
+glab ci status
+# or
+glab pipeline status
+```
+
+If any required check is **pending**, offer auto-merge instead of a direct merge:
+`gh pr merge --auto` (GitHub) or `glab mr merge --auto-merge` (GitLab) queues the
+merge to run once checks pass. A bare `gh pr merge` fails while required checks
+are pending — "merge anyway" does not work in that state. Note: `glab mr merge`
+enables auto-merge by default while a pipeline is running.
+
+If any required check is **failing**, stop and report the status to the human.
+Don't merge on red. If the human says "merge anyway": on GitHub a forced merge
+requires `--admin` (bypasses branch protection, needs admin rights on the repo) —
+state that implication explicitly before using it. On GitLab, merging on red is
+controlled by project settings — ask the human to fix the pipeline or adjust the
+setting.
+
+---
+
+## Step 3: Confirm Before Merging
+
+**Show the human:**
+- PR/MR URL and number/iid
+- CI status (green/red)
+- Merge strategy (squash by default)
+- Whether the source branch will be deleted
+
+Ask for explicit confirmation before running the merge command.
+
+---
+
+## Step 4: Merge
+
+### GitHub
+```bash
+gh pr merge <number> --squash --delete-branch
+```
+Alternatives: `--rebase`, `--merge`, `--auto` (merge automatically once required
+checks pass), or `--admin` (forced merge — see Step 2) per the human's request.
+
+### GitLab
+```bash
+glab mr merge <iid> --squash --remove-source-branch
+```
+Alternatives: `--rebase`, or `--auto-merge` (merge once the pipeline succeeds —
+already the default while a pipeline is running) per the human's request.
+
+---
+
+## Step 5: Report
+
+Show the human the merge result — the merge commit SHA, the target branch tip, and
+whether the source branch was deleted. Suggest switching back to the base branch
+locally (`git checkout <base> && git pull`) if the source branch was removed. Done.