@indigoai-us/hq-cli 5.314.0 → 5.316.0

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

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

@@ -0,0 +1,199 @@
+#!/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-after-sync.sh

@@ -1,93 +1,16 @@
 #!/usr/bin/env bash
-# qmd-reindex-after-sync.sh — incremental qmd reindex after an HQ sync.
+# FORWARDER — the implementation of this script lives in the hq CLI.
 #
-# Why this exists: the qmd index is a per-machine local SQLite store derived
-# from local folder paths. Nothing re-indexed it after `hq-sync` pulled new
-# files in, so search results diverged between teammates depending on who ran
-# `qmd update` most recently. This script makes post-sync indexing automatic
-# and deterministic, so every machine's personal index converges to the same
-# content. The index itself stays personal (it is large, binary, and embeds
-# absolute local paths); only the *freshness* is made automatic.
-#
-# Behavior:
-#   1. Auto-registers any company knowledge dir that isn't yet a qmd
-#      collection (fixes the "newly-synced knowledge isn't searchable until I
-#      manually map it" gap).
-#   2. Runs an incremental lexical reindex (`qmd update` — fast, skips
-#      unchanged files by mtime).
-#   3. Rebuilds embeddings only when called with --embed (slow on a
-#      multi-GB index; meant for an idle/interval pass, not every sync).
-#
-# Idempotent and safe: no-op (exit 0) when qmd is absent or the path isn't an
-# HQ root. Never blocks or fails a sync.
-#
-# Usage: qmd-reindex-after-sync.sh [hq_root] [--embed]
-#   hq_root  Local HQ directory (default: $PWD). Must contain core/core.yaml.
-#   --embed  Also rebuild embeddings (deferred-cost; omit for fast lexical-only).
-
-set -uo pipefail
-
-hq_root=""
-embed=0
-for arg in "$@"; do
-  case "$arg" in
-    --embed) embed=1 ;;
-    --*)     : ;;                       # ignore unknown flags
-    *)       [ -z "$hq_root" ] && hq_root="$arg" ;;
-  esac
-done
-[ -z "$hq_root" ] && hq_root="$PWD"
-
-command -v qmd >/dev/null 2>&1 || exit 0
-[ -f "$hq_root/core/core.yaml" ] || exit 0
-
-cd "$hq_root" || exit 0
-
-# 1. Auto-register company knowledge collections that don't exist yet.
-#    Convention matches /newcompany: --name <slug> --mask "**/*.md".
-existing="$(qmd collection list 2>/dev/null || true)"
-for kdir in companies/*/knowledge; do
-  [ -d "$kdir" ] || continue
-  [ -n "$(find "$kdir" -name '*.md' -not -name 'INDEX.md' -print -quit 2>/dev/null)" ] || continue
-  slug="$(basename "$(dirname "$kdir")")"
-  printf '%s\n' "$existing" | grep -Fq "qmd://$slug/" && continue
-  qmd collection add "$hq_root/$kdir" --name "$slug" --mask "**/*.md" >/dev/null 2>&1 || true
-  qmd context add "qmd://$slug" "Knowledge base for $slug." >/dev/null 2>&1 || true
-done
-
-# 1b. Auto-register company *projects* collections that don't exist yet.
-#    Convention matches the HQ-level `hq-projects` collection: --name <slug>-projects
-#    --mask "**/*.{md,json}" (so prd.json + project docs are searchable). Without
-#    this, company projects/ dirs are indexed by nothing and /startwork's global
-#    `qmd search "prd.json"` and /brainstorm's project discovery silently miss them.
-for pdir in companies/*/projects; do
-  [ -d "$pdir" ] || continue
-  [ -n "$(find "$pdir" -type f \( -name '*.md' -o -name '*.json' \) -print -quit 2>/dev/null)" ] || continue
-  slug="$(basename "$(dirname "$pdir")")"
-  name="${slug}-projects"
-  printf '%s\n' "$existing" | grep -Fq "qmd://$name/" && continue
-  qmd collection add "$hq_root/$pdir" --name "$name" --mask "**/*.{md,json}" >/dev/null 2>&1 || true
-  qmd context add "qmd://$name" "Project PRDs and documentation for $slug." >/dev/null 2>&1 || true
-done
-
-# 1c. Auto-register the personal knowledge collection if it isn't one yet.
-#     personal/knowledge is now read DIRECTLY (the reindex symlink mirror into
-#     core/knowledge is retired), so it needs its own qmd collection to stay
-#     searchable rather than riding in under a core collection.
-if [ -d "personal/knowledge" ] && \
-   [ -n "$(find "personal/knowledge" -name '*.md' -not -name 'INDEX.md' -print -quit 2>/dev/null)" ]; then
-  printf '%s\n' "$existing" | grep -Fq "qmd://personal-knowledge/" || {
-    qmd collection add "$hq_root/personal/knowledge" --name "personal-knowledge" --mask "**/*.md" >/dev/null 2>&1 || true
-    qmd context add "qmd://personal-knowledge" "Personal knowledge base (owner overlay)." >/dev/null 2>&1 || true
-  }
-fi
+# This shipped compatibility path must delegate rather than invoke qmd itself:
+# `hq core qmd-reindex-after-sync` participates in hq-cli's shared embed lock.
+# Arguments, stdio, exit status, and signal disposition are preserved.
 
-# 2. Incremental lexical reindex (cheap; mtime-incremental inside qmd).
-qmd update >/dev/null 2>&1 || true
+set -euo pipefail
 
-# 3. Embeddings only on explicit request.
-if [ "$embed" -eq 1 ]; then
-  qmd embed >/dev/null 2>&1 || true
+if ! command -v hq >/dev/null 2>&1; then
+  echo "qmd-reindex-after-sync.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
 
-exit 0
+exec hq core qmd-reindex-after-sync "$@"

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

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

@@ -0,0 +1,32 @@
+#!/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/rebuild-company-knowledge-index.sh

@@ -8,7 +8,7 @@
 #   - .md files → first `#` heading (stripped)
 #   - .yaml files → `description:` field if present
 #   - .json files → `description` field if present
-#   - directories → "{N} item(s)"
+#   - directories → README.md `#` heading plus "{N} item(s)", or "{N} item(s)"
 #
 # Most company knowledge dirs are embedded git repos (160000 gitlinks). The
 # generated INDEX.md lives inside the inner repo; HQ git won't track its
@@ -42,7 +42,15 @@ describe_item() {
   if [[ -d "$path" ]]; then
     local n
     n=$(find "$path" -mindepth 1 -maxdepth 1 ! -name '.*' 2>/dev/null | wc -l | tr -d ' ')
-    echo "${n} item(s)"
+    local h=""
+    if [[ -f "$path/README.md" ]]; then
+      h=$(awk '/^# / { sub(/^# +/, ""); print; exit }' "$path/README.md" 2>/dev/null || true)
+    fi
+    if [[ -n "$h" ]]; then
+      echo "${h} (${n} item(s))"
+    else
+      echo "${n} item(s)"
+    fi
     return
   fi
   case "$name" in
@@ -70,6 +78,26 @@ describe_item() {
   esac
 }
 
+sha256_file() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$1" | awk '{print $1}'
+  else
+    shasum -a 256 "$1" | awk '{print $1}'
+  fi
+}
+
+stamp_generated() {
+  local tmp="$1"
+  local out="$2"
+  local norm
+  norm=$(mktemp)
+  sed 's/^> Auto-generated. Updated: [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]$/> Auto-generated. Updated: <date>/' "$tmp" > "$norm"
+  local hash
+  hash=$(sha256_file "$norm")
+  rm -f "$norm"
+  awk -v h="$hash" '{print} /^> Auto-generated. Updated: / {print "<!-- hq-generated-sha256: " h " -->"}' "$tmp" > "$out"
+}
+
 write_knowledge_index() {
   local co="$1"
   local kdir="companies/${co}/knowledge"
@@ -77,6 +105,8 @@ write_knowledge_index() {
   local out="${kdir}/INDEX.md"
   local title
   title="$(titleize "$co") Knowledge"
+  local tmp
+  tmp=$(mktemp)
 
   {
     echo "# ${title}"
@@ -108,7 +138,10 @@ write_knowledge_index() {
         find -L "$kdir" -mindepth 1 -maxdepth 1 -type f 2>/dev/null | sort
       }
     )
-  } > "$out"
+  } > "$tmp"
+
+  stamp_generated "$tmp" "$out"
+  rm -f "$tmp"
 
   echo "rebuild-company-knowledge-index: wrote ${out}" >&2
 }