@indigoai-us/hq-cli 5.286.0 → 5.288.0

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 ## [Unreleased]
 
+## [5.288.0] — 2026-09-29
+
+## [5.287.0] — 2026-09-29
+- Group hook-timeout events by script while preserving triage diagnostics.
+- Preserve safe slow-child script basenames in hook-timeout diagnostics.
+- Cloud provisioning and retirement now stop after 15 seconds when a Vault API request stalls, with a clear timeout error.
+- Add native TypeScript implementations for four `hq core` worktree and
+  handoff scripts behind the default-off `core-native-handoff` flag. The
+  original shell assets remain bundled as the rollback path.
+
+### Fixed
+
+- `hq team-sync` keeps its successful no-team result, reports which company
+  directories are cloud-backed, and points to `hq sync pull --all` and
+  `hq sync status` for cloud-backed companies.
+
+### Fixed
+
+- Confirm primary-dispatched Outpost profile recovery when it is queued for
+  reconcile, and sync the cleared recovery state to the primary lane mirror.
+- Cache-first `hq lanes list` now allows one detached Outpost summary refresh
+  per HQ root at a time, avoiding duplicate work from overlapping list calls.
+
+### Fixed
+
+- The lanes hook reads only transcript bytes appended since its last check.
+  It still replays compaction messages and resets the offset when a transcript
+  is replaced or truncated.
+
+### Added
+
+- `hq core ontology merge-copies --only <file>` handles only the copy -> original pairs listed in a JSON file and reports every other found pair as skipped (`not_listed`).
+
+### Changed
+
+- The checkpoint ontology step always applies its ten quality rules (company
+  brief, annotation stripping on grok, grok-first backend, no link aliases,
+  first-name people, ambiguous concept links, dominant sibling link, hub
+  mention floor, concept-project link, named evidence). Their
+  `checkpoint.ontology.*` flags, on for everyone since 2026-09-29, are no
+  longer read.
+
+### Added
+
+- Record company-scoped exposure for printed CLI plan-limit notices when the default-off `billing.limit-at-action-prompt` flag is enabled; count an upgrade engagement only after the user confirms opening the link.
+
+### Fixed
+
+- `hq secrets` and other noninteractive person-token callers reuse a fresh same-principal session written by another process while a stale refresh is rejected.
+
 ## [5.286.0] — 2026-09-29
 
 ### Changed
@@ -23,6 +73,13 @@
 
 ### Fixed
 
+- Recover a queued Outpost lane held for `worker_profile_changed` with its
+  printed `hq lanes resume <id> --worker <profile>` command. The lane owner's
+  profile copy is authoritative: the command records an authorized re-pin in
+  history, leaves the lane queued for normal reconcile admission, and syncs the
+  cleared recovery state back to the primary mirror. Other queued lanes still
+  require `hq lanes admit`.
+
 - A remote `hq lanes list` read no longer dispatches owner hire summaries,
   capacity probes, or mirror snapshots to other Outposts. Two Outposts that
   each held a lane placed on the other ran `hq lanes list --json` on each other

package/assets/scaffold/core/scripts/clean-worktree-reconcile-handoff.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+# Remove only handoff mirrors that are byte-identical to the incoming branch,
+# so clean-worktree's merge can recreate them from that branch.
+set -euo pipefail
+
+usage() {
+  echo "Usage: clean-worktree-reconcile-handoff.sh <absolute-hq-root> <local-branch>" >&2
+}
+
+if [[ $# -ne 2 ]]; then
+  usage
+  exit 64
+fi
+
+HQ_ROOT="$1"
+BRANCH="$2"
+if [[ "$HQ_ROOT" != /* ]]; then
+  echo "ERROR: HQ root must be an absolute path" >&2
+  usage
+  exit 64
+fi
+if [[ ! -d "$HQ_ROOT" ]]; then
+  echo "ERROR: HQ root is not a directory: $HQ_ROOT" >&2
+  exit 1
+fi
+HQ_ROOT="$(cd -P "$HQ_ROOT" && pwd -P)"
+TOPLEVEL="$(git -C "$HQ_ROOT" rev-parse --show-toplevel 2>/dev/null)" || {
+  echo "ERROR: HQ root is not a Git worktree: $HQ_ROOT" >&2
+  exit 1
+}
+TOPLEVEL="$(cd -P "$TOPLEVEL" && pwd -P)"
+if [[ "$TOPLEVEL" != "$HQ_ROOT" ]]; then
+  echo "ERROR: supplied path is not the Git worktree root: $HQ_ROOT" >&2
+  exit 1
+fi
+
+BRANCH_REF="refs/heads/$BRANCH"
+if ! git -C "$HQ_ROOT" show-ref --verify --quiet "$BRANCH_REF"; then
+  echo "ERROR: incoming branch does not exist locally: $BRANCH" >&2
+  exit 1
+fi
+
+POINTER_PATH="workspace/threads/handoff.json"
+if ! git -C "$HQ_ROOT" cat-file -e "$BRANCH_REF:$POINTER_PATH" 2>/dev/null; then
+  echo "No incoming handoff pointer on $BRANCH; no mirror paths to reconcile."
+  exit 0
+fi
+
+THREAD_PATH="$(git -C "$HQ_ROOT" show "$BRANCH_REF:$POINTER_PATH" | jq -er '.thread_path | select(type == "string")')" || {
+  echo "ERROR: incoming branch handoff pointer has no string thread_path" >&2
+  exit 1
+}
+case "$THREAD_PATH" in
+  workspace/threads/*) ;;
+  *) echo "ERROR: unsafe incoming handoff thread_path: $THREAD_PATH" >&2; exit 1 ;;
+esac
+case "/$THREAD_PATH/" in
+  *"//"*|*"/./"*|*"/../"*)
+    echo "ERROR: unsafe incoming handoff thread_path: $THREAD_PATH" >&2
+    exit 1
+    ;;
+esac
+if [[ "$THREAD_PATH" == "$POINTER_PATH" || "$THREAD_PATH" == *$'\n'* || "$THREAD_PATH" == *$'\r'* ]]; then
+  echo "ERROR: unsafe incoming handoff thread_path: $THREAD_PATH" >&2
+  exit 1
+fi
+if ! git -C "$HQ_ROOT" cat-file -e "$BRANCH_REF:$THREAD_PATH" 2>/dev/null; then
+  echo "ERROR: incoming handoff thread is missing from $BRANCH: $THREAD_PATH" >&2
+  exit 1
+fi
+
+branch_file_matches() {
+  local relative_path="$1" local_file="$2" comparison_status=0
+  if git -C "$HQ_ROOT" show "$BRANCH_REF:$relative_path" | cmp -s - "$local_file"; then
+    return 0
+  else
+    comparison_status=$?
+  fi
+  if [[ "$comparison_status" -eq 1 ]]; then
+    return 1
+  fi
+  return 2
+}
+
+declare -a mirror_paths=("$POINTER_PATH" "$THREAD_PATH")
+declare -a identical_paths=()
+declare -a differing_paths=()
+for relative_path in "${mirror_paths[@]}"; do
+  absolute_path="$HQ_ROOT/$relative_path"
+  if [[ ! -e "$absolute_path" && ! -L "$absolute_path" ]]; then
+    continue
+  fi
+  if [[ -L "$absolute_path" || ! -f "$absolute_path" ]]; then
+    differing_paths+=("$relative_path (not a regular file)")
+    continue
+  fi
+  comparison_status=0
+  if branch_file_matches "$relative_path" "$absolute_path"; then
+    identical_paths+=("$relative_path")
+  else
+    comparison_status=$?
+    if [[ "$comparison_status" -eq 1 ]]; then
+      differing_paths+=("$relative_path (content differs from $BRANCH)")
+    else
+      echo "ERROR: could not compare incoming $relative_path with $absolute_path" >&2
+      exit 1
+    fi
+  fi
+done
+
+if [[ ${#differing_paths[@]} -gt 0 ]]; then
+  for relative_path in "${differing_paths[@]}"; do
+    echo "BLOCK: preserved main-checkout handoff path: $relative_path" >&2
+  done
+  echo "No mirror paths were removed; surface these local files before merging." >&2
+  exit 2
+fi
+
+reconciliation_blocked=0
+for relative_path in "${identical_paths[@]}"; do
+  absolute_path="$HQ_ROOT/$relative_path"
+  if [[ ! -e "$absolute_path" && ! -L "$absolute_path" ]]; then
+    continue
+  fi
+  if [[ -L "$absolute_path" || ! -f "$absolute_path" ]]; then
+    echo "BLOCK: preserved changed main-checkout path: $relative_path" >&2
+    reconciliation_blocked=1
+    continue
+  fi
+
+  destination_dir="$(dirname "$absolute_path")"
+  moved_file="$(mktemp "$destination_dir/.clean-worktree-handoff.XXXXXX")"
+  if ! mv "$absolute_path" "$moved_file"; then
+    rm -f "$moved_file"
+    echo "ERROR: could not safely move mirrored handoff path: $relative_path" >&2
+    exit 1
+  fi
+
+  comparison_status=0
+  if [[ ! -L "$moved_file" && -f "$moved_file" ]] && branch_file_matches "$relative_path" "$moved_file"; then
+    if [[ -e "$absolute_path" || -L "$absolute_path" ]]; then
+      rm -f "$moved_file"
+      echo "BLOCK: a new main-checkout file appeared during reconciliation; preserved it: $relative_path" >&2
+      reconciliation_blocked=1
+    else
+      rm "$moved_file"
+      echo "Reconciled byte-identical handoff mirror: $relative_path"
+    fi
+  else
+    comparison_status=$?
+    if [[ ! -e "$absolute_path" && ! -L "$absolute_path" ]]; then
+      if mv "$moved_file" "$absolute_path"; then
+        echo "BLOCK: handoff path changed during reconciliation; restored it untouched: $relative_path" >&2
+      else
+        echo "BLOCK: handoff path changed during reconciliation; preserved it at $moved_file" >&2
+      fi
+    else
+      echo "BLOCK: handoff path changed during reconciliation; preserved captured file at $moved_file and current path $absolute_path" >&2
+    fi
+    if [[ "$comparison_status" -gt 1 ]]; then
+      echo "ERROR: could not compare incoming $relative_path with its moved file" >&2
+      exit 1
+    fi
+    reconciliation_blocked=1
+  fi
+done
+
+if [[ "$reconciliation_blocked" -ne 0 ]]; then
+  echo "No merge should be attempted until the changed handoff paths are surfaced." >&2
+  exit 2
+fi

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

@@ -0,0 +1,285 @@
+#!/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/verify-story-deliverables.sh

@@ -0,0 +1,148 @@
+#!/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