@indigoai-us/hq-cli 5.312.2-beta.0 → 5.314.0

package/assets/scaffold/core/scripts/resolve-company.sh

@@ -1,199 +0,0 @@
-#!/usr/bin/env bash
-# hq-core: public
-# resolve-company.sh — resolve the active company for skills and routing.
-#
-# Resolution order (first hit wins): explicit manifest slug in the prompt,
-# session company_slug, enabled device default, then none. Prompt matching is
-# whole-token only; free text never guesses a company.
-#
-# Output: {"company":"<slug>","source":"prompt|session|device_default|none"}
-# Always exits 0 and never writes state.
-
-set -uo pipefail
-
-ROOT=""
-PROMPT=""
-HAVE_PROMPT=0
-
-while [ $# -gt 0 ]; do
-  case "$1" in
-    --root) ROOT="${2:-}"; shift 2 || shift ;;
-    --prompt) PROMPT="${2:-}"; HAVE_PROMPT=1; shift 2 || shift ;;
-    --help|-h)
-      sed -n '2,14p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
-      exit 0
-      ;;
-    *) shift ;;
-  esac
-done
-
-if [ "$HAVE_PROMPT" -eq 0 ] && [ ! -t 0 ]; then
-  PROMPT="$(cat 2>/dev/null || true)"
-fi
-: "${PROMPT:=}"
-
-emit() {
-  printf '{"company":"%s","source":"%s"}\n' "$1" "$2"
-  exit 0
-}
-
-if [ -z "$ROOT" ]; then
-  ROOT="${HQ_ROOT:-${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && cd .. && pwd)}}"
-fi
-
-MANIFEST="$ROOT/companies/manifest.yaml"
-[ -f "$MANIFEST" ] || emit "" "none"
-
-SLUGS="$(
-  awk '
-    function keep(slug) {
-      return slug != "" && slug != "_template" && slug != "companies" && slug != "unaffiliated_repos"
-    }
-    /^companies:[[:space:]]*$/ { wrapped = 1; next }
-    wrapped && /^[^[:space:]][^:]*:[[:space:]]*$/ { wrapped = 0 }
-    wrapped && /^  [A-Za-z][A-Za-z0-9_-]*:/ {
-      line = $0; sub(/^[[:space:]]+/, "", line); sub(/:.*/, "", line)
-      if (keep(line)) print line
-      next
-    }
-    !wrapped && /^[A-Za-z][A-Za-z0-9_-]*:/ {
-      line = $0; sub(/:.*/, "", line)
-      if (keep(line)) print line
-    }
-  ' "$MANIFEST" | sort -u
-)"
-[ -n "$SLUGS" ] || emit "" "none"
-
-is_known_slug() {
-  printf '%s\n' "$SLUGS" | grep -Fxq "$1"
-}
-
-prompt_slug() {
-  local normalized="" match=""
-  [ -n "$PROMPT" ] || return 0
-  normalized="$(printf '%s' "$PROMPT" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9_-' ' ')"
-  match="$(
-    # Prompt normalization is case-insensitive, but company IDs are not.
-    # Keep a folded match only when exactly one registered ID has that key.
-    # If IDs differ only by case, do not guess which tenant the prompt means.
-    printf '%s\n' "$SLUGS" | awk -v line="$normalized" '
-      BEGIN {
-        n = split(line, tok, /[ \t]+/)
-        for (i = 1; i <= n; i++) if (tok[i] != "" && !(tok[i] in pos)) pos[tok[i]] = i
-        bestSlug = ""; bestLen = 0; bestPos = 0
-      }
-      {
-        slug = $0
-        key = tolower(slug)
-        if (key in pos) {
-          matches[key]++
-          candidate[key] = slug
-        }
-      }
-      END {
-        for (key in matches) {
-          if (matches[key] != 1) continue
-          slug = candidate[key]
-          len = length(slug); p = pos[key]
-          if (len > bestLen || (len == bestLen && p < bestPos)) {
-            bestSlug = slug; bestLen = len; bestPos = p
-          }
-        }
-        if (bestSlug != "") print bestSlug
-      }
-    '
-  )"
-  printf '%s' "$match"
-}
-
-MATCH="$(prompt_slug)"
-[ -n "$MATCH" ] && emit "$MATCH" "prompt"
-
-SESSION_CO=""
-if [ -x "$ROOT/core/scripts/hq-session.sh" ]; then
-  SESSION_CO="$(bash "$ROOT/core/scripts/hq-session.sh" get company_slug 2>/dev/null || true)"
-  SESSION_CO="$(printf '%s' "$SESSION_CO" | tr -d '[:space:]\"')"
-fi
-if [ -n "$SESSION_CO" ] && is_known_slug "$SESSION_CO"; then
-  emit "$SESSION_CO" "session"
-fi
-
-is_fleet_identity() {
-  [ -n "${HQ_AGENT_WORKDIR:-}" ] && return 0
-  [ -n "${HQ_AGENT_COMPANY_DIR:-}" ] && return 0
-  [ -n "${HQ_AGENT_IDENTITY_FILE:-}" ] && return 0
-  [ -f /etc/hq-agent/identity.json ] && return 0
-  [ -f /etc/hq-agent/machine-creds.json ] && return 0
-  agent_root="${HQ_AGENT_ROOT_PREFIX:-}"
-  if [ -n "$agent_root" ]; then
-    [ -f "${agent_root%/}/var/lib/hq-agent/identity.json" ] && return 0
-  else
-    [ -f /var/lib/hq-agent/identity.json ] && return 0
-  fi
-  [ -f /var/lib/hq-agent/machine-creds.json ] && return 0
-  return 1
-}
-
-run_with_timeout() {
-  command -v node >/dev/null 2>&1 || return 127
-  node -e '
-const { spawn } = require("child_process");
-const command = process.argv[1];
-if (!command) process.exit(127);
-const child = spawn(command, process.argv.slice(2), { detached: true, stdio: ["ignore", "pipe", "ignore"] });
-let finished = false;
-const finish = (status) => {
-  if (finished) return;
-  finished = true;
-  clearTimeout(timer);
-  try { process.kill(-child.pid, "SIGTERM"); } catch (_) {}
-  process.exit(status);
-};
-child.stdout.on("data", (chunk) => process.stdout.write(chunk));
-child.once("error", () => finish(127));
-child.once("exit", (code) => finish(typeof code === "number" ? code : 1));
-const timer = setTimeout(() => finish(124), 2000);
-' "$@"
-}
-
-if ! is_fleet_identity && command -v hq >/dev/null 2>&1 && command -v jq >/dev/null 2>&1; then
-  DEFAULT_JSON="$(run_with_timeout hq mesh context default get --json 2>/dev/null || true)"
-  DEFAULT_SLUG="$(printf '%s' "$DEFAULT_JSON" | jq -er '(.defaultCompany // .) as $default | if $default.enabled == true and ($default.source // "") != "disabled" and ($default.needsChoice // false) == false and ($default.slug | type == "string") then $default.slug else empty end' 2>/dev/null || true)"
-  DEFAULT_SLUG="$(printf '%s' "$DEFAULT_SLUG" | tr -d '[:space:]\"')"
-  if [ -n "$DEFAULT_SLUG" ] && is_known_slug "$DEFAULT_SLUG"; then
-    # A device default is only a local preference. Reconcile performs the
-    # token-backed active-membership check; never promote this fallback when
-    # that preflight is unavailable, times out, or returns a noncanonical row.
-    PREFLIGHT_SESSION_ID="resolve-default-$$-$RANDOM"
-    PREFLIGHT_OPERATION_ID="resolve-default-op-$$-$RANDOM"
-    PREFLIGHT_OBSERVATION="$(jq -cn \
-      --arg session_id "$PREFLIGHT_SESSION_ID" \
-      --arg operation_id "$PREFLIGHT_OPERATION_ID" \
-      --arg root "$ROOT" \
-      '{contractVersion:1,clientOperationId:$operation_id,identity:{sessionId:$session_id,harness:"hq-core",adapterVersion:"1"},cwd:$root,hqRoot:$root}')"
-    PREFLIGHT_STATUS=0
-    PREFLIGHT_RESULT="$(run_with_timeout hq mesh context reconcile --observation-json "$PREFLIGHT_OBSERVATION" --machine --offline 2>/dev/null)" || PREFLIGHT_STATUS=$?
-    VALIDATED_SLUG=""
-    if [ "$PREFLIGHT_STATUS" -eq 0 ]; then
-      VALIDATED_SLUG="$(printf '%s' "$PREFLIGHT_RESULT" | jq -er \
-        --arg slug "$DEFAULT_SLUG" \
-        --arg session_id "$PREFLIGHT_SESSION_ID" \
-        --arg operation_id "$PREFLIGHT_OPERATION_ID" '
-          if type == "object"
-            and .contractVersion == 1
-            and (.sessionId | type == "string") and .sessionId == $session_id
-            and (.clientOperationId | type == "string") and .clientOperationId == $operation_id
-            and (.kind == "queued" or .kind == "needs_project" or .kind == "needs_task" or .kind == "bound")
-            and (.classification == "needs_project" or .classification == "needs_task" or .classification == "bound")
-            and (.delivery == "queued" or .delivery == "acked")
-            and .lifecycle == "open"
-            and .companySlug == $slug
-            and (.companyUid | type == "string") and (.companyUid | length > 0)
-          then .companySlug else empty end
-        ' 2>/dev/null || true)"
-    fi
-    [ "$VALIDATED_SLUG" = "$DEFAULT_SLUG" ] && emit "$DEFAULT_SLUG" "device_default"
-  fi
-fi
-
-emit "" "none"

package/assets/scaffold/core/scripts/resume-thread-lock.sh

@@ -1,285 +0,0 @@
-#!/usr/bin/env bash
-# hq-core: public
-# resume-thread-lock.sh — durable, session-attributed lock markers for
-# /resumework. Locks live outside individual thread JSON files so archival can
-# move a thread without orphaning or mutating its immutable handoff record.
-#
-# Usage:
-#   resume-thread-lock.sh inspect <thread-id>
-#   resume-thread-lock.sh acquire <thread-id> --session-id <session-id>
-#   resume-thread-lock.sh acquire <thread-id> --replace --expected-generation <generation> --session-id <session-id>
-#
-# inspect always exits zero and returns one JSON object with status unlocked,
-# locked, or stale. acquire exits 3 with that same locked/stale JSON when an
-# existing marker needs an explicit user confirmation; --replace is reserved
-# for the confirmed re-resume path.
-
-set -euo pipefail
-
-HQ_ROOT="${HQ_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
-THREADS_DIR="$HQ_ROOT/workspace/threads"
-LOCKS_DIR="$THREADS_DIR/resume-locks"
-STALE_SECONDS="${HQ_RESUME_LOCK_STALE_SECONDS:-86400}"
-REPLACE_CLAIM_STALE_SECONDS="${HQ_RESUME_REPLACE_CLAIM_STALE_SECONDS:-60}"
-
-usage() {
-  cat <<'USAGE'
-usage:
-  resume-thread-lock.sh inspect <thread-id>
-  resume-thread-lock.sh acquire <thread-id> --session-id <session-id>
-  resume-thread-lock.sh acquire <thread-id> --replace --expected-generation <generation> --session-id <session-id>
-USAGE
-}
-
-fail_usage() {
-  echo "resume-thread-lock: $*" >&2
-  usage >&2
-  exit 2
-}
-
-command -v jq >/dev/null 2>&1 || {
-  echo "resume-thread-lock: jq is required" >&2
-  exit 1
-}
-
-[[ "$STALE_SECONDS" =~ ^[0-9]+$ ]] || fail_usage "HQ_RESUME_LOCK_STALE_SECONDS must be a non-negative integer"
-[[ "$REPLACE_CLAIM_STALE_SECONDS" =~ ^[0-9]+$ ]] || fail_usage "HQ_RESUME_REPLACE_CLAIM_STALE_SECONDS must be a non-negative integer"
-
-subcommand="${1:-}"
-shift || true
-
-thread_id="${1:-}"
-shift || true
-[[ "$thread_id" =~ ^T-[A-Za-z0-9][A-Za-z0-9_-]*$ ]] || fail_usage "thread id must be a canonical T-* id"
-
-replace="false"
-session_id=""
-expected_generation=""
-expected_generation_set="false"
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --replace)
-      replace="true"
-      shift
-      ;;
-    --session-id)
-      [[ $# -ge 2 ]] || fail_usage "--session-id requires a value"
-      session_id="$2"
-      shift 2
-      ;;
-    --expected-generation)
-      [[ $# -ge 2 ]] || fail_usage "--expected-generation requires a value"
-      expected_generation="$2"
-      expected_generation_set="true"
-      shift 2
-      ;;
-    *)
-      fail_usage "unknown argument: $1"
-      ;;
-  esac
-done
-
-case "$subcommand" in
-  inspect)
-    [[ "$replace" = "false" && -z "$session_id" ]] \
-      || fail_usage "inspect takes only a thread id"
-    ;;
-  acquire)
-    [[ -n "$session_id" ]] || fail_usage "acquire requires --session-id"
-    if [[ "$replace" = "true" ]]; then
-      [[ "$expected_generation_set" = "true" ]] || fail_usage "--replace requires --expected-generation from the inspected lock"
-    else
-      [[ "$expected_generation_set" = "false" ]] || fail_usage "--expected-generation is only valid with --replace"
-    fi
-    ;;
-  *)
-    fail_usage "expected inspect or acquire"
-    ;;
-esac
-
-lock_dir="$LOCKS_DIR/$thread_id.lock"
-record_path="$lock_dir/current.json"
-replace_claim_dir="$lock_dir/.replace-claim"
-relative_lock_path="workspace/threads/resume-locks/$thread_id.lock"
-
-now_epoch() {
-  date -u +%s
-}
-
-now_iso() {
-  date -u +%Y-%m-%dT%H:%M:%SZ
-}
-
-claim_is_stale() {
-  local claim_mtime current_epoch
-  claim_mtime="$(stat -f %m "$replace_claim_dir" 2>/dev/null || stat -c %Y "$replace_claim_dir" 2>/dev/null || echo 0)"
-  [[ "$claim_mtime" =~ ^[0-9]+$ ]] || return 1
-  current_epoch="$(now_epoch)"
-  (( current_epoch - claim_mtime > REPLACE_CLAIM_STALE_SECONDS ))
-}
-
-acquire_replace_claim() {
-  if mkdir "$replace_claim_dir" 2>/dev/null; then
-    return 0
-  fi
-
-  # A killed process can leave an empty claim directory behind. Recover only a
-  # demonstrably stale claim, and only with rmdir so an unexpected payload is
-  # never removed.
-  if [[ -d "$replace_claim_dir" ]] && claim_is_stale; then
-    rmdir "$replace_claim_dir" 2>/dev/null || true
-    mkdir "$replace_claim_dir" 2>/dev/null && return 0
-  fi
-
-  return 1
-}
-
-emit_unlocked() {
-  jq -cn \
-    --arg thread_id "$thread_id" \
-    --arg lock_path "$relative_lock_path" \
-    '{status:"unlocked", thread_id:$thread_id, lock_path:$lock_path}'
-}
-
-emit_stale() {
-  local reason="$1" owner_session="$2" resumed_at="$3" generation="$4"
-  local prompt="This thread was already resumed by ${owner_session} at ${resumed_at}. Its lock is stale (${reason}). Re-resume anyway?"
-  jq -cn \
-    --arg thread_id "$thread_id" \
-    --arg lock_path "$relative_lock_path" \
-    --arg stale_reason "$reason" \
-    --arg session_id "$owner_session" \
-    --arg resumed_at "$resumed_at" \
-    --arg lock_generation "$generation" \
-    --arg prompt "$prompt" \
-    '{status:"stale", thread_id:$thread_id, lock_path:$lock_path, stale_reason:$stale_reason, session_id:$session_id, resumed_at:$resumed_at, lock_generation:$lock_generation, prompt:$prompt}'
-}
-
-emit_locked() {
-  local owner_session="$1" resumed_at="$2" generation="$3"
-  local prompt="This thread was already resumed by ${owner_session} at ${resumed_at}. Re-resume anyway?"
-  jq -cn \
-    --arg thread_id "$thread_id" \
-    --arg lock_path "$relative_lock_path" \
-    --arg session_id "$owner_session" \
-    --arg resumed_at "$resumed_at" \
-    --arg lock_generation "$generation" \
-    --arg prompt "$prompt" \
-    '{status:"locked", thread_id:$thread_id, lock_path:$lock_path, session_id:$session_id, resumed_at:$resumed_at, lock_generation:$lock_generation, prompt:$prompt}'
-}
-
-# Print the existing lock's state. A damaged or expired marker is deliberately
-# not removed: it is still evidence that this handoff was resumed and must pass
-# through the same explicit re-resume confirmation as a fresh marker.
-existing_state() {
-  if [[ ! -d "$lock_dir" ]]; then
-    if [[ -e "$lock_dir" ]]; then
-      emit_stale "invalid-lock-path" "unknown session" "unknown time" ""
-    else
-      emit_unlocked
-    fi
-    return
-  fi
-
-  if [[ ! -f "$record_path" ]]; then
-    emit_stale "missing-record" "unknown session" "unknown time" ""
-    return
-  fi
-
-  if ! jq -e '
-    .version == 1
-    and (.thread_id | type == "string" and length > 0)
-    and (.session_id | type == "string" and length > 0)
-    and (.resumed_at | type == "string" and length > 0)
-    and (.resumed_epoch | type == "number")
-    and (.generation | type == "string" and length > 0)
-  ' "$record_path" >/dev/null 2>&1; then
-    emit_stale "invalid-record" "unknown session" "unknown time" ""
-    return
-  fi
-
-  local record_thread record_session record_at record_epoch record_generation current_epoch
-  record_thread="$(jq -r '.thread_id' "$record_path")"
-  record_session="$(jq -r '.session_id' "$record_path")"
-  record_at="$(jq -r '.resumed_at' "$record_path")"
-  record_epoch="$(jq -r '.resumed_epoch' "$record_path")"
-  record_generation="$(jq -r '.generation' "$record_path")"
-
-  if [[ "$record_thread" != "$thread_id" || ! "$record_epoch" =~ ^[0-9]+$ ]]; then
-    emit_stale "invalid-record" "$record_session" "$record_at" "$record_generation"
-    return
-  fi
-
-  current_epoch="$(now_epoch)"
-  if (( current_epoch - record_epoch > STALE_SECONDS )); then
-    emit_stale "expired" "$record_session" "$record_at" "$record_generation"
-    return
-  fi
-
-  emit_locked "$record_session" "$record_at" "$record_generation"
-}
-
-write_record() {
-  local record_dir="$1" epoch timestamp tmp generation
-  epoch="$(now_epoch)"
-  timestamp="$(now_iso)"
-  tmp="$(mktemp "$record_dir/.current.XXXXXX")"
-  generation="$(basename "$tmp")"
-  jq -cn \
-    --arg thread_id "$thread_id" \
-    --arg session_id "$session_id" \
-    --arg resumed_at "$timestamp" \
-    --arg generation "$generation" \
-    --argjson resumed_epoch "$epoch" \
-    '{version:1, thread_id:$thread_id, session_id:$session_id, resumed_at:$resumed_at, resumed_epoch:$resumed_epoch, generation:$generation}' \
-    > "$tmp"
-  mv -f "$tmp" "$record_path"
-  WRITTEN_GENERATION="$generation"
-}
-
-emit_acquired() {
-  local generation="$1"
-  jq -cn \
-    --arg thread_id "$thread_id" \
-    --arg lock_path "$relative_lock_path" \
-    --arg session_id "$session_id" \
-    --arg lock_generation "$generation" \
-    '{status:"acquired", thread_id:$thread_id, lock_path:$lock_path, session_id:$session_id, lock_generation:$lock_generation}'
-}
-
-case "$subcommand" in
-  inspect)
-    existing_state
-    ;;
-  acquire)
-    mkdir -p "$LOCKS_DIR"
-    if mkdir "$lock_dir" 2>/dev/null; then
-      write_record "$lock_dir"
-      emit_acquired "$WRITTEN_GENERATION"
-      exit 0
-    fi
-
-    if [[ "$replace" != "true" ]]; then
-      existing_state
-      exit 3
-    fi
-
-    [[ -d "$lock_dir" ]] || {
-      echo "resume-thread-lock: cannot refresh non-directory lock path: $relative_lock_path" >&2
-      exit 1
-    }
-    if ! acquire_replace_claim; then
-      existing_state
-      exit 4
-    fi
-    trap 'rmdir "$replace_claim_dir" 2>/dev/null || true' EXIT
-    current_state="$(existing_state)"
-    current_generation="$(jq -r '.lock_generation // ""' <<<"$current_state")"
-    if [[ "$current_generation" != "$expected_generation" ]]; then
-      printf '%s\n' "$current_state"
-      exit 4
-    fi
-    write_record "$lock_dir"
-    emit_acquired "$WRITTEN_GENERATION"
-    ;;
-esac

package/assets/scaffold/core/scripts/source-yaml-validate.sh

@@ -1,36 +0,0 @@
-#!/usr/bin/env bash
-# source-yaml-validate.sh — validate a sources/{channel}/source.yaml.
-# Spec: core/knowledge/public/hq-core/source-yaml-spec.md
-# Usage: source-yaml-validate.sh <path/to/source.yaml>
-# Exit 0 valid; 1 invalid (each violation printed); 2 bad usage / missing file.
-set -uo pipefail
-f="${1:-}"
-[ -n "$f" ] || { echo "usage: source-yaml-validate.sh <source.yaml>" >&2; exit 2; }
-[ -f "$f" ] || { echo "source-yaml-validate: no such file $f" >&2; exit 2; }
-
-get() {
-  awk -v k="$1" '$0 ~ "^"k":" { sub("^"k":[[:space:]]*", ""); sub("[[:space:]]+#.*$", ""); gsub(/^["\x27]|["\x27]$/, ""); print; exit }' "$f"
-}
-v=0
-bad() { echo "$f: $*"; v=$((v+1)); }
-oneof() { case " $3 " in *" $2 "*) ;; *) bad "$1 must be one of: $3 (got '${2:-<missing>}')" ;; esac; }
-
-channel="$(get channel)"; kind="$(get kind)"; arrives="$(get arrives)"; pull="$(get pull_command)"
-aud="$(get audience_rule)"; proc="$(get processor)"; run="$(get run)"; sched="$(get schedule)"
-
-[ -n "$channel" ] || bad "channel is required"
-folder="$(basename "$(dirname "$f")")"
-[ -z "$channel" ] || [ "$channel" = "$folder" ] || bad "channel '$channel' must equal its folder name '$folder'"
-oneof kind "$kind" "meeting email slack doc custom"
-oneof arrives "$arrives" "drop pull cloud"
-[ "$arrives" != pull ] || [ -n "$pull" ] || bad "pull_command is required when arrives: pull"
-[ -n "$aud" ] || bad "audience_rule is required (attendees|thread|channel|company|explicit); it is never defaulted"
-[ -z "$aud" ] || oneof audience_rule "$aud" "attendees thread channel company explicit"
-[ -n "$proc" ] || bad "processor is required (<worker>/<skill>)"
-[ -z "$proc" ] || printf '%s' "$proc" | grep -Eq '^[a-z0-9-]+/[a-z0-9-]+$' || bad "processor must look like <worker>/<skill> (got '$proc')"
-oneof run "$run" "local cloud"
-if [ -z "$sched" ]; then bad "schedule is required (cron or on-close)"
-elif [ "$sched" != on-close ] && [ "$(printf '%s' "$sched" | awk '{print NF}')" -ne 5 ]; then bad "schedule must be a 5-field cron or on-close (got '$sched')"; fi
-
-[ "$v" -eq 0 ] && { echo "$f: ok"; exit 0; }
-exit 1

package/assets/scaffold/core/scripts/verify-story-deliverables.sh

@@ -1,148 +0,0 @@
-#!/usr/bin/env bash
-# hq-core: public
-# verify-story-deliverables.sh — make `passes: true` checkable: verify the
-# evidence a story worker returns, and any deliverables the PRD declared
-# (2026-09-07).
-#
-# Why: a PRD "passes" flag recorded that a step RAN, not that work EXISTS. An
-# audit found a project marked 16/17 complete whose named deliverables mostly
-# did not exist anywhere. Nothing anywhere checked disk or git.
-#
-# Two inputs, both optional, deliberately NOT strict by default:
-#   * EVIDENCE — what the worker says it produced, returned at completion in
-#     the run-project / execute-task return contract (`evidence: [...]`, plus
-#     `commits: [...]` which are checked as `commit:` evidence). This is the
-#     primary signal: it is written at the moment of completion, so it is
-#     accurate to what was built, and --write records it on the story as an
-#     audit trail. A claimed-but-missing item FAILS (a fabricated claim is
-#     worse than no claim). No evidence at all is allowed (legacy workers).
-#   * DELIVERABLES — what the PRD declared up front (optional). Checked when
-#     present; a planned-but-missing item fails, because that is exactly the
-#     "16/17 complete, nothing on disk" case.
-#
-# Usage:
-#   verify-story-deliverables.sh --prd <prd.json> --story <id> [--repo <path>]
-#       [--evidence-json '<array>'] [--commits-json '<array>'] [--write] [--json] [--strict]
-#
-# Reference forms (evidence and deliverables share them):
-#   "deliverables": [
-#     "path:core/scripts/foo.sh",            # file or dir, relative to HQ root
-#     "repo-path:src/lib/bar.ts",            # relative to --repo (or metadata.repoPath)
-#     "branch:feature/x",                    # branch exists in --repo (local or origin)
-#     "commit:<sha-prefix>",                 # commit reachable in --repo
-#     "url:https://…"                        # HTTP 2xx/3xx (skipped with --offline)
-#   ]
-#   A bare string without a prefix is treated as "path:".
-#
-# Exit 0: every checked reference present. With nothing to check (no evidence,
-#         no declared deliverables) this is reported as "unverified" and still
-#         exits 0 — pass --strict to make that a failure.
-# Exit 3: one or more references missing (each is named on stderr).
-# Exit 2: usage / unreadable PRD / unknown story.
-# --write: on exit 0, record the verified references on the story in prd.json as
-#          `evidence: [{ref, verifiedAt}]` (only that field is touched).
-set -uo pipefail
-
-HQ_ROOT="${HQ_ROOT:-${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}}"
-PRD=""; STORY=""; REPO=""; JSON=0; STRICT=0; WRITE=0; EVIDENCE_JSON="[]"; COMMITS_JSON="[]"; OFFLINE="${HQ_DELIVERABLES_OFFLINE:-0}"
-while [ $# -gt 0 ]; do
-  case "$1" in
-    --prd) PRD="$2"; shift 2 ;;
-    --story) STORY="$2"; shift 2 ;;
-    --repo) REPO="$2"; shift 2 ;;
-    --evidence-json) EVIDENCE_JSON="$2"; shift 2 ;;
-    --commits-json) COMMITS_JSON="$2"; shift 2 ;;
-    --write) WRITE=1; shift ;;
-    --json) JSON=1; shift ;;
-    --strict) STRICT=1; shift ;;
-    --offline) OFFLINE=1; shift ;;
-    -h|--help) sed -n 2,30p "$0"; exit 0 ;;
-    *) echo "verify-story-deliverables: unknown arg $1" >&2; exit 2 ;;
-  esac
-done
-[ -n "$PRD" ] && [ -n "$STORY" ] || { echo "usage: --prd <prd.json> --story <id> [--repo <path>]" >&2; exit 2; }
-[ -r "$PRD" ] || { echo "verify-story-deliverables: cannot read $PRD" >&2; exit 2; }
-command -v jq >/dev/null 2>&1 || { echo "verify-story-deliverables: jq required" >&2; exit 2; }
-
-jq_capture() {
-  # jq.exe emits CRLF from Windows Bash; strip CR from every captured line.
-  jq "$@" | sed 's/\r$//'
-}
-
-story_json="$(jq_capture -c --arg id "$STORY" '.userStories[]? | select(.id == $id)' "$PRD" 2>/dev/null | head -1)"
-[ -n "$story_json" ] || { echo "verify-story-deliverables: story $STORY not in $PRD" >&2; exit 2; }
-[ -n "$REPO" ] || REPO="$(jq_capture -r '.metadata.repoPath // empty' "$PRD" 2>/dev/null)"
-case "$REPO" in ""|/*) ;; *) REPO="$HQ_ROOT/$REPO" ;; esac
-
-jq -e 'type == "array"' <<<"$EVIDENCE_JSON" >/dev/null 2>&1 || { echo "verify-story-deliverables: --evidence-json must be a JSON array" >&2; exit 2; }
-jq -e 'type == "array"' <<<"$COMMITS_JSON" >/dev/null 2>&1 || { echo "verify-story-deliverables: --commits-json must be a JSON array" >&2; exit 2; }
-# Everything to check: declared deliverables + worker evidence + worker commits
-# (as commit: refs), de-duplicated, in that order.
-REFS_JSON="$(jq_capture -cn --argjson d "$(printf '%s' "$story_json" | jq_capture -c '(.deliverables // [])')" --argjson e "$EVIDENCE_JSON" --argjson c "$COMMITS_JSON" \
-  '($d + $e + ($c | map("commit:" + tostring))) | map(select(type == "string" and length > 0)) | unique')"
-count="$(jq_capture -r 'length' <<<"$REFS_JSON")"
-declared="$(printf '%s' "$story_json" | jq_capture -r '(.deliverables // []) | length')"
-if [ "$count" = "0" ]; then
-  if [ "$STRICT" = "1" ]; then
-    echo "verify-story-deliverables: $STORY has no evidence and declares no deliverables (--strict)" >&2
-    [ "$JSON" = 1 ] && printf '{"story":"%s","status":"unverified","missing":[],"present":[]}\n' "$STORY"
-    exit 3
-  fi
-  [ "$JSON" = 1 ] && printf '{"story":"%s","status":"unverified","missing":[],"present":[]}\n' "$STORY" \
-    || echo "verify-story-deliverables: $STORY — nothing to verify (worker returned no evidence; PRD declares no deliverables). Allowed, but this done-mark is unverified."
-  exit 0
-fi
-
-present=(); missing=()
-while IFS= read -r d; do
-  [ -n "$d" ] || continue
-  kind="${d%%:*}"; val="${d#*:}"
-  case "$d" in *:*) ;; *) kind="path"; val="$d" ;; esac
-  ok=0
-  case "$kind" in
-    path)
-      case "$val" in /*) t="$val" ;; *) t="$HQ_ROOT/$val" ;; esac
-      [ -e "$t" ] && ok=1 ;;
-    repo-path)
-      [ -n "$REPO" ] && [ -e "$REPO/$val" ] && ok=1 ;;
-    branch)
-      [ -n "$REPO" ] && [ -d "$REPO" ] && {
-        git -C "$REPO" show-ref --verify --quiet "refs/heads/$val" \
-        || git -C "$REPO" show-ref --verify --quiet "refs/remotes/origin/$val"; } && ok=1 ;;
-    commit)
-      [ -n "$REPO" ] && [ -d "$REPO" ] && git -C "$REPO" cat-file -e "${val}^{commit}" 2>/dev/null && ok=1 ;;
-    url)
-      if [ "$OFFLINE" = "1" ]; then ok=1
-      else
-        code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 15 -L "$val" 2>/dev/null || echo 000)"
-        case "$code" in 2*|3*) ok=1 ;; esac
-      fi ;;
-    *) ok=0 ;;
-  esac
-  if [ "$ok" = 1 ]; then present+=("$d"); else missing+=("$d"); fi
-done < <(jq_capture -r '.[]' <<<"$REFS_JSON")
-
-if [ "$JSON" = 1 ]; then
-  jq -cn --arg s "$STORY" \
-    --argjson m "$(printf '%s\n' "${missing[@]:-}" | jq_capture -R . | jq_capture -s 'map(select(. != ""))')" \
-    --argjson p "$(printf '%s\n' "${present[@]:-}" | jq_capture -R . | jq_capture -s 'map(select(. != ""))')" \
-    '{story:$s, status:(if ($m|length)==0 then "present" else "missing" end), missing:$m, present:$p}'
-fi
-if [ "${#missing[@]}" -gt 0 ]; then
-  echo "verify-story-deliverables: $STORY is NOT verifiably complete — ${#missing[@]} of $count reference(s) do not exist:" >&2
-  for d in "${missing[@]}"; do echo "  - $d" >&2; done
-  echo "Do not write passes:true. A claimed path/branch/commit/URL must exist; a declared deliverable must be produced (or the declaration corrected)." >&2
-  exit 3
-fi
-if [ "$WRITE" = 1 ]; then
-  now="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-  jq_capture --arg id "$STORY" --arg now "$now" --argjson refs "$(printf '%s\n' "${present[@]}" | jq_capture -R . | jq_capture -s 'map(select(. != ""))')" \
-    '.userStories = (.userStories | map(if .id == $id then .evidence = ($refs | map({ref: ., verifiedAt: $now})) else . end))' \
-    "$PRD" > "$PRD.tmp" && mv "$PRD.tmp" "$PRD"
-fi
-recorded_suffix=""
-if [ "$WRITE" = 1 ]; then
-  recorded_suffix="; recorded on the story"
-fi
-[ "$JSON" = 1 ] || echo "verify-story-deliverables: $STORY — all $count reference(s) present ($declared declared, $((count - declared)) from worker evidence)$recorded_suffix"
-exit 0