codebyplan 1.5.1 → 1.8.0

package/templates/skills/cbp-git-worktree-create/SKILL.md

@@ -0,0 +1,226 @@
+---
+scope: org-shared
+name: cbp-git-worktree-create
+description: Create git worktree with clean command setup and register in CodeByPlan
+argument-hint: <branch-name> e.g. codebyplan-app
+effort: low
+---
+
+# Git Worktree Create
+
+Create a git worktree as a sibling folder and register it in CodeByPlan. The worktree gets its own full copy of `.claude/` files on disk (rules, skills, hooks, agents, context) — git deduplicates at the object level so there's no real cost.
+
+## Arguments
+
+`$ARGUMENTS`: branch name — becomes both the branch name and the folder name.
+
+Examples:
+- `codebyplan-app` → folder `../codebyplan-app/`, branch `codebyplan-app`
+- `codebyplan-package` → folder `../codebyplan-package/`, branch `codebyplan-package`
+
+## Prerequisites
+
+- Must run from the **main repo** (the non-worktree checkout)
+- Working tree should be clean
+- Branch should not already exist as a worktree
+
+## Instructions
+
+### Step 1: Verify Main Repo
+
+```bash
+MAIN_REPO="$(git rev-parse --show-toplevel)"
+```
+
+Verify this is the main repo (not itself a worktree):
+
+```bash
+git rev-parse --git-dir
+```
+
+If the result is a file (not `.git` directory), this is already a worktree. Stop:
+
+```
+## Error
+
+Run this command from the main repo, not from a worktree.
+Main repo: [path from git-common-dir parent]
+```
+
+### Step 2: Validate Arguments
+
+If `$ARGUMENTS` is empty, ask the user:
+
+```
+What should the worktree be called? (e.g. codebyplan-app)
+```
+
+Set:
+- `BRANCH_NAME` = `$ARGUMENTS`
+- `WORKTREE_PATH` = `$MAIN_REPO/../$BRANCH_NAME`
+
+### Step 3: Check for Conflicts
+
+Check if the worktree already exists:
+
+```bash
+git worktree list | grep "$BRANCH_NAME"
+```
+
+If it exists:
+```
+## Worktree Already Exists
+
+Branch `[name]` is already checked out at [path].
+
+Use `/cbp-git-worktree-remove [name]` to remove it first.
+```
+Stop here.
+
+Check if the folder already exists:
+
+```bash
+ls -d "$WORKTREE_PATH" 2>/dev/null
+```
+
+If it exists, stop and inform the user.
+
+### Step 4: Create Branch If Needed
+
+Check if branch exists:
+
+```bash
+git branch --list "$BRANCH_NAME"
+```
+
+If branch does NOT exist, create it from current HEAD:
+
+```bash
+git branch "$BRANCH_NAME"
+```
+
+### Step 5: Create Worktree
+
+```bash
+git worktree add "$WORKTREE_PATH" "$BRANCH_NAME"
+```
+
+### Step 6: Set Up MCP Connection
+
+Copy `.mcp.json` from the main repo to the worktree. The config points at the remote MCP endpoint (`https://codebyplan.com/mcp`) and reads the API key from the environment, so no path rewriting is needed:
+
+```bash
+cp "$MAIN_REPO/.mcp.json" "$WORKTREE_PATH/.mcp.json"
+```
+
+Expected shape (do NOT rewrite paths — this is remote HTTP):
+
+```json
+{
+  "mcpServers": {
+    "codebyplan": {
+      "url": "https://codebyplan.com/mcp",
+      "headers": {
+        "x-api-key": "${CODEBYPLAN_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+### Step 7: Set Up Environment
+
+Copy `.env.local` from the main repo to the worktree (contains `CODEBYPLAN_API_KEY` and any other local env):
+
+```bash
+cp "$MAIN_REPO/.env.local" "$WORKTREE_PATH/.env.local"
+```
+
+Verify `.env.local` is already in `.gitignore` (it should be via `.env.local` pattern). If not, add it.
+
+### Step 8: Push Branch
+
+```bash
+cd "$WORKTREE_PATH" && git push -u origin "$BRANCH_NAME"
+```
+
+### Step 9: Register Worktree in CodeByPlan
+
+Get the repo ID from CLAUDE.md (`Repo ID` in Key References table).
+
+Use MCP `create_worktree` to register the worktree in the CodeByPlan database:
+
+```
+MCP create_worktree:
+  repo_id: [repo-id from CLAUDE.md]
+  name: $BRANCH_NAME
+  path: $WORKTREE_PATH
+  status: "active"
+```
+
+Save the returned `worktree_id` for reference.
+
+### Step 10: Write `.codebyplan/` directory
+
+Create the `.codebyplan/` directory in the worktree root and write per-concern config stubs:
+
+```bash
+mkdir -p "$WORKTREE_PATH/.codebyplan"
+```
+
+Write `.codebyplan/repo.json` with the correct `repo_id`:
+
+```json
+{
+  "repo_id": "[repo-id from CLAUDE.md]"
+}
+```
+
+Write stubs for the other per-concern files (populated by `npx codebyplan sync` on first run):
+
+```bash
+# .codebyplan/server.json — server port and type config
+echo '{}' > "$WORKTREE_PATH/.codebyplan/server.json"
+
+# .codebyplan/git.json — branch config
+echo '{}' > "$WORKTREE_PATH/.codebyplan/git.json"
+
+# .codebyplan/shipment.json — surface shipment config
+echo '{}' > "$WORKTREE_PATH/.codebyplan/shipment.json"
+
+# .codebyplan/vendor.json — vendor docs path
+echo '{}' > "$WORKTREE_PATH/.codebyplan/vendor.json"
+```
+
+The `.codebyplan/device.local.json` file is created by `npx codebyplan setup` on the device (gitignored). The `worktree_id` is never persisted in any of these files — it is resolved at runtime via `npx codebyplan resolve-worktree` based on the device_id, filesystem path, and current git branch.
+
+No need to mark as `skip-worktree` — the committed files are merge-safe per CHK-108 and CHK-120.
+
+### Step 11: Show Result
+
+```
+## Worktree Created
+
+**Branch**: [branch-name]
+**Path**: [worktree-path]
+**Main repo**: [main-repo-path]
+**CodeByPlan**: Registered (worktree ID: [id])
+
+### Setup
+- MCP: connected (remote endpoint)
+- API key: copied from main repo `.env.local`
+- `.claude/` files: full copy on disk (rules, skills, hooks, agents, context)
+
+### Next Steps
+- Open `[worktree-path]` in your editor
+- Run `/cbp-session-start` to begin working
+- Checkpoints can be assigned to this worktree via `worktree_id`
+
+### Existing Worktrees
+[output of git worktree list]
+```
+
+## Integration
+
+- **Related**: `/cbp-git-worktree-remove` (cleanup and deregister)
+- **MCP tools**: `create_worktree`

package/templates/skills/cbp-git-worktree-remove/SKILL.md

@@ -0,0 +1,145 @@
+---
+scope: org-shared
+name: cbp-git-worktree-remove
+description: Remove git worktree and deregister from CodeByPlan
+argument-hint: <name> e.g. codebyplan-app
+effort: low
+---
+
+# Git Worktree Remove
+
+Remove a git worktree folder, deregister it from CodeByPlan, and optionally delete its branch.
+
+## Arguments
+
+`$ARGUMENTS`: worktree name or path to remove.
+
+## Prerequisites
+
+- Must run from the **main repo** (not from the worktree being removed)
+
+## Instructions
+
+### Step 1: Verify Main Repo
+
+```bash
+MAIN_REPO="$(git rev-parse --show-toplevel)"
+```
+
+Verify not in a worktree (`.git` should be a directory, not a file).
+
+### Step 2: List Worktrees
+
+```bash
+git worktree list
+```
+
+If `$ARGUMENTS` is empty, show the list and ask which to remove.
+
+### Step 3: Resolve Worktree
+
+Find matching worktree from the list. Match by:
+1. Exact path
+2. Folder name (e.g. `codebyplan-app`)
+3. Branch name
+
+If no match found, show available worktrees and stop.
+
+Set:
+- `WORKTREE_PATH` = resolved path
+- `BRANCH_NAME` = branch checked out in that worktree
+
+### Step 4: Look Up Worktree in CodeByPlan
+
+Get the repo ID from CLAUDE.md (`Repo ID` in Key References table).
+
+Use MCP `get_worktrees` to find the worktree record:
+
+```
+MCP get_worktrees:
+  repo_id: [repo-id from CLAUDE.md]
+  status: "active"
+```
+
+Match by `name` = `$BRANCH_NAME` or `path` = `$WORKTREE_PATH`.
+
+Set `WORKTREE_ID` = matched worktree's `id`.
+
+If not found in CodeByPlan, note it and continue with local removal.
+
+### Step 5: Check for Assigned Checkpoints
+
+If `WORKTREE_ID` was found, warn if any checkpoints are assigned to this worktree:
+
+```
+⚠ This worktree has [N] checkpoint(s) assigned. They will become unassigned.
+```
+
+### Step 6: Confirm with User
+
+```
+## Remove Worktree
+
+**Path**: [worktree-path]
+**Branch**: [branch-name]
+**CodeByPlan**: [registered | not registered]
+
+Remove worktree and delete the branch? (The main repo is not affected)
+```
+
+Ask:
+1. Remove worktree only (keep branch)
+2. Remove worktree and delete branch
+3. Cancel
+
+### Step 7: Deregister from CodeByPlan
+
+If `WORKTREE_ID` was found, delete the worktree record:
+
+```
+MCP delete_worktree:
+  worktree_id: [worktree-id]
+```
+
+### Step 8: Remove Git Worktree
+
+```bash
+git worktree remove "$WORKTREE_PATH"
+```
+
+If force needed (uncommitted changes):
+```bash
+git worktree remove --force "$WORKTREE_PATH"
+```
+
+Only use `--force` if the user confirms.
+
+### Step 9: Delete Branch (if requested)
+
+**Protected branch check:** If `$BRANCH_NAME` is `main`, `development`, or `preview` — refuse deletion and stop.
+
+**Checkpoint verification:** Before deleting a feat branch, verify that the associated checkpoint has completed via `/cbp-checkpoint-end`. If the checkpoint is still active, warn the user that unshipped work may be lost.
+
+```bash
+git branch -d "$BRANCH_NAME" && git push origin --delete "$BRANCH_NAME"
+```
+
+Use `-d` (not `-D`) to prevent deleting unmerged work. If it fails because the branch is not fully merged, inform the user and ask if they want to force delete with `-D`.
+
+### Step 10: Show Result
+
+```
+## Worktree Removed
+
+**Removed**: [worktree-path]
+**Branch**: [deleted | kept]
+**CodeByPlan**: [deregistered | was not registered]
+
+### Remaining Worktrees
+[output of git worktree list]
+```
+
+## Integration
+
+- **Related**: `/cbp-git-worktree-create` (create and register)
+- **MCP tools**: `get_worktrees`, `delete_worktree`

package/templates/skills/cbp-merge-main/SKILL.md

@@ -0,0 +1,228 @@
+---
+scope: org-shared
+name: cbp-merge-main
+description: Merge main into the current feat branch with interactive per-conflict resolution and inline QA re-run
+model: sonnet
+effort: high
+---
+
+# Merge Main into Feat Branch
+
+Codifies the long-lived-branch-integration auto-memory rule (`[[feedback_long-lived-branch-integration]]`): when working on a feat branch that has diverged from main, merge main INTO the feat branch (not the reverse), resolve conflicts with the user, run a scoped QA pass, then return control to the caller — never rebase, never force-push, never push automatically.
+
+Triggered by `/cbp-task-start` (Step 3.6, optional stale-check), `/cbp-task-complete` (Step 4.5, mandatory pre-complete), and `/cbp-checkpoint-end` (Step 0, mandatory pre-shipment). User can also invoke manually at any time.
+
+## When to Use
+
+- **Auto-trigger (optional)**: `/cbp-task-start` Step 3.6 detects the feat branch is >10 commits behind `origin/{BASE}` OR the last fetch is >24h old.
+- **Auto-trigger (mandatory)**: `/cbp-task-complete` Step 4.5 — always run before marking a task complete to ensure the feat branch includes the latest main work.
+- **Auto-trigger (mandatory)**: `/cbp-checkpoint-end` Step 0 — always run before shipment to ensure no main drift reaches production.
+- **Manual invocation**: user runs `/cbp-merge-main` directly when they know main has advanced and want to pull it in immediately.
+
+## Instructions
+
+### Step 0: Pre-flight
+
+1. Read `.codebyplan/git.json` → `branch_config.base` (default `"main"`, read defensively — file may be absent) and `branch_config.protected` (default `["main"]`). Do NOT reference a removed `branch_config.integration` key.
+2. Run `git branch --show-current` → `CURRENT`. If `CURRENT` is in `branch_config.protected` OR does NOT match `feat/*`, error and STOP:
+
+   ```
+   /cbp-merge-main must run on a feat branch. Current: {CURRENT}.
+   Switch to a feat branch first.
+   ```
+
+3. Working-tree gate:
+   - Run `git diff --quiet`; if exit code is non-zero, `unstaged_dirty=true`, else `unstaged_dirty=false`.
+   - Run `git diff --cached --quiet`; if exit code is non-zero, `staged_present=true`, else `staged_present=false`.
+
+   Decision matrix:
+   - `unstaged_dirty=true` → AskUserQuestion:
+     - **Commit current changes first** (recommended) — trigger `/cbp-git-commit`, then re-check tree, then proceed.
+     - **Proceed with dirty tree** — soft warning; the merge may interleave with uncommitted edits.
+     - **Cancel** — abort the skill.
+   - `unstaged_dirty=false AND staged_present=true` → print one informational line and proceed to Step 1:
+     `Staged changes detected — proceeding with merge.`
+     (Pre-staged files will be included in the merge commit at Step 2 — this is intentional; the caller already approved them via /cbp-round-update.)
+   - `unstaged_dirty=false AND staged_present=false` → proceed silently to Step 1.
+   - Either `git diff` command exits with code ≥ 2 (git hard error — not-a-repo, detached HEAD with no commits, index lock, corrupt object store): surface the raw error output and STOP. Do NOT proceed to Step 1.
+
+   NEVER `git stash` for any reason (per `[[feedback_no-git-stash]]`).
+
+### Step 1: Fetch Latest Main
+
+1. Run `git fetch origin {BASE}`. **If this fails (offline, auth, registry)**, abort:
+
+   ```
+   /cbp-merge-main cannot proceed offline — `git fetch origin {BASE}` failed.
+   Resolve connectivity and re-invoke.
+   ```
+
+2. Measure drift:
+
+   ```bash
+   BEHIND=$(git rev-list --count HEAD..origin/{BASE})
+   AHEAD=$(git rev-list --count origin/{BASE}..HEAD)
+   ```
+
+3. If `BEHIND == 0`: print one-line `Already up to date with origin/{BASE} ({AHEAD} ahead, 0 behind).` and RETURN SUCCESS to the caller. No merge needed.
+
+### Step 1.5: Migration Timestamp Collision Pre-Check
+
+Supabase migrations are version-keyed by their numeric filename prefix. Two files sharing a prefix break `supabase db push`: the schema_migrations table records ONE version per prefix, the second file at the same prefix becomes orphaned, and every subsequent migration stalls — surfacing as the Supabase Preview check failing with `MIGRATIONS_FAILED`. Catch this BEFORE committing the merge, while a clean rollback is one `git merge --abort` away.
+
+1. Probe both sides of the would-be merge. Use `git ls-files` for the HEAD side so any in-progress `git mv` staged in the index (e.g. a rename produced by step 5 of a prior pass through this section) is reflected — `git ls-tree HEAD` would still see the committed-only state and re-trigger the collision. Use `git ls-tree origin/{BASE}` for the main side since we want the committed remote state, not anything locally staged:
+
+   ```bash
+   git ls-files supabase/migrations/ 2>/dev/null \
+     | sed 's|.*/||' | sort > /tmp/cbp-merge-our-names.txt
+   git ls-tree -r --name-only origin/{BASE} supabase/migrations/ 2>/dev/null \
+     | sed 's|.*/||' | sort > /tmp/cbp-merge-their-names.txt
+   ```
+
+2. A true collision is a numeric prefix that appears on BOTH sides with DIFFERENT filenames. A shared filename (same prefix, same basename — i.e. an already-merged migration) is NOT a collision. Compute the unique-to-each-side basenames first, then look for shared prefixes within that unique set:
+
+   ```bash
+   # Files unique to each side (same-named files are NOT collisions)
+   comm -23 /tmp/cbp-merge-our-names.txt /tmp/cbp-merge-their-names.txt > /tmp/cbp-merge-only-ours.txt
+   comm -13 /tmp/cbp-merge-our-names.txt /tmp/cbp-merge-their-names.txt > /tmp/cbp-merge-only-theirs.txt
+   # True collision: a prefix in only-ours also appears in only-theirs (same prefix, different basename)
+   COLLISIONS=$(cat /tmp/cbp-merge-only-ours.txt /tmp/cbp-merge-only-theirs.txt \
+     | sed 's|_.*||' | sort | uniq -d)
+   ```
+
+3. If `COLLISIONS` is empty, proceed silently to Step 2.
+
+4. If `COLLISIONS` is non-empty, for each colliding prefix list both file paths (one from `HEAD`, one from `origin/{BASE}`) and surface via AskUserQuestion:
+
+   - **Rename HEAD-side (Recommended when a main migration is already applied to a shared remote)** — rename the local file to a fresh, sequential timestamp that respects existing apply-order dependencies (probe `supabase migration list --db-url <preview>` if a preview branch exists, or inspect FK references in surrounding migrations). The orchestrator runs `git mv <old> <new>` itself; the rename lands in the git index and is picked up by the re-probe at step 5.
+   - **Rename main-side (manual, OUT-OF-SKILL)** — only when the main file definitely has not been applied anywhere yet AND the user has write access to `{BASE}`. This skill does NOT touch the main branch: it runs on a feat branch (Step 0 enforces this) and the Key Rules below forbid any push from this skill. The user must, in a separate terminal: `git checkout {BASE} && git mv <old> <new> && git commit -m "fix(migration): rename to resolve collision with feat/..." && git push origin {BASE}`. After that push is confirmed remote-side, re-invoke `/cbp-merge-main` — Step 1 will fetch the updated main tip and Step 1.5 will re-probe with the rename in place.
+   - **Defer to a new task in the active checkpoint** — `git merge --abort` is unnecessary because Step 2 has not started. Create a CHK-bound task per `infra-issue-absorption.md` "Resolve-in-Current-Scope by Default" and STOP `/cbp-merge-main`. Resume after the task completes.
+   - **Abort merge** — STOP the skill. User decides later.
+
+5. After any HEAD-side rename action, re-execute Step 1.5 (collisions may chain — fixing one can expose another). The HEAD-side probe at step 1 uses `git ls-files` rather than `git ls-tree HEAD`, so the freshly-staged `git mv` is visible without requiring a commit. Main-side renames require a fresh `/cbp-merge-main` invocation (the user manually fetched and re-ran per option 2 above), not an in-skill loop.
+
+This check is intentionally placed BEFORE Step 2's `git merge`: catching collisions pre-merge means no merge commit to revert, no conflict-resolution work to throw away, no Supabase Preview poll to fail.
+
+### Step 2: Merge with `--no-ff --no-commit`
+
+1. Run:
+
+   ```
+   git merge origin/{BASE} --no-ff --no-commit
+   ```
+
+   `--no-commit` defers the merge commit so Step 3 can resolve conflicts before committing (or `git merge --abort` if the user cancels). NEVER use `--ff-only` or rebase semantics — per locked decision.
+
+2. If git reports `Automatic merge went well; stopped before committing as requested.` (no conflicts):
+   - Commit the merge: `git commit --no-edit` (uses git's default merge message). If that fails (e.g. no MERGE_MSG template), fall back to: `git commit -m "chore(merge): integrate origin/{BASE} into {CURRENT}"`.
+   - Skip to Step 4.
+
+3. If conflicts: continue to Step 3.
+
+### Step 3: Interactive Per-Conflict Resolution
+
+1. List conflicted files and lock the count: `N=$(git diff --name-only --diff-filter=U | wc -l)`. `N` is the canonical conflict count used by Step 3.5 fallback message and Step 5 output; it stays fixed at the initial value across loop-backs.
+
+2. Load cross-reference context. Via MCP, gather all active CHK/TASK file ownership:
+   - `get_checkpoints(repo_id)` filtered to `status IN ('pending', 'active', 'in_progress')`.
+   - For each active checkpoint, also call `get_tasks(checkpoint_id)` and collect every `task.files_changed[].path` — checkpoint-bound task file ownership lives here, NOT on the checkpoint itself.
+   - `get_tasks(repo_id, standalone: true)` filtered to `status IN ('pending', 'in_progress')` — adds standalone-task file ownership.
+
+   Build a map `path -> [referencing CHK-NNN TASK-N + brief context]` by matching each conflicted path against:
+   - `checkpoint.context.files_to_change[]` (checkpoint-level plan)
+   - `task.files_changed[].path` (both checkpoint-bound AND standalone task file ownership)
+   - `task.requirements` (substring match for the path)
+
+3. For each conflicted file, IN ORDER:
+
+   a. Show:
+   - Conflicted file path
+   - `BEHIND` / `AHEAD` summary
+   - Cross-reference matches (`This file is referenced by CHK-NNN TASK-N: <brief>`)
+   - A unified diff of the conflict markers (`git diff -- {path}`)
+
+   b. Surface AskUserQuestion with these options. The "Recommended" tag is computed from cross-reference data:
+   - **Take ours (feat branch)** — `git checkout --ours {path} && git add {path}`.
+     Recommended when the path appears in any active CHK/TASK files_changed (the feat branch's work owns this file).
+   - **Take theirs (main)** — `git checkout --theirs {path} && git add {path}`.
+     Recommended when the path is NOT referenced by any active CHK/TASK (main's evolution wins by default).
+   - **Manual edit** — pause the skill. Prompt: `Edit {path} to resolve, then reply 'done' to continue.` Wait. After 'done': run `grep -l '<<<<<<<' {path}` — if it matches, the file still has conflict markers; surface the same prompt again. When clean: `git add {path}` and move on.
+   - **Show full diff** — print `git diff -- {path}` (working copy vs HEAD). For per-side views, run each separately (the `--base` / `--ours` / `--theirs` flags are mutually exclusive — combining them in one `git diff` invocation is invalid): `git diff --base -- {path}` (ancestor), `git diff --ours -- {path}` (HEAD), `git diff --theirs -- {path}` (MERGE_HEAD). After printing, RE-ASK the question — this option is meta and does not progress.
+
+   c. **Deliberate override of `[[feedback_claude-dir-wholesale-on-merge]]`**: that auto-memory rule recommended a wholesale `.claude/` overwrite for one-off long-lived-branch migrations. THIS skill is the routine periodic-sync mechanism, and the user explicitly chose per-conflict review for ALL paths including `.claude/`. Do NOT add a `.claude/`-wholesale shortcut. If a future maintainer is tempted to optimize by re-introducing the wholesale rule, the comment in this step is the contract: per-conflict review is the policy.
+
+4. After all conflicts resolved, verify clean: `git diff --name-only --diff-filter=U` MUST return empty. If not, loop back to step 3 with the remaining conflicts.
+
+5. Commit the merge:
+
+   ```
+   git commit --no-edit
+   ```
+
+   If that fails (e.g. no merge message template), fall back to explicit message:
+
+   ```
+   git commit -m "chore(merge): integrate origin/{BASE} into {CURRENT} (resolved {N} conflicts)"
+   ```
+
+### Step 4: Inline Automated QA Re-run
+
+Run a scoped subset of the testing-qa check matrix INLINE (no agent spawn — this skill stays lightweight):
+
+1. `pnpm -w lint` — always. On non-zero exit, surface stdout/stderr and AskUserQuestion:
+   - **Continue (commit-as-is)** — leave the merge committed; flag QA failure in output.
+   - **Abort merge** — `git reset --hard HEAD~1` to revert just the merge commit. Stop the skill.
+   - **Skip (mark warn)** — leave the merge committed; treat as warn, not fail.
+
+2. `pnpm exec tsc --noEmit` — only if any merged file matches `*.ts` or `*.tsx`. Same three-option prompt on failure.
+
+3. `pnpm test --run` — only if any merged file matches typical source globs (`src/**`, `apps/**/src/**`, `packages/**/src/**`). Same three-option prompt on failure.
+
+4. Build a `qa_summary` object:
+
+   ```
+   {
+     "lint": "pass" | "fail" | "warn" | "skipped",
+     "tsc": "pass" | "fail" | "warn" | "skipped",
+     "tests": "pass" | "fail" | "warn" | "skipped",
+     "merged_files_count": N,
+     "user_choice_on_failure": "continue" | "abort" | "skip" | null
+   }
+   ```
+
+Do NOT auto-revert without user consent. User-driven gating is the contract.
+
+### Step 5: Output
+
+Print:
+
+```
+## /cbp-merge-main complete
+
+**Merged**: origin/{BASE} → {CURRENT}
+**Commits pulled in**: {BEHIND}
+**Conflicts resolved**: {N}
+**QA**: {pass|warn|fail} ({passed}/{total})
+```
+
+Return control to the caller. **This skill NEVER pushes** — the caller decides when to push (preserves merge-commit review opportunity for the user before it lands on remote).
+
+## Key Rules
+
+- **Never rebase. Never force-push.** Merge-only via `--no-ff` (per `[[feedback_long-lived-branch-integration]]`).
+- **Never `git stash`** (per `[[feedback_no-git-stash]]`). Dirty tree → commit or cancel.
+- **Per-conflict user prompts — no shortcuts.** Deliberate override of `[[feedback_claude-dir-wholesale-on-merge]]`; that rule was scoped to a one-off migration.
+- **Never push.** Caller pushes after reviewing the merge commit.
+- **Abort on offline.** `git fetch` failure is a hard stop.
+
+## Integration
+
+- **Triggered by**:
+  - `/cbp-task-start` Step 3.6 (optional stale-check: >10 commits behind OR >24h fetch age)
+  - `/cbp-task-complete` Step 4.5 (mandatory pre-complete)
+  - `/cbp-checkpoint-end` Step 0 (mandatory pre-shipment)
+  - User-invocable manually
+- **Reads**: `.codebyplan/git.json`, MCP `get_checkpoints`, MCP `get_tasks`, git state
+- **Writes**: git merge commit (no MCP writes; no remote push)
+- **Spawns**: none (`/cbp-git-commit` is inline-triggered at Step 0 dirty-tree handling)
+- **Network**: contacts `origin` via `git fetch`. Offline = abort.