autonomous-coding-toolkit 1.0.0

package/scripts/auto-compound.sh

@@ -0,0 +1,273 @@
+#!/usr/bin/env bash
+# auto-compound.sh — Automated Code Factory pipeline
+#
+# Usage: auto-compound.sh <project-dir> [--report <file>] [--dry-run] [--max-iterations N]
+#
+# Pipeline:
+#   1. Analyze report → pick #1 priority (analyze-report.sh)
+#   2. Generate PRD → create prd.json with acceptance criteria (claude /create-prd)
+#   3. Create branch → compound/<feature-slug>
+#   4. Run Ralph loop → iterate until all tasks pass
+#   5. Push branch → open PR for review
+#
+# Requires: claude CLI, jq, gh, ollama
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
+source "$SCRIPT_DIR/lib/common.sh"
+source "$SCRIPT_DIR/lib/ollama.sh"
+PROJECT_DIR="${1:-}"
+REPORT_FILE=""
+DRY_RUN=false
+MAX_ITERATIONS=25
+MODEL="deepseek-r1:8b"
+
+# Parse args
+shift || true
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --report) REPORT_FILE="$2"; shift 2 ;;
+    --dry-run) DRY_RUN=true; shift ;;
+    --max-iterations) MAX_ITERATIONS="$2"; shift 2 ;;
+    --model) MODEL="$2"; shift 2 ;;
+    -h|--help)
+      cat <<'EOF'
+auto-compound.sh — Automated Code Factory pipeline
+
+USAGE:
+  auto-compound.sh <project-dir> [OPTIONS]
+
+OPTIONS:
+  --report <file>        Path to report file (default: latest in reports/)
+  --dry-run              Show what would happen without executing
+  --max-iterations <n>   Max Ralph loop iterations (default: 25)
+  --model <name>         Ollama model for analysis (default: deepseek-r1:8b)
+
+PIPELINE:
+  1. Analyze report → pick #1 priority
+  2. Generate PRD with machine-verifiable acceptance criteria
+  3. Create feature branch (compound/<slug>)
+  4. Run Ralph loop with quality gates
+  5. Push and open PR for review
+
+REPORT FORMAT:
+  Any markdown file in reports/ with issues, metrics, feedback.
+  See scripts/analyze-report.sh for details.
+EOF
+      exit 0
+      ;;
+    *) echo "Unknown option: $1" >&2; exit 1 ;;
+  esac
+done
+
+if [[ -z "$PROJECT_DIR" ]] || [[ ! -d "$PROJECT_DIR" ]]; then
+  echo "Error: Project directory required" >&2
+  echo "Usage: auto-compound.sh <project-dir> [--report <file>]" >&2
+  exit 1
+fi
+
+cd "$PROJECT_DIR"
+
+# Find report file
+if [[ -z "$REPORT_FILE" ]]; then
+  if [[ -d "reports" ]]; then
+    REPORT_FILE=$(find reports/ -name '*.md' -printf '%T@ %p\n' 2>/dev/null | sort -rn | head -1 | cut -d' ' -f2-)
+  fi
+fi
+
+if [[ -z "$REPORT_FILE" ]] || [[ ! -f "$REPORT_FILE" ]]; then
+  echo "Error: No report file found" >&2
+  echo "Provide --report <file> or place reports in reports/*.md" >&2
+  exit 1
+fi
+
+echo "═══════════════════════════════════════════════"
+echo "  Code Factory Pipeline"
+echo "═══════════════════════════════════════════════"
+echo "Project:    $PROJECT_DIR"
+echo "Report:     $REPORT_FILE"
+echo "Model:      $MODEL"
+echo "Max iters:  $MAX_ITERATIONS"
+echo "═══════════════════════════════════════════════"
+echo ""
+
+# Step 1: Analyze report
+echo "📊 Step 1: Analyzing report..."
+if [[ "$DRY_RUN" == "true" ]]; then
+  echo "  [dry-run] Would analyze $REPORT_FILE with $MODEL"
+  PRIORITY="example-feature"
+  FEATURE_SLUG="example-feature"
+else
+  "$SCRIPT_DIR/analyze-report.sh" "$REPORT_FILE" --model "$MODEL" --output-dir .
+  PRIORITY=$(jq -r '.priority' analysis.json)
+  # Create slug from priority
+  FEATURE_SLUG=$(echo "$PRIORITY" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | cut -c1-40)
+fi
+echo "  Priority: $PRIORITY"
+echo "  Branch:   compound/$FEATURE_SLUG"
+echo ""
+
+# Step 2: Create branch
+echo "🌿 Step 2: Creating branch..."
+BRANCH_NAME="compound/$FEATURE_SLUG"
+if [[ "$DRY_RUN" == "true" ]]; then
+  echo "  [dry-run] Would create branch: $BRANCH_NAME"
+else
+  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+fi
+echo ""
+
+# Step 2.5: Research phase
+echo "🔎 Step 2.5: Running research phase..."
+if [[ "$DRY_RUN" == "true" ]]; then
+  echo "  [dry-run] Would research: $PRIORITY"
+else
+  mkdir -p tasks
+  RESEARCH_SLUG=$(echo "$FEATURE_SLUG" | cut -c1-30)
+  RESEARCH_JSON="tasks/research-${RESEARCH_SLUG}.json"
+
+  # Run research via Claude (produces tasks/research-*.md and tasks/research-*.json)
+  research_output=$(claude --print "Use the research skill to investigate: $PRIORITY. Design context: $(cat analysis.json). Write findings to tasks/research-${RESEARCH_SLUG}.md and tasks/research-${RESEARCH_SLUG}.json" 2>&1) || {
+      echo "WARNING: Research phase failed (non-fatal):" >&2
+      echo "$research_output" | tail -10 >&2
+  }
+
+  # Check research gate
+  if [[ -f "$RESEARCH_JSON" ]]; then
+      "$SCRIPT_DIR/research-gate.sh" "$RESEARCH_JSON" || {
+          echo "BLOCKED: Unresolved research issues. Resolve or re-run with --force on research-gate.sh" >&2
+          exit 1
+      }
+      echo "  Research gate: clear"
+  else
+      echo "  No research JSON produced (continuing without research context)"
+  fi
+
+  # Append to progress.txt
+  echo "## Research: $PRIORITY" >> progress.txt
+  if [[ -f "$RESEARCH_JSON" ]]; then
+      jq -r '.recommended_approach // "No approach documented"' "$RESEARCH_JSON" >> progress.txt
+  fi
+  echo "" >> progress.txt
+fi
+echo ""
+
+# Step 3: Generate PRD
+echo "📋 Step 3: Generating PRD..."
+if [[ "$DRY_RUN" == "true" ]]; then
+  echo "  [dry-run] Would run: claude '/create-prd $PRIORITY'"
+  echo "  [dry-run] Would create tasks/prd.json"
+else
+  mkdir -p tasks
+  # Include research context if available
+  research_context=""
+  RESEARCH_SLUG=$(echo "$FEATURE_SLUG" | cut -c1-30)
+  RESEARCH_JSON="tasks/research-${RESEARCH_SLUG}.json"
+  if [[ -f "$RESEARCH_JSON" ]]; then
+      research_context=" Research findings: $(jq -c '{approach: .recommended_approach, warnings: .warnings, dependencies: .dependencies}' "$RESEARCH_JSON" 2>/dev/null || echo "{}")"
+  fi
+  # Use Claude to generate the PRD
+  prd_output=$(claude --print "/create-prd $PRIORITY. Context from analysis: $(cat analysis.json).$research_context" 2>&1) || {
+      echo "WARNING: PRD generation failed:" >&2
+      echo "$prd_output" | tail -10 >&2
+  }
+
+  if [[ ! -f "tasks/prd.json" ]]; then
+    echo "Warning: PRD generation didn't create tasks/prd.json" >&2
+    echo "You may need to run /create-prd manually" >&2
+  fi
+fi
+echo ""
+
+# Step 4: Configure quality checks
+echo "🔍 Step 4: Configuring quality checks..."
+QUALITY_GATE="$SCRIPT_DIR/quality-gate.sh"
+if [[ -x "$QUALITY_GATE" ]]; then
+  QUALITY_CHECKS="$QUALITY_GATE --project-root $PROJECT_DIR"
+  echo "  Using composite quality gate: $QUALITY_GATE"
+else
+  # Fallback: use detect_project_type if quality-gate.sh not available
+  project_type=$(detect_project_type "$PROJECT_DIR")
+  case "$project_type" in
+    python)  QUALITY_CHECKS="pytest --timeout=120 -x -q" ;;
+    node)
+      QUALITY_CHECKS=""
+      grep -q '"test"' package.json 2>/dev/null && QUALITY_CHECKS+="npm test"
+      grep -q '"lint"' package.json 2>/dev/null && { [[ -n "$QUALITY_CHECKS" ]] && QUALITY_CHECKS+=";"; QUALITY_CHECKS+="npm run lint"; }
+      ;;
+    make)    QUALITY_CHECKS="make test" ;;
+    *)       QUALITY_CHECKS="" ;;
+  esac
+  echo "  Fallback mode — quality-gate.sh not found"
+fi
+
+echo "  Quality checks: ${QUALITY_CHECKS:-none detected}"
+echo ""
+
+# Step 5: Run Ralph loop
+echo "🔄 Step 5: Starting Ralph loop..."
+if [[ "$DRY_RUN" == "true" ]]; then
+  echo "  [dry-run] Would run Ralph loop with:"
+  echo "    --max-iterations $MAX_ITERATIONS"
+  echo "    --quality-checks '$QUALITY_CHECKS'"
+  echo "    --prd tasks/prd.json"
+  echo "    --completion-promise 'ALL TASKS COMPLETE'"
+else
+  RALPH_ARGS="Implement the features in tasks/prd.json. Read prd.json, pick the next task where passes is false, implement it, verify acceptance criteria pass, update prd.json, commit, and move to the next task."
+  RALPH_ARGS+=" --max-iterations $MAX_ITERATIONS"
+  RALPH_ARGS+=" --completion-promise 'ALL TASKS COMPLETE'"
+
+  if [[ -n "$QUALITY_CHECKS" ]]; then
+    RALPH_ARGS+=" --quality-checks '$QUALITY_CHECKS'"
+  fi
+
+  if [[ -f "tasks/prd.json" ]]; then
+    RALPH_ARGS+=" --prd tasks/prd.json"
+  fi
+
+  echo "  Running: /ralph-loop $RALPH_ARGS"
+  echo ""
+  echo "  Monitor progress:"
+  echo "    head -15 .claude/ralph-loop.local.md"
+  echo "    cat progress.txt"
+  echo "    jq '.[].passes' tasks/prd.json"
+  echo ""
+
+  # Launch Claude with Ralph loop
+  claude "/ralph-loop $RALPH_ARGS"
+fi
+echo ""
+
+# Step 6: Push and create PR
+echo "📤 Step 6: Pushing and creating PR..."
+if [[ "$DRY_RUN" == "true" ]]; then
+  echo "  [dry-run] Would push $BRANCH_NAME and create PR"
+else
+  if ! git push -u origin "$BRANCH_NAME" 2>&1; then
+    echo "ERROR: git push failed for branch $BRANCH_NAME" >&2
+    echo "  Check: authentication, remote availability, branch protection rules" >&2
+    exit 1
+  fi
+
+  # Create PR
+  PR_BODY="## Summary
+Auto-generated by Code Factory pipeline.
+
+**Priority:** $PRIORITY
+**Analysis:** See analysis.json
+**Tasks:** See tasks/prd.json
+
+## Quality Checks
+$QUALITY_CHECKS
+
+## Generated by
+\`auto-compound.sh\` → \`analyze-report.sh\` → \`/create-prd\` → \`/ralph-loop\`"
+
+  gh pr create --title "compound: $PRIORITY" --body "$PR_BODY" 2>/dev/null || echo "PR creation skipped (may already exist)"
+fi
+
+echo ""
+echo "═══════════════════════════════════════════════"
+echo "  Pipeline complete!"
+echo "═══════════════════════════════════════════════"

package/scripts/batch-audit.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Batch audit across all project repos
+# Usage: batch-audit.sh <projects-dir> [focus]
+# Focus: stale-refs | security | test-coverage | naming | lessons | full (default: stale-refs)
+
+set -euo pipefail
+
+PROJECTS_DIR="${1:-}"
+FOCUS="${2:-stale-refs}"
+
+if [[ -z "$PROJECTS_DIR" || ! -d "$PROJECTS_DIR" ]]; then
+    echo "Usage: batch-audit.sh <projects-dir> [focus]" >&2
+    echo "Focus options: stale-refs | security | test-coverage | naming | lessons | full" >&2
+    exit 1
+fi
+
+RESULTS_DIR="/tmp/batch-audit-$(date +%Y%m%d-%H%M%S)"
+mkdir -p "$RESULTS_DIR"
+
+echo "=== Batch Audit: $FOCUS ==="
+echo "Results: $RESULTS_DIR"
+echo ""
+
+for PROJECT_DIR in "$PROJECTS_DIR"/*/; do
+    [[ ! -d "$PROJECT_DIR" ]] && continue
+    project="$(basename "$PROJECT_DIR")"
+
+    echo "--- $project ---"
+    RESULT_FILE="$RESULTS_DIR/$project.txt"
+
+    claude -p "Run /audit $FOCUS on this project. Output the audit report only, no fixes." \
+        --allowedTools "Bash,Read,Grep,Glob" \
+        --cwd "$PROJECT_DIR" \
+        --output-format text > "$RESULT_FILE" 2>&1 || true
+
+    echo "  Findings saved to $RESULT_FILE"
+    echo ""
+done
+
+echo "=== Complete ==="
+echo "All results in: $RESULTS_DIR"
+echo "Quick view: cat $RESULTS_DIR/*.txt"

package/scripts/batch-test.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# Run tests across all projects with memory awareness
+# Usage: batch-test.sh <projects-dir> [project-name]
+#
+# Auto-detects test runner (pytest, npm test, make test) for each project.
+# Checks available memory before running — skips full suite if < 4GB available.
+# Exits non-zero if any project's tests fail. Reports summary.
+
+set -euo pipefail
+
+PROJECTS_DIR="${1:-}"
+TARGET="${2:-}"
+
+if [[ -z "$PROJECTS_DIR" || ! -d "$PROJECTS_DIR" ]]; then
+    echo "Usage: batch-test.sh <projects-dir> [project-name]" >&2
+    exit 1
+fi
+
+PASS_COUNT=0
+FAIL_COUNT=0
+SKIP_COUNT=0
+FAILED_PROJECTS=()
+
+check_memory() {
+    local avail_mb
+    avail_mb=$(free -m 2>/dev/null | awk '/Mem:/{print $7}') || avail_mb=0
+    if [[ -z "$avail_mb" || "$avail_mb" -lt 4000 ]]; then
+        echo "WARNING: Low memory (${avail_mb:-unknown}MB). Consider running targeted tests."
+        return 1
+    fi
+    return 0
+}
+
+run_project_tests() {
+    local project_dir="$1"
+    local project
+    project="$(basename "$project_dir")"
+
+    if [ ! -d "$project_dir" ]; then
+        echo "SKIP: $project (not found)"
+        SKIP_COUNT=$((SKIP_COUNT + 1))
+        return 0
+    fi
+
+    echo "=== $project ==="
+    local exit_code=0
+    (
+        cd "$project_dir"
+
+        # Auto-detect test runner
+        if [[ -f pyproject.toml || -f setup.py || -f pytest.ini ]]; then
+            if check_memory; then
+                .venv/bin/python -m pytest --timeout=120 -x -q 2>&1
+            else
+                echo "Low memory — running with reduced parallelism"
+                .venv/bin/python -m pytest --timeout=120 -x -q -n 0 2>&1
+            fi
+        elif [[ -f package.json ]] && grep -q '"test"' package.json 2>/dev/null; then
+            npm test 2>&1
+        elif [[ -f Makefile ]] && grep -q '^test:' Makefile 2>/dev/null; then
+            make test 2>&1
+        else
+            echo "  No test runner detected — skipped"
+            exit 2  # Signal "skipped" to caller
+        fi
+    ) || exit_code=$?
+
+    if [[ $exit_code -eq 2 ]]; then
+        SKIP_COUNT=$((SKIP_COUNT + 1))
+    elif [[ $exit_code -ne 0 ]]; then
+        FAIL_COUNT=$((FAIL_COUNT + 1))
+        FAILED_PROJECTS+=("$project")
+        echo "  FAILED (exit $exit_code)"
+    else
+        PASS_COUNT=$((PASS_COUNT + 1))
+    fi
+
+    echo ""
+    return 0  # Don't abort the loop — continue to next project
+}
+
+if [[ -n "$TARGET" ]]; then
+    run_project_tests "$PROJECTS_DIR/$TARGET"
+else
+    for d in "$PROJECTS_DIR"/*/; do
+        [[ -d "$d" ]] && run_project_tests "$d"
+    done
+fi
+
+echo "=== Summary ==="
+echo "  Passed: $PASS_COUNT"
+echo "  Failed: $FAIL_COUNT"
+echo "  Skipped: $SKIP_COUNT"
+if [[ ${#FAILED_PROJECTS[@]} -gt 0 ]]; then
+    echo "  Failed projects: ${FAILED_PROJECTS[*]}"
+fi
+echo "=== Done ==="
+
+if [[ $FAIL_COUNT -gt 0 ]]; then
+    exit 1
+fi

package/scripts/entropy-audit.sh

@@ -0,0 +1,221 @@
+#!/usr/bin/env bash
+# shellcheck disable=SC2034  # FIX_MODE parsed but reserved for future auto-fix mode
+# entropy-audit.sh — Detect documentation drift, naming inconsistencies, and stale conventions
+#
+# Usage: entropy-audit.sh [--project <name>] [--all] [--fix]
+#
+# Checks:
+#   1. CLAUDE.md freshness — file references that no longer exist
+#   2. Naming drift — files/functions that violate project conventions
+#   3. Dead code — unreferenced exports and unused imports
+#   4. File size violations — files exceeding 300-line taste invariant
+#   5. Doc staleness — CLAUDE.md mentions of removed features
+#
+# Designed to run as a systemd timer for continuous entropy management.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
+source "$SCRIPT_DIR/lib/common.sh"
+
+PROJECTS_DIR="${PROJECTS_DIR:-$HOME/Documents/projects}"
+ALL_PROJECTS=false
+FIX_MODE=false  # reserved for auto-fix mode
+TARGET_PROJECT=""
+RESULTS_DIR="/tmp/entropy-audit-$(date +%Y%m%d-%H%M%S)"
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --project) TARGET_PROJECT="$2"; shift 2 ;;
+    --all) ALL_PROJECTS=true; shift ;;
+    --fix) FIX_MODE=true; shift ;;
+    --projects-dir) PROJECTS_DIR="$2"; shift 2 ;;
+    -h|--help)
+      echo "entropy-audit.sh — Detect and report codebase entropy"
+      echo ""
+      echo "Usage: entropy-audit.sh [--project <name>] [--all] [--fix]"
+      echo ""
+      echo "Options:"
+      echo "  --project <name>  Audit a specific project"
+      echo "  --all             Audit all projects"
+      echo "  --fix             Auto-fix simple issues (dead refs in CLAUDE.md)"
+      exit 0
+      ;;
+    *) echo "Unknown: $1" >&2; exit 1 ;;
+  esac
+done
+
+mkdir -p "$RESULTS_DIR"
+
+audit_project() {
+  local project_dir="$1"
+  local project_name
+  project_name="$(basename "$project_dir")"
+  local report="$RESULTS_DIR/$project_name.md"
+
+  echo "Auditing $project_name..."
+
+  {
+    echo "# Entropy Audit: $project_name"
+    echo "Date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    echo ""
+
+    # Check 1: CLAUDE.md references to nonexistent files
+    echo "## 1. Dead References in CLAUDE.md"
+    local claude_md="$project_dir/CLAUDE.md"
+    local dead_count=0
+    if [[ -f "$claude_md" ]]; then
+      # Extract file paths mentioned in backticks — collect into array to avoid subshell
+      local refs
+      refs=$(grep -oE '`[^`]+\.(py|ts|js|sh|json|md|yaml|yml)`' "$claude_md" 2>/dev/null | tr -d '`' || true)
+      if [[ -n "$refs" ]]; then
+        while IFS= read -r ref; do
+          # Skip paths with placeholders
+          if echo "$ref" | grep -qE '<|>|\*|\$|~'; then continue; fi
+          # Check relative to project dir
+          if [[ ! -f "$project_dir/$ref" ]] && [[ ! -f "$ref" ]]; then
+            echo "- ❌ Referenced but missing: \`$ref\`"
+            dead_count=$((dead_count + 1))
+          fi
+        done <<< "$refs"
+      fi
+      if [[ $dead_count -eq 0 ]]; then
+        echo "- ✅ All references valid"
+      else
+        echo "- Found $dead_count dead reference(s)"
+      fi
+    else
+      echo "- ⚠️ No CLAUDE.md found"
+    fi
+    echo ""
+
+    # Check 2: File size violations (>300 lines)
+    echo "## 2. File Size Violations (>300 lines)"
+    local size_count=0
+    local code_files
+    code_files=$(find "$project_dir" \( -name '*.py' -o -name '*.ts' -o -name '*.js' -o -name '*.sh' \) \
+      -not -path '*/node_modules/*' -not -path '*/__pycache__/*' -not -path '*/.git/*' -not -path '*/.venv/*' -not -path '*/venv/*' -not -path '*/site-packages/*' -not -path '*/.tox/*' 2>/dev/null || true)
+    code_files=$(echo "$code_files" | sed '/^[[:space:]]*$/d')
+    if [[ -n "$code_files" ]]; then
+      while IFS= read -r f; do
+        [[ -z "$f" ]] && continue
+        local lines
+        lines=$(wc -l < "$f" 2>/dev/null || echo 0)
+        if [[ $lines -gt 300 ]]; then
+          echo "- ⚠️ \`$(basename "$f")\`: $lines lines"
+          size_count=$((size_count + 1))
+        fi
+      done <<< "$code_files"
+    fi
+    if [[ $size_count -eq 0 ]]; then
+      echo "- ✅ All files within limit"
+    else
+      echo "- Found $size_count file(s) over 300 lines"
+    fi
+    echo ""
+
+    # Check 3: Naming convention drift
+    echo "## 3. Naming Convention Check"
+    local naming_count=0
+    local py_files
+    py_files=$(find "$project_dir" -name '*.py' \
+      -not -path '*/node_modules/*' -not -path '*/__pycache__/*' -not -path '*/.git/*' -not -path '*/.venv/*' -not -path '*/venv/*' -not -path '*/site-packages/*' -not -path '*/.tox/*' 2>/dev/null || true)
+    py_files=$(echo "$py_files" | sed '/^[[:space:]]*$/d')
+    if [[ -n "$py_files" ]]; then
+      while IFS= read -r f; do
+        [[ -z "$f" ]] && continue
+        local camel_funcs
+        camel_funcs=$(grep -nE '^def [a-z]+[A-Z]' "$f" 2>/dev/null || true)
+        if [[ -n "$camel_funcs" ]]; then
+          echo "- ⚠️ \`$(basename "$f")\`: camelCase functions found (should be snake_case)"
+          naming_count=$((naming_count + 1))
+        fi
+      done <<< "$py_files"
+    fi
+    if [[ $naming_count -eq 0 ]]; then
+      echo "- ✅ No naming drift detected"
+    fi
+    echo ""
+
+    # Check 4: Unused imports (Python only, basic check — first 20 files)
+    echo "## 4. Import Hygiene"
+    local import_count=0
+    local py_sample
+    py_sample=$(find "$project_dir" -name '*.py' -not -path '*__pycache__*' -not -path '*.git*' 2>/dev/null | head -20 || true)
+    py_sample=$(echo "$py_sample" | sed '/^[[:space:]]*$/d')
+    if [[ -n "$py_sample" ]]; then
+      while IFS= read -r f; do
+        [[ -z "$f" ]] && continue
+        local imports
+        imports=$(grep -E '^(from .+ import .+|import .+)' "$f" 2>/dev/null || true)
+        if [[ -n "$imports" ]]; then
+          while IFS= read -r imp; do
+            local name
+            name=$(echo "$imp" | grep -oE 'import (\w+)' | tail -1 | awk '{print $2}' || true)
+            if [[ -n "$name" ]]; then
+              local count
+              count=$(grep -c "$name" "$f" 2>/dev/null || echo 0)
+              if [[ $count -le 1 ]]; then
+                echo "- ⚠️ \`$(basename "$f")\`: possibly unused import: \`$name\`"
+                import_count=$((import_count + 1))
+              fi
+            fi
+          done <<< "$imports"
+        fi
+      done <<< "$py_sample"
+    fi
+    if [[ $import_count -eq 0 ]]; then
+      echo "- ✅ No obvious unused imports"
+    fi
+    echo ""
+
+    # Check 5: Git status (uncommitted work)
+    echo "## 5. Uncommitted Work"
+    if [[ -d "$project_dir/.git" ]]; then
+      local untracked
+      untracked=$(cd "$project_dir" && git status --porcelain 2>/dev/null | wc -l || echo 0)
+      if [[ $untracked -gt 0 ]]; then
+        echo "- ⚠️ $untracked uncommitted files"
+      else
+        echo "- ✅ Working tree clean"
+      fi
+    fi
+    echo ""
+
+  } > "$report"
+
+  echo "  Report: $report"
+}
+
+# Determine which projects to audit
+if [[ -n "$TARGET_PROJECT" ]]; then
+  audit_project "$PROJECTS_DIR/$TARGET_PROJECT"
+elif [[ "$ALL_PROJECTS" == "true" ]]; then
+  for d in "$PROJECTS_DIR"/*/; do
+    [[ -d "$d" ]] && audit_project "$d"
+  done
+  # Also audit workspace-level CLAUDE.md
+  echo ""
+  echo "Workspace CLAUDE.md audit:"
+  if [[ -f "$HOME/Documents/CLAUDE.md" ]]; then
+    local_refs=$(grep -oE '`[^`]+\.(py|ts|js|sh|json|md|yaml|yml)`' "$HOME/Documents/CLAUDE.md" 2>/dev/null | tr -d '`' || true)
+    if [[ -n "$local_refs" ]]; then
+      while IFS= read -r ref; do
+        if echo "$ref" | grep -qE '<|>|\*|\$|~'; then continue; fi
+        if [[ ! -f "$HOME/Documents/$ref" ]] && [[ ! -f "$ref" ]]; then
+          echo "  ❌ Dead ref: $ref"
+        fi
+      done <<< "$local_refs"
+    fi
+  fi
+else
+  echo "Usage: entropy-audit.sh --project <name> | --all" >&2
+  echo "Projects available:" >&2
+  ls "$PROJECTS_DIR" 2>/dev/null | while read -r p; do echo "  $p"; done >&2
+  exit 1
+fi
+
+echo ""
+echo "═══════════════════════════════════════════════"
+echo "Results: $RESULTS_DIR/"
+echo "═══════════════════════════════════════════════"

package/scripts/failure-digest.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# failure-digest.sh — Parse failed batch logs into structured failure digest
+#
+# Usage: failure-digest.sh <log-file>
+#
+# Extracts:
+#   - Failed test names (FAILED pattern)
+#   - Error types and messages (Traceback, Error:, Exception:)
+#   - Test summary line (N failed, M passed)
+#
+# Output: Structured text digest suitable for retry prompts
+set -euo pipefail
+
+LOG_FILE="${1:-}"
+
+if [[ "$LOG_FILE" == "--help" || "$LOG_FILE" == "-h" ]]; then
+    echo "failure-digest.sh — Parse batch log into structured failure digest"
+    echo "Usage: failure-digest.sh <log-file>"
+    exit 0
+fi
+
+if [[ -z "$LOG_FILE" || ! -f "$LOG_FILE" ]]; then
+    echo "Error: Log file required" >&2
+    exit 1
+fi
+
+echo "=== Failure Digest ==="
+echo "Log: $(basename "$LOG_FILE")"
+echo ""
+
+# Extract failed test names
+echo "--- Failed Tests ---"
+grep -E '^FAILED ' "$LOG_FILE" 2>/dev/null | sed 's/^FAILED /  /' || echo "  (none found)"
+echo ""
+
+# Extract error types and messages
+echo "--- Errors ---"
+grep -E '(Error|Exception|FAIL):' "$LOG_FILE" 2>/dev/null | grep -v '^FAILED ' | head -20 | sed 's/^/  /' || echo "  (none found)"
+echo ""
+
+# Extract tracebacks (last frame + error line)
+echo "--- Stack Traces (last frame) ---"
+grep -B1 -E '^\w+Error:|^\w+Exception:' "$LOG_FILE" 2>/dev/null | head -20 | sed 's/^/  /' || echo "  (none found)"
+echo ""
+
+# Extract test summary
+echo "--- Summary ---"
+grep -E '[0-9]+ (failed|passed|error)' "$LOG_FILE" 2>/dev/null | tail -1 | sed 's/^/  /' || echo "  (no summary found)"
+echo ""
+
+echo "=== End Digest ==="