@indigoai-us/hq-cli 5.290.0 → 5.292.0

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

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

@@ -0,0 +1,226 @@
+#!/usr/bin/env bash
+# hq-core: public
+# hq-delegate-grant.sh — materialize a delegation's dossier in the vault and
+# write the ACL grants its manifest declares, verifying each one landed.
+#
+# Usage:
+#   core/scripts/hq-delegate-grant.sh --manifest <path> [--yes]
+#
+# Without --yes: prints the full grant plan (prefix, principal, permission —
+# the write grant is a privilege escalation and needs explicit confirmation)
+# and exits 2 without mutating anything. The caller (the /delegate skill)
+# confirms with the user, then re-invokes with --yes.
+#
+# With --yes:
+#   1. hq sync push the project directory so the vault prefix exists
+#   2. hq files share each manifest vaultPrefix to the recipient
+#   3. read each grant back with hq files acl and match grantee + permission
+#   4. advance manifest status building -> granted, stamping verifiedAt
+#
+# Direct ACL grants ONLY — this helper never mints a share-session URL
+# (policy hq-delegate-never-inlines-secrets-or-share-urls).
+#
+# Idempotent: a prefix whose grant already exists is reported, not an error.
+# A failed read-back exits non-zero and leaves manifest status unchanged.
+#
+# Env: HQ_ROOT — HQ root override (default: resolved from script location)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HQ_ROOT="${HQ_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+usage() { sed -n '3,25p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; }
+die()   { echo "hq-delegate-grant: $*" >&2; exit 1; }
+
+command -v jq >/dev/null 2>&1 || die "jq is required but not installed"
+
+MANIFEST="" YES=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --manifest) MANIFEST="${2:-}"; shift 2 ;;
+    --yes)      YES=1; shift ;;
+    -h|--help)  usage; exit 0 ;;
+    *) die "unknown argument: $1" ;;
+  esac
+done
+
+[ -n "$MANIFEST" ] || die "--manifest is required"
+[ -f "$MANIFEST" ] || die "manifest not found: $MANIFEST"
+jq -e . "$MANIFEST" >/dev/null 2>&1 || die "manifest is not valid JSON: $MANIFEST"
+
+COMPANY="$(jq -r '.company // empty' "$MANIFEST")"
+PROJECT="$(jq -r '.project.name // empty' "$MANIFEST")"
+PRINCIPAL="$(jq -r '.to.principal // empty' "$MANIFEST")"
+DISPLAY="$(jq -r '.to.displayName // .to.principal // empty' "$MANIFEST")"
+STATUS="$(jq -r '.status // empty' "$MANIFEST")"
+[ -n "$COMPANY" ]   || die "manifest has no company"
+[ -n "$PROJECT" ]   || die "manifest has no project.name"
+[ -n "$PRINCIPAL" ] || die "manifest has no to.principal"
+
+# File-ACL principals must be an email, grp_<id>, or @all — an agentUid is
+# NOT accepted by `hq files share`. For agent recipients, grants flow through
+# a deterministic per-agent delegation group (the /new-agent pattern):
+# grp_dlg-<uid tail>, containing exactly that agent.
+GRANT_PRINCIPAL="$PRINCIPAL"
+case "$PRINCIPAL" in
+  agt_*)
+    TAIL="$(printf '%s' "$PRINCIPAL" | tail -c 9 | tr '[:upper:]' '[:lower:]')"
+    GRANT_PRINCIPAL="grp_dlg-$TAIL"
+    ;;
+esac
+
+case "$STATUS" in
+  building|granted) ;;
+  *) die "manifest status is '$STATUS' — grants run from 'building' (or re-run from 'granted'), not from there" ;;
+esac
+
+PREFIX_COUNT="$(jq '.vaultPrefixes | length' "$MANIFEST")"
+[ "$PREFIX_COUNT" -gt 0 ] || die "manifest has no vaultPrefixes"
+
+# --- validate every prefix BEFORE touching anything --------------------------
+# Company-relative, trailing-slash folder form. A bare prefix would degrade to
+# a single literal key and grant nothing useful; company-anchored prefixes do
+# not exist in the bucket. Either is a hard error, never a silent grant.
+
+BAD="$(jq -r '.vaultPrefixes[] | .prefix
+  | select((endswith("/") | not) or startswith("companies/") or startswith("/"))' "$MANIFEST")"
+if [ -n "$BAD" ]; then
+  die "prefix violates the hq-files prefix conventions (must be company-relative folder form ending in '/'): $BAD"
+fi
+
+# --- plan (always printed; the only output without --yes) --------------------
+
+echo "Delegation grant plan — company '$COMPANY', recipient '$PRINCIPAL':"
+if [ "$GRANT_PRINCIPAL" != "$PRINCIPAL" ]; then
+  echo "  0. Agent recipient: grants flow through group $GRANT_PRINCIPAL (created if absent, containing exactly $DISPLAY)"
+fi
+echo "  1. Push companies/$COMPANY/projects/$PROJECT/ to the vault (on-conflict keep)"
+jq -r '.vaultPrefixes[] | "  2. Grant \(.permission) on \(.prefix) — \(.reason // "")"' "$MANIFEST"
+WRITE_PREFIXES="$(jq -r '.vaultPrefixes[] | select(.permission == "write") | .prefix' "$MANIFEST")"
+if [ -n "$WRITE_PREFIXES" ]; then
+  echo
+  echo "NOTE: granting 'write' is a privilege escalation. The recipient will be able"
+  echo "to upload, overwrite, and delete under: $(printf '%s ' "$WRITE_PREFIXES")"
+fi
+
+if [ "$YES" -ne 1 ]; then
+  echo
+  echo "hq-delegate-grant: confirmation required — re-run with --yes after the user approves" >&2
+  exit 2
+fi
+
+# --- 1. materialize the dossier AND referenced knowledge in the vault --------
+# (Live finding: granting read on a knowledge prefix is useless if the
+# specific referenced file was never pushed — the recipient's pull succeeds
+# on the prefix and silently misses the file. Push every referenced
+# company-local knowledge/policy path alongside the dossier.)
+
+hq sync push "companies/$COMPANY/projects/$PROJECT/" --company "$COMPANY" --on-conflict keep \
+  || die "vault push failed for companies/$COMPANY/projects/$PROJECT/"
+
+jq -r --arg co "$COMPANY" \
+  '((.knowledge // []) + (.policies // []))[] | select(startswith("companies/" + $co + "/"))' \
+  "$MANIFEST" | while IFS= read -r kpath; do
+  if [ -e "$HQ_ROOT/$kpath" ]; then
+    hq sync push "$kpath" --company "$COMPANY" --on-conflict keep \
+      || die "vault push failed for referenced knowledge: $kpath"
+  else
+    echo "hq-delegate-grant: referenced path missing locally (cannot push): $kpath — the verify probe will fail if it is not already in the vault" >&2
+  fi
+done
+
+# --- 1b. agent recipients: ensure the delegation group exists + contains them
+
+if [ "$GRANT_PRINCIPAL" != "$PRINCIPAL" ]; then
+  # Both calls are idempotent-tolerated: an existing group / existing member
+  # is fine — the ACL read-back below is the arbiter of success.
+  hq groups create "$GRANT_PRINCIPAL" --name "Delegation: $DISPLAY" --company "$COMPANY" \
+    || echo "hq-delegate-grant: group create reported an error (may already exist) — continuing" >&2
+  hq groups add "$GRANT_PRINCIPAL" "$PRINCIPAL" --company "$COMPANY" \
+    || echo "hq-delegate-grant: group add reported an error (may already be a member) — continuing" >&2
+fi
+
+# --- 2+3. exact structured read-back; never infer identity from a new row ---
+# Requires the structured CLI contracts. Unsupported/failed reads stop the flow.
+EXPECTED_TYPE="" EXPECTED_ID="" EXPECTED_COMPANY=""
+case "$GRANT_PRINCIPAL" in
+  grp_*) EXPECTED_TYPE=group; EXPECTED_ID="$GRANT_PRINCIPAL" ;;
+  @all) EXPECTED_TYPE=company-wide; EXPECTED_ID="" ;;
+  *)
+    RESOLVE_RC=0
+    RESOLVED="$(hq people resolve "$PRINCIPAL" --company "$COMPANY" --json --membership-only)" || RESOLVE_RC=$?
+    if printf '%s' "$RESOLVED" | jq -e '.status == "found" and (.person.personUid | type == "string") and (.person.companyUid | type == "string")' >/dev/null; then
+      [ "$RESOLVE_RC" -eq 0 ] || die "recipient resolution failed"
+      EXPECTED_TYPE=person
+      EXPECTED_ID="$(printf '%s' "$RESOLVED" | jq -r '.person.personUid')"
+      EXPECTED_COMPANY="$(printf '%s' "$RESOLVED" | jq -r '.person.companyUid')"
+    elif printf '%s' "$RESOLVED" | jq -e '.status == "not_found"' >/dev/null; then
+      case "$PRINCIPAL" in *@*) EXPECTED_TYPE=email; EXPECTED_ID="$(printf '%s' "$PRINCIPAL" | tr '[:upper:]' '[:lower:]' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')" ;; *) die "unresolved recipient" ;; esac
+    else
+      die "authoritative recipient lookup failed; update hq-cli if --membership-only is unsupported"
+    fi
+    ;;
+esac
+
+read_acl() {
+  local result
+  result="$(hq files acl "$1" --company "$COMPANY" --json)" || return 1
+  printf '%s' "$result" | jq -e --arg prefix "$1" --arg company "$EXPECTED_COMPANY" '
+    .schemaVersion == 1 and
+    (
+      .prefix == $prefix or
+      (($prefix | endswith("/*")) and .prefix == ($prefix | sub("\\*$"; "")))
+    ) and
+    (.companyUid | type == "string") and ($company == "" or .companyUid == $company) and
+    (.direct | type == "array") and (.exists | type == "boolean")
+  ' >/dev/null || { echo "hq-delegate-grant: invalid structured ACL response for $1" >&2; return 1; }
+  printf '%s' "$result"
+}
+
+NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+i=0
+while [ "$i" -lt "$PREFIX_COUNT" ]; do
+  PFX="$(jq -r ".vaultPrefixes[$i].prefix" "$MANIFEST")"
+  PERM="$(jq -r ".vaultPrefixes[$i].permission" "$MANIFEST")"
+  # Always address the recursive "folder/*" pattern explicitly. Since hq-pro
+  # #3662 (2026-09-23) the server echoes the raw pattern back on read, and a
+  # bare trailing "/" can mean a PRIVATE folder pattern when that flag is on.
+  # A delegation grant is always the recursive share, never a private folder.
+  ACL_PATTERN="${PFX}*"
+  BEFORE="$(read_acl "$ACL_PATTERN")" || die "ACL preflight failed; no share attempted for $PFX"
+  EXPECTED_COMPANY="$(printf '%s' "$BEFORE" | jq -r '.companyUid')"
+  SHARE_RC=0
+  hq files share "$ACL_PATTERN" --with "$GRANT_PRINCIPAL" --permission "$PERM" --company "$COMPANY" || SHARE_RC=$?
+  [ "$SHARE_RC" -eq 0 ] || echo "hq-delegate-grant: share reported an error on $PFX; checking exact grant" >&2
+  landed=0
+  for delay in 0 1 2; do
+    [ "$delay" -eq 0 ] || sleep "$delay"
+    if AFTER="$(read_acl "$ACL_PATTERN")" && printf '%s' "$AFTER" | jq -e \
+      --arg id "$EXPECTED_ID" --arg type "$EXPECTED_TYPE" --arg perm "$PERM" \
+      '.exists and any(.direct[]; .granteeType == $type and .granteeId == $id and .permission == $perm)' >/dev/null; then
+      landed=1
+      break
+    fi
+  done
+  [ "$landed" -eq 1 ] || die "grant outcome unconfirmed for $PRINCIPAL on $PFX; retain this manifest and resume"
+  TMP_MANIFEST="$(mktemp)"
+  jq --argjson i "$i" --arg now "$NOW" --arg id "$EXPECTED_ID" --arg type "$EXPECTED_TYPE" \
+    --arg company "$EXPECTED_COMPANY" --argjson rc "$SHARE_RC" '
+    .vaultPrefixes[$i].verifiedAt = $now |
+    .vaultPrefixes[$i].grantReceipt = {companyUid:$company,granteeType:$type,granteeId:$id,shareExitCode:$rc,verifiedAt:$now}
+  ' "$MANIFEST" > "$TMP_MANIFEST" && mv "$TMP_MANIFEST" "$MANIFEST"
+  echo "hq-delegate-grant: verified $PERM on $PFX for $PRINCIPAL"
+  i=$((i + 1))
+done
+
+# --- 4. advance manifest status ----------------------------------------------
+
+TMP_MANIFEST="$(mktemp)"
+jq --arg now "$NOW" --arg gp "$GRANT_PRINCIPAL" '
+  .status = "granted"
+  | .grantPrincipal = $gp
+  | .vaultPrefixes = [.vaultPrefixes[] | . + {verifiedAt: $now}]
+' "$MANIFEST" > "$TMP_MANIFEST" && mv "$TMP_MANIFEST" "$MANIFEST"
+
+echo "hq-delegate-grant: all $PREFIX_COUNT grants verified — manifest status advanced to 'granted'"

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

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# hq-core: public
+# Publish final delegation artifacts and verify their canonical cloud bytes.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HQ_ROOT="${HQ_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+. "$SCRIPT_DIR/lib/secret-patterns.sh"
+die() { echo "hq-delegate-publish: $*" >&2; exit 1; }
+[ "${1:-}" = --manifest ] && [ -f "${2:-}" ] || die 'usage: --manifest <path>'
+MANIFEST="$2"
+LOCK="$MANIFEST.send-lock"
+if [ "${3:-}" = --lock-held ]; then
+  [ -d "$LOCK" ] || die 'verification lock missing'
+  OWN_LOCK=0
+else
+  [ "$#" -eq 2 ] || die 'usage: --manifest <path>'
+  mkdir "$LOCK" 2>/dev/null || die 'verification or delivery is active; retry after it finishes'
+  OWN_LOCK=1
+fi
+STAGE=""
+trap '[[ -z "$STAGE" ]] || rm -rf "$STAGE"; [ "$OWN_LOCK" -eq 0 ] || rmdir "$LOCK"' EXIT
+COMPANY="$(jq -er '.company' "$MANIFEST")"
+PROJECT="$(jq -er '.project.name' "$MANIFEST")"
+ID="$(jq -er '.delegationId' "$MANIFEST")"
+for part in "$COMPANY" "$PROJECT" "$ID"; do
+  [[ "$part" =~ ^[A-Za-z0-9_-][A-Za-z0-9._-]*$ ]] || die 'unsafe path segment'
+done
+jq -e '.status == "granted" or .status == "verified"' "$MANIFEST" >/dev/null || die 'confirmed grants required'
+if [ "$(jq -r '.mode' "$MANIFEST")" = transfer ]; then
+  jq -e '.ownershipTransferredAt != null' "$MANIFEST" >/dev/null || die 'transfer must finish before publication'
+fi
+REL="companies/$COMPANY/projects/$PROJECT"
+PROJECT_DIR="$HQ_ROOT/$REL"
+BUNDLE="$(cd "$(dirname "$MANIFEST")" && pwd)"
+[ -f "$BUNDLE/BRIEF.md" ] || die 'BRIEF.md missing'
+[ -f "$PROJECT_DIR/prd.json" ] || die 'PRD missing'
+if [ "$(jq -r '.mode' "$MANIFEST")" = transfer ]; then
+  EXPECTED_OWNER="$(jq -r '.to.principal' "$MANIFEST")"
+  jq -e --arg owner "$EXPECTED_OWNER" '.metadata.owner == $owner' "$PROJECT_DIR/prd.json" >/dev/null || die 'local PRD owner does not match recipient'
+fi
+STAGE="$(mktemp -d)"
+atomic_copy() {
+  local target_tmp
+  target_tmp="$(mktemp "${2}.tmp.XXXXXX")"
+  if ! cp "$1" "$target_tmp"; then rm -f "$target_tmp"; return 1; fi
+  mv -f "$target_tmp" "$2"
+}
+DEST="$PROJECT_DIR/delegation/$ID"
+cp "$BUNDLE/BRIEF.md" "$STAGE/BRIEF.md"
+file_hash() {
+  if command -v sha256sum >/dev/null 2>&1; then sha256sum "$1" | cut -d ' ' -f1; else shasum -a 256 "$1" | cut -d ' ' -f1; fi
+}
+# Snapshot final project content, excluding mutable/self-referential receipts.
+: > "$STAGE/hashes"
+for file in "$PROJECT_DIR/prd.json" "$PROJECT_DIR/README.md" "$PROJECT_DIR/journal/delegations.md"; do
+  [ -f "$file" ] || continue
+  jq -cn --arg key "${file#"$HQ_ROOT/"}" --arg value "$(file_hash "$file")" '{key:$key,value:$value}' >> "$STAGE/hashes"
+done
+jq -cn --arg key "$REL/delegation/$ID/BRIEF.md" --arg value "$(file_hash "$STAGE/BRIEF.md")" '{key:$key,value:$value}' >> "$STAGE/hashes"
+jq -s 'from_entries' "$STAGE/hashes" > "$STAGE/checksums"
+jq --slurpfile hashes "$STAGE/checksums" '.checksums=$hashes[0] | .status="granted" | .recipientAccess="unconfirmed" | del(.publication,.verifiedAt,.sentAt,.dmEventId)' "$MANIFEST" > "$STAGE/manifest.json"
+hq_scan_secrets "$STAGE/manifest.json" "$STAGE/BRIEF.md" || die 'unsafe generated dossier'
+if grep -Eq 'share-session/[A-Za-z0-9_-]+' "$STAGE/manifest.json" "$STAGE/BRIEF.md"; then
+  die 'share-session capability in dossier; nothing published'
+fi
+mkdir -p "$DEST"
+atomic_copy "$STAGE/BRIEF.md" "$DEST/BRIEF.md"
+atomic_copy "$STAGE/manifest.json" "$DEST/manifest.json"
+atomic_copy "$STAGE/manifest.json" "$MANIFEST"
+# keep may preserve stale canonical content. Read-back must catch that instead
+# of overwriting concurrent changes merely to make the check pass.
+hq sync push "$REL/" --company "$COMPANY" --on-conflict keep || die 'final dossier push failed; resume publication'
+cp "$STAGE/hashes" "$STAGE/receipts"
+jq -cn --arg key "$REL/delegation/$ID/manifest.json" --arg value "$(file_hash "$DEST/manifest.json")" '{key:$key,value:$value}' >> "$STAGE/receipts"
+while IFS= read -r row; do
+  path="$(printf '%s' "$row" | jq -r '.key')"
+  expected="$(printf '%s' "$row" | jq -r '.value')"
+  matched=0
+  for delay in 0 1 2; do
+    [ "$delay" -eq 0 ] || sleep "$delay"
+    if hq files cat "${path#"companies/$COMPANY/"}" --company "$COMPANY" > "$STAGE/remote"; then
+      if [ "$(file_hash "$STAGE/remote")" = "$expected" ]; then matched=1; break; fi
+    fi
+  done
+  [ "$matched" -eq 1 ] || die "canonical cloud content differs or is unreadable: $path; resolve before sending"
+done < "$STAGE/receipts"
+jq -s 'from_entries' "$STAGE/receipts" > "$STAGE/files"
+jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg path "$REL/delegation/$ID/manifest.json" --slurpfile files "$STAGE/files" \
+  '.publication={verifiedAt:$now,manifestPath:$path,files:$files[0]} | .recipientAccess="unconfirmed"' "$MANIFEST" > "$STAGE/updated"
+atomic_copy "$STAGE/updated" "$MANIFEST"
+echo 'hq-delegate-publish: canonical dossier bytes verified as sender; recipient access unconfirmed'