prizmkit 1.0.45 → 1.0.58

package/bundled/dev-pipeline/run.sh

@@ -28,8 +28,8 @@ set -euo pipefail
 #   LOG_RETENTION_DAYS    Delete logs older than N days (default: 14)
 #   LOG_MAX_TOTAL_MB      Keep total logs under N MB via oldest-first cleanup (default: 1024)
 #   PIPELINE_MODE         Override mode for all features: lite|standard|full|self-evolve (used by daemon)
-#   USE_WORKTREE          Enable git worktree isolation per session (default: 1). Set to 0 to disable.
-#   AUTO_PUSH             Auto-push to remote after successful worktree merge (default: 0). Set to 1 to enable.
+#   DEV_BRANCH            Custom dev branch name (default: auto-generated dev/pipeline-{run_id})
+#   AUTO_PUSH             Auto-push to remote after successful feature (default: 0). Set to 1 to enable.
 # ============================================================
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -46,7 +46,7 @@ LOG_RETENTION_DAYS=${LOG_RETENTION_DAYS:-14}
 LOG_MAX_TOTAL_MB=${LOG_MAX_TOTAL_MB:-1024}
 VERBOSE=${VERBOSE:-0}
 MODEL=${MODEL:-""}
-USE_WORKTREE=${USE_WORKTREE:-1}
+DEV_BRANCH=${DEV_BRANCH:-""}
 AUTO_PUSH=${AUTO_PUSH:-0}
 
 # Source shared common helpers (CLI/platform detection + logs + deps)
@@ -56,8 +56,8 @@ prizm_detect_cli_and_platform
 # Source shared heartbeat library
 source "$SCRIPT_DIR/lib/heartbeat.sh"
 
-# Source shared worktree library
-source "$SCRIPT_DIR/lib/worktree.sh"
+# Source shared branch library
+source "$SCRIPT_DIR/lib/branch.sh"
 
 # Detect stream-json support
 detect_stream_json_support "$CLI_CMD"
@@ -65,9 +65,9 @@ detect_stream_json_support "$CLI_CMD"
 # Feature list path (set in main, used by cleanup trap)
 FEATURE_LIST=""
 
-# Active worktree tracking (for cleanup on interrupt)
-_ACTIVE_WORKTREE_PATH=""
-_ACTIVE_WORKTREE_BRANCH=""
+# Branch tracking (for cleanup on interrupt)
+_ORIGINAL_BRANCH=""
+_DEV_BRANCH_NAME=""
 
 # ============================================================
 # Shared: Spawn an AI CLI session and wait for result
@@ -83,7 +83,6 @@ _ACTIVE_WORKTREE_BRANCH=""
 #   $4 - bootstrap_prompt (path)
 #   $5 - session_dir
 #   $6 - max_retries (for status update)
-#   $7 - worktree_path (optional; if set, AI CLI runs inside this directory)
 spawn_and_wait_session() {
     local feature_id="$1"
     local feature_list="$2"
@@ -91,7 +90,6 @@ spawn_and_wait_session() {
     local bootstrap_prompt="$4"
     local session_dir="$5"
     local max_retries="$6"
-    local worktree_path="${7:-}"
 
     local session_log="$session_dir/logs/session.log"
     local progress_json="$session_dir/logs/progress.json"
@@ -116,14 +114,6 @@ spawn_and_wait_session() {
     # within an existing Claude Code session (e.g. via launch-daemon.sh).
     unset CLAUDECODE 2>/dev/null || true
 
-    # If worktree path is provided, cd into it for the AI CLI session
-    local _saved_pwd=""
-    if [[ -n "$worktree_path" && -d "$worktree_path" ]]; then
-        _saved_pwd="$(pwd)"
-        cd "$worktree_path"
-        log_info "Running AI CLI in worktree: $worktree_path"
-    fi
-
     case "$CLI_CMD" in
         *claude*)
             # Claude Code: prompt via -p argument, --dangerously-skip-permissions for auto-accept
@@ -149,11 +139,6 @@ spawn_and_wait_session() {
     esac
     local cbc_pid=$!
 
-    # Restore original directory if we changed it
-    if [[ -n "$_saved_pwd" ]]; then
-        cd "$_saved_pwd"
-    fi
-
     # Start progress parser (no-op if stream-json not supported)
     start_progress_parser "$session_log" "$progress_json" "$SCRIPTS_DIR"
     local parser_pid="${_PARSER_PID:-}"
@@ -229,9 +214,9 @@ spawn_and_wait_session() {
                 else
                     local docs_changed=""
                     docs_changed=$(git -C "$project_root" log --name-only --format="" -1 2>/dev/null \
-                        | grep -E '(\.prizm-docs/|\.prizmkit/specs/REGISTRY\.md)' | head -1 || true)
+                        | grep -E '\.prizm-docs/' | head -1 || true)
                     if [[ -z "$docs_changed" ]]; then
-                        log_warn "Session committed but no .prizm-docs or REGISTRY.md changes detected."
+                        log_warn "Session committed but no .prizm-docs changes detected."
                         session_status="docs_missing"
                     fi
                 fi
@@ -280,13 +265,10 @@ cleanup() {
     # Kill all child processes (claude-internal, heartbeat, progress parser, etc.)
     kill 0 2>/dev/null || true
 
-    # Clean up active worktree if any
-    if [[ -n "$_ACTIVE_WORKTREE_PATH" ]]; then
-        local _project_root
-        _project_root="$(cd "$SCRIPT_DIR/.." && pwd)"
-        worktree_cleanup "$_project_root" "$_ACTIVE_WORKTREE_PATH" "$_ACTIVE_WORKTREE_BRANCH"
-        _ACTIVE_WORKTREE_PATH=""
-        _ACTIVE_WORKTREE_BRANCH=""
+    # Log current branch info for recovery
+    if [[ -n "$_DEV_BRANCH_NAME" ]]; then
+        log_info "Development was on branch: $_DEV_BRANCH_NAME"
+        log_info "Original branch was: $_ORIGINAL_BRANCH"
     fi
 
     if [[ -n "$FEATURE_LIST" && -f "$FEATURE_LIST" ]]; then
@@ -623,13 +605,9 @@ sys.exit(1)
         log_warn "Interrupted. Killing session..."
         # Kill all child processes
         kill 0 2>/dev/null || true
-        # Clean up active worktree if any
-        if [[ -n "$_ACTIVE_WORKTREE_PATH" ]]; then
-            local _proj_root
-            _proj_root="$(cd "$SCRIPT_DIR/.." && pwd)"
-            worktree_cleanup "$_proj_root" "$_ACTIVE_WORKTREE_PATH" "$_ACTIVE_WORKTREE_BRANCH"
-            _ACTIVE_WORKTREE_PATH=""
-            _ACTIVE_WORKTREE_BRANCH=""
+        # Log current branch info
+        if [[ -n "$_DEV_BRANCH_NAME" ]]; then
+            log_info "Development was on branch: $_DEV_BRANCH_NAME"
         fi
         log_info "Session log: $session_dir/logs/session.log"
         exit 130
@@ -638,63 +616,31 @@ sys.exit(1)
 
     _SPAWN_RESULT=""
 
-    # Worktree lifecycle: create worktree before session if enabled
-    local _wt_path="" _wt_branch=""
-    if [[ "$USE_WORKTREE" == "1" ]]; then
-        local _proj_root
-        _proj_root="$(cd "$SCRIPT_DIR/.." && pwd)"
-        local _wt_base="$STATE_DIR/worktrees"
-        local _source_branch
-        _source_branch=$(git -C "$_proj_root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
-
-        # Prune stale worktrees before creating new one
-        worktree_prune_stale "$_proj_root"
-
-        _WORKTREE_PATH=""
-        _WORKTREE_BRANCH=""
-        if worktree_create "$_proj_root" "$_wt_base" "$session_id" "$_source_branch"; then
-            _wt_path="$_WORKTREE_PATH"
-            _wt_branch="$_WORKTREE_BRANCH"
-            _ACTIVE_WORKTREE_PATH="$_wt_path"
-            _ACTIVE_WORKTREE_BRANCH="$_wt_branch"
-        else
-            log_warn "Failed to create worktree; running session in main working tree"
-        fi
+    # Branch lifecycle: create and checkout feature branch
+    local _proj_root
+    _proj_root="$(cd "$SCRIPT_DIR/.." && pwd)"
+    local _source_branch
+    _source_branch=$(git -C "$_proj_root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
+    _ORIGINAL_BRANCH="$_source_branch"
+
+    local _branch_name="${DEV_BRANCH:-dev/${feature_id}-$(date +%s)}"
+    if branch_create "$_proj_root" "$_branch_name" "$_source_branch"; then
+        _DEV_BRANCH_NAME="$_branch_name"
+    else
+        log_warn "Failed to create branch; running session on current branch"
     fi
 
     spawn_and_wait_session \
         "$feature_id" "$feature_list" "$session_id" \
-        "$bootstrap_prompt" "$session_dir" 999 "$_wt_path"
+        "$bootstrap_prompt" "$session_dir" 999
     local session_status="$_SPAWN_RESULT"
 
-    # Worktree lifecycle: merge and cleanup after session
-    if [[ -n "$_wt_path" && -n "$_wt_branch" ]]; then
+    # Auto-push after successful session
+    if [[ "$session_status" == "success" && "$AUTO_PUSH" == "1" ]]; then
         local _proj_root
         _proj_root="$(cd "$SCRIPT_DIR/.." && pwd)"
-        local _target_branch
-        _target_branch=$(git -C "$_proj_root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
-
-        if [[ "$session_status" == "success" ]]; then
-            _MERGE_RESULT=""
-            worktree_merge "$_proj_root" "$_wt_branch" "$_target_branch" "$feature_id" "$session_id" || true
-            if [[ "$_MERGE_RESULT" == "success" ]]; then
-                if [[ "$AUTO_PUSH" == "1" ]]; then
-                    log_info "AUTO_PUSH enabled; pushing to remote..."
-                    git -C "$_proj_root" push 2>/dev/null || log_warn "Auto-push failed"
-                fi
-                worktree_cleanup "$_proj_root" "$_wt_path" "$_wt_branch"
-            elif [[ "$_MERGE_RESULT" == "conflict" ]]; then
-                session_status="merge_conflict"
-                _SPAWN_RESULT="merge_conflict"
-                log_warn "Worktree branch preserved for manual conflict resolution: $_wt_branch"
-            else
-                worktree_cleanup "$_proj_root" "$_wt_path" "$_wt_branch"
-            fi
-        else
-            worktree_cleanup "$_proj_root" "$_wt_path" "$_wt_branch"
-        fi
-        _ACTIVE_WORKTREE_PATH=""
-        _ACTIVE_WORKTREE_BRANCH=""
+        log_info "AUTO_PUSH enabled; pushing to remote..."
+        git -C "$_proj_root" push -u origin "$_DEV_BRANCH_NAME" 2>/dev/null || log_warn "Auto-push failed"
     fi
 
     echo ""
@@ -766,13 +712,6 @@ main() {
     check_dependencies
     run_log_cleanup
 
-    # Prune stale worktree references at startup
-    if [[ "$USE_WORKTREE" == "1" ]]; then
-        local _prune_root
-        _prune_root="$(cd "$SCRIPT_DIR/.." && pwd)"
-        worktree_prune_stale "$_prune_root"
-    fi
-
     # Initialize pipeline state if needed
     if [[ ! -f "$STATE_DIR/pipeline.json" ]]; then
         log_info "Initializing pipeline state..."
@@ -813,6 +752,23 @@ main() {
     echo -e "${BOLD}════════════════════════════════════════════════════${NC}"
     echo ""
 
+    # Branch lifecycle: create dev branch for this pipeline run
+    local _proj_root
+    _proj_root="$(cd "$SCRIPT_DIR/.." && pwd)"
+    local _source_branch
+    _source_branch=$(git -C "$_proj_root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
+    _ORIGINAL_BRANCH="$_source_branch"
+
+    local run_id_for_branch
+    run_id_for_branch=$(jq -r '.run_id' "$STATE_DIR/pipeline.json" 2>/dev/null || echo "$$")
+    local _branch_name="${DEV_BRANCH:-dev/pipeline-${run_id_for_branch}}"
+    if branch_create "$_proj_root" "$_branch_name" "$_source_branch"; then
+        _DEV_BRANCH_NAME="$_branch_name"
+        log_info "Dev branch: $_branch_name"
+    else
+        log_warn "Failed to create dev branch; running on current branch: $_source_branch"
+    fi
+
     # Main processing loop
     local session_count=0
 
@@ -851,6 +807,10 @@ for f in data.get('stuck_features', []):
             log_success "════════════════════════════════════════════════════"
             log_success "  All features completed! Pipeline finished."
             log_success "  Total sessions: $session_count"
+            if [[ -n "$_DEV_BRANCH_NAME" ]]; then
+                log_success "  Dev branch: $_DEV_BRANCH_NAME"
+                log_success "  Merge with: git checkout $_ORIGINAL_BRANCH && git merge $_DEV_BRANCH_NAME"
+            fi
             log_success "════════════════════════════════════════════════════"
             rm -f "$STATE_DIR/current-session.json"
             break
@@ -948,70 +908,17 @@ os.replace(tmp, target)
         log_info "Spawning AI CLI session: $session_id"
         _SPAWN_RESULT=""
 
-        # Worktree lifecycle: create worktree before session if enabled
-        local _wt_path="" _wt_branch=""
-        if [[ "$USE_WORKTREE" == "1" ]]; then
-            local _proj_root
-            _proj_root="$(cd "$SCRIPT_DIR/.." && pwd)"
-            local _wt_base="$STATE_DIR/worktrees"
-            local _source_branch
-            _source_branch=$(git -C "$_proj_root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
-
-            _WORKTREE_PATH=""
-            _WORKTREE_BRANCH=""
-            if worktree_create "$_proj_root" "$_wt_base" "$session_id" "$_source_branch"; then
-                _wt_path="$_WORKTREE_PATH"
-                _wt_branch="$_WORKTREE_BRANCH"
-                _ACTIVE_WORKTREE_PATH="$_wt_path"
-                _ACTIVE_WORKTREE_BRANCH="$_wt_branch"
-            else
-                log_warn "Failed to create worktree; running session in main working tree"
-            fi
-        fi
-
         spawn_and_wait_session \
             "$feature_id" "$feature_list" "$session_id" \
-            "$bootstrap_prompt" "$session_dir" "$MAX_RETRIES" "$_wt_path"
+            "$bootstrap_prompt" "$session_dir" "$MAX_RETRIES"
         local session_status="$_SPAWN_RESULT"
 
-        # Worktree lifecycle: merge and cleanup after session
-        if [[ -n "$_wt_path" && -n "$_wt_branch" ]]; then
+        # Auto-push after successful session
+        if [[ "$session_status" == "success" && "$AUTO_PUSH" == "1" ]]; then
             local _proj_root
             _proj_root="$(cd "$SCRIPT_DIR/.." && pwd)"
-            local _target_branch
-            _target_branch=$(git -C "$_proj_root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
-
-            if [[ "$session_status" == "success" ]]; then
-                _MERGE_RESULT=""
-                worktree_merge "$_proj_root" "$_wt_branch" "$_target_branch" "$feature_id" "$session_id" || true
-                if [[ "$_MERGE_RESULT" == "success" ]]; then
-                    if [[ "$AUTO_PUSH" == "1" ]]; then
-                        log_info "AUTO_PUSH enabled; pushing to remote..."
-                        git -C "$_proj_root" push 2>/dev/null || log_warn "Auto-push failed"
-                    fi
-                    worktree_cleanup "$_proj_root" "$_wt_path" "$_wt_branch"
-                elif [[ "$_MERGE_RESULT" == "conflict" ]]; then
-                    session_status="merge_conflict"
-                    _SPAWN_RESULT="merge_conflict"
-                    log_warn "Worktree branch preserved for manual conflict resolution: $_wt_branch"
-                    # Update feature status to merge_conflict
-                    python3 "$SCRIPTS_DIR/update-feature-status.py" \
-                        --feature-list "$feature_list" \
-                        --state-dir "$STATE_DIR" \
-                        --feature-id "$feature_id" \
-                        --session-status "merge_conflict" \
-                        --session-id "$session_id" \
-                        --max-retries "$MAX_RETRIES" \
-                        --action update >/dev/null 2>&1 || true
-                else
-                    worktree_cleanup "$_proj_root" "$_wt_path" "$_wt_branch"
-                fi
-            else
-                # Non-success: cleanup worktree
-                worktree_cleanup "$_proj_root" "$_wt_path" "$_wt_branch"
-            fi
-            _ACTIVE_WORKTREE_PATH=""
-            _ACTIVE_WORKTREE_BRANCH=""
+            log_info "AUTO_PUSH enabled; pushing to remote..."
+            git -C "$_proj_root" push 2>/dev/null || log_warn "Auto-push failed"
         fi
 
         session_count=$((session_count + 1))

package/bundled/dev-pipeline/scripts/parse-stream-progress.py

@@ -32,7 +32,7 @@ PHASE_KEYWORDS = {
     "analyze": ["prizmkit-analyze", "cross-check", "consistency", "analyzing"],
     "implement": ["prizmkit-implement", "implement", "TDD", "coding", "writing code"],
     "code-review": ["prizmkit-code-review", "code review", "review verdict", "reviewing"],
-    "summarize": ["prizmkit-summarize", "REGISTRY.md", "summarize", "summary"],
+    "retrospective": ["prizmkit-retrospective", "retrospective", "knowledge distillation", "TRAPS", ".prizm-docs/ sync", "structural sync"],
     "commit": ["prizmkit-committer", "git commit", "feat(", "fix(", "committing"],
 }
 

package/bundled/dev-pipeline/templates/bootstrap-tier1.md

@@ -37,7 +37,6 @@ You are the **session orchestrator**. Implement Feature {{FEATURE_ID}}: "{{FEATU
 .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md
 .prizmkit/specs/{{FEATURE_SLUG}}/plan.md
 .prizmkit/specs/{{FEATURE_SLUG}}/tasks.md
-.prizmkit/specs/REGISTRY.md
 ```
 
 ---
@@ -111,24 +110,17 @@ Key decisions: [list]
 
 **CP-2**: All acceptance criteria met, tests pass.
 
-### Phase 4.5: Prizm Doc Update (mandatory for feature sessions)
+### Phase 4.5: Memory Maintenance (mandatory before commit)
 
-Run `/prizmkit-prizm-docs` and sync project docs before commit:
-1. Use `git diff --cached --name-status` (fallback: `git diff --name-status`) to locate changed modules
-2. Update affected `.prizm-docs/` files (L1/L2, changelog.prizm)
-3. Stage documentation updates (`git add .prizm-docs/`) if changed
+Run `/prizmkit-retrospective` — the **sole maintainer** of `.prizm-docs/`:
+1. **Structural sync**: Use `git diff --cached --name-status` to locate changed modules, update KEY_FILES/INTERFACES/DEPENDENCIES/file counts in affected `.prizm-docs/` files
+2. **Knowledge injection** (feature sessions only): Extract TRAPS/RULES/DECISIONS from completed work into `.prizm-docs/`
+3. Stage all doc changes: `git add .prizm-docs/`
 
-Doc maintenance pass condition (pipeline-enforced): `REGISTRY.md` **or** `.prizm-docs/` changed in the final commit.
-
-### Phase 4.7: Retrospective (feature sessions only, before commit)
-
-If this session is a feature (not a bug-fix-only commit), run `/prizmkit-retrospective` now — **before committing**.
-Retrospective must update relevant `.prizm-docs/` sections (TRAPS/RULES/DECISIONS) when applicable, so those changes are included in the feature commit.
-Stage any `.prizm-docs/` changes produced: `git add .prizm-docs/`
+Doc maintenance pass condition (pipeline-enforced): `.prizm-docs/` changed in the final commit.
 
 ### Phase 5: Commit
 
-- Run `/prizmkit-summarize` → archive to REGISTRY.md
 - Run `/prizmkit-committer` → `feat({{FEATURE_ID}}): {{FEATURE_TITLE}}`, do NOT push
 - MANDATORY: commit must be done via `/prizmkit-committer` skill. Do NOT run manual `git add`/`git commit` as a substitute.
 - Do NOT run `update-feature-status.py` here — the pipeline runner handles feature-list.json updates automatically after session exit.
@@ -174,11 +166,11 @@ After writing `session-status.json`, verify repository is clean:
 git status --short
 ```
 
-If any files remain, include them in the last commit:
+If any files remain (e.g. session-status.json), stage and create a follow-up commit:
 
 ```bash
 git add -A
-git commit --amend --no-edit
+git commit -m "chore({{FEATURE_ID}}): include session artifacts"
 ```
 
 Re-check `git status --short` and ensure it is empty before exiting.

package/bundled/dev-pipeline/templates/bootstrap-tier2.md

@@ -13,7 +13,7 @@ You are the **session orchestrator**. Implement Feature {{FEATURE_ID}}: "{{FEATU
 
 **CRITICAL**: You MUST NOT exit until ALL work is complete and session-status.json is written. When you spawn subagents, wait for each to finish (run_in_background=false).
 
-**Tier 2 — Dual Agent**: You handle context + planning directly. Then spawn Dev and Reviewer subagents. No TeamCreate required.
+**Tier 2 — Dual Agent**: You handle context + planning directly. Then spawn Dev and Reviewer subagents. You may spawn agents directly via the Task tool or use TeamCreate for coordination — choose based on the situation.
 
 ### Feature Description
 
@@ -37,7 +37,6 @@ You are the **session orchestrator**. Implement Feature {{FEATURE_ID}}: "{{FEATU
 .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md  ← written by you, read by Dev + Reviewer
 .prizmkit/specs/{{FEATURE_SLUG}}/plan.md
 .prizmkit/specs/{{FEATURE_SLUG}}/tasks.md
-.prizmkit/specs/REGISTRY.md
 ```
 
 **`context-snapshot.md`** is the shared knowledge base. You write it once; Dev and Reviewer read it instead of re-scanning individual files.
@@ -138,24 +137,17 @@ Wait for Reviewer to return.
 
 **CP-2**: Tests pass, verdict is not NEEDS_FIXES.
 
-### Phase 4.5: Prizm Doc Update (mandatory for feature sessions)
+### Phase 4.5: Memory Maintenance (mandatory before commit)
 
-Run `/prizmkit-prizm-docs` and sync project docs before commit:
-1. Use `git diff --cached --name-status` (fallback: `git diff --name-status`) to locate changed modules
-2. Update affected `.prizm-docs/` files (L1/L2, changelog.prizm)
-3. Stage documentation updates (`git add .prizm-docs/`) if changed
+Run `/prizmkit-retrospective` — the **sole maintainer** of `.prizm-docs/`:
+1. **Structural sync**: Use `git diff --cached --name-status` to locate changed modules, update KEY_FILES/INTERFACES/DEPENDENCIES/file counts in affected `.prizm-docs/` files
+2. **Knowledge injection** (feature sessions only): Extract TRAPS/RULES/DECISIONS from completed work into `.prizm-docs/`
+3. Stage all doc changes: `git add .prizm-docs/`
 
-Doc maintenance pass condition (pipeline-enforced): `REGISTRY.md` **or** `.prizm-docs/` changed in the final commit.
-
-### Phase 4.7: Retrospective (feature sessions only, before commit)
-
-If this session is a feature (not a bug-fix-only commit), run `/prizmkit-retrospective` now — **before committing**.
-Retrospective must update relevant `.prizm-docs/` sections (TRAPS/RULES/DECISIONS) when applicable, so those changes are included in the feature commit.
-Stage any `.prizm-docs/` changes produced: `git add .prizm-docs/`
+Doc maintenance pass condition (pipeline-enforced): `.prizm-docs/` changed in the final commit.
 
 ### Phase 5: Commit
 
-- Run `/prizmkit-summarize` → archive to REGISTRY.md
 - Run `/prizmkit-committer` → `feat({{FEATURE_ID}}): {{FEATURE_TITLE}}`, do NOT push
 - MANDATORY: commit must be done via `/prizmkit-committer` skill. Do NOT run manual `git add`/`git commit` as a substitute.
 - Do NOT run `update-feature-status.py` here — the pipeline runner handles feature-list.json updates automatically after session exit.
@@ -201,11 +193,11 @@ After writing `session-status.json`, verify repository is clean:
 git status --short
 ```
 
-If any files remain, include them in the last commit:
+If any files remain (e.g. session-status.json), stage and create a follow-up commit:
 
 ```bash
 git add -A
-git commit --amend --no-edit
+git commit -m "chore({{FEATURE_ID}}): include session artifacts"
 ```
 
 Re-check `git status --short` and ensure it is empty before exiting.
@@ -223,7 +215,7 @@ Re-check `git status --short` and ensure it is empty before exiting.
 
 ## Reminders
 
-- Tier 2: orchestrator builds context+plan, Dev implements, Reviewer reviews — no TeamCreate
+- Tier 2: orchestrator builds context+plan, Dev implements, Reviewer reviews — use direct Task spawn or TeamCreate as appropriate
 - Build context-snapshot.md FIRST; all subagents read it instead of re-reading source files
 - Do NOT use `run_in_background=true` when spawning subagents
 - ALWAYS write session-status.json before exiting

package/bundled/dev-pipeline/templates/bootstrap-tier3.md

@@ -13,7 +13,7 @@ You are the **session orchestrator**. Implement Feature {{FEATURE_ID}}: "{{FEATU
 
 **CRITICAL**: You MUST NOT exit until ALL work is complete and session-status.json is written. When you spawn subagents, wait for each to finish (run_in_background=false). Do NOT spawn agents in background and exit — that kills the session.
 
-**Tier 3 — Full Team**: Dev + Reviewer agents spawned directly via Task tool. Full 7-phase pipeline.
+**Tier 3 — Full Team**: For complex features, create a coordinated agent team via TeamCreate. Use the full 7-phase pipeline with Dev + Reviewer agents.
 
 ### Feature Description
 
@@ -71,7 +71,6 @@ LLM context is frozen at prompt time. Modifying a skill source file during this
 .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md  ← orchestrator writes, all subagents read
 .prizmkit/specs/{{FEATURE_SLUG}}/spec.md
 .prizmkit/specs/{{FEATURE_SLUG}}/plan.md              ← includes Tasks section
-.prizmkit/specs/REGISTRY.md
 ```
 
 **`context-snapshot.md`** is the shared knowledge base. Orchestrator writes it once; Dev and Reviewer read it instead of re-scanning source files. This eliminates redundant I/O across all agents.
@@ -119,7 +118,7 @@ Save the list of **pre-existing failing tests** (if any) as `BASELINE_FAILURES`.
 
 ### Step 1: Team Setup
 
-No TeamCreate required. Agents are spawned directly via the `Task` tool using `subagent_type`.
+Create a coordinated agent team for this feature session:
 
 1. Run init script:
    `python3 {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}`
@@ -127,6 +126,11 @@ No TeamCreate required. Agents are spawned directly via the `Task` tool using `s
 2. Check for existing artifacts:
    `ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null`
 
+3. Create the agent team:
+   - Call `TeamCreate` with `team_name="prizm-dev-team-{{FEATURE_ID}}"` and `description="Implementing {{FEATURE_TITLE}}"`
+   - Reference team config at `{{TEAM_CONFIG_PATH}}` for agent definitions
+   - Spawn Dev and Reviewer agents as team members
+
 Agent files are at:
 - Dev: `{{DEV_SUBAGENT_PATH}}`
 - Reviewer: `{{REVIEWER_SUBAGENT_PATH}}`
@@ -287,7 +291,7 @@ Wait for Reviewer to return.
 
 **CP-3**: Integration tests pass, verdict is not NEEDS_FIXES.
 
-### Phase 7: Summarize & Commit — DO NOT SKIP
+### Phase 7: Retrospective & Commit — DO NOT SKIP
 
 {{IF_MODE_SELF_EVOLVE}}
 **Framework Validation Gate (self-evolve mode)**:
@@ -310,7 +314,7 @@ bash {{VALIDATOR_SCRIPTS_DIR}}/validate-framework.sh
 Then set `"reload_needed": true` in session-status.json.
 {{END_IF_MODE_SELF_EVOLVE}}
 
-**For bug fixes**: skip `/prizmkit-summarize`, skip retrospective, and use `fix(<scope>):` commit prefix.
+**For bug fixes**: run `/prizmkit-retrospective` for structural sync only (skip knowledge injection unless a new TRAPS was discovered). Use `fix(<scope>):` commit prefix.
 
 **7a.** Check if feature already committed:
 ```bash
@@ -319,21 +323,11 @@ git log --oneline | grep "{{FEATURE_ID}}" | head -3
 - If a commit for `{{FEATURE_ID}}` already exists → **skip 7c** (do NOT run /prizmkit-committer, do NOT run git reset, do NOT stage or unstage anything). Proceed directly to Step 3.
 - If no existing commit → proceed normally with 7a–7c.
 
-**7b.** Run `/prizmkit-summarize` → archive to REGISTRY.md
-
-**7b.5.** Update prizm-docs (feature sessions):
-- Read the 'Implementation Log' in `context-snapshot.md` to identify changed files
-- For each changed file, check if any related `.prizm-docs/` L1/L2 doc needs updating (new APIs, changed behavior, new TRAPS)
-- Update `.prizm-docs/changelog.prizm`: append one-line entry `- feat({{FEATURE_ID}}): {{FEATURE_TITLE}}`
-- Stage all modified prizm-docs: `git add .prizm-docs/`
-- Pipeline docs pass condition is `REGISTRY.md` OR `.prizm-docs/` changed in final commit
-
-**7b.6.** Run `/prizmkit-retrospective` (feature sessions only, **before commit**):
-- Extract lessons from completed feature — compare spec/plan/tasks vs actual
-- Update relevant `.prizm-docs/` sections: TRAPS, RULES, DECISIONS
-- Write `.prizmkit/specs/{{FEATURE_SLUG}}/retrospective.md`
-- Stage any `.prizm-docs/` changes: `git add .prizm-docs/`
-- **Skip if this session is bug-fix-only**
+**7b.** Run `/prizmkit-retrospective` (**before commit**, the sole maintainer of `.prizm-docs/`):
+- **Structural sync**: update KEY_FILES/INTERFACES/DEPENDENCIES/file counts for changed modules
+- **Knowledge injection** (feature sessions only): extract TRAPS, RULES, DECISIONS from completed work
+- Stage all doc changes: `git add .prizm-docs/`
+- **For bug-fix sessions**: structural sync only, skip knowledge injection unless a genuinely new pitfall was discovered
 
 **7c.** Run `/prizmkit-committer` → `feat({{FEATURE_ID}}): {{FEATURE_TITLE}}`, do NOT push
 
@@ -383,18 +377,20 @@ After writing `session-status.json`, verify repository is clean:
 git status --short
 ```
 
-If any files remain, include them in the last commit:
+If any files remain (e.g. session-status.json), stage and create a follow-up commit:
 
 ```bash
 git add -A
-git commit --amend --no-edit
+git commit -m "chore({{FEATURE_ID}}): include session artifacts"
 ```
 
 Re-check `git status --short` and ensure it is empty before exiting.
 
 ## Step 4: Team Cleanup
 
-No team cleanup needed — agents were spawned directly without TeamCreate.
+Clean up the agent team created in Step 1:
+- Call `TeamDelete` to remove the team and free resources
+- Only call TeamDelete after all agents have completed and session-status.json is written
 
 ## Critical Paths
 
@@ -411,7 +407,7 @@ No team cleanup needed — agents were spawned directly without TeamCreate.
 
 ## Reminders
 
-- Tier 3: full team — Dev (implementation) → Reviewer (review) — agents spawned directly via Task tool (no TeamCreate needed)
+- Tier 3: full team — Dev (implementation) → Reviewer (review) — create coordinated team via TeamCreate, clean up with TeamDelete at session end
 - context-snapshot.md is the team knowledge base: orchestrator writes it once, all agents read it
 - Do NOT use `run_in_background=true` when spawning agents
 - ALWAYS write session-status.json before exiting

package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md

@@ -21,14 +21,14 @@ You are the **bug fix session orchestrator**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}
 **MANDATORY TEAM REQUIREMENT**: You MUST use the `prizm-dev-team` multi-agent team. This is NON-NEGOTIABLE. All implementation and review work MUST be performed by the appropriate team agents (Dev, Reviewer). You are the orchestrator — handle coordination, planning, and commit phases directly.
 
 **BUG FIX DOCUMENTATION POLICY**: Bug fixes MUST NOT be recorded as new documentation entries:
-- Do NOT run `/prizmkit-summarize` (no REGISTRY.md entries)
+- Run `/prizmkit-retrospective` with structural sync only (Job 1) — skip knowledge injection unless a genuinely new TRAP was discovered
 - Do NOT create spec/plan/tasks under `.prizmkit/specs/`
 - Do NOT update `.prizm-docs/` module docs for pure bug fixes (unless TRAPS update is needed)
 - Commit with `fix(<scope>):` prefix, NOT `feat:`
 
 ### Team Definition Reference
 
-- **Source of truth**: `core/team/prizm-dev-team.json`
+- **Source of truth**: `{{TEAM_CONFIG_PATH}}`
 - **Installed team config**: `{{TEAM_CONFIG_PATH}}`
 
 ### Bug Description
@@ -81,7 +81,7 @@ You are the **bug fix session orchestrator**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}
    - If valid, reuse it. Set `TEAM_REUSED=true`
 
 2. **If no reusable team**, create a new one:
-   - Reference `core/team/prizm-dev-team.json`
+   - Reference `{{TEAM_CONFIG_PATH}}`
    - Call `TeamCreate` with `team_name="prizm-dev-team-{{BUG_ID}}"` and `description="Fixing {{BUG_TITLE}}"`
    - Set `TEAM_REUSED=false`
 
@@ -211,7 +211,7 @@ You are the **bug fix session orchestrator**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}
   1. Run `/prizmkit-committer` with:
      - Commit message: `fix({{FIX_SCOPE}}): {{BUG_TITLE}}`
      - Include both fix code and reproduction test
-     - Do NOT run `/prizmkit-summarize`
+     - Do NOT run `/prizmkit-retrospective` with REGISTRY archiving
      - Do NOT push (user will push manually)
   2. If a new pitfall was discovered (not previously in TRAPS):
      - Update the affected module's TRAPS section in `.prizm-docs/`
@@ -267,7 +267,7 @@ Write to: `{{SESSION_STATUS_PATH}}`
 
 | Resource | Path |
 |----------|------|
-| Team Definition (source of truth) | `core/team/prizm-dev-team.json` |
+| Team Definition (source of truth) | `{{TEAM_CONFIG_PATH}}` |
 | Team Config (installed) | `{{TEAM_CONFIG_PATH}}` |
 | Bug Fix Artifacts Dir | `.prizmkit/bugfix/{{BUG_ID}}/` |
 | Fix Plan | `.prizmkit/bugfix/{{BUG_ID}}/fix-plan.md` |
@@ -282,7 +282,7 @@ Write to: `{{SESSION_STATUS_PATH}}`
 - **MANDATORY**: Use `prizm-dev-team` — single-agent execution is FORBIDDEN
 - **Only 2 artifact files per bug**: fix-plan.md + fix-report.md — NEVER more
 - **Do NOT create** spec.md, plan.md, or tasks.md for bug fixes
-- **Do NOT run** `/prizmkit-summarize` (no REGISTRY.md entries for bugs)
+- **Do NOT run** `/prizmkit-retrospective` knowledge injection for bugs (structural sync only, unless genuinely new TRAP discovered)
 - **Commit with** `fix(<scope>):` prefix, NOT `feat:`
 - **Update TRAPS** in `.prizm-docs/` only if a genuinely new pitfall was discovered
 - Dev agents use TDD approach: reproduction test goes from RED → GREEN