@indigoai-us/hq-cli 5.291.0 → 5.292.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [5.292.0] — 2026-09-30
+- Add native `hq core jobs reconcile` behind `core-native-jobs`, retaining the bundled shell rollback and scheduled-job helpers.
+- Behind the default-off `cli.staged-self-update` flag, an npm global self-update installs the new version beside the running package, checks that it answers `--version`, then swaps it in with two renames. The running `hq` stays on disk for the whole install, so services the daemon starts during an update no longer fail with "hq: command not found" or MODULE_NOT_FOUND. pnpm, Bun, Windows and linked installs keep the in-place update.
+
+- Disable Git auto-maintenance, auto-gc, and detached gc during CM-W2b corpus
+  creation so fixture snapshots cannot race lock files.
+
+### Added
+
+- `hq core ontology merge-copies --listed --only <file>` (flag `checkpoint.ontology.merge-listed-pairs`, default off) merges exactly the copy -> original pairs in the file, including pairs whose names differ, such as a company listed under two names. Each pair must name two entities of one type; a copy listed twice, or listed as both a copy and an original, is skipped as `listed_conflict`. Signal and link holds apply as for other pairs.
+- `hq core ontology drop-aliases --only <file>` (flag `checkpoint.ontology.drop-aliases`, default off) removes reviewed wrong aliases, given as `{ entity, alias }` pairs, from entity files. It is a dry run unless `--apply` is given, and it writes through the multi-writer outbox so sync uploads the change.
+
+### Fixed
+
+- `hq core ontology merge-copies --rewrite-refs` no longer edits signal or source files, which sync cannot upload. A pair whose copy a signal or source still names is now held as `server_owned_refs`, and its copy is kept.
+### Added
+
+- Add `hq core delegate bundle`, `grant`, `publish`, `send`, and `verify` as
+  native TypeScript handlers behind the default-off `core-native-delegate`
+  flag, with their shell companions retained as rollback assets.
+- Match native handoff open-steps JSON nulls and invalid-JSON exit codes, and sync zero-change handoffs to the calling session's bound company after mirroring the thread.
+
 ## [5.291.0] — 2026-09-29
 - Add native `hq core jobs schedule-parse` and `validate` commands behind the default-off `core-native-jobs` gate, retaining their shell rollback companions.
 
@@ -28,14 +50,6 @@
 ### Added
 
 - Gate `hq sync push --personal <paths>` behind the default-off `cli.personal-targeted-push-paths` flag; explicit paths are normalized and checked against personal-vault scope and exclusions before upload.
-
-## [5.289.0] — 2026-09-29
-- A failed `hq update` restores the previous working hq-cli install when it could be backed up, instead of leaving the CLI partially updated.
-
-## [5.288.0] — 2026-09-29
-
-### Added
-
 - `hq core ontology merge-copies --rewrite-refs` (flag `checkpoint.ontology.merge-rewrite-refs`, default off) re-points signal refs, invoice and bill links, source and knowledge links from a merged copy to its survivor and carries the copy's external ids and web domains; a pair whose files hold different values for one external id stays held (`external_id_conflict`).
 - A `--only` entry can carry `resolve_external_ids: { <provider>: { primary, namespace, object_type? } }`. With `--rewrite-refs`, a conflicting provider id then keeps `primary` in `external_ids` and moves the pair's other id to the survivor's `external_refs` (`system`, `namespace`, `objectType`, `recordId`), so no id is dropped. A `primary` that matches neither id still holds the pair.
 
@@ -47,6 +61,11 @@
 - `merge-copies --rewrite-refs` no longer holds a survivor as `merge_invalid` when it gains external ids but has no `web_domains` key (or the reverse).
 - `merge-copies` treats an annotation list item whose first key is `path:` as a link to the copy, so it no longer deletes a copy such an annotation still names.
 
+## [5.289.0] — 2026-09-29
+- A failed `hq update` restores the previous working hq-cli install when it could be backed up, instead of leaving the CLI partially updated.
+
+## [5.288.0] — 2026-09-29
+
 ### Added
 
 - Add lead autopilot prompts to the lanes reconcile pass behind

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

@@ -56,6 +56,8 @@ set -euo pipefail
 HQ_ROOT="${HQ_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
 cd "$HQ_ROOT"
 HQ_ROOT="$(pwd -P)"
+HANDOFF_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HANDOFF_SCRIPT_DIR/lib/session-id.sh"
 HAS_GIT_CHECKOUT="false"
 COMMON_GIT_DIR=""
 GIT_PROBE_OUTPUT=""
@@ -252,6 +254,22 @@ MIRROR_COMPANIES_JSON=$(printf '%s\n' "${SAFE_STAGE_PATHS[@]:-}" | jq -R -s -c '
   | unique
 ' 2>/dev/null || printf '[]')
 
+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"
+}
+
+BOUND_SESSION_COMPANY="$(bound_session_company)"
+if [[ -n "$BOUND_SESSION_COMPANY" && -d "companies/$BOUND_SESSION_COMPANY" ]]; then
+  MIRROR_COMPANIES_JSON="$(jq -c --arg company "$BOUND_SESSION_COMPANY" '. + [$company] | unique' <<< "$MIRROR_COMPANIES_JSON")"
+fi
+
 # -------- bg git reap (if launched by caller) --------
 GIT_BG_ERRORS=""
 if [[ -f /tmp/handoff-git-bg.pid ]]; then

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

@@ -18,6 +18,8 @@ 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:-}"
@@ -105,18 +107,83 @@ 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. Trust only
-# the finalizer's lowercase company-slug metadata before constructing a path.
+# 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 '.metadata.company // empty | if type == "array" then .[] else . end' "$THREAD_PATH" 2>/dev/null || true)
+  done < <(jq -r '.[]' <<< "$SYNC_COMPANIES_JSON")
 elif [[ -n "$THREAD_PATH" && -f "$THREAD_PATH" ]]; then
   log "workspace-sync: skipped (hq CLI unavailable)"
 fi
@@ -150,9 +217,7 @@ fi
 WM_END_HOOK="$HQ_ROOT/core/hooks/SessionEnd/35-work-mesh-session-end.sh"
 if [[ -f "$WM_END_HOOK" ]]; then
   sid=""
-  if [[ -f "$HQ_ROOT/workspace/sessions/.current" ]]; then
-    sid="$(tr -d '[:space:]' <"$HQ_ROOT/workspace/sessions/.current" 2>/dev/null || true)"
-  fi
+  sid="$(session_id_resolve "$HQ_ROOT")"
   if [[ -n "$sid" ]]; then
     payload=$(printf '{"session_id":"%s"}' "$sid")
   else

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

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