@the-bearded-bear/claude-craft 8.3.1 → 8.3.2-next.989ef26

package/README.md

@@ -12,6 +12,7 @@ A comprehensive framework for AI-assisted development with [Claude Code](https:/
 
 ## What's New in v8.3 (Audit-driven release: tokens + security)
 
+- **Sprint 1-4 audit-driven improvements** (v8.3.2) -- new `@paperclip-reviewer` agent, `cli/lib/path-safety.js` shared module, `claude-craft doctor` enforces Claude Code 2.1.97+ baseline with OS-specific yq install hints, ralph.sh refactored from 937 → 812 lines (`run_ralph()` -35%), auto-generated `AGENTS-FULL-REFERENCE.md` + `COMMANDS-FULL-REFERENCE.md`, governance + comparison docs. 809 vitest + 37 bats tests verts.
 - **Dependabot config fix** (v8.3.1) -- removed two erroneous ecosystems (`/cli/kanban/client` and `docker /`) introduced in v8.3.0 that caused Dependabot run failures
 - **Token optimization via `context: fork`** (v8.3.0) -- 15 heavy skills (>100 lines) now run in isolated contexts (Claude Code v2.1.105+), saving 8-15K tokens per long session
 - **CHANGELOG truncated** (v8.3.0) -- 117 KB → 67 KB shipped, archive moved to `docs/CHANGELOG-archive.md`
@@ -225,6 +226,32 @@ Step-by-step tutorials available in 5 languages:
 
 [All guides](docs/guides/index.md) | [Project Creation](docs/guides/en/02-project-creation.md) | [Tools Reference](docs/guides/en/05-tools-reference.md) | [Troubleshooting](docs/guides/en/06-troubleshooting.md) | [Backlog Management](docs/guides/en/07-backlog-management.md)
 
+## Project Governance & Sustainability
+
+Claude Craft is maintained by [The Bearded CTO](https://thebeardedcto.com), a solo founder with deep involvement in the AFUP and Symfony French ecosystem.
+
+| Item | Status |
+|------|--------|
+| **Funding model** | Bootstrapped — no VC, no sponsorships. Sustainability via consulting + future Pro support tier. |
+| **Maintenance commitment** | Active development since 2026-01. Targeting weekly minor releases, monthly minor versions. |
+| **Bus factor** | Currently 1 (solo maintainer). [Co-maintainer search open](CHARTER.md) — looking for one tech lead from the AFUP / Symfony / Flutter / React community. |
+| **Succession plan** | Documented in [CHARTER.md](CHARTER.md). MIT license guarantees indefinite community fork rights if maintainer disappears. |
+| **Roadmap visibility** | [GitHub Issues](https://github.com/TheBeardedBearSAS/claude-craft/issues) + [CHANGELOG.md](CHANGELOG.md) + recurring `audit/YYYY-MM-DD-*` reports |
+| **Decision process** | RFC via GitHub Discussions for breaking changes. ADRs in `docs/adr/` for architectural choices. |
+| **Security disclosure** | See [SECURITY.md](SECURITY.md). 90-day disclosure timeline, GPG-signed advisories. |
+| **License upgrade path** | MIT (free, perpetual). A future Commercial license is documented in `LICENSE-COMMERCIAL.md` (DRAFT) for support contracts; never restrictive of MIT rights. |
+
+### For Enterprise Adopters
+
+If you're considering Claude Craft for a team of 5+ developers and need :
+
+- **SLA-backed support** with response times
+- **Custom integration** for your stack
+- **Onboarding consulting** for your team
+- **DPA** (Data Processing Agreement) for RGPD compliance
+
+Contact `flavien.metivier@gmail.com` to discuss a Pro support agreement. Pricing is project-based (no per-seat licensing).
+
 ## Contributing
 
 Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md).

package/Tools/Ralph/lib/dependencies.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+set -euo pipefail
+# =============================================================================
+# Ralph Wiggum — Dependency check module
+#
+# Extracted from ralph.sh in audit-driven release v8.3.x (ARCH-002 partial).
+# Single responsibility: ensure required CLI tools are present before the
+# main loop starts. Optional tools (git, yq) are warned about but not
+# treated as failures.
+#
+# This file is sourced by ralph.sh::load_modules(). It depends on the
+# `print_*` helpers and the `MSG_*` strings already loaded by ralph.sh
+# before this module runs.
+# =============================================================================
+
+ralph_check_dependencies() {
+    local missing=()
+
+    # Required: claude — the agent loop literally cannot run without it.
+    if ! command -v claude &> /dev/null; then
+        missing+=("claude")
+    fi
+
+    # Required: jq — used everywhere to parse Claude's JSON output and to read
+    # session state files.
+    if ! command -v jq &> /dev/null; then
+        missing+=("jq")
+    fi
+
+    # Optional: git is recommended for the checkpoint/recovery feature but
+    # the loop can still run without it (no auto-commit, no rollback).
+    if ! command -v git &> /dev/null; then
+        print_warning "${MSG_ERROR_GIT_NOT_FOUND:-git not found — checkpoint feature disabled}"
+    fi
+
+    # Optional: yq is used by the YAML config loader. Tip-only — the loop
+    # falls back to defaults when ralph.yml is absent.
+    if ! command -v yq &> /dev/null; then
+        print_verbose "${MSG_ERROR_YQ_NOT_FOUND:-yq not found — YAML config disabled}"
+    fi
+
+    if [[ ${#missing[@]} -gt 0 ]]; then
+        print_error "${MSG_ERROR:-Error}: Missing required dependencies: ${missing[*]}"
+        exit 1
+    fi
+}
+
+# Backwards-compat alias: ralph.sh originally called `check_dependencies`.
+# Keep both names available so we don't break callers that source the lib
+# directly.
+check_dependencies() {
+    ralph_check_dependencies "$@"
+}

package/Tools/Ralph/lib/loop-finalizer.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+set -euo pipefail
+# =============================================================================
+# Ralph Wiggum — Post-loop finalisation
+#
+# Extracted from ralph.sh::run_ralph() (lines 688-741) in audit-driven release
+# v8.3.x (Sprint 4 deep refactor of ARCH-002). This block runs once after the
+# main while-loop exits. It is a sequence of one-way calls to finalise every
+# observability subsystem and persist the session — none of these calls feed
+# back into the loop, which is what makes the extraction safe.
+#
+# Sourced by ralph.sh::load_modules(). Depends on functions provided by
+# previously-loaded modules:
+#   - save_sprint_progress           → sprint-progress.sh
+#   - save_metrics_export            → metrics-exporter.sh
+#   - aggregate_session_metrics      → metrics-exporter.sh
+#   - record_circuit_breaker_outcome → circuit-breaker.sh
+#   - finalize_dashboard             → dashboard.sh
+#   - print_summary                  → ralph.sh (defined locally, sourced)
+#   - save_session                   → session.sh
+#   - print_warning                  → ralph.sh (helper)
+#
+# Reads global variables MAX_ITERATIONS, MSG_CB_MAX_REACHED, CB_ADAPTIVE_ENABLED,
+# CB_CURRENT_PROFILE — each owned by parse_args/load_messages/circuit-breaker.sh
+# respectively, never mutated here.
+# =============================================================================
+
+# Run all post-loop finalisation steps and exit with the appropriate code.
+#
+# Arguments:
+#   $1 session_id   — current Ralph session identifier
+#   $2 iteration    — final iteration count (1-based)
+#   $3 dod_passed   — "true" if Definition of Done validated, else "false"
+#   $4 exit_reason  — initial exit reason from the loop body (may be "")
+#   $5 start_time   — epoch seconds at loop start (for duration computation)
+#
+# Returns 0 if Definition of Done passed, 1 otherwise — same contract as the
+# original inline code.
+ralph_finalize_loop() {
+    local session_id="$1"
+    local iteration="$2"
+    local dod_passed="$3"
+    local exit_reason="$4"
+    local start_time="$5"
+
+    # Refine exit_reason if max iterations reached without DoD passing.
+    if [[ $iteration -ge $MAX_ITERATIONS && "$dod_passed" != "true" ]]; then
+        exit_reason="max_iterations"
+        print_warning "${MSG_CB_MAX_REACHED}"
+    fi
+
+    # Calculate duration
+    local end_time
+    end_time=$(date +%s)
+    local duration=$((end_time - start_time))
+
+    # Save sprint progress before summary
+    if type save_sprint_progress &>/dev/null; then
+        save_sprint_progress "$session_id"
+    fi
+
+    # Save metrics export
+    if type save_metrics_export &>/dev/null; then
+        local final_status="completed"
+        [[ "$dod_passed" != "true" ]] && final_status="failed"
+        save_metrics_export "$session_id" "$final_status"
+    fi
+
+    # Aggregate metrics for history
+    if type aggregate_session_metrics &>/dev/null; then
+        aggregate_session_metrics "$session_id"
+    fi
+
+    # Record circuit breaker outcome for learning
+    if type record_circuit_breaker_outcome &>/dev/null && [[ "${CB_ADAPTIVE_ENABLED:-false}" == "true" ]]; then
+        local success="false"
+        [[ "$dod_passed" == "true" ]] && success="true"
+        record_circuit_breaker_outcome "${CB_CURRENT_PROFILE:-default}" "$success" "$iteration"
+    fi
+
+    # Finalize dashboard
+    if type finalize_dashboard &>/dev/null; then
+        local dash_status="completed"
+        [[ "$dod_passed" != "true" ]] && dash_status="failed"
+        [[ "$exit_reason" == "circuit_breaker" ]] && dash_status="interrupted"
+        finalize_dashboard "$dash_status"
+    fi
+
+    # Print summary
+    print_summary "$session_id" "$iteration" "$duration" "$dod_passed" "$exit_reason"
+
+    # Save final state
+    save_session "$session_id" "$exit_reason"
+
+    # Return appropriate exit code (preserves run_ralph's pre-refactor contract)
+    if [[ "$dod_passed" == "true" ]]; then
+        return 0
+    else
+        return 1
+    fi
+}

package/Tools/Ralph/lib/loop-init.sh

@@ -0,0 +1,97 @@
+#!/bin/bash
+set -euo pipefail
+# =============================================================================
+# Ralph Wiggum — Loop initialisation
+#
+# Extracted from ralph.sh::run_ralph() (lines 436-499) in audit-driven release
+# v8.3.x (Sprint 4 deep refactor of ARCH-002). Splits the original monolithic
+# init phase into two functions because session creation needs to happen in
+# between (it is the only step that produces SESSION_ID, which the post-session
+# inits then consume).
+#
+# Pattern:
+#   run_ralph()
+#     ralph_init_loop_pre_session             # Bloc A : metrics/dashboard/health/hooks
+#     create_session OR resume_session        # Bloc B : produces SESSION_ID (stays inline)
+#     ralph_init_loop_post_session "$SESSION_ID"  # Bloc C : circuit breaker, autonomous, context manager
+#
+# Sourced by ralph.sh::load_modules(). Depends on functions provided by
+# previously-loaded modules:
+#   - init_metrics_exporter            → metrics-exporter.sh
+#   - init_dashboard                   → dashboard.sh
+#   - init_health_monitor              → health-monitor.sh
+#   - init_hooks                       → hooks-generator.sh
+#   - init_circuit_breaker             → circuit-breaker.sh
+#   - enable_autonomous_mode           → circuit-breaker.sh
+#   - init_recovery_engine             → recovery-engine.sh
+#   - init_escalation_service          → escalation-service.sh
+#   - init_context_manager             → context-manager.sh
+#   - export_session_context_for_hooks → hooks-generator.sh
+#   - print_info, print_verbose        → ralph.sh (helpers)
+#
+# Reads global variables AUTONOMOUS_MODE, PROMPT, MAX_ITERATIONS, TIMEOUT,
+# MSG_STARTING_LOOP, MSG_SESSION_ID — owned by parse_args/load_messages, never
+# mutated here.
+# =============================================================================
+
+# Initialise observability subsystems that do NOT need a session id yet.
+# Idempotent if any module is missing (each call is type-guarded).
+ralph_init_loop_pre_session() {
+    if type init_metrics_exporter &>/dev/null; then
+        init_metrics_exporter
+    fi
+
+    if type init_dashboard &>/dev/null; then
+        init_dashboard
+    fi
+
+    if type init_health_monitor &>/dev/null; then
+        init_health_monitor
+    fi
+
+    if type init_hooks &>/dev/null; then
+        init_hooks
+    fi
+}
+
+# Initialise resilience and context subsystems that depend on the session id.
+# Must be called after the session has been created or resumed.
+#
+# Arguments:
+#   $1 session_id — Ralph session identifier, just produced by Bloc B.
+ralph_init_loop_post_session() {
+    local session_id="$1"
+
+    # Initialize circuit breaker — always present (loaded ahead of this module).
+    init_circuit_breaker
+
+    # Enable autonomous mode if requested
+    if [[ "${AUTONOMOUS_MODE:-false}" == "true" ]]; then
+        if type enable_autonomous_mode &>/dev/null; then
+            enable_autonomous_mode
+        fi
+
+        if type init_recovery_engine &>/dev/null; then
+            init_recovery_engine
+        fi
+
+        if type init_escalation_service &>/dev/null; then
+            init_escalation_service
+        fi
+    fi
+
+    # Initialize context manager (auto-compact)
+    if type init_context_manager &>/dev/null; then
+        init_context_manager
+    fi
+
+    print_info "${MSG_STARTING_LOOP}..."
+    print_verbose "${MSG_SESSION_ID}: $session_id"
+    print_verbose "Max iterations: $MAX_ITERATIONS"
+    print_verbose "Timeout: ${TIMEOUT}ms"
+
+    # Export session context for hooks
+    if type export_session_context_for_hooks &>/dev/null; then
+        export_session_context_for_hooks "$session_id" "STARTING" "$PROMPT"
+    fi
+}

package/Tools/Ralph/lib/loop-iteration.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+set -euo pipefail
+# =============================================================================
+# Ralph Wiggum — Per-iteration observability sinks
+#
+# Extracted from ralph.sh::run_ralph() (lines 644-669) in audit-driven release
+# v8.3.x (Sprint 4 deep refactor of ARCH-002). All calls in this module are
+# one-way observability sinks — nothing they produce is read by the rest of
+# the iteration body, which makes this the lowest-risk extraction candidate.
+#
+# Sourced by ralph.sh::load_modules(). Depends on functions provided by
+# previously-loaded modules:
+#   - update_session_metrics    → session.sh
+#   - record_iteration_end      → metrics-exporter.sh
+#   - record_health_data        → metrics-exporter.sh
+#   - check_health_patterns     → health-monitor.sh
+#   - print_health_warnings     → health-monitor.sh
+#   - create_checkpoint         → checkpoint.sh
+#
+# Each call site preserves the original `type X &>/dev/null` guards so a
+# missing module degrades gracefully (matches behaviour pre-refactor).
+# =============================================================================
+
+# Record metrics, health data, and a checkpoint at the end of one iteration.
+#
+# Arguments:
+#   $1 session_id     — current Ralph session identifier
+#   $2 iteration      — 1-based iteration counter
+#   $3 response       — last Claude response (used by the checkpoint)
+#   $4 invoke_status  — exit code from the last invoke_claude call
+#
+# Reads global associative array METRICS_DATA (declared by metrics-exporter.sh).
+# Side effects: writes session metrics, health JSON, checkpoint files under
+# the session directory. No return value.
+ralph_record_iteration_observability() {
+    local session_id="$1"
+    local iteration="$2"
+    local response="$3"
+    local invoke_status="$4"
+
+    # Update metrics — always present (session.sh is loaded before this module).
+    update_session_metrics "$session_id" "$iteration" "$response"
+
+    # Record iteration end for metrics
+    if type record_iteration_end &>/dev/null; then
+        record_iteration_end "$iteration"
+    fi
+
+    # Record health data
+    if type record_health_data &>/dev/null; then
+        local had_error="false"
+        [[ $invoke_status -ne 0 ]] && had_error="true"
+        record_health_data "$iteration" "$had_error" "${METRICS_DATA["last_context_usage"]:-0}" "${METRICS_DATA["iteration_${iteration}_duration"]:-0}"
+    fi
+
+    # Check health patterns
+    if type check_health_patterns &>/dev/null; then
+        if ! check_health_patterns; then
+            if type print_health_warnings &>/dev/null; then
+                print_health_warnings
+            fi
+        fi
+    fi
+
+    # Create checkpoint (async if configured)
+    create_checkpoint "$session_id" "$iteration"
+}

package/Tools/Ralph/ralph.sh

@@ -135,31 +135,18 @@ print_iteration() {
 # Dependency checks
 # =============================================================================
 
+# Implementation extracted to lib/dependencies.sh (audit ARCH-002 partial).
+# The function is provided once load_modules() sources that file. We keep a
+# light fallback here so `check_dependencies` remains callable even if the
+# module is missing for some reason — the fallback only checks `claude` and
+# exits with a clear message.
 check_dependencies() {
-    local missing=()
-
-    # Check for claude command
-    if ! command -v claude &> /dev/null; then
-        missing+=("claude")
-    fi
-
-    # Check for jq (JSON parsing)
-    if ! command -v jq &> /dev/null; then
-        missing+=("jq")
-    fi
-
-    # Check for git (optional but recommended for checkpointing)
-    if ! command -v git &> /dev/null; then
-        print_warning "${MSG_ERROR_GIT_NOT_FOUND}"
-    fi
-
-    # Check for yq (YAML parsing - optional)
-    if ! command -v yq &> /dev/null; then
-        print_verbose "${MSG_ERROR_YQ_NOT_FOUND}"
+    if declare -F ralph_check_dependencies > /dev/null; then
+        ralph_check_dependencies
+        return
     fi
-
-    if [[ ${#missing[@]} -gt 0 ]]; then
-        print_error "${MSG_ERROR}: Missing required dependencies: ${missing[*]}"
+    if ! command -v claude &> /dev/null; then
+        echo "Error: 'claude' CLI not found (lib/dependencies.sh missing too)" >&2
         exit 1
     fi
 }
@@ -176,6 +163,7 @@ load_modules() {
     # 4. ASC modules (recovery, escalation, parallel, conductor) loaded last
     local modules=(
         "utils"
+        "dependencies"
         "session"
         "loop"
         "dod-validator"
@@ -195,6 +183,9 @@ load_modules() {
         "escalation-service"
         "parallel-manager"
         "sprint-conductor"
+        "loop-init"
+        "loop-iteration"
+        "loop-finalizer"
     )
 
     for module in "${modules[@]}"; do
@@ -443,24 +434,12 @@ run_ralph() {
     local response=""
     local start_time=$(date +%s)
 
-    # Initialize v2.0 modules
-    if type init_metrics_exporter &>/dev/null; then
-        init_metrics_exporter
-    fi
-
-    if type init_dashboard &>/dev/null; then
-        init_dashboard
-    fi
-
-    if type init_health_monitor &>/dev/null; then
-        init_health_monitor
-    fi
-
-    if type init_hooks &>/dev/null; then
-        init_hooks
-    fi
+    # Pre-session initialisation (metrics, dashboard, health, hooks).
+    # Implementation extracted to lib/loop-init.sh in Sprint 4.
+    ralph_init_loop_pre_session
 
-    # Initialize or resume session
+    # Initialize or resume session — kept inline because it produces SESSION_ID
+    # (Bloc B per audit cartography), which both Bloc C and the loop body need.
     if [[ -n "$CONTINUE_SESSION" ]]; then
         SESSION_ID="$CONTINUE_SESSION"
         resume_session "$SESSION_ID" || {
@@ -473,40 +452,9 @@ run_ralph() {
         print_success "${MSG_SESSION_CREATED}: $SESSION_ID"
     fi
 
-    # Initialize circuit breaker
-    init_circuit_breaker
-
-    # Enable autonomous mode if requested
-    if [[ "$AUTONOMOUS_MODE" == "true" ]]; then
-        if type enable_autonomous_mode &>/dev/null; then
-            enable_autonomous_mode
-        fi
-
-        # Initialize recovery engine
-        if type init_recovery_engine &>/dev/null; then
-            init_recovery_engine
-        fi
-
-        # Initialize escalation service
-        if type init_escalation_service &>/dev/null; then
-            init_escalation_service
-        fi
-    fi
-
-    # Initialize context manager (auto-compact)
-    if type init_context_manager &>/dev/null; then
-        init_context_manager
-    fi
-
-    print_info "${MSG_STARTING_LOOP}..."
-    print_verbose "${MSG_SESSION_ID}: $SESSION_ID"
-    print_verbose "Max iterations: $MAX_ITERATIONS"
-    print_verbose "Timeout: ${TIMEOUT}ms"
-
-    # Export session context for hooks
-    if type export_session_context_for_hooks &>/dev/null; then
-        export_session_context_for_hooks "$SESSION_ID" "STARTING" "$PROMPT"
-    fi
+    # Post-session initialisation (circuit breaker, autonomous, context manager,
+    # hook context export). Also extracted to lib/loop-init.sh.
+    ralph_init_loop_post_session "$SESSION_ID"
 
     # Main loop
     while [[ $iteration -lt $MAX_ITERATIONS ]]; do
@@ -653,32 +601,9 @@ $PROMPT" "$TIMEOUT")
             fi
         fi
 
-        # Update metrics
-        update_session_metrics "$SESSION_ID" "$iteration" "$response"
-
-        # Record iteration end for metrics
-        if type record_iteration_end &>/dev/null; then
-            record_iteration_end "$iteration"
-        fi
-
-        # Record health data
-        if type record_health_data &>/dev/null; then
-            local had_error="false"
-            [[ $invoke_status -ne 0 ]] && had_error="true"
-            record_health_data "$iteration" "$had_error" "${METRICS_DATA["last_context_usage"]:-0}" "${METRICS_DATA["iteration_${iteration}_duration"]:-0}"
-        fi
-
-        # Check health patterns
-        if type check_health_patterns &>/dev/null; then
-            if ! check_health_patterns; then
-                if type print_health_warnings &>/dev/null; then
-                    print_health_warnings
-                fi
-            fi
-        fi
-
-        # Create checkpoint (async if configured)
-        create_checkpoint "$SESSION_ID" "$iteration"
+        # Per-iteration observability sinks (metrics, health, checkpoint).
+        # Implementation extracted to lib/loop-iteration.sh in Sprint 4.
+        ralph_record_iteration_observability "$SESSION_ID" "$iteration" "$response" "$invoke_status"
 
         # Check Definition of Done
         print_info "${MSG_DOD_CHECKING}"
@@ -719,60 +644,10 @@ $PROMPT" "$TIMEOUT")
         fi
     done
 
-    # Check if max iterations reached
-    if [[ $iteration -ge $MAX_ITERATIONS && "$dod_passed" != "true" ]]; then
-        exit_reason="max_iterations"
-        print_warning "${MSG_CB_MAX_REACHED}"
-    fi
-
-    # Calculate duration
-    local end_time=$(date +%s)
-    local duration=$((end_time - start_time))
-
-    # Save sprint progress before summary
-    if type save_sprint_progress &>/dev/null; then
-        save_sprint_progress "$SESSION_ID"
-    fi
-
-    # Save metrics export
-    if type save_metrics_export &>/dev/null; then
-        local final_status="completed"
-        [[ "$dod_passed" != "true" ]] && final_status="failed"
-        save_metrics_export "$SESSION_ID" "$final_status"
-    fi
-
-    # Aggregate metrics for history
-    if type aggregate_session_metrics &>/dev/null; then
-        aggregate_session_metrics "$SESSION_ID"
-    fi
-
-    # Record circuit breaker outcome for learning
-    if type record_circuit_breaker_outcome &>/dev/null && [[ "$CB_ADAPTIVE_ENABLED" == "true" ]]; then
-        local success="false"
-        [[ "$dod_passed" == "true" ]] && success="true"
-        record_circuit_breaker_outcome "$CB_CURRENT_PROFILE" "$success" "$iteration"
-    fi
-
-    # Finalize dashboard
-    if type finalize_dashboard &>/dev/null; then
-        local dash_status="completed"
-        [[ "$dod_passed" != "true" ]] && dash_status="failed"
-        [[ "$exit_reason" == "circuit_breaker" ]] && dash_status="interrupted"
-        finalize_dashboard "$dash_status"
-    fi
-
-    # Print summary
-    print_summary "$SESSION_ID" "$iteration" "$duration" "$dod_passed" "$exit_reason"
-
-    # Save final state
-    save_session "$SESSION_ID" "$exit_reason"
-
-    # Return appropriate exit code
-    if [[ "$dod_passed" == "true" ]]; then
-        return 0
-    else
-        return 1
-    fi
+    # Post-loop finalisation (sprint progress, metrics, dashboard, session save).
+    # Implementation extracted to lib/loop-finalizer.sh in Sprint 4. The function
+    # returns 0 if DoD passed, 1 otherwise — same exit contract as before.
+    ralph_finalize_loop "$SESSION_ID" "$iteration" "$dod_passed" "$exit_reason" "$start_time"
 }
 
 # =============================================================================

package/cli/lib/doctor.js

@@ -5,10 +5,67 @@
 
 import fs from 'fs';
 import path from 'path';
+import os from 'os';
 import { execSync } from 'child_process';
 import c from './colors.js';
 import { listDirs } from './fs-utils.js';
 
+// Single source of truth for the security baseline. Bumped from 2.1.47 in v8.3.0
+// after CVE-2025-59536 (CVSS 8.7) cumulative hardening completed in 2.1.97.
+const MIN_CLAUDE_CODE = '2.1.97';
+const RECOMMENDED_CLAUDE_CODE = '2.1.117';
+
+/**
+ * Compare two semver-ish version strings (`major.minor.patch`).
+ * Returns -1 if a < b, 0 if equal, 1 if a > b.
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1|0|1}
+ */
+function semverCmp(a, b) {
+  const pa = a.split('.').map((n) => parseInt(n, 10));
+  const pb = b.split('.').map((n) => parseInt(n, 10));
+  for (let i = 0; i < 3; i++) {
+    const da = pa[i] || 0;
+    const db = pb[i] || 0;
+    if (da !== db) return da < db ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * Extract the first `X.Y.Z` triple from a free-form `claude --version` output.
+ * @param {string} output
+ * @returns {string|null}
+ */
+function extractSemver(output) {
+  const m = output.match(/(\d+)\.(\d+)\.(\d+)/);
+  return m ? m[0] : null;
+}
+
+/**
+ * OS-specific yq installation hints. Returned as a list of one-liner instructions
+ * that the user can copy/paste.
+ * @returns {string[]}
+ */
+function yqInstallHints() {
+  const platform = os.platform();
+  if (platform === 'darwin') {
+    return ['brew install yq'];
+  }
+  if (platform === 'linux') {
+    return [
+      'sudo apt-get install yq           # Debian/Ubuntu (snap version)',
+      'sudo snap install yq              # Snap (Mike Farah build, recommended)',
+      'wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq && chmod +x /usr/local/bin/yq',
+    ];
+  }
+  if (platform === 'win32') {
+    return ['winget install --id MikeFarah.yq  # Windows native', 'Or use WSL: see Linux instructions above'];
+  }
+  return ['See https://github.com/mikefarah/yq#install for your platform'];
+}
+
 /**
  * Run a shell command and return the trimmed output, or null on failure.
  * @param {string} cmd - Shell command to execute
@@ -58,13 +115,28 @@ function runDoctor(targetPath, deps = {}) {
     failed++;
   }
 
-  // 3. Claude Code installed
-  const claudeVer = exec('claude --version');
-  if (claudeVer) {
-    console.log(`  ${c.green}[OK]${c.reset} Claude Code ${claudeVer}`);
-    passed++;
+  // 3. Claude Code installed and >= 2.1.97 (CVE-2025-59536 baseline)
+  const claudeVerRaw = exec('claude --version');
+  if (claudeVerRaw) {
+    const semver = extractSemver(claudeVerRaw);
+    if (semver && semverCmp(semver, MIN_CLAUDE_CODE) < 0) {
+      console.log(
+        `  ${c.red}[FAIL]${c.reset} Claude Code ${semver} — requires >= ${MIN_CLAUDE_CODE} (CVE-2025-59536, CVSS 8.7)`
+      );
+      console.log(`         Upgrade: ${c.cyan}npm install -g @anthropic-ai/claude-code@latest${c.reset}`);
+      failed++;
+    } else if (semver && semverCmp(semver, RECOMMENDED_CLAUDE_CODE) < 0) {
+      console.log(
+        `  ${c.yellow}[WARN]${c.reset} Claude Code ${semver} — recommended ${RECOMMENDED_CLAUDE_CODE} (forked subagents, native CLI)`
+      );
+      warned++;
+    } else {
+      console.log(`  ${c.green}[OK]${c.reset} Claude Code ${semver || claudeVerRaw}`);
+      passed++;
+    }
   } else {
     console.log(`  ${c.yellow}[WARN]${c.reset} Claude Code not found (optional for install, required for usage)`);
+    console.log(`         Install: ${c.cyan}npm install -g @anthropic-ai/claude-code${c.reset}`);
     warned++;
   }
 
@@ -78,13 +150,18 @@ function runDoctor(targetPath, deps = {}) {
     failed++;
   }
 
-  // 5. yq available (Mike Farah version)
+  // 5. yq available (Mike Farah version) — required for monorepo YAML config (claude-projects.yaml)
   const yqVer = exec('yq --version');
   if (yqVer) {
     console.log(`  ${c.green}[OK]${c.reset} ${yqVer}`);
     passed++;
   } else {
-    console.log(`  ${c.yellow}[WARN]${c.reset} yq not found (required for YAML config)`);
+    console.log(
+      `  ${c.yellow}[WARN]${c.reset} yq not found (required for monorepo YAML config — claude-projects.yaml)`
+    );
+    for (const hint of yqInstallHints()) {
+      console.log(`         ${c.cyan}${hint}${c.reset}`);
+    }
     warned++;
   }
 

package/cli/lib/installer.js

@@ -9,6 +9,7 @@ import { spawnSync } from 'child_process';
 import c from './colors.js';
 import { TECHNOLOGIES, LANGUAGES } from './constants.js';
 import { printBanner, printSuccess } from './banner.js';
+import { assertSafeTarget } from './path-safety.js';
 
 /**
  * Execute a shell script synchronously via bash.
@@ -49,10 +50,16 @@ export async function interactiveInstall(cli, { CLI_ROOT, VERSION }) {
     console.log(`${c.cyan}[1/5]${c.reset} ${c.bold}Target Directory${c.reset}`);
     const defaultPath = process.cwd();
     const targetInput = await cli.prompt(`  Enter path (${c.dim}${defaultPath}${c.reset}): `);
-    cli.config.targetPath = targetInput || defaultPath;
+    const rawTarget = targetInput || defaultPath;
 
-    // Resolve and validate path
-    cli.config.targetPath = path.resolve(cli.config.targetPath);
+    // Security: reject system directories (/, /etc, /usr, /bin, …) before any side effect.
+    try {
+      cli.config.targetPath = assertSafeTarget(rawTarget);
+    } catch (err) {
+      console.log(`  ${c.red}${err.message}${c.reset}`);
+      cli.closeReadline();
+      return;
+    }
     if (!fs.existsSync(cli.config.targetPath)) {
       console.log(`  ${c.yellow}Directory doesn't exist. Create it? (y/n)${c.reset}`);
       const create = await cli.prompt('  ');

package/cli/lib/path-safety.js

@@ -0,0 +1,74 @@
+/**
+ * Path and argument safety helpers shared by all CLI commands.
+ *
+ * Exists to enforce a single authoritative implementation of the security
+ * checks that protect against CWE-22 (path traversal) and CWE-78 (argument
+ * injection). Originally inlined in `cli/lib/update.js` after the 2026-04-23
+ * security audit; extracted here in v8.3.x so installer/doctor/list and any
+ * future command can reuse the same guard rails.
+ *
+ * @module cli/lib/path-safety
+ */
+
+import path from 'path';
+
+/**
+ * System directories Claude Craft must never write into. Refusing these
+ * targets prevents both accidental nukes (typo `--target=/`) and malicious
+ * exploitation of an `--target` value supplied by an untrusted caller.
+ */
+export const FORBIDDEN_SYSTEM_DIRS = Object.freeze([
+  '/',
+  '/etc',
+  '/usr',
+  '/bin',
+  '/sbin',
+  '/boot',
+  '/lib',
+  '/var',
+  '/root',
+  '/proc',
+  '/sys',
+  '/dev',
+]);
+
+/**
+ * Resolve `targetPath` to an absolute path and refuse it if it points to a
+ * forbidden system directory.
+ *
+ * Resolution is intentional: a relative path like `./../../etc` must be
+ * normalised before being compared, otherwise an attacker could bypass the
+ * check by supplying a syntactic relative form.
+ *
+ * @param {string} targetPath - Path supplied by the caller (relative or absolute).
+ * @returns {string} The resolved absolute path, safe to use as a target.
+ * @throws {Error} If the resolved path is `/` or any subtree of a forbidden directory.
+ */
+export function assertSafeTarget(targetPath) {
+  if (typeof targetPath !== 'string' || targetPath.length === 0) {
+    throw new Error('Target path must be a non-empty string');
+  }
+  const resolved = path.resolve(targetPath);
+  for (const forbidden of FORBIDDEN_SYSTEM_DIRS) {
+    if (resolved === forbidden || resolved.startsWith(forbidden + path.sep)) {
+      throw new Error(`Refusing to operate on system directory: ${resolved}`);
+    }
+  }
+  return resolved;
+}
+
+/**
+ * Validate a two-letter ISO 639-1 language code. Used to ensure the `--lang`
+ * value cannot be turned into argument injection on the bash scripts called
+ * via `spawnSync`.
+ *
+ * @param {string} lang - Language code to validate (e.g. `fr`).
+ * @returns {string} The same code if valid.
+ * @throws {Error} If `lang` is not exactly two lowercase ASCII letters.
+ */
+export function assertSafeLang(lang) {
+  if (!/^[a-z]{2}$/.test(lang)) {
+    throw new Error(`Invalid --lang value: "${lang}" (expected 2-letter lowercase code)`);
+  }
+  return lang;
+}

package/cli/lib/update.js

@@ -9,41 +9,7 @@ import { spawnSync } from 'child_process';
 import c from './colors.js';
 import { listDirs } from './fs-utils.js';
 import { TECH_REGISTRY } from './tech-registry.js';
-
-// Security: reject paths into system directories to prevent accidental or malicious
-// installation outside the user's expected workspace.
-const FORBIDDEN_SYSTEM_DIRS = [
-  '/',
-  '/etc',
-  '/usr',
-  '/bin',
-  '/sbin',
-  '/boot',
-  '/lib',
-  '/var',
-  '/root',
-  '/proc',
-  '/sys',
-  '/dev',
-];
-
-function assertSafeTarget(targetPath) {
-  const resolved = path.resolve(targetPath);
-  for (const forbidden of FORBIDDEN_SYSTEM_DIRS) {
-    if (resolved === forbidden || resolved.startsWith(forbidden + path.sep)) {
-      throw new Error(`Refusing to operate on system directory: ${resolved}`);
-    }
-  }
-  return resolved;
-}
-
-// Security: enforce allowlist on language code (prevents argument injection via --lang).
-function assertSafeLang(lang) {
-  if (!/^[a-z]{2}$/.test(lang)) {
-    throw new Error(`Invalid --lang value: "${lang}" (expected 2-letter lowercase code)`);
-  }
-  return lang;
-}
+import { assertSafeTarget, assertSafeLang } from './path-safety.js';
 
 /**
  * Run the update command against a target directory.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-bearded-bear/claude-craft",
-  "version": "8.3.1",
+  "version": "8.3.2-next.989ef26",
   "description": "A comprehensive framework for AI-assisted development with Claude Code. Install standardized rules, agents, and commands for your projects.",
   "type": "module",
   "main": "cli/index.js",
@@ -19,6 +19,8 @@
     "lint:fix": "eslint cli/ --fix",
     "lint:shell": "find Dev/ Infra/ Project/ Tools/ scripts/ .bmad/ -name '*.sh' -type f | xargs shellcheck --severity=warning",
     "lint:i18n": "bash scripts/verify-i18n-parity.sh",
+    "docs:generate": "node scripts/generate-references.mjs",
+    "docs:check": "node scripts/generate-references.mjs --check",
     "format:check": "prettier --check cli/",
     "format": "prettier --write cli/",
     "kanban:build": "vite build --config cli/kanban/client/vite.config.js",