@indigoai-us/hq-cli 5.282.0 → 5.284.0

package/CHANGELOG.md

@@ -2,11 +2,43 @@
 
 ## [Unreleased]
 
+## [5.284.0] — 2026-09-29
+- The existing Work Mesh MQTT subscriber can signal agent inbox wakes through a private local marker without persisting MQTT message contents.
+
+### Fixed
+
+- A remote `hq lanes list` read no longer dispatches owner hire summaries,
+  capacity probes, or mirror snapshots to other Outposts. Two Outposts that
+  each held a lane placed on the other ran `hq lanes list --json` on each other
+  without end, which filled both boxes with SSM commands.
+
+## [5.283.0] — 2026-09-29
+
+### Added
+
+- `hq core ontology merge-copies --variants` merges two-file duplicate entity
+  groups whose names differ only in case, spacing or punctuation, keeping the
+  spaced name. Behind `checkpoint.ontology.merge-variants` (off by default).
+
 ## [5.282.0] — 2026-09-29
 
+### Added
+
+- Add native TypeScript handlers for `hq core knowledge-prefs` and `hq core
+  policy age-report`, `retire`, and `frontmatter`, gated by the default-off
+  `core-native-policy` flag. Bundled shell assets remain available for rollback
+  during the first release.
+
 ### Changed
 
 - Pin the third-party package setup action in the fast-route benchmark workflow to its resolved commit.
+- When the default-off `lanes.outpost-snapshot-cache` flag is enabled,
+  `hq lanes list` returns the last cached Outpost hire summaries immediately
+  and refreshes stale or missing summaries in the background. JSON rows show
+  snapshot age and stale/loading markers; text output includes a short stale or
+  loading note. `--fresh` waits for current owner summaries. Validated Outpost
+  snapshots live for three seconds; failed reads or lock acquisition are not
+  cached.
 
 ### Fixed
 

package/assets/scaffold/.claude/hooks/validate-policy-frontmatter.sh

@@ -0,0 +1,485 @@
+#!/bin/bash
+# validate-policy-frontmatter.sh — PreToolUse (Write, Edit, MultiEdit).
+#
+# Blocks the create/edit of a POLICY file whose RESULTING frontmatter is missing
+# `when:` or `on:`, or whose `when:` is rejected by the canonical boolean
+# trigger grammar.
+# These fields drive just-in-time policy injection (see
+# core/knowledge/public/hq-core/policies-spec.md). Every policy authored or
+# edited must declare both, and malformed expressions must not reach the
+# runtime's degraded compatibility path.
+#
+# For `enforcement: hard` it also enforces the two limits that keep an
+# always-injected, full-text rule from eating the session it is meant to guard:
+#   - no unconditional `when:` (a tautology containing `always`) on a REACTIVE
+#     event — that outranks policies that genuinely matched. Unconditional
+#     rules belong on `on: [SessionStart]`.
+#   - a binding body at or under HQ_POLICY_HARD_RULE_MAX_BYTES (default 6144),
+#     measured over the same span inject-policy-on-trigger.sh quotes: text
+#     after the frontmatter, up to the first archival heading (`## Rationale`,
+#     `## Background`, `## Change history`, `## Examples`, `## References`, …).
+# Both are checked only for hard policies; core/scripts/lint-policy-triggers.sh
+# reports the softer cases across the whole tree.
+#
+# Targets: */policies/*.md (core/, companies/*/, repos/*/*/.claude/, personal/).
+# Excludes: README.md and the .claude/audit/ redaction-rule store (those are not
+# trigger-injected policies). The retired `_digest.md` path has no exemption.
+#
+# Advisory-safe: FAILS OPEN (exit 0) on ambiguity about whether a write targets
+# a policy (non-policy paths, unparsable tool input, or no analyzer engine), so
+# it never blocks an unrelated write. Once it has identified a policy with a
+# `when:`, it FAILS CLOSED if the canonical evaluator is unavailable: silently
+# skipping that dependency would admit malformed hard rules. Engines: node first
+# (complex analyzers run on node per the hooks-no-python migration), else a
+# jq/awk port of the frontmatter/resulting-text analyzer. Neither port parses
+# trigger expressions; core/scripts/eval-trigger.sh owns that grammar.
+#
+# HQ_ALLOW_POLICY_NO_TRIGGER is an emergency operator override. It requires
+# explicit human permission; an agent must never set, export, or write it on
+# its own initiative.
+#
+# Exit codes: 0 = allow, 2 = block.
+#
+# Wired in .claude/settings.json PreToolUse (Edit/Write/MultiEdit) and gated by
+# hook-gate.sh under "validate-policy-frontmatter" (all three profiles).
+
+set -uo pipefail
+
+INPUT="$(cat)"
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+HOOK_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../.." 2>/dev/null && pwd)"
+HQ_ROOT="${HQ_ROOT:-$HOOK_ROOT}"
+EVAL_TRIGGER="$HQ_ROOT/core/scripts/eval-trigger.sh"
+JQ="$(command -v jq || true)"
+NODE="$(command -v node || true)"
+case "${HQ_HOOK_ENGINE:-}" in
+  jq)   NODE="" ;;
+  node) JQ="" ;;
+esac
+if [ -z "$NODE" ] && [ -z "$JQ" ]; then exit 0; fi   # fail open
+
+# Slurp the analyzer into a top-level var (NOT a heredoc inside $(...), which
+# bash 3.2 / macOS mis-parses — see hooks-heredoc-syntax.test.sh), then run via
+# `node -e`. Tool JSON is passed through the environment, not stdin/argv.
+JSPROG=''
+IFS= read -r -d '' JSPROG <<'JS' || true
+const fs = require("fs");
+const path = require("path");
+
+const allow = () => { console.log("ALLOW"); process.exit(0); };
+
+let data;
+try { data = JSON.parse(process.env.HQ_HOOK_INPUT || ""); } catch (e) { allow(); }
+const ti = (data && typeof data === "object" && data.tool_input && typeof data.tool_input === "object")
+  ? data.tool_input : {};
+const fp = ti.file_path || "";
+if (!fp) allow();
+
+const proj = process.env.HQ_PROJECT_DIR || "";
+const p = path.isAbsolute(fp) ? fp : path.normalize(path.join(proj, fp));
+const low = p.toLowerCase().replace(/\\/g, "/");
+
+if (!(low.endsWith(".md") && low.includes("/policies/"))) allow();
+const base = low.split("/").pop();
+if (base === "readme.md") allow();
+if (low.includes("/audit/")) allow();   // secret-redaction store, not a policy
+
+const readCurrent = () => { try { return fs.readFileSync(p, "utf8"); } catch (e) { return ""; } };
+// literal replace-once; a function replacement so "$&"-style patterns in the
+// new string are never interpreted
+const replaceOnce = (hay, o, n) => (o === "" ? hay : hay.replace(o, () => n));
+
+let text = null;
+if (ti.content !== undefined && ti.content !== null) {          // Write
+  text = String(ti.content);
+} else if (Array.isArray(ti.edits)) {                           // MultiEdit
+  text = readCurrent();
+  for (const e of ti.edits) {
+    const o = String((e && e.old_string) || ""), n = String((e && e.new_string) || "");
+    text = (o === "" && text === "") ? n : replaceOnce(text, o, n);
+  }
+} else if ("new_string" in ti) {                                // Edit
+  const cur = readCurrent();
+  const o = String(ti.old_string || ""), n = String(ti.new_string || "");
+  text = (cur === "" && o === "") ? n : replaceOnce(cur, o, n);
+} else allow();
+
+if (text === null) allow();
+
+// Analyze a line-ending-normalized COPY (CRLF / lone-CR -> LF): Windows
+// editors produce \r\n and the python original tolerated it via \s*. The
+// edit replay above runs on the RAW text so old_string matching is exact.
+const norm = String(text).replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+const m = norm.match(/^\s*---[ \t]*\n([\s\S]*?)\n---[ \t]*(\n|$)/);
+if (!m) { console.log("BLOCK|no-frontmatter"); process.exit(0); }
+const fm = m[1];
+const missing = [];
+const whenLines = [...fm.matchAll(/^[ \t]*when:[ \t]*(.*)$/gm)].map((match) => match[1]);
+if (!whenLines.some((expr) => /\S/.test(expr))) missing.push("when");
+if (!/^[ \t]*on:[ \t]*\S/m.test(fm)) missing.push("on");
+if (missing.length) { console.log("BLOCK|" + missing.join(",")); process.exit(0); }
+
+// ── Strictness rules for enforcement: hard ────────────────────────────────
+// A hard policy is injected in FULL TEXT and, when its trigger is loose, on
+// every event. Both cost is paid out of the same context the user is trying to
+// work in, so both are constrained here — at authoring time, where the fix is
+// one line — rather than being silently truncated at injection time.
+const enfMatch = fm.match(/^[ \t]*enforcement:[ \t]*["']?([A-Za-z]+)["']?/m);
+const isHard = enfMatch && enfMatch[1].toLowerCase() === "hard";
+
+if (isHard) {
+  // (1) `when: always` must not be paired with a reactive event. A tautology on
+  // PreToolUse/PostToolUse/UserPromptSubmit/AssistantIntent is ranked as an
+  // event-specific match and takes the cap slot of a policy that actually
+  // matched. SessionStart is the documented home for unconditional rules.
+  // A pure OR-chain containing `always` is a tautology; anything with && or !
+  // is conditional and left alone.
+  const tautological = whenLines.some((w) => {
+    const normalized = w.toLowerCase();
+    return !/[&!]/.test(normalized) && /(^|[^A-Za-z0-9_./-])always([^A-Za-z0-9_./-]|$)/.test(normalized);
+  });
+  const onLine = (fm.match(/^[ \t]*on:[ \t]*(.*)$/m) || [, ""])[1];
+  const reactive = ["PreToolUse", "PostToolUse", "UserPromptSubmit", "AssistantIntent"]
+    .filter((e) => onLine.includes(e));
+  if (tautological && reactive.length) {
+    console.log("BLOCK|hard-always-reactive|" + reactive.join(", "));
+    process.exit(0);
+  }
+
+  // (2) Bound the binding text. Everything from the first archival heading on
+  // is history, not rule — the injector already stops there, so measure the
+  // same span the agent will actually be made to read.
+  const STOP = /^#+[ \t]*(rationale|rationale and context|background|change history|changelog|history|examples?|references?|related|see also|sources?|provenance|evidence)[ \t]*$/;
+  const after = norm.slice(m.index + m[0].length);
+  const binding = [];
+  for (const line of after.split("\n")) {
+    if (STOP.test(line.trim().toLowerCase())) break;
+    binding.push(line);
+  }
+  const bytes = Buffer.byteLength(binding.join("\n").trim(), "utf8");
+  const max = parseInt(process.env.HQ_POLICY_HARD_RULE_MAX_BYTES || "6144", 10);
+  if (Number.isFinite(max) && max > 0 && bytes > max) {
+    console.log("BLOCK|hard-too-long|" + bytes + "|" + max);
+    process.exit(0);
+  }
+}
+
+// Leave syntax to the canonical batch evaluator below. Emit one record for
+// every `when:` so duplicate frontmatter keys do not escape validation.
+for (const when of whenLines) console.log("CHECK|" + when);
+JS
+
+# Literal replace-once (newline-safe) for the jq/awk fallback engine. Strings
+# cross via ENVIRON, not `awk -v`: -v mangles backslash escapes and BSD/
+# onetrueawk aborts on newlines in -v values (same constraint as
+# inject-policy-on-trigger.sh's HQ_ALREADY).
+replace_once() {  # env: R_CUR R_OLD R_NEW -> stdout
+  awk 'BEGIN{
+    cur=ENVIRON["R_CUR"]; old=ENVIRON["R_OLD"]; new=ENVIRON["R_NEW"]
+    if (old=="") { printf "%s", cur; exit }
+    i=index(cur, old)
+    if (i==0) printf "%s", cur
+    else printf "%s%s%s", substr(cur,1,i-1), new, substr(cur,i+length(old))
+  }'
+}
+
+# jq/awk port of the node analyzer above — same path filters, same
+# resulting-text semantics (Write content / Edit / MultiEdit replays), same
+# ALLOW / BLOCK|missing contract. Used when node is unavailable.
+analyze_with_jq() {
+  local fp path low base kind text cur o n count idx
+  fp="$(printf '%s' "$INPUT" | "$JQ" -r '.tool_input.file_path // empty' 2>/dev/null || true)"
+  [ -n "$fp" ] || { echo ALLOW; return; }
+  case "$fp" in /*|[A-Za-z]:*) path="$fp" ;; *) path="$PROJECT_DIR/$fp" ;; esac
+  low="$(printf '%s' "$path" | tr '[:upper:]' '[:lower:]' | tr '\\' '/')"
+  case "$low" in *.md) : ;; *) echo ALLOW; return ;; esac
+  case "$low" in */policies/*) : ;; *) echo ALLOW; return ;; esac
+  base="${low##*/}"
+  case "$base" in readme.md) echo ALLOW; return ;; esac
+  case "$low" in */audit/*) echo ALLOW; return ;; esac
+
+  kind="$(printf '%s' "$INPUT" | "$JQ" -r 'if (.tool_input.content? != null) then "write" elif ((.tool_input.edits? | type) == "array") then "multi" elif (.tool_input | has("new_string")) then "edit" else "none" end' 2>/dev/null || echo none)"
+  case "$kind" in
+    write) text="$(printf '%s' "$INPUT" | "$JQ" -r '.tool_input.content')" ;;
+    edit)
+      cur=""; [ -f "$path" ] && cur="$(cat "$path" 2>/dev/null || true)"
+      o="$(printf '%s' "$INPUT" | "$JQ" -r '.tool_input.old_string // ""')"
+      n="$(printf '%s' "$INPUT" | "$JQ" -r '.tool_input.new_string // ""')"
+      if [ -z "$cur" ] && [ -z "$o" ]; then text="$n"
+      else text="$(R_CUR="$cur" R_OLD="$o" R_NEW="$n" replace_once)"; fi
+      ;;
+    multi)
+      cur=""; [ -f "$path" ] && cur="$(cat "$path" 2>/dev/null || true)"
+      text="$cur"
+      count="$(printf '%s' "$INPUT" | "$JQ" -r '.tool_input.edits | length' 2>/dev/null || echo 0)"
+      idx=0
+      while [ "$idx" -lt "${count:-0}" ]; do
+        o="$(printf '%s' "$INPUT" | "$JQ" -r ".tool_input.edits[$idx].old_string // \"\"")"
+        n="$(printf '%s' "$INPUT" | "$JQ" -r ".tool_input.edits[$idx].new_string // \"\"")"
+        if [ -z "$o" ] && [ -z "$text" ]; then text="$n"
+        else text="$(R_CUR="$text" R_OLD="$o" R_NEW="$n" replace_once)"; fi
+        idx=$((idx+1))
+      done
+      ;;
+    *) echo ALLOW; return ;;
+  esac
+
+  printf '%s' "$text" | awk '
+    # normalize line endings (CRLF / stray CR) before structural checks —
+    # mirrors the node engine and the python original'"'"'s \s* tolerance
+    { line=$0; sub(/\r$/, "", line); L[NR]=line }
+    END{
+      i=1
+      while (i<=NR && L[i] ~ /^[ \t]*$/) i++
+      if (i>NR || L[i] !~ /^[ \t]*---[ \t]*$/) { print "BLOCK|no-frontmatter"; exit }
+      i++
+      closed=0; w=0; wc=0; o=0; taut=0; onx=""; enf=""
+      for (; i<=NR; i++) {
+        if (L[i] ~ /^---[ \t]*$/) { closed=1; break }
+        if (L[i] ~ /^[ \t]*when:[ \t]*/) {
+          wx=L[i]; sub(/^[ \t]*when:[ \t]*/, "", wx)
+          wx=tolower(wx)
+          whens[++wc]=wx
+          if (wx ~ /[^ \t]/) w=1
+          # a pure OR-chain containing `always` is a tautology; && / ! make it
+          # conditional and it is left alone
+          if (wx !~ /[&!]/ && wx ~ /(^|[^A-Za-z0-9_.\/-])always([^A-Za-z0-9_.\/-]|$)/) taut=1
+        }
+        if (L[i] ~ /^[ \t]*on:[ \t]*[^ \t]/) { o=1; onx=L[i] }
+        if (L[i] ~ /^[ \t]*enforcement:[ \t]*[^ \t]/) {
+          enf=L[i]; sub(/^[ \t]*enforcement:[ \t]*/, "", enf)
+          gsub(/["'"'"']/, "", enf); sub(/[ \t].*$/, "", enf); enf=tolower(enf)
+        }
+      }
+      if (!closed) { print "BLOCK|no-frontmatter"; exit }
+      m=""
+      if (!w) m="when"
+      if (!o) m=(m=="" ? "on" : m ",on")
+      if (m!="") { print "BLOCK|" m; exit }
+      if (enf == "hard") {
+        # (1) unconditional trigger on a reactive event — see the node engine
+        react=""
+        split("PreToolUse PostToolUse UserPromptSubmit AssistantIntent", ev, " ")
+        for (k=1; k<=4; k++) if (index(onx, ev[k]) > 0) react=react (react=="" ? "" : ", ") ev[k]
+        if (taut && react != "") { print "BLOCK|hard-always-reactive|" react; exit }
+
+        # (2) bound the binding text — the same span the injector will quote
+        stop="^#+[ \t]*(rationale|rationale and context|background|change history|changelog|history|examples?|references?|related|see also|sources?|provenance|evidence)[ \t]*$"
+        bytes=0
+        for (i++; i<=NR; i++) {
+          probe=tolower(L[i]); sub(/^[ \t]+/, "", probe); sub(/[ \t]+$/, "", probe)
+          if (probe ~ stop) break
+          bytes += length(L[i]) + 1
+        }
+        max=ENVIRON["HQ_POLICY_HARD_RULE_MAX_BYTES"]; if (max=="") max=6144
+        if (max+0 > 0 && bytes > max+0) { print "BLOCK|hard-too-long|" bytes "|" max; exit }
+      }
+      # Grammar validation belongs solely to eval-trigger.sh. Emit every
+      # populated when: line so duplicate keys are checked too.
+      for (k=1; k<=wc; k++) print "CHECK|" whens[k]
+    }'
+}
+
+if [ -n "$NODE" ]; then
+  RESULT="$(HQ_HOOK_INPUT="$INPUT" HQ_PROJECT_DIR="$PROJECT_DIR" "$NODE" -e "$JSPROG" 2>/dev/null || echo ALLOW)"
+else
+  RESULT="$(analyze_with_jq)"
+fi
+
+# The evaluator is deliberately checked only after the frontmatter analyzer
+# identifies a policy with at least one populated `when:`. A missing evaluator
+# must block that policy write: allowing it would recreate the malformed-rule
+# bypass this hook exists to prevent. Non-policy writes remain advisory-safe.
+override_enabled() {
+  [ "${HQ_ALLOW_POLICY_NO_TRIGGER:-}" = "1" ] || [ "${HQ_ALLOW_POLICY_NO_TRIGGER:-}" = "true" ]
+}
+
+block_missing_evaluator() {
+  # This is an operator-selected emergency override, deliberately as broad as
+  # the existing override below: it permits a policy write even when structural
+  # checks would otherwise block. Keeping only presence checks in this path
+  # would make the same documented override behave differently based on whether
+  # the evaluator happened to be executable, and could still prevent a repair
+  # write during an evaluator outage. Never make that degradation silent.
+  if override_enabled; then
+    cat >&2 <<MSG
+NOTE: HQ_ALLOW_POLICY_NO_TRIGGER override active. Allowing this policy write
+without canonical trigger syntax validation because the evaluator is unavailable:
+${EVAL_TRIGGER}
+MSG
+    exit 0
+  fi
+  cat >&2 <<MSG
+BLOCKED: cannot validate this policy's when: expression because the canonical
+trigger evaluator is unavailable.
+
+Checked: ${EVAL_TRIGGER}
+Expected: an executable core/scripts/eval-trigger.sh resolved from HQ_ROOT.
+
+This write is blocked fail-closed rather than silently skipping syntax
+validation. Restore that executable (or correct HQ_ROOT / CLAUDE_PROJECT_DIR)
+and retry; allowing the write would permit rules that can never parse or fire.
+MSG
+  exit 2
+}
+
+case "$RESULT" in
+  CHECK\|*)
+    [ -x "$EVAL_TRIGGER" ] || block_missing_evaluator
+
+    CHECK_EXPRESSIONS=()
+    check_count=0
+    while IFS= read -r check_line; do
+      case "$check_line" in
+        CHECK\|*)
+          CHECK_EXPRESSIONS[check_count]="${check_line#CHECK|}"
+          check_count=$((check_count + 1))
+          ;;
+        *)
+          # The analyzer's protocol is internal and deterministic. A mixed
+          # response after identifying a policy is unsafe to interpret as an
+          # allow, so use the same explicit fail-closed diagnostic.
+          block_missing_evaluator
+          ;;
+      esac
+    done <<EOF
+$RESULT
+EOF
+
+    [ "$check_count" -gt 0 ] || block_missing_evaluator
+    CHECK_OUTPUT="$({
+      check_index=0
+      while [ "$check_index" -lt "$check_count" ]; do
+        id="when-$check_index"
+        when="${CHECK_EXPRESSIONS[check_index]}"
+        printf '%s\t%s\n' "$id" "$when"
+        check_index=$((check_index + 1))
+      done
+    } | bash "$EVAL_TRIGGER" --check 2>&1)" || block_missing_evaluator
+
+    check_index=0
+    malformed_when_found=0
+    bad_when=""
+    while IFS=$'\t' read -r checked_id checked_status checked_extra || [ -n "${checked_id:-}${checked_status:-}${checked_extra:-}" ]; do
+      [ "$checked_id" = "when-$check_index" ] && [ -z "$checked_extra" ] || block_missing_evaluator
+      case "$checked_status" in
+        ok) ;;
+        malformed)
+          malformed_when_found=1
+          bad_when="${CHECK_EXPRESSIONS[check_index]}"
+          ;;
+        *) block_missing_evaluator ;;
+      esac
+      check_index=$((check_index + 1))
+    done <<EOF
+$CHECK_OUTPUT
+EOF
+    [ "$check_index" = "$check_count" ] || block_missing_evaluator
+    if [ "$malformed_when_found" = "1" ]; then
+      RESULT="BLOCK|invalid-when|$bad_when"
+    else
+      RESULT="ALLOW"
+    fi
+    ;;
+esac
+
+case "$RESULT" in
+  BLOCK*)
+    if override_enabled; then
+      exit 0
+    fi
+    reason="${RESULT#BLOCK|}"
+    case "$reason" in
+      hard-always-reactive*)
+        events="${reason#hard-always-reactive|}"
+        cat >&2 <<MSG
+BLOCKED: an enforcement: hard policy pairs an unconditional \`when:\` with a
+reactive event (${events}).
+
+\`when: always\` is TRUE for every command, prompt, and message. On a reactive
+event the injector ranks that as an event-specific match, so it takes the
+session cap slot of a policy that genuinely matched the thing you are doing —
+the loose trigger crowds out the precise one.
+
+Pick one:
+  when: always          + on: [SessionStart]        # ambient governance rule
+  when: <real signal>   + on: [PreToolUse, ...]     # e.g. deploy || publish
+
+Name the word(s) that actually appear when the rule is relevant. See
+core/knowledge/public/hq-core/policies-spec.md ("Trigger Expressions").
+
+(The HQ_ALLOW_POLICY_NO_TRIGGER override requires explicit human permission.
+An agent must never set, export, or write it on its own initiative.)
+MSG
+        exit 2
+        ;;
+      hard-too-long*)
+        rest="${reason#hard-too-long|}"
+        cat >&2 <<MSG
+BLOCKED: enforcement: hard policy body is ${rest%%|*} bytes; the limit is ${rest##*|}.
+
+A hard policy is injected VERBATIM into the session, so its length is a
+recurring context cost for every session it fires in. Keep the binding rule
+tight and move the reasoning out of the injected span: everything from the
+first \`## Rationale\` / \`## Background\` / \`## Change history\` /
+\`## Examples\` / \`## References\` heading onward is NOT counted and NOT
+injected, so long-form context belongs there.
+
+If the rule genuinely needs more than that, either split it into separate
+policies with distinct triggers, or raise HQ_POLICY_HARD_RULE_MAX_BYTES in
+.claude/settings.local.json "env".
+
+(The HQ_ALLOW_POLICY_NO_TRIGGER override requires explicit human permission.
+An agent must never set, export, or write it on its own initiative.)
+MSG
+        exit 2
+        ;;
+    esac
+    if [ "${reason%%|*}" = "invalid-when" ]; then
+      when_expression="${reason#invalid-when|}"
+      cat >&2 <<MSG
+BLOCKED: policy file has a malformed when: trigger expression:
+
+  when: ${when_expression}
+
+The canonical trigger evaluator rejected it. A space is NOT an AND, and quoted
+phrases are NOT tokens. Use explicit boolean operators instead:
+  "pull request"  -> (pull && request)
+  "force-push"    -> force-push
+
+Use only identifiers joined by the documented boolean grammar:
+  when: <identifier>                 # e.g.  always  |  git  |  /deep-plan
+  when: <expr> && <expr>             # AND
+  when: <expr> || <expr>             # OR
+  when: ! <expr>                     # NOT
+  when: ( <expr> )                   # grouping
+Identifiers may contain letters, digits, _, ., /, and internal -. Quotes,
+YAML block scalars, adjacent identifiers without an operator, and other
+punctuation are not valid. See core/knowledge/public/hq-core/policies-spec.md
+("Trigger Expressions"). Fix the expression, then retry.
+
+(The HQ_ALLOW_POLICY_NO_TRIGGER override requires explicit human permission.
+An agent must never set, export, or write it on its own initiative.)
+MSG
+      exit 2
+    fi
+    cat >&2 <<MSG
+BLOCKED: policy file is missing required trigger frontmatter (missing: ${reason}).
+
+Every policy under */policies/ must declare BOTH:
+  when: <expression>   # e.g.  always  |  git && push  |  deploy || share
+  on:   [<events>]     # any of PreToolUse, PostToolUse, UserPromptSubmit, AssistantIntent, SessionStart
+These drive just-in-time policy injection. See
+core/knowledge/public/hq-core/policies-spec.md ("Trigger Expressions").
+Add both fields to the frontmatter, then retry.
+
+(The HQ_ALLOW_POLICY_NO_TRIGGER override requires explicit human permission.
+An agent must never set, export, or write it on its own initiative.)
+MSG
+    exit 2
+    ;;
+  *)
+    exit 0
+    ;;
+esac