@indigoai-us/hq-cli 5.98.2 → 5.99.0

package/dist/lib/doctor/fix/apply.js

@@ -0,0 +1,352 @@
+/**
+ * `hq doctor --fix` — apply the allowlisted safe repairs (US-011).
+ *
+ * Read-by-default is the doctor's whole safety posture, so the write path is
+ * wrapped in guardrails that are NOT polish — each is a PRD acceptance criterion:
+ *
+ *   1. Dirty-tree refusal. If the working tree has uncommitted changes under
+ *      `.claude/`, `.codex/`, or `.grok/`, `--fix` refuses and exits non-zero
+ *      unless `--force`, so a repair can never be tangled up with unrelated
+ *      in-flight edits to the security layer.
+ *   2. Allowlist only. It repairs exactly three classes — restore an execute
+ *      bit, add a hook id to the gate profiles it is missing from, re-register a
+ *      script present on disk — and NEVER rewrites a hook body or deletes a file.
+ *      Classification is owned by {@link deriveRemediation}; a content-drift
+ *      finding is manual-only and simply never appears in the fixable set.
+ *   3. Preview + confirmation. Every change is shown diff-style and requires
+ *      confirmation, with `--yes` for non-interactive use.
+ *   4. Backup first. Before any write, the affected files are copied under
+ *      `workspace/doctor/backups/<timestamp>/` and the restore command is
+ *      printed on completion.
+ *   5. Re-verify. After applying, the affected checks are re-run and their
+ *      post-fix status reported, so the user sees the real result rather than an
+ *      assumed success.
+ *
+ * The applier resolves nothing about the host: the caller passes the HQ root
+ * (the command resolves it once), keeping this module decoupled from the CLI and
+ * trivially testable against a fake tree.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createDefaultRegistry } from "../registry.js";
+import { flattenFamilies } from "../report.js";
+import { gateMembership, parseHookGateProfiles, } from "../hook-gate-profiles.js";
+import { createBackup } from "./backup.js";
+import { deriveRemediation } from "./remediation.js";
+/** The tree subtrees whose uncommitted changes block a `--fix` run. */
+export const HOOK_CONFIG_DIRS = [".claude", ".codex", ".grok"];
+/**
+ * Apply every auto-fixable finding, honouring the dirty-tree refusal, the
+ * preview/confirmation gate, the pre-write backup, and the post-fix re-check.
+ * Returns a structured result rather than throwing so both the CLI and tests can
+ * assert on it.
+ */
+export async function applyFixes(options) {
+    const write = options.stdout ?? ((chunk) => void process.stdout.write(chunk));
+    const writeErr = options.stderr ?? ((chunk) => void process.stderr.write(chunk));
+    const hqRoot = options.hqRoot;
+    const empty = (over = {}) => ({
+        exitCode: 0,
+        wrote: false,
+        refused: null,
+        fixableCount: 0,
+        backupDir: null,
+        restoreCommand: null,
+        applied: [],
+        ...over,
+    });
+    // 1. Dirty-tree refusal (AC8). Never write over uncommitted security-layer
+    //    edits unless the user forces it.
+    if (!options.force) {
+        const dirty = (options.dirtyCheck ?? uncommittedHookConfigChanges)(hqRoot);
+        if (dirty.length > 0) {
+            writeErr(`hq doctor --fix: refusing to run — uncommitted changes under ` +
+                `${HOOK_CONFIG_DIRS.join(", ")}:\n` +
+                dirty.map((line) => `  ${line}`).join("\n") +
+                `\nCommit or stash them, or re-run with --force.\n`);
+            return empty({ exitCode: 1, refused: "dirty-tree" });
+        }
+    }
+    // 2. Collect findings and keep only the allowlisted auto-fixable ones.
+    const findings = await runChecks(hqRoot);
+    const fixable = [];
+    for (const result of findings) {
+        const rem = deriveRemediation(result);
+        if (rem && rem.autoFixable)
+            fixable.push({ result, rem });
+    }
+    if (fixable.length === 0) {
+        write("hq doctor --fix: nothing to repair — no auto-fixable findings.\n");
+        return empty();
+    }
+    const plans = fixable
+        .map(({ result, rem }) => planFix(hqRoot, result, rem))
+        .filter((plan) => plan !== null);
+    if (plans.length === 0) {
+        write("hq doctor --fix: nothing to repair — no auto-fixable findings.\n");
+        return empty();
+    }
+    // 3. Diff-style preview + confirmation (AC5).
+    write(`hq doctor --fix will apply ${plans.length} repair${plans.length === 1 ? "" : "s"}:\n\n`);
+    for (const plan of plans)
+        write(plan.preview + "\n");
+    if (!options.yes) {
+        const confirmed = await Promise.resolve((options.confirm ?? declineByDefault)());
+        if (!confirmed) {
+            write("Aborted — no changes written.\n");
+            return empty({ refused: "declined" });
+        }
+    }
+    // 4. Back up every file about to change BEFORE the first write (AC6).
+    const affected = unique(plans.map((plan) => plan.relpath));
+    const backup = createBackup(hqRoot, affected, options.now);
+    // 5. Apply. Each plan reads the current on-disk state, so multiple plans that
+    //    touch the same file (two gate ids) compose correctly.
+    for (const plan of plans)
+        plan.apply();
+    write(`\nBacked up ${backup.files.length} file${backup.files.length === 1 ? "" : "s"} to ${backup.dir}\n`);
+    write(`To restore: ${backup.restoreCommand}\n`);
+    // 6. Re-run the checks and report the post-fix status of each repair (AC7).
+    const after = await runChecks(hqRoot);
+    const applied = plans.map((plan) => ({
+        checkId: plan.checkId,
+        fixClass: plan.fixClass,
+        target: plan.target,
+        summary: plan.summary,
+        postStatus: plan.postStatus(after),
+    }));
+    write("\nPost-fix status:\n");
+    for (const fix of applied) {
+        write(`  ${fix.postStatus ?? "UNKNOWN"}  ${fix.checkId} [${fix.target}]\n`);
+    }
+    return {
+        exitCode: 0,
+        wrote: true,
+        refused: null,
+        fixableCount: fixable.length,
+        backupDir: backup.dir,
+        restoreCommand: backup.restoreCommand,
+        applied,
+    };
+}
+/** Run the default (read-only) check registry and flatten to a result list. */
+async function runChecks(hqRoot) {
+    const context = { hqRoot, platform: { id: "unknown" } };
+    const families = await createDefaultRegistry().run(context);
+    return flattenFamilies(families);
+}
+// --- Dirty-tree probe ----------------------------------------------------------
+/**
+ * The uncommitted changes under {@link HOOK_CONFIG_DIRS}, one porcelain line
+ * each. Returns [] when the tree is clean OR when `hqRoot` is not a git repo
+ * (git exits non-zero): with no VCS there is no in-flight change to protect, and
+ * the backup still covers the write.
+ */
+export function uncommittedHookConfigChanges(hqRoot) {
+    const result = spawnSync("git", ["-C", hqRoot, "status", "--porcelain", "--", ...HOOK_CONFIG_DIRS], { encoding: "utf8" });
+    if (result.error || result.status !== 0 || typeof result.stdout !== "string") {
+        return [];
+    }
+    return result.stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+// --- Fix planning --------------------------------------------------------------
+/** Build the concrete plan for one auto-fixable finding, or null if unplannable. */
+function planFix(hqRoot, result, rem) {
+    switch (rem.fixClass) {
+        case "executable-bit":
+            return planExecutableBit(hqRoot, result, rem);
+        case "gate-profile":
+            return planGateProfile(hqRoot, result, rem);
+        case "register-hook":
+            return planRegisterHook(hqRoot, result, rem);
+        default:
+            return null;
+    }
+}
+/** Restore the execute bit on a hook script. */
+function planExecutableBit(hqRoot, result, rem) {
+    const abs = rem.fixTarget;
+    if (!abs)
+        return null;
+    let beforeMode;
+    try {
+        beforeMode = fs.statSync(abs).mode & 0o777;
+    }
+    catch {
+        return null; // Script vanished between check and fix; skip rather than fail.
+    }
+    const afterMode = beforeMode | 0o111;
+    const relpath = toRelpath(hqRoot, abs);
+    return {
+        checkId: result.checkId,
+        fixClass: "executable-bit",
+        target: abs,
+        relpath,
+        preview: `  ${relpath}\n` +
+            `    - mode ${octal(beforeMode)}\n` +
+            `    + mode ${octal(afterMode)} (restore executable bit)`,
+        summary: `chmod +x ${relpath}`,
+        apply: () => fs.chmodSync(abs, afterMode),
+        postStatus: (results) => statusForPath(results, abs),
+    };
+}
+/** Add a gated hook id to the `hook-gate.sh` profiles it is missing from. */
+function planGateProfile(hqRoot, result, rem) {
+    const hookId = rem.fixTarget;
+    if (!hookId)
+        return null;
+    const gatePath = path.join(hqRoot, ".claude", "hooks", "hook-gate.sh");
+    let source;
+    try {
+        source = fs.readFileSync(gatePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const missing = gateMembership(hookId, parseHookGateProfiles(source)).missing;
+    if (missing.length === 0)
+        return null;
+    const relpath = toRelpath(hqRoot, gatePath);
+    const preview = `  ${relpath}\n` +
+        missing
+            .map((profile) => `    + is_in_${profile}_profile: allow "${hookId}" (return 0)`)
+            .join("\n");
+    return {
+        checkId: result.checkId,
+        fixClass: "gate-profile",
+        target: hookId,
+        relpath,
+        preview,
+        summary: `add ${hookId} to ${missing.join(", ")} in hook-gate.sh`,
+        apply: () => {
+            const current = fs.readFileSync(gatePath, "utf8");
+            const updated = addHookIdToGateProfiles(current, hookId, missing);
+            fs.writeFileSync(gatePath, updated);
+        },
+        postStatus: (results) => statusForTarget(results, ".gate-profiles", hookId),
+    };
+}
+/** Re-register a script that is present on disk but wired in no settings file. */
+function planRegisterHook(hqRoot, result, rem) {
+    const scriptAbs = rem.fixTarget;
+    if (!scriptAbs)
+        return null;
+    const settingsPath = path.join(hqRoot, ".claude", "settings.json");
+    const hookId = path.basename(scriptAbs).replace(/\.sh$/, "");
+    const event = "PreToolUse";
+    const command = `bash "$CLAUDE_PROJECT_DIR/.claude/hooks/hook-gate.sh" ${hookId} ` +
+        `"$CLAUDE_PROJECT_DIR/.claude/hooks/${hookId}.sh"`;
+    const relpath = toRelpath(hqRoot, settingsPath);
+    return {
+        checkId: result.checkId,
+        fixClass: "register-hook",
+        target: scriptAbs,
+        relpath,
+        preview: `  ${relpath}\n` +
+            `    + hooks.${event}: register ${hookId} via hook-gate.sh\n` +
+            `      ${command}`,
+        summary: `register ${hookId} on ${event}`,
+        apply: () => {
+            const settings = readJson(settingsPath) ?? {};
+            const updated = registerHookInSettings(settings, event, command);
+            fs.writeFileSync(settingsPath, JSON.stringify(updated, null, 2) + "\n");
+        },
+        // After registration the script becomes a wired, executable file, reported
+        // by the Claude wiring tier's `…script` PASS keyed on the same path.
+        postStatus: (results) => statusForPath(results, scriptAbs),
+    };
+}
+// --- Shell / JSON edit primitives ---------------------------------------------
+/**
+ * Insert a new `case` arm allowlisting `hookId` (leading to `return 0`) at the
+ * top of each named profile function's `case "$1" in` block. Additive: it never
+ * rewrites an existing arm, so an id already present in another profile is
+ * untouched and the parser recognises the new arm exactly as it would a
+ * hand-written one. A profile whose function or case block cannot be located is
+ * left unchanged rather than corrupted.
+ */
+export function addHookIdToGateProfiles(source, hookId, profiles) {
+    let output = source;
+    for (const profile of profiles) {
+        output = insertProfileArm(output, profile, hookId);
+    }
+    return output;
+}
+function insertProfileArm(source, profile, hookId) {
+    const fnMatch = new RegExp(`is_in_${profile}_profile\\s*\\(\\)\\s*\\{`).exec(source);
+    if (!fnMatch)
+        return source;
+    const afterFn = fnMatch.index + fnMatch[0].length;
+    const region = source.slice(afterFn);
+    const caseMatch = /case\s+"\$(?:1|HOOK_ID)"\s+in[^\n]*\n/.exec(region);
+    if (!caseMatch)
+        return source;
+    const insertAt = afterFn + caseMatch.index + caseMatch[0].length;
+    const arm = `    ${hookId})\n      return 0\n      ;;\n`;
+    return source.slice(0, insertAt) + arm + source.slice(insertAt);
+}
+/**
+ * Append a `type: command` hook registration to `settings.hooks[event]`,
+ * creating the `hooks` map and the event array as needed. Tolerant of a
+ * non-object `hooks` value — it is replaced rather than trusted.
+ */
+export function registerHookInSettings(settings, event, command) {
+    const root = settings && typeof settings === "object"
+        ? { ...settings }
+        : {};
+    const hooksValue = root.hooks;
+    const hooks = hooksValue && typeof hooksValue === "object"
+        ? { ...hooksValue }
+        : {};
+    const existing = Array.isArray(hooks[event])
+        ? [...hooks[event]]
+        : [];
+    existing.push({ hooks: [{ type: "command", command, timeout: 5 }] });
+    hooks[event] = existing;
+    root.hooks = hooks;
+    return root;
+}
+// --- Post-fix status lookup ----------------------------------------------------
+/** The status of the result whose `target` equals `absPath`, preferring PASS. */
+function statusForPath(results, absPath) {
+    const matches = results.filter((result) => result.target === absPath);
+    const pass = matches.find((result) => result.status === "PASS");
+    return (pass ?? matches[0])?.status ?? null;
+}
+/** The status of the result matching a check-id suffix and target. */
+function statusForTarget(results, checkIdSuffix, target) {
+    const match = results.find((result) => result.checkId.endsWith(checkIdSuffix) && result.target === target);
+    return match?.status ?? null;
+}
+// --- Small helpers -------------------------------------------------------------
+/** The default interactive confirmation: decline unless a TTY says yes. */
+function declineByDefault() {
+    if (!process.stdin.isTTY)
+        return false;
+    // A real TTY prompt is handled by the command layer; the library default is
+    // conservative — never write without an explicit yes.
+    return false;
+}
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function toRelpath(hqRoot, abs) {
+    const rel = path.relative(hqRoot, abs);
+    return rel === "" ? abs : rel;
+}
+function octal(mode) {
+    return "0" + (mode & 0o777).toString(8).padStart(3, "0");
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+//# sourceMappingURL=apply.js.map

package/dist/lib/doctor/fix/backup.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pre-write backups for `hq doctor --fix` (US-011).
+ *
+ * `--fix` writes to safety-hook configuration, so every run that changes a file
+ * first copies the ORIGINAL under `workspace/doctor/backups/<timestamp>/`,
+ * preserving the file's relative path so a restore is unambiguous, and hands
+ * back a single restore command the applier prints on completion. This is one of
+ * the load-bearing guardrails from the PRD: a diagnostic tool that edits the
+ * security layer must always leave the user a one-command way back.
+ *
+ * The module is pure filesystem work with an injectable clock, so the applier's
+ * tests get a deterministic backup directory name without racing the wall clock.
+ */
+/** Where backups live under the resolved HQ root. */
+export declare const BACKUP_RELDIR: string;
+/** The result of a backup pass. */
+export interface BackupResult {
+    /** Absolute path of the timestamped backup directory. */
+    dir: string;
+    /** Relative paths (to the HQ root) actually copied, in input order. */
+    files: string[];
+    /** A single shell command that restores every backed-up file in place. */
+    restoreCommand: string;
+}
+/**
+ * A filesystem-safe backup directory name derived from an instant, e.g.
+ * `2026-08-11T08-30-00-000Z`. Colons and dots — illegal or awkward in paths —
+ * are replaced with dashes; the value stays sortable and unique per millisecond.
+ */
+export declare function backupTimestamp(now?: Date): string;
+/**
+ * Copy each of `relpaths` (relative to `hqRoot`) into a fresh timestamped backup
+ * directory, preserving both the relative path structure and the file mode.
+ * Paths that do not exist on disk are skipped rather than failing the run — the
+ * applier only lists files it is about to write, but a missing one must not
+ * abort a backup pass. Returns the directory, the copied set, and a restore
+ * command.
+ */
+export declare function createBackup(hqRoot: string, relpaths: readonly string[], now?: () => Date): BackupResult;
+//# sourceMappingURL=backup.d.ts.map

package/dist/lib/doctor/fix/backup.js

@@ -0,0 +1,64 @@
+/**
+ * Pre-write backups for `hq doctor --fix` (US-011).
+ *
+ * `--fix` writes to safety-hook configuration, so every run that changes a file
+ * first copies the ORIGINAL under `workspace/doctor/backups/<timestamp>/`,
+ * preserving the file's relative path so a restore is unambiguous, and hands
+ * back a single restore command the applier prints on completion. This is one of
+ * the load-bearing guardrails from the PRD: a diagnostic tool that edits the
+ * security layer must always leave the user a one-command way back.
+ *
+ * The module is pure filesystem work with an injectable clock, so the applier's
+ * tests get a deterministic backup directory name without racing the wall clock.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+/** Where backups live under the resolved HQ root. */
+export const BACKUP_RELDIR = path.join("workspace", "doctor", "backups");
+/**
+ * A filesystem-safe backup directory name derived from an instant, e.g.
+ * `2026-08-11T08-30-00-000Z`. Colons and dots — illegal or awkward in paths —
+ * are replaced with dashes; the value stays sortable and unique per millisecond.
+ */
+export function backupTimestamp(now = new Date()) {
+    return now.toISOString().replace(/[:.]/g, "-");
+}
+/**
+ * Copy each of `relpaths` (relative to `hqRoot`) into a fresh timestamped backup
+ * directory, preserving both the relative path structure and the file mode.
+ * Paths that do not exist on disk are skipped rather than failing the run — the
+ * applier only lists files it is about to write, but a missing one must not
+ * abort a backup pass. Returns the directory, the copied set, and a restore
+ * command.
+ */
+export function createBackup(hqRoot, relpaths, now = () => new Date()) {
+    const dir = path.join(hqRoot, BACKUP_RELDIR, backupTimestamp(now()));
+    fs.mkdirSync(dir, { recursive: true });
+    const files = [];
+    for (const rel of relpaths) {
+        const src = path.join(hqRoot, rel);
+        let mode;
+        try {
+            mode = fs.statSync(src).mode & 0o777;
+        }
+        catch {
+            continue; // Not on disk — nothing to back up.
+        }
+        const dest = path.join(dir, rel);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(src, dest);
+        try {
+            fs.chmodSync(dest, mode);
+        }
+        catch {
+            // Best-effort mode preservation; the content copy already succeeded.
+        }
+        files.push(rel);
+    }
+    // `cp -a <dir>/. <hqRoot>/` copies the backup contents — including the leading
+    // dot-directories (.claude/.codex/.grok) — back over the tree, restoring both
+    // content and mode.
+    const restoreCommand = `cp -a "${dir}/." "${hqRoot}/"`;
+    return { dir, files, restoreCommand };
+}
+//# sourceMappingURL=backup.js.map

package/dist/lib/doctor/fix/remediation.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Structured remediation for every doctor finding (US-011).
+ *
+ * The wiring/parity tiers (US-004/US-005) already attach a one-line
+ * `remediation` string to each finding. `--fix` needs more than prose: it needs
+ * to know, mechanically, whether a finding is one of the allowlisted SAFE repair
+ * classes, and if so exactly which file or hook id to act on. This module is the
+ * single classifier that turns a {@link CheckResult} into that structured shape.
+ *
+ * The three — and only three — auto-fixable classes are a deliberate, security
+ * -reviewed allowlist (see the PRD decision record):
+ *
+ *   - `executable-bit`  — restore the execute bit on a hook script that exists
+ *                         but lost `+x`. Detected by the shared `chmod +x …`
+ *                         remediation the Claude, Codex, and core-event exec-bit
+ *                         findings all emit.
+ *   - `gate-profile`    — add a gated hook id to the `hook-gate.sh` profile
+ *                         allowlists it is missing from. Detected by the
+ *                         `…gate-profiles` FAIL from the Claude wiring tier.
+ *   - `register-hook`   — re-register a script that is present on disk but wired
+ *                         nowhere. Detected by the `…orphan` WARN.
+ *
+ * EVERYTHING else — content drift between platform copies, a missing script, a
+ * missing Codex counterpart, an unquoted `$CLAUDE_PROJECT_DIR`, a stale
+ * allowed-divergence entry — is `autoFixable: false` (manual-only). `--fix` must
+ * never rewrite a hook body or create/delete a file, so those cases carry the
+ * human remediation and nothing the applier will act on. A test pins that a
+ * content-drift finding is manual-only, because that boundary is load-bearing:
+ * deciding which of two diverged copies is correct needs human judgement.
+ */
+import type { CheckResult } from "../types.js";
+/** The allowlisted safe repair classes `--fix` is permitted to apply. */
+export type FixClass = "executable-bit" | "gate-profile" | "register-hook";
+/**
+ * A finding's structured remediation. `autoFixable`, `action`, and `command`
+ * are the `--json` surface (AC1); `fixTarget`/`fixClass` are the internal handle
+ * `--fix` acts on and are not part of the JSON contract.
+ */
+export interface Remediation {
+    /** Whether `--fix` is allowed to repair this finding mechanically. */
+    autoFixable: boolean;
+    /** Plain-language description of the exact repair. */
+    action: string;
+    /** The equivalent shell command a user could run by hand, or "" when none. */
+    command: string;
+    /** The safe class when {@link autoFixable}, else null (manual-only). */
+    fixClass: FixClass | null;
+    /**
+     * The concrete file path (exec-bit, register-hook) or hook id (gate-profile)
+     * the auto-fix operates on. Present only when {@link autoFixable}. Internal —
+     * deliberately omitted from the `--json` document.
+     */
+    fixTarget?: string;
+}
+/**
+ * Extract the target path from a `chmod +x <path>` command, stripping one layer
+ * of surrounding single or double quotes. Returns "" when the string is not a
+ * chmod-exec command.
+ */
+export declare function chmodTargetPath(command: string | undefined): string;
+/**
+ * Classify a finding into its structured remediation, or null when the result
+ * is not a finding at all (only FAIL and WARN describe an actionable problem;
+ * PASS/NA/UNTESTED/UNKNOWN/KNOWN-DEFECT carry nothing to remediate).
+ *
+ * The classification keys off the shared remediation-string shape and the check
+ * id SUFFIX rather than a full id, so it survives a family renaming its id
+ * prefix and never mistakes one tier's ids for another's.
+ */
+export declare function deriveRemediation(result: CheckResult): Remediation | null;
+//# sourceMappingURL=remediation.d.ts.map

package/dist/lib/doctor/fix/remediation.js

@@ -0,0 +1,103 @@
+/**
+ * Structured remediation for every doctor finding (US-011).
+ *
+ * The wiring/parity tiers (US-004/US-005) already attach a one-line
+ * `remediation` string to each finding. `--fix` needs more than prose: it needs
+ * to know, mechanically, whether a finding is one of the allowlisted SAFE repair
+ * classes, and if so exactly which file or hook id to act on. This module is the
+ * single classifier that turns a {@link CheckResult} into that structured shape.
+ *
+ * The three — and only three — auto-fixable classes are a deliberate, security
+ * -reviewed allowlist (see the PRD decision record):
+ *
+ *   - `executable-bit`  — restore the execute bit on a hook script that exists
+ *                         but lost `+x`. Detected by the shared `chmod +x …`
+ *                         remediation the Claude, Codex, and core-event exec-bit
+ *                         findings all emit.
+ *   - `gate-profile`    — add a gated hook id to the `hook-gate.sh` profile
+ *                         allowlists it is missing from. Detected by the
+ *                         `…gate-profiles` FAIL from the Claude wiring tier.
+ *   - `register-hook`   — re-register a script that is present on disk but wired
+ *                         nowhere. Detected by the `…orphan` WARN.
+ *
+ * EVERYTHING else — content drift between platform copies, a missing script, a
+ * missing Codex counterpart, an unquoted `$CLAUDE_PROJECT_DIR`, a stale
+ * allowed-divergence entry — is `autoFixable: false` (manual-only). `--fix` must
+ * never rewrite a hook body or create/delete a file, so those cases carry the
+ * human remediation and nothing the applier will act on. A test pins that a
+ * content-drift finding is manual-only, because that boundary is load-bearing:
+ * deciding which of two diverged copies is correct needs human judgement.
+ */
+/** Matches an exec-bit remediation command, quoted or not: `chmod +x <path>`. */
+const CHMOD_EXEC = /^chmod\s+\+x\s+(.+)$/;
+/**
+ * Extract the target path from a `chmod +x <path>` command, stripping one layer
+ * of surrounding single or double quotes. Returns "" when the string is not a
+ * chmod-exec command.
+ */
+export function chmodTargetPath(command) {
+    if (!command)
+        return "";
+    const match = CHMOD_EXEC.exec(command.trim());
+    if (!match)
+        return "";
+    return match[1].trim().replace(/^["']/, "").replace(/["']$/, "");
+}
+/**
+ * Classify a finding into its structured remediation, or null when the result
+ * is not a finding at all (only FAIL and WARN describe an actionable problem;
+ * PASS/NA/UNTESTED/UNKNOWN/KNOWN-DEFECT carry nothing to remediate).
+ *
+ * The classification keys off the shared remediation-string shape and the check
+ * id SUFFIX rather than a full id, so it survives a family renaming its id
+ * prefix and never mistakes one tier's ids for another's.
+ */
+export function deriveRemediation(result) {
+    if (result.status !== "FAIL" && result.status !== "WARN")
+        return null;
+    const { checkId, remediation } = result;
+    const target = result.target ?? "";
+    // executable-bit — the Claude, Codex, and core-event exec-bit findings all
+    // emit a `chmod +x <path>` remediation. Take the path from the command, not
+    // from `target`, because the Codex tier reports the hook id in `target`.
+    const chmodPath = chmodTargetPath(remediation);
+    if (chmodPath) {
+        return {
+            autoFixable: true,
+            fixClass: "executable-bit",
+            fixTarget: chmodPath,
+            action: `Restore the executable bit on ${chmodPath}.`,
+            command: `chmod +x "${chmodPath}"`,
+        };
+    }
+    // gate-profile — a gated hook id present in some but not all three profiles.
+    if (checkId.endsWith(".gate-profiles") && result.status === "FAIL" && target) {
+        return {
+            autoFixable: true,
+            fixClass: "gate-profile",
+            fixTarget: target,
+            action: `Add ${target} to the hook-gate.sh profile allowlists it is missing from.`,
+            command: remediation ?? `Add ${target} to the missing hook-gate.sh profiles.`,
+        };
+    }
+    // register-hook — a script on disk that no settings file references.
+    if (checkId.endsWith(".orphan") && target) {
+        return {
+            autoFixable: true,
+            fixClass: "register-hook",
+            fixTarget: target,
+            action: `Re-register ${target} in .claude/settings.json.`,
+            command: remediation ?? `Register ${target} in .claude/settings.json.`,
+        };
+    }
+    // Manual-only: content drift, missing scripts/counterparts, unquoted
+    // expansions, stale allowed-divergence entries, invalid settings, etc. `--fix`
+    // never touches these.
+    return {
+        autoFixable: false,
+        fixClass: null,
+        action: remediation ?? result.message,
+        command: remediation ?? "",
+    };
+}
+//# sourceMappingURL=remediation.js.map