@moretea-labs/forge 1.6.0 → 1.7.1

package/scripts/check-task-workflow.sh

@@ -1,1002 +1,4 @@
 #!/bin/bash
 set -euo pipefail
-
-usage() {
-  cat <<'USAGE_EOF'
-Usage: scripts/check-task-workflow.sh [--strict]
-USAGE_EOF
-}
-
-strict=0
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --strict)
-      strict=1
-      shift
-      ;;
-    --help|-h)
-      usage
-      exit 0
-      ;;
-    *)
-      echo "Unknown argument: $1" >&2
-      usage
-      exit 1
-      ;;
-  esac
-done
-
-issues=0
-bootstrap_issues=0
-WORKFLOW_CONTRACT_PATH=".ai/harness/workflow-contract.json"
-policy_file=".ai/harness/policy.json"
-json_runtime=""
-
-report_issue() {
-  local message="$1"
-  echo "[workflow] $message"
-  issues=$((issues + 1))
-}
-
-report_bootstrap() {
-  local message="$1"
-  bootstrap_issues=$((bootstrap_issues + 1))
-  echo "[workflow] Bootstrap/remediation required (ignored runtime; check is read-only): $message"
-  echo "[workflow] Supported remediation: bash scripts/migrate-project-template.sh --repo . --dry-run (inspect), then run the repository bootstrap/migration command in the owning checkout."
-}
-
-resolve_json_runtime() {
-  if command -v node >/dev/null 2>&1; then
-    printf 'node'
-    return 0
-  fi
-
-  if command -v bun >/dev/null 2>&1; then
-    printf 'bun'
-    return 0
-  fi
-
-  if command -v python3 >/dev/null 2>&1; then
-    printf 'python3'
-    return 0
-  fi
-
-  return 1
-}
-
-contract_query_lines() {
-  local selector="$1"
-  local runtime
-
-  runtime="$(resolve_json_runtime || true)"
-  if [[ -z "$runtime" || ! -f "$WORKFLOW_CONTRACT_PATH" ]]; then
-    return 1
-  fi
-
-  case "$runtime" in
-    python3)
-      "$runtime" - "$WORKFLOW_CONTRACT_PATH" "$selector" <<'PY_EOF'
-import json
-import sys
-
-path, selector = sys.argv[1], sys.argv[2]
-value = json.load(open(path, "r", encoding="utf-8"))
-for part in selector.split("."):
-    value = value.get(part) if isinstance(value, dict) else None
-if isinstance(value, list):
-    for item in value:
-        print(item)
-elif value is not None:
-    print(value)
-PY_EOF
-      ;;
-    *)
-      "$runtime" -e '
-const fs = require("fs");
-const [, filePath, selector] = process.argv;
-let value = JSON.parse(fs.readFileSync(filePath, "utf8"));
-for (const part of selector.split(".")) {
-  value = value && typeof value === "object" ? value[part] : undefined;
-}
-if (Array.isArray(value)) {
-  for (const item of value) {
-    console.log(item);
-  }
-} else if (value !== undefined && value !== null) {
-  console.log(value);
-}
-' "$WORKFLOW_CONTRACT_PATH" "$selector"
-      ;;
-  esac
-}
-
-ACTIVE_PLAN_MARKER=".ai/harness/active-plan"
-LEGACY_ACTIVE_PLAN_MARKER=".claude/.active-plan"
-ACTIVE_WORKTREE_MARKER=".ai/harness/active-worktree"
-
-read_active_plan_marker() {
-  local marker_file="$1"
-  local marker_plan
-
-  if [[ -f "$marker_file" ]]; then
-    marker_plan="$(cat "$marker_file" 2>/dev/null | xargs)"
-    if [[ -n "$marker_plan" && -f "$marker_plan" ]]; then
-      printf '%s' "$marker_plan"
-      return 0
-    fi
-  fi
-
-  return 1
-}
-
-get_active_plan() {
-  read_active_plan_marker "$ACTIVE_PLAN_MARKER" \
-    || read_active_plan_marker "$LEGACY_ACTIVE_PLAN_MARKER"
-}
-
-extract_status() {
-  local file="$1"
-  # Trim with sed, not xargs: xargs aborts on unbalanced quotes in user-edited
-  # status text, which would kill the whole check under set -e.
-  awk '/\*\*Status\*\*:/ {sub(/^.*\*\*Status\*\*: */, ""); gsub(/\r/, ""); print; exit}' "$file" \
-    | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//'
-}
-
-plan_evidence_contract_error() {
-  local file="$1"
-  local section=""
-  local missing=0
-
-  section="$(awk '
-    BEGIN { in_section = 0 }
-    /^## Evidence Contract[[:space:]]*$/ { in_section = 1; next }
-    in_section && /^## / { exit }
-    in_section { print }
-  ' "$file")"
-
-  if [[ -z "$(printf '%s' "$section" | tr -d '[:space:]')" ]]; then
-    echo "missing ## Evidence Contract section"
-    return 1
-  fi
-
-  local label line value
-  for label in "State/progress path" "Verification evidence" "Evaluator rubric" "Stop condition" "Rollback surface"; do
-    line="$(printf '%s\n' "$section" | grep -Ei "^[[:space:]]*-[[:space:]]*(\\*\\*)?${label}(\\*\\*)?[[:space:]]*:" | head -1 || true)"
-    if [[ -z "$line" ]]; then
-      echo "missing field: ${label}"
-      missing=1
-      continue
-    fi
-
-    value="${line#*:}"
-    value="$(printf '%s' "$value" | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')"
-    if [[ -z "$value" ]] || printf '%s' "$value" | grep -Eiq '^(tbd|todo|n/a|none|unknown|\.\.\.)$'; then
-      echo "field has no concrete value: ${label}"
-      missing=1
-    fi
-  done
-
-  [[ "$missing" -eq 0 ]]
-}
-
-check_plan_template_evidence_contract() {
-  local file="$1"
-  local label
-
-  grep -Eq '^## Evidence Contract[[:space:]]*$' "$file" || {
-    report_issue "Plan template is missing ## Evidence Contract: $file"
-    return
-  }
-
-  for label in "State/progress path" "Verification evidence" "Evaluator rubric" "Stop condition" "Rollback surface"; do
-    if ! grep -Eiq "^[[:space:]]*-[[:space:]]*(\\*\\*)?${label}(\\*\\*)?[[:space:]]*:" "$file"; then
-      report_issue "Plan template Evidence Contract is missing field '${label}': $file"
-    fi
-  done
-}
-
-todo_source_plan() {
-  if [[ ! -f "${todo_file:-tasks/todos.md}" ]]; then
-    return 1
-  fi
-  awk -F': ' '/^\> \*\*Source Plan\*\*:/ {print $2; exit}' "${todo_file:-tasks/todos.md}" | xargs
-}
-
-todo_is_deferred_ledger() {
-  local file="${1:-${todo_file:-tasks/todos.md}}"
-  [[ -f "$file" ]] || return 1
-  grep -Eq '^# Deferred Goal Ledger[[:space:]]*$' "$file" \
-    && grep -Eq '^> \*\*Status\*\*:[[:space:]]*Backlog[[:space:]]*$' "$file"
-}
-
-todo_deferred_ledger_error() {
-  local file="${1:-${todo_file:-tasks/todos.md}}"
-  local missing=0
-
-  grep -Eq '^# Deferred Goal Ledger[[:space:]]*$' "$file" || {
-    echo "missing '# Deferred Goal Ledger' heading"
-    missing=1
-  }
-  grep -Eq '^> \*\*Status\*\*:[[:space:]]*Backlog[[:space:]]*$' "$file" || {
-    echo "missing Backlog status"
-    missing=1
-  }
-  grep -Eq '^## Deferred Goals[[:space:]]*$' "$file" || {
-    echo "missing ## Deferred Goals section"
-    missing=1
-  }
-  grep -Eq '\|[[:space:]]*Goal[[:space:]]*\|[[:space:]]*Why Deferred[[:space:]]*\|[[:space:]]*Tradeoff[[:space:]]*\|[[:space:]]*Revisit Trigger[[:space:]]*\|' "$file" || {
-    echo "missing deferred-goal table with Tradeoff and Revisit Trigger"
-    missing=1
-  }
-
-  [[ "$missing" -eq 0 ]]
-}
-
-sprint_known_status() {
-  case "$1" in
-    Draft|Approved|Executing|Done|Archived)
-      return 0
-      ;;
-  esac
-  return 1
-}
-
-prd_known_status() {
-  case "$1" in
-    Draft|Approved|Superseded)
-      return 0
-      ;;
-  esac
-  return 1
-}
-
-markdown_section_has_content() {
-  local file="$1"
-  local section="$2"
-  awk -v section="$section" '
-    $0 ~ "^## " section "[[:space:]]*$" { in_section = 1; next }
-    in_section && /^## / { exit }
-    !in_section { next }
-    /^#/ { next }
-    {
-      line = $0
-      gsub(/^[[:space:]]*[->]*[[:space:]]*/, "", line)
-      gsub(/[[:space:]]+$/, "", line)
-      if (line == "" || line == "..." || line ~ /^Replace /) next
-      content = 1
-    }
-    END { exit content ? 0 : 1 }
-  ' "$file"
-}
-
-sprint_prd_has_content() {
-  local file="$1"
-  markdown_section_has_content "$file" "PRD"
-}
-
-sprint_ready_error() {
-  local file="$1"
-  local missing=0
-
-  if ! sprint_prd_has_content "$file"; then
-    echo "PRD section is empty or placeholder-only"
-    missing=1
-  fi
-
-  if ! grep -Eq '^\|[[:space:]]*#[[:space:]]*\|[[:space:]]*Status[[:space:]]*\|[[:space:]]*Task[[:space:]]*\|[[:space:]]*Mode[[:space:]]*\|[[:space:]]*Acceptance[[:space:]]*\|[[:space:]]*Plan[[:space:]]*\|' "$file"; then
-    echo "missing backlog table header '| # | Status | Task | Mode | Acceptance | Plan |'"
-    missing=1
-  else
-    local row_errors
-    row_errors="$(awk -F '|' '
-      /^## Backlog[[:space:]]*$/ { in_section = 1; next }
-      in_section && /^## / { exit }
-      !in_section { next }
-      /^\|[[:space:]]*[0-9]+[[:space:]]*\|/ {
-        rows++
-        idx = $2; status = $3; task = $4; mode = $5; acceptance = $6
-        gsub(/^[[:space:]]+|[[:space:]]+$/, "", idx)
-        gsub(/^[[:space:]]+|[[:space:]]+$/, "", status)
-        gsub(/^[[:space:]]+|[[:space:]]+$/, "", task)
-        gsub(/^[[:space:]]+|[[:space:]]+$/, "", mode)
-        gsub(/^[[:space:]]+|[[:space:]]+$/, "", acceptance)
-        if (status !~ /^\[[ xX]\]$/) printf "row %s has an invalid status cell (expected [ ] or [x])\n", idx
-        if (task == "" || task == "...") printf "row %s is missing a task\n", idx
-        if (mode != "contract" && mode != "inline") printf "row %s has an invalid mode (expected contract or inline)\n", idx
-        if (acceptance == "" || tolower(acceptance) ~ /^(\.\.\.|tbd|todo|n\/a|none)$/) printf "row %s is missing a concrete acceptance line\n", idx
-        if (acceptance == "Replace with a machine-checkable acceptance line") printf "row %s still has the template placeholder acceptance\n", idx
-        seen_idx[idx]++
-        if (task != "") seen_task[task]++
-      }
-      END {
-        if (rows == 0) print "backlog table has no task rows"
-        for (i in seen_idx) if (seen_idx[i] > 1) printf "duplicate backlog index %s\n", i
-        for (t in seen_task) if (seen_task[t] > 1) printf "duplicate backlog task %s\n", t
-      }
-    ' "$file")"
-    if [[ -n "$row_errors" ]]; then
-      printf '%s\n' "$row_errors"
-      missing=1
-    fi
-  fi
-
-  [[ "$missing" -eq 0 ]]
-}
-
-prd_ready_error() {
-  local file="$1"
-  local missing=0
-
-  for section in "AI Quick-Read Card" "Problem" "Acceptance Scenarios"; do
-    if ! markdown_section_has_content "$file" "$section"; then
-      echo "PRD section '$section' is missing or placeholder-only"
-      missing=1
-    fi
-  done
-
-  [[ "$missing" -eq 0 ]]
-}
-
-derive_slug() {
-  basename "$1" | sed -E 's/^plan-[0-9]{8}-[0-9]{4}-//; s/\.md$//'
-}
-
-plan_contract_path() {
-  local plan_file="$1" path
-  path="$(awk '
-    /^> \*\*Task Contract\*\*:/ {
-      sub(/^> \*\*Task Contract\*\*:[[:space:]]*/, "")
-      gsub(/`/, "")
-      print
-      exit
-    }
-    /^> \*\*Sprint Contract\*\*:/ {
-      sub(/^> \*\*Sprint Contract\*\*:[[:space:]]*/, "")
-      gsub(/`/, "")
-      print
-      exit
-    }
-  ' "$plan_file" | xargs)"
-
-  case "$path" in
-    tasks/contracts/*.contract.md)
-      printf '%s' "$path"
-      ;;
-  esac
-}
-
-derive_contract_path() {
-  local plan_file="$1"
-  local explicit slug stem
-  explicit="$(plan_contract_path "$plan_file")"
-  if [[ -n "$explicit" ]]; then
-    printf '%s' "$explicit"
-    return 0
-  fi
-
-  slug="$(derive_slug "$plan_file")"
-  stem="$(basename "$plan_file" | sed -E 's/^plan-//; s/\.md$//')"
-  if [[ -f "tasks/contracts/${stem}.contract.md" ]] || [[ ! -f "tasks/contracts/${slug}.contract.md" ]]; then
-    printf 'tasks/contracts/%s.contract.md' "$stem"
-  else
-    printf 'tasks/contracts/%s.contract.md' "$slug"
-  fi
-}
-
-file_mtime() {
-  local file="$1"
-  local mtime
-
-  mtime="$(stat -c '%Y' "$file" 2>/dev/null || true)"
-  if [[ "$mtime" =~ ^[0-9]+$ ]]; then
-    printf '%s' "$mtime"
-    return 0
-  fi
-
-  mtime="$(stat -f '%m' "$file" 2>/dev/null || true)"
-  if [[ "$mtime" =~ ^[0-9]+$ ]]; then
-    printf '%s' "$mtime"
-    return 0
-  fi
-
-  printf '0'
-}
-
-handoff_declares_no_active_plan() {
-  local file="$1"
-  [[ -f "$file" ]] || return 1
-  grep -Eiq '(^|[^[:alnum:]])No active plan([^[:alnum:]]|$)|^[[:space:]]*(-[[:space:]]*)?(Active Plan|Plan):[[:space:]]*\(none\)[[:space:]]*$' "$file"
-}
-
-resume_references_plan() {
-  local file="$1"
-  [[ -f "$file" ]] || return 1
-  grep -Eiq '^[[:space:]]*-[[:space:]]*(Active plan|Plan):[[:space:]]+`?plans/' "$file"
-}
-
-check_handoff_resume_pair() {
-  local handoff_file="$1"
-  local resume_file="$2"
-  local handoff_mtime resume_mtime
-
-  [[ -f "$handoff_file" || -f "$resume_file" ]] || return 0
-
-  if [[ -f "$handoff_file" && ! -f "$resume_file" ]]; then
-    report_bootstrap "Handoff current exists but resume packet is missing: $resume_file"
-    return 0
-  fi
-
-  if [[ ! -f "$handoff_file" && -f "$resume_file" ]]; then
-    report_bootstrap "Resume packet exists but handoff current is missing: $handoff_file"
-    return 0
-  fi
-
-  handoff_mtime="$(file_mtime "$handoff_file")"
-  resume_mtime="$(file_mtime "$resume_file")"
-  if [[ "$resume_mtime" =~ ^[0-9]+$ && "$handoff_mtime" =~ ^[0-9]+$ && "$resume_mtime" -lt "$handoff_mtime" ]]; then
-    report_bootstrap "Resume packet is older than handoff current: $resume_file < $handoff_file. Refresh it with scripts/prepare-handoff.sh or scripts/codex-handoff-resume.sh."
-  fi
-
-  if handoff_declares_no_active_plan "$handoff_file" && resume_references_plan "$resume_file"; then
-    report_bootstrap "Handoff current declares no active plan but resume packet references a historical plan: $resume_file. Archive or regenerate the resume packet before continuing."
-  fi
-}
-
-check_current_resume_freshness() {
-  local current_file="$1"
-  local resume_file="$2"
-  local current_mtime resume_mtime
-
-  [[ -f "$current_file" && -f "$resume_file" ]] || return 0
-  current_mtime="$(file_mtime "$current_file")"
-  resume_mtime="$(file_mtime "$resume_file")"
-  if [[ "$current_mtime" =~ ^[0-9]+$ && "$resume_mtime" =~ ^[0-9]+$ && "$resume_mtime" -lt "$current_mtime" ]]; then
-    report_bootstrap "Resume packet is older than current status snapshot: $resume_file < $current_file. Run scripts/prepare-handoff.sh --reason <reason> or scripts/codex-handoff-resume.sh."
-  fi
-}
-
-check_required_file() {
-  local path="$1"
-  if [[ -f "$path" ]]; then
-    return 0
-  fi
-
-  if [[ "$path" == .ai/harness/scripts/* ]]; then
-    local helper_name="${path##*/}"
-    if [[ "${helper_source:-package}" == "package" && -f "scripts/$helper_name" ]]; then
-      return 0
-    fi
-    if [[ -f "assets/templates/helpers/$helper_name" && -f "scripts/$helper_name" ]]; then
-      return 0
-    fi
-  fi
-
-  case "$path" in
-    .ai/context/*|.ai/harness/*)
-      report_bootstrap "Missing generated runtime file: $path"
-      ;;
-    *)
-      report_issue "Missing required file: $path"
-      ;;
-  esac
-}
-
-check_reference_config_stub() {
-  local path="$1"
-  [[ -f "$path" ]] || return 0
-  grep -Fq "<!-- forge: reference-config-stub v1 -->" "$path" || return 0
-
-  local name="${path##*/}"
-  local doc_id="${name%.md}"
-  if ! grep -Fq "> **Doc ID**: $doc_id" "$path"; then
-    report_issue "Reference config stub has wrong or missing Doc ID: $path"
-  fi
-  if ! grep -Fq "forge docs path $doc_id" "$path"; then
-    report_issue "Reference config stub is missing resolver command: $path"
-  fi
-}
-
-check_reference_config_stubs() {
-  local path
-  if [[ ! -d "docs/reference-configs" ]]; then
-    return 0
-  fi
-  for path in docs/reference-configs/*.md; do
-    [[ -e "$path" ]] || continue
-    check_reference_config_stub "$path"
-  done
-}
-
-check_generation_surface_terminology() {
-  local file
-  local surfaces=(
-    ".claude/templates/plan.template.md"
-    ".claude/templates/contract.template.md"
-    ".claude/templates/review.template.md"
-    "scripts/capture-plan.sh"
-    "scripts/new-plan.sh"
-    "scripts/ensure-task-workflow.sh"
-    "scripts/plan-to-todo.sh"
-    "scripts/lib/project-init-lib.sh"
-  )
-
-  for file in "${surfaces[@]}"; do
-    [[ -f "$file" ]] || continue
-    if grep -Eq 'Sprint Contract|Sprint Review' "$file"; then
-      report_issue "Legacy task artifact terminology in generation surface: $file. Use Task Contract / Task Review for new artifacts; keep verify-sprint.sh and other legacy filenames only for compatibility."
-    fi
-    if grep -Eq 'tasks/todo\.md|tasks/sprints/' "$file"; then
-      report_issue "Legacy workflow path emitted by generation surface: $file. Migrate tasks/todo.md to tasks/todos.md and tasks/sprints/*.sprint.md to plans/sprints/."
-    fi
-  done
-}
-
-trace_schema_error() {
-  local file="$1"
-  local runtime
-
-  [[ -s "$file" ]] || return 0
-  if ! grep -q '[^[:space:]]' "$file"; then
-    return 0
-  fi
-  if grep -Eq '^[[:space:]]*\{[[:space:]]*\}[[:space:]]*$' "$file"; then
-    return 0
-  fi
-
-  runtime="$(resolve_json_runtime || true)"
-  if [[ -z "$runtime" ]]; then
-    echo "missing node, bun, or python3 to validate trace schema"
-    return 1
-  fi
-
-  case "$runtime" in
-    python3)
-      "$runtime" - "$file" <<'PY_EOF'
-import json
-import sys
-
-path = sys.argv[1]
-try:
-    data = json.load(open(path, "r", encoding="utf-8"))
-except Exception as exc:
-    print(f"invalid JSON: {exc}")
-    sys.exit(1)
-
-errors = []
-if data.get("schema") != "forge-run-trace.v1":
-    errors.append("schema must be forge-run-trace.v1")
-for key in ["run_id", "task_profile", "active_plan", "worktree", "branch", "failure_class", "next_step"]:
-    if key not in data:
-        errors.append(f"missing field: {key}")
-for key in ["commands", "guards", "handoffs", "files_changed"]:
-    if not isinstance(data.get(key), list):
-        errors.append(f"field must be an array: {key}")
-for key in ["external_acceptance", "allowed_paths_check"]:
-    if not isinstance(data.get(key), dict):
-        errors.append(f"field must be an object: {key}")
-if data.get("status") not in ["pass", "fail"]:
-    errors.append("status must be pass or fail")
-contract = data.get("contract")
-if not (isinstance(contract, str) or (isinstance(contract, dict) and contract.get("file"))):
-    errors.append("contract must be a string or object with file")
-review = data.get("review")
-if not (isinstance(review, str) or (isinstance(review, dict) and "file" in review)):
-    errors.append("review must be a string or object with file")
-if errors:
-    print("; ".join(errors))
-    sys.exit(1)
-PY_EOF
-      ;;
-    *)
-      "$runtime" -e '
-const fs = require("fs");
-const file = process.argv[1];
-let data;
-try {
-  data = JSON.parse(fs.readFileSync(file, "utf8"));
-} catch (error) {
-  console.log(`invalid JSON: ${error.message}`);
-  process.exit(1);
-}
-const errors = [];
-if (data.schema !== "forge-run-trace.v1") errors.push("schema must be forge-run-trace.v1");
-for (const key of ["run_id", "task_profile", "active_plan", "worktree", "branch", "failure_class", "next_step"]) {
-  if (!(key in data)) errors.push(`missing field: ${key}`);
-}
-for (const key of ["commands", "guards", "handoffs", "files_changed"]) {
-  if (!Array.isArray(data[key])) errors.push(`field must be an array: ${key}`);
-}
-for (const key of ["external_acceptance", "allowed_paths_check"]) {
-  if (!data[key] || typeof data[key] !== "object" || Array.isArray(data[key])) {
-    errors.push(`field must be an object: ${key}`);
-  }
-}
-if (!["pass", "fail"].includes(data.status)) errors.push("status must be pass or fail");
-if (!(typeof data.contract === "string" || (data.contract && typeof data.contract === "object" && data.contract.file))) {
-  errors.push("contract must be a string or object with file");
-}
-if (!(typeof data.review === "string" || (data.review && typeof data.review === "object" && "file" in data.review))) {
-  errors.push("review must be a string or object with file");
-}
-if (errors.length) {
-  console.log(errors.join("; "));
-  process.exit(1);
-}
-' "$file"
-      ;;
-  esac
-}
-
-check_required_dir() {
-  local path="$1"
-  if [[ -d "$path" ]]; then
-    return 0
-  fi
-
-  if [[ "$path" == ".ai/harness/scripts" && "${helper_source:-package}" == "package" && -d "scripts" ]]; then
-    return 0
-  fi
-
-  if [[ "$path" == ".ai/harness/scripts" && -d "assets/templates/helpers" && -d "scripts" ]]; then
-    return 0
-  fi
-
-  case "$path" in
-    .ai/context|.ai/context/*|.ai/harness|.ai/harness/*)
-      report_bootstrap "Missing generated runtime directory: $path"
-      ;;
-    *)
-      report_issue "Missing required directory: $path"
-      ;;
-  esac
-}
-
-check_helper_runtime_files() {
-  local helper_names=()
-  local helper_name
-
-  if [[ -f "$WORKFLOW_CONTRACT_PATH" ]]; then
-    while IFS= read -r helper_name; do
-      [[ -n "$helper_name" ]] && helper_names+=("$helper_name")
-    done < <(contract_query_lines "helpers.scripts" 2>/dev/null || true)
-  fi
-
-  if [[ "${#helper_names[@]}" -eq 0 ]]; then
-    helper_names=(
-      new-spec.sh new-sprint.sh new-plan.sh capture-plan.sh plan-to-todo.sh
-      contract-run.ts contract-worktree.sh ship-worktrees.sh archive-workflow.sh
-      refresh-current-status.sh prepare-handoff.sh verify-contract.sh summarize-failures.sh
-      verify-sprint.sh harness-trace-grade.sh sprint-backlog.sh check-task-sync.sh check-deploy-sql-order.sh
-      check-architecture-sync.sh check-agent-tooling.sh check-context-files.sh
-      check-brain-manifest.sh sync-brain-docs.sh check-skill-version.ts
-      select-agent-context-blocks.sh ensure-task-workflow.sh check-task-workflow.sh
-      maintenance-triage.sh heartbeat-triage.sh switch-plan.sh workflow-contract.ts
-      inspect-project-state.ts migrate-workflow-docs.ts migrate-project-template.sh
-      capability-resolver.ts architecture-event.ts capability-config.ts architecture-queue.sh
-      archive-architecture-request.sh context-contract-sync.sh workstream-sync.sh
-      prepare-codex-handoff.sh codex-handoff-resume.sh
-    )
-  fi
-
-  check_required_dir "$helper_compat_dir"
-  if [[ "${helper_source:-package}" != "package" ]]; then
-    check_required_dir "$helper_runtime_dir"
-  fi
-
-  for helper_name in "${helper_names[@]}"; do
-    check_required_file "$helper_compat_dir/$helper_name"
-    if [[ "${helper_source:-package}" != "package" && "$helper_runtime_dir" != "$helper_compat_dir" ]]; then
-      check_required_file "$helper_runtime_dir/$helper_name"
-    fi
-  done
-}
-
-policy_get() {
-  local jq_path="$1"
-  local default_value="$2"
-
-  if [[ -f "$policy_file" ]] && command -v jq >/dev/null 2>&1; then
-    local value
-    value="$(jq -r "$jq_path // empty" "$policy_file" 2>/dev/null || true)"
-    if [[ -n "$value" ]]; then
-      printf '%s' "$value"
-      return 0
-    fi
-  fi
-
-  printf '%s' "$default_value"
-}
-
-todo_file="$(policy_get '.tasks.todo_file' 'tasks/todos.md')"
-current_status_file="$(policy_get '.tasks.current_status_file' 'tasks/current.md')"
-lessons_file="$(policy_get '.tasks.lessons_file' 'tasks/lessons.md')"
-research_dir="$(policy_get '.tasks.research_dir' 'docs/researches')"
-contracts_dir="$(policy_get '.tasks.contracts_dir' 'tasks/contracts')"
-reviews_dir="$(policy_get '.tasks.reviews_dir' 'tasks/reviews')"
-notes_dir="$(policy_get '.tasks.notes_dir' 'tasks/notes')"
-workstreams_dir="$(policy_get '.tasks.workstreams_dir' 'tasks/workstreams')"
-runs_dir="$(policy_get '.harness.runs_dir' '.ai/harness/runs')"
-checks_file="$(policy_get '.harness.checks_file' '.ai/harness/checks/latest.json')"
-helper_runtime_dir="$(policy_get '.harness.helper_runtime_dir' '.ai/harness/scripts')"
-helper_compat_dir="$(policy_get '.harness.helper_compat_dir' 'scripts')"
-helper_source="$(policy_get '.harness.helper_source' 'package')"
-context_map_file="$(policy_get '.context.map_file' '.ai/context/context-map.json')"
-brain_manifest_file="$(policy_get '.information_lifecycle.external_knowledge.manifest_file' '.ai/harness/brain-manifest.json')"
-handoff_file="$(policy_get '.session.continuation_file' '.ai/harness/session/continuation.md')"
-resume_file="$(policy_get '.session.resume_file' '.ai/harness/session/resume.md')"
-sprints_dir="$(policy_get '.sprints.dir' 'plans/sprints')"
-sprint_marker_file="$(policy_get '.sprints.active_marker_file' '.ai/harness/sprint/active-sprint')"
-legacy_sprints_dir="tasks/sprints"
-upgrade_strategy_version=""
-if [[ -f "$policy_file" ]] && command -v jq >/dev/null 2>&1; then
-  upgrade_strategy_version="$(policy_get '.upgrade.strategy_version' '')"
-fi
-
-check_required_dir "plans"
-check_required_dir "plans/archive"
-check_required_dir "plans/prds"
-check_required_dir "$sprints_dir"
-check_required_dir "tasks"
-check_required_dir "tasks/archive"
-check_required_dir "$contracts_dir"
-check_required_dir "$reviews_dir"
-check_required_dir "$notes_dir"
-check_required_dir "$workstreams_dir"
-check_required_dir ".claude/templates"
-check_required_dir ".ai/context"
-check_required_dir ".ai/harness"
-if [[ "$helper_source" != "package" ]]; then
-  check_required_dir "$helper_runtime_dir"
-fi
-check_required_dir "$runs_dir"
-
-helper_file() {
-  printf '%s/%s' "$helper_runtime_dir" "$1"
-}
-
-check_required_file "docs/spec.md"
-check_required_file ".claude/templates/spec.template.md"
-check_required_file ".claude/templates/plan.template.md"
-check_required_file ".claude/templates/research.template.md"
-check_required_file ".claude/templates/contract.template.md"
-check_required_file ".claude/templates/review.template.md"
-check_required_file ".claude/templates/implementation-notes.template.md"
-check_required_file ".claude/templates/prd.template.md"
-check_helper_runtime_files
-check_required_file "$todo_file"
-check_required_file "$current_status_file"
-check_required_file "$lessons_file"
-check_required_dir "$research_dir"
-check_required_file "$context_map_file"
-check_required_file "$policy_file"
-check_required_file "$brain_manifest_file"
-
-if [[ -f ".claude/templates/plan.template.md" ]]; then
-  check_plan_template_evidence_contract ".claude/templates/plan.template.md"
-fi
-
-if [[ -f "$policy_file" && -z "$upgrade_strategy_version" ]] && command -v jq >/dev/null 2>&1; then
-  report_issue "Harness policy is missing upgrade.strategy_version; rerun migration to merge the versioned upgrade strategy."
-fi
-
-if [[ ! -f "$WORKFLOW_CONTRACT_PATH" ]]; then
-  report_bootstrap "Missing generated workflow contract manifest: $WORKFLOW_CONTRACT_PATH"
-else
-  json_runtime="$(resolve_json_runtime || true)"
-  if [[ -z "$json_runtime" ]]; then
-    report_issue "Missing node, bun, or python3 to read workflow contract manifest: $WORKFLOW_CONTRACT_PATH"
-  else
-    while IFS= read -r rel_dir; do
-      [[ -z "$rel_dir" ]] && continue
-      check_required_dir "$rel_dir"
-    done < <(contract_query_lines "artifacts.requiredDirectories")
-
-    while IFS= read -r rel_file; do
-      [[ -z "$rel_file" ]] && continue
-      check_required_file "$rel_file"
-    done < <(contract_query_lines "artifacts.requiredFiles")
-  fi
-fi
-
-check_reference_config_stubs
-check_generation_surface_terminology
-if [[ -f "$checks_file" ]] && ! trace_error="$(trace_schema_error "$checks_file")"; then
-  report_issue "Latest checks trace is not forge-run-trace.v1 compatible: ${trace_error//$'\n'/; }"
-fi
-
-if [[ -f "docs/plan.md" ]]; then
-  report_issue "Legacy docs/plan.md detected; migrate or archive it into plans/."
-fi
-
-if [[ -f "docs/TODO.md" ]]; then
-  report_issue "Legacy docs/TODO.md detected; migrate it into tasks/todos.md."
-fi
-
-if [[ "$todo_file" != "tasks/todo.md" && -f "tasks/todo.md" ]]; then
-  report_issue "Legacy tasks/todo.md detected; migrate it into ${todo_file}."
-fi
-
-if [[ -f "scripts/check-deploy-sql-order.sh" ]]; then
-  if ! bash "scripts/check-deploy-sql-order.sh" --quiet; then
-    report_issue "Deploy SQL order check failed."
-  fi
-fi
-
-if [[ -f "scripts/check-brain-manifest.sh" && -f "$brain_manifest_file" ]]; then
-  if ! bash "scripts/check-brain-manifest.sh"; then
-    report_issue "Brain manifest check failed."
-  fi
-fi
-
-if [[ -f "scripts/sync-brain-docs.sh" && -f "$brain_manifest_file" ]]; then
-  if ! bash "scripts/sync-brain-docs.sh" --check; then
-    report_issue "Brain doc sync check failed."
-  fi
-fi
-
-todo_source="$(todo_source_plan || true)"
-if [[ -f "$todo_file" ]]; then
-  if grep -q '[^[:space:]]' "$todo_file"; then
-    if ! todo_is_deferred_ledger "$todo_file"; then
-      report_issue "Legacy ${todo_file} detected; expected a deferred-goal ledger, not an active execution checklist."
-    elif ! ledger_error="$(todo_deferred_ledger_error "$todo_file")"; then
-      report_issue "${todo_file} deferred ledger is incomplete: ${ledger_error//$'\n'/; }"
-    fi
-  fi
-fi
-
-if [[ -d "plans/prds" ]]; then
-  while IFS= read -r prd_sprint_file; do
-    [[ -n "$prd_sprint_file" ]] || continue
-    report_issue "Sprint backlog file is in the PRD catalog; migrate ${prd_sprint_file} into ${sprints_dir}/."
-  done < <(
-    find plans/prds -maxdepth 1 -type f -name '*.prd.md' -print0 2>/dev/null \
-      | xargs -0 grep -El '^(# Sprint:|## Backlog[[:space:]]*$)' 2>/dev/null || true
-  )
-
-  while IFS= read -r prd_file; do
-    [[ -n "$prd_file" ]] || continue
-    case "$(basename "$prd_file")" in
-      [0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]-[0-9][0-9][0-9][0-9]-*.prd.md)
-        ;;
-      *)
-        report_issue "PRD filename must match <YYYYMMDD>-<HHMM>-<slug>.prd.md: $prd_file"
-        continue
-        ;;
-    esac
-
-    prd_status="$(extract_status "$prd_file")"
-    if [[ -z "$prd_status" ]]; then
-      report_issue "PRD is missing a '**Status**' line: $prd_file"
-      continue
-    fi
-    if ! prd_known_status "$prd_status"; then
-      report_issue "PRD has unknown status '${prd_status}': $prd_file"
-      continue
-    fi
-    if [[ "$prd_status" == "Approved" ]]; then
-      if ! prd_error="$(prd_ready_error "$prd_file")"; then
-        report_issue "PRD $prd_file is not approval-ready: ${prd_error//$'\n'/; }"
-      fi
-    fi
-  done < <(find plans/prds -maxdepth 1 -type f -name '*.prd.md' 2>/dev/null | sort)
-fi
-
-if [[ -d "$sprints_dir" ]]; then
-  while IFS= read -r sprint_file; do
-    [[ -n "$sprint_file" ]] || continue
-    sprint_status="$(extract_status "$sprint_file")"
-    if [[ -z "$sprint_status" ]]; then
-      report_issue "Sprint is missing a '**Status**' line: $sprint_file"
-      continue
-    fi
-    if ! sprint_known_status "$sprint_status"; then
-      report_issue "Sprint has unknown status '${sprint_status}': $sprint_file"
-      continue
-    fi
-    if [[ "$sprint_status" == "Approved" || "$sprint_status" == "Executing" ]]; then
-      if ! sprint_error="$(sprint_ready_error "$sprint_file")"; then
-        report_issue "Sprint $sprint_file is not execution-ready: ${sprint_error//$'\n'/; }"
-      fi
-    fi
-  done < <(find "$sprints_dir" -maxdepth 1 -type f -name '*.sprint.md' 2>/dev/null | sort)
-fi
-
-if [[ "$sprints_dir" != "$legacy_sprints_dir" && -d "$legacy_sprints_dir" ]]; then
-  report_issue "Legacy sprint directory detected; migrate ${legacy_sprints_dir}/*.sprint.md into ${sprints_dir}/*.sprint.md."
-fi
-
-if [[ -d "plans/prds" ]]; then
-  while IFS= read -r prd_sprint_file; do
-    [[ -n "$prd_sprint_file" ]] || continue
-    report_issue "Sprint backlog file is in the PRD catalog; migrate ${prd_sprint_file} into ${sprints_dir}/."
-  done < <(
-    find plans/prds -maxdepth 1 -type f -name '*.prd.md' -print0 2>/dev/null \
-      | xargs -0 grep -El '^(# Sprint:|## Backlog[[:space:]]*$)' 2>/dev/null || true
-  )
-fi
-
-if [[ -f "$sprint_marker_file" ]]; then
-  marker_sprint="$(sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//' "$sprint_marker_file" 2>/dev/null || true)"
-  if [[ -z "$marker_sprint" || ! -f "$marker_sprint" ]]; then
-    report_issue "Active sprint marker does not resolve to a sprint file: ${marker_sprint:-(empty)} (marker: $sprint_marker_file)"
-  else
-    case "$marker_sprint" in
-      "$sprints_dir"/*)
-        case "$marker_sprint" in
-          *..*)
-            report_issue "Active sprint marker must not contain '..': $marker_sprint (marker: $sprint_marker_file)"
-            ;;
-        esac
-        ;;
-      *)
-        report_issue "Active sprint marker points outside ${sprints_dir}: $marker_sprint (marker: $sprint_marker_file)"
-        ;;
-    esac
-  fi
-fi
-
-if [[ -f "$current_status_file" ]]; then
-  if ! grep -Eq '^# Current Status Snapshot[[:space:]]*$' "$current_status_file"; then
-    report_issue "${current_status_file} is missing '# Current Status Snapshot' heading."
-  fi
-  if grep -Eq '^[[:space:]]*-[[:space:]]\[[ xX]\][[:space:]]+' "$current_status_file"; then
-    report_issue "${current_status_file} must remain a read model, not a checklist."
-  fi
-fi
-
-check_handoff_resume_pair "$handoff_file" "$resume_file"
-check_current_resume_freshness "$current_status_file" "$resume_file"
-
-active_plan="$(get_active_plan || true)"
-if [[ -z "$active_plan" ]]; then
-  if [[ -f "$ACTIVE_WORKTREE_MARKER" ]]; then
-    report_issue "$ACTIVE_WORKTREE_MARKER exists but no active plan marker resolves to a plan."
-  fi
-else
-  if [[ ! -f "$ACTIVE_WORKTREE_MARKER" ]]; then
-    report_issue "Active plan marker exists but $ACTIVE_WORKTREE_MARKER is missing."
-  else
-    current_worktree="$(pwd -P)"
-    marked_worktree="$(cat "$ACTIVE_WORKTREE_MARKER" 2>/dev/null | xargs || true)"
-    if [[ -z "$marked_worktree" ]]; then
-      report_issue "$ACTIVE_WORKTREE_MARKER is empty."
-    elif [[ "$marked_worktree" != "$current_worktree" ]]; then
-      report_issue "$ACTIVE_WORKTREE_MARKER points to $marked_worktree, expected $current_worktree."
-    fi
-  fi
-
-  plan_status="$(extract_status "$active_plan")"
-  if [[ -z "$plan_status" ]]; then
-    report_issue "Active plan is missing a '**Status**' line: $active_plan"
-  fi
-
-  if [[ "$plan_status" == "Approved" || "$plan_status" == "Executing" ]]; then
-    if ! evidence_error="$(plan_evidence_contract_error "$active_plan")"; then
-      report_issue "Active $plan_status plan has incomplete Evidence Contract: $active_plan (${evidence_error//$'\n'/; })"
-    fi
-
-    contract_file="$(derive_contract_path "$active_plan")"
-    if [[ ! -f "$contract_file" ]]; then
-      report_issue "Active $plan_status plan is missing its task contract: $contract_file"
-    elif ! grep -Eq '^> \*\*Capability ID\*\*: .+' "$contract_file"; then
-      report_issue "Active task contract is missing a capability binding: $contract_file"
-    fi
-  fi
-fi
-
-if [[ "$issues" -eq 0 ]]; then
-  if [[ "$bootstrap_issues" -gt 0 ]]; then
-    echo "[workflow] OK: source/document contracts pass; $bootstrap_issues generated runtime item(s) need local bootstrap/remediation."
-  fi
-  echo "[workflow] OK"
-  exit 0
-fi
-
-if [[ "$strict" -eq 1 ]]; then
-  exit 1
-fi
-
-echo "[workflow] Found $issues issue(s); rerun with --strict to fail the check."
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec "$SCRIPT_DIR/lib/run-forge-helper.sh" "check-task-workflow.sh" "$@"