prizmkit 1.0.122 → 1.0.124

package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py

@@ -84,10 +84,16 @@ def parse_args():
     )
     parser.add_argument(
         "--mode",
-        choices=["lite", "standard", "full", "self-evolve"],
+        choices=["lite", "standard", "full"],
         default=None,
         help="Override pipeline mode (default: auto-detect from complexity)",
     )
+    parser.add_argument(
+        "--critic",
+        choices=["true", "false"],
+        default=None,
+        help="Override critic enablement (default: read from feature field)",
+    )
     return parser.parse_args()
 
 
@@ -279,39 +285,20 @@ def process_conditional_blocks(content, resume_phase):
     return content
 
 
-def process_mode_blocks(content, pipeline_mode, init_done):
-    """Process pipeline mode and init conditional blocks.
+def process_mode_blocks(content, pipeline_mode, init_done, critic_enabled=False):
+    """Process pipeline mode, init, and critic conditional blocks.
 
     Keeps the block matching the current mode, removes the others.
-    For self-evolve mode: keeps SELF_EVOLVE blocks AND FULL blocks
-    (since self-evolve is full + framework guardrails).
+    Handles {{IF_CRITIC_ENABLED}} / {{END_IF_CRITIC_ENABLED}} blocks.
     """
-    is_self_evolve = pipeline_mode == "self-evolve"
-
-    # Step 1: Handle SELF_EVOLVE conditional blocks first
-    se_open = "{{IF_MODE_SELF_EVOLVE}}"
-    se_close = "{{END_IF_MODE_SELF_EVOLVE}}"
-    if is_self_evolve:
-        # Keep content, remove tags
-        content = content.replace(se_open + "\n", "")
-        content = content.replace(se_open, "")
-        content = content.replace(se_close + "\n", "")
-        content = content.replace(se_close, "")
-    else:
-        # Remove entire SELF_EVOLVE blocks
-        pattern = re.escape(se_open) + r".*?" + re.escape(se_close) + r"\n?"
-        content = re.sub(pattern, "", content, flags=re.DOTALL)
-
-    # Step 2: Handle lite/standard/full blocks
-    # self-evolve inherits full mode for the standard tier blocks
-    effective_mode = "full" if is_self_evolve else pipeline_mode
+    # Handle lite/standard/full blocks
     modes = ["lite", "standard", "full"]
 
     for mode in modes:
         tag_open = "{{{{IF_MODE_{}}}}}".format(mode.upper())
         tag_close = "{{{{END_IF_MODE_{}}}}}".format(mode.upper())
 
-        if mode == effective_mode:
+        if mode == pipeline_mode:
             # Keep content, remove tags
             content = content.replace(tag_open + "\n", "")
             content = content.replace(tag_open, "")
@@ -338,6 +325,20 @@ def process_mode_blocks(content, pipeline_mode, init_done):
             "", content, flags=re.DOTALL,
         )
 
+    # Critic blocks
+    critic_open = "{{IF_CRITIC_ENABLED}}"
+    critic_close = "{{END_IF_CRITIC_ENABLED}}"
+    if critic_enabled:
+        # Keep content, remove tags
+        content = content.replace(critic_open + "\n", "")
+        content = content.replace(critic_open, "")
+        content = content.replace(critic_close + "\n", "")
+        content = content.replace(critic_close, "")
+    else:
+        # Remove entire CRITIC blocks
+        pattern = re.escape(critic_open) + r".*?" + re.escape(critic_close) + r"\n?"
+        content = re.sub(pattern, "", content, flags=re.DOTALL)
+
     return content
 
 
@@ -430,6 +431,9 @@ def build_replacements(args, feature, features, global_context, script_dir):
     reviewer_subagent = os.path.join(
         agents_dir, "prizm-dev-team-reviewer.md",
     )
+    critic_subagent = os.path.join(
+        agents_dir, "prizm-dev-team-critic.md",
+    )
 
     # Verify agent files actually exist — missing files cause confusing
     # errors when the AI session tries to read them later.
@@ -472,14 +476,47 @@ def build_replacements(args, feature, features, global_context, script_dir):
     else:
         pipeline_mode = determine_pipeline_mode(complexity)
 
-    is_self_evolve = pipeline_mode == "self-evolve"
-
     # Auto-detect resume: if all planning artifacts exist and resume_phase
     # is "null" (fresh start), skip to Phase 6
     effective_resume = args.resume_phase
     if effective_resume == "null" and artifacts["all_complete"]:
         effective_resume = "6"
 
+    # Determine critic enablement (priority: CLI > env > feature field > default)
+    critic_env = os.environ.get("ENABLE_CRITIC", "").lower()
+    if args.critic is not None:
+        critic_enabled = args.critic == "true"
+    elif critic_env in ("true", "1"):
+        critic_enabled = True
+    elif critic_env in ("false", "0"):
+        critic_enabled = False
+    else:
+        critic_enabled = bool(feature.get("critic", False))
+
+    # Determine critic count (from feature field, default 1)
+    # Multi-critic voting (3) must be explicitly set by the user in feature-list.json
+    critic_count = feature.get("critic_count", 1)
+
+    # Guard: if critic enabled but agent file missing, force disable and warn
+    if critic_enabled and not os.path.isfile(critic_subagent):
+        LOGGER.warning(
+            "Critic enabled but agent file not found: %s. "
+            "Critic phases will be SKIPPED. "
+            "Run `npx prizmkit install` to install agent definitions.",
+            critic_subagent,
+        )
+        critic_enabled = False
+
+    # Guard: if critic enabled but tier doesn't support it (lite), warn and disable
+    if critic_enabled and pipeline_mode == "lite":
+        LOGGER.warning(
+            "Critic enabled for feature %s but pipeline_mode='lite' (tier1) "
+            "does not support critic phases. Critic will be SKIPPED. "
+            "Use estimated_complexity='high' or pass --mode standard/full.",
+            args.feature_id,
+        )
+        critic_enabled = False
+
     replacements = {
         "{{RUN_ID}}": args.run_id,
         "{{SESSION_ID}}": args.session_id,
@@ -501,6 +538,7 @@ def build_replacements(args, feature, features, global_context, script_dir):
         "{{TEAM_CONFIG_PATH}}": team_config_path,
         "{{DEV_SUBAGENT_PATH}}": dev_subagent,
         "{{REVIEWER_SUBAGENT_PATH}}": reviewer_subagent,
+        "{{CRITIC_SUBAGENT_PATH}}": critic_subagent,
         "{{VALIDATOR_SCRIPTS_DIR}}": validator_scripts_dir,
         "{{INIT_SCRIPT_PATH}}": init_script_path,
         "{{SESSION_STATUS_PATH}}": session_status_abs,
@@ -508,11 +546,12 @@ def build_replacements(args, feature, features, global_context, script_dir):
         "{{FEATURE_SLUG}}": feature_slug,
         "{{PIPELINE_MODE}}": pipeline_mode,
         "{{COMPLEXITY}}": complexity,
+        "{{CRITIC_ENABLED}}": "true" if critic_enabled else "false",
+        "{{CRITIC_COUNT}}": str(critic_count),
         "{{INIT_DONE}}": "true" if init_done else "false",
         "{{HAS_SPEC}}": "true" if artifacts["has_spec"] else "false",
         "{{HAS_PLAN}}": "true" if artifacts["has_plan"] else "false",
         "{{ARTIFACTS_COMPLETE}}": "true" if artifacts["all_complete"] else "false",
-        "{{IS_SELF_EVOLVE}}": "true" if is_self_evolve else "false",
     }
 
     return replacements, effective_resume
@@ -523,10 +562,11 @@ def render_template(template_content, replacements, resume_phase):
     # Step 1: Process fresh_start/resume conditional blocks
     content = process_conditional_blocks(template_content, resume_phase)
 
-    # Step 2: Process mode and init conditional blocks
+    # Step 2: Process mode, init, and critic conditional blocks
     pipeline_mode = replacements.get("{{PIPELINE_MODE}}", "standard")
     init_done = replacements.get("{{INIT_DONE}}", "false") == "true"
-    content = process_mode_blocks(content, pipeline_mode, init_done)
+    critic_enabled = replacements.get("{{CRITIC_ENABLED}}", "false") == "true"
+    content = process_mode_blocks(content, pipeline_mode, init_done, critic_enabled)
 
     # Step 3: Replace all {{PLACEHOLDER}} variables
     for placeholder, value in replacements.items():
@@ -584,7 +624,6 @@ def main():
             "lite": "bootstrap-tier1.md",
             "standard": "bootstrap-tier2.md",
             "full": "bootstrap-tier3.md",
-            "self-evolve": "bootstrap-tier3.md",
         }
         _tier_file = _tier_file_map.get(_mode, "bootstrap-tier2.md")
         _tier_path = os.path.join(script_dir, "..", "templates", _tier_file)

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

@@ -88,8 +88,13 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md 2>/dev/null && echo "EXI
 
 If MISSING — build it now:
 1. Read `.prizm-docs/root.prizm` and relevant L1 prizm docs
-2. Scan `src/` for files related to this feature; read each one
-3. Write `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`:
+2. Detect source code directories: read KEY_FILES and STRUCTURE sections from `root.prizm` to identify where source code lives (e.g. `src/`, `app/`, `lib/`, `cmd/`, `packages/`, or project root). If `root.prizm` is missing, scan the project tree:
+   ```bash
+   find . -maxdepth 2 -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rb" -o -name "*.rs" \) -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/vendor/*' | head -30
+   ```
+   Identify the top-level source directories from the results.
+3. Scan the detected source directories for files related to this feature; read each one
+4. Write `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`:
    - **Section 1 — Feature Brief**: feature description + acceptance criteria (copy from above)
    - **Section 2 — Project Structure**: run the following to get a visual directory tree, then paste output:
      ```bash
@@ -108,6 +113,12 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
 If plan.md missing, write it directly:
 - `plan.md`: key components, data flow, files to create/modify, and a Tasks section with `[ ]` checkboxes (each task = one implementable unit). Keep under 80 lines.
 
+**Database Design Gate** (if feature involves data persistence — new tables, schema changes, new entities):
+Before proceeding past CP-1:
+1. Scan for existing schema files (`*.prisma`, `*.sql`, `migrations/`, `models/`, `*.entity.*`) and read them
+2. Ensure new tables/fields follow existing naming conventions and constraint patterns
+3. Resolve all uncertain DB design decisions before writing Tasks — document choices in plan.md
+
 **CP-1**: plan.md exists with Tasks section.
 
 ### Phase 3: Implement + Test

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

@@ -38,9 +38,9 @@ You are running in headless mode with a FINITE context window. Exceeding it will
 1. **context-snapshot.md is your single source of truth** — After Phase 1 builds it, ALWAYS read context-snapshot.md instead of re-reading individual source files
 2. **Never re-read your own writes** — After you create/modify a file, do NOT read it back to verify. Trust your write was correct.
 3. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
-4. **One task at a time** — In Phase 3 (implement), complete and test one task before starting the next.
+4. **One task at a time** — In Phase 4 (implement), complete and test one task before starting the next.
 5. **Minimize tool output** — When running commands, use `| head -20` or `| tail -20` to limit output. Never dump entire test suites or logs.
-6. **No intermediate commits** — Do NOT run `git add`/`git commit` during Phase 1-4. All changes are committed once at the end in Phase 5 via `/prizmkit-committer`.
+6. **No intermediate commits** — Do NOT run `git add`/`git commit` during Phase 1-5. All changes are committed once at the end in Phase 6 via `/prizmkit-committer`.
 7. **Capture test output once** — When running the test suite, always use `$TEST_CMD 2>&1 | tee /tmp/test-out.txt | tail -20`. Then grep `/tmp/test-out.txt` for details. Never re-run the suite just to apply a different filter.
 
 ---
@@ -90,7 +90,7 @@ cat .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md 2>/dev/null || echo "NO_PREV
 ```
 If failure-log.md exists:
 - Read ROOT_CAUSE and SUGGESTION — adjust your approach accordingly
-- Read DISCOVERED_TRAPS — if any are genuine, inject into .prizm-docs/ during Phase 5 retrospective
+- Read DISCOVERED_TRAPS — if any are genuine, inject into .prizm-docs/ during Phase 6 retrospective
 - Do NOT delete failure-log.md until this session completes all phases and commits successfully
 
 ```bash
@@ -99,8 +99,13 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md 2>/dev/null && echo "EXI
 
 If MISSING — build it now:
 1. Read `.prizm-docs/root.prizm` and relevant L1/L2 prizm docs
-2. Scan `src/` for files related to this feature; read each one
-3. Write `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`:
+2. Detect source code directories: read KEY_FILES and STRUCTURE sections from `root.prizm` to identify where source code lives (e.g. `src/`, `app/`, `lib/`, `cmd/`, `packages/`, or project root). If `root.prizm` is missing, scan the project tree:
+   ```bash
+   find . -maxdepth 2 -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rb" -o -name "*.rs" \) -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/vendor/*' | head -30
+   ```
+   Identify the top-level source directories from the results.
+3. Scan the detected source directories for files related to this feature; read each one
+4. Write `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`:
    - **Section 1 — Feature Brief**: feature description + acceptance criteria (copy from above)
    - **Section 2 — Project Structure**: run the following to get a visual directory tree, then paste output:
      ```bash
@@ -111,12 +116,12 @@ If MISSING — build it now:
      ### Files to Modify
      | File | Why Needed | Key Interfaces |
      |------|-----------|----------------|
-     | `src/config.js` | Add runtime config layer | `config` (Zod object), `configSchema` |
+     | `<source-dir>/config.js` | Add runtime config layer | `config` (Zod object), `configSchema` |
 
      ### Files for Reference
      | File | Why Needed | Key Interfaces |
      |------|-----------|----------------|
-     | `src/security/permission-guard.js` | Permission check integration | `checkCommandPermission(userId, cmd)` |
+     | `<source-dir>/security/permission-guard.js` | Permission check integration | `checkCommandPermission(userId, cmd)` |
 
      ### Known TRAPS (from .prizm-docs/)
      - <trap entries extracted from L1/L2 docs>
@@ -139,7 +144,50 @@ Before proceeding past CP-1, verify:
 
 **CP-1**: plan.md exists with Tasks section.
 
-### Phase 3: Implement — Dev Subagent
+### Phase 3: Analyze — Reviewer Subagent
+
+Spawn Reviewer agent (Agent tool, subagent_type="prizm-dev-team-reviewer", run_in_background=false).
+
+Prompt:
+> "Read {{REVIEWER_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
+> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST — Section 3 has project context, Section 4 has file manifest.
+> 2. Run prizmkit-analyze: cross-check `plan.md` (including Tasks section) against feature description and acceptance criteria for consistency.
+> 3. Before flagging CRITICAL or HIGH issues, read the relevant source files listed in the File Manifest to verify.
+> Report: CRITICAL, HIGH, MEDIUM issues found (or 'No issues found')."
+
+Wait for Reviewer to return.
+- If CRITICAL issues found: fix them yourself — read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` for full project context. Fix ONLY the listed CRITICAL issues in plan.md. Then re-run analyze (max 1 round).
+
+**CP-2**: No CRITICAL issues.
+
+{{IF_CRITIC_ENABLED}}
+### Phase 3.5: Plan Challenge — Critic Agent
+
+**Guard**: Verify critic agent file exists before spawning:
+```bash
+ls {{CRITIC_SUBAGENT_PATH}} 2>/dev/null && echo "CRITIC:READY" || echo "CRITIC:MISSING"
+```
+If CRITIC:MISSING — skip Phase 3.5 entirely and proceed to Phase 4. Log: "Critic agent not installed — skipping Plan Challenge."
+
+Spawn Critic agent (Agent tool, subagent_type="prizm-dev-team-critic", run_in_background=false).
+
+Prompt:
+> "Read {{CRITIC_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
+> **MODE: Plan Challenge**
+> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST — Section 3 has project context, Section 4 has file manifest.
+> 2. Read `.prizm-docs/root.prizm` and relevant L1/L2 docs for affected modules.
+> 3. Read existing source files in the modules this plan touches.
+> 4. Challenge plan.md against the project's existing architecture, patterns, and style.
+> Write `.prizmkit/specs/{{FEATURE_SLUG}}/challenge-report.md` with findings (or 'No significant challenges')."
+
+Wait for Critic to return.
+- Read challenge-report.md. For items marked CRITICAL/HIGH: decide whether to adjust plan.md or document why the plan stands.
+- Max 1 plan revision round.
+
+**CP-2.5**: Plan challenges reviewed and resolved.
+{{END_IF_CRITIC_ENABLED}}
+
+### Phase 4: Implement — Dev Subagent
 
 **Build artifacts rule** (passed to Dev): After any build/compile command (`go build`, `npm run build`, `tsc`, etc.), ensure the output binary or build directory is in `.gitignore`. Never commit compiled binaries, build output, or generated artifacts.
 
@@ -171,7 +219,34 @@ grep -q "## Implementation Log" .prizmkit/specs/{{FEATURE_SLUG}}/context-snapsho
 ```
 If GATE:MISSING — send message to Dev (re-spawn if needed): "Write the '## Implementation Log' section to context-snapshot.md before I can proceed to review. Include: files changed/created, key decisions, deviations from plan, notable discoveries."
 
-### Phase 4: Review + Test — Reviewer Subagent
+{{IF_CRITIC_ENABLED}}
+### Phase 4.5: Code Challenge — Critic Agent
+
+**Guard**: Verify critic agent file exists before spawning:
+```bash
+ls {{CRITIC_SUBAGENT_PATH}} 2>/dev/null && echo "CRITIC:READY" || echo "CRITIC:MISSING"
+```
+If CRITIC:MISSING — skip Phase 4.5 entirely and proceed to Phase 5. Log: "Critic agent not installed — skipping Code Challenge."
+
+Spawn Critic agent (Agent tool, subagent_type="prizm-dev-team-critic", run_in_background=false).
+
+Prompt:
+> "Read {{CRITIC_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
+> **MODE: Code Challenge**
+> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — Implementation Log section shows what Dev changed.
+> 2. Read `.prizm-docs/root.prizm` and relevant module docs for RULES/PATTERNS.
+> 3. Read the actual source files changed (from Implementation Log).
+> 4. Read comparable existing source files in the same module for style comparison.
+> 5. Challenge code integration quality: style fit, robustness, existing code cohesion, hidden impact.
+> Write `.prizmkit/specs/{{FEATURE_SLUG}}/challenge-report.md` (overwrite) with findings (or 'No significant challenges')."
+
+Wait for Critic to return.
+- Read challenge-report.md. For items marked CRITICAL/HIGH: spawn Dev to fix, then proceed to Review.
+
+**CP-3.5**: Code challenges reviewed and resolved.
+{{END_IF_CRITIC_ENABLED}}
+
+### Phase 5: Review + Test — Reviewer Subagent
 
 Spawn Reviewer subagent (Agent tool, subagent_type="prizm-dev-team-reviewer", run_in_background=false).
 
@@ -198,29 +273,29 @@ If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write the '#
 
 - If NEEDS_FIXES: spawn Dev to fix (Dev reads Fix Instructions in snapshot), re-run Review (max 3 rounds)
 
-**CP-2**: Tests pass, verdict is not NEEDS_FIXES.
+**CP-3**: Tests pass, verdict is not NEEDS_FIXES.
 
-### Phase 5: Architecture Sync & Commit (SINGLE COMMIT)
+### Phase 6: Architecture Sync & Commit (SINGLE COMMIT)
 
-**5a.** Run `/prizmkit-retrospective` — maintains `.prizm-docs/` (architecture index):
+**6a.** Run `/prizmkit-retrospective` — maintains `.prizm-docs/` (architecture index):
 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. **Architecture knowledge** (feature sessions only): Extract TRAPS/RULES/DECISIONS from completed work into `.prizm-docs/`
 3. Stage doc changes: `git add .prizm-docs/`
 ⚠️ Do NOT commit here. Only stage.
 
-**5b.** Stage all feature code explicitly (NEVER use `git add -A` or `git add .`):
+**6b.** Stage all feature code explicitly (NEVER use `git add -A` or `git add .`):
 ```bash
 git add <specific-files-created-or-modified>
 git add .prizm-docs/
 ```
 
-**5c.** Run `/prizmkit-committer` → THE ONLY commit for this feature:
+**6c.** Run `/prizmkit-committer` → THE ONLY commit for this feature:
 `feat({{FEATURE_ID}}): {{FEATURE_TITLE}}`
 This single commit includes: feature code + tests + .prizm-docs/ updates. 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.
 
-**5d.** Final verification:
+**6d.** Final verification:
 ```bash
 git status --short
 ```
@@ -234,6 +309,9 @@ Working tree MUST be clean after this step. If any feature-related files remain,
 | Context Snapshot | `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` |
 | Dev Agent Def | {{DEV_SUBAGENT_PATH}} |
 | Reviewer Agent Def | {{REVIEWER_SUBAGENT_PATH}} |
+{{IF_CRITIC_ENABLED}}
+| Critic Agent Def | {{CRITIC_SUBAGENT_PATH}} |
+{{END_IF_CRITIC_ENABLED}}
 | Project Root | {{PROJECT_ROOT}} |
 
 ## Failure Capture Protocol
@@ -260,13 +338,13 @@ rm -f .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md
 
 ## Reminders
 
-- Tier 2: orchestrator builds context+plan, Dev implements, Reviewer reviews+tests — use direct Agent spawn for agents
+- Tier 2: orchestrator builds context+plan, Analyzer checks consistency, Dev implements, Reviewer reviews+tests — use direct Agent spawn for agents
 - Build context-snapshot.md FIRST; all subagents read it instead of re-reading source files
 - context-snapshot.md is append-only: orchestrator writes Sections 1-4, Dev appends Implementation Log, Reviewer appends Review Notes
 - Gate checks enforce Implementation Log and Review Notes are written before proceeding
 - Do NOT use `run_in_background=true` when spawning subagents
 - `/prizmkit-committer` is mandatory, and must not be replaced with manual git commit commands
-- Do NOT run `git add`/`git commit` during Phase 1-4 — all changes are committed once in Phase 5
+- Do NOT run `git add`/`git commit` during Phase 1-5 — all changes are committed once in Phase 6
 - If any files remain after the commit, amend the existing commit — do NOT create a follow-up commit
 - When staging files, always use explicit file names — NEVER use `git add -A` or `git add .`
 - On timeout: check snapshot + git diff HEAD → model:lite → remaining steps only → max 2 retries per phase → orchestrator fallback