cc-workspace 4.7.0 → 5.2.1

package/global-skills/e2e-validator/references/container-strategies.md

@@ -1,25 +1,30 @@
 # Container Strategies — E2E Validator Reference
 
+## Key principle (v5)
+
+**No worktrees.** The e2e-validator works directly on repos checked out at the correct branch
+(merged source branch or session branch). Build contexts point to `../{repo}` directly.
+
 ## Overlay strategy (preferred — repos have docker-compose)
 
 When repos already have `docker-compose.yml`, generate an **overlay** file that:
 - Creates a shared e2e network
 - Overrides env vars for test isolation
 - Adds health checks if missing
-- Maps worktree paths as build contexts
+- Uses `../{repo}` as build context (no /tmp/ paths)
 
 ### Template: docker-compose.e2e.yml (overlay)
 
 ```yaml
 # E2E overlay — use with: docker compose -f ../repo/docker-compose.yml -f ./e2e/docker-compose.e2e.yml up
 # Generated by e2e-validator agent
+# Ports: check e2e-config.md for assigned ports — verify they are free before starting
 
 networks:
   e2e:
     driver: bridge
 
 services:
-  # Override each service to join the e2e network and use test env
   api:
     networks:
       - e2e
@@ -62,26 +67,43 @@ services:
       - /var/lib/postgresql/data  # RAM disk for speed
 ```
 
-### Worktree build context override
-
-When testing session branches, override the build context to point to worktrees:
+### Build context — always point to repo directory
 
 ```yaml
 services:
   api:
     build:
-      context: /tmp/e2e-api
+      context: ../api        # repo at current checked-out branch (merged or session)
       dockerfile: Dockerfile
   frontend:
     build:
-      context: /tmp/e2e-frontend
+      context: ../frontend
       dockerfile: Dockerfile
 ```
 
+**Never use /tmp/ paths.** The e2e-validator checks out the correct branch directly in the repo.
+
 ## Standalone strategy (repos have NO docker-compose)
 
 Generate a complete `docker-compose.e2e.yml` from scratch.
 
+### Port assignment
+
+Assign ports in `e2e-config.md` and check they are free before starting.
+Prefer non-standard ports to avoid conflicts with local dev servers:
+
+| Service type | Default E2E port |
+|---|---|
+| PHP/Laravel API | 18000 |
+| Node.js API | 13000 |
+| Vue/Quasar frontend | 19000 |
+| React/Next frontend | 13001 |
+| PostgreSQL | 15432 |
+| MySQL | 13306 |
+| Redis | 16379 |
+
+Using non-standard ports reduces conflicts with local dev environments.
+
 ### Per-stack templates
 
 #### PHP/Laravel
@@ -89,10 +111,10 @@ Generate a complete `docker-compose.e2e.yml` from scratch.
 services:
   api:
     build:
-      context: /tmp/e2e-api
+      context: ../api
       dockerfile: Dockerfile
     ports:
-      - "8000:8000"
+      - "18000:8000"
     environment:
       - APP_ENV=testing
       - APP_KEY=${APP_KEY}
@@ -121,9 +143,9 @@ services:
 services:
   api:
     build:
-      context: /tmp/e2e-api
+      context: ../api
     ports:
-      - "3000:3000"
+      - "13000:3000"
     environment:
       - NODE_ENV=test
       - DATABASE_URL=postgresql://test:test@db:5432/app_test
@@ -143,11 +165,11 @@ services:
 services:
   frontend:
     build:
-      context: /tmp/e2e-frontend
+      context: ../frontend
     ports:
-      - "9000:9000"
+      - "19000:9000"
     environment:
-      - VITE_API_URL=http://localhost:8000
+      - VITE_API_URL=http://localhost:18000
     healthcheck:
       test: ["CMD", "curl", "-sf", "http://localhost:9000"]
       interval: 5s
@@ -162,11 +184,11 @@ services:
 services:
   frontend:
     build:
-      context: /tmp/e2e-frontend
+      context: ../frontend
     ports:
-      - "3000:3000"
+      - "13001:3000"
     environment:
-      - NEXT_PUBLIC_API_URL=http://localhost:8000
+      - NEXT_PUBLIC_API_URL=http://localhost:13000
     healthcheck:
       test: ["CMD", "curl", "-sf", "http://localhost:3000"]
       interval: 5s
@@ -180,9 +202,9 @@ services:
 services:
   api:
     build:
-      context: /tmp/e2e-api
+      context: ../api
     ports:
-      - "8000:8000"
+      - "18000:8000"
     environment:
       - DATABASE_URL=postgresql://test:test@db:5432/app_test
       - ENVIRONMENT=testing
@@ -203,9 +225,9 @@ services:
 services:
   api:
     build:
-      context: /tmp/e2e-api
+      context: ../api
     ports:
-      - "8080:8080"
+      - "18080:8080"
     environment:
       - DATABASE_URL=postgresql://test:test@db:5432/app_test
       - ENV=test
@@ -230,6 +252,8 @@ services:
       - POSTGRES_DB=app_test
       - POSTGRES_USER=test
       - POSTGRES_PASSWORD=test
+    ports:
+      - "15432:5432"
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U test"]
       interval: 3s
@@ -249,6 +273,8 @@ services:
       - MYSQL_USER=test
       - MYSQL_PASSWORD=test
       - MYSQL_ROOT_PASSWORD=root
+    ports:
+      - "13306:3306"
     healthcheck:
       test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
       interval: 3s
@@ -263,6 +289,8 @@ services:
 ```yaml
   redis:
     image: redis:7-alpine
+    ports:
+      - "16379:6379"
     healthcheck:
       test: ["CMD", "redis-cli", "ping"]
       interval: 3s
@@ -277,6 +305,8 @@ services:
     image: mongo:7
     environment:
       - MONGO_INITDB_DATABASE=app_test
+    ports:
+      - "127017:27017"
     healthcheck:
       test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
       interval: 3s
@@ -289,11 +319,12 @@ services:
 
 ## Startup sequence
 
-Always start in dependency order:
+Always start in dependency order with global timeout (10 minutes max):
 1. Databases (db, redis, mongo) — wait for healthy
 2. Backend services (api) — wait for healthy
 3. Frontend services — wait for healthy
-4. Run tests
+4. Seed test data if seeder exists
+5. Run tests
 
 ## Teardown
 
@@ -302,3 +333,4 @@ docker compose -f ./e2e/docker-compose.e2e.yml down -v --remove-orphans
 ```
 
 Always use `-v` to remove test volumes and `--remove-orphans` for cleanup.
+No worktree removal needed — branches are restored via `git checkout` only.

package/global-skills/hooks/orphan-cleanup.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# orphan-cleanup.sh
+# SessionStart hook (phase 1): cleans ONLY orphaned worktrees.
+# v5.0: Active session worktrees (/tmp/{repo}-{session-name}/) are NEVER cleaned here.
+#       Only truly orphaned worktrees (no matching session JSON) are removed.
+# Stdout on exit 0 is added as context visible to Claude.
+set -euo pipefail
+
+cat > /dev/null
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+SESSIONS_DIR="$PROJECT_DIR/.sessions"
+ORPHAN_COUNT=0
+
+shopt -s nullglob
+for wt in /tmp/*-session-* /tmp/e2e-*; do
+    [ -d "$wt" ] || continue
+
+    # Check if this worktree belongs to an active session
+    IS_ACTIVE_SESSION=0
+    if [ -d "$SESSIONS_DIR" ]; then
+        for session_file in "$SESSIONS_DIR"/*.json; do
+            [ -f "$session_file" ] || continue
+            SESSION_STATUS=$(jq -r '.status // "unknown"' "$session_file" 2>/dev/null) || continue
+            [ "$SESSION_STATUS" != "active" ] && continue
+            if jq -r '.repos[].worktree_path // empty' "$session_file" 2>/dev/null | grep -qF "$wt"; then
+                IS_ACTIVE_SESSION=1
+                break
+            fi
+        done
+    fi
+
+    # Skip active session worktrees — they persist until session close
+    [ "$IS_ACTIVE_SESSION" -eq 1 ] && continue
+
+    # Check if registered with a repo
+    REPO_FOUND=0
+    PARENT_DIR="$(cd "$PROJECT_DIR/.." 2>/dev/null && pwd)" || continue
+    for repo_dir in "$PARENT_DIR"/*/; do
+        [ -d "$repo_dir/.git" ] || continue
+        if git -C "$repo_dir" worktree list 2>/dev/null | grep -q "$wt"; then
+            if [ ! -f "$wt/.git" ]; then
+                git -C "$repo_dir" worktree remove "$wt" --force 2>/dev/null && ORPHAN_COUNT=$((ORPHAN_COUNT + 1))
+                REPO_FOUND=1
+                break
+            fi
+            REPO_FOUND=1
+            break
+        fi
+    done
+
+    if [ "$REPO_FOUND" -eq 0 ] && { [ -d "$wt/.git" ] || [ -f "$wt/.git" ]; }; then
+        rm -rf "$wt" 2>/dev/null && ORPHAN_COUNT=$((ORPHAN_COUNT + 1))
+    fi
+done
+
+if [ "$ORPHAN_COUNT" -gt 0 ]; then
+    echo "[Cleanup] Removed $ORPHAN_COUNT orphaned worktree(s) from /tmp/ (no matching active session)."
+fi
+
+exit 0

package/global-skills/hooks/permission-auto-approve.sh

@@ -1,16 +1,73 @@
 #!/usr/bin/env bash
 # permission-auto-approve.sh
-# PermissionRequest hook: auto-approves Read/Glob/Grep to reduce friction.
+# PermissionRequest hook: auto-approves Read/Glob/Grep and safe git/bash operations
+# for the orchestrator (Opus) to reduce friction on exploration and git management.
 # Uses hookSpecificOutput JSON with decision.behavior: "allow".
+#
+# Security: compound commands (&&, ||, ;, |, backticks, $()) are NEVER auto-approved.
+# Only single, known-safe commands get auto-approval.
 set -euo pipefail
 
 INPUT=$(cat)
 TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null) || true
 
+ALLOW_JSON='{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow","toolNames":["Bash"]}}}'
+ALLOW_READ='{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow","toolNames":["Read","Glob","Grep"]}}}'
+
+# Auto-approve read-only tools
 if echo "$TOOL_NAME" | grep -qE '^(Read|Glob|Grep)$'; then
-    cat << 'EOF'
-{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow","toolNames":["Read","Glob","Grep"]}}}
-EOF
+    echo "$ALLOW_READ"
+    exit 0
+fi
+
+# Auto-approve Bash for safe git operations and test/typecheck commands in worktrees
+if [ "$TOOL_NAME" = "Bash" ]; then
+    COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null) || true
+
+    # SECURITY: reject compound commands — never auto-approve chained operations
+    # This prevents `git branch session/x && rm -rf /` style bypasses
+    # Exception: `cd /tmp/... && <safe-test-command>` is a legitimate micro-QA pattern
+    if echo "$COMMAND" | grep -qE '(&&|\|\||[;|]|`|\$\()'; then
+        # Allow: cd /tmp/{worktree} && {test-command}
+        if echo "$COMMAND" | grep -qE '^\s*cd\s+(/private)?/tmp/[a-zA-Z][a-zA-Z0-9_-]+\s+&&\s+(npm run (typecheck|test|lint)|php artisan test|go test|pytest|npx vitest|npx jest|yarn test|pnpm test)\b'; then
+            echo "$ALLOW_JSON"
+            exit 0
+        fi
+        # All other compound commands — do not auto-approve
+        exit 0
+    fi
+
+    # Safe git read operations (handles: git, git --no-pager, git -c key=val, git -C path)
+    if echo "$COMMAND" | grep -qE '^\s*git\s+(--no-pager\s+|(-[cC]\s+\S+\s+))*(log|status|diff|branch --list|branch --show-current|worktree list|show|rev-parse)\b'; then
+        echo "$ALLOW_JSON"
+        exit 0
+    fi
+
+    # Safe git branch creation (no checkout) — handles -C path prefix
+    # Only session/ prefixed branches
+    if echo "$COMMAND" | grep -qE '^\s*git\s+(--no-pager\s+|(-[cC]\s+\S+\s+))*branch\s+session/'; then
+        echo "$ALLOW_JSON"
+        exit 0
+    fi
+
+    # Safe git worktree add for session worktrees in /tmp/
+    if echo "$COMMAND" | grep -qE '^\s*git\s+((-[cC]\s+\S+\s+))*worktree\s+add\s+/tmp/'; then
+        echo "$ALLOW_JSON"
+        exit 0
+    fi
+
+    # Safe typecheck/test commands in /tmp/ worktrees (micro-QA)
+    # Compound check above already rejected chained commands
+    if echo "$COMMAND" | grep -qE '^\s*cd\s+(/private)?/tmp/[a-zA-Z]'; then
+        echo "$ALLOW_JSON"
+        exit 0
+    fi
+
+    # Safe git diff for debug artifact check in /tmp/ worktrees
+    if echo "$COMMAND" | grep -qE '^\s*git\s+-C\s+(/private)?/tmp/\S+\s+diff\b'; then
+        echo "$ALLOW_JSON"
+        exit 0
+    fi
 fi
 
 exit 0

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

@@ -1,46 +1,16 @@
 #!/usr/bin/env bash
 # session-start-context.sh
-# SessionStart hook: injects active plan context, repo status, and cleans orphan worktrees.
+# SessionStart hook (phase 2): injects active plan context, repo status, session info.
+# Orphan worktree cleanup is handled by orphan-cleanup.sh (separate hook).
 # Stdout on exit 0 is added as context visible to Claude.
 set -euo pipefail
 
 cat > /dev/null
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+SESSIONS_DIR="$PROJECT_DIR/.sessions"
 OUTPUT=""
 
-# ── Orphan worktree cleanup ──────────────────────────────────
-# Clean /tmp/ worktrees that were left behind by crashed implementers.
-# These are safe to remove: they're temporary by design.
-ORPHAN_COUNT=0
-for wt in /tmp/*-session-* /tmp/e2e-* 2>/dev/null; do
-    [ -d "$wt" ] || continue
-    # Check if the worktree is registered with any repo
-    REPO_FOUND=0
-    PARENT_DIR="$(cd "$PROJECT_DIR/.." 2>/dev/null && pwd)" || continue
-    for repo_dir in "$PARENT_DIR"/*/; do
-        [ -d "$repo_dir/.git" ] || continue
-        if git -C "$repo_dir" worktree list 2>/dev/null | grep -q "$wt"; then
-            # Worktree is registered — check if it's stale (no git lock, no recent activity)
-            if [ ! -f "$wt/.git" ]; then
-                # Not a valid worktree anymore — remove registration
-                git -C "$repo_dir" worktree remove "$wt" --force 2>/dev/null && ORPHAN_COUNT=$((ORPHAN_COUNT + 1))
-                REPO_FOUND=1
-                break
-            fi
-            REPO_FOUND=1
-            break
-        fi
-    done
-    if [ "$REPO_FOUND" -eq 0 ] && [ -d "$wt/.git" ] || [ -f "$wt/.git" ]; then
-        # Unregistered worktree directory — likely a crash remnant. Remove it.
-        rm -rf "$wt" 2>/dev/null && ORPHAN_COUNT=$((ORPHAN_COUNT + 1))
-    fi
-done
-if [ "$ORPHAN_COUNT" -gt 0 ]; then
-    OUTPUT+="[Cleanup] Removed $ORPHAN_COUNT orphan worktree(s) from /tmp/.\n"
-fi
-
-# ── Active plans ─────────────────────────────────────────────
+# ── Active plans ─────────────────────────────────────────────────────────────
 if [ -d "$PROJECT_DIR/plans" ]; then
     ACTIVE_PLANS=$(find "$PROJECT_DIR/plans" -name '*.md' \
         ! -name '_TEMPLATE.md' \
@@ -49,26 +19,19 @@ if [ -d "$PROJECT_DIR/plans" ]; then
         | sort | tail -5)
 
     if [ -n "$ACTIVE_PLANS" ]; then
-        FIRST_PLAN=""
         OUTPUT+="[Session context] Active plans with pending tasks:\n"
         while IFS= read -r plan; do
             PLAN_NAME=$(basename "$plan")
-            [ -z "$FIRST_PLAN" ] && FIRST_PLAN="$PLAN_NAME"
             TODO=$(grep -c '⏳' "$plan" 2>/dev/null || echo "0")
             WIP=$(grep -c '🔄' "$plan" 2>/dev/null || echo "0")
             DONE=$(grep -c '✅' "$plan" 2>/dev/null || echo "0")
             OUTPUT+="  - $PLAN_NAME (⏳ $TODO pending, 🔄 $WIP in progress, ✅ $DONE done)\n"
         done <<< "$ACTIVE_PLANS"
         OUTPUT+="\nRead these plans to resume where you left off.\n"
-
-        if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "$FIRST_PLAN" ]; then
-            echo "ACTIVE_PLAN=$FIRST_PLAN" >> "$CLAUDE_ENV_FILE"
-        fi
     fi
 fi
 
-# ── Active sessions ──────────────────────────────────────────
-SESSIONS_DIR="$PROJECT_DIR/.sessions"
+# ── Active sessions ───────────────────────────────────────────────────────────
 if [ -d "$SESSIONS_DIR" ]; then
     ACTIVE_SESSIONS=""
     for session_file in "$SESSIONS_DIR"/*.json; do
@@ -81,16 +44,16 @@ if [ -d "$SESSIONS_DIR" ]; then
     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"
+        OUTPUT+="Session branches and worktrees are already set up. Teammates use worktree_path from session JSON.\n\n"
     fi
 fi
 
-# ── Workspace check ──────────────────────────────────────────
+# ── Workspace check ───────────────────────────────────────────────────────────
 if [ ! -f "$PROJECT_DIR/workspace.md" ]; then
-    OUTPUT+="[WARNING] No workspace.md found. Run setup-workspace.sh first.\n"
+    OUTPUT+="[WARNING] No workspace.md found. Run: claude --agent workspace-init\n"
 fi
 
-# ── First-session detection ──────────────────────────────────
+# ── First-session detection ───────────────────────────────────────────────────
 if [ -f "$PROJECT_DIR/workspace.md" ]; then
     if grep -q '\[UNCONFIGURED\]' "$PROJECT_DIR/workspace.md" 2>/dev/null; then
         OUTPUT+="[FIRST SESSION] workspace.md is not yet configured. Run: claude --agent workspace-init\n"
@@ -108,7 +71,7 @@ if [ -f "$PROJECT_DIR/workspace.md" ]; then
     fi
 fi
 
-# ── Auto-discovery: new repos ────────────────────────────────
+# ── Auto-discovery: new repos ─────────────────────────────────────────────────
 if [ -f "$PROJECT_DIR/workspace.md" ] && ! grep -q '\[UNCONFIGURED\]' "$PROJECT_DIR/workspace.md" 2>/dev/null; then
     PARENT_DIR="$(cd "$PROJECT_DIR/.." 2>/dev/null && pwd)"
     NEW_REPOS=""