@indigoai-us/hq-cli 5.313.0 → 5.314.0

package/assets/scaffold/core/scripts/handoff-open-steps.sh

@@ -1,81 +0,0 @@
-#!/usr/bin/env bash
-# hq-core: public
-# handoff-open-steps.sh — list and close next steps across handoff threads
-# (2026-09-07).
-#
-# Handoff threads record next_steps; since 2026-09-07 each carries an `id`
-# (`<thread_id>#<n>`) and a `status` (open|done|dropped). This script is the
-# closure side: /startwork and /resumework list what is still open instead of
-# re-copying it forward, and a session closes a step when it is actually done.
-#
-# Usage:
-#   handoff-open-steps.sh list [--limit N] [--company <slug>] [--json]
-#   handoff-open-steps.sh close <step-id> [--as done|dropped] [--note "<why>"]
-#   handoff-open-steps.sh reopen <step-id>
-#
-# Threads live in workspace/threads/T-*.json (and archive/**). Closing edits
-# the step in place inside its thread file (only `status`, `closed_at`,
-# `closed_by`, `note`) and bumps `updated_at`; nothing else in the thread is
-# touched. Legacy steps without an id are listed with a synthetic id and can be
-# closed the same way (the id is written on first close).
-set -uo pipefail
-HQ_ROOT="${HQ_ROOT:-${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}}"
-THREADS="$HQ_ROOT/workspace/threads"
-command -v jq >/dev/null 2>&1 || { echo "handoff-open-steps: jq required" >&2; exit 2; }
-CMD="${1:-list}"; shift || true
-
-thread_files() { # newest first, handoffs and checkpoints only
-  find "$THREADS" -name 'T-*.json' ! -name '*.changeset.json' ! -path '*/resume-locks/*' 2>/dev/null \
-    | while IFS= read -r f; do printf '%s\t%s\n' "$(stat -c %Y "$f" 2>/dev/null || stat -f %m "$f")" "$f"; done \
-    | sort -rn | cut -f2
-}
-normalize_thread() { # <file> -> ensure every step has id/status (in memory)
-  jq -c '.next_steps = ((.next_steps // []) | to_entries | map(.key as $k |
-      (if (.value|type)=="string" then {step:.value} else .value end)
-      | .id = (.id // (input_filename|split("/")|last|sub("\\.json$";"")) + "#" + (($k+1)|tostring))
-      | .status = (.status // "open")) | map(del(.key)))' "$1"
-}
-
-case "$CMD" in
-  list)
-    LIMIT=20; CO=""; JSON=0
-    while [ $# -gt 0 ]; do case "$1" in --limit) LIMIT="$2"; shift 2;; --company) CO="$2"; shift 2;; --json) JSON=1; shift;; *) shift;; esac; done
-    n=0; rows=""
-    while IFS= read -r f; do
-      [ -n "$f" ] || continue
-      [ "$n" -ge "$LIMIT" ] && break
-      n=$((n+1))
-      t="$(normalize_thread "$f" 2>/dev/null)" || continue
-      if [ -n "$CO" ]; then
-        printf '%s' "$t" | jq -e --arg co "$CO" '(.metadata.company // []) | index($co) != null' >/dev/null 2>&1 || continue
-      fi
-      rows="$rows$(printf '%s' "$t" | jq -c '{thread: .thread_id, title: (.metadata.title // ""), created: .created_at} as $h | .next_steps[] | select(.status == "open") | $h + {id, step}')
-"
-    done < <(thread_files)
-    if [ "$JSON" = 1 ]; then printf '%s' "$rows" | jq -s 'map(select(. != null))'; exit 0; fi
-    if [ -z "$(printf '%s' "$rows" | tr -d '[:space:]')" ]; then echo "No open handoff steps in the last $n thread(s)."; exit 0; fi
-    printf '%s' "$rows" | jq -r '"\(.id)  \(.step)  [\(.title)]"'
-    ;;
-  close|reopen)
-    ID="${1:-}"; shift || true
-    [ -n "$ID" ] || { echo "usage: $CMD <step-id>" >&2; exit 2; }
-    AS="done"; NOTE=""
-    while [ $# -gt 0 ]; do case "$1" in --as) AS="$2"; shift 2;; --note) NOTE="$2"; shift 2;; *) shift;; esac; done
-    [ "$CMD" = reopen ] && AS="open"
-    case "$AS" in done|dropped|open) ;; *) echo "--as must be done|dropped" >&2; exit 2;; esac
-    tid="${ID%%#*}"
-    f="$(find "$THREADS" -name "$tid.json" ! -path '*/resume-locks/*' 2>/dev/null | head -1)"
-    [ -n "$f" ] || { echo "handoff-open-steps: thread $tid not found under $THREADS" >&2; exit 3; }
-    now="$(date -u +%Y-%m-%dT%H:%M:%SZ)"; by="${HQ_SESSION_ID:-${CLAUDE_SESSION_ID:-unknown-session}}"
-    normalize_thread "$f" | jq --arg id "$ID" --arg as "$AS" --arg now "$now" --arg by "$by" --arg note "$NOTE" '
-      if ([.next_steps[] | select(.id == $id)] | length) == 0 then error("step \($id) not in thread") else . end
-      | .next_steps = (.next_steps | map(if .id == $id then
-          (if $as == "open" then del(.closed_at, .closed_by) | .status = "open"
-           else .status = $as | .closed_at = $now | .closed_by = $by | (if $note != "" then .note = $note else . end) end)
-        else . end))
-      | .updated_at = $now' > "$f.tmp" 2>"$f.err" || { cat "$f.err" >&2; rm -f "$f.tmp" "$f.err"; exit 3; }
-    rm -f "$f.err"; mv "$f.tmp" "$f"
-    echo "handoff-open-steps: $ID -> $AS"
-    ;;
-  *) sed -n 2,22p "$0"; exit 2 ;;
-esac

package/assets/scaffold/core/scripts/handoff-post.sh

@@ -1,252 +0,0 @@
-#!/usr/bin/env bash
-# handoff-post.sh — detached post-handoff orchestrator.
-#
-# Runs AFTER handoff-finalize.sh emits handoff.json. Does the mechanical work
-# that used to burn foreground-session tokens:
-#   1. Archive old threads (60d), then regen thread INDEX.md + recent.md (bash)
-#   2. Regen orchestrator INDEX.md (bash)
-#   3. qmd reindex via qmd-reindex-bg.sh (single-flight; agent boxes skip)
-#
-# Model work is intentionally not launched from this detached shell. /learn and
-# /document-release follow-ups run from the handoff skill itself, so auth
-# failures cannot disappear into /tmp logs.
-#
-# Usage (called by handoff skill as `nohup handoff-post.sh ... &`):
-#   core/scripts/handoff-post.sh <thread_path> [learnings_json_file]
-
-set -euo pipefail
-
-HQ_ROOT="${HQ_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
-cd "$HQ_ROOT"
-HANDOFF_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$HANDOFF_SCRIPT_DIR/lib/session-id.sh"
-
-THREAD_PATH="${1:-}"
-LEARNINGS_FILE="${2:-}"
-
-LOG_DIR="${HANDOFF_LOG_DIR:-/tmp}"
-LOG_MAIN="${LOG_DIR}/handoff-post.log"
-LOG_QMD="${LOG_DIR}/qmd-handoff.log"
-
-TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-
-log() { echo "[${TS}] $*" >> "$LOG_MAIN"; }
-
-: > "$LOG_MAIN"
-log "handoff-post starting (thread=${THREAD_PATH:-none}, learnings=${LEARNINGS_FILE:-none})"
-
-# --- 1. Archive old threads (gated once per 24h) ---
-if hq core archive-old-threads --gated >>"$LOG_MAIN" 2>&1; then
-  log "archive: ok"
-else
-  log "archive: error (continuing)"
-fi
-
-# --- 2. Regen thread INDEX + recent (bash, no Claude) ---
-if hq core rebuild-index threads --both >>"$LOG_MAIN" 2>&1; then
-  log "threads-index: ok"
-else
-  log "threads-index: error (continuing)"
-fi
-
-# --- 3. Regen orchestrator INDEX (bash, no Claude) ---
-if hq core rebuild-index orchestrator >>"$LOG_MAIN" 2>&1; then
-  log "orchestrator-index: ok"
-else
-  log "orchestrator-index: error (continuing)"
-fi
-
-if [[ -n "$LEARNINGS_FILE" && -s "$LEARNINGS_FILE" ]]; then
-  learning_count=$(jq 'if type == "array" then length else 0 end' "$LEARNINGS_FILE" 2>/dev/null || echo 0)
-  if [[ "${learning_count:-0}" -gt 0 ]]; then
-    log "learn: eligible and pending runtime dispatch by handoff skill (${learning_count} learning(s); no dispatch proof)"
-  else
-    log "learn: no learnings to dispatch"
-  fi
-else
-  log "learn: no learnings file provided"
-fi
-
-if [[ -n "$THREAD_PATH" && -f "$THREAD_PATH" ]]; then
-  if scope_counts=$(jq -r '
-    (.files_touched // []) as $files
-    | (if ($files | type) == "array" then
-         [$files[] |
-           if type == "string" then .
-           elif type == "object" and (.path | type) == "string" then .path
-           else null
-           end]
-       else [] end) as $paths
-    | [
-        ($paths | map(select(if type == "string" then test("^(companies|repos)/") else false end)) | length),
-        ($paths | map(select(. == null)) | length)
-      ]
-    | @tsv
-  ' "$THREAD_PATH" 2>/dev/null); then
-    IFS=$'\t' read -r scope_match skipped_count <<< "$scope_counts"
-  else
-    scope_match=0
-    skipped_count=0
-    log "document-release: skipped (invalid thread JSON)"
-  fi
-  for ((skipped_index = 0; skipped_index < skipped_count; skipped_index++)); do
-    log "document-release: skipped unsupported files_touched entry"
-  done
-  if [[ "$scope_match" -gt 0 ]]; then
-    if bash "$HQ_ROOT/core/scripts/skill-installed.sh" document-release "${HQ_ACTIVE_COMPANY:-}" >/dev/null 2>>"$LOG_MAIN"; then
-      log "document-release: eligible and pending runtime dispatch by handoff skill ($scope_match scoped files; no dispatch proof)"
-    else
-      log "document-release: skipped (skill not installed)"
-    fi
-  else
-    log "document-release: skipped (no company/repo files in files_touched)"
-  fi
-else
-  log "document-release: skipped (no thread path)"
-fi
-
-# --- 3b. Push company handoff mirrors promptly (best effort) ---
-# Session snapshots are intentionally gitignored, so a completed mirror needs
-# the sync client to make the handoff available to a second device. Keep
-# finalizer company metadata and add the company bound to this session when no
-# changed path identified one; never use a device-wide active-company value.
-bound_session_company() {
-  local session_id metadata company
-  session_id="$(session_id_resolve "$HQ_ROOT")"
-  [[ -n "$session_id" ]] || return 0
-  metadata="$HQ_ROOT/workspace/sessions/$session_id/meta.yaml"
-  [[ -r "$metadata" ]] || return 0
-  company="$(awk '$1 == "company_slug:" { sub(/^[^:]+:[[:space:]]*/, ""); gsub(/^"|"$/, ""); print; exit }' "$metadata" 2>/dev/null || true)"
-  [[ "$company" =~ ^[a-z][a-z0-9_-]*$ ]] || return 0
-  printf '%s' "$company"
-}
-
-if [[ -n "$THREAD_PATH" && -f "$THREAD_PATH" ]] && command -v hq >/dev/null 2>&1; then
-  if [[ "$THREAD_PATH" == /* ]]; then
-    THREAD_FILE="$THREAD_PATH"
-  else
-    THREAD_FILE="$HQ_ROOT/$THREAD_PATH"
-  fi
-  SYNC_COMPANIES_JSON="$(jq -c '
-    (.metadata.company // [])
-    | (if type == "array" then . else [.] end)
-    | map(select(type == "string" and test("^[a-z][a-z0-9_-]*$")))
-    | unique
-  ' "$THREAD_FILE" 2>/dev/null || printf '[]')"
-  BOUND_COMPANY="$(bound_session_company)"
-  if [[ -n "$BOUND_COMPANY" ]]; then
-    UPDATED_SYNC_COMPANIES_JSON="$(jq -c --arg company "$BOUND_COMPANY" '. + [$company] | unique' <<< "$SYNC_COMPANIES_JSON")"
-    if [[ "$SYNC_COMPANIES_JSON" != "$UPDATED_SYNC_COMPANIES_JSON" ]]; then
-      SYNC_COMPANIES_JSON="$UPDATED_SYNC_COMPANIES_JSON"
-      THREAD_TMP="$(mktemp "$HQ_ROOT/workspace/threads/.handoff-post-XXXXXX")"
-      if jq -c --argjson companies "$SYNC_COMPANIES_JSON" \
-        '.metadata = (.metadata // {}) | .metadata.company = $companies' \
-        "$THREAD_FILE" > "$THREAD_TMP" && mv "$THREAD_TMP" "$THREAD_FILE"; then
-        :
-      else
-        rm -f "$THREAD_TMP"
-        log "workspace-sync: skipped (could not add bound company to handoff thread)"
-        SYNC_COMPANIES_JSON='[]'
-      fi
-    else
-      SYNC_COMPANIES_JSON="$UPDATED_SYNC_COMPANIES_JSON"
-    fi
-  fi
-  THREAD_ID="$(jq -r '.thread_id // empty' "$THREAD_FILE" 2>/dev/null || true)"
-  THREAD_MIRRORABLE="false"
-  case "$THREAD_FILE" in
-    "$HQ_ROOT"/workspace/threads/T-*.json)
-      if [[ "$THREAD_ID" =~ ^T-[A-Za-z0-9._-]+$ ]]; then THREAD_MIRRORABLE="true"; fi
-      ;;
-  esac
-  if [[ "$THREAD_MIRRORABLE" == "true" && "$SYNC_COMPANIES_JSON" != '[]' ]]; then
-    MIRROR_HOOK="$HQ_ROOT/.claude/hooks/mirror-thread-to-company.sh"
-    if [[ -f "$MIRROR_HOOK" ]]; then
-      jq -n --arg file_path "$THREAD_FILE" \
-        '{tool_name:"Write",tool_input:{file_path:$file_path}}' | \
-        bash "$MIRROR_HOOK" >>"$LOG_MAIN" 2>&1 || \
-        log "workspace-sync: mirror hook failed for handoff thread"
-    else
-      log "workspace-sync: mirror hook unavailable for handoff thread"
-    fi
-  fi
-  while IFS= read -r company; do
-    [[ "$company" =~ ^[a-z][a-z0-9_-]*$ ]] || continue
-    [[ -d "$HQ_ROOT/companies/$company/workspace" ]] || continue
-    if [[ "$THREAD_MIRRORABLE" != "true" || \
-          ! -f "$HQ_ROOT/companies/$company/workspace/sessions/$THREAD_ID.json" ]]; then
-      log "workspace-sync: skipped (thread mirror missing for $company)"
-      continue
-    fi
-    if hq sync push --company "$company" "companies/$company/workspace" >>"$LOG_MAIN" 2>&1; then
-      log "workspace-sync: pushed companies/$company/workspace"
-    else
-      log "workspace-sync: failed companies/$company/workspace"
-    fi
-  done < <(jq -r '.[]' <<< "$SYNC_COMPANIES_JSON")
-elif [[ -n "$THREAD_PATH" && -f "$THREAD_PATH" ]]; then
-  log "workspace-sync: skipped (hq CLI unavailable)"
-fi
-
-# --- 4. qmd reindex (agent: skip; laptop: single-flight) ---
-# handoff-finalize may already have run the helper; agent boxes no-op
-# (skipped-agent). Never dual-nohup raw cleanup+update+embed on agents.
-# Never invoke managed index wrappers — handoff owns no agent freshness.
-# Prefer Core US-001 helper; fleet binary only if Core file is missing.
-# Lock acquisition runs BEFORE the US-010 session_end spawn so a detached
-# session-end hook cannot delay or interleave with finalize+post single-flight.
-_QMD_BG="$HQ_ROOT/core/scripts/qmd-reindex-bg.sh"
-if [[ ! -f "$_QMD_BG" ]] && [[ -x /usr/local/bin/hq-agent-qmd-reindex-bg ]]; then
-  _QMD_BG=/usr/local/bin/hq-agent-qmd-reindex-bg
-fi
-if [[ -x "$_QMD_BG" ]] || [[ -f "$_QMD_BG" ]]; then
-  _qmd_out="$(bash "$_QMD_BG" --log "$LOG_QMD" 2>/dev/null || true)"
-  # Empty stdout is busy/dedupe quiet — never claim "ok".
-  log "qmd: reindex-bg → ${_qmd_out:-busy-or-quiet}"
-elif [[ -d /var/lib/hq-agent ]]; then
-  log "qmd: skipped-agent (no helper; indexer owns freshness)"
-else
-  log "qmd: skipped (helper missing)"
-fi
-
-# --- 4b. Work Mesh Live: enqueue session_end (US-010) ---
-# Detached + non-blocking. Presence ends via spool; daemon flushes.
-# Same launch shape as the former work-mesh-close hook (nohup + disown).
-# Runs AFTER qmd reindex so this path cannot perturb single-flight lock
-# acquisition order or spawn count. Guarded: older checkouts skip quietly.
-WM_END_HOOK="$HQ_ROOT/core/hooks/SessionEnd/35-work-mesh-session-end.sh"
-if [[ -f "$WM_END_HOOK" ]]; then
-  sid=""
-  sid="$(session_id_resolve "$HQ_ROOT")"
-  if [[ -n "$sid" ]]; then
-    payload=$(printf '{"session_id":"%s"}' "$sid")
-  else
-    payload='{}'
-  fi
-  HQ_ROOT="$HQ_ROOT" CLAUDE_CODE_SESSION_ID="${sid:-}" \
-    nohup bash -c 'printf "%s\n" "$1" | bash "$2" SessionEnd' \
-    _ "$payload" "$WM_END_HOOK" \
-    >>"${LOG_DIR}/work-mesh-session-end.log" 2>&1 </dev/null &
-  disown 2>/dev/null || true
-  log "work-mesh-session-end: launched PID $!"
-else
-  log "work-mesh-session-end: skipped (hook absent)"
-fi
-
-# --- 5. Worktree GC (gated once-per-24h, detached, fully fail-soft) ---
-# HQ worktrees accumulate forever and can reach hundreds of GB. Opportunistically
-# GC the provably-safe stale ones on every handoff. --gated caps this to once per
-# 24h; --apply lets it actually remove (the script's own guards keep it to clean,
-# old, branch-preserved, unreferenced worktrees only). Launched DETACHED because
-# the safety check fetches from origin per repo — it must never block or fail the
-# handoff. Guarded so an older checkout without the script simply skips it.
-WT_GC="$HQ_ROOT/core/scripts/worktree-gc.sh"
-if [[ -f "$WT_GC" ]]; then
-  HQ_ROOT="$HQ_ROOT" nohup bash "$WT_GC" --apply --gated >>"${LOG_DIR}/worktree-gc.log" 2>&1 </dev/null &
-  disown 2>/dev/null || true
-  log "worktree-gc: launched PID $! (--apply --gated)"
-else
-  log "worktree-gc: skipped (script absent)"
-fi
-
-log "handoff-post complete"

package/assets/scaffold/core/scripts/hq-delegate-bundle.sh

@@ -1,307 +0,0 @@
-#!/usr/bin/env bash
-# hq-core: public
-# hq-delegate-bundle.sh — freeze a project into a portable delegation bundle.
-#
-# Usage:
-#   core/scripts/hq-delegate-bundle.sh build \
-#     --company <slug> --project <name> --to <principal> \
-#     [--to-kind person|agent] [--to-name <display name>] \
-#     [--mode transfer|share] [--dry-run]
-#
-# --dry-run prints the manifest JSON to stdout and writes nothing.
-#
-# Writes workspace/delegations/<delegationId>/{manifest.json,BRIEF.md} and
-# prints the delegationId on stdout. The manifest is the single source of
-# truth for every downstream delegation step (grants, verification, pickup
-# prompt) — schema documented in
-# core/knowledge/public/hq-core/delegation-bundle-spec.md.
-#
-# Fails closed (non-zero, nothing written) when:
-#   - required arguments are missing
-#   - the project directory or its prd.json does not exist / parses invalid
-#   - the generated manifest or BRIEF matches a secret-detection pattern
-#
-# Env:
-#   HQ_ROOT — HQ root override (default: resolved from this script's location)
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-HQ_ROOT="${HQ_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
-
-# shellcheck source=lib/secret-patterns.sh
-. "$SCRIPT_DIR/lib/secret-patterns.sh"
-
-usage() {
-  sed -n '3,13p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
-}
-
-die() {
-  echo "hq-delegate-bundle: $*" >&2
-  exit 1
-}
-
-command -v jq >/dev/null 2>&1 || die "jq is required but not installed"
-
-# --- argument parsing --------------------------------------------------------
-
-[ "${1:-}" = "build" ] || { usage >&2; exit 1; }
-shift
-
-COMPANY="" PROJECT="" TO="" TO_KIND="person" TO_NAME="" MODE="transfer" DRY_RUN=0
-while [ $# -gt 0 ]; do
-  case "$1" in
-    --company) COMPANY="${2:-}"; shift 2 ;;
-    --project) PROJECT="${2:-}"; shift 2 ;;
-    --to)      TO="${2:-}"; shift 2 ;;
-    --to-kind) TO_KIND="${2:-}"; shift 2 ;;
-    --to-name) TO_NAME="${2:-}"; shift 2 ;;
-    --mode)    MODE="${2:-}"; shift 2 ;;
-    --dry-run) DRY_RUN=1; shift ;;
-    -h|--help) usage; exit 0 ;;
-    *) die "unknown argument: $1" ;;
-  esac
-done
-
-[ -n "$COMPANY" ] || die "--company is required"
-[ -n "$PROJECT" ] || die "--project is required"
-[ -n "$TO" ]      || die "--to is required"
-case "$MODE" in transfer|share) ;; *) die "--mode must be transfer or share" ;; esac
-case "$TO_KIND" in person|agent) ;; *) die "--to-kind must be person or agent" ;; esac
-
-PROJECT_DIR="$HQ_ROOT/companies/$COMPANY/projects/$PROJECT"
-PRD="$PROJECT_DIR/prd.json"
-[ -d "$PROJECT_DIR" ] || die "project directory not found: companies/$COMPANY/projects/$PROJECT"
-[ -f "$PRD" ] || die "project has no prd.json: companies/$COMPANY/projects/$PROJECT/prd.json"
-jq -e . "$PRD" >/dev/null 2>&1 || die "prd.json is not valid JSON: $PRD"
-
-# --- identity ----------------------------------------------------------------
-
-CREATED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-DELEGATION_ID="dlg-$(date -u +%Y%m%d-%H%M%S)-$PROJECT"
-WHOAMI_JSON="$(hq whoami --json)" || die "could not read sender identity; update hq-cli if --json is unsupported"
-printf '%s' "$WHOAMI_JSON" | jq -e '.authenticated != false and ((.email // .personUid // .agentUid // "") | length > 0)' >/dev/null \
-  || die "sender identity is missing or expired; run hq login"
-FROM_EMAIL="$(printf '%s' "$WHOAMI_JSON" | jq -r '.email // empty')"
-FROM_UID="$(printf '%s' "$WHOAMI_JSON" | jq -r '.personUid // .agentUid // empty')"
-
-# --- checksum helper (macOS + Linux) -----------------------------------------
-
-file_sha256() {
-  if command -v sha256sum >/dev/null 2>&1; then
-    sha256sum "$1" | awk '{print $1}'
-  else
-    shasum -a 256 "$1" | awk '{print $1}'
-  fi
-}
-
-# --- derive vault prefixes, knowledge, policies ------------------------------
-#
-# Vault prefixes are BUCKET-RELATIVE (never prefixed with companies/<slug>/)
-# and always in trailing-slash folder form — see hq-files "Prefix Conventions".
-
-PROJECT_PREFIX="projects/$PROJECT/"
-
-# knowledge entries from prd metadata: split into vault-grantable (under this
-# company), policies (under this company's policies/), and repo-based docs
-# (recorded for the brief, never granted as vault prefixes).
-KNOWLEDGE_JSON="$(jq -c '[.metadata.knowledge // [] | .[]]' "$PRD")"
-
-VAULT_READ_PREFIXES="$(printf '%s' "$KNOWLEDGE_JSON" | jq -r --arg co "$COMPANY" '
-  [ .[]
-    | select(startswith("companies/" + $co + "/"))
-    | sub("^companies/" + $co + "/"; "")
-    # a file path -> its containing folder; a dir path -> itself with slash
-    | if endswith("/") then . else (split("/")[:-1] | join("/") + "/") end
-  ] | unique | .[]')"
-
-MANIFEST_KNOWLEDGE="$(printf '%s' "$KNOWLEDGE_JSON" | jq -c --arg co "$COMPANY" '
-  [ .[] | select((startswith("companies/" + $co + "/policies/")) | not) ] | unique')"
-MANIFEST_POLICIES="$(printf '%s' "$KNOWLEDGE_JSON" | jq -c --arg co "$COMPANY" '
-  [ .[] | select(startswith("companies/" + $co + "/policies/")) ] | unique')"
-
-# vaultPrefixes[]: write on the project dossier, read on referenced knowledge.
-VAULT_PREFIXES_JSON="$(
-  {
-    jq -cn --arg p "$PROJECT_PREFIX" \
-      '{prefix: $p, permission: "write", reason: "project dossier"}'
-    if [ -n "$VAULT_READ_PREFIXES" ]; then
-      printf '%s\n' "$VAULT_READ_PREFIXES" | while IFS= read -r pfx; do
-        [ -n "$pfx" ] || continue
-        jq -cn --arg p "$pfx" \
-          '{prefix: $p, permission: "read", reason: "referenced knowledge/policies"}'
-      done
-    fi
-  } | jq -cs 'unique_by(.prefix)'
-)"
-
-# Guard: every prefix must be folder form and company-relative.
-printf '%s' "$VAULT_PREFIXES_JSON" | jq -e '
-  all(.[]; (.prefix | endswith("/")) and (.prefix | startswith("companies/") | not))
-' >/dev/null || die "internal error: derived a non-folder or company-anchored prefix"
-
-# --- repo block (recorded here; verified/pushed by the US-004 step) ----------
-
-REPO_PATH="$(jq -r '.metadata.repoPath // empty' "$PRD")"
-if [ -n "$REPO_PATH" ]; then
-  REPO_JSON="$(jq -cn \
-    --arg path "$REPO_PATH" \
-    --arg branch "$(jq -r '.branchName // empty' "$PRD")" \
-    --arg base "$(jq -r '.metadata.baseBranch // "main"' "$PRD")" \
-    '{path: $path, remote: null, branch: (if $branch == "" then null else $branch end),
-      baseBranch: $base, headSha: null, dirtyFiles: [], accessVerified: false}')"
-else
-  REPO_JSON="null"
-fi
-
-# --- board id ----------------------------------------------------------------
-
-BOARD_ID="null"
-BOARD_FILE="$HQ_ROOT/companies/$COMPANY/board.json"
-if [ -f "$BOARD_FILE" ]; then
-  BOARD_ID="$(jq --arg prd "companies/$COMPANY/projects/$PROJECT/prd.json" \
-    '[.projects // [] | .[] | select(.prd_path == $prd) | .id] | first // null' \
-    "$BOARD_FILE" 2>/dev/null || echo null)"
-fi
-
-# --- checksums of the project dossier ----------------------------------------
-
-CHECKSUMS_JSON="$(
-  cd "$HQ_ROOT" || exit 1
-  find "companies/$COMPANY/projects/$PROJECT" -type f ! -name '.DS_Store' | sort | head -200 | \
-  while IFS= read -r f; do
-    jq -cn --arg p "$f" --arg h "$(file_sha256 "$f")" '{key: $p, value: $h}'
-  done | jq -s 'from_entries'
-)"
-
-# --- build in a temp dir, scan, then move into place -------------------------
-
-STAGE="$(mktemp -d)"
-trap 'rm -rf "$STAGE"' EXIT
-
-jq -n \
-  --arg id "$DELEGATION_ID" \
-  --arg createdAt "$CREATED_AT" \
-  --arg mode "$MODE" \
-  --arg fromEmail "$FROM_EMAIL" \
-  --arg fromUid "$FROM_UID" \
-  --arg toKind "$TO_KIND" \
-  --arg toPrincipal "$TO" \
-  --arg toName "$TO_NAME" \
-  --arg company "$COMPANY" \
-  --arg project "$PROJECT" \
-  --arg prdPath "companies/$COMPANY/projects/$PROJECT/prd.json" \
-  --argjson boardId "$BOARD_ID" \
-  --argjson vaultPrefixes "$VAULT_PREFIXES_JSON" \
-  --argjson repo "$REPO_JSON" \
-  --argjson knowledge "$MANIFEST_KNOWLEDGE" \
-  --argjson policies "$MANIFEST_POLICIES" \
-  --argjson checksums "$CHECKSUMS_JSON" \
-  '{
-    schemaVersion: 1,
-    delegationId: $id,
-    createdAt: $createdAt,
-    mode: $mode,
-    from: {email: (if $fromEmail == "" then null else $fromEmail end),
-           personUid: (if $fromUid == "" then null else $fromUid end)},
-    to: {kind: $toKind, principal: $toPrincipal,
-         displayName: (if $toName == "" then null else $toName end)},
-    company: $company,
-    project: {name: $project, prdPath: $prdPath, boardId: $boardId},
-    vaultPrefixes: $vaultPrefixes,
-    repo: $repo,
-    secrets: [],
-    knowledge: $knowledge,
-    policies: $policies,
-    checksums: $checksums,
-    status: "building"
-  }' > "$STAGE/manifest.json"
-
-# --- BRIEF.md — full prose for a reader who has never seen the project -------
-
-DESCRIPTION="$(jq -r '.description // "No description recorded."' "$PRD")"
-GOAL="$(jq -r '.metadata.goal // empty' "$PRD")"
-TOTAL_STORIES="$(jq -r '[.userStories // [] | .[]] | length' "$PRD")"
-DONE_STORIES="$(jq -r '[.userStories // [] | .[] | select(.passes == true)] | length' "$PRD")"
-DONE_LIST="$(jq -r '[.userStories // [] | .[] | select(.passes == true)] | .[] | "- \(.id): \(.title)"' "$PRD")"
-NEXT_STEPS="$(jq -r '[.userStories // [] | .[] | select(.passes != true)]
-  | sort_by(.priority) | .[:3] | .[]
-  | "### \(.id): \(.title)\n\n\(.description)\n"' "$PRD")"
-OPEN_QUESTIONS="$(jq -r '[.metadata.openQuestions // [] | .[]] | .[] | "- \(.)"' "$PRD")"
-TRAPS="$(jq -r '[.metadata.securityNotes // empty, (.metadata.executionConventions // [] | .[])]
-  | .[] | "- \(.)"' "$PRD")"
-
-{
-  echo "# Delegation brief — $PROJECT"
-  echo
-  echo "This brief describes the **$PROJECT** project in the **$COMPANY** company. Completed handoff steps are recorded in the manifest. Pull the files and acknowledge receipt; report any access error to the sender."
-  echo
-  echo "## What this project is"
-  echo
-  echo "$DESCRIPTION"
-  if [ -n "$GOAL" ]; then
-    echo
-    echo "## The goal"
-    echo
-    echo "$GOAL"
-  fi
-  echo
-  echo "## Where things stand"
-  echo
-  echo "$DONE_STORIES of $TOTAL_STORIES stories are complete."
-  if [ -n "$DONE_LIST" ]; then
-    echo
-    echo "Already done:"
-    echo
-    echo "$DONE_LIST"
-  fi
-  echo
-  echo "## The next three steps"
-  echo
-  if [ -n "$NEXT_STEPS" ]; then
-    echo "$NEXT_STEPS"
-  else
-    echo "All stories are complete. Remaining work, if any, is described in the project's post-implementation notes."
-  fi
-  if [ -n "$OPEN_QUESTIONS" ]; then
-    echo "## Open questions"
-    echo
-    echo "$OPEN_QUESTIONS"
-    echo
-  fi
-  if [ -n "$TRAPS" ]; then
-    echo "## Known traps and conventions"
-    echo
-    echo "$TRAPS"
-    echo
-  fi
-  echo "## Where everything lives"
-  echo
-  echo "The full PRD (every story, acceptance criteria, and decision history) is at \`companies/$COMPANY/projects/$PROJECT/prd.json\`. The pickup prompt that accompanied this brief pulls every file you need on demand — you do not need to run a full sync."
-} > "$STAGE/BRIEF.md"
-
-# --- fail-closed secret scan -------------------------------------------------
-
-if ! hq_scan_secrets "$STAGE/manifest.json" "$STAGE/BRIEF.md"; then
-  die "generated bundle matched a secret-detection pattern — nothing written (see stderr above)"
-fi
-
-# --- dry run: print the manifest, write nothing ------------------------------
-
-if [ "$DRY_RUN" -eq 1 ]; then
-  cat "$STAGE/manifest.json"
-  rm -rf "$STAGE"
-  trap - EXIT
-  echo "hq-delegate-bundle: dry run — nothing written" >&2
-  exit 0
-fi
-
-# --- move into place ---------------------------------------------------------
-
-DEST="$HQ_ROOT/workspace/delegations/$DELEGATION_ID"
-mkdir -p "$(dirname "$DEST")"
-mv "$STAGE" "$DEST"
-trap - EXIT
-
-echo "$DELEGATION_ID"
-echo "hq-delegate-bundle: wrote workspace/delegations/$DELEGATION_ID/{manifest.json,BRIEF.md}" >&2