session-orchestrator 3.17.0 → 3.19.0

package/scripts/lib/validate/check-hooks-symmetry.mjs

@@ -1,12 +1,31 @@
 #!/usr/bin/env node
 // scripts/lib/validate/check-hooks-symmetry.mjs
-// Verify event-key + handler-file symmetry across hooks/{hooks,hooks-codex,hooks-cursor,hooks-pi}.json
+// Verify event-key + handler-file + per-event handler-set symmetry across
+// hooks/{hooks,hooks-codex,hooks-cursor,hooks-pi}.json (Check 6: #942)
+// Check 6 projects platform-native event namespaces onto the logical Claude
+// events first, then refuses to report parity for any counterpart event that
+// lands on no hooks.json event — whether that is one dropped projection or the
+// whole namespace (a vacuum-true PASS — see Check 6).
 // Exit 0 = all checks pass, 1 = any check fails
 // Stdout: '  PASS: ...' / '  FAIL: ...' lines + 'Results: N passed, M failed'
 
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
+// The pi projection is IMPORTED, not copied: pi-hook-bridge.mjs is the runtime
+// that actually rewrites `hook_event_name` for every Pi event, so it is the one
+// source of truth for which pi event becomes which Claude event (#953). A local
+// literal here was a second copy of the same 5 pairs — it could drift silently,
+// and the validator would then certify a projection the runtime does not use.
+// Deliberately NOT the same for `cursorEventMap` below: nothing at runtime
+// projects Cursor events (Cursor calls the handlers directly), so the
+// validator's copy is the only witness there. Even if a runtime source existed,
+// reading Check 3's expectation from the artefact it checks would make the
+// check self-certifying — the "undocumented pi-native event" test at
+// tests/scripts/check-hooks-symmetry.test.mjs would become unreachable. Keep
+// cursorEventMap validator-owned; do not "helpfully" collapse it too.
+import { PI_TO_CANONICAL_EVENT } from '../pi-hook-bridge.mjs';
+
 const PLUGIN_ROOT = process.argv[2];
 if (!PLUGIN_ROOT) {
   console.error('Usage: check-hooks-symmetry.mjs <plugin-root>');
@@ -25,12 +44,125 @@ const DOCUMENTED_ASYMMETRIES = {
   // Claude/Codex events with no Pi-native v1 mapping yet.
   piMissingFromMain: ['PostToolUseFailure', 'PostToolBatch', 'SubagentStart', 'SubagentStop', 'CwdChanged'],
   // Pi-native extension events that map onto Claude/Codex hook events.
-  piEventMap: {
-    session_start: 'SessionStart',
-    session_shutdown: 'SessionEnd',
-    tool_call: 'PreToolUse',
-    tool_result: 'PostToolUse',
-    agent_end: 'Stop',
+  // Bound to the runtime constant (see the import comment): the projection this
+  // validator checks hooks-pi.json against is the SAME object pi-hook-bridge.mjs
+  // applies to live payloads, so the two cannot drift apart.
+  piEventMap: PI_TO_CANONICAL_EVENT,
+  // Cursor-IDE-native events projected onto the logical Claude events they
+  // correspond to. WITHOUT this projection Check 6 compared a FOREIGN event
+  // namespace against hooks.json: not one key matched, the per-event loop
+  // `continue`d on every iteration, and hooks-cursor.json reported
+  // "handler sets match hooks.json (documented asymmetries: 0)" while missing
+  // 20 of 22 handlers — a vacuum-true PASS. Check 6's projection guard now
+  // fails closed PER declared event (#946), so dropping a single entry from
+  // this map is caught too, not only the loss of every projection: the first
+  // version tested `sharedEvents.length === 0`, under which removing just
+  // `afterFileEdit` left the run green and merely moved cursor's documented-
+  // asymmetry count from 12 to 8.
+  // afterFileEdit fires AFTER the edit (hooks-cursor.json `note`,
+  // docs/cursor-setup.md) → it projects onto PostToolUse, never PreToolUse.
+  cursorEventMap: {
+    beforeShellExecution: 'PreToolUse',
+    afterFileEdit: 'PostToolUse',
+  },
+  // Check 6 (#942): handlers wired on a Claude event but intentionally absent
+  // from the SAME logical event on a counterpart manifest. Checks 1-3 compare
+  // event KEYS and Check 4 handler EXISTENCE — a handler wired on only one
+  // platform was structurally invisible to all four (the #942 blind spot:
+  // post-bash-write-verify.mjs shipped Claude-only and nothing flagged it).
+  // A handler missing on a shared event and NOT listed here → FAIL.
+  handlerAsymmetries: {
+    codex: {
+      // Codex 0.144.4 has no payload adapter (docs/codex-setup.md § Hook
+      // Surface and Trust): Edit/Write handlers expect Claude payload shapes,
+      // Bash guards expect tool_name === 'Bash'. Wiring them would be a silent
+      // no-op, not enforcement (#919-P2 class) — "pretending the payloads are
+      // compatible would create false enforcement".
+      PreToolUse: [
+        'skill-invocation-telemetry.mjs',
+        'enforce-scope.mjs',
+        'config-protection.mjs',
+        'pre-bash-destructive-guard.mjs',
+        'pre-bash-staging-fence.mjs',
+        'pre-bash-memory-propose-audit.mjs',
+        // pre-bash-sessions-ledger-guard (#958): same Bash-payload dependency
+        // as the guards above — it reads tool_name === 'Bash' and
+        // tool_input.command, neither of which any Codex bridge delivers
+        // (measured 2026-07-31: `grep -rn "tool_name" scripts/lib/codex/*.mjs`
+        // → 0 matches, exit 1). A manifest entry would be a silent no-op, not
+        // enforcement — #919-P2 class. Gap registered, not faked.
+        'pre-bash-sessions-ledger-guard.mjs',
+        'pre-bash-templates-first.mjs',
+        'pre-bash-issue-budget.mjs',
+        'enforce-commands.mjs',
+      ],
+      // post-bash-write-verify (#942): needs tool_name === 'Bash', which no
+      // Codex bridge delivers — documented exception until an adapter exists.
+      // Measured 2026-07-31: `grep -rn "tool_name" scripts/lib/codex/*.mjs`
+      // → 0 matches (exit 1), so a manifest entry here would be a silent
+      // no-op, not enforcement. Same #919-P2 class as the PreToolUse block.
+      PostToolUse: [
+        'post-edit-validate.mjs',
+        'post-tooluse-frontend-slop.mjs',
+        'post-bash-write-verify.mjs',
+      ],
+      SubagentStart: ['subagent-telemetry.mjs'],
+      SubagentStop: ['subagent-telemetry.mjs', 'post-subagent-discovery-validator.mjs'],
+    },
+    pi: {
+      // skill-invocation-telemetry: Pi has no Skill tool (pi-hook-bridge
+      // TOOL_NAME_MAP) — the matcher can never fire.
+      // pre-bash-templates-first + pre-bash-issue-budget (#946): status-quo
+      // gaps predating #942. Operator decision 2026-07-31 — NOT ported, gap
+      // registered instead; #946 tracks the port-or-justify follow-up.
+      // pre-bash-sessions-ledger-guard (#958): NOT ported. Pi has a payload
+      // adapter (pi-hook-bridge.mjs), so unlike codex/cursor this one is
+      // portable — but wiring it is a separate decision with its own test
+      // surface, and the operator's 2026-07-31 rule is that a gap gets
+      // registered rather than faked. #958 tracks the port-or-justify.
+      PreToolUse: [
+        'skill-invocation-telemetry.mjs',
+        'pre-bash-sessions-ledger-guard.mjs', // #958
+        'pre-bash-templates-first.mjs', // #946
+        'pre-bash-issue-budget.mjs',    // #946
+      ],
+    },
+    // Cursor is NOT wired (#919) and will not be: hooks-cursor.json is a
+    // mapping REFERENCE, not live enforcement. Every handler expects Claude
+    // Code payload shapes (tool_name === 'Bash', tool_input.command) and emits
+    // a Claude PreToolUse envelope; fed a Cursor payload enforce-commands.mjs
+    // short-circuits at gate G1 and writes 0 bytes to stdout AND stderr with
+    // exit 0, so the harness sees no decision and the command runs. Cursor
+    // needs an input/output adapter like scripts/lib/pi-hook-bridge.mjs; none
+    // exists. Operator decision 2026-07-31 — gap registered, not closed:
+    // #919 (Cursor no-op) tracks the adapter, #946 the allowlist-provenance
+    // rule that every entry here names its issue. These entries exist so the
+    // gap is MACHINE-readable (Check 6 counts them) rather than prose-only.
+    cursor: {
+      // #919: beforeShellExecution → PreToolUse. Only enforce-commands.mjs is
+      // mapped at all; the other eight PreToolUse handlers have no Cursor
+      // mapping whatsoever.
+      PreToolUse: [
+        'skill-invocation-telemetry.mjs',    // #919
+        'enforce-scope.mjs',                 // #919
+        'config-protection.mjs',             // #919
+        'pre-bash-destructive-guard.mjs',    // #919
+        'pre-bash-staging-fence.mjs',        // #919
+        'pre-bash-memory-propose-audit.mjs', // #919
+        'pre-bash-sessions-ledger-guard.mjs',// #919 (#958 — needs tool_name === 'Bash')
+        'pre-bash-templates-first.mjs',      // #919
+        'pre-bash-issue-budget.mjs',         // #919
+      ],
+      // #919: afterFileEdit → PostToolUse. Cursor maps enforce-scope.mjs here
+      // (post-hoc warning only); none of Claude's four PostToolUse handlers
+      // has a Cursor mapping.
+      PostToolUse: [
+        'post-edit-validate.mjs',          // #919
+        'post-tooluse-frontend-slop.mjs',  // #919
+        'post-bash-write-verify.mjs',      // #919 (#942 class — needs tool_name === 'Bash')
+        'loop-guard.mjs',                  // #919
+      ],
+    },
   },
 };
 
@@ -163,9 +295,10 @@ if (piJson) {
 // Handles two shapes:
 //   Claude/Codex: hooks[event] = Array<{ hooks: Array<{ command: "node \"$CLAUDE_PLUGIN_ROOT/hooks/foo.mjs\"" }> }>
 //   Cursor:       hooks[event] = { script: "hooks/foo.mjs" }
-function extractHandlers(json) {
-  const handlers = new Set();
-  for (const event of Object.values(json.hooks || {})) {
+function extractHandlersByEvent(json) {
+  const byEvent = {};
+  for (const [eventName, event] of Object.entries(json.hooks || {})) {
+    const handlers = new Set();
     const matchers = Array.isArray(event) ? event : [event];
     for (const m of matchers) {
       // Cursor shape: script field at matcher level
@@ -181,6 +314,15 @@ function extractHandlers(json) {
         if (match) handlers.add(match[1]);
       }
     }
+    byEvent[eventName] = handlers;
+  }
+  return byEvent;
+}
+
+function extractHandlers(json) {
+  const handlers = new Set();
+  for (const set of Object.values(extractHandlersByEvent(json))) {
+    for (const h of set) handlers.add(h);
   }
   return handlers;
 }
@@ -252,6 +394,98 @@ if (unreferenced.length === 0) {
   pass(`hooks/ has ${unreferenced.length} unreferenced .mjs files (allowed; they may be library helpers): ${unreferenced.join(', ')}`);
 }
 
+// Step 9 (#942): per-event handler-SET parity, Claude → counterpart.
+// Checks 1-3 compare event keys, Check 4 handler existence — neither sees a
+// handler wired on one platform only. For every logical event the counterpart
+// DECLARES (event-level absences stay governed by Checks 1-3), each Claude
+// handler must be present on the counterpart or listed in
+// DOCUMENTED_ASYMMETRIES.handlerAsymmetries. Undocumented gap → FAIL.
+console.log('');
+console.log('--- Check 6: per-event handler-set parity across manifests (#942) ---');
+const claudeHandlersByEvent = extractHandlersByEvent(claudeJson);
+
+// Pi and Cursor declare platform-native event names; project them onto the
+// logical main events before comparing, or the whole comparison is vacuous.
+// Native events with no mapping are carried through under their own name so
+// the projection guard below still sees them as declared.
+//
+// The merge is a UNION, not an assignment: two native events may project onto
+// the SAME logical event (a harness with `before_shell` AND `before_edit` both
+// mapping to PreToolUse, or — reachable today via the identity fallback — a
+// counterpart that declares the logical event alongside a native event that
+// projects onto it). Assignment let the second write silently discard the
+// first set, so its handlers resurfaced as a phantom "undocumented asymmetry"
+// or vanished from the comparison entirely.
+function handlersByMainEvent(json, eventMap) {
+  const byNativeEvent = extractHandlersByEvent(json);
+  const byMain = {};
+  for (const [nativeEvent, handlers] of Object.entries(byNativeEvent)) {
+    const target = eventMap[nativeEvent] || nativeEvent;
+    byMain[target] = new Set([...(byMain[target] ?? []), ...handlers]);
+  }
+  return byMain;
+}
+
+const HANDLER_PARITY_COUNTERPARTS = [
+  { file: 'hooks-codex.json', key: 'codex', byEvent: codexJson ? extractHandlersByEvent(codexJson) : null },
+  {
+    file: 'hooks-cursor.json',
+    key: 'cursor',
+    byEvent: cursorJson ? handlersByMainEvent(cursorJson, DOCUMENTED_ASYMMETRIES.cursorEventMap) : null,
+  },
+  {
+    file: 'hooks-pi.json',
+    key: 'pi',
+    byEvent: piJson ? handlersByMainEvent(piJson, DOCUMENTED_ASYMMETRIES.piEventMap) : null,
+  },
+];
+
+for (const { file, key, byEvent } of HANDLER_PARITY_COUNTERPARTS) {
+  if (!byEvent) {
+    pass(`${file} absent (optional config) — handler parity skipped`);
+    continue;
+  }
+  // Projection guard: every event a counterpart declares must land on a
+  // logical event hooks.json also declares. An unprojected event makes the
+  // per-event loop below `continue` on the logical event it was supposed to
+  // cover, so those handlers are never compared and Check 6 still reports
+  // PASS — only the `documented asymmetries:` count moves. Losing ALL
+  // projections is how hooks-cursor.json passed with 20 of 22 handlers
+  // missing; losing ONE is the same blindness at smaller scale, so the guard
+  // fails closed per event, not only on the empty intersection (#946).
+  const declaredEvents = Object.keys(byEvent);
+  const sharedEvents = declaredEvents.filter((e) => Object.hasOwn(claudeHandlersByEvent, e));
+  const unprojectedEvents = declaredEvents.filter((e) => !Object.hasOwn(claudeHandlersByEvent, e));
+  if (declaredEvents.length > 0 && sharedEvents.length === 0) {
+    // Whole-namespace loss keeps its own message: nothing at all was compared.
+    fail(`${file} shares ZERO logical events with hooks.json after projection (declares: ${declaredEvents.join(', ')}) — handler parity would pass vacuously; add an event projection to DOCUMENTED_ASYMMETRIES`);
+    continue;
+  }
+  if (unprojectedEvents.length > 0) {
+    fail(`${file} declares events with no logical counterpart in hooks.json after projection: ${unprojectedEvents.join(', ')} — handlers on the logical events they stand for are never compared; add a projection to DOCUMENTED_ASYMMETRIES.${key}EventMap`);
+    continue;
+  }
+
+  const allow = DOCUMENTED_ASYMMETRIES.handlerAsymmetries[key] || {};
+  const undocumented = [];
+  let documentedCount = 0;
+  for (const [event, claudeSet] of Object.entries(claudeHandlersByEvent)) {
+    const counterpartSet = byEvent[event];
+    if (!counterpartSet) continue; // event not declared on counterpart — Checks 1-3 govern
+    const allowed = new Set(allow[event] || []);
+    for (const handler of claudeSet) {
+      if (counterpartSet.has(handler)) continue;
+      if (allowed.has(handler)) { documentedCount++; continue; }
+      undocumented.push(`${event} → ${handler}`);
+    }
+  }
+  if (undocumented.length === 0) {
+    pass(`${file} per-event handler sets match hooks.json (documented asymmetries: ${documentedCount})`);
+  } else {
+    fail(`${file} missing UNDOCUMENTED handlers on shared events: ${undocumented.join(', ')}`);
+  }
+}
+
 // Final
 console.log('');
 console.log(`Results: ${passed} passed, ${failed} failed`);

package/scripts/lib/validate/check-rules.mjs

@@ -1,21 +1,71 @@
 #!/usr/bin/env node
-// check-rules.mjs — Validate .claude/rules/*.md files with auto-generated: true
-// against the never-always-on invariant (FA4 #697 backstop for the reconcile emitter
-// brandmauer in scripts/lib/reconcile/emitter.mjs ~line 193).
+// check-rules.mjs — Validate .claude/rules/*.md files against two invariants:
 //
-// Rules WITHOUT `auto-generated: true` in their frontmatter are SKIPPED — this
-// gate only validates generated rules. Handwritten rules are not audited here.
+// (1) AUTO-GENERATED rules (`auto-generated: true` — FA4 #697 backstop for the
+//     reconcile emitter brandmauer in scripts/lib/reconcile/emitter.mjs ~line
+//     193). HARD-FAIL, exit-code-driving:
+//       (a) never-always-on: must have at least one activation axis — a
+//           non-empty `globs` array OR a `host-class` key. A rule that is
+//           always-on (globs null/absent AND no host-class) is a budget
+//           violation (#668 / #687).
+//           SPECIAL CASE (#892 QA Defect — the auto-generated twin of #880 QA
+//           Defect 1) — an EMPTY `globs` array (`globs: []`) is NOT the
+//           "no axis" case and is NOT always-on: rule-loader.mjs
+//           unconditionally excludes on `globs.length === 0` (~line 526)
+//           AFTER gating runs, so the rule never loads in ANY context — even
+//           one where a co-present `host-class:` key would otherwise satisfy
+//           the axis. Before #892 this branch silently mis-reported (or, when
+//           paired with `host-class:`, silently missed entirely) this case
+//           under the inverted "always-on" FAIL message. This gets its own
+//           distinct FAIL, fired independent of `host-class`, because
+//           `host-class` cannot rescue an empty globs array from that
+//           unconditional exclusion — mirrors the handwritten branch's
+//           identical `hasEmptyGlobs` fix below.
+//       (b) learning-key must be present (traceability back to the emitter source).
+//       (c) expires-at must be present (auto-generated rules must have a TTL).
 //
-// For every auto-generated rule, three invariants are checked:
-//   (a) never-always-on: must have at least one activation axis — a non-empty
-//       `globs` array OR a `host-class` key. A rule that is always-on
-//       (globs null/empty AND no host-class) is a budget violation (#668 / #687).
-//   (b) learning-key must be present (traceability back to the emitter source).
-//   (c) expires-at must be present (auto-generated rules must have a TTL).
+// (2) HANDWRITTEN rules (no `auto-generated: true` — #880 FA5, WARN-only,
+//     NEVER affects the exit code). The auto-generated brandmauer above only
+//     binds the MACHINE author (the reconcile emitter) — a human authoring a
+//     rule file by hand bypasses it entirely. #880's finding: several
+//     handwritten rules in this repo carry only a `tier:` axis (no
+//     `globs`/`paths`/`host-class`) and no periodic-review marker, and nothing
+//     in the system ever prompts a re-review. This second, symmetric check
+//     extends the SAME invariant shape to handwritten rules, starting in WARN
+//     mode — a hard gate is a later, deliberate step (see
+//     docs/rule-authoring.md § "Handwritten Rule Review Date (#880 FA5)").
+//     A handwritten rule is flagged when it is missing EITHER:
+//       (a) an activation axis — a non-empty `globs`/`paths` array, a
+//           `host-class` key, OR a `tier` key. `tier:` counts: rule-loader.mjs
+//           `applyGates()` honours it as a real load-context gate (excludes
+//           `coordinator-only` rules from wave context and vice versa) — see
+//           docs/rule-authoring.md § "Tier gating (issue #692)".
+//           SPECIAL CASE — an EMPTY `globs`/`paths` array (`globs: []`) is
+//           NOT the "no axis" case and is NOT always-on: rule-loader.mjs
+//           unconditionally excludes on `globs.length === 0` AFTER gating
+//           runs, so the rule never loads in any context — even one where a
+//           co-present `tier:`/`host-class:` key would otherwise satisfy the
+//           axis. This branch gets its own distinct WARN, fired independent
+//           of `tier`/`host-class`, because neither can rescue an empty
+//           globs array from that unconditional exclusion (#880 QA Defect 1
+//           fix — see the FAIL/WARN inversion this replaced in git blame).
+//       (b) a `review-date` key (ISO 8601 date) — a periodic-review marker,
+//           DELIBERATELY DISTINCT from `expires-at`. rule-loader.mjs treats
+//           `expires-at` as a live EXPIRY gate (`applyGates`): reusing it on a
+//           hand-authored always-on safety rule (e.g. security.md) would make
+//           that rule silently stop loading the day the date passes — an
+//           unacceptable behaviour change for a metadata-only review marker.
+//           `review-date` is inert: it is NOT in rule-loader.mjs's
+//           SCALAR_META_KEYS allowlist (contract-locked, not modified by
+//           #880), so `parseGlobsFrontmatter()` never surfaces it and
+//           `loadApplicableRules()` never gates on it — it is parsed only by
+//           THIS script, via the local `hasFrontmatterKey()` helper below.
 //
 // Usage: check-rules.mjs <plugin-root>
-// Outputs lines of the form "  PASS: ..." / "  FAIL: ..."
-// Exit 0 = all invariants satisfied (or no auto-generated rules found); exit 1 = at least one failure.
+// Outputs lines of the form "  PASS: ..." / "  FAIL: ..." / "  WARN: ...".
+// Exit 0 = all AUTO-GENERATED invariants satisfied (WARN lines from the
+// handwritten check NEVER affect the exit code); exit 1 = at least one
+// auto-generated FAIL.
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -32,6 +82,7 @@ const RULES_DIR = join(pluginRoot, '.claude', 'rules');
 
 let passed = 0;
 let failed = 0;
+let warned = 0;
 
 function pass(msg) {
   console.log(`  PASS: ${msg}`);
@@ -43,8 +94,39 @@ function fail(msg) {
   failed++;
 }
 
+function warn(msg) {
+  console.log(`  WARN: ${msg}`);
+  warned++;
+}
+
+// ---------------------------------------------------------------------------
+// Local frontmatter helper for the `review-date` key (#880 FA5). Deliberately
+// NOT routed through rule-loader.mjs's `parseGlobsFrontmatter()` — that
+// module is contract-locked and its SCALAR_META_KEYS allowlist does not (and
+// should not) recognise `review-date`, per the module-doc rationale above.
+// This is a minimal, self-contained frontmatter-block scan mirroring
+// rule-loader.mjs's own FRONTMATTER_RE, not a general YAML parser.
+// ---------------------------------------------------------------------------
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+
+/**
+ * Returns true when the frontmatter block of `contents` contains a top-level
+ * `key:` line carrying a non-empty value.
+ *
+ * @param {string} contents - raw file contents
+ * @param {string} key - frontmatter key name (no colon)
+ * @returns {boolean}
+ */
+function hasFrontmatterKey(contents, key) {
+  const match = FRONTMATTER_RE.exec(contents);
+  if (!match) return false;
+  const keyRe = new RegExp(`^${key}:\\s*(\\S.*)?$`, 'm');
+  const keyMatch = keyRe.exec(match[1]);
+  return Boolean(keyMatch && keyMatch[1] && keyMatch[1].trim() !== '');
+}
+
 // ============================================================================
-// Check: auto-generated rule invariants
+// Check: .claude/rules/ rule invariants
 // ============================================================================
 console.log('--- Check: .claude/rules/ auto-generated rule invariants ---');
 
@@ -52,7 +134,7 @@ console.log('--- Check: .claude/rules/ auto-generated rule invariants ---');
 if (!existsSync(RULES_DIR)) {
   pass('no .claude/rules/ directory found — nothing to validate');
   console.log('');
-  console.log(`Results: ${passed} passed, ${failed} failed`);
+  console.log(`Results: ${passed} passed, ${failed} failed, ${warned} warned`);
   process.exit(0);
 }
 
@@ -67,12 +149,16 @@ try {
 if (mdFiles.length === 0) {
   pass('no .md rule files found — nothing to validate');
   console.log('');
-  console.log(`Results: ${passed} passed, ${failed} failed`);
+  console.log(`Results: ${passed} passed, ${failed} failed, ${warned} warned`);
   process.exit(0);
 }
 
-// Track whether we found any auto-generated rules at all.
-let autoGeneratedCount = 0;
+// Parse every rule file once, splitting into the auto-generated and
+// handwritten cohorts. Malformed frontmatter → skipped from BOTH checks
+// (matches pre-#880 behaviour: a rule whose frontmatter cannot be parsed is
+// neither PASS'd nor FAIL'd).
+const autoGeneratedEntries = [];
+const handwrittenEntries = [];
 
 for (const name of mdFiles.sort()) {
   const filePath = join(RULES_DIR, name);
@@ -88,28 +174,52 @@ for (const name of mdFiles.sort()) {
   try {
     parsed = parseGlobsFrontmatter(contents);
   } catch {
-    // Malformed frontmatter — not an auto-generated rule, skip.
+    // Malformed frontmatter — not auditable by either branch, skip.
     continue;
   }
 
   const { globs, meta } = parsed;
-
-  // Only validate rules that explicitly declare auto-generated: true.
-  if (meta['auto-generated'] !== true) continue;
-
-  autoGeneratedCount++;
   const rel = `.claude/rules/${name}`;
 
+  if (meta['auto-generated'] === true) {
+    autoGeneratedEntries.push({ rel, globs, meta });
+  } else {
+    handwrittenEntries.push({ rel, globs, meta, contents });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Auto-generated branch (FA4 #697) — UNCHANGED behaviour, hard-fail.
+// ---------------------------------------------------------------------------
+for (const { rel, globs, meta } of autoGeneratedEntries) {
   // (a) never-always-on: must have at least one activation axis.
-  // globs is null (no frontmatter / no globs key) OR empty array → always-on.
-  // host-class absent → no host-class axis.
+  // globs is one of: null (no frontmatter / no globs key), [] (key present
+  // but EMPTY — the #892 QA-Defect special case, see module doc), or a
+  // populated array. host-class absent → no host-class axis.
+  const hasEmptyGlobs = Array.isArray(globs) && globs.length === 0;
   const hasGlobs = Array.isArray(globs) && globs.length > 0;
   const hasHostClass = Object.prototype.hasOwnProperty.call(meta, 'host-class');
 
-  if (!hasGlobs && !hasHostClass) {
+  if (hasEmptyGlobs) {
+    // An empty globs array is NOT "no axis at all" and is NOT "always-on" —
+    // it is the opposite: rule-loader.mjs's unconditional globs.length === 0
+    // exclusion (~line 526) fires AFTER gating, so this rule never loads in
+    // ANY context, even one that also carries a host-class: key. Fire
+    // independent of hasHostClass — host-class cannot rescue an empty globs
+    // array from that unconditional exclusion (#892 QA Defect fix — see the
+    // module doc for the full rule-loader.mjs citation and the identical
+    // handwritten-branch fix this mirrors, #880 QA Defect 1).
     fail(
-      `${rel} — auto-generated rule is always-on (no activation axis: globs is absent/empty AND host-class absent). ` +
-      'This violates the never-always-on invariant (#668/#687). Add a globs filter or host-class axis.',
+      `${rel} — auto-generated rule has an empty globs array (globs: []) — this rule matches NOTHING and never ` +
+        'loads in ANY context, even one that also carries a host-class: key (rule-loader.mjs excludes on ' +
+        'globs.length === 0 unconditionally, after gating runs). This is the OPPOSITE of "always-on" but still ' +
+        'violates the never-always-on invariant (#668/#687) because the rule never activates at all. Populate ' +
+        'globs: with real patterns or remove the file.',
+    );
+  } else if (!hasGlobs && !hasHostClass) {
+    fail(
+      `${rel} — auto-generated rule is always-on (no activation axis: globs is absent AND host-class absent). ` +
+        'This violates the never-always-on invariant (#668/#687). Add a globs filter or host-class axis.',
     );
   }
 
@@ -123,21 +233,93 @@ for (const name of mdFiles.sort()) {
     fail(`${rel} — auto-generated rule is missing required frontmatter key: expires-at`);
   }
 
-  // Emit a PASS line only when the rule satisfies ALL three invariants:
-  // an activation axis (globs or host-class) AND learning-key AND expires-at.
-  // When any failed, the FAIL line(s) above already emitted.
+  // Emit a PASS line only when the rule satisfies ALL three invariants: a
+  // genuine activation axis (a NON-EMPTY globs array, or host-class — NEVER
+  // an empty globs array, which is dead-not-passing regardless of host-class)
+  // AND learning-key AND expires-at. When any failed, the FAIL line(s) above
+  // already emitted.
   const lkOk = Object.prototype.hasOwnProperty.call(meta, 'learning-key');
   const eaOk = Object.prototype.hasOwnProperty.call(meta, 'expires-at');
-  if ((hasGlobs || hasHostClass) && lkOk && eaOk) {
+  if (!hasEmptyGlobs && (hasGlobs || hasHostClass) && lkOk && eaOk) {
     pass(`${rel} — auto-generated rule satisfies all invariants`);
   }
 }
 
-if (autoGeneratedCount === 0) {
+if (autoGeneratedEntries.length === 0) {
   pass('no auto-generated rules found — nothing to validate');
 }
 
+// ---------------------------------------------------------------------------
+// Handwritten branch (#880 FA5) — WARN-only, non-fatal, never affects exit code.
+// ---------------------------------------------------------------------------
+console.log('');
+console.log(
+  '--- Check: .claude/rules/ handwritten-rule activation + review-date (warn mode, #880) ---',
+);
+
+for (const { rel, globs, meta, contents } of handwrittenEntries) {
+  // `globs` (the merged globs/paths value from parseGlobsFrontmatter — #795
+  // alias, `globs:` wins when both are present) is one of:
+  //   - null                     → neither key present
+  //   - [] (Array, length 0)     → key present but EMPTY
+  //   - [...] (Array, length>0)  → key present and populated
+  const hasEmptyGlobs = Array.isArray(globs) && globs.length === 0;
+  const hasGlobsAxis = Array.isArray(globs) && globs.length > 0;
+  const hasHostClassAxis = Object.prototype.hasOwnProperty.call(meta, 'host-class');
+  const hasTierAxis = Object.prototype.hasOwnProperty.call(meta, 'tier');
+  const hasAxis = hasGlobsAxis || hasHostClassAxis || hasTierAxis;
+  const hasReviewDate = hasFrontmatterKey(contents, 'review-date');
+
+  if (hasEmptyGlobs) {
+    // An empty globs/paths array is NOT the same condition as "no axis at
+    // all", and it is NOT "always-on" — it is the opposite. Per
+    // rule-loader.mjs's loadApplicableRules() (~line 526): once frontmatter
+    // parses, tier/host-class/mode/expiry gating (applyGates) runs FIRST and
+    // can only ADD exclusions; if the rule survives that gating, the loader
+    // THEN unconditionally excludes it when `globs.length === 0` ("matches
+    // nothing (intentionally scoped out)") — this check fires regardless of
+    // whether a tier:/host-class: key would otherwise have satisfied the
+    // axis requirement. So a rule with `globs: []` never loads in ANY
+    // context, even one paired with `tier: always`. Always warn with the
+    // accurate "dead rule" message here, independent of `hasAxis` — a
+    // co-present tier:/host-class: key cannot rescue an empty globs array
+    // from this unconditional exclusion, so it must not suppress the warning
+    // either (#880 QA Defect 1 fix).
+    warn(
+      `${rel} — handwritten rule has an empty globs/paths array (globs: [] or paths: []) — this rule matches ` +
+        'NOTHING and never loads in ANY context, even one that also carries a tier:/host-class: key ' +
+        '(rule-loader.mjs excludes on globs.length === 0 unconditionally, after gating runs). This is the ' +
+        'OPPOSITE of "always-on". If this is a deliberately disabled rule, consider removing the file instead; ' +
+        'otherwise populate globs:/paths: with real patterns.',
+    );
+  } else if (!hasAxis) {
+    warn(
+      `${rel} — handwritten rule has no activation axis (globs/paths/host-class/tier all absent) — loads ` +
+        'always-on in every context. Not a build failure yet (warn mode, #880); add a tier: or globs: axis ' +
+        'if this rule should be scoped.',
+    );
+  }
+
+  if (!hasReviewDate) {
+    warn(
+      `${rel} — handwritten rule is missing a review-date (no periodic-review marker). ` +
+        'See docs/rule-authoring.md § "Handwritten Rule Review Date (#880 FA5)".',
+    );
+  }
+
+  if (!hasEmptyGlobs && hasAxis && hasReviewDate) {
+    pass(`${rel} — handwritten rule has an activation axis and a review-date`);
+  }
+}
+
+if (handwrittenEntries.length === 0) {
+  // Deliberately NOT routed through pass() — this is bookkeeping, not an
+  // audited invariant, and must not inflate the `passed` count that
+  // auto-generated-only fixtures assert an exact value against.
+  console.log('  (no handwritten rules found — nothing to check)');
+}
+
 console.log('');
-console.log(`Results: ${passed} passed, ${failed} failed`);
+console.log(`Results: ${passed} passed, ${failed} failed, ${warned} warned`);
 
 process.exit(failed > 0 ? 1 : 0);