cc-workspace 4.1.4 → 4.2.1

package/README.md

@@ -88,13 +88,13 @@ my-workspace/
 │   ├── .claude/
 │   │   ├── settings.json           <- env vars + hooks
 │   │   └── hooks/
-│   │       ├── block-orchestrator-writes.sh
 │   │       ├── session-start-context.sh
 │   │       ├── validate-spawn-prompt.sh
-│   │       └── ...                  <- 11 scripts
+│   │       └── ...                  <- 9 scripts (all warning-only)
 │   ├── CLAUDE.md                    <- orchestrator profile
 │   ├── workspace.md                 <- filled by workspace-init
 │   ├── constitution.md              <- filled by workspace-init
+│   ├── .sessions/                   <- session state (gitignored, created per session)
 │   ├── templates/
 │   │   ├── workspace.template.md
 │   │   ├── constitution.template.md
@@ -110,6 +110,70 @@ my-workspace/
 
 ---
 
+## Parallel sessions (branch isolation)
+
+Run multiple features in parallel without branch conflicts.
+
+### The problem
+
+When two orchestrator sessions dispatch teammates to the same repo, branches get mixed:
+teammates from session B may branch off session A's code. The result is interleaved commits
+and confused agents.
+
+### The solution
+
+Each feature gets a **session** — a named scope that maps to a dedicated `session/{name}`
+branch in each impacted repo. Branches are created from a configurable **source branch**
+(e.g., `preprod`, `develop`) defined per repo in `workspace.md`.
+
+### Setup source branches (one time)
+
+In `workspace.md`, add the `Source Branch` column to the service map:
+
+```markdown
+| Service  | Repo        | Type     | CLAUDE.md | Source Branch | Description    |
+|----------|-------------|----------|-----------|---------------|----------------|
+| api      | ../api      | backend  | ✓         | preprod       | REST API       |
+| frontend | ../frontend | frontend | ✓         | preprod       | Vue/Quasar SPA |
+```
+
+### How it works
+
+1. The team-lead identifies impacted repos during planning (Phase 2)
+2. After plan approval, **Phase 2.5** creates a session:
+   - Writes `.sessions/{name}.json` with impacted repos only
+   - Spawns a Task subagent to run `git branch session/{name} {source}` in each repo
+   - Uses `git branch` (NOT `git checkout -b`) to avoid disrupting other sessions
+3. Teammates receive the session branch in their spawn prompt — they do NOT create their own branches
+4. PRs go from `session/{name}` → `source_branch` (never to main directly)
+
+### Session CLI commands
+
+```bash
+cc-workspace session list                  # show active sessions + branches
+cc-workspace session status feature-auth   # commits per repo on session branch
+cc-workspace session close feature-auth    # interactive: create PRs, delete branches, clean up
+```
+
+`session close` asks for confirmation before every action (PR creation, branch deletion, JSON cleanup).
+
+### Parallel workflow
+
+```bash
+# Terminal 1
+cd orchestrator/
+claude --agent team-lead
+# → "Implement OAuth" → creates session/feature-auth in api/ + frontend/
+
+# Terminal 2
+cd orchestrator/
+claude --agent team-lead
+# → "Add billing" → creates session/feature-billing in api/ + frontend/
+# Both sessions are fully isolated — different branches, no conflicts
+```
+
+---
+
 ## How it works
 
 ### The problem
@@ -149,6 +213,7 @@ parallel in each repo via Agent Teams.
 ```
 CLARIFY  -> ask max 5 questions if ambiguity
 PLAN     -> write the plan in ./plans/, wait for approval
+SESSION  -> create session branches in impacted repos (Phase 2.5)
 SPAWN    -> Wave 1: API/data in parallel
            Wave 2: frontend with validated API contract
            Wave 3: infra/config if applicable
@@ -160,14 +225,13 @@ REPORT   -> final summary
 ### Security — path-aware writes
 
 The orchestrator can write in `orchestrator/` (plans, workspace.md, constitution.md)
-but never in sibling repos. The `block-orchestrator-writes.sh` hook dynamically
-detects if the target path is in a repo (presence of `.git/`).
+but never in sibling repos. A `PreToolUse` hook in the team-lead agent frontmatter
+dynamically checks if the target path is inside orchestrator/ before allowing writes.
 
 Protection layers:
 1. `disallowedTools: Bash` in agent frontmatter
 2. `tools` whitelist in agent frontmatter (note: `allowed-tools` is the skill equivalent)
-3. `PreToolUse` path-aware hook in agent frontmatter
-4. `block-orchestrator-writes.sh` hook in .claude/hooks/
+3. `PreToolUse` path-aware hook in agent frontmatter (team-lead only — teammates write freely in their worktrees)
 
 ---
 
@@ -200,15 +264,15 @@ next one starts. The plan on disk is the source of truth.
 
 ---
 
-## The 9 hooks + 1 agent-level hook
+## The 9 hooks (settings.json) + 1 agent-level hook (team-lead frontmatter)
 
 All hooks in settings.json are **non-blocking** (exit 0 + warning). No hook blocks the session.
 
 | Hook | Event | Effect |
 |------|-------|--------|
-| **block-orchestrator-writes** | `PreToolUse` Write\|Edit\|MultiEdit | Blocks writes in repos, allows orchestrator/. **Agent frontmatter only** (team-lead) — not in settings.json, so teammates can write freely. |
-| **validate-spawn-prompt** | `PreToolUse` Teammate | Warning if missing context (rules, UX, tasks) |
-| **session-start-context** | `SessionStart` | Injects active plans + first session detection |
+| **path-aware write guard** | `PreToolUse` Write\|Edit\|MultiEdit | Blocks writes outside orchestrator/. **Agent frontmatter only** (team-lead) — not in settings.json, so teammates write freely in worktrees. |
+| **validate-spawn-prompt** | `PreToolUse` Teammate | Warning if missing context (rules, UX, tasks, session branch) |
+| **session-start-context** | `SessionStart` | Injects active plans + active sessions + first session detection |
 | **user-prompt-guard** | `UserPromptSubmit` | Warning if code requested in a repo |
 | **subagent-start-context** | `SubagentStart` | Injects active plan + constitution |
 | **permission-auto-approve** | `PermissionRequest` | Auto-approve Read/Glob/Grep |
@@ -339,6 +403,20 @@ Both `init` and `update` are safe to re-run:
 
 ---
 
+## Changelog v4.1.4 -> v4.2.0
+
+| # | Feature | Detail |
+|---|---------|--------|
+| 1 | **Session management** | Branch isolation for parallel features. Each session creates `session/{name}` branches in impacted repos only. `git branch` (no checkout) to avoid disrupting other sessions. |
+| 2 | **Source branch per repo** | `workspace.md` service map now includes a `Source Branch` column (e.g., `preprod`, `develop`). Session branches are created from this branch. |
+| 3 | **Phase 2.5 in dispatch** | New phase between Plan and Dispatch: creates session JSON + branches via Task subagent. |
+| 4 | **CLI session commands** | `cc-workspace session list/status/close`. Close is interactive — asks confirmation before PRs, branch deletion, JSON cleanup. |
+| 5 | **Session-aware hooks** | `session-start-context.sh` detects active sessions. `validate-spawn-prompt.sh` warns if session branch missing from spawn prompt. |
+| 6 | **Spawn templates updated** | Teammates use `session/{name}` branch (already exists). No more `feature/[name]` — teammates never create their own branches. |
+| 7 | **merge-prep session-aware** | Reads `.sessions/` for branch names and source branches. PRs target source branch, not hardcoded main. |
+
+---
+
 ## Changelog v4.1.0 -> v4.1.4
 
 | # | Fix | Detail |

package/bin/cli.js

@@ -225,7 +225,8 @@ function generateSettings(orchDir) {
         // block-orchestrator-writes.sh is NOT here — it's in team-lead agent
         // frontmatter only. Putting it in settings.json would block teammates
         // from writing in their worktrees.
-        withMatcher("Teammate", "validate-spawn-prompt.sh", 5)
+        withMatcher("Teammate", "validate-spawn-prompt.sh", 5),
+        withMatcher("Bash", "guard-session-checkout.sh", 5)
       ],
       SessionStart: [
         withoutMatcher("session-start-context.sh", 10)
@@ -256,65 +257,10 @@ function generateSettings(orchDir) {
   fs.writeFileSync(path.join(orchDir, ".claude", "settings.json"), JSON.stringify(settings, null, 2) + "\n");
 }
 
-// ─── Block hook (inline, always regenerated) ────────────────
-function generateBlockHook(hooksDir) {
-  const blockHook = `#!/usr/bin/env bash
-# block-orchestrator-writes.sh v${PKG.version}
-# PreToolUse hook: blocks writes to sibling repos. Allows writes within orchestrator/.
-set -euo pipefail
-
-INPUT=$(cat)
-
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null) || FILE_PATH=""
-
-if [ -z "$FILE_PATH" ]; then
-    cat << 'EOF'
-{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Cannot determine target path. Delegate to a teammate."}}
-EOF
-    exit 0
-fi
-
-ORCH_DIR="\${CLAUDE_PROJECT_DIR:-.}"
-ORCH_ABS="$(cd "$ORCH_DIR" 2>/dev/null && pwd)" || ORCH_ABS=""
-
-if [ -d "$(dirname "$FILE_PATH")" ]; then
-    TARGET_ABS="$(cd "$(dirname "$FILE_PATH")" 2>/dev/null && pwd)/$(basename "$FILE_PATH")"
-else
-    TARGET_ABS="$FILE_PATH"
-fi
-
-if [ -n "$ORCH_ABS" ]; then
-    case "$TARGET_ABS" in
-        "$ORCH_ABS"/*)
-            exit 0
-            ;;
-    esac
-fi
-
-PARENT_DIR="$(dirname "$ORCH_ABS" 2>/dev/null)" || PARENT_DIR=""
-if [ -n "$PARENT_DIR" ]; then
-    for repo_dir in "$PARENT_DIR"/*/; do
-        [ -d "$repo_dir/.git" ] || continue
-        REPO_ABS="$(cd "$repo_dir" 2>/dev/null && pwd)"
-        case "$TARGET_ABS" in
-            "$REPO_ABS"/*)
-                REPO_NAME=$(basename "$REPO_ABS")
-                cat << EOF
-{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"BLOCKED: Cannot write in repo $REPO_NAME/. Delegate to a teammate via Agent Teams."}}
-EOF
-                exit 0
-                ;;
-        esac
-    done
-fi
-
-cat << 'EOF'
-{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"BLOCKED: Write target is outside orchestrator/. Delegate to a teammate."}}
-EOF
-exit 0
-`;
-  fs.writeFileSync(path.join(hooksDir, "block-orchestrator-writes.sh"), blockHook, { mode: 0o755 });
-}
+// ─── Block hook ──────────────────────────────────────────────
+// block-orchestrator-writes is now ONLY in team-lead agent frontmatter.
+// It is NOT in settings.json (would be inherited by teammates, blocking their writes).
+// The generateBlockHook() function was removed in v4.1.4.
 
 // ─── CLAUDE.md content ──────────────────────────────────────
 function claudeMdContent() {
@@ -356,6 +302,7 @@ Run once. Idempotent — can be re-run to re-diagnose.
 - Templates: \`./templates/\`
 - Service profiles: \`./plans/service-profiles.md\`
 - Active plans: \`./plans/*.md\`
+- Active sessions: \`./.sessions/*.json\`
 
 ## Skills (9)
 - **dispatch-feature**: 4 modes, clarify → plan → waves → collect → verify
@@ -382,6 +329,8 @@ Run once. Idempotent — can be re-run to re-diagnose.
 11. Compact after each cycle
 12. Hooks are warning-only — never blocking
 13. Retrospective cycle after each completed feature
+14. Session branches for parallel isolation — teammates use session/{name}, never create own branches
+15. Never \`git checkout -b\` in repos — use \`git branch\` (no checkout) to avoid disrupting parallel sessions
 `;
 }
 
@@ -398,9 +347,9 @@ function planTemplateContent() {
 [Clarify answers]
 
 ## Impacted services
-| Service | Impacted | Branch | Teammate | Status |
-|---------|----------|--------|----------|--------|
-| | yes/no | feature/[name] | | ⏳ |
+| Service | Impacted | Session Branch | Teammate | Status |
+|---------|----------|----------------|----------|--------|
+| | yes/no | session/[name] | | ⏳ |
 
 ## Waves
 - Wave 1: [producers]
@@ -518,6 +467,13 @@ function updateLocal() {
     ok("_TEMPLATE.md updated");
   }
 
+  // ── .sessions/ (create if missing) ──
+  const sessionsDir = path.join(orchDir, ".sessions");
+  if (!fs.existsSync(sessionsDir)) {
+    mkdirp(sessionsDir);
+    ok(".sessions/ created");
+  }
+
   // ── NEVER touch: workspace.md, constitution.md, plans/*.md, service-profiles.md ──
   info(`${c.dim}workspace.md, constitution.md, plans/ — preserved${c.reset}`);
 
@@ -534,6 +490,7 @@ function setupWorkspace(workspacePath, projectName) {
   mkdirp(path.join(orchDir, ".claude", "hooks"));
   mkdirp(path.join(orchDir, "plans"));
   mkdirp(path.join(orchDir, "templates"));
+  mkdirp(path.join(orchDir, ".sessions"));
   ok("Structure created");
 
   // ── Templates ──
@@ -615,6 +572,7 @@ function setupWorkspace(workspacePath, projectName) {
   if (!fs.existsSync(gi)) {
     fs.writeFileSync(gi, [
       ".claude/bash-commands.log", ".claude/worktrees/", ".claude/modified-files.log",
+      ".sessions/",
       "plans/*.md", "!plans/_TEMPLATE.md", "!plans/service-profiles.md", ""
     ].join("\n"));
     ok(".gitignore");
@@ -745,6 +703,7 @@ function doctor() {
     check("plans/", fs.existsSync(path.join(cwd, "plans")), "missing");
     check("templates/", fs.existsSync(path.join(cwd, "templates")), "missing");
     check(".claude/hooks/", fs.existsSync(path.join(cwd, ".claude", "hooks")), "missing");
+    check(".sessions/", fs.existsSync(path.join(cwd, ".sessions")), "missing — run: npx cc-workspace update");
     const configured = !fs.readFileSync(path.join(cwd, "workspace.md"), "utf8").includes("[UNCONFIGURED]");
     check("workspace.md configured", configured, "[UNCONFIGURED] — run: claude --agent workspace-init");
   } else if (hasOrch) {
@@ -766,6 +725,37 @@ function doctor() {
   log("");
 }
 
+// ─── Session helpers ─────────────────────────────────────────
+function findOrchDir() {
+  const cwd = process.cwd();
+  if (fs.existsSync(path.join(cwd, "workspace.md"))) return cwd;
+  if (fs.existsSync(path.join(cwd, "orchestrator", "workspace.md")))
+    return path.join(cwd, "orchestrator");
+  return null;
+}
+
+function readSessions(orchDir) {
+  const sessDir = path.join(orchDir, ".sessions");
+  if (!fs.existsSync(sessDir)) return [];
+  return fs.readdirSync(sessDir)
+    .filter(f => f.endsWith(".json"))
+    .map(f => {
+      try {
+        return JSON.parse(fs.readFileSync(path.join(sessDir, f), "utf8"));
+      } catch { return null; }
+    })
+    .filter(Boolean);
+}
+
+function sessionStatusBadge(status) {
+  const badges = {
+    active: `${c.green}active${c.reset}`,
+    closed: `${c.dim}closed${c.reset}`,
+    closing: `${c.yellow}closing${c.reset}`,
+  };
+  return badges[status] || status;
+}
+
 // ─── CLI ────────────────────────────────────────────────────
 const args = process.argv.slice(2);
 const command = args[0];
@@ -832,6 +822,15 @@ switch (command) {
     log(`    ${c.cyan}npx cc-workspace doctor${c.reset}`);
     log(`      Check all components are installed and consistent.`);
     log("");
+    log(`    ${c.cyan}npx cc-workspace session list${c.reset}`);
+    log(`      Show all active sessions and their branches.`);
+    log("");
+    log(`    ${c.cyan}npx cc-workspace session status${c.reset} ${c.dim}<name>${c.reset}`);
+    log(`      Show detailed session info: commits per repo on session branch.`);
+    log("");
+    log(`    ${c.cyan}npx cc-workspace session close${c.reset} ${c.dim}<name>${c.reset}`);
+    log(`      Interactive close: create PRs, delete branches, clean up.`);
+    log("");
     log(`    ${c.cyan}npx cc-workspace version${c.reset}`);
     log(`      Show package and installed versions.`);
     log("");
@@ -845,6 +844,184 @@ switch (command) {
     break;
   }
 
+  case "session": {
+    const subCmd = args[1];
+    const orchDir = findOrchDir();
+    if (!orchDir) {
+      fail("No orchestrator/ found. Run from workspace root or orchestrator/.");
+      process.exit(1);
+    }
+
+    switch (subCmd) {
+      case "list": {
+        log(BANNER_SMALL);
+        step("Active sessions");
+        const sessions = readSessions(orchDir);
+        if (sessions.length === 0) {
+          info(`${c.dim}No sessions found in .sessions/${c.reset}`);
+        } else {
+          for (const s of sessions) {
+            const repoCount = Object.keys(s.repos || {}).length;
+            log(`  ${c.bold}${s.name}${c.reset}  ${sessionStatusBadge(s.status)}  ${c.dim}created: ${s.created}${c.reset}  ${c.dim}repos: ${repoCount}${c.reset}`);
+            for (const [name, repo] of Object.entries(s.repos || {})) {
+              const branchIcon = repo.branch_created ? `${c.green}✓${c.reset}` : `${c.red}✗${c.reset}`;
+              log(`    ${c.dim}├──${c.reset} ${name}  ${repo.session_branch}  ${branchIcon}`);
+            }
+          }
+        }
+        log("");
+        break;
+      }
+
+      case "status": {
+        const sessionName = args[2];
+        if (!sessionName) {
+          fail("Usage: cc-workspace session status <name>");
+          process.exit(1);
+        }
+        log(BANNER_SMALL);
+        const sessionFile = path.join(orchDir, ".sessions", `${sessionName}.json`);
+        if (!fs.existsSync(sessionFile)) {
+          fail(`Session "${sessionName}" not found`);
+          process.exit(1);
+        }
+        const session = JSON.parse(fs.readFileSync(sessionFile, "utf8"));
+        step(`Session: ${session.name}`);
+        log(`  ${c.dim}Status${c.reset}   ${sessionStatusBadge(session.status)}`);
+        log(`  ${c.dim}Created${c.reset}  ${session.created}`);
+        log("");
+
+        for (const [name, repo] of Object.entries(session.repos || {})) {
+          const repoPath = path.resolve(orchDir, repo.path);
+          log(`  ${c.bold}${name}${c.reset} ${c.dim}(${repo.path})${c.reset}`);
+          log(`    source: ${repo.source_branch}  →  session: ${repo.session_branch}`);
+          if (repo.branch_created && fs.existsSync(path.join(repoPath, ".git"))) {
+            try {
+              const commits = execSync(
+                `git -C "${repoPath}" log ${repo.session_branch} --oneline --not ${repo.source_branch} 2>/dev/null || echo "(no commits yet)"`,
+                { encoding: "utf8", timeout: 5000 }
+              ).trim();
+              log(`    ${c.dim}commits:${c.reset}`);
+              for (const line of commits.split("\n").slice(0, 10)) {
+                log(`      ${line}`);
+              }
+            } catch {
+              log(`    ${c.yellow}(could not read commits)${c.reset}`);
+            }
+          }
+          log("");
+        }
+        break;
+      }
+
+      case "close": {
+        const sessionName = args[2];
+        if (!sessionName) {
+          fail("Usage: cc-workspace session close <name>");
+          process.exit(1);
+        }
+        const sessionFile = path.join(orchDir, ".sessions", `${sessionName}.json`);
+        if (!fs.existsSync(sessionFile)) {
+          fail(`Session "${sessionName}" not found`);
+          process.exit(1);
+        }
+        const session = JSON.parse(fs.readFileSync(sessionFile, "utf8"));
+
+        log(BANNER_SMALL);
+        step(`Closing session: ${session.name}`);
+        log("");
+
+        const readline = require("readline");
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const ask = (q) => new Promise(r => rl.question(q, r));
+
+        (async () => {
+          // Step 1: offer to create PRs
+          for (const [name, repo] of Object.entries(session.repos || {})) {
+            if (!repo.branch_created) continue;
+            const repoPath = path.resolve(orchDir, repo.path);
+            const answer = await ask(
+              `  Create PR ${c.cyan}${repo.session_branch}${c.reset} → ${c.cyan}${repo.source_branch}${c.reset} in ${c.bold}${name}${c.reset}? [y/N] `
+            );
+            if (answer.toLowerCase() === "y") {
+              try {
+                const result = execSync(
+                  `cd "${repoPath}" && gh pr create --base "${repo.source_branch}" --head "${repo.session_branch}" --title "${session.name}: ${name}" --body "Session: ${session.name}"`,
+                  { encoding: "utf8", timeout: 30000 }
+                );
+                ok(`PR created: ${result.trim()}`);
+              } catch (e) {
+                fail(`PR creation failed: ${e.stderr || e.message}`);
+              }
+            }
+          }
+
+          // Step 2: offer to delete session branches
+          for (const [name, repo] of Object.entries(session.repos || {})) {
+            if (!repo.branch_created) continue;
+            const repoPath = path.resolve(orchDir, repo.path);
+            // Check for unpushed commits before offering deletion
+            let unpushed = "";
+            try {
+              unpushed = execSync(
+                `git -C "${repoPath}" log "${repo.session_branch}" --oneline --not --remotes 2>/dev/null`,
+                { encoding: "utf8", timeout: 5000 }
+              ).trim();
+            } catch { /* branch may not have remote tracking */ }
+            if (unpushed) {
+              warn(`${name}: ${unpushed.split("\\n").length} unpushed commit(s) on ${repo.session_branch}`);
+            }
+            const answer = await ask(
+              `  Delete branch ${c.cyan}${repo.session_branch}${c.reset} in ${c.bold}${name}${c.reset}?${unpushed ? ` ${c.red}(has unpushed commits)${c.reset}` : ""} [y/N] `
+            );
+            if (answer.toLowerCase() === "y") {
+              try {
+                // Use -D (force) — user already confirmed, branch may not be merged yet
+                execSync(`git -C "${repoPath}" branch -D "${repo.session_branch}"`,
+                  { encoding: "utf8", timeout: 5000 });
+                ok(`Branch deleted in ${name}`);
+              } catch (e) {
+                fail(`Branch deletion failed in ${name}: ${e.stderr || e.message}`);
+              }
+            }
+          }
+
+          // Step 3: offer to delete session JSON
+          const answer = await ask(
+            `  Delete session file ${c.dim}.sessions/${sessionName}.json${c.reset}? [y/N] `
+          );
+          if (answer.toLowerCase() === "y") {
+            fs.unlinkSync(sessionFile);
+            ok("Session file deleted");
+          } else {
+            session.status = "closed";
+            fs.writeFileSync(sessionFile, JSON.stringify(session, null, 2) + "\n");
+            ok("Session marked as closed");
+          }
+
+          rl.close();
+          log("");
+        })();
+        break;
+      }
+
+      default:
+        if (!subCmd) {
+          log(BANNER_SMALL);
+          log(`\n  ${c.bold}Usage:${c.reset}`);
+          log(`    ${c.cyan}cc-workspace session list${c.reset}              ${c.dim}Show active sessions${c.reset}`);
+          log(`    ${c.cyan}cc-workspace session status${c.reset} ${c.dim}<name>${c.reset}    ${c.dim}Detailed session info${c.reset}`);
+          log(`    ${c.cyan}cc-workspace session close${c.reset} ${c.dim}<name>${c.reset}     ${c.dim}Interactive close${c.reset}`);
+          log("");
+        } else {
+          fail(`Unknown session subcommand: ${subCmd}`);
+          log(`  Usage: ${c.cyan}cc-workspace session${c.reset} ${c.dim}list | status <name> | close <name>${c.reset}`);
+          process.exit(1);
+        }
+    }
+    break;
+  }
+
   default: {
     fail(`Unknown command: ${command}`);
     log(`  Run: ${c.cyan}npx cc-workspace --help${c.reset}`);

package/global-skills/agents/implementer.md

@@ -16,14 +16,31 @@ maxTurns: 50
 
 You are a focused implementer. You receive tasks and deliver clean code.
 
+## Git workflow (CRITICAL — do this first)
+You are in a temporary worktree. If you don't commit, YOUR WORK WILL BE LOST.
+
+**CRITICAL**: Do NOT run `git checkout` in the main repo. Do NOT use `git -C ../repo checkout`.
+You are already in an isolated worktree — all git commands run HERE, not in the main repo.
+
+1. **FIRST**: Switch to the session branch inside your worktree:
+   `git checkout session/{name}` (safe — you're in a worktree)
+2. **Verify**: `git branch --show-current` must show `session/{name}`
+3. If checkout fails: `git fetch origin session/{name}` then retry
+4. **Do NOT stay on `worktree-agent-*` branches** — always switch to the session branch
+5. **Commit after each logical unit** — never wait until the end
+6. **Before reporting back**: `git status` must show clean working tree.
+   If anything is uncommitted: COMMIT IT NOW before reporting.
+
 ## Workflow
-1. Read the repo's CLAUDE.md — follow its conventions strictly
-2. Implement the assigned tasks from the plan
-3. Use the **LSP tool** for code navigation (go-to-definition, find-references)
-4. Run existing tests — fix any regressions you introduce
-5. Identify and remove dead code exposed by your changes
-6. Commit on the feature branch with conventional commits
-7. Report back: files changed, tests pass/fail, dead code found, blockers
+1. Check out the session branch (see Git workflow above)
+2. Read the repo's CLAUDE.md — follow its conventions strictly
+3. Implement the assigned tasks from the plan
+4. Use the **LSP tool** for code navigation (go-to-definition, find-references)
+5. Run existing tests — fix any regressions you introduce
+6. Identify and remove dead code exposed by your changes
+7. Commit on the session branch with conventional commits — after each unit, not at the end
+8. Before reporting: `git status` — must be clean. `git log --oneline -5` — include in report
+9. Report back: files changed, tests pass/fail, dead code found, commits (hash+message), blockers
 
 ## Rules
 - Follow existing patterns in the codebase — consistency over preference

package/global-skills/agents/team-lead.md

@@ -61,6 +61,67 @@ On startup, check if `./workspace.md` contains `[UNCONFIGURED]`.
 | **C — Go direct** | Immediate dispatch, no interactive plan |
 | **D — Single-service** | 1 repo, no waves, for targeted fixes |
 
+## Session management
+
+Sessions provide branch isolation when running multiple features in parallel.
+Each session maps to a `session/{name}` branch in each impacted repo.
+
+### On startup: detect active sessions
+After loading workspace.md, scan `./.sessions/` for active session JSON files.
+If active sessions exist, display them:
+> Active sessions: [name1] (repos: api, front), [name2] (repos: api)
+
+### Creating a session (Phase 2.5 — after Plan approval, before Dispatch)
+1. Derive the session name from the feature name (slugified, e.g., `feature-auth`)
+2. Read `workspace.md` for the source branch per repo (Source Branch column)
+3. Identify which repos are impacted by the plan
+4. Write `.sessions/{name}.json`:
+```json
+{
+  "name": "feature-auth",
+  "created": "2026-02-25",
+  "status": "active",
+  "repos": {
+    "api": {
+      "path": "../api",
+      "source_branch": "preprod",
+      "session_branch": "session/feature-auth",
+      "branch_created": true
+    }
+  }
+}
+```
+5. Spawn a Task subagent (with Bash) to create the branches:
+   - `git -C ../[repo] branch session/{name} {source_branch}` for each repo
+   - CRITICAL: use `git branch` (NOT `git checkout -b`) — checkout would
+     disrupt other sessions' working directories
+   - If the branch already exists, verify it and skip creation
+6. Verify branches were created (Task subagent reports back)
+7. Update the session JSON: set `branch_created: true` for each successful branch
+
+### During dispatch
+- Include the session branch in every teammate spawn prompt
+- Teammates use the session branch — they do NOT create their own branches
+- The spawn prompt MUST include these EXACT instructions:
+  ```
+  CRITICAL: Do NOT run `git checkout` in the main repo. Do NOT use `git -C ../repo checkout`.
+  You are in an isolated worktree — all git commands run HERE.
+  1. git checkout session/{name}  (switch to session branch inside your worktree)
+  2. git branch --show-current    (verify: must show session/{name})
+  3. Do NOT stay on worktree-agent-* branches — use the session branch.
+  Branch session/{name} ALREADY EXISTS. ALL commits go on this branch.
+  ```
+
+### During collection
+- Verify commits are on the session branch via Task subagent:
+  `git -C ../[repo] log session/{name} --oneline`
+- If a teammate committed on a different branch, flag it as a blocker
+
+### Session close
+Session close is handled by the CLI: `cc-workspace session close {name}`
+The team-lead does NOT close sessions — the user does via the CLI.
+Close requires user approval before each action (PR, branch delete, JSON delete).
+
 ## Auto-discovery of repos
 
 On startup AND during config:
@@ -102,10 +163,16 @@ Explore subagents are read-only, they do NOT need a worktree.
 ## Commit granularity enforcement
 
 When collecting teammate reports:
+- **FIRST: verify commits exist on the session branch** — spawn a Task subagent (Bash):
+  `git -C ../[repo] log session/{name} --oneline -10`
+  If 0 commits → the teammate forgot to commit. DO NOT accept the report.
+  Re-dispatch with explicit instruction to checkout + commit.
 - **Check commit count vs plan** — the plan defines N commit units, the teammate must have N+ commits
 - **Flag giant commits** — any commit >400 lines gets flagged in the session log
 - **If a teammate made a single commit for all tasks**: ask them to split via SendMessage
   before accepting the wave as complete
+- **If teammate reports "done" but 0 commits**: the worktree was likely cleaned up.
+  Check if the worktree still exists. If lost, re-dispatch entirely.
 - **Progress tracker** in the plan must be updated after each teammate report
 
 ## What you NEVER do
@@ -117,9 +184,12 @@ When collecting teammate reports:
 - Accept a single giant commit covering multiple tasks — enforce atomic commits
 - Let the context grow (compact after each cycle)
 - Launch wave 2 before wave 1 has reported
+- Create branches with `git checkout -b` in repos — always `git branch` (no checkout)
+- Let teammates create their own branches — they use the session branch
 
 ## What you CAN write
 - Plans in `./plans/`
+- Session files in `./.sessions/`
 - `./workspace.md` and `./constitution.md`
 - Any file in your orchestrator/ directory
 

package/global-skills/agents/workspace-init.md

@@ -39,9 +39,10 @@ Check silently (no questions to the user):
 | 4 | `./templates/workspace.template.md` exists | Flag |
 | 5 | `./templates/constitution.template.md` exists | Flag |
 | 6 | `./.claude/settings.json` exists and contains `AGENT_TEAMS` + `SUBAGENT_MODEL` | Regenerate if missing |
-| 7 | `./.claude/hooks/` contains all 11 hooks | List the missing ones |
+| 7 | `./.claude/hooks/` contains all 9 hooks | List the missing ones |
 | 8 | All hooks are executable (`chmod +x`) | Auto-fix |
 | 9 | `./CLAUDE.md` exists | Flag |
+| 10 | `./.sessions/` exists | Create the directory |
 
 ### Phase 2: Global diagnostic
 
@@ -83,10 +84,10 @@ Re-run: npx cc-workspace update --force
 4. Present a summary table to the user:
 
    ```
-   | Repo | Type | CLAUDE.md | .claude/ | Tests | Git clean |
-   |------|------|-----------|----------|-------|-----------|
-   | apidocker | Laravel | ✅ | ✅ hooks:3 | ✅ pest | ✅ |
-   | frontend  | Vue/Quasar | ✅ | ❌ | ✅ vitest | ⚠️ 12 files |
+   | Repo | Type | CLAUDE.md | Source Branch | .claude/ | Tests | Git clean |
+   |------|------|-----------|---------------|----------|-------|-----------|
+   | apidocker | Laravel | ✅ | preprod | ✅ hooks:3 | ✅ pest | ✅ |
+   | frontend  | Vue/Quasar | ✅ | preprod | ❌ | ✅ vitest | ⚠️ 12 files |
    ```
 
 5. Regenerate `./plans/service-profiles.md` with all collected info
@@ -119,6 +120,19 @@ If some repos don't have a `CLAUDE.md`:
 
 ### Phase 4: Interactive configuration
 
+**If `./workspace.md` is already configured** (no `[UNCONFIGURED]`):
+
+Check for missing columns or outdated info:
+1. If the service map is missing the `Source Branch` column:
+   - For each repo, detect the likely source branch:
+     - `git -C ../repo symbolic-ref refs/remotes/origin/HEAD 2>/dev/null` (strip refs/remotes/origin/)
+     - Or check for common branches: `preprod`, `develop`, `main`, `master`
+     - Or read from existing sections (e.g., "Branches de travail" notes)
+   - Present the proposed source branches and ask for confirmation
+   - Add the `Source Branch` column to the existing service map table
+2. If new repos are detected (not in the service map), propose adding them
+3. Update the orchestrator version in the header
+
 **If `./workspace.md` contains `[UNCONFIGURED]`:**
 
 1. Read `./templates/workspace.template.md` — this is the reference structure.
@@ -134,6 +148,10 @@ If some repos don't have a `CLAUDE.md`:
    **Service map section:**
    - Present detected repos with their auto-detected type
    - Pre-fill roles based on CLAUDE.md files read in Phase 3
+   - For each repo, ask the **Source Branch** (the integration branch from which
+     session branches will be created, e.g., `preprod`, `develop`, `main`).
+     Pre-fill by detecting the default branch: `git -C ../repo symbolic-ref refs/remotes/origin/HEAD 2>/dev/null`
+     or fallback to `main`
    - Ask for confirmation + corrections
    - For each service: role in one sentence
 
@@ -175,7 +193,7 @@ Present a summary table:
 ╠═══════════════════════════════════════════════════════╣
 ║                                                         ║
 ║  Orchestrator structure        ✅ OK                    ║
-║  Hooks (11/11)                 ✅ OK                    ║
+║  Hooks (9/9)                   ✅ OK                    ║
 ║  Settings (Agent Teams)        ✅ OK                    ║
 ║  Global components             ✅ OK (or ⚠️ details)   ║
 ║  workspace.md                  ✅ Configured             ║

package/global-skills/cross-service-check/SKILL.md

@@ -19,7 +19,12 @@ Scope: ONLY inter-service alignment. Not code quality, not bugs.
 
 ## Setup
 
-Read `./workspace.md` for the service map.
+1. Read `./workspace.md` for the service map
+2. Check `./.sessions/` for the active session related to the current feature
+   - If a session exists, all checks MUST run against the **session branch**
+     (e.g., `session/feature-auth`), not against `main` or the default branch
+   - Use `git -C ../[repo] show session/{name}:[file]` to read files from the
+     session branch without checking it out
 
 ## Checks (parallel Explore subagents via Task, Haiku)
 

package/global-skills/dispatch-feature/SKILL.md

@@ -88,6 +88,41 @@ vs done per service, visible at a glance.
 
 Independent services go in the same wave. Save. **Present plan, wait for approval.**
 
+## Phase 2.5: Session setup (branch isolation)
+
+After plan approval and before dispatch:
+
+1. Derive session name from feature name (slug: lowercase, hyphens, no spaces)
+2. Read `./workspace.md` — extract the `Source Branch` column for each service
+3. Identify repos impacted by the plan
+4. Write `./.sessions/{session-name}.json`:
+   ```json
+   {
+     "name": "{session-name}",
+     "created": "{date}",
+     "status": "active",
+     "repos": {
+       "{service}": {
+         "path": "../{service}",
+         "source_branch": "{from workspace.md}",
+         "session_branch": "session/{session-name}",
+         "branch_created": false
+       }
+     }
+   }
+   ```
+5. Spawn a **Task subagent with Bash** to create branches in each impacted repo:
+   ```
+   git -C ../[repo] branch session/{name} {source_branch}
+   ```
+   - Use `git branch` — NOT `git checkout -b` (checkout disrupts other sessions)
+   - If the branch already exists, verify it points to the right source and skip
+   - The Task subagent reports success/failure per repo
+6. Update the session JSON: set `branch_created: true` for each successful branch
+
+> **Why a Task subagent?** The team-lead has `disallowedTools: Bash`.
+> Branch creation requires shell access, so it must be delegated.
+
 ## Phase 3: Spawn teammates (Agent Teams)
 
 Use the **Teammate** tool to spawn teammates. Each teammate is an independent
@@ -101,6 +136,8 @@ For EVERY teammate, include in the spawn prompt:
 3. API contract (if applicable)
 4. Instruction to read repo CLAUDE.md first
 5. Instruction to escalate architectural decisions not in the plan
+6. Session branch: `session/{name}` — tell the teammate this branch ALREADY EXISTS,
+   all commits go on it, they must NOT create other branches
 
 See @references/spawn-templates.md for the full templates per service type
 (backend, frontend, infra, explore).
@@ -148,6 +185,9 @@ On each teammate report:
 2. Update the **progress tracker** table (commits done / planned)
 3. Note dead code found
 4. Verify commit count and sizes — flag if a teammate made a single giant commit
+4b. Verify commits are on the session branch (not on a rogue branch):
+    - Spawn a Task subagent (Bash): `git -C ../[repo] log session/{name} --oneline -5`
+    - If teammate committed on a different branch, flag it as a blocker
 5. If a teammate failed → analyze, correct plan, re-dispatch
 6. **Session log** entry: `[HH:MM] teammate-[service]: [status], [N] commits, [N] files, tests [pass/fail]`
 7. If current wave done → launch next wave

package/global-skills/dispatch-feature/references/anti-patterns.md

@@ -18,6 +18,10 @@ Reference file for dispatch-feature. Loaded on-demand when Claude needs reminder
 10. **NEVER keep code details in your context** — summarize to 3 lines in the plan, then compact
 11. **NEVER assume repos are listed in workspace.md** — scan `../` at feature start for
     any new `.git` repos that may have appeared since last configuration
+12. **NEVER let teammates create their own branches** — they must use the session branch
+    (`session/{name}`). The team-lead creates it during Phase 2.5.
+13. **NEVER use `git checkout -b` in repos** — use `git branch {name} {source}` (no checkout).
+    Checkout changes the working directory, which disrupts other sessions running in parallel.
 
 ## Common mistakes to watch for
 
@@ -31,3 +35,8 @@ Reference file for dispatch-feature. Loaded on-demand when Claude needs reminder
 | Giant commit (500+ lines) | PR unreadable, impossible to review | Split into atomic commits (~300 lines max) per logical unit |
 | Single commit at the end | All-or-nothing, no partial rollback | Commit after each logical unit — data, logic, API, tests |
 | Task without commit boundary | Teammate guesses the split | Plan must define commit units per task |
+| Teammate creates own branch | Report shows commits on `feature/xxx` instead of `session/xxx` | Re-dispatch with explicit session branch instruction |
+| `git checkout -b` in repo | Other session's worktree on wrong branch | Always use `git branch` (no checkout) for session branch creation |
+| No session created before dispatch | Branches mixed between parallel sessions | Always run Phase 2.5 before Phase 3 |
+| Teammate reports done with 0 commits | Worktree cleaned up, changes LOST | Verify commits on session branch before accepting report |
+| Teammate didn't checkout session branch | Commits on wrong branch or detached HEAD | Git workflow section must be FIRST in spawn prompt |

package/global-skills/dispatch-feature/references/spawn-templates.md

@@ -11,6 +11,29 @@ Reference file for dispatch-feature. Loaded on-demand, not at skill activation.
 ```
 You are teammate-[service]. Read the CLAUDE.md in your repo first.
 
+## Git workflow (CRITICAL — read first)
+You are working in a temporary worktree. If you don't commit, YOUR WORK WILL BE LOST
+when the worktree is cleaned up.
+
+CRITICAL: Do NOT run `git checkout` in the main repo. Do NOT use `git -C ../repo checkout`.
+You are already in an isolated worktree — all git commands run HERE, not in the main repo.
+
+1. FIRST THING: Switch to the session branch inside your worktree:
+   git checkout session/{session-name}
+   (This is safe — you are in a worktree, not the main repo)
+2. Verify you are on the right branch:
+   git branch --show-current  (must show: session/{session-name})
+3. If checkout fails with "did not match any file(s)":
+   git fetch origin session/{session-name}
+   git checkout session/{session-name}
+4. Commit AFTER EACH logical unit — do NOT wait until the end
+5. Before reporting back, verify ALL changes are committed:
+   git status  (must show: nothing to commit, working tree clean)
+6. If git status shows uncommitted changes when you're done: COMMIT THEM NOW
+
+Branch `session/{session-name}` ALREADY EXISTS. Do NOT create other branches.
+Do NOT create branches named worktree-agent-* — use the session branch.
+
 ## Constitution (non-negotiable)
 [paste all rules from your workspace's constitution.md]
 
@@ -30,7 +53,8 @@ You are teammate-[service]. Read the CLAUDE.md in your repo first.
 6. **Atomic commits** — follow the commit plan below
 7. If you hit an architectural decision NOT covered by the plan: STOP and
    report the dilemma instead of guessing
-8. Report back: files created/modified, tests pass/fail, dead code found,
+8. **Before reporting back**: run `git status` — if anything is uncommitted, commit it NOW
+9. Report back: files created/modified, tests pass/fail, dead code found,
    commits made (hash + message), blockers
 
 ## Commit strategy (mandatory)
@@ -43,7 +67,6 @@ You are teammate-[service]. Read the CLAUDE.md in your repo first.
 - **Commit message format**: `feat(domain): description` or `fix(domain): description`
 - **Each commit must compile and pass tests** — no broken intermediate states
 - **Commit as you go** — do NOT accumulate all changes for a single final commit
-- Branch: `feature/[name]` — create it on your first commit
 ```
 
 ## Frontend teammate spawn template
@@ -51,6 +74,29 @@ You are teammate-[service]. Read the CLAUDE.md in your repo first.
 ```
 You are teammate-[service]. Read the CLAUDE.md in your repo first.
 
+## Git workflow (CRITICAL — read first)
+You are working in a temporary worktree. If you don't commit, YOUR WORK WILL BE LOST
+when the worktree is cleaned up.
+
+CRITICAL: Do NOT run `git checkout` in the main repo. Do NOT use `git -C ../repo checkout`.
+You are already in an isolated worktree — all git commands run HERE, not in the main repo.
+
+1. FIRST THING: Switch to the session branch inside your worktree:
+   git checkout session/{session-name}
+   (This is safe — you are in a worktree, not the main repo)
+2. Verify you are on the right branch:
+   git branch --show-current  (must show: session/{session-name})
+3. If checkout fails with "did not match any file(s)":
+   git fetch origin session/{session-name}
+   git checkout session/{session-name}
+4. Commit AFTER EACH logical unit — do NOT wait until the end
+5. Before reporting back, verify ALL changes are committed:
+   git status  (must show: nothing to commit, working tree clean)
+6. If git status shows uncommitted changes when you're done: COMMIT THEM NOW
+
+Branch `session/{session-name}` ALREADY EXISTS. Do NOT create other branches.
+Do NOT create branches named worktree-agent-* — use the session branch.
+
 ## Constitution (non-negotiable)
 [paste all rules from your workspace's constitution.md]
 
@@ -72,8 +118,9 @@ You are teammate-[service]. Read the CLAUDE.md in your repo first.
 6. List any dead code (unused components, composables, store actions, CSS)
 7. **Atomic commits** — follow the commit plan below
 8. If you hit an architectural decision NOT covered by the plan: STOP and escalate
-9. Report back: files created/modified, tests pass/fail, dead code found,
-   UX compliance, commits made (hash + message), blockers
+9. **Before reporting back**: run `git status` — if anything is uncommitted, commit it NOW
+10. Report back: files created/modified, tests pass/fail, dead code found,
+    UX compliance, commits made (hash + message), blockers
 
 ## Commit strategy (mandatory)
 - **One commit per logical unit** — each task = one commit minimum
@@ -86,7 +133,6 @@ You are teammate-[service]. Read the CLAUDE.md in your repo first.
 - **Commit message format**: `feat(domain): description` or `fix(domain): description`
 - **Each commit must compile and pass tests** — no broken intermediate states
 - **Commit as you go** — do NOT accumulate all changes for a single final commit
-- Branch: `feature/[name]` — create it on your first commit
 ```
 
 ## Infra/Config teammate spawn template
@@ -94,6 +140,29 @@ You are teammate-[service]. Read the CLAUDE.md in your repo first.
 ```
 You are teammate-[service]. Read the CLAUDE.md in your repo first.
 
+## Git workflow (CRITICAL — read first)
+You are working in a temporary worktree. If you don't commit, YOUR WORK WILL BE LOST
+when the worktree is cleaned up.
+
+CRITICAL: Do NOT run `git checkout` in the main repo. Do NOT use `git -C ../repo checkout`.
+You are already in an isolated worktree — all git commands run HERE, not in the main repo.
+
+1. FIRST THING: Switch to the session branch inside your worktree:
+   git checkout session/{session-name}
+   (This is safe — you are in a worktree, not the main repo)
+2. Verify you are on the right branch:
+   git branch --show-current  (must show: session/{session-name})
+3. If checkout fails with "did not match any file(s)":
+   git fetch origin session/{session-name}
+   git checkout session/{session-name}
+4. Commit AFTER EACH logical unit — do NOT wait until the end
+5. Before reporting back, verify ALL changes are committed:
+   git status  (must show: nothing to commit, working tree clean)
+6. If git status shows uncommitted changes when you're done: COMMIT THEM NOW
+
+Branch `session/{session-name}` ALREADY EXISTS. Do NOT create other branches.
+Do NOT create branches named worktree-agent-* — use the session branch.
+
 ## Constitution (non-negotiable)
 [paste all rules from your workspace's constitution.md]
 
@@ -108,9 +177,9 @@ You are teammate-[service]. Read the CLAUDE.md in your repo first.
 5. **Atomic commits** — one commit per logical config change
 6. Commit message format: `chore(service): description`
 7. If you hit an architectural decision NOT covered by the plan: STOP and escalate
-8. Report back: files modified, consistency check results,
+8. **Before reporting back**: run `git status` — if anything is uncommitted, commit it NOW
+9. Report back: files modified, consistency check results,
    commits made (hash + message), blockers
-- Branch: `feature/[name]`
 ```
 
 ## Explore/Haiku subagent template (read-only)
@@ -134,3 +203,6 @@ When a teammate reports back:
 - **Architectural decision not in plan** (blocking): STOP the wave, escalate to user
 - **No report after extended time**: send a status request via SendMessage
 - **Max re-dispatches per teammate per wave**: 2. After that, escalate to user.
+- **0 commits reported**: the teammate likely forgot to commit. Check the worktree
+  with a Task subagent before accepting the report. If changes exist uncommitted,
+  re-dispatch with explicit instruction to commit.

package/global-skills/hooks/guard-session-checkout.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# guard-session-checkout.sh
+# PreToolUse hook (matcher: Bash): blocks `git checkout session/` in main repos.
+# Session branches must only be checked out INSIDE worktrees, never in main repos
+# (doing so disrupts other parallel sessions).
+# v4.2.1: hard guardrail — this hook BLOCKS (exit 0 + deny JSON).
+set -euo pipefail
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null) || true
+
+[ -z "$COMMAND" ] && exit 0
+
+# Only care about git checkout/switch targeting session/ branches
+if ! echo "$COMMAND" | grep -qE 'git\s+(checkout|switch)\s+.*session/' 2>/dev/null; then
+    exit 0
+fi
+
+# Pattern 1: git -C <repo> checkout session/ — always wrong (targets main repo from outside)
+if echo "$COMMAND" | grep -qE 'git\s+-C\s+\S+\s+(checkout|switch)\s+.*session/' 2>/dev/null; then
+    printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"BLOCKED: git checkout session/ with -C targets the main repo directly. This disrupts other parallel sessions. You are in a worktree — run `git checkout session/{name}` from INSIDE your worktree (without -C) instead. If you are not in a worktree, something is wrong with your isolation setup."}}'
+    exit 0
+fi
+
+# Pattern 2: git checkout session/ without -C — check if we are in a main repo
+# In a worktree, .git is a FILE (gitdir pointer). In a main repo, .git is a DIRECTORY.
+if [ -d ".git" ] && [ ! -f ".git" ]; then
+    printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"BLOCKED: git checkout session/ detected in a main repo (not a worktree). Checking out a session branch in the main repo disrupts other parallel sessions. You must work in an isolated worktree. If you are a teammate, your worktree should already exist — run `git checkout session/{name}` from inside it."}}'
+    exit 0
+fi
+
+# We are in a worktree (.git is a file) — allow the checkout
+exit 0

package/global-skills/hooks/session-start-context.sh

@@ -36,6 +36,24 @@ if [ -d "$PROJECT_DIR/plans" ]; then
     fi
 fi
 
+# Detect active sessions
+SESSIONS_DIR="$PROJECT_DIR/.sessions"
+if [ -d "$SESSIONS_DIR" ]; then
+    ACTIVE_SESSIONS=""
+    for session_file in "$SESSIONS_DIR"/*.json; do
+        [ -f "$session_file" ] || continue
+        SESSION_NAME=$(jq -r '.name // empty' "$session_file" 2>/dev/null) || continue
+        SESSION_STATUS=$(jq -r '.status // "unknown"' "$session_file" 2>/dev/null) || continue
+        [ "$SESSION_STATUS" != "active" ] && continue
+        SESSION_REPOS=$(jq -r '[.repos | keys[]] | join(", ")' "$session_file" 2>/dev/null) || SESSION_REPOS="?"
+        ACTIVE_SESSIONS+="  - $SESSION_NAME (repos: $SESSION_REPOS)\n"
+    done
+    if [ -n "$ACTIVE_SESSIONS" ]; then
+        OUTPUT+="[Session context] Active sessions:\n$ACTIVE_SESSIONS"
+        OUTPUT+="Session branches are already created. Teammates must use these branches.\n\n"
+    fi
+fi
+
 # Check workspace.md exists
 if [ ! -f "$PROJECT_DIR/workspace.md" ]; then
     OUTPUT+="[WARNING] No workspace.md found. Run setup-workspace.sh first.\n"

package/global-skills/hooks/validate-spawn-prompt.sh

@@ -67,6 +67,14 @@ if ! echo "$PROMPT" | grep -qiE '(escalat|STOP and report|STOP and escalate|repo
     WARNINGS+="- Missing escalation instruction. Include: 'If you hit an architectural decision NOT covered by the plan: STOP and escalate.'\n"
 fi
 
+# Check 7: Session branch instruction (if sessions exist)
+SESSIONS_DIR="${CLAUDE_PROJECT_DIR:-.}/.sessions"
+if [ -d "$SESSIONS_DIR" ] && ls "$SESSIONS_DIR"/*.json >/dev/null 2>&1; then
+    if ! echo "$PROMPT" | grep -qiE '(session/|session branch|ALREADY EXISTS.*branch)' 2>/dev/null; then
+        WARNINGS+="- Active sessions exist but no session branch found in spawn prompt. Include the session branch instruction.\n"
+    fi
+fi
+
 # Report — ALL checks are warnings only (v4.0)
 ISSUES=""
 [ -n "$BLOCKERS" ] && ISSUES+="$BLOCKERS"

package/global-skills/merge-prep/SKILL.md

@@ -18,9 +18,12 @@ You prepare the merge. You do NOT merge. You produce a merge readiness report.
 
 ## Phase 1: Collect branch info
 
-1. Read `./workspace.md` for the service map
+1. Read `./workspace.md` for the service map (including Source Branch column)
 2. Read `./plans/{feature-name}.md` for the active plan
-3. For each service with status ✅, identify the feature branch name
+3. Check `.sessions/` for the session associated with this feature
+   - If a session exists, use `session/{name}` as the branch name
+   - Use the session's `source_branch` as the merge target (not hardcoded `main`)
+4. For each service with status ✅, identify the session branch name
 
 ## Phase 2: Conflict detection
 
@@ -38,7 +41,7 @@ For lightweight read-only cross-checks, spawn Explore subagents (Task, Haiku).
 For each service, generate a PR summary:
 
 ```markdown
-### [service] — PR: feature/[name] → [target]
+### [service] — PR: session/[name] → [source_branch]
 
 **Changes**: [N] files modified, [M] files created, [D] files deleted
 
@@ -72,7 +75,7 @@ Write to `./plans/{feature-name}.md`:
 ### Merge readiness
 | Service | Branch | Up-to-date | Conflicts | Tests | Ready |
 |---------|--------|-----------|-----------|-------|-------|
-| [name] | feature/[x] | ✅/❌ | none/[list] | ✅/❌ | ✅/❌ |
+| [name] | session/[x] | ✅/❌ | none/[list] | ✅/❌ | ✅/❌ |
 
 ### Merge order
 1. [service] — [branch] → [target]

package/global-skills/refresh-profiles/SKILL.md

@@ -13,10 +13,10 @@ allowed-tools: Read, Write, Glob, Grep
 
 # Refresh Service Profiles
 
-1. Read `./workspace.md` to get the list of repos and their paths
+1. Read `./workspace.md` to get the list of repos, their paths, and their **source branches**
 2. For each repo listed, read its CLAUDE.md
-3. Extract per repo: stack, patterns, auth, tests, conventions, special notes
-4. Write result to `./plans/service-profiles.md`
+3. Extract per repo: stack, patterns, auth, tests, conventions, source branch, special notes
+4. Write result to `./plans/service-profiles.md` — include the source branch per repo
 5. Add today's date in the header
 
 If a repo doesn't exist or has no CLAUDE.md, mark it as "[not found]".

package/global-skills/templates/workspace.template.md

@@ -8,9 +8,11 @@
 
 ## Service map
 <!-- Auto-generated from sibling repo scan. Review and add descriptions. -->
-| Service | Repo | Type | CLAUDE.md | Description |
-|---------|------|------|-----------|-------------|
+| Service | Repo | Type | CLAUDE.md | Source Branch | Description |
+|---------|------|------|-----------|---------------|-------------|
 <!-- [AUTO_DISCOVERED_REPOS] -->
+<!-- Source Branch: the integration branch per repo (e.g., preprod, develop, main).
+     Session branches are created from this branch. Never push directly to it. -->
 
 ## Inter-service relationships
 <!-- Describe the request flow between services -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-workspace",
-  "version": "4.1.4",
+  "version": "4.2.1",
   "description": "Claude Code multi-workspace orchestrator — skills, hooks, agents, and templates for multi-service projects",
   "bin": {
     "cc-workspace": "./bin/cli.js"