codebyplan 1.13.64 → 1.13.66

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

@@ -22,46 +22,44 @@ Always write a session log for this session — **even if empty**. `/cbp-session
 2. Pull facts from local state files rather than narrating from memory:
    - Rounds added/completed, tasks advanced/completed during this session (read from `.codebyplan/state/checkpoints/` subtree)
    - Decisions, blockers, or discoveries recorded in checkpoint/task context
-3. Run `codebyplan session update-log --id <log-id> --ended-at <now> --summary <text> --pending <text> --git-branch <current-branch>` (CLI write-through: updates `.codebyplan/state/session/current.json` + REST). Break-glass fallback: MCP `update_session_log` when the CLI is unavailable. Fields:
+3. Run `codebyplan session update-log --id <log-id> --ended-at <now> --git-branch <current-branch>` (CLI write-through: updates `.codebyplan/state/session/current.json` + REST). Break-glass fallback: MCP `update_session_log` when the CLI is unavailable. Fields:
    - `ended_at`: now (maps to the `closed_at` column per TASK-2 alias)
-   - `summary`: concise — may be empty if nothing happened
-   - `pending`: open items the next session should see first
    - `git_branch`: the current git branch (informational; `git rev-parse --abbrev-ref HEAD`)
-   - **Do NOT pass `--handoff` / `handoff` field.** The DB handoff field is no longer written here. Omit entirely — never pass `handoff:null` (it clobbers summary/pending content).
+   - Carryover notes now go to committed `.codebyplan/handoff/` files (Step 1.3) — not the session log.
 
 ### Step 1.3: Optional Handoff File (mid-work only)
 
 When an active in-progress task or round exists, offer to write a handoff file so the next session can auto-resume. Skip entirely when not mid-work.
 
-1. Read `.codebyplan/state/todos.json` (local-first) and check `rows[0]` (queue head, ordered by `sort_order`). If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_todos({ repo_id })` when the state dir is absent and sync fails. The worker stamps `command`, `instructions`, `state`, and entity ids `checkpoint_id` / `task_id` / `round_id` on every row.
+1. Read `.codebyplan/state/todos.json` (local-first) and check `rows[0]` (queue head, ordered by `sort_order`). If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_todos({ repo_id })` when the state dir is absent and sync fails.
 
 2. **If `rows[0]` exists and its `command` is non-empty** (active work in flight):
-   - Determine the handoff file path. The directory is keyed by the human-facing **number** (`<NNN>` checkpoint number / `<N>` standalone task number) — matching the committed `.codebyplan/checkpoint/<NNN>/` plan-artifact convention and the session-start resume probe (which globs by number). Resolve the number from local state (break-glass: MCP):
-     - Checkpoint work: read `.codebyplan/state/checkpoints/<rows[0].checkpoint_id>.json` → `number` (break-glass: MCP `get_checkpoints`). Path: `.codebyplan/checkpoint/<NNN>/handoff.md`.
-     - Standalone work: read the standalone task's `number` from local standalone state (break-glass: MCP `get_standalone_tasks`). Path: `.codebyplan/standalone/<N>/handoff.md`.
-   - Offer to write the file:
+   - Resolve the level and number (level is `checkpoint`/`standalone`, NOT `task` — a session-end
+     handoff is a checkpoint-scope resume-pointer; `task`-level handoffs are reserved for explicit
+     user-deferred scope and gate only `/cbp-finalize`):
+     - Checkpoint work: read `.codebyplan/state/checkpoints/<rows[0].checkpoint_id>.json` → `number` (break-glass: MCP `get_checkpoints`). Level: `checkpoint`, number: `<NNN>` (3-digit zero-pad).
+     - Standalone work: read the standalone task `number` from local standalone state (break-glass: MCP `get_standalone_tasks`). Level: `standalone`, number: `<N>`.
+   - Offer to write:
      ```
-     Write handoff file for next session?
-     <path>
+     Write handoff for next session?
+     .codebyplan/handoff/<level>/<identifier>.md
 
      Reply: yes | no
      ```
-   - On `yes`: write the file with this structure:
+   - On `yes`: run `codebyplan handoff write --level <level> --number <N> --content "<content>"` where content is:
      ```markdown
-     ---
-     command: <rows[0].command>
-     state: <rows[0].state>
-     captured_at: <ISO now>
-     checkpoint_id: <rows[0].checkpoint_id or null>
-     task_id: <rows[0].task_id or null>
-     round_id: <rows[0].round_id or null>
-     ---
-
-     <rows[0].instructions — human-readable trigger reason>
+     ## Session handoff — CHK-<N>
+
+     Captured: <ISO now>
+     Next action: `<rows[0].command>`
+
+     <rows[0].instructions>
      ```
-   - The file is committed with the session's final commit (Step 1.5) or the user can stage it manually.
+     (Standalone variant: `## Session handoff — TASK-<N>` heading.)
+   - On `no`: skip — do not create an empty file.
+   - The committed file is picked up by the Step 1.5 infra-commit offer automatically (it lives under the managed `.gitignore` negation `!.codebyplan/handoff/`).
 
-3. **If the queue is empty or `rows[0].command` is empty/idle**: skip — no handoff file is written.
+3. **If the queue is empty or `rows[0].command` is empty/idle**: skip.
 
 ### Step 1.5: Commit Non-Task Files
 
@@ -146,7 +144,7 @@ You can close this window.
 
 - **Triggered by**: user invocation (prompted by `/cbp-todo` when no work remains)
 - **Reads**: `.codebyplan/repo.json`; local-first reads (with `npx codebyplan sync` + MCP break-glass): `.codebyplan/state/session/current.json` (Step 1 resolve log), `.codebyplan/state/todos.json` (Step 1.3 mid-work detection + Step 1.5 active-task lookup), `.codebyplan/state/checkpoints/<id>/tasks/<id>/rounds/` (Step 1.5 task-file resolution); `codebyplan session freshness-gate` (Step 1.7 package-freshness gate, without --halt-on-update); `codebyplan session infra-files --json --task-files <csv>` (Step 1.5 infra-file set math)
-- **Writes**: `codebyplan session update-log --id <id> --git-branch <branch> ...` (Step 1 finalize — CLI write-through to `.codebyplan/state/session/current.json`; break-glass: MCP `update_session_log`; handoff field never passed), `codebyplan session create-log` (Step 1 fallback when no log exists; break-glass: MCP `create_session_log`), optional handoff file at `.codebyplan/checkpoint/<NNN>/handoff.md` or `.codebyplan/standalone/<N>/handoff.md` (Step 1.3, mid-work only), `codebyplan session update-state --action deactivate` (Step 3 — CLI write-through to `.codebyplan/state/session/state.json`; break-glass: MCP `update_session_state`)
+- **Writes**: `codebyplan session update-log --id <id> --ended-at <now> --git-branch <branch>` (Step 1 finalize — CLI write-through to `.codebyplan/state/session/current.json`; break-glass: MCP `update_session_log`; summary/pending/handoff fields never passed), `codebyplan session create-log` (Step 1 fallback when no log exists; break-glass: MCP `create_session_log`), `codebyplan handoff write --level <checkpoint|standalone> --number <N>` (Step 1.3, mid-work only, committed under `.codebyplan/handoff/`), `codebyplan session update-state --action deactivate` (Step 3 — CLI write-through to `.codebyplan/state/session/state.json`; break-glass: MCP `update_session_state`)
 - **Spawns**: none
 - **Triggers**: none at the skill-contract level. Step 1.5 may invoke `/cbp-git-commit` inline on user approval; Step 1.7 may invoke `/cbp-git-commit` on the `result === 'updated'` path (committing changed `.claude/` and `.codebyplan/` paths).
 - **Paired with**: `/cbp-session-start`

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

@@ -78,7 +78,29 @@ The envelope shape:
 **Parse and branch**:
 
 - `status === 'update_halt'` → print `rendered_block` (the update-halt message) and **STOP**. No further writes, no `/cbp-todo` trigger.
-- Otherwise → print `rendered_block` (the Step 6 output block), then proceed to Step 5.7 and Step 7.
+- Otherwise → print `rendered_block` (the Step 6 output block), then proceed to Step 5.5, Step 5.7, and Step 7.
+
+### Step 5.5: Surface Committed Handoff Notes
+
+After printing the orchestrator output, surface any committed handoff files from previous sessions. Non-blocking.
+
+1. Run `codebyplan handoff status --json` → parse `nonEmpty[]`.
+2. If `nonEmpty` is empty → skip silently.
+3. For each entry in `nonEmpty`, read the content:
+   - `repo` → `codebyplan handoff read --level repo`
+   - `checkpoint` → `codebyplan handoff read --level checkpoint --number <identifier>`
+   - `task` → split identifier `"<NNN>-<T>"` → `codebyplan handoff read --level task --number <NNN> --task <T>`
+   - `standalone` → `codebyplan handoff read --level standalone --number <identifier>`
+4. Display:
+   ```
+   Handoff notes from previous session(s):
+
+   [<level>: <identifier>]
+   <content>
+
+   ---
+   ```
+5. Non-blocking — proceed to Step 5.7 regardless.
 
 ### Step 5.7: Commit Non-Task Files (Claude-side)
 
@@ -109,7 +131,7 @@ Route from `envelope.next_action`:
 ## Integration
 
 - **Triggered by**: user invocation, `/clear` recovery
-- **Reads**: MCP `health_check` (Step 0 hard gate — stays MCP unconditionally); `codebyplan session start --json` (Steps 1–5.8 — the orchestrator runs `codebyplan whoami --json` for caller identity and reads `.codebyplan/repo.json`, `.codebyplan/git.json`, `.codebyplan/state/session/current.json`, `.codebyplan/state/todos.json`, `.codebyplan/state/checkpoints/` entity files, `scripts/infra-drift.mjs`, `.codebyplan/architecture.json`, `.codebyplan/lsp.json`)
+- **Reads**: MCP `health_check` (Step 0 hard gate — stays MCP unconditionally); `codebyplan session start --json` (Steps 1–5.8 — the orchestrator runs `codebyplan whoami --json` for caller identity and reads `.codebyplan/repo.json`, `.codebyplan/git.json`, `.codebyplan/state/session/current.json`, `.codebyplan/state/todos.json`, `.codebyplan/state/checkpoints/` entity files, `scripts/infra-drift.mjs`, `.codebyplan/architecture.json`, `.codebyplan/lsp.json`); `codebyplan handoff status --json` + `codebyplan handoff read --level <l> ...` (Step 5.5 — committed handoff surfacing)
 - **Writes**: orchestrator calls `codebyplan session update-state --action activate` (Step 7) and `codebyplan session create-log` (Step 8 — user-level; no worktree_id in the body) — both SKIPPED on Step 0 hard-fail and on `status: update_halt`
 - **Spawns**: none
 - **Triggers**: `/cbp-git-commit` (conditional, on user approval at Step 5.7), `envelope.handoff.command` (on `next_action: resume_handoff`), `/cbp-todo` (on `next_action: trigger_todo` or `commit_then_todo`); STOPS with no trigger on `next_action: stop` or `mcp_update_halt`

package/templates/skills/cbp-setup-cd/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-setup-cd
 description: Detect configured CD surfaces, write/update .codebyplan/cd.json via `codebyplan cd init`, scaffold publish.yml and release-desktop.yml GitHub Actions workflows, and walk through environment/approval/OIDC setup. Interactive, idempotent.
 argument-hint: "[--force]"

package/templates/skills/cbp-setup-ci/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-setup-ci
 description: Detect CI platforms, write/update .codebyplan/ci.json, scaffold the GitHub Actions CI workflow, and enforce the required CI status check on the main branch. Interactive, idempotent.
 argument-hint: "[--force]"

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

@@ -80,6 +80,38 @@ Stop here.
 
 `task.context.task_testing_output` must exist with `all_passed: true`. If not, surface "Run `/cbp-standalone-task-testing` first" and stop.
 
+### Step 2.7: Verify Standalone Task Handoff Is Resolved
+
+Run `codebyplan handoff status --json` and parse the output.
+
+Check if `nonEmpty[]` contains an entry where `level === 'standalone'` AND `identifier === '{N}'`
+(the bare standalone task number — e.g. `45`).
+
+If a matching entry is found, BLOCK with:
+
+```
+## Cannot Complete Standalone Task — Handoff Unresolved
+
+Standalone TASK-[N] has unresolved handoff content at `.codebyplan/handoff/standalone/[N].md`.
+
+The handoff file contains scope that has not been resolved. You must clear it before
+completing this task. Three options — pick exactly one:
+
+1. **Absorb** — address the pending scope in current work, then clear:
+   `codebyplan handoff clear --level standalone --number [N]`
+2. **Defer** — create a new standalone task to cover the scope,
+   then clear: `codebyplan handoff clear --level standalone --number [N]`
+3. **Escalate** — move the content to the repo handoff:
+   `codebyplan handoff append --level repo --content "<content>"`
+   then clear: `codebyplan handoff clear --level standalone --number [N]`
+
+Never silently delete handoff content — it represents tracked scope.
+```
+
+(STOP)
+
+If no matching entry: continue to Step 3.
+
 ### Step 3: Verify QA and File Approval
 
 Load `task.qa` and `task.files_changed`:

package/templates/skills/cbp-stripe/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-stripe
 description: "Stripe integration guidance — load when implementing or reviewing payments, Checkout, subscriptions/billing, webhooks, Connect, Tax, or Treasury. Encodes the API-selection routing table, the no-payment_method_types rule, restricted-key security, and Stripe SDK conventions."
 model: inherit