codebyplan 1.9.0 → 1.10.1

package/dist/cli.js

@@ -14,7 +14,7 @@ var VERSION, PACKAGE_NAME;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    VERSION = "1.9.0";
+    VERSION = "1.10.1";
     PACKAGE_NAME = "codebyplan";
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.9.0",
+  "version": "1.10.1",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {

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

@@ -23,6 +23,7 @@ Examples:
 - Must run from the **main repo** (the non-worktree checkout)
 - Working tree should be clean
 - Branch should not already exist as a worktree
+- New branches are always rooted at `origin/{production}` (read from `.codebyplan/git.json`), independent of the main repo's currently checked-out branch
 
 ## Instructions
 
@@ -87,18 +88,23 @@ If it exists, stop and inform the user.
 
 ### Step 4: Create Branch If Needed
 
+Resolve the production branch: read `.codebyplan/git.json` and take `branch_config.production` (fall back to `main` if the file or field is absent). Call this `$PRODUCTION`.
+
 Check if branch exists:
 
 ```bash
 git branch --list "$BRANCH_NAME"
 ```
 
-If branch does NOT exist, create it from current HEAD:
+If branch does NOT exist, create it from the freshest production tip — **not** from the main repo's ambient HEAD (which is often a stale home branch such as `codebyplan-main`):
 
 ```bash
-git branch "$BRANCH_NAME"
+git fetch origin "$PRODUCTION" 2>/dev/null || true
+git branch "$BRANCH_NAME" "origin/$PRODUCTION"
 ```
 
+This guarantees every worktree starts at `origin/{production}` regardless of which branch the main repo currently has checked out.
+
 ### Step 5: Create Worktree
 
 ```bash
@@ -204,6 +210,7 @@ No need to mark as `skip-worktree` — the committed files are merge-safe per CH
 **Branch**: [branch-name]
 **Path**: [worktree-path]
 **Main repo**: [main-repo-path]
+**Base**: origin/[production] ([sha])
 **CodeByPlan**: Registered (worktree ID: [id])
 
 ### Setup

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

@@ -10,12 +10,12 @@ effort: high
 
 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.
+Triggered by `/cbp-task-start` (Step 3.6, optional stale-check), `/cbp-task-complete` (Step 5.5, mandatory pre-push — runs after the task commit on a clean tree), 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-task-complete` Step 5.5 — mandatory pre-push, after the task commit; runs on a clean tree to ensure the feat branch includes the latest main work before the single trailing push.
 - **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.
 
@@ -219,7 +219,7 @@ Return control to the caller. **This skill NEVER pushes** — the caller decides
 
 - **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-task-complete` Step 5.5 (mandatory pre-push, after task commit)
   - `/cbp-checkpoint-end` Step 0 (mandatory pre-shipment)
   - User-invocable manually
 - **Reads**: `.codebyplan/git.json`, MCP `get_checkpoints`, MCP `get_tasks`, git state

package/templates/skills/cbp-session-end/SKILL.md

@@ -74,6 +74,31 @@ Same rule as `/cbp-session-start` Step 5.7 — only commit files that are **not*
 
 Non-blocking — session end proceeds either way.
 
+### Step 1.6: Home-Branch Fast-Forward
+
+Keep this worktree's **home branch** rooted at the freshest production tip — no prompt, fully non-blocking. Home branches are the folder-named placeholder branches each worktree rests on (e.g. `codebyplan-web`); `feat/*` branches are deliberately skipped — they integrate via `/cbp-merge-main` with QA, never an auto fast-forward.
+
+Runs after Step 1.5 so any infra commits land first, and before Step 1.7 so the asset-update CLIs operate on the freshest tree.
+
+Resolve the production branch: read `.codebyplan/git.json` and take `branch_config.production` (fall back to `main` if the file or field is absent). Call this `$PRODUCTION`. Then compare the current branch against the worktree's folder name:
+
+```bash
+FOLDER="$(basename "$(git rev-parse --show-toplevel)")"
+CURRENT="$(git rev-parse --abbrev-ref HEAD)"
+```
+
+- **`$CURRENT` != `$FOLDER`** (a `feat/*` or any non-home branch): skip silently — no fetch, no output.
+- **`$CURRENT` == `$FOLDER`** (home branch): fast-forward to `origin/$PRODUCTION`, warning once per failure and continuing:
+
+  ```bash
+  git fetch origin "$PRODUCTION" 2>/dev/null \
+    || echo "⚠ home-branch ff: fetch failed — staying on local $CURRENT"
+  git merge --ff-only "origin/$PRODUCTION" 2>/dev/null \
+    || echo "⚠ home-branch ff: $CURRENT not fast-forwardable (ahead/diverged) — left untouched"
+  ```
+
+Never rebase, reset, force-push, or stash. A non-fast-forwardable home branch is a signal to reconcile manually, not to overwrite.
+
 ### Step 1.7: Auto-Update CodeByPlan Assets
 
 Run the latest published CLIs to pull any asset or config changes. Sub-block A runs first, then Sub-block B. A failure in A does **not** skip B — each sub-block has its own retry-and-warn lane.
@@ -179,7 +204,7 @@ You can close this window.
 ## Integration
 
 - **Triggered by**: user invocation (prompted by `/cbp-todo` when no work remains)
-- **Reads**: `.codebyplan/repo.json`, MCP `get_session_logs` (resolve current log), MCP `get_current_task`, MCP `get_rounds`, MCP `get_next_action` (Step 1.3 handoff snapshot)
+- **Reads**: `.codebyplan/repo.json`, `.codebyplan/git.json` (`branch_config.production` for the Step 1.6 home-branch fast-forward), MCP `get_session_logs` (resolve current log), MCP `get_current_task`, MCP `get_rounds`, MCP `get_next_action` (Step 1.3 handoff snapshot)
 - **Writes**: MCP `update_session_log` (with `ended_at` + `handoff` per TASK-2 alias surface; or `create_session_log` fallback), MCP `update_session_state` (deactivate)
 - **Spawns**: none
 - **Triggers**: none at the skill-contract level. Steps 1.5 and 1.7 may invoke `/cbp-git-commit` inline on user approval.

package/templates/skills/cbp-session-start/SKILL.md

@@ -12,7 +12,7 @@ Activate the session, open a fresh session log, and surface the previous log's p
 
 ## Instructions
 
-Do Steps 0–5 and Step 4.5 silently (no intermediate output). Step 5.7 may surface an approval gate. Produce ONE output block at Step 6, then auto-trigger `/cbp-todo`.
+Do Steps 0–5 and Step 4.5 silently (no intermediate output). Step 1.4 may surface a one-line fast-forward note or warning, and Step 5.7 may surface an approval gate. Produce ONE output block at Step 6, then auto-trigger `/cbp-todo`.
 
 ### Step 0: MCP Health Check
 
@@ -50,6 +50,29 @@ Pass `WORKTREE_ID` to MCP tools that support it. Empty output means the (device,
 
 **If `worktree_id` resolves to empty** (the (device, path, branch) tuple does not match any registered worktree row): the session continues, but downstream MCP calls treat this caller as untagged — every hard-lock pre-guard sees a NULL `caller_worktree_id` and may reject mutations on assigned rows. Surface a one-line note in the Step 6 output instructing the user to run `npx codebyplan setup` from this directory to register the worktree.
 
+### Step 1.4: Home-Branch Fast-Forward
+
+Keep this worktree's **home branch** rooted at the freshest production tip — no prompt, fully non-blocking. Home branches are the folder-named placeholder branches each worktree rests on (e.g. `codebyplan-web`); `feat/*` branches are deliberately skipped — they integrate via `/cbp-merge-main` with QA, never an auto fast-forward.
+
+Resolve the production branch: read `.codebyplan/git.json` and take `branch_config.production` (fall back to `main` if the file or field is absent). Call this `$PRODUCTION`. Then compare the current branch against the worktree's folder name:
+
+```bash
+FOLDER="$(basename "$(git rev-parse --show-toplevel)")"
+CURRENT="$(git rev-parse --abbrev-ref HEAD)"
+```
+
+- **`$CURRENT` != `$FOLDER`** (a `feat/*` or any non-home branch): skip silently — no fetch, no output.
+- **`$CURRENT` == `$FOLDER`** (home branch): fast-forward to `origin/$PRODUCTION`, warning once per failure and continuing:
+
+  ```bash
+  git fetch origin "$PRODUCTION" 2>/dev/null \
+    || echo "⚠ home-branch ff: fetch failed — staying on local $CURRENT"
+  git merge --ff-only "origin/$PRODUCTION" 2>/dev/null \
+    || echo "⚠ home-branch ff: $CURRENT not fast-forwardable (ahead/diverged) — left untouched"
+  ```
+
+Never rebase, reset, force-push, or stash. A non-fast-forwardable home branch is a signal to reconcile manually, not to overwrite.
+
 ### Step 2: Check Dev Server
 
 **Skip if `server_type` is `"none"`.**
@@ -147,7 +170,7 @@ Trigger `/cbp-todo` to determine what to work on.
 ## Integration
 
 - **Triggered by**: user invocation, `/clear` recovery
-- **Reads**: `.codebyplan/repo.json`, MCP `get_session_logs` (worktree-filtered, limit 1 — single call shared by Step 4 and Step 4.5), MCP `health_check`, MCP `get_current_task`, MCP `get_rounds`, MCP `get_checkpoints` / `get_tasks` / `get_rounds` for freshness probe (Step 4.5)
+- **Reads**: `.codebyplan/repo.json`, `.codebyplan/git.json` (`branch_config.production` for the Step 1.4 home-branch fast-forward), MCP `get_session_logs` (worktree-filtered, limit 1 — single call shared by Step 4 and Step 4.5), MCP `health_check`, MCP `get_current_task`, MCP `get_rounds`, MCP `get_checkpoints` / `get_tasks` / `get_rounds` for freshness probe (Step 4.5)
 - **Writes**: MCP `create_session_log` (new, possibly empty), MCP `update_session_state` (activate)
 - **Spawns**: none
 - **Triggers**: `/cbp-git-commit` (conditional, on user approval), `handoff.command` (on fresh handoff hit at Step 4.5), `/cbp-todo` (auto fall-through)

package/templates/skills/cbp-task-complete/SKILL.md

@@ -102,26 +102,34 @@ Load `task.qa` and `task.files_changed`:
 
 Collect all files_changed from task. Deduplicate (latest action wins).
 
-### Step 4.5: Merge Production Branch Before Commit (mandatory)
+### Step 5: Git Commit (no push)
 
-Before committing task work, ensure the feat branch is current with the latest production (main) work. This prevents shipping a stale PR and surfaces conflicts at task-complete time rather than at PR review.
+Commit the task work FIRST, so the merge in Step 5.5 runs against a clean tree. `/cbp-merge-main` must never run before the task commit.
 
-1. Trigger `/cbp-merge-main`.
-2. If the skill exits with failure (offline, unresolved conflicts, user-aborted): surface the failure and STOP — do NOT proceed to Step 5 (commit). The user resolves and re-invokes `/cbp-task-complete`.
-3. If the skill exits with QA warnings the user chose to commit-as-is: continue to Step 5; surface a soft warning in the Step 9 output (`⚠ Merged with QA failures pending fix in follow-up`).
-4. On clean success: continue to Step 5.
+**Zero-file guard**: if `aggregated_files` is empty (investigative or DB-only tasks), skip the commit. Record "No git commit: zero files changed" in the Step 9 summary, then continue to Step 5.5 (the branch may still need a main sync).
+
+**Already-committed guard**: if the aggregated files are already committed (working tree clean for them — e.g. a re-invoke after a Step 5.5 merge failure), skip the commit and continue to Step 5.5; the prior run's task commit still stands.
+
+Otherwise: invoke `/cbp-git-commit` to stage approved files and create the commit. Claude does NOT git add directly. Do NOT push here — the push in Step 5.7 carries both this commit and the merge commit.
 
-### Step 5: Git Commit and Push
+### Step 5.5: Merge Production Branch (mandatory)
+
+Now that task work is committed, ensure the feat branch is current with the latest production (main) work. Running the merge AFTER the commit means `/cbp-merge-main` resolves conflicts against committed work on a clean tree — no dirty-tree interleave, no Step-0 dirty-tree prompt for the task files. This still prevents shipping a stale PR and surfaces conflicts at task-complete time rather than at PR review.
+
+1. Trigger `/cbp-merge-main`.
+2. If the skill exits with failure (offline, unresolved conflicts, user-aborted): surface the failure and STOP — do NOT proceed to Step 5.7 (push) or Step 7 (complete). The task commit from Step 5 persists; the user resolves and re-invokes `/cbp-task-complete`, which re-runs the merge on the now-clean tree.
+3. If the skill exits with QA warnings the user chose to commit-as-is: continue to Step 5.7; surface a soft warning in the Step 9 output (`⚠ Merged with QA failures pending fix in follow-up`).
+4. On clean success: continue to Step 5.7.
 
-**Zero-file guard**: if `aggregated_files` is empty (investigative or DB-only tasks), skip commit and push. Record "No git commit: zero files changed" in the Step 9 summary.
+### Step 5.7: Push
 
-Otherwise: invoke `/cbp-git-commit` to stage approved files and create the commit. Claude does NOT git add directly. After commit:
+Push once, carrying BOTH the task commit (Step 5) and the merge commit (Step 5.5):
 
 ```bash
 git push origin $(git branch --show-current)
 ```
 
-If push fails, investigate and fix per migration-infrastructure rule — never skip.
+Skip the push only when nothing was committed in Step 5 AND `/cbp-merge-main` reported already-up-to-date (nothing to push). If push fails, investigate and fix per migration-infrastructure rule — never skip.
 
 ### Step 6: Update Task Files