@indigoai-us/hq-cli 5.282.0 → 5.283.0

package/assets/scaffold/core/scripts/eval-trigger.sh

@@ -0,0 +1,193 @@
+#!/bin/bash
+# eval-trigger.sh — evaluate a policy `when:` boolean expression against a fact set.
+#
+# Usage:
+#   eval-trigger.sh "<expr>" "<space-separated facts>"
+#   eval-trigger.sh --check < "<id>\t<expr>" lines   → "<id>\tok|malformed"
+#
+# Expression grammar (tiny boolean algebra over open identifiers):
+#   expr   := or
+#   or     := and ( '||' and )*
+#   and    := not ( '&&' not )*
+#   not    := '!' not | atom
+#   atom   := '(' or ')' | identifier
+#   identifier := [A-Za-z0-9_./][A-Za-z0-9_./-]*
+#                 Letters, digits, _ . / - . May start with `.` or `/`, so a
+#                 filename (`.mcp.json`, `settings.json`) or a slash-command
+#                 (`/brainstorm`) is a single literal token. Operators
+#                 (`&& || ! ( )`) and whitespace are the only delimiters.
+#
+# Tokens are OPEN — no vocabulary. Identifiers are compared with the fact set
+# case-insensitively; absent or misspelled identifiers are FALSE.
+#
+# Exit codes:
+#   0 — expression is TRUE  given the facts
+#   1 — expression is FALSE given the facts
+#   2 — expression is empty / malformed / unsafe  → caller should FAIL OPEN
+#
+# Safety: each identifier is substituted with 1/0 by fact membership, then the
+# result must contain ONLY `0 1 & | ! ( )` and spaces. Anything else (quotes,
+# backticks, `$`, letters left over, etc.) yields exit 2 — the expression is
+# never eval'd by a shell, only by awk's own boolean operators. Dots, slashes,
+# and dashes are part of the identifier charset, so they are consumed by the
+# substitution and never survive to the gate; quotes/backticks/$ still do, and
+# still fail open.
+
+set -euo pipefail
+
+# --check: batch SYNTAX mode. Reads `<id><TAB><expr>` lines on stdin and prints
+# `<id><TAB>ok` or `<id><TAB>malformed`, one line per input. Validity does not
+# depend on the fact set — every identifier substitutes to 0 — so this is the
+# same parse the single-expression mode runs, just without a process per
+# expression. Callers linting a whole tree use this; there is deliberately no
+# second implementation of the grammar to drift from.
+if [ "${1-}" = "--check" ]; then
+  awk -F'\t' '
+    function skip() { while (substr(E, pos, 1) ~ /[ \t]/) pos++ }
+    function parseOr(  v) {
+      v = parseAnd(); skip()
+      while (valid && substr(E, pos, 2) == "||") {
+        pos += 2
+        rhs = parseAnd()
+        v = (v || rhs)
+        skip()
+      }
+      return v
+    }
+    function parseAnd(  v) {
+      v = parseNot(); skip()
+      while (valid && substr(E, pos, 2) == "&&") {
+        pos += 2
+        rhs = parseNot()
+        v = (v && rhs)
+        skip()
+      }
+      return v
+    }
+    function parseNot(  c) {
+      skip(); c = substr(E, pos, 1)
+      if (c == "!") { pos++; return (parseNot() ? 0 : 1) }
+      return parseAtom()
+    }
+    function parseAtom(  v, c) {
+      skip(); c = substr(E, pos, 1)
+      if (c == "(") {
+        pos++; v = parseOr(); skip()
+        if (substr(E, pos, 1) != ")") { valid = 0; return 0 }
+        pos++; return v
+      }
+      if (c == "0" || c == "1") { pos++; return (c == "1") ? 1 : 0 }
+      valid = 0; return 0
+    }
+    function check(expr,   e, s, out, tok) {
+      e = expr; gsub(/[ \t]/, "", e)
+      if (e == "") return 0
+      s = expr; out = ""
+      while (match(s, "[A-Za-z0-9_./][A-Za-z0-9_./-]*")) {
+        tok = substr(s, RSTART, RLENGTH)
+        out = out substr(s, 1, RSTART - 1) "0"
+        s = substr(s, RSTART + RLENGTH)
+      }
+      out = out s
+      if (out ~ /[^01&|!() \t]/) return 0
+      E = out; pos = 1; valid = 1
+      parseOr()
+      skip()
+      if (!valid || pos <= length(E)) return 0 # trailing garbage / bad atom
+      return 1
+    }
+    # The first tab separates the caller id from the expression. Rejoin any
+    # remaining fields so tabs inside an expression retain their documented
+    # whitespace meaning instead of being silently discarded by the awk field
+    # separator.
+    {
+      expr = $2
+      for (field = 3; field <= NF; field++) expr = expr "\t" $field
+      print $1 "\t" (check(expr) ? "ok" : "malformed")
+    }
+  '
+  exit 0
+fi
+
+EXPR="${1-}"
+FACTS="${2-}"
+
+# Empty expression → nothing to evaluate; caller fails open.
+case "$EXPR" in
+  ''|*[!\ ]*) : ;;  # has at least one non-space char → continue
+esac
+# (the case above is a readability no-op; the real empty check is in awk)
+
+awk -v expr="$EXPR" -v facts="$FACTS" '
+function skip() { while (substr(E, pos, 1) ~ /[ \t]/) pos++ }
+function parseOr(  v) {
+  v = parseAnd(); skip()
+  while (valid && substr(E, pos, 2) == "||") {
+    pos += 2
+    rhs = parseAnd()
+    v = (v || rhs)
+    skip()
+  }
+  return v
+}
+function parseAnd(  v) {
+  v = parseNot(); skip()
+  while (valid && substr(E, pos, 2) == "&&") {
+    pos += 2
+    rhs = parseNot()
+    v = (v && rhs)
+    skip()
+  }
+  return v
+}
+function parseNot(  c) {
+  skip(); c = substr(E, pos, 1)
+  if (c == "!") { pos++; return (parseNot() ? 0 : 1) }
+  return parseAtom()
+}
+function parseAtom(  v, c) {
+  skip(); c = substr(E, pos, 1)
+  if (c == "(") {
+    pos++; v = parseOr(); skip()
+    if (substr(E, pos, 1) != ")") { valid = 0; return 0 }
+    pos++; return v
+  }
+  if (c == "0" || c == "1") { pos++; return (c == "1") ? 1 : 0 }
+  valid = 0; return 0
+}
+BEGIN {
+  # empty / whitespace-only expression → fail open
+  e = expr; gsub(/[ \t]/, "", e)
+  if (e == "") exit 2
+
+  # build fact membership set
+  n = split(facts, fa, /[ ,]+/)
+  for (i = 1; i <= n; i++) if (fa[i] != "") have[fa[i]] = 1
+
+  # substitute identifiers -> 1/0 by membership
+  s = expr; out = ""
+  while (match(s, "[A-Za-z0-9_./][A-Za-z0-9_./-]*")) {
+    tok = substr(s, RSTART, RLENGTH)
+    out = out substr(s, 1, RSTART - 1) ((tolower(tok) in have) ? "1" : "0")
+    s = substr(s, RSTART + RLENGTH)
+  }
+  out = out s
+
+  # safety gate: only 0 1 & | ! ( ) and spaces may remain
+  if (out ~ /[^01&|!() \t]/) exit 2
+
+  # evaluate
+  E = out; pos = 1; valid = 1
+  v = parseOr()
+
+  # The parse must consume the WHOLE expression. Recursive descent stops at the
+  # first token it cannot continue from, so `merge || pull request` would parse
+  # as `merge || pull` and silently discard everything after the bare space —
+  # the policy then fires (or fails to) on a prefix nobody authored. Leftover
+  # input means the expression is malformed, not shorter.
+  skip()
+  if (!valid || pos <= length(E)) exit 2
+
+  exit (v ? 0 : 1)
+}
+'

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/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"