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

package/assets/scaffold/core/scripts/policy-age-report.sh

@@ -1,156 +0,0 @@
-#!/usr/bin/env bash
-# hq-core: public
-# policy-age-report.sh — measure policy usage and flag retirement candidates
-# (2026-09-07).
-#
-# Why: nothing retired a policy. About 85% of one install's 1,251 personal
-# policies were machine-written, and the only "usage" signal was that the
-# loader printed them — which, above the host's output ceiling, meant nothing.
-# This report gives the fade-out its inputs. It does NOT delete anything; it
-# names candidates with the evidence, for a human (or /learn --retire) to act on.
-#
-# Signals per policy (from workspace/orchestrator/policy-trigger-state/*.txt,
-# one ledger per session, and the policy files themselves):
-#   fired          number of sessions whose ledger recorded the slug (emitted)
-#   retrieved      number of sessions that pulled the full text (record-policy-retrieval.sh)
-#   last_fired     newest ledger mtime that contains the slug (UTC date)
-#   age_days       days since frontmatter `created:` (or file mtime)
-#   stale_refs     backtick-quoted HQ-relative paths in the Rule text that no
-#                  longer exist on disk (an inaccuracy proxy). Only core/,
-#                  .claude/, companies/<co>/ paths are judged; lines that talk
-#                  about a path being deleted/removed/legacy are not dependencies;
-#                  a same-stem sibling (foo.sh -> foo.mjs) counts as renamed.
-#   single_incident frontmatter source is a one-off (user-correction,
-#                  session-learning, back-pressure-failure) AND version == 1
-#
-# Candidate classes (--candidates):
-#   never-fired    fired == 0 and age_days >= --min-age (default 30)
-#   dormant        fired > 0 but last_fired older than --dormant-days (default 90)
-#   stale-refs     stale_refs > 0 (rule points at something that is gone)
-#   single-incident-old   single_incident, age_days >= --incident-days (default 60), and fired <= 1
-#
-# Usage:
-#   policy-age-report.sh [--dir <policies-dir>]... [--json] [--candidates] [--min-age N] [--dormant-days N] [--incident-days N]
-# Defaults: personal/policies and core/policies (add --dir companies/<co>/policies when bound).
-set -uo pipefail
-HQ_ROOT="${HQ_ROOT:-${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}}"
-LEDGERS="${HQ_POLICY_LEDGER_DIR:-$HQ_ROOT/workspace/orchestrator/policy-trigger-state}"
-DIRS=(); JSON=0; CAND=0; MIN_AGE=30; DORMANT=90; INCIDENT=60
-while [ $# -gt 0 ]; do
-  case "$1" in
-    --dir) DIRS+=("$2"); shift 2 ;;
-    --json) JSON=1; shift ;;
-    --candidates) CAND=1; shift ;;
-    --min-age) MIN_AGE="$2"; shift 2 ;;
-    --dormant-days) DORMANT="$2"; shift 2 ;;
-    --incident-days) INCIDENT="$2"; shift 2 ;;
-    -h|--help) sed -n 2,32p "$0"; exit 0 ;;
-    *) echo "policy-age-report: unknown arg $1" >&2; exit 2 ;;
-  esac
-done
-[ "${#DIRS[@]}" -gt 0 ] || DIRS=("$HQ_ROOT/personal/policies" "$HQ_ROOT/core/policies")
-command -v jq >/dev/null 2>&1 || { echo "policy-age-report: jq required" >&2; exit 2; }
-NOW_EPOCH="${HQ_POLICY_REPORT_NOW_EPOCH:-$(date +%s)}"
-TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
-
-# One pass over every ledger: slug<TAB>mtime, then reduce to count + max mtime.
-HAVE_LEDGERS=0
-if [ -d "$LEDGERS" ] && [ -n "$(find "$LEDGERS" -name '*.txt' -type f 2>/dev/null | head -1)" ]; then
-  HAVE_LEDGERS=1
-  find "$LEDGERS" -name '*.txt' -type f 2>/dev/null | while IFS= read -r f; do
-    m="$(stat -c %Y "$f" 2>/dev/null || stat -f %m "$f")"
-    awk -v m="$m" 'NF { print $1 "\t" m }' "$f"
-  done | awk -F'\t' '{ c[$1]++; if ($2 > mx[$1]) mx[$1] = $2 } END { for (s in c) print s "\t" c[s] "\t" mx[s] }' > "$TMP/usage.tsv"
-else
-  : > "$TMP/usage.tsv"
-fi
-# Retrieval ledger (record-policy-retrieval.sh): sessions that PULLED the full text.
-RETRIEVALS="${HQ_POLICY_RETRIEVAL_LEDGER_DIR:-$HQ_ROOT/workspace/orchestrator/policy-retrieval-state}"
-if [ -d "$RETRIEVALS" ]; then
-  cat "$RETRIEVALS"/*.txt 2>/dev/null | awk 'NF { c[$1]++ } END { for (s in c) print s "\t" c[s] }' > "$TMP/retrieved.tsv"
-else
-  : > "$TMP/retrieved.tsv"
-fi
-
-to_epoch() { # YYYY-MM-DD -> epoch (0 on failure)
-  date -u -d "$1" +%s 2>/dev/null || date -u -j -f %Y-%m-%d "$1" +%s 2>/dev/null || echo 0
-}
-
-for dir in "${DIRS[@]}"; do
-  case "$dir" in /*) ;; *) dir="$HQ_ROOT/$dir" ;; esac
-  [ -d "$dir" ] || continue
-  for f in "$dir"/*.md; do
-    [ -f "$f" ] || continue
-    b="$(basename "$f")"
-    case "$b" in README.md|example-policy.md|_digest*.md|*" "*|*.conflict-*|*.sync-conflict-*) continue ;; esac
-    [ -L "$f" ] && continue   # personal overlay mirrors live in core/ as symlinks; count the source once
-    grep -q '^status: retired' "$f" && continue   # already retired (policy-retire.sh)
-    id="$(awk 'NR==1&&!/^---/{exit} /^---/{d++; if(d==2)exit; next} d==1&&/^id:/{sub(/^id:[ \t]*/,""); gsub(/^["'"'"']|["'"'"']$/,""); print; exit}' "$f")"
-    [ -n "$id" ] || id="${b%.md}"
-    enf="$(awk '/^---/{d++; if(d==2)exit; next} d==1&&/^enforcement:/{sub(/^enforcement:[ \t]*/,""); print; exit}' "$f")"
-    src="$(awk '/^---/{d++; if(d==2)exit; next} d==1&&/^source:/{sub(/^source:[ \t]*/,""); gsub(/"/,""); print; exit}' "$f")"
-    ver="$(awk '/^---/{d++; if(d==2)exit; next} d==1&&/^version:/{sub(/^version:[ \t]*/,""); print; exit}' "$f")"
-    created="$(awk '/^---/{d++; if(d==2)exit; next} d==1&&/^created:/{sub(/^created:[ \t]*/,""); gsub(/"/,""); print substr($0,1,10); exit}' "$f")"
-    if [ -n "$created" ]; then ce="$(to_epoch "$created")"; else ce=0; fi
-    [ "$ce" -gt 0 ] || ce="$(stat -c %Y "$f" 2>/dev/null || stat -f %m "$f")"
-    age_days=$(( (NOW_EPOCH - ce) / 86400 ))
-    fired=0; last=""
-    row="$(awk -F'\t' -v s="$id" '$1==s{print; exit}' "$TMP/usage.tsv")"
-    if [ -n "$row" ]; then fired="$(cut -f2 <<<"$row")"; last_e="$(cut -f3 <<<"$row")"; last="$(date -u -d "@$last_e" +%Y-%m-%d 2>/dev/null || date -u -r "$last_e" +%Y-%m-%d)"; last_age=$(( (NOW_EPOCH - last_e) / 86400 )); else last_age=-1; fi
-    retrieved="$(awk -F'\t' -v s="$id" '$1==s{print $2; exit}' "$TMP/retrieved.tsv")"; retrieved="${retrieved:-0}"
-    # stale refs: backtick paths in the Rule section that look HQ-relative and are missing
-    stale=""; renamed=""
-    while IFS= read -r ref; do
-      [ -n "$ref" ] || continue
-      # Only release-owned or company-owned paths can make a rule inaccurate:
-      # core/, .claude/, companies/<slug>/ (when that company exists here).
-      # personal/, workspace/, repos/ are user- or environment-specific and are
-      # never judged. A ref whose top-level dir is absent is not judged either.
-      case "$ref" in
-        .claude/state/*|.claude/worktrees/*|core/packages/*) continue ;;   # runtime / install-specific
-        core/*|.claude/*) ;;
-        companies/*) co_ref="${ref#companies/}"; co_ref="${co_ref%%/*}"; [ -d "$HQ_ROOT/companies/$co_ref" ] || continue ;;
-        *) continue ;;
-      esac
-      # Placeholder examples in prose (`core/scripts/foo.sh`, `.claude/hooks/example.sh`) are not dependencies.
-      case "$(basename "$ref")" in foo*|bar*|baz*|example*|placeholder*|sample*|your-*|my-*|x.sh|dummy*) continue ;; esac
-      if [ ! -e "$HQ_ROOT/$ref" ]; then
-        # A sibling with the same stem (renamed extension: foo.sh -> foo.mjs) means
-        # the subject still exists and the rule needs a fix, not retirement.
-        stem="${ref%.*}"
-        if ls "$HQ_ROOT/$stem".* >/dev/null 2>&1; then renamed="${renamed:+$renamed,}$ref"; else stale="${stale:+$stale,}$ref"; fi
-      fi
-    done < <(awk '/^## Rule/{r=1;next} r&&/^## /{r=0} r' "$f" \
-      | grep -viE '(deleted|removed|retired|deprecated|no longer|not exist|never (call|use|run|read)|do not (call|use|run|read)|must not|instead of|was renamed|old path|legacy)' \
-      | grep -oE '`(core|personal|companies|repos|workspace|\.claude)/[A-Za-z0-9_./-]+`' | tr -d '`' | grep -vE '\{|\}|\*' | sort -u)
-    stale_n=0; [ -n "$stale" ] && stale_n="$(tr ',' '\n' <<<"$stale" | wc -l | tr -d ' ')"
-    judged_n="$(awk '/^## Rule/{r=1;next} r&&/^## /{r=0} r' "$f" | grep -viE '(deleted|removed|retired|deprecated|no longer|not exist|never (call|use|run|read)|do not (call|use|run|read)|must not|instead of|was renamed|old path|legacy)' | grep -oE '`(core|\.claude|companies)/[A-Za-z0-9_./-]+`' | tr -d '`' | grep -vE '\{|\}|\*|/(foo|bar|baz|example|placeholder|sample|your-|my-|dummy)|^\.claude/state/|^\.claude/worktrees/|^core/packages/' | sort -u | wc -l | tr -d ' ')"
-    single=0; case "$src" in user-correction|session-learning|back-pressure-failure) [ "${ver:-1}" = "1" ] && single=1 ;; esac
-    classes=""
-    if [ "$fired" = 0 ] && [ "$age_days" -ge "$MIN_AGE" ] && [ "$HAVE_LEDGERS" = 1 ]; then classes="never-fired"; fi
-    if [ "$fired" -gt 0 ] && [ "$last_age" -ge "$DORMANT" ]; then classes="${classes:+$classes,}dormant"; fi
-    if [ "$stale_n" -gt 0 ]; then classes="${classes:+$classes,}stale-refs"; fi
-    if [ -n "$renamed" ]; then classes="${classes:+$classes,}renamed-refs"; fi
-    # A one-off rule that keeps firing has earned its place; only flag it when it never (or once) fired.
-    if [ "$single" = 1 ] && [ "$age_days" -ge "$INCIDENT" ] && [ "$fired" -le 1 ]; then classes="${classes:+$classes,}single-incident-old"; fi
-    printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$id" "${f#"$HQ_ROOT"/}" "${enf:-unset}" "$age_days" "$fired" "${last:--}" "$stale_n" "$stale" "$single" "$classes" "$retrieved" "$judged_n" "$renamed"
-  done
-done > "$TMP/rows.tsv"
-
-if [ "$JSON" = 1 ]; then
-  jq -R -s -c --argjson cand "$CAND" '
-    split("\n") | map(select(length>0) | split("\t") | {id:.[0], path:.[1], enforcement:.[2], age_days:(.[3]|tonumber), fired:(.[4]|tonumber), last_fired:(if .[5]=="-" then null else .[5] end), stale_refs:(if .[7]=="" then [] else (.[7]|split(",")) end), single_incident:(.[8]=="1"), candidate_classes:(if .[9]=="" then [] else (.[9]|split(",")) end), retrieved:((.[10] // "0")|tonumber), refs_judged:((.[11] // "0")|tonumber), renamed_refs:(if (.[12] // "")=="" then [] else (.[12]|split(",")) end)})
-    | if $cand == 1 then map(select(.candidate_classes|length>0)) else . end' "$TMP/rows.tsv"
-  exit 0
-fi
-total="$(wc -l < "$TMP/rows.tsv" | tr -d ' ')"
-never="$(awk -F'\t' '$5==0' "$TMP/rows.tsv" | wc -l | tr -d ' ')"
-cands="$(awk -F'\t' '$10!=""' "$TMP/rows.tsv" | wc -l | tr -d ' ')"
-stale_total="$(awk -F'\t' '$7>0' "$TMP/rows.tsv" | wc -l | tr -d ' ')"
-echo "policy-age-report: $total policies, $never never fired, $stale_total with stale references, $cands retirement candidates (min-age ${MIN_AGE}d, dormant ${DORMANT}d, incident ${INCIDENT}d)"
-if [ "$CAND" = 1 ]; then
-  awk -F'\t' '$10!="" { printf "  %-14s %-60s fired=%-4s last=%-10s age=%-4sd %s%s\n", $10, $1, $5, $6, $4, ($7>0 ? "stale:" $8 : ""), "" }' "$TMP/rows.tsv" | sort
-else
-  echo "  (add --candidates to list them, --json for machine-readable rows)"
-fi
-exit 0

package/assets/scaffold/core/scripts/policy-retire.sh

@@ -1,199 +0,0 @@
-#!/usr/bin/env bash
-# hq-core: public
-# policy-retire.sh — retire (or restore) a policy without deleting it (2026-09-07).
-#
-# Why: nothing retired policies, so the corpus only grew. Retirement is a
-# frontmatter state, not a deletion: the file stays where it is (history,
-# grep-ability, restore), and every consumer skips `status: retired` — the
-# trigger loader, the company-bind digest, the age report.
-#
-# Usage:
-#   policy-retire.sh <slug-or-path> --reason "<why>" [--by <who>]
-#   policy-retire.sh <slug-or-path> --restore
-#   policy-retire.sh --from-report <age-report.json> --class <never-fired|dormant|stale-refs|single-incident-old> --reason "<why>" [--yes]
-#   policy-retire.sh --auto [--dir <policies-dir>]... [--classes a,b] [--report-dir <dir>] [--dry-run]
-#
-# --auto is the human-ON-the-loop mode (2026-09-07): it runs the age report,
-# retires every candidate with a per-policy reason, and writes a dated report
-# (default workspace/reports/policy-retirement-<date>.md) so a wrong call can
-# be found and reversed with --restore. Nobody approves in advance. Classes and
-# reasons:
-#   never-fired          never emitted in any session ledger, older than 30 days
-#   dormant              last emitted more than 90 days ago
-#   stale-refs           its Rule text points at HQ paths that no longer exist
-#   single-incident-old  a one-off correction, older than 60 days, fired at most once
-# Defaults to personal/policies plus the bound company's policies; core/ is
-# release-owned and is retired only in the hq-core-staging tree.
-#
-# <slug-or-path>: a policy file path, or a slug looked up under personal/policies,
-# core/policies, and companies/*/policies (first match). Symlinked overlay
-# mirrors are resolved to their source file.
-# --from-report: batch mode over `policy-age-report.sh --json --candidates`
-# output; lists what would change and requires --yes to write.
-set -uo pipefail
-HQ_ROOT="${HQ_ROOT:-${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}}"
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-VALIDATOR_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-POLICY_VALIDATOR="$VALIDATOR_ROOT/.claude/hooks/validate-policy-frontmatter.sh"
-TARGET=""; REASON=""; BY="${HQ_SESSION_ID:-${USER:-unknown}}"; RESTORE=0; REPORT=""; CLASS=""; YES=0
-AUTO=0; DRY=0; AUTO_DIRS=(); REPORT_DIR=""; CLASSES=""
-while [ $# -gt 0 ]; do
-  case "$1" in
-    --auto) AUTO=1; shift ;;
-    --dry-run) DRY=1; shift ;;
-    --dir) AUTO_DIRS+=("$2"); shift 2 ;;
-    --report-dir) REPORT_DIR="$2"; shift 2 ;;
-    --classes) CLASSES="$2"; shift 2 ;;   # comma list; default: all classes
-    --reason) REASON="$2"; shift 2 ;;
-    --by) BY="$2"; shift 2 ;;
-    --restore) RESTORE=1; shift ;;
-    --from-report) REPORT="$2"; shift 2 ;;
-    --class) CLASS="$2"; shift 2 ;;
-    --yes) YES=1; shift ;;
-    -h|--help) sed -n 2,22p "$0"; exit 0 ;;
-    -*) echo "policy-retire: unknown arg $1" >&2; exit 2 ;;
-    *) TARGET="$1"; shift ;;
-  esac
-done
-resolve() { # slug-or-path -> real file path or empty
-  local t="$1" f
-  if [ -f "$t" ]; then f="$t"
-  else
-    for d in "$HQ_ROOT/personal/policies" "$HQ_ROOT/core/policies" "$HQ_ROOT"/companies/*/policies; do
-      [ -f "$d/$t.md" ] && { f="$d/$t.md"; break; }
-      [ -f "$d/$t" ] && { f="$d/$t"; break; }
-    done
-  fi
-  [ -n "${f:-}" ] || return 1
-  [ -L "$f" ] && f="$(cd "$(dirname "$f")" && realpath "$(readlink "$f")" 2>/dev/null || readlink "$f")"
-  printf '%s' "$f"
-}
-validate_policy_before_write() { # <policy-file>
-  # Do not replicate frontmatter extraction here. The authoring hook validates
-  # every resulting `when:` key (including duplicates), hard-policy limits,
-  # and the canonical trigger grammar. A retirement write must meet that exact
-  # contract or a sanctioned route could modify a policy normal authoring
-  # rejects.
-  local f="$1" payload result
-  [ -f "$POLICY_VALIDATOR" ] || { echo "policy-retire: missing policy validator: $POLICY_VALIDATOR" >&2; return 1; }
-  command -v jq >/dev/null 2>&1 || { echo "policy-retire: jq is required for canonical policy validation" >&2; return 1; }
-  payload="$(jq -nc --arg file "$f" --rawfile content "$f" '{tool_input:{file_path:$file,content:$content}}')" \
-    || { echo "policy-retire: could not prepare policy validation input for $f" >&2; return 1; }
-  result="$(HQ_ROOT="$VALIDATOR_ROOT" CLAUDE_PROJECT_DIR="$VALIDATOR_ROOT" HQ_ALLOW_POLICY_NO_TRIGGER= \
-    bash "$POLICY_VALIDATOR" <<<"$payload" 2>&1)" || {
-      printf 'policy-retire: refusing to write %s; canonical policy validation failed:\n%s\n' "$f" "$result" >&2
-      return 1
-    }
-}
-set_status() { # <file> <retired|active> <reason>
-  local f="$1" st="$2" why="$3" now; now="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-  head -1 "$f" | grep -q '^---' || { echo "policy-retire: $f has no frontmatter" >&2; return 1; }
-  validate_policy_before_write "$f" || return 1
-  awk -v st="$st" -v why="$why" -v by="$BY" -v now="$now" '
-    BEGIN { d=0; done=0 }
-    /^---[ \t]*$/ { d++; if (d==2 && !done) {
-        if (st=="retired") { print "status: retired"; print "retired_at: " now; print "retired_by: " by; print "retired_reason: \"" why "\"" }
-        done=1 }
-      print; next }
-    d==1 && /^(status|retired_at|retired_by|retired_reason):/ { next }
-    { print }' "$f" > "$f.tmp" && mv "$f.tmp" "$f"
-}
-if [ "$AUTO" = 1 ]; then
-  AGE="$HQ_ROOT/core/scripts/policy-age-report.sh"; [ -x "$AGE" ] || AGE="$(dirname "${BASH_SOURCE[0]}")/policy-age-report.sh"
-  if [ "${#AUTO_DIRS[@]}" -eq 0 ]; then
-    AUTO_DIRS=("$HQ_ROOT/personal/policies")
-    co="$(bash "$HQ_ROOT/core/scripts/hq-session.sh" get company_slug 2>/dev/null || true)"
-    [ -n "$co" ] && [ "$co" != "personal" ] && [ -d "$HQ_ROOT/companies/$co/policies" ] && AUTO_DIRS+=("$HQ_ROOT/companies/$co/policies")
-  fi
-  dirargs=(); for d in "${AUTO_DIRS[@]}"; do dirargs+=(--dir "$d"); done
-  json="$(HQ_ROOT="$HQ_ROOT" bash "$AGE" "${dirargs[@]}" --json --candidates 2>/dev/null)" || json="[]"
-  n="$(jq 'length' <<<"$json")"
-  today="$(date -u +%Y-%m-%d)"; [ -n "$REPORT_DIR" ] || REPORT_DIR="$HQ_ROOT/workspace/reports"
-  out="$REPORT_DIR/policy-retirement-$today.md"; mkdir -p "$REPORT_DIR"
-  # One file per day; each run appends its own section so nothing is overwritten.
-  : > "$out.tmp"
-  if [ ! -f "$out" ]; then
-    {
-      echo "# Automatic policy retirement — $today"; echo
-      echo "Mode: human on the loop. Each policy below was retired by \`policy-retire.sh --auto\` with the reason shown."
-      echo "Reverse any wrong call with \`bash core/scripts/policy-retire.sh <slug> --restore\` and fix the rule that produced it."
-      echo
-    } > "$out.tmp"
-  fi
-  { echo "## Run $(date -u +%H:%M:%SZ) — dirs: ${AUTO_DIRS[*]}"; echo; } >> "$out.tmp"
-  retired=0; failed=0; needfix=0; would_retire=0
-  while IFS=$'	' read -r id path classes fired last age stale judged stale_n renamed; do
-    [ -n "$path" ] || continue
-    f="$HQ_ROOT/$path"; [ -f "$f" ] || f="$path"; [ -f "$f" ] || continue
-    grep -q '^status: retired' "$f" && continue
-    if [ -n "$CLASSES" ]; then
-      keep=""; for c in $(tr ',' ' ' <<<"$classes"); do case ",$CLASSES," in *,$c,*) keep="${keep:+$keep,}$c" ;; esac; done
-      classes="$keep"; [ -n "$classes" ] || continue
-    fi
-    why=""
-    # stale-refs retires only when EVERY judged reference is gone — the rule's
-    # whole subject vanished. A partly stale rule is reported for a fix, not retired.
-    case ",$classes," in *,renamed-refs,*) printf -- '- needs-fix (not retired) **%s** (%s): referenced file was renamed: %s\n' "$id" "$path" "$renamed" >> "$out.tmp"; needfix=$((needfix+1)) ;; esac
-    case ",$classes," in *,stale-refs,*)
-      if [ "${judged:-0}" -gt 0 ] && [ "${stale_n:-0}" -eq "${judged:-0}" ]; then why="every path the rule depends on is gone ($stale)"
-      else printf -- '- needs-fix (not retired) **%s** (%s): references gone: %s\n' "$id" "$path" "$stale" >> "$out.tmp"; needfix=$((needfix+1)); fi ;;
-    esac
-    case ",$classes," in *,never-fired,*) why="${why:+$why; }never emitted in any session ledger over ${age} days" ;; esac
-    case ",$classes," in *,dormant,*) why="${why:+$why; }last emitted $last, more than the dormant window ago" ;; esac
-    case ",$classes," in *,single-incident-old,*) why="${why:+$why; }one-off correction, ${age} days old, fired ${fired}x" ;; esac
-    [ -n "$why" ] || continue
-    if [ "$DRY" = 1 ]; then
-      echo "would retire: $id — $why"
-      would_retire=$((would_retire+1))
-      continue
-    fi
-    if set_status "$f" retired "auto: $why"; then
-      echo "retired: $id — $why"
-      printf -- '- **%s** (%s): %s\n' "$id" "$path" "$why" >> "$out.tmp"
-      retired=$((retired+1))
-    else
-      echo "failed: $id ($path); policy was not retired" >&2
-      printf -- '- failed (not retired) **%s** (%s): canonical policy validation failed\n' "$id" "$path" >> "$out.tmp"
-      failed=$((failed+1))
-    fi
-  done < <(jq -r '.[] | [.id, .path, (.candidate_classes|join(",")), (.fired|tostring), (.last_fired // "never"), (.age_days|tostring), (.stale_refs|join(", ")), ((.refs_judged // 0)|tostring), ((.stale_refs|length)|tostring), ((.renamed_refs // [])|join(", "))] | @tsv' <<<"$json")
-  if [ "$DRY" = 1 ]; then rm -f "$out.tmp"; echo "policy-retire --auto: $would_retire of $n candidates would be retired (dry run)"
-  else
-    if [ "$retired" -gt 0 ] || [ "$failed" -gt 0 ] || [ "$needfix" -gt 0 ]; then cat "$out.tmp" >> "$out"; rm -f "$out.tmp"; echo "policy-retire --auto: $retired retired, $failed failed, $needfix need a fix; report ${out#"$HQ_ROOT"/}"; else rm -f "$out.tmp"; echo "policy-retire --auto: nothing to retire"; fi
-  fi
-  [ "$failed" -eq 0 ] || exit 1
-  exit 0
-fi
-if [ -n "$REPORT" ]; then
-  [ -n "$CLASS" ] && [ -n "$REASON" ] || { echo "--from-report needs --class and --reason" >&2; exit 2; }
-  [ -r "$REPORT" ] || { echo "cannot read $REPORT" >&2; exit 2; }
-  retired=0; failed=0; selected=0
-  while IFS=$'\t' read -r id path; do
-    [ -n "$path" ] || continue
-    f="$HQ_ROOT/$path"; [ -f "$f" ] || continue
-    grep -q '^status: retired' "$f" && continue
-    selected=$((selected+1))
-    if [ "$YES" = 1 ]; then
-      if set_status "$f" retired "$REASON [$CLASS]"; then
-        retired=$((retired+1)); echo "retired: $id ($path)"
-      else
-        failed=$((failed+1)); echo "failed: $id ($path); policy was not retired" >&2
-      fi
-    else echo "would retire: $id ($path)"; fi
-  done < <(jq -r --arg c "$CLASS" '.[] | select(.candidate_classes | index($c)) | "\(.id)\t\(.path)"' "$REPORT")
-  if [ "$YES" = 1 ]; then
-    echo "policy-retire: $retired retired [$CLASS]; $failed failed"
-    [ "$failed" -eq 0 ] || exit 1
-  else
-    echo "policy-retire: $selected would be retired [$CLASS] (add --yes)"
-  fi
-  exit 0
-fi
-[ -n "$TARGET" ] || { sed -n 2,22p "$0"; exit 2; }
-F="$(resolve "$TARGET")" || { echo "policy-retire: no policy found for '$TARGET'" >&2; exit 3; }
-if [ "$RESTORE" = 1 ]; then
-  set_status "$F" active "" && echo "policy-retire: restored ${F#"$HQ_ROOT"/}"
-else
-  [ -n "$REASON" ] || { echo "policy-retire: --reason is required" >&2; exit 2; }
-  set_status "$F" retired "$REASON" && echo "policy-retire: retired ${F#"$HQ_ROOT"/} — $REASON"
-fi

package/assets/scaffold/core/scripts/qmd-reindex-bg.sh

@@ -1,40 +0,0 @@
-#!/usr/bin/env bash
-# FORWARDER — the implementation of this script now lives in the hq CLI.
-#
-# It runs as `hq index background`. This file stays behind so every existing
-# caller — skills, other scripts, CI, and muscle memory — keeps working against
-# the path it already knows.
-#
-# Why the implementation moved: the single-flight background reindex is a
-# durable state machine (lock ownership, stale reclaim, completion stamps,
-# signal cleanup) that belongs in tested code rather than 700 lines of shell.
-#
-# Equivalence is not assumed. hq-cli's e2e/qmd-background-differential.test.ts
-# runs a byte-frozen copy of this script's pre-migration source against the CLI
-# over identical injected worlds and compares exit status, stdout, the qmd argv
-# sequence, and the resulting lock/stamp state: agent short-circuit before any
-# qmd lookup or lock, empty-HOME silence, cleanup->update->embed ordering with a
-# completion stamp, no stamp after a failed update, and no competing writer
-# behind a held lock.
-#
-# ONE INTENDED DIVERGENCE: this script printed "skipped" when no qmd was on
-# PATH. The CLI bundles qmd (@tobilu/qmd is a dependency, resolved via
-# node_modules/.bin since hq-cli 5.94.1), so it proceeds instead of skipping.
-# That is the point of bundling; see hq-cli#333.
-#
-# The ABI is otherwise preserved: arguments are forwarded unchanged, stdin is
-# never read by this file, stdout and stderr are inherited untouched, and the
-# child replaces this process so its exit code and signal disposition become the
-# caller's.
-
-set -euo pipefail
-
-HQ_ROOT="${HQ_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
-
-if ! command -v hq >/dev/null 2>&1; then
-  echo "qmd-reindex-bg.sh: requires the hq CLI — this script's implementation now ships with it." >&2
-  echo "Install it with: npm install -g @indigoai-us/hq-cli" >&2
-  exit 127
-fi
-
-exec hq index background --hq-root "$HQ_ROOT" "$@"

package/assets/scaffold/core/scripts/read-policy-frontmatter.sh

@@ -1,32 +0,0 @@
-#!/bin/bash
-# read-policy-frontmatter.sh — Extract YAML frontmatter from a policy file
-#
-# Usage: bash core/scripts/read-policy-frontmatter.sh <policy-file>
-#
-# Returns only the YAML frontmatter block (between the first two --- markers),
-# skipping the policy body. Used by /startwork, /plan, /brainstorm, /run commands
-# to minimize context burn when scanning policy metadata (id, title, enforcement,
-# when) without loading the full ## Rule and ## Rationale sections.
-# (Fields id/title/enforcement/when/on live in that block.)
-#
-# Exit codes:
-#   0 - Success, frontmatter written to stdout
-#   1 - Usage error or file not readable
-
-set -euo pipefail
-
-if [ $# -lt 1 ]; then
-  echo "USAGE: read-policy-frontmatter.sh <policy-file>" >&2
-  exit 1
-fi
-
-FILE="$1"
-
-if [ ! -r "$FILE" ]; then
-  echo "ERROR: File not readable: $FILE" >&2
-  exit 1
-fi
-
-# Extract frontmatter: lines between first two --- markers.
-# c counts --- markers; print lines only while inside the frontmatter (c==1).
-awk '/^---$/{c++; next} c==1' "$FILE"

package/assets/scaffold/core/scripts/refresh-vault-access.sh

@@ -1,188 +0,0 @@
-#!/usr/bin/env bash
-# hq-core: public
-# refresh-vault-access.sh — build/refresh the local vault-access manifest that
-# enforce-vault-write-access.sh (PreToolUse hook) reads.
-#
-# Output: <hqRoot>/.hq/vault-access.json
-#
-#   {
-#     "version": 1,
-#     "generatedAt": "2026-01-01T00:00:00Z",
-#     "companies": {
-#       "<slug>": {
-#         "role": "owner|admin|member|guest|unknown",
-#         "grants": [ { "path": "reports/*", "permission": "read|write" } ]
-#       }
-#     }
-#   }
-#
-# Sources (best-effort, all via the hq CLI):
-#   - grants: `hq files shared-with-me` (explicit per-prefix grants)
-#   - role:   `hq members --company <slug> list` matched against the caller's
-#             email (from `hq whoami`, override with HQ_VAULT_ACCESS_EMAIL)
-#
-# Fail-open by design: anything this script cannot determine is recorded as
-# role "unknown" (the hook does not enforce unknown roles), and a company it
-# cannot query at all is left out of the manifest entirely (the hook allows
-# companies absent from the manifest). The server-side STS/ACL layer remains
-# the authoritative security boundary — this manifest only powers the local
-# early-warning block for read-only shares.
-#
-# Usage:
-#   bash core/scripts/refresh-vault-access.sh [--company <slug>]... [--root <hqRoot>]
-#
-# With no --company, refreshes every company that appears in the
-# `hq files shared-with-me` cross-company roll-up.
-
-set -uo pipefail
-
-log() { printf 'refresh-vault-access: %s\n' "$*" >&2; }
-
-ROOT=""
-SLUGS=()
-while [ $# -gt 0 ]; do
-  case "$1" in
-    --root)
-      ROOT="${2:-}"
-      shift 2 || { log "--root requires a value"; exit 1; }
-      ;;
-    --company)
-      SLUGS[${#SLUGS[@]}]="${2:-}"
-      shift 2 || { log "--company requires a value"; exit 1; }
-      ;;
-    -h|--help)
-      sed -n '2,33p' "$0" | sed 's/^# \{0,1\}//'
-      exit 0
-      ;;
-    *)
-      log "unknown argument: $1"
-      exit 1
-      ;;
-  esac
-done
-
-is_hq_root() { [ -n "${1:-}" ] && [ -d "${1%/}/core" ] && [ -d "${1%/}/.claude" ]; }
-
-if [ -z "$ROOT" ]; then
-  if is_hq_root "${CLAUDE_PROJECT_DIR:-}"; then
-    ROOT="$CLAUDE_PROJECT_DIR"
-  else
-    dir="$PWD"
-    while [ -n "$dir" ] && [ "$dir" != "/" ]; do
-      if is_hq_root "$dir"; then ROOT="$dir"; break; fi
-      dir="$(dirname "$dir")"
-    done
-  fi
-fi
-if ! is_hq_root "$ROOT"; then
-  log "could not resolve the HQ root (pass --root <hqRoot>)"
-  exit 1
-fi
-
-command -v jq >/dev/null 2>&1 || { log "jq is required"; exit 1; }
-if ! command -v hq >/dev/null 2>&1; then
-  log "hq CLI not found — nothing refreshed (the write-access hook stays fail-open without a manifest)"
-  exit 0
-fi
-
-strip_ansi() { sed -e 's/\x1b\[[0-9;]*m//g'; }
-
-# ── caller email (for role lookup) ─────────────────────────────────────────
-EMAIL="${HQ_VAULT_ACCESS_EMAIL:-}"
-if [ -z "$EMAIL" ]; then
-  EMAIL="$(hq whoami 2>/dev/null | strip_ansi \
-    | grep -Eo '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}' \
-    | grep -v '@outposts\.' | head -1 || true)"
-fi
-[ -n "$EMAIL" ] || log "could not determine caller email — roles will be 'unknown' (hook will not enforce)"
-
-# ── explicit grants via shared-with-me ─────────────────────────────────────
-# Table columns: COMPANY  PATH  PERMISSION  SOURCE (header + ─── separator).
-fetch_grants_tsv() {
-  # $1 = optional slug filter; prints "slug<TAB>path<TAB>permission" rows.
-  local slug="${1:-}" out
-  if [ -n "$slug" ]; then
-    out="$(hq files shared-with-me --company "$slug" 2>/dev/null | strip_ansi)" || return 1
-  else
-    out="$(hq files shared-with-me 2>/dev/null | strip_ansi)" || return 1
-  fi
-  # hq-cli >= 5.142 renders a private-folder row as "foo/ (private folder)";
-  # drop the label so the PATH column stays the verbatim `foo/` pattern.
-  printf '%s\n' "$out" | awk '
-    { sub(/ \(private folder\)/, "") }
-    /^COMPANY[[:space:]]/ { next }
-    /^─/ { next }
-    /^[[:space:]]*$/ { next }
-    /^Nothing is explicitly shared/ { next }
-    NF >= 3 {
-      perm = ""
-      if ($3 == "read" || $3 == "write" || $3 == "admin") perm = $3
-      else if (NF >= 4 && ($4 == "read" || $4 == "write" || $4 == "admin")) perm = $4
-      if (perm != "") printf "%s\t%s\t%s\n", $1, $2, perm
-    }'
-}
-
-# ── role lookup ────────────────────────────────────────────────────────────
-fetch_role() {
-  # $1 = slug; prints role or "unknown". Never fails.
-  local slug="$1" out role=""
-  if [ -n "$EMAIL" ]; then
-    # --company is declared on the parent `members` group, so it goes first.
-    out="$(hq members --company "$slug" list 2>/dev/null | strip_ansi)" || out=""
-    if [ -n "$out" ]; then
-      role="$(printf '%s\n' "$out" | awk -v email="$EMAIL" '$1 == email { print $2; exit }')"
-    fi
-  fi
-  case "$role" in
-    owner|admin|member|guest) printf '%s' "$role" ;;
-    *) printf 'unknown' ;;
-  esac
-}
-
-GRANTS_TSV=""
-if [ "${#SLUGS[@]}" -gt 0 ]; then
-  for slug in "${SLUGS[@]}"; do
-    rows="$(fetch_grants_tsv "$slug")" || { log "skipping $slug — shared-with-me query failed"; continue; }
-    GRANTS_TSV="${GRANTS_TSV}${rows}
-"
-  done
-else
-  GRANTS_TSV="$(fetch_grants_tsv)" || { log "shared-with-me roll-up failed — nothing refreshed"; exit 0; }
-fi
-
-# Companies to include = every slug present in the grant rows (plus any
-# explicitly requested slugs, so a company with zero explicit grants still
-# gets a role entry when asked for by name).
-ALL_SLUGS="$(printf '%s\n' "$GRANTS_TSV" | awk -F'\t' 'NF { print $1 }' | sort -u)"
-if [ "${#SLUGS[@]}" -gt 0 ]; then
-  ALL_SLUGS="$(printf '%s\n%s\n' "$ALL_SLUGS" "$(printf '%s\n' "${SLUGS[@]}")" | awk 'NF' | sort -u)"
-fi
-
-if [ -z "$ALL_SLUGS" ]; then
-  log "no explicit grants found — writing an empty manifest (hook stays fail-open everywhere)"
-fi
-
-COMPANIES_JSON="{}"
-while IFS= read -r slug; do
-  [ -n "$slug" ] || continue
-  role="$(fetch_role "$slug")"
-  grants_json="$(printf '%s\n' "$GRANTS_TSV" \
-    | awk -F'\t' -v s="$slug" '$1 == s { printf "%s\t%s\n", $2, $3 }' \
-    | jq -Rn '[inputs | split("\t") | select(length == 2) | {path: .[0], permission: .[1]}]')"
-  COMPANIES_JSON="$(printf '%s' "$COMPANIES_JSON" \
-    | jq --arg slug "$slug" --arg role "$role" --argjson grants "$grants_json" \
-        '. + {($slug): {role: $role, grants: $grants}}')"
-done <<EOF
-$ALL_SLUGS
-EOF
-
-mkdir -p "$ROOT/.hq"
-TMP_OUT="$(mktemp "$ROOT/.hq/vault-access.json.XXXXXX")"
-jq -n --argjson companies "$COMPANIES_JSON" \
-  --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-  '{version: 1, generatedAt: $ts, companies: $companies}' > "$TMP_OUT"
-mv "$TMP_OUT" "$ROOT/.hq/vault-access.json"
-
-N_COMPANIES="$(printf '%s\n' "$ALL_SLUGS" | awk 'NF' | wc -l | tr -d ' ')"
-log "wrote .hq/vault-access.json ($N_COMPANIES companies, identity: ${EMAIL:-unknown})"
-exit 0