@indigoai-us/hq-cli 5.98.3 → 5.99.1

package/dist/lib/doctor/checks/runtime-probe.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Runtime probe (US-006): did HQ's hooks actually FIRE in this session?
+ *
+ * Every other hooks check answers "is the configuration correct?". This one
+ * answers the question that correct configuration cannot: "did the host actually
+ * dispatch the hooks it loaded?". `personal-context.md` and
+ * `core/docs/hq/HOOKS-NOT-FIRING.md` document that the Claude Code **app** and
+ * **SDK** runtimes load `.claude/settings.json` correctly and then never
+ * dispatch a single command hook — so a tree that passes every wiring check can
+ * still have zero live enforcement. Only evidence that a hook *ran* can catch
+ * that, and the one durable trace a real dispatch leaves is the policy-trigger
+ * ledger under `workspace/orchestrator/policy-trigger-state/`.
+ *
+ * ## Two layers, on purpose
+ *
+ *   1. {@link reproduceCheckHqHooks} is a faithful TypeScript port of
+ *      `core/scripts/check-hq-hooks.sh --require-ledger`: same settings/wiring
+ *      checks, same ledger rule, same overall pass/fail. It is the piece US-012
+ *      reduces that shell script to a wrapper over, and the piece the agreement
+ *      test pins against the live script. Its verdict is a plain boolean, exactly
+ *      like the script's exit code.
+ *
+ *   2. {@link checkRuntimeProbe} turns that raw verdict into an honest,
+ *      platform-aware doctor result. The raw script FAILs on any missing ledger;
+ *      the doctor is more discerning, because a missing ledger means different
+ *      things on different hosts:
+ *        - app / SDK  → FAIL: those hosts never dispatch, so a missing ledger is
+ *          proof of no enforcement (AC3).
+ *        - unknown    → UNKNOWN: the host could not be identified, so live
+ *          enforcement cannot be claimed either way (AC4) — never PASS, never a
+ *          confident FAIL.
+ *        - CLI / Codex / Grok → UNTESTED: those hosts DO dispatch, so an empty
+ *          ledger just means nothing has triggered a policy hook yet this
+ *          session. "Wired but not yet exercised" is UNTESTED, not a failure.
+ *
+ * The probe is strictly read-only: it stats and reads files and NEVER writes to
+ * the ledger or mutates session state (AC6). Reading it can never manufacture the
+ * very evidence it is looking for.
+ */
+import type { CheckContext, CheckResult } from "../types.js";
+/** Common id prefix for every result the runtime probe emits. */
+export declare const RUNTIME_PROBE_PREFIX = "hooks.runtime";
+/**
+ * The ledger directory, relative to the HQ root. A hook that fires through the
+ * policy-trigger path appends a `<session-id>.txt` file here; its presence is the
+ * one durable proof that dispatch happened. Kept in exact parity with
+ * `check-hq-hooks.sh` (`LEDGER_DIR="$HQ_ROOT/workspace/orchestrator/policy-trigger-state"`).
+ */
+export declare const POLICY_TRIGGER_LEDGER_RELPATH = "workspace/orchestrator/policy-trigger-state";
+/** The two lifecycle events `check-hq-hooks.sh` requires a command hook on. */
+export declare const REQUIRED_HOOK_EVENTS: readonly ["SessionStart", "PreToolUse"];
+/** Whether the ledger was found. Mirrors the script's `present`/`missing`. */
+export type LedgerState = "present" | "missing";
+/** Options for {@link reproduceCheckHqHooks}. */
+export interface ReproduceOptions {
+    /** Absolute HQ tree root to inspect. */
+    hqRoot: string;
+    /**
+     * Scope the ledger check to this exact session (the `--session-id` flag). When
+     * set, only `<sessionId>.txt` counts; an older session's ledger cannot stand in
+     * for the current runtime. When absent, any ledger file suffices, exactly as
+     * the script behaves without `--session-id`.
+     */
+    sessionId?: string;
+}
+/**
+ * The reproduced verdict of `check-hq-hooks.sh --require-ledger`. `ok` is the
+ * boolean twin of the script's exit code: true ⇔ exit 0, false ⇔ exit non-zero.
+ */
+export interface HookLoadReproduction {
+    /** True iff the script would exit 0 (no issues, ledger present). */
+    ok: boolean;
+    /** Whether the (optionally session-scoped) ledger was found. */
+    ledgerState: LedgerState;
+    /** The human-readable issues, mirroring the script's `ISSUES` array. */
+    issues: string[];
+}
+/**
+ * Faithfully reproduce `core/scripts/check-hq-hooks.sh --require-ledger` in
+ * TypeScript. The checks, in the script's order:
+ *
+ *   1. `.claude/settings.json` present and valid JSON.
+ *   2. A `type: "command"` hook on both SessionStart and PreToolUse.
+ *   3. No hook command word-splits `$CLAUDE_PROJECT_DIR` (the quote-aware scan
+ *      shared with the Claude wiring tier), and every script a command actually
+ *      runs exists on disk.
+ *   4. The optional `.claude/settings.local.json` overlay, when present, is valid
+ *      JSON and passes the same command scan.
+ *   5. The policy-trigger ledger exists (session-scoped when `sessionId` is set).
+ *
+ * Never throws: an unreadable or malformed input becomes an issue, not an
+ * exception, so the probe degrades exactly like the defensively-written script.
+ */
+export declare function reproduceCheckHqHooks(opts: ReproduceOptions): HookLoadReproduction;
+/**
+ * The runtime-probe check family entry. Reproduces the script verdict, then
+ * renders it as a single platform-aware doctor result. See the module header for
+ * the per-platform status rationale.
+ */
+export declare function checkRuntimeProbe(context: CheckContext): CheckResult[];
+//# sourceMappingURL=runtime-probe.d.ts.map

package/dist/lib/doctor/checks/runtime-probe.js

@@ -0,0 +1,335 @@
+/**
+ * Runtime probe (US-006): did HQ's hooks actually FIRE in this session?
+ *
+ * Every other hooks check answers "is the configuration correct?". This one
+ * answers the question that correct configuration cannot: "did the host actually
+ * dispatch the hooks it loaded?". `personal-context.md` and
+ * `core/docs/hq/HOOKS-NOT-FIRING.md` document that the Claude Code **app** and
+ * **SDK** runtimes load `.claude/settings.json` correctly and then never
+ * dispatch a single command hook — so a tree that passes every wiring check can
+ * still have zero live enforcement. Only evidence that a hook *ran* can catch
+ * that, and the one durable trace a real dispatch leaves is the policy-trigger
+ * ledger under `workspace/orchestrator/policy-trigger-state/`.
+ *
+ * ## Two layers, on purpose
+ *
+ *   1. {@link reproduceCheckHqHooks} is a faithful TypeScript port of
+ *      `core/scripts/check-hq-hooks.sh --require-ledger`: same settings/wiring
+ *      checks, same ledger rule, same overall pass/fail. It is the piece US-012
+ *      reduces that shell script to a wrapper over, and the piece the agreement
+ *      test pins against the live script. Its verdict is a plain boolean, exactly
+ *      like the script's exit code.
+ *
+ *   2. {@link checkRuntimeProbe} turns that raw verdict into an honest,
+ *      platform-aware doctor result. The raw script FAILs on any missing ledger;
+ *      the doctor is more discerning, because a missing ledger means different
+ *      things on different hosts:
+ *        - app / SDK  → FAIL: those hosts never dispatch, so a missing ledger is
+ *          proof of no enforcement (AC3).
+ *        - unknown    → UNKNOWN: the host could not be identified, so live
+ *          enforcement cannot be claimed either way (AC4) — never PASS, never a
+ *          confident FAIL.
+ *        - CLI / Codex / Grok → UNTESTED: those hosts DO dispatch, so an empty
+ *          ledger just means nothing has triggered a policy hook yet this
+ *          session. "Wired but not yet exercised" is UNTESTED, not a failure.
+ *
+ * The probe is strictly read-only: it stats and reads files and NEVER writes to
+ * the ledger or mutates session state (AC6). Reading it can never manufacture the
+ * very evidence it is looking for.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { scanHookCommand } from "./claude-wiring.js";
+/** Common id prefix for every result the runtime probe emits. */
+export const RUNTIME_PROBE_PREFIX = "hooks.runtime";
+/**
+ * The ledger directory, relative to the HQ root. A hook that fires through the
+ * policy-trigger path appends a `<session-id>.txt` file here; its presence is the
+ * one durable proof that dispatch happened. Kept in exact parity with
+ * `check-hq-hooks.sh` (`LEDGER_DIR="$HQ_ROOT/workspace/orchestrator/policy-trigger-state"`).
+ */
+export const POLICY_TRIGGER_LEDGER_RELPATH = "workspace/orchestrator/policy-trigger-state";
+/** The two lifecycle events `check-hq-hooks.sh` requires a command hook on. */
+export const REQUIRED_HOOK_EVENTS = ["SessionStart", "PreToolUse"];
+/**
+ * Faithfully reproduce `core/scripts/check-hq-hooks.sh --require-ledger` in
+ * TypeScript. The checks, in the script's order:
+ *
+ *   1. `.claude/settings.json` present and valid JSON.
+ *   2. A `type: "command"` hook on both SessionStart and PreToolUse.
+ *   3. No hook command word-splits `$CLAUDE_PROJECT_DIR` (the quote-aware scan
+ *      shared with the Claude wiring tier), and every script a command actually
+ *      runs exists on disk.
+ *   4. The optional `.claude/settings.local.json` overlay, when present, is valid
+ *      JSON and passes the same command scan.
+ *   5. The policy-trigger ledger exists (session-scoped when `sessionId` is set).
+ *
+ * Never throws: an unreadable or malformed input becomes an issue, not an
+ * exception, so the probe degrades exactly like the defensively-written script.
+ */
+export function reproduceCheckHqHooks(opts) {
+    const { hqRoot, sessionId } = opts;
+    const issues = [];
+    const rootHasSpace = /\s/.test(hqRoot);
+    const settingsPath = path.join(hqRoot, ".claude", "settings.json");
+    const localPath = path.join(hqRoot, ".claude", "settings.local.json");
+    // --- 1 + 2 + 3: the shipped settings file -----------------------------------
+    const base = readJson(settingsPath);
+    if (!base.present) {
+        issues.push(".claude/settings.json is missing");
+    }
+    else if (base.invalid) {
+        issues.push(".claude/settings.json is not valid JSON");
+    }
+    else {
+        for (const event of REQUIRED_HOOK_EVENTS) {
+            if (!hasCommandHook(base.value, event)) {
+                issues.push(`${event} has no command hook in .claude/settings.json`);
+            }
+        }
+        scanSettingsFile(base.value, ".claude/settings.json", hqRoot, rootHasSpace, issues);
+    }
+    // --- 4: the optional local overlay ------------------------------------------
+    // Its absence is never an issue, but when present Claude Code merges its hooks
+    // in, so a command hiding there fails a spaced root exactly like a shipped one.
+    const local = readJson(localPath);
+    if (local.present) {
+        if (local.invalid) {
+            issues.push(".claude/settings.local.json is not valid JSON");
+        }
+        else {
+            scanSettingsFile(local.value, ".claude/settings.local.json", hqRoot, rootHasSpace, issues);
+        }
+    }
+    // --- 5: the policy-trigger ledger -------------------------------------------
+    const ledgerState = resolveLedgerState(hqRoot, sessionId);
+    if (ledgerState === "missing") {
+        issues.push(sessionId
+            ? `policy-trigger ledger was not found for session ${sessionId} under ${POLICY_TRIGGER_LEDGER_RELPATH}`
+            : `policy-trigger ledger was not found under ${POLICY_TRIGGER_LEDGER_RELPATH}`);
+    }
+    return { ok: issues.length === 0, ledgerState, issues };
+}
+/**
+ * The runtime-probe check family entry. Reproduces the script verdict, then
+ * renders it as a single platform-aware doctor result. See the module header for
+ * the per-platform status rationale.
+ */
+export function checkRuntimeProbe(context) {
+    const hqRoot = context.hqRoot;
+    const sessionId = context.sessionId;
+    const platformId = context.platform?.id ?? "unknown";
+    const checkId = `${RUNTIME_PROBE_PREFIX}.enforcement`;
+    const target = POLICY_TRIGGER_LEDGER_RELPATH;
+    const scope = sessionId ? ` for session ${sessionId}` : "";
+    const repro = reproduceCheckHqHooks({ hqRoot, sessionId });
+    // Unknown host: the label cannot be trusted, so live enforcement cannot be
+    // verified in either direction. UNKNOWN (never PASS or FAIL) is the honest
+    // verdict and, per the exit-code contract, still draws the user's attention.
+    if (platformId === "unknown") {
+        return [
+            {
+                status: "UNKNOWN",
+                checkId,
+                target,
+                message: `Host platform is unknown, so whether hooks actually dispatched this ` +
+                    `session cannot be verified — the policy-trigger ledger is ${repro.ledgerState}${scope}. ` +
+                    `Not reporting hook enforcement as working.`,
+                remediation: `Run hq doctor from the terminal Claude Code CLI (pass --session-id on ` +
+                    `an app/SDK host) for a definitive runtime verdict.`,
+            },
+        ];
+    }
+    // Ledger present ⇒ a hook demonstrably fired this session ⇒ enforcement is live.
+    if (repro.ledgerState === "present") {
+        return [
+            {
+                status: "PASS",
+                checkId,
+                target,
+                message: `Hook dispatch was observed this session: the policy-trigger ledger has an entry${scope}.`,
+            },
+        ];
+    }
+    // Ledger missing on a non-dispatching host is proof, not ambiguity: the app and
+    // SDK runtimes load hook config and never fire it. This is the one failure the
+    // whole probe exists to surface.
+    if (platformId === "claude-code-app" || platformId === "claude-code-sdk") {
+        const host = platformId === "claude-code-app" ? "Claude Code app" : "Claude Code SDK";
+        return [
+            {
+                status: "FAIL",
+                checkId,
+                target,
+                message: `Hook enforcement is NOT observed: no policy-trigger ledger entry exists${scope} and this host ` +
+                    `is the ${host} runtime, which does not dispatch command hooks. Correct-looking hook ` +
+                    `configuration is not working enforcement here.`,
+                remediation: `Use the terminal Claude Code CLI for hook-enforced work (see ` +
+                    `core/docs/hq/HOOKS-NOT-FIRING.md). Verify with: ` +
+                    `bash core/scripts/check-hq-hooks.sh --root "$PWD" --require-ledger.`,
+            },
+        ];
+    }
+    // Dispatching host (CLI / Codex / Grok) with an empty ledger: hooks are wired
+    // and this host does fire them, but nothing has triggered a policy hook yet
+    // this session. Wired-but-not-yet-exercised is UNTESTED, never a failure.
+    return [
+        {
+            status: "UNTESTED",
+            checkId,
+            target,
+            message: `Hooks are wired but dispatch has not been observed yet: the policy-trigger ledger has no ` +
+                `entry${scope}. This host (${platformId}) does dispatch hooks, so trigger a policy-gated action ` +
+                `and re-check to confirm live enforcement.`,
+            remediation: `After a real action, verify with: bash core/scripts/check-hq-hooks.sh --root "$PWD" ` +
+                `--require-ledger${sessionId ? ` --session-id ${sessionId}` : ""}.`,
+        },
+    ];
+}
+// --- ledger ------------------------------------------------------------------
+/**
+ * Resolve whether the ledger counts as present. Session-scoped: only
+ * `<sessionId>.txt` counts. Unscoped: any `*.txt` anywhere under the ledger
+ * directory counts, matching the script's recursive `find -type f -name '*.txt'`.
+ */
+function resolveLedgerState(hqRoot, sessionId) {
+    const ledgerDir = path.join(hqRoot, ...POLICY_TRIGGER_LEDGER_RELPATH.split("/"));
+    if (sessionId) {
+        return isFile(path.join(ledgerDir, `${sessionId}.txt`))
+            ? "present"
+            : "missing";
+    }
+    return ledgerDirHasTxt(ledgerDir) ? "present" : "missing";
+}
+/** True when any `*.txt` file exists anywhere under `dir` (recursive). */
+function ledgerDirHasTxt(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (ledgerDirHasTxt(full))
+                return true;
+        }
+        else if (entry.isFile() && entry.name.endsWith(".txt")) {
+            return true;
+        }
+    }
+    return false;
+}
+// --- settings inspection -----------------------------------------------------
+/**
+ * Scan every command hook in one parsed settings object: count the commands that
+ * word-split `$CLAUDE_PROJECT_DIR`, and check that every script a command
+ * actually runs exists on disk. Appends to `issues`, mirroring the script's
+ * `scan_hook_commands`.
+ */
+function scanSettingsFile(settings, label, hqRoot, rootHasSpace, issues) {
+    const commands = enumerateCommands(settings);
+    const scans = commands.map((command) => scanHookCommand(command));
+    const unquoted = scans.filter((scan) => scan.unquotedProjectDir).length;
+    if (unquoted > 0) {
+        issues.push(rootHasSpace
+            ? `${unquoted} hook command(s) in ${label} reference $CLAUDE_PROJECT_DIR without quotes and this HQ root contains a space, so /bin/sh splits the path and every one of those hooks is failing right now: ${hqRoot}`
+            : `${unquoted} hook command(s) in ${label} reference $CLAUDE_PROJECT_DIR without quotes; they break on any install path containing a space`);
+    }
+    const required = new Set();
+    for (const scan of scans) {
+        for (const rp of scan.requiredRelpaths)
+            required.add(rp);
+    }
+    for (const rp of [...required].sort()) {
+        if (!fs.existsSync(path.join(hqRoot, rp))) {
+            issues.push(`a hook command in ${label} runs a script that does not exist: ${rp}`);
+        }
+    }
+}
+/**
+ * Whether `settings.hooks[event]` carries at least one non-empty `type:
+ * "command"` hook. Tolerant of every malformed shape — a non-conforming branch
+ * simply does not count.
+ */
+function hasCommandHook(settings, event) {
+    const entries = hookEntriesFor(settings, event);
+    for (const entry of entries) {
+        const inner = entry?.hooks;
+        if (!Array.isArray(inner))
+            continue;
+        for (const item of inner) {
+            const hook = item;
+            if (hook?.type === "command" &&
+                typeof hook.command === "string" &&
+                hook.command.length > 0) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/** Every non-empty command string across every lifecycle event in `settings`. */
+function enumerateCommands(settings) {
+    const out = [];
+    const hooks = hooksObject(settings);
+    if (!hooks)
+        return out;
+    for (const entries of Object.values(hooks)) {
+        if (!Array.isArray(entries))
+            continue;
+        for (const entry of entries) {
+            const inner = entry?.hooks;
+            if (!Array.isArray(inner))
+                continue;
+            for (const item of inner) {
+                const hook = item;
+                if (hook?.type === "command" &&
+                    typeof hook.command === "string" &&
+                    hook.command.length > 0) {
+                    out.push(hook.command);
+                }
+            }
+        }
+    }
+    return out;
+}
+function hookEntriesFor(settings, event) {
+    const hooks = hooksObject(settings);
+    const entries = hooks?.[event];
+    return Array.isArray(entries) ? entries : [];
+}
+function hooksObject(settings) {
+    if (!settings || typeof settings !== "object")
+        return null;
+    const hooks = settings.hooks;
+    if (!hooks || typeof hooks !== "object")
+        return null;
+    return hooks;
+}
+function readJson(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return { present: false };
+    }
+    try {
+        return { present: true, value: JSON.parse(raw) };
+    }
+    catch {
+        return { present: true, invalid: true };
+    }
+}
+function isFile(file) {
+    try {
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=runtime-probe.js.map

package/dist/lib/doctor/compat.d.ts

@@ -0,0 +1,85 @@
+/**
+ * check-hq-hooks.sh ⇄ `hq doctor` compatibility (US-012).
+ *
+ * US-012 reduces `core/scripts/check-hq-hooks.sh` to a thin wrapper over
+ * `hq doctor`, so HQ has ONE answer to "are my hooks working" instead of four
+ * partially-overlapping tools. The wrapper must, however, keep its narrow
+ * contract intact (AC1): the same PASS/FAIL header, the same
+ * `HQ runtime enforcement: OBSERVED / NOT OBSERVED` line the app/SDK safety
+ * instruction in `personal-context.md` greps for, and the same 0/2 exit codes —
+ * and it must degrade to its inline implementation when the `hq` CLI is absent
+ * or too old (AC2), because it exists precisely to run when the toolchain is
+ * suspect.
+ *
+ * The wrapper therefore does NOT adopt the full `hq doctor` verdict: the doctor
+ * is a strict superset (Codex/Grok parity, three-profile membership, exec bits,
+ * fixture coverage) and reports the known Codex drift as FAIL on a healthy tree,
+ * which would break every existing check-hq-hooks caller. Instead it maps a
+ * *scoped* slice of the doctor's JSON — exactly the checks check-hq-hooks
+ * originally performed (settings load + the policy-trigger ledger) — back onto
+ * its own contract.
+ *
+ * This module is that scope and mapping, as one tested TypeScript reference. The
+ * shell wrapper mirrors it in bash (`jq` over `hq doctor --json`); the agreement
+ * test (`compat.test.ts`) pins the real wrapper's exit code and output against
+ * both this reference and the live `hq doctor` on healthy and broken fake trees.
+ * It is the same "two implementations, one contract, pinned by a test" pattern
+ * that `reproduceCheckHqHooks` (US-006) uses in the other direction.
+ */
+import type { DoctorJsonDocument } from "./json-output.js";
+/** Exit code check-hq-hooks.sh returns on success. Preserved by the wrapper. */
+export declare const CHECK_HQ_HOOKS_PASS_EXIT = 0;
+/** Exit code check-hq-hooks.sh returns on a health failure. Preserved. */
+export declare const CHECK_HQ_HOOKS_FAIL_EXIT = 2;
+/** Exit code check-hq-hooks.sh returns on a usage error. Preserved. */
+export declare const CHECK_HQ_HOOKS_USAGE_EXIT = 64;
+/** The runtime-probe result id: whether hooks actually fired (the ledger). */
+export declare const RUNTIME_ENFORCEMENT_CHECK_ID = "hooks.runtime.enforcement";
+/**
+ * The `hq doctor` check ids that correspond to check-hq-hooks.sh's *settings
+ * load* scope — the subset of the hooks family the wrapper is allowed to fail
+ * on. Deliberately narrow: it covers a missing/invalid settings file, an
+ * unquoted `$CLAUDE_PROJECT_DIR` that word-splits on a spaced root, and a hook
+ * command that runs a script which is not on disk — and nothing else. The many
+ * richer doctor findings (executable bits, orphaned scripts, three-profile
+ * membership, Codex/Grok parity, fixture coverage) are intentionally OUT of
+ * scope, so the wrapper stays byte-for-byte compatible with callers that only
+ * ever cared whether the hook configuration could load.
+ */
+export declare const CHECK_HQ_HOOKS_SETTINGS_SCOPE: readonly string[];
+/**
+ * Whether hook dispatch was observed this session. Mirrors the wrapper's
+ * `HQ runtime enforcement: …` line. `NOT CHECKED` is the default when
+ * `--require-ledger` was not passed (the wrapper prints "ledger: not checked").
+ */
+export type RuntimeObservation = "OBSERVED" | "NOT OBSERVED" | "NOT CHECKED";
+/** The verdict the wrapper renders, derived from a scoped `hq doctor` run. */
+export interface CheckHqHooksVerdict {
+    /** True iff the wrapper exits 0 (no in-scope failure, ledger observed when required). */
+    ok: boolean;
+    /** The exit code the wrapper returns: 0 on pass, 2 on failure. */
+    exitCode: number;
+    /** The `HQ hook health: …` header value. */
+    hookHealth: "PASS" | "FAIL";
+    /** The `HQ runtime enforcement: …` observation. */
+    runtime: RuntimeObservation;
+    /** The failing messages, in the wrapper's `  - <message>` bullet form. */
+    issues: string[];
+}
+/** Options for {@link deriveCheckHqHooksVerdict}. */
+export interface DeriveVerdictOptions {
+    /**
+     * Whether `--require-ledger` (or `--session-id`, which implies it) was passed.
+     * When true, an unobserved policy-trigger ledger is a failure, exactly as the
+     * inline script treats a missing ledger — regardless of platform.
+     */
+    requireLedger?: boolean;
+}
+/**
+ * Derive the check-hq-hooks.sh verdict from a `hq doctor --json` document,
+ * scoped to check-hq-hooks' original concerns. This is the exact logic the
+ * shell wrapper reproduces with `jq`; keeping it here as one tested function is
+ * what lets `compat.test.ts` prove the wrapper and `hq doctor` agree.
+ */
+export declare function deriveCheckHqHooksVerdict(doc: DoctorJsonDocument, options?: DeriveVerdictOptions): CheckHqHooksVerdict;
+//# sourceMappingURL=compat.d.ts.map

package/dist/lib/doctor/compat.js

@@ -0,0 +1,102 @@
+/**
+ * check-hq-hooks.sh ⇄ `hq doctor` compatibility (US-012).
+ *
+ * US-012 reduces `core/scripts/check-hq-hooks.sh` to a thin wrapper over
+ * `hq doctor`, so HQ has ONE answer to "are my hooks working" instead of four
+ * partially-overlapping tools. The wrapper must, however, keep its narrow
+ * contract intact (AC1): the same PASS/FAIL header, the same
+ * `HQ runtime enforcement: OBSERVED / NOT OBSERVED` line the app/SDK safety
+ * instruction in `personal-context.md` greps for, and the same 0/2 exit codes —
+ * and it must degrade to its inline implementation when the `hq` CLI is absent
+ * or too old (AC2), because it exists precisely to run when the toolchain is
+ * suspect.
+ *
+ * The wrapper therefore does NOT adopt the full `hq doctor` verdict: the doctor
+ * is a strict superset (Codex/Grok parity, three-profile membership, exec bits,
+ * fixture coverage) and reports the known Codex drift as FAIL on a healthy tree,
+ * which would break every existing check-hq-hooks caller. Instead it maps a
+ * *scoped* slice of the doctor's JSON — exactly the checks check-hq-hooks
+ * originally performed (settings load + the policy-trigger ledger) — back onto
+ * its own contract.
+ *
+ * This module is that scope and mapping, as one tested TypeScript reference. The
+ * shell wrapper mirrors it in bash (`jq` over `hq doctor --json`); the agreement
+ * test (`compat.test.ts`) pins the real wrapper's exit code and output against
+ * both this reference and the live `hq doctor` on healthy and broken fake trees.
+ * It is the same "two implementations, one contract, pinned by a test" pattern
+ * that `reproduceCheckHqHooks` (US-006) uses in the other direction.
+ */
+/** Exit code check-hq-hooks.sh returns on success. Preserved by the wrapper. */
+export const CHECK_HQ_HOOKS_PASS_EXIT = 0;
+/** Exit code check-hq-hooks.sh returns on a health failure. Preserved. */
+export const CHECK_HQ_HOOKS_FAIL_EXIT = 2;
+/** Exit code check-hq-hooks.sh returns on a usage error. Preserved. */
+export const CHECK_HQ_HOOKS_USAGE_EXIT = 64;
+/** The runtime-probe result id: whether hooks actually fired (the ledger). */
+export const RUNTIME_ENFORCEMENT_CHECK_ID = "hooks.runtime.enforcement";
+/**
+ * The `hq doctor` check ids that correspond to check-hq-hooks.sh's *settings
+ * load* scope — the subset of the hooks family the wrapper is allowed to fail
+ * on. Deliberately narrow: it covers a missing/invalid settings file, an
+ * unquoted `$CLAUDE_PROJECT_DIR` that word-splits on a spaced root, and a hook
+ * command that runs a script which is not on disk — and nothing else. The many
+ * richer doctor findings (executable bits, orphaned scripts, three-profile
+ * membership, Codex/Grok parity, fixture coverage) are intentionally OUT of
+ * scope, so the wrapper stays byte-for-byte compatible with callers that only
+ * ever cared whether the hook configuration could load.
+ */
+export const CHECK_HQ_HOOKS_SETTINGS_SCOPE = [
+    "hooks.settings-present",
+    "hooks.settings-valid-json",
+    "hooks.claude.settings-local-valid-json",
+    "hooks.claude.unquoted-project-dir",
+    "hooks.claude.script-missing",
+];
+/** The doctor statuses that count as a failure for check-hq-hooks' purposes. */
+const FAILING_STATUSES = new Set([
+    "FAIL",
+    "UNKNOWN",
+]);
+/**
+ * Derive the check-hq-hooks.sh verdict from a `hq doctor --json` document,
+ * scoped to check-hq-hooks' original concerns. This is the exact logic the
+ * shell wrapper reproduces with `jq`; keeping it here as one tested function is
+ * what lets `compat.test.ts` prove the wrapper and `hq doctor` agree.
+ */
+export function deriveCheckHqHooksVerdict(doc, options = {}) {
+    const requireLedger = options.requireLedger === true;
+    const scope = new Set(CHECK_HQ_HOOKS_SETTINGS_SCOPE);
+    const messages = [];
+    // Settings-load concern: any in-scope result that FAILs or is UNKNOWN.
+    for (const result of doc.results) {
+        if (scope.has(result.checkId) && FAILING_STATUSES.has(result.status)) {
+            messages.push(result.message);
+        }
+    }
+    // Runtime/ledger concern: only checked under --require-ledger. The runtime
+    // probe reports PASS only when a hook demonstrably fired this session; any
+    // other status (UNTESTED on a dispatching host, FAIL on app/SDK, UNKNOWN on an
+    // unidentifiable host) means dispatch was not observed — which is a failure
+    // for --require-ledger, matching the inline script's "fail on a missing
+    // ledger" contract.
+    const runtimeResult = doc.results.find((result) => result.checkId === RUNTIME_ENFORCEMENT_CHECK_ID);
+    const runtime = observeRuntime(runtimeResult?.status, requireLedger);
+    if (requireLedger && runtime !== "OBSERVED") {
+        messages.push(runtimeResult?.message ??
+            "policy-trigger ledger was not found under workspace/orchestrator/policy-trigger-state");
+    }
+    const ok = messages.length === 0;
+    return {
+        ok,
+        exitCode: ok ? CHECK_HQ_HOOKS_PASS_EXIT : CHECK_HQ_HOOKS_FAIL_EXIT,
+        hookHealth: ok ? "PASS" : "FAIL",
+        runtime,
+        issues: messages.map((message) => `  - ${message}`),
+    };
+}
+function observeRuntime(status, requireLedger) {
+    if (!requireLedger)
+        return "NOT CHECKED";
+    return status === "PASS" ? "OBSERVED" : "NOT OBSERVED";
+}
+//# sourceMappingURL=compat.js.map