@nlaprell/shipit 1.0.0

package/scripts/README.md

@@ -0,0 +1,70 @@
+# Scripts
+
+Shell scripts for the ShipIt framework. Run via `pnpm <script-name>` (see `package.json`).
+
+## Categories
+
+### Intent Management
+
+- `new-intent.sh` — Create a new intent file (feature, bug, tech-debt)
+- `fix-intents.sh` — Auto-fix common intent issues (dependency ordering, whitespace)
+- `kill-intent.sh` — Kill an intent with rationale
+
+### Workflow Orchestration
+
+- `workflow-orchestrator.sh` — Generate workflow state files for `/ship` phases (spec-driven: reads `workflow-templates/phases.yml` and substitutes templates)
+- `workflow-templates/` — Phase spec (`phases.yml`) and `.tpl` templates; add a phase by adding a spec entry and a template file
+- `verify.sh` — Run verification phase (tests, mutation, audit)
+
+Agent coordinator (task queue and agent assignment) is **experimental** and lives in `experimental/`; see `experimental/README.md`.
+
+### Generation
+
+- `generate-release-plan.sh` — Build release plan from intents
+- `generate-roadmap.sh` — Generate roadmap (now/next/later) and dependency graph
+- `generate-docs.sh` — Update README, CHANGELOG, release notes
+- `generate-dashboard.sh` — Generate project dashboard
+- `generate-project-context.sh` — Generate project context for agents
+- `generate-system-state.sh` — Generate SYSTEM_STATE.md for Steward
+
+### Validation
+
+- `validate-project.sh` — Validate project.json against schema
+- `validate-cursor.sh` — Validate Cursor integration (rules, commands)
+
+### Deployment
+
+- `deploy.sh` — Deploy with readiness checks
+- `check-readiness.sh` — Run readiness checks before deploy
+
+### Project Setup
+
+- `init-project.sh` — Initialize a new ShipIt project
+- `scope-project.sh` — AI-assisted feature breakdown
+
+### Drift & Metrics
+
+- `drift-check.sh` — Calculate drift metrics (PR size, test ratio, deps)
+- `collect-metrics.sh` — Collect metrics for reporting
+- `audit-check.sh` — Run npm audit for vulnerabilities
+
+### Utilities
+
+- `help.sh` — List all commands with descriptions (builds "Available commands" from `command-manifest.yml`)
+- `command-manifest.yml` — Single source of truth for slash commands: id, slash, pnpm script, one-liner, category. Add a command by adding an entry; help.sh reads it.
+- `status.sh` — Unified dashboard (intents, workflow, tests)
+- `suggest.sh` — Suggest next intent to work on
+
+### Test & Issue Tooling
+
+- `create-test-plan-issue.sh` — Create GitHub issues from test failures
+- `setup-worktrees.sh` — Setup git worktrees for parallel work
+
+## Shared Libraries (`lib/`)
+
+- `common.sh` — Plumbing: `error_exit`, color variables, optional `require_cmd`. Source this (or `intent.sh`) in new scripts to avoid duplicating error handling and colors.
+- `intent.sh` — Intent domain: `resolve_intent_file`, `require_intent_file`, `INTENT_DIR`. Sources `common.sh`. Use in scripts that resolve intent IDs to paths (e.g. workflow-orchestrator, kill-intent).
+- `progress.sh` — Progress indicator helpers
+- `suggest-next.sh` — Next-step suggestion logic
+- `validate-intents.sh` — Intent validation (dependencies, circular deps)
+- `verify-outputs.sh` — Output verification and generator chaining

package/scripts/audit-check.sh

@@ -0,0 +1,125 @@
+#!/bin/bash
+
+# Audit guard with allowlist and expiry checks.
+
+set -euo pipefail
+
+AUDIT_LEVEL="${1:-moderate}"
+ALLOWLIST_FILE="_system/security/audit-allowlist.json"
+
+if ! command -v pnpm >/dev/null 2>&1; then
+    echo "ERROR: pnpm is required to run audit checks" >&2
+    exit 1
+fi
+
+if [ -f "$ALLOWLIST_FILE" ]; then
+    ALLOWLIST_JSON="$(cat "$ALLOWLIST_FILE")"
+else
+    ALLOWLIST_JSON='{"advisories":[]}'
+fi
+
+AUDIT_JSON="$(pnpm audit --json || true)"
+if [ -z "$AUDIT_JSON" ]; then
+    echo "ERROR: pnpm audit returned no output" >&2
+    exit 1
+fi
+
+printf "%s" "$AUDIT_JSON" | AUDIT_LEVEL="$AUDIT_LEVEL" AUDIT_ALLOWLIST_JSON="$ALLOWLIST_JSON" node <<'NODE'
+const fs = require('fs');
+
+const input = fs.readFileSync(0, 'utf8');
+const audit = JSON.parse(input || '{}');
+const allowlist = JSON.parse(process.env.AUDIT_ALLOWLIST_JSON || '{"advisories":[]}');
+const level = process.env.AUDIT_LEVEL || 'moderate';
+
+const levels = { info: 0, low: 1, moderate: 2, high: 3, critical: 4 };
+if (!(level in levels)) {
+  console.error(`ERROR: Invalid audit level "${level}"`);
+  process.exit(2);
+}
+
+const threshold = levels[level];
+const advisories = audit.advisories || {};
+const findings = Object.values(advisories).map((a) => ({
+  id: String(a.id),
+  severity: a.severity || 'info',
+  title: a.title || '',
+  url: a.url || '',
+  recommendation: a.recommendation || '',
+}));
+
+const scoped = findings.filter((f) => (levels[f.severity] ?? 0) >= threshold);
+const allow = new Map((allowlist.advisories || []).map((a) => [String(a.id), a]));
+const today = new Date().toISOString().slice(0, 10);
+
+const unlisted = [];
+const expired = [];
+const invalid = [];
+const allowed = [];
+
+for (const f of scoped) {
+  const entry = allow.get(String(f.id));
+  if (!entry) {
+    unlisted.push(f);
+    continue;
+  }
+
+  if (!entry.reason || !entry.expires) {
+    invalid.push({
+      ...f,
+      missingReason: !entry.reason,
+      missingExpires: !entry.expires,
+    });
+    continue;
+  }
+
+  if (entry.expires < today) {
+    expired.push({ ...f, expires: entry.expires, reason: entry.reason || '' });
+    continue;
+  }
+
+  allowed.push({ ...f, expires: entry.expires || '', reason: entry.reason || '' });
+}
+
+if (scoped.length === 0) {
+  console.log(`✓ pnpm audit: no ${level}+ vulnerabilities`);
+  process.exit(0);
+}
+
+if (unlisted.length || expired.length || invalid.length) {
+  console.error(
+    `✗ pnpm audit: ${unlisted.length} unlisted, ${expired.length} expired, ${invalid.length} invalid allowlist entries`
+  );
+
+  if (unlisted.length) {
+    console.error('Unlisted advisories:');
+    for (const f of unlisted) {
+      console.error(`- ${f.id} ${f.severity} ${f.title}`);
+    }
+  }
+
+  if (expired.length) {
+    console.error('Expired advisories:');
+    for (const f of expired) {
+      console.error(`- ${f.id} ${f.severity} ${f.title} (expired ${f.expires})`);
+    }
+  }
+
+  if (invalid.length) {
+    console.error('Invalid allowlist entries (missing reason/expires):');
+    for (const f of invalid) {
+      const missing = [];
+      if (f.missingReason) missing.push('reason');
+      if (f.missingExpires) missing.push('expires');
+      console.error(`- ${f.id} ${f.severity} ${f.title} (missing ${missing.join(', ')})`);
+    }
+  }
+
+  process.exit(1);
+}
+
+console.log(`✓ pnpm audit: ${scoped.length} ${level}+ advisories allowlisted`);
+for (const f of allowed) {
+  console.log(`- ${f.id} ${f.severity} ${f.title}`);
+}
+NODE

package/scripts/calibration-report.sh

@@ -0,0 +1,198 @@
+#!/bin/bash
+
+# Confidence calibration report: stated confidence vs actual outcomes.
+# Reads _system/artifacts/confidence-calibration.json; prints metrics and optional alert.
+# Usage: calibration-report.sh [--last N] [--json] [--fail-on-threshold X]
+#   --last N: show last N decisions in table
+#   --json: output metrics as JSON (for dashboard)
+#   --fail-on-threshold X: exit 1 if calibration error (MAE) > X (e.g. 0.2)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+cd "$REPO_ROOT"
+
+# shellcheck source=scripts/lib/common.sh
+. "$SCRIPT_DIR/lib/common.sh"
+
+require_cmd jq
+
+CALIBRATION_FILE="_system/artifacts/confidence-calibration.json"
+LAST_N=""
+OUTPUT_JSON=false
+FAIL_THRESHOLD=""
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --last)
+            LAST_N="${2:-}"
+            shift 2
+            ;;
+        --json)
+            OUTPUT_JSON=true
+            shift
+            ;;
+        --fail-on-threshold)
+            FAIL_THRESHOLD="${2:-}"
+            shift 2
+            ;;
+        *)
+            echo "Usage: $0 [--last N] [--json] [--fail-on-threshold X]" >&2
+            exit 1
+            ;;
+    esac
+done
+
+if [ ! -f "$CALIBRATION_FILE" ]; then
+    echo "No calibration data (missing $CALIBRATION_FILE). Run /verify to record decisions." >&2
+    [ "$OUTPUT_JSON" = true ] && echo '{"decisions_count":0,"message":"No calibration file"}' || true
+    exit 0
+fi
+
+DECISIONS=$(jq -c '.decisions // []' "$CALIBRATION_FILE")
+COUNT=$(echo "$DECISIONS" | jq 'length')
+if [ "$COUNT" -eq 0 ]; then
+    echo "No decisions yet. Run /verify to record confidence vs outcomes." >&2
+    [ "$OUTPUT_JSON" = true ] && echo "{\"decisions_count\":0,\"message\":\"No decisions\"}" || true
+    exit 0
+fi
+
+# Decisions with stated_confidence for metrics (exclude null)
+WITH_CONF=$(echo "$DECISIONS" | jq '[.[] | select(.stated_confidence != null)]')
+N_WITH_CONF=$(echo "$WITH_CONF" | jq 'length')
+
+if [ "$OUTPUT_JSON" = true ]; then
+    # JSON output: metrics for dashboard
+    MAE="null"
+    BRIER="null"
+    OVER_UNDER="null"
+    BINS_JSON="[]"
+    if [ "$N_WITH_CONF" -gt 0 ]; then
+        MAE=$(echo "$WITH_CONF" | jq '
+            [.[] | (.stated_confidence - (if .actual_outcome == "success" then 1 else 0 end)) | if . < 0 then -. else . end] | add / length
+        ')
+        BRIER=$(echo "$WITH_CONF" | jq '
+            [.[] | ((.stated_confidence - (if .actual_outcome == "success" then 1 else 0 end)) | . * .)] | add / length
+        ')
+        AVG_STATED=$(echo "$WITH_CONF" | jq '[.[].stated_confidence] | add / length')
+        SUCCESS_RATE=$(echo "$WITH_CONF" | jq '[.[] | if .actual_outcome == "success" then 1 else 0 end] | add / length')
+        if [ "$(echo "$AVG_STATED" | jq '. > '"$SUCCESS_RATE"'')" = "true" ]; then
+            OVER_UNDER="over-confident"
+        elif [ "$(echo "$AVG_STATED" | jq '. < '"$SUCCESS_RATE"'')" = "true" ]; then
+            OVER_UNDER="under-confident"
+        else
+            OVER_UNDER="well-calibrated"
+        fi
+        BINS_JSON=$(echo "$WITH_CONF" | jq '
+            def bin_label(c):
+                if c < 0.5 then "0.0-0.5"
+                elif c < 0.7 then "0.5-0.7"
+                elif c < 0.9 then "0.7-0.9"
+                else "0.9-1.0" end;
+            [.[] | {bin: bin_label(.stated_confidence), stated: .stated_confidence, success: (if .actual_outcome == "success" then 1 else 0 end)}]
+            | group_by(.bin)
+            | map({
+                bin: .[0].bin,
+                total: length,
+                successes: (map(.success) | add),
+                success_rate: ((map(.success) | add) / length)
+              })
+        ')
+    fi
+    jq -n \
+        --argjson decisions_count "$COUNT" \
+        --argjson with_confidence "$N_WITH_CONF" \
+        --argjson mae "$MAE" \
+        --argjson brier "$BRIER" \
+        --argjson bins "$BINS_JSON" \
+        --arg over_under "$OVER_UNDER" \
+        '{decisions_count: $decisions_count, with_confidence: $with_confidence, calibration_error_mae: $mae, brier_score: $brier, bins: $bins, over_under: $over_under}'
+    exit 0
+fi
+
+# Human-readable report
+echo -e "${BLUE}════════════════════════════════════════${NC}"
+echo -e "${BLUE}Confidence Calibration Report${NC}"
+echo -e "${BLUE}════════════════════════════════════════${NC}"
+echo ""
+
+if [ "$N_WITH_CONF" -eq 0 ]; then
+    echo "No decisions with stated_confidence yet (run /verify after analysis phases that output confidence)."
+    echo "Total decisions: $COUNT (outcomes only)."
+    echo ""
+    echo "Last decisions:"
+    echo "$DECISIONS" | jq -r '.[-10:] | .[] | "  \(.id)  outcome=\(.actual_outcome)  stated_confidence=\(.stated_confidence // "n/a")"' 2>/dev/null || true
+    exit 0
+fi
+
+# Calibration error (MAE)
+MAE=$(echo "$WITH_CONF" | jq '[.[] | (.stated_confidence - (if .actual_outcome == "success" then 1 else 0 end)) | if . < 0 then -. else . end] | add / length')
+BRIER=$(echo "$WITH_CONF" | jq '[.[] | ((.stated_confidence - (if .actual_outcome == "success" then 1 else 0 end)) | . * .)] | add / length')
+
+echo -e "${CYAN}Metrics (decisions with stated_confidence: $N_WITH_CONF)${NC}"
+echo "  Calibration error (MAE): $MAE"
+echo "  Brier score:             $BRIER"
+echo ""
+
+# Over/under confidence
+AVG_STATED=$(echo "$WITH_CONF" | jq '[.[].stated_confidence] | add / length')
+SUCCESS_RATE=$(echo "$WITH_CONF" | jq '[.[] | if .actual_outcome == "success" then 1 else 0 end] | add / length')
+echo -e "${CYAN}Calibration summary${NC}"
+echo "  Avg stated confidence: $AVG_STATED  |  Actual success rate: $SUCCESS_RATE"
+if [ "$(echo "$AVG_STATED" | jq '. > '"$SUCCESS_RATE"'')" = "true" ]; then
+    echo -e "  ${YELLOW}→ Over-confident: stated confidence is higher than actual success rate. Consider lowering stated confidence when uncertain.${NC}"
+elif [ "$(echo "$AVG_STATED" | jq '. < '"$SUCCESS_RATE"'')" = "true" ]; then
+    echo -e "  ${GREEN}→ Under-confident: stated confidence is lower than actual success. You may be more confident when outcomes are good.${NC}"
+else
+    echo -e "  ${GREEN}→ Well-calibrated.${NC}"
+fi
+echo ""
+
+# Bins table
+echo -e "${CYAN}Success rate by confidence bin${NC}"
+printf "  %-12s %6s %8s %10s\n" "Bin" "Total" "Success" "Rate"
+echo "$WITH_CONF" | jq -r '
+    def bin_label(c):
+        if c < 0.5 then "0.0-0.5"
+        elif c < 0.7 then "0.5-0.7"
+        elif c < 0.9 then "0.7-0.9"
+        else "0.9-1.0" end;
+    [.[] | {bin: bin_label(.stated_confidence), success: (if .actual_outcome == "success" then 1 else 0 end)}]
+    | group_by(.bin)
+    | map({bin: .[0].bin, total: length, successes: (map(.success) | add)})
+    | sort_by(.bin)
+    | .[]
+    | "  \(.bin)  \(.total)  \(.successes)  \((.successes / .total * 100) | floor / 100)"
+' 2>/dev/null | while read -r line; do echo "$line"; done
+echo ""
+
+# Optional alert: last K with high stated confidence but low success
+ALERT_K=10
+RECENT_HIGH=$(echo "$DECISIONS" | jq '[.[-'"$ALERT_K"':] | .[] | select(.stated_confidence != null and .stated_confidence > 0.8)]')
+N_RECENT_HIGH=$(echo "$RECENT_HIGH" | jq 'length')
+if [ "$N_RECENT_HIGH" -ge 3 ]; then
+    RECENT_SUCCESS_RATE=$(echo "$RECENT_HIGH" | jq '[.[] | if .actual_outcome == "success" then 1 else 0 end] | add / length')
+    if [ "$(echo "$RECENT_SUCCESS_RATE" | jq '. < 0.5')" = "true" ]; then
+        echo -e "${YELLOW}⚠ Possible over-confidence: last $ALERT_K decisions with stated_confidence > 0.8 have success rate < 50%. Review recent decisions.${NC}"
+        echo ""
+    fi
+fi
+
+# Last N decisions table
+if [ -n "$LAST_N" ]; then
+    echo -e "${CYAN}Last $LAST_N decisions${NC}"
+    printf "  %-8s %8s %-8s %s\n" "ID" "Stated" "Outcome" "Notes (truncated)"
+    echo "$DECISIONS" | jq -r --argjson n "$LAST_N" '.[-$n:] | .[] | "  \(.id)  \(.stated_confidence // "n/a")  \(.actual_outcome)  \(.notes | .[0:50])"' 2>/dev/null | while read -r line; do echo "$line"; done
+    echo ""
+fi
+
+# Exit 1 if --fail-on-threshold and MAE > threshold
+if [ -n "$FAIL_THRESHOLD" ]; then
+    if [ "$(echo "$MAE" | jq '. > '"$FAIL_THRESHOLD"'')" = "true" ]; then
+        echo -e "${RED}Calibration error ($MAE) exceeds threshold ($FAIL_THRESHOLD).${NC}" >&2
+        exit 1
+    fi
+fi
+
+exit 0

package/scripts/check-readiness.sh

@@ -0,0 +1,155 @@
+#!/bin/bash
+
+# Production Readiness Check Script
+# Validates project is ready for deployment
+
+set -euo pipefail
+
+error_exit() {
+    echo "ERROR: $1" >&2
+    exit "${2:-1}"
+}
+
+warning() {
+    echo "WARNING: $1" >&2
+}
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+ENVIRONMENT="${1:-}"
+if [ -z "$ENVIRONMENT" ]; then
+    error_exit "Usage: ./scripts/check-readiness.sh <environment>" 1
+fi
+
+echo -e "${BLUE}Running readiness checks for: ${ENVIRONMENT}${NC}"
+echo ""
+
+FAILED=0
+
+# Check 1: Tests pass
+echo -e "${YELLOW}[1/7] Running tests...${NC}"
+if command -v pnpm >/dev/null 2>&1; then
+    if pnpm test >/dev/null 2>&1; then
+        echo -e "${GREEN}✓ Tests pass${NC}"
+    else
+        echo -e "${RED}✗ Tests failed${NC}"
+        FAILED=1
+    fi
+else
+    warning "pnpm not found, skipping test check"
+fi
+echo ""
+
+# Check 2: Coverage threshold
+echo -e "${YELLOW}[2/7] Checking test coverage...${NC}"
+if [ -f "project.json" ]; then
+    COVERAGE_THRESHOLD=$(jq -r '.settings.testCoverageMinimum // 80' project.json 2>/dev/null || echo "80")
+    if command -v pnpm >/dev/null 2>&1; then
+        # Try to get coverage (simplified check)
+        if pnpm test:coverage >/dev/null 2>&1; then
+            echo -e "${GREEN}✓ Coverage check passed${NC}"
+        else
+            warning "Could not verify coverage threshold ($COVERAGE_THRESHOLD%)"
+        fi
+    fi
+else
+    warning "project.json not found, using default threshold (80%)"
+fi
+echo ""
+
+# Check 3: Lint and typecheck
+echo -e "${YELLOW}[3/7] Running lint and typecheck...${NC}"
+if command -v pnpm >/dev/null 2>&1; then
+    if pnpm lint >/dev/null 2>&1 && pnpm typecheck >/dev/null 2>&1; then
+        echo -e "${GREEN}✓ Lint and typecheck pass${NC}"
+    else
+        echo -e "${RED}✗ Lint or typecheck failed${NC}"
+        FAILED=1
+    fi
+else
+    warning "pnpm not found, skipping lint/typecheck"
+fi
+echo ""
+
+# Check 4: Security audit
+echo -e "${YELLOW}[4/7] Running security audit...${NC}"
+if command -v pnpm >/dev/null 2>&1; then
+    if [ -f "scripts/audit-check.sh" ]; then
+        if ./scripts/audit-check.sh moderate; then
+            echo -e "${GREEN}✓ No unlisted moderate+ vulnerabilities${NC}"
+        else
+            warning "Security audit found unlisted or expired advisories"
+        fi
+    else
+        warning "audit-check.sh not found, skipping allowlist enforcement"
+        if pnpm audit --audit-level=moderate >/dev/null 2>&1; then
+            echo -e "${GREEN}✓ No moderate/high/critical vulnerabilities${NC}"
+        else
+            warning "Security audit found issues (review manually)"
+        fi
+    fi
+else
+    warning "pnpm not found, skipping security audit"
+fi
+echo ""
+
+# Check 5: Documentation
+echo -e "${YELLOW}[5/7] Checking documentation...${NC}"
+DOCS_OK=1
+if [ ! -f "README.md" ]; then
+    echo -e "${RED}✗ README.md missing${NC}"
+    DOCS_OK=0
+fi
+if [ ! -f "CHANGELOG.md" ]; then
+    warning "CHANGELOG.md missing (recommended)"
+fi
+if [ $DOCS_OK -eq 1 ]; then
+    echo -e "${GREEN}✓ Documentation present${NC}"
+fi
+echo ""
+
+# Check 6: Drift check
+echo -e "${YELLOW}[6/7] Running drift check...${NC}"
+if [ -f "scripts/drift-check.sh" ]; then
+    if ./scripts/drift-check.sh >/dev/null 2>&1; then
+        echo -e "${GREEN}✓ Drift check passed${NC}"
+    else
+        warning "Drift check found issues (review manually)"
+    fi
+else
+    warning "drift-check.sh not found, skipping"
+fi
+echo ""
+
+# Check 7: Invariants
+echo -e "${YELLOW}[7/7] Checking invariants...${NC}"
+if [ -f "_system/architecture/invariants.yml" ]; then
+    if [ -f "scripts/validate-project.sh" ]; then
+        if ./scripts/validate-project.sh >/dev/null 2>&1; then
+            echo -e "${GREEN}✓ Invariants valid${NC}"
+        else
+            warning "Invariant validation issues (review manually)"
+        fi
+    else
+        echo -e "${GREEN}✓ Invariants file exists${NC}"
+    fi
+else
+    warning "invariants.yml not found"
+fi
+echo ""
+
+# Summary
+echo -e "${BLUE}════════════════════════════════════════${NC}"
+if [ $FAILED -eq 0 ]; then
+    echo -e "${GREEN}✓ Production readiness checks PASSED${NC}"
+    exit 0
+else
+    echo -e "${RED}✗ Production readiness checks FAILED${NC}"
+    echo -e "${YELLOW}Fix the issues above before deploying${NC}"
+    exit 1
+fi

package/scripts/collect-metrics.sh

@@ -0,0 +1,116 @@
+#!/bin/bash
+
+# Metrics Collection Script
+# Tracks workflow success rates and time-per-phase metrics
+
+set -euo pipefail
+
+error_exit() {
+    echo "ERROR: $1" >&2
+    exit "${2:-1}"
+}
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+METRICS_FILE="metrics.json"
+
+echo -e "${BLUE}Collecting workflow metrics...${NC}"
+
+# Initialize metrics if needed
+if [ ! -f "$METRICS_FILE" ]; then
+    cat > "$METRICS_FILE" << EOF
+{
+  "version": "1.0",
+  "created": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
+  "workflows": [],
+  "summary": {
+    "totalWorkflows": 0,
+    "successfulWorkflows": 0,
+    "failedWorkflows": 0,
+    "averagePhaseTime": {},
+    "bottlenecks": []
+  }
+}
+EOF
+fi
+
+# Collect intent metrics
+intent_files=()
+while IFS= read -r file; do
+    intent_files+=("$file")
+done < <(find intent -type f -name "*.md" ! -name "_TEMPLATE.md" 2>/dev/null)
+
+INTENT_TOTAL=${#intent_files[@]}
+if [ "$INTENT_TOTAL" -gt 0 ]; then
+    INTENT_SHIPPED=$(grep -l "Status.*shipped" "${intent_files[@]}" 2>/dev/null | wc -l | tr -d ' ')
+    INTENT_FAILED=$(grep -l "Status.*killed" "${intent_files[@]}" 2>/dev/null | wc -l | tr -d ' ')
+else
+    INTENT_SHIPPED=0
+    INTENT_FAILED=0
+fi
+
+# Calculate success rate
+if [ "$INTENT_TOTAL" -gt 0 ]; then
+    SUCCESS_RATE=$((INTENT_SHIPPED * 100 / INTENT_TOTAL))
+else
+    SUCCESS_RATE=0
+fi
+
+# Collect phase completion times (if workflow state files have timestamps)
+collect_phase_times() {
+    local intent_id="$1"
+    local phases=("01_analysis" "02_plan" "03_implementation" "04_verification" "05_release_notes")
+    
+    for phase in "${phases[@]}"; do
+        local file="work/workflow-state/${phase}.md"
+        if [ -f "$file" ]; then
+            # Extract timestamp if available
+            local created=$(grep -i "generated\|created" "$file" | head -1 | grep -o "[0-9]\{4\}-[0-9]\{2\}-[0-9]\{2\}T[0-9]\{2\}:[0-9]\{2\}:[0-9]\{2\}Z" | head -1 || echo "")
+            echo "$phase:$created"
+        fi
+    done
+}
+
+# Generate metrics summary
+cat > "metrics-summary.md" << EOF || error_exit "Failed to generate metrics summary"
+# Workflow Metrics Summary
+
+**Generated:** $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+## Success Metrics
+
+| Metric | Value |
+|--------|-------|
+| **Total Intents** | $INTENT_TOTAL |
+| **Shipped** | $INTENT_SHIPPED |
+| **Failed/Killed** | $INTENT_FAILED |
+| **Success Rate** | $SUCCESS_RATE% |
+
+## Phase Completion
+
+[Phase completion times will be tracked here]
+
+## Bottlenecks
+
+[Identified bottlenecks will be listed here]
+
+## Recommendations
+
+[Recommendations based on metrics]
+
+---
+
+*Run \`pnpm collect-metrics\` to update metrics.*
+EOF
+
+echo -e "${GREEN}✓ Metrics collected${NC}"
+echo ""
+echo -e "${YELLOW}Summary:${NC}"
+echo "  Total Intents: $INTENT_TOTAL"
+echo "  Success Rate: $SUCCESS_RATE%"
+echo "  Metrics saved to: metrics-summary.md"
+echo ""