dev-playbooks-cn 1.0.0

package/skills/devbooks-delivery-workflow/scripts/progress-dashboard.sh

@@ -0,0 +1,319 @@
+#!/usr/bin/env bash
+# progress-dashboard.sh - Provide progress visualization for change packages
+#
+# This script displays a dashboard showing:
+# - Task completion rate
+# - Role status (handoff state)
+# - Evidence status (Red/Green)
+#
+# Reference: harden-devbooks-quality-gates design.md AC-010
+
+set -euo pipefail
+
+usage() {
+  cat <<'EOF' >&2
+usage: progress-dashboard.sh <change-id> [options]
+
+Display progress dashboard for a change package:
+- Task completion rate and breakdown
+- Role status (current role, handoff state)
+- Evidence status (Red baseline, Green final)
+
+Options:
+  --project-root <dir>  Project root directory (default: pwd)
+  --change-root <dir>   Change packages root (default: changes)
+  --format <fmt>        Output format: text (default), markdown, json
+  -h, --help            Show this help message
+
+Exit Codes:
+  0 - Dashboard generated successfully
+  1 - Change package not found or error
+  2 - Usage error
+
+Examples:
+  progress-dashboard.sh my-change-001
+  progress-dashboard.sh my-change-001 --format markdown
+  progress-dashboard.sh my-change-001 --change-root dev-playbooks/changes
+EOF
+}
+
+if [[ $# -eq 0 ]]; then
+  usage
+  exit 2
+fi
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+change_id="$1"
+shift
+
+project_root="${DEVBOOKS_PROJECT_ROOT:-$(pwd)}"
+change_root="${DEVBOOKS_CHANGE_ROOT:-changes}"
+output_format="text"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --project-root)
+      project_root="${2:-}"
+      shift 2
+      ;;
+    --change-root)
+      change_root="${2:-}"
+      shift 2
+      ;;
+    --format)
+      output_format="${2:-text}"
+      shift 2
+      ;;
+    *)
+      echo "error: unknown option: $1" >&2
+      usage
+      exit 2
+      ;;
+  esac
+done
+
+# Validate change-id
+if [[ -z "$change_id" || "$change_id" == "-"* || "$change_id" =~ [[:space:]] ]]; then
+  echo "error: invalid change-id: '$change_id'" >&2
+  exit 2
+fi
+
+# Validate format
+case "$output_format" in
+  text|markdown|json) ;;
+  *)
+    echo "error: invalid --format: '$output_format' (use: text, markdown, json)" >&2
+    exit 2
+    ;;
+esac
+
+# Build paths
+project_root="${project_root%/}"
+change_root="${change_root%/}"
+
+if [[ "$change_root" = /* ]]; then
+  change_dir="${change_root}/${change_id}"
+else
+  change_dir="${project_root}/${change_root}/${change_id}"
+fi
+
+# Check change directory exists
+if [[ ! -d "$change_dir" ]]; then
+  echo "error: change directory not found: ${change_dir}" >&2
+  exit 1
+fi
+
+# Define file paths
+tasks_file="${change_dir}/tasks.md"
+handoff_file="${change_dir}/handoff.md"
+proposal_file="${change_dir}/proposal.md"
+design_file="${change_dir}/design.md"
+verification_file="${change_dir}/verification.md"
+red_evidence="${change_dir}/evidence/red-baseline"
+green_evidence="${change_dir}/evidence/green-final"
+
+# =============================================================================
+# Collect Data
+# =============================================================================
+
+# Task completion
+total_tasks=0
+completed_tasks=0
+p0_total=0
+p0_completed=0
+p1_total=0
+p1_completed=0
+p2_total=0
+p2_completed=0
+
+if [[ -f "$tasks_file" ]]; then
+  # Count all tasks
+  total_tasks=$(grep -cE "^- \[[xX ]\]" "$tasks_file" 2>/dev/null) || total_tasks=0
+  completed_tasks=$(grep -cE "^- \[[xX]\]" "$tasks_file" 2>/dev/null) || completed_tasks=0
+
+  # Count by priority
+  p0_total=$(grep -cE "^- \[[xX ]\] \[P0\]" "$tasks_file" 2>/dev/null) || p0_total=0
+  p0_completed=$(grep -cE "^- \[[xX]\] \[P0\]" "$tasks_file" 2>/dev/null) || p0_completed=0
+  p1_total=$(grep -cE "^- \[[xX ]\] \[P1\]" "$tasks_file" 2>/dev/null) || p1_total=0
+  p1_completed=$(grep -cE "^- \[[xX]\] \[P1\]" "$tasks_file" 2>/dev/null) || p1_completed=0
+  p2_total=$(grep -cE "^- \[[xX ]\] \[P2\]" "$tasks_file" 2>/dev/null) || p2_total=0
+  p2_completed=$(grep -cE "^- \[[xX]\] \[P2\]" "$tasks_file" 2>/dev/null) || p2_completed=0
+fi
+
+# Calculate completion rate
+if [[ $total_tasks -gt 0 ]]; then
+  completion_rate=$((completed_tasks * 100 / total_tasks))
+else
+  completion_rate=100
+fi
+
+# Role status
+handoff_state="none"
+if [[ -f "$handoff_file" ]]; then
+  confirmed=$(grep -cE "^- \[[xX]\]" "$handoff_file" 2>/dev/null || echo "0")
+  total_sigs=$(grep -cE "^- \[[xX ]\]" "$handoff_file" 2>/dev/null || echo "0")
+  if [[ $confirmed -eq $total_sigs && $total_sigs -gt 0 ]]; then
+    handoff_state="complete"
+  elif [[ $confirmed -gt 0 ]]; then
+    handoff_state="partial"
+  else
+    handoff_state="pending"
+  fi
+fi
+
+# Determine current phase
+current_phase="unknown"
+if [[ ! -f "$proposal_file" ]]; then
+  current_phase="proposal"
+elif [[ ! -f "$design_file" ]]; then
+  current_phase="design"
+elif [[ ! -f "$verification_file" ]]; then
+  current_phase="test-owner"
+elif [[ $completion_rate -lt 100 ]]; then
+  current_phase="coder"
+else
+  current_phase="review"
+fi
+
+# Evidence status
+red_exists="no"
+green_exists="no"
+red_count=0
+green_count=0
+
+if [[ -d "$red_evidence" ]]; then
+  red_count=$(find "$red_evidence" -type f 2>/dev/null | wc -l | tr -d ' ')
+  if [[ $red_count -gt 0 ]]; then
+    red_exists="yes"
+  fi
+fi
+
+if [[ -d "$green_evidence" ]]; then
+  green_count=$(find "$green_evidence" -type f 2>/dev/null | wc -l | tr -d ' ')
+  if [[ $green_count -gt 0 ]]; then
+    green_exists="yes"
+  fi
+fi
+
+# Document status
+proposal_exists=$([[ -f "$proposal_file" ]] && echo "yes" || echo "no")
+design_exists=$([[ -f "$design_file" ]] && echo "yes" || echo "no")
+tasks_exists=$([[ -f "$tasks_file" ]] && echo "yes" || echo "no")
+verification_exists=$([[ -f "$verification_file" ]] && echo "yes" || echo "no")
+
+# =============================================================================
+# Output
+# =============================================================================
+
+case "$output_format" in
+  text)
+    echo "=================================================="
+    echo "Progress Dashboard: ${change_id}"
+    echo "=================================================="
+    echo ""
+    echo "## Task Completion"
+    echo "  Total: ${completed_tasks}/${total_tasks} (${completion_rate}%)"
+    echo "  [P0]: ${p0_completed}/${p0_total}"
+    echo "  [P1]: ${p1_completed}/${p1_total}"
+    echo "  [P2]: ${p2_completed}/${p2_total}"
+    echo ""
+    echo "## Role Status"
+    echo "  Current Phase: ${current_phase}"
+    echo "  Handoff State: ${handoff_state}"
+    echo ""
+    echo "## Evidence Status"
+    echo "  Red Baseline: ${red_exists} (${red_count} files)"
+    echo "  Green Final:  ${green_exists} (${green_count} files)"
+    echo ""
+    echo "## Document Status"
+    echo "  proposal.md:     ${proposal_exists}"
+    echo "  design.md:       ${design_exists}"
+    echo "  tasks.md:        ${tasks_exists}"
+    echo "  verification.md: ${verification_exists}"
+    echo ""
+    ;;
+
+  markdown)
+    echo "# Progress Dashboard: ${change_id}"
+    echo ""
+    echo "## Task Completion"
+    echo ""
+    echo "| Priority | Completed | Total | Rate |"
+    echo "|----------|-----------|-------|------|"
+    echo "| All | ${completed_tasks} | ${total_tasks} | ${completion_rate}% |"
+    echo "| P0 | ${p0_completed} | ${p0_total} | - |"
+    echo "| P1 | ${p1_completed} | ${p1_total} | - |"
+    echo "| P2 | ${p2_completed} | ${p2_total} | - |"
+    echo ""
+    echo "## Role Status"
+    echo ""
+    echo "- **Current Phase**: ${current_phase}"
+    echo "- **Handoff State**: ${handoff_state}"
+    echo ""
+    echo "## Evidence Status"
+    echo ""
+    echo "| Type | Exists | Files |"
+    echo "|------|--------|-------|"
+    echo "| Red Baseline | ${red_exists} | ${red_count} |"
+    echo "| Green Final | ${green_exists} | ${green_count} |"
+    echo ""
+    echo "## Document Status"
+    echo ""
+    echo "| Document | Exists |"
+    echo "|----------|--------|"
+    echo "| proposal.md | ${proposal_exists} |"
+    echo "| design.md | ${design_exists} |"
+    echo "| tasks.md | ${tasks_exists} |"
+    echo "| verification.md | ${verification_exists} |"
+    ;;
+
+  json)
+    # Convert yes/no to JSON boolean true/false
+    red_exists_bool=$([[ "$red_exists" == "yes" ]] && echo "true" || echo "false")
+    green_exists_bool=$([[ "$green_exists" == "yes" ]] && echo "true" || echo "false")
+    proposal_exists_bool=$([[ "$proposal_exists" == "yes" ]] && echo "true" || echo "false")
+    design_exists_bool=$([[ "$design_exists" == "yes" ]] && echo "true" || echo "false")
+    tasks_exists_bool=$([[ "$tasks_exists" == "yes" ]] && echo "true" || echo "false")
+    verification_exists_bool=$([[ "$verification_exists" == "yes" ]] && echo "true" || echo "false")
+
+    cat << EOF
+{
+  "changeId": "${change_id}",
+  "tasks": {
+    "total": ${total_tasks},
+    "completed": ${completed_tasks},
+    "completionRate": ${completion_rate},
+    "byPriority": {
+      "p0": {"total": ${p0_total}, "completed": ${p0_completed}},
+      "p1": {"total": ${p1_total}, "completed": ${p1_completed}},
+      "p2": {"total": ${p2_total}, "completed": ${p2_completed}}
+    }
+  },
+  "role": {
+    "currentPhase": "${current_phase}",
+    "handoffState": "${handoff_state}"
+  },
+  "evidence": {
+    "redBaseline": {"exists": ${red_exists_bool}, "fileCount": ${red_count}},
+    "greenFinal": {"exists": ${green_exists_bool}, "fileCount": ${green_count}}
+  },
+  "documents": {
+    "proposal": ${proposal_exists_bool},
+    "design": ${design_exists_bool},
+    "tasks": ${tasks_exists_bool},
+    "verification": ${verification_exists_bool}
+  }
+}
+EOF
+    ;;
+esac
+
+exit 0

package/skills/devbooks-delivery-workflow/scripts/prototype-promote.sh

@@ -0,0 +1,341 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================================================
+# prototype-promote.sh
+# ============================================================================
+# Promotes a prototype to production track.
+#
+# This script enforces:
+# 1. PROTOTYPE.md checklist is complete
+# 2. Production design.md exists with AC-xxx items
+# 3. Production verification.md exists (Test Owner has produced acceptance tests)
+# 4. All quality gates pass before promotion
+#
+# Reference: "The Mythical Man-Month" Chapter 11 "Plan to Throw One Away"
+# ============================================================================
+
+usage() {
+  cat <<'EOF' >&2
+usage: prototype-promote.sh <change-id> [--project-root <dir>] [--change-root <dir>] [--archive-dir <dir>] [--force]
+
+Promotes a prototype to production track:
+1. Validates prototype/PROTOTYPE.md checklist is complete
+2. Requires design.md to exist with AC-xxx items
+3. Requires verification.md to exist (Test Owner acceptance tests)
+4. Archives characterization tests to <archive-dir>/<change-id>/
+5. Removes prototype/ directory
+
+Defaults (can be overridden by flags or env):
+  DEVBOOKS_PROJECT_ROOT: pwd
+  DEVBOOKS_CHANGE_ROOT:  changes
+  Archive directory:     tests/archived-characterization
+
+Options:
+  --force         Skip confirmation prompt
+  --archive-dir   Custom archive directory for characterization tests
+
+WARNING: This script enforces that:
+- Test Owner has produced NEW acceptance tests (not just characterization tests)
+- All quality gates (design.md, verification.md) exist
+- Prototype checklist is complete
+
+Example:
+  prototype-promote.sh my-feature-001
+  prototype-promote.sh my-feature-001 --project-root /path/to/repo
+EOF
+}
+
+# Color output helpers
+red() { printf '\033[0;31m%s\033[0m\n' "$*" >&2; }
+green() { printf '\033[0;32m%s\033[0m\n' "$*" >&2; }
+yellow() { printf '\033[0;33m%s\033[0m\n' "$*" >&2; }
+
+err() { red "error: $*"; }
+warn() { yellow "warn: $*"; }
+ok() { green "ok: $*"; }
+
+if [[ $# -eq 0 ]]; then
+  usage
+  exit 2
+fi
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+change_id="$1"
+shift
+
+project_root="${DEVBOOKS_PROJECT_ROOT:-$(pwd)}"
+change_root="${DEVBOOKS_CHANGE_ROOT:-changes}"
+archive_dir=""
+force=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --project-root)
+      project_root="${2:-}"
+      shift 2
+      ;;
+    --change-root)
+      change_root="${2:-}"
+      shift 2
+      ;;
+    --archive-dir)
+      archive_dir="${2:-}"
+      shift 2
+      ;;
+    --force)
+      force=true
+      shift
+      ;;
+    *)
+      usage
+      exit 2
+      ;;
+  esac
+done
+
+if [[ -z "$change_id" ]]; then
+  err "change-id is required"
+  exit 2
+fi
+
+# Normalize paths
+project_root="${project_root%/}"
+change_root="${change_root%/}"
+
+if [[ "$change_root" = /* ]]; then
+  change_dir="${change_root}/${change_id}"
+else
+  change_dir="${project_root}/${change_root}/${change_id}"
+fi
+
+# Default archive directory
+if [[ -z "$archive_dir" ]]; then
+  archive_dir="${project_root}/tests/archived-characterization"
+fi
+
+prototype_dir="${change_dir}/prototype"
+prototype_md="${prototype_dir}/PROTOTYPE.md"
+design_md="${change_dir}/design.md"
+verification_md="${change_dir}/verification.md"
+
+# ============================================================================
+# Validation checks
+# ============================================================================
+
+echo "=== Prototype Promotion Check: ${change_id} ==="
+echo ""
+
+errors=0
+
+# Check 1: Prototype directory exists
+if [[ ! -d "$prototype_dir" ]]; then
+  err "no prototype directory found: ${prototype_dir}"
+  err "hint: run 'change-scaffold.sh ${change_id} --prototype' first"
+  exit 1
+fi
+
+echo "checking: prototype directory exists"
+ok "found: ${prototype_dir}"
+
+# Check 2: PROTOTYPE.md exists
+if [[ ! -f "$prototype_md" ]]; then
+  err "missing: ${prototype_md}"
+  ((errors++))
+else
+  echo "checking: PROTOTYPE.md exists"
+  ok "found: ${prototype_md}"
+
+  # Check 3: Promotion checklist is complete (no unchecked items in promotion section)
+  echo "checking: promotion checklist is complete"
+
+  # Extract lines between "Promotion Checklist" and next "## " or "Discard Checklist"
+  # and check for unchecked items "- [ ]"
+  if grep -A 20 "Promotion Checklist" "$prototype_md" 2>/dev/null | \
+     grep -B 20 -E "(^## |Discard Checklist)" 2>/dev/null | \
+     grep -q "^\- \[ \]"; then
+    err "unchecked items in promotion checklist"
+    err "hint: complete all items in 'Promotion Checklist' section of PROTOTYPE.md"
+    grep -A 20 "Promotion Checklist" "$prototype_md" | grep "^\- \[ \]" | head -5 >&2
+    ((errors++))
+  else
+    ok "promotion checklist complete"
+  fi
+fi
+
+# Check 4: Production design.md exists
+echo "checking: production design.md exists"
+if [[ ! -f "$design_md" ]]; then
+  err "missing: ${design_md}"
+  err "hint: create production-level design.md with AC-xxx items"
+  ((errors++))
+else
+  ok "found: ${design_md}"
+
+  # Check 4b: design.md contains AC-xxx items
+  echo "checking: design.md contains AC-xxx items"
+  if ! grep -qE "AC-[0-9]+" "$design_md" 2>/dev/null; then
+    warn "no AC-xxx items found in design.md"
+    warn "hint: add acceptance criteria (e.g., AC-001, AC-002)"
+  else
+    ac_count=$(grep -oE "AC-[0-9]+" "$design_md" | sort -u | wc -l | tr -d ' ')
+    ok "found ${ac_count} AC-xxx item(s)"
+  fi
+fi
+
+# Check 5: Production verification.md exists
+echo "checking: production verification.md exists"
+if [[ ! -f "$verification_md" ]]; then
+  err "missing: ${verification_md}"
+  err "hint: Test Owner must produce acceptance tests (not just characterization tests)"
+  ((errors++))
+else
+  ok "found: ${verification_md}"
+fi
+
+# Check 6: Characterization tests exist (warning only)
+echo "checking: characterization tests exist"
+char_dir="${prototype_dir}/characterization"
+if [[ -d "$char_dir" ]] && [[ -n "$(ls -A "$char_dir" 2>/dev/null)" ]]; then
+  char_count=$(find "$char_dir" -type f \( -name "*.py" -o -name "*.ts" -o -name "*.js" -o -name "*.test.*" \) 2>/dev/null | wc -l | tr -d ' ')
+  ok "found ${char_count} characterization test file(s)"
+else
+  warn "no characterization tests found in ${char_dir}"
+  warn "hint: characterization tests help preserve behavior knowledge"
+fi
+
+# Check 7: Basic test coverage (P1 - harden-devbooks-quality-gates)
+echo "checking: prototype has basic test coverage"
+proto_src="${prototype_dir}/src"
+if [[ -d "$proto_src" ]]; then
+  src_count=$(find "$proto_src" -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.sh" \) 2>/dev/null | wc -l | tr -d ' ')
+  test_count=$(find "$prototype_dir" -type f \( -name "*.test.*" -o -name "*_test.*" -o -name "*.spec.*" \) 2>/dev/null | wc -l | tr -d ' ')
+
+  if [[ "$src_count" -gt 0 ]]; then
+    if [[ "$test_count" -eq 0 ]]; then
+      warn "no test files found for ${src_count} source files in prototype"
+      warn "hint: consider adding characterization tests before promotion"
+    else
+      ratio=$((test_count * 100 / src_count))
+      if [[ "$ratio" -lt 50 ]]; then
+        warn "low test coverage: ${test_count} test files for ${src_count} source files (${ratio}%)"
+      else
+        ok "test coverage: ${test_count} test files for ${src_count} source files (${ratio}%)"
+      fi
+    fi
+  fi
+fi
+
+# Check 8: Complexity threshold warning (P1 - harden-devbooks-quality-gates)
+echo "checking: prototype complexity"
+if [[ -d "$proto_src" ]]; then
+  # Count total lines of code
+  total_loc=$(find "$proto_src" -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.sh" \) -exec cat {} \; 2>/dev/null | wc -l | tr -d ' ')
+
+  # Complexity threshold: warn if > 1000 lines (configurable via env)
+  complexity_threshold="${PROTOTYPE_COMPLEXITY_THRESHOLD:-1000}"
+
+  if [[ "$total_loc" -gt "$complexity_threshold" ]]; then
+    warn "prototype exceeds complexity threshold: ${total_loc} lines (threshold: ${complexity_threshold})"
+    warn "hint: consider breaking into smaller modules before promotion"
+  else
+    ok "complexity: ${total_loc} lines (threshold: ${complexity_threshold})"
+  fi
+fi
+
+echo ""
+
+# ============================================================================
+# Error summary
+# ============================================================================
+
+if [[ $errors -gt 0 ]]; then
+  echo "=== Promotion Blocked ==="
+  err "${errors} error(s) found"
+  echo ""
+  echo "Required before promotion:"
+  echo "  1. Complete all items in PROTOTYPE.md 'Promotion Checklist'"
+  echo "  2. Create production design.md with AC-xxx items"
+  echo "  3. Have Test Owner create verification.md with acceptance tests"
+  exit 1
+fi
+
+# ============================================================================
+# Confirmation
+# ============================================================================
+
+echo "=== Ready for Promotion ==="
+echo ""
+echo "This will:"
+echo "  1. Archive characterization tests to: ${archive_dir}/${change_id}/"
+echo "  2. Remove prototype directory: ${prototype_dir}"
+echo ""
+
+if [[ "$force" != true ]]; then
+  read -r -p "Proceed? [y/N] " response
+  case "$response" in
+    [yY][eE][sS]|[yY])
+      ;;
+    *)
+      echo "aborted"
+      exit 0
+      ;;
+  esac
+fi
+
+# ============================================================================
+# Execute promotion
+# ============================================================================
+
+# Archive characterization tests
+if [[ -d "$char_dir" ]] && [[ -n "$(ls -A "$char_dir" 2>/dev/null)" ]]; then
+  mkdir -p "${archive_dir}/${change_id}"
+  cp -r "${char_dir}/"* "${archive_dir}/${change_id}/" 2>/dev/null || true
+  ok "archived: characterization tests -> ${archive_dir}/${change_id}/"
+fi
+
+# Create promotion record
+cat > "${change_dir}/evidence/prototype-promotion.md" <<EOF
+# Prototype Promotion Record
+
+- Change ID: ${change_id}
+- Promoted at: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+- Characterization tests archived to: ${archive_dir}/${change_id}/
+
+## Pre-promotion state
+
+- Prototype directory existed: yes
+- PROTOTYPE.md checklist: complete
+- design.md: present
+- verification.md: present
+
+## Post-promotion
+
+- Prototype directory: removed
+- Production track: active
+
+---
+Reference: "The Mythical Man-Month" Chapter 11 - "The first system built is not suitable...plan to throw one away"
+EOF
+ok "created: ${change_dir}/evidence/prototype-promotion.md"
+
+# Remove prototype directory
+rm -rf "$prototype_dir"
+ok "removed: ${prototype_dir}"
+
+echo ""
+echo "=== Promotion Complete ==="
+ok "prototype promoted for ${change_id}"
+echo ""
+echo "Next steps:"
+echo "  1. Run 'change-check.sh ${change_id} --mode apply' to validate production track"
+echo "  2. Coder implements against verification.md acceptance tests"
+echo "  3. Review characterization tests in ${archive_dir}/${change_id}/ for behavior reference"