@indigoai-us/hq-cli 5.90.0 → 5.92.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [5.92.0]
+
+### Changed
+
+- `hq core codex-skill-bridge` now runs as native, tested TypeScript instead of
+  a bundled shell asset, completing the `hq core` utility migration. Install,
+  status, doctor, dry-run, stale-HQ-root repair, blocked-target refusal, legacy
+  `.Codex` handling, and the local-config path rewrite are all preserved and
+  proven byte-identical to the shell implementation by a differential suite
+  covering sixteen scenarios. The scaffold script still ships for loose HQ
+  trees. (#325)
+
+## [5.91.0]
+
+### Changed
+
+- The `hq core checkpoint` maintenance sibling now curates the policy and
+  knowledge stores instead of only appending to them. It searches the existing
+  policies first and then amends, supersedes, merges or creates, and corrects a
+  stale durable fact in place rather than shadowing it with a contradictory
+  copy. Deletion is bounded: only as part of a merge or supersede, only inside
+  the policy directories the sibling could already write, never a HARD-marked
+  policy (those are flagged in the report for a human), and never a file it has
+  not read. Every amendment, supersession, merge and deletion must be named in
+  the run report with its reason. (#320)
+
 ## [5.90.0]
 
 ### Changed

package/dist/commands/core-checkpoint.d.ts

@@ -11,7 +11,7 @@ import { Command } from "commander";
  * Kept in TypeScript rather than in a bundled asset: it is an instruction to
  * a locally-installed agent, not a scaffold script that should be packaged.
  */
-export declare const SIBLING_PROMPT_TEMPLATE = "You are the HQ checkpoint sibling \u2014 a background maintenance agent for this\nHQ install. Your parent session's state is in <payloadPath>. Work\nquietly and do not ask questions; if something is ambiguous, record it in the\nreport instead of guessing.\n\n1. Read the payload. If it lists a transcript path that exists, read its tail (~400 lines)\n   both for session context and to extract additional reusable learnings/insights\n   the parent did not pass explicitly. Never quote secrets\n   or tokens from the transcript. If .claude/skills/checkpoint/SKILL.md exists\n   under this HQ root, read it and follow it wherever it goes beyond these instructions;\n   the write bounds below always win over the skill text.\n2. Upgrade the thread file named in the payload IN PLACE: verify/repair its\n   JSON; fill git.remote_url, git.initial_commit, git.commits_made, and\n   git.knowledge_repos by scanning core/knowledge/public/*,\n   core/knowledge/private/*, personal/knowledge/*, and companies/*/knowledge\n   for symlinks or directories containing .git, recording dirty repositories\n   as {\"<name>\": {\"commit\": \"<short>\", \"dirty\": true}}. Fill worker,\n   next_steps, and insights; set type to \"checkpoint\"; then rename the file to\n   drop -auto- from its filename. Use the renamed path in every reference you\n   write afterwards.\n3. For every explicit or transcript-derived learning that is a reusable rule,\n   distill a non-duplicate policy file under personal/policies/ or, only when\n   the payload names a company and the rule is company-specific,\n   companies/<company>/policies/, following\n   core/knowledge/public/hq-core/policies-spec.md. Store up to two explicit or\n   transcript-derived insights per core/knowledge/public/hq-core/insights-spec.md\n   when present, otherwise workspace/insights/. Durable facts (not rules) may\n   go under personal/knowledge/ or companies/<company>/knowledge/ only.\n4. Close an active session journal fail-soft with\n   bash .claude/skills/_shared/journal.sh close \"<project_dir>\" \"<one-line synthesis>\".\n   Write a legacy checkpoint JSON under workspace/checkpoints/<id>.json with\n   id, created_at, summary, files, and next_steps for backward compatibility.\n5. Update workspace/threads/recent.md and regenerate\n   workspace/threads/INDEX.md. For each company whose knowledge path appears\n   in files_touched, regenerate companies/<company>/knowledge/INDEX.md under\n   core/knowledge/public/hq-core/index-md-spec.md. Mechanical index generation\n   is allowed for those companies, but knowledge/policy content writes remain\n   restricted to the payload's named company.\n6. Run .claude/skills/document-release/SKILL.md best-effort when it exists;\n   skip silently on any failure. Hook or automation improvements go ONLY under\n   personal/hooks/ as proposals.\n7. WRITE BOUNDS: you may write only under personal/, workspace/, and companies/<company>/ as constrained above. You must NEVER write into .claude/, core/, .agents/, .codex/, repos/, or anywhere outside the HQ root.\n8. Write <runDir>/report.md \u2014 full prose: what you read, what you changed\n   (paths), and what you skipped and why. Then drain the queue: while\n   workspace/checkpoints/sibling/pending.jsonl exists and is non-empty, claim\n   it atomically by renaming it aside \u2014\n   mv workspace/checkpoints/sibling/pending.jsonl <runDir>/pending-claimed-N.jsonl\n   (N counting up from 2) \u2014 and process the claimed payloads with this same\n   flow. Repeat until a claim finds nothing left, then update the report.\n   NEVER read the queue and truncate it in place: a payload appended between\n   your read and the truncate is lost, and its checkpoint is never enriched.\n";
+export declare const SIBLING_PROMPT_TEMPLATE = "You are the HQ checkpoint sibling \u2014 a background maintenance agent for this\nHQ install. Your parent session's state is in <payloadPath>. Work\nquietly and do not ask questions; if something is ambiguous, record it in the\nreport instead of guessing.\n\n1. Read the payload. If it lists a transcript path that exists, read its tail (~400 lines)\n   both for session context and to extract additional reusable learnings/insights\n   the parent did not pass explicitly. Never quote secrets\n   or tokens from the transcript. If .claude/skills/checkpoint/SKILL.md exists\n   under this HQ root, read it and follow it wherever it goes beyond these instructions;\n   the write bounds below always win over the skill text.\n2. Upgrade the thread file named in the payload IN PLACE: verify/repair its\n   JSON; fill git.remote_url, git.initial_commit, git.commits_made, and\n   git.knowledge_repos by scanning core/knowledge/public/*,\n   core/knowledge/private/*, personal/knowledge/*, and companies/*/knowledge\n   for symlinks or directories containing .git, recording dirty repositories\n   as {\"<name>\": {\"commit\": \"<short>\", \"dirty\": true}}. Fill worker,\n   next_steps, and insights; set type to \"checkpoint\"; then rename the file to\n   drop -auto- from its filename. Use the renamed path in every reference you\n   write afterwards.\n3. For every explicit or transcript-derived learning that is a reusable rule,\n   FIRST search the existing policies for one the learning refines, contradicts\n   or duplicates. Then take exactly one of these actions and name it in the\n   report \u2014 the policy set is curated, not append-only:\n   - AMEND an existing policy in place when the learning sharpens it, narrows\n     its scope, or adds a case, and the rule as written is still correct.\n   - SUPERSEDE it when the learning contradicts it: rewrite the rule to what is\n     now true and record inside the file what changed and why.\n   - MERGE near-duplicates into the single best-named file, then delete the\n     files you merged away.\n   - CREATE a new policy only when no existing policy covers the rule.\n   Follow core/knowledge/public/hq-core/policies-spec.md. Write under\n   personal/policies/ or, only when the payload names a company and the rule is\n   company-specific, companies/<company>/policies/.\n   DELETION BOUNDS: delete a policy only as the MERGE or SUPERSEDE step above,\n   only inside those two directories, and never one whose body marks it HARD \u2014\n   if a hard policy now looks wrong, leave it untouched and flag it in the\n   report for a human to decide. Never delete a file you have not read.\n   Apply the same curation to durable facts (not rules) under\n   personal/knowledge/ or companies/<company>/knowledge/: correct a stale fact\n   in place rather than appending a second, contradictory copy of it.\n   Store up to two explicit or transcript-derived insights per\n   core/knowledge/public/hq-core/insights-spec.md when present, otherwise\n   workspace/insights/.\n4. Close an active session journal fail-soft with\n   bash .claude/skills/_shared/journal.sh close \"<project_dir>\" \"<one-line synthesis>\".\n   Write a legacy checkpoint JSON under workspace/checkpoints/<id>.json with\n   id, created_at, summary, files, and next_steps for backward compatibility.\n5. Update workspace/threads/recent.md and regenerate\n   workspace/threads/INDEX.md. For each company whose knowledge path appears\n   in files_touched, regenerate companies/<company>/knowledge/INDEX.md under\n   core/knowledge/public/hq-core/index-md-spec.md. Mechanical index generation\n   is allowed for those companies, but knowledge/policy content writes remain\n   restricted to the payload's named company.\n6. Run .claude/skills/document-release/SKILL.md best-effort when it exists;\n   skip silently on any failure. Hook or automation improvements go ONLY under\n   personal/hooks/ as proposals.\n7. WRITE BOUNDS: you may write only under personal/, workspace/, and companies/<company>/ as constrained above. You must NEVER write into .claude/, core/, .agents/, .codex/, repos/, or anywhere outside the HQ root.\n8. Write <runDir>/report.md \u2014 full prose: what you read, what you changed\n   (paths), and what you skipped and why. List every policy or knowledge file\n   you amended, superseded, merged or deleted with the reason, so a human can\n   audit and reverse it; a deletion you do not name in the report is a defect.\n   Then drain the queue: while\n   workspace/checkpoints/sibling/pending.jsonl exists and is non-empty, claim\n   it atomically by renaming it aside \u2014\n   mv workspace/checkpoints/sibling/pending.jsonl <runDir>/pending-claimed-N.jsonl\n   (N counting up from 2) \u2014 and process the claimed payloads with this same\n   flow. Repeat until a claim finds nothing left, then update the report.\n   NEVER read the queue and truncate it in place: a payload appended between\n   your read and the truncate is lost, and its checkpoint is never enriched.\n";
 export declare function renderSiblingPrompt(runDir: string, payloadPath: string): string;
 /** Attach the native checkpoint command to the hidden `hq core` group. */
 export declare function registerCoreCheckpointCommand(core: Command): void;

package/dist/commands/core-checkpoint.js

@@ -56,13 +56,29 @@ report instead of guessing.
    drop -auto- from its filename. Use the renamed path in every reference you
    write afterwards.
 3. For every explicit or transcript-derived learning that is a reusable rule,
-   distill a non-duplicate policy file under personal/policies/ or, only when
-   the payload names a company and the rule is company-specific,
-   companies/<company>/policies/, following
-   core/knowledge/public/hq-core/policies-spec.md. Store up to two explicit or
-   transcript-derived insights per core/knowledge/public/hq-core/insights-spec.md
-   when present, otherwise workspace/insights/. Durable facts (not rules) may
-   go under personal/knowledge/ or companies/<company>/knowledge/ only.
+   FIRST search the existing policies for one the learning refines, contradicts
+   or duplicates. Then take exactly one of these actions and name it in the
+   report — the policy set is curated, not append-only:
+   - AMEND an existing policy in place when the learning sharpens it, narrows
+     its scope, or adds a case, and the rule as written is still correct.
+   - SUPERSEDE it when the learning contradicts it: rewrite the rule to what is
+     now true and record inside the file what changed and why.
+   - MERGE near-duplicates into the single best-named file, then delete the
+     files you merged away.
+   - CREATE a new policy only when no existing policy covers the rule.
+   Follow core/knowledge/public/hq-core/policies-spec.md. Write under
+   personal/policies/ or, only when the payload names a company and the rule is
+   company-specific, companies/<company>/policies/.
+   DELETION BOUNDS: delete a policy only as the MERGE or SUPERSEDE step above,
+   only inside those two directories, and never one whose body marks it HARD —
+   if a hard policy now looks wrong, leave it untouched and flag it in the
+   report for a human to decide. Never delete a file you have not read.
+   Apply the same curation to durable facts (not rules) under
+   personal/knowledge/ or companies/<company>/knowledge/: correct a stale fact
+   in place rather than appending a second, contradictory copy of it.
+   Store up to two explicit or transcript-derived insights per
+   core/knowledge/public/hq-core/insights-spec.md when present, otherwise
+   workspace/insights/.
 4. Close an active session journal fail-soft with
    bash .claude/skills/_shared/journal.sh close "<project_dir>" "<one-line synthesis>".
    Write a legacy checkpoint JSON under workspace/checkpoints/<id>.json with
@@ -78,7 +94,10 @@ report instead of guessing.
    personal/hooks/ as proposals.
 7. WRITE BOUNDS: you may write only under personal/, workspace/, and companies/<company>/ as constrained above. You must NEVER write into .claude/, core/, .agents/, .codex/, repos/, or anywhere outside the HQ root.
 8. Write <runDir>/report.md — full prose: what you read, what you changed
-   (paths), and what you skipped and why. Then drain the queue: while
+   (paths), and what you skipped and why. List every policy or knowledge file
+   you amended, superseded, merged or deleted with the reason, so a human can
+   audit and reverse it; a deletion you do not name in the report is a defect.
+   Then drain the queue: while
    workspace/checkpoints/sibling/pending.jsonl exists and is non-empty, claim
    it atomically by renaming it aside —
    mv workspace/checkpoints/sibling/pending.jsonl <runDir>/pending-claimed-N.jsonl

package/dist/commands/core.js

@@ -41,6 +41,7 @@ import { ontologyReadmeDrift } from "../lib/core-utils/ontology-readme-drift.js"
 import { resizeScreenshot } from "../lib/core-utils/resize-screenshot.js";
 import { tokenUsageReport } from "../lib/core-utils/token-usage-report.js";
 import { createWorktree } from "../lib/core-utils/worktree.js";
+import { runCodexSkillBridgeCommand } from "../lib/core-utils/codex-skill-bridge-entry.js";
 /**
  * These commands are now native implementations. Their retained shell assets
  * are deliberately claimed in SCAFFOLD_ONLY_ASSETS: loose HQ trees still ship
@@ -53,6 +54,7 @@ export const NATIVE_UTILITY_COMMANDS = [
     { name: "resize-screenshot", root: "cwd", summary: "Downscale a screenshot for context efficiency", run: (args) => resizeScreenshot(args) },
     { name: "token-usage-report", root: "cwd", summary: "Report session token usage", run: (args) => tokenUsageReport(args) },
     { name: "worktree", root: "live", summary: "Create a git worktree under workspace/worktrees/", run: (args, context) => createWorktree(args, { cwd: context.cwd, hqRoot: context.hqRoot }) },
+    { name: "codex-skill-bridge", root: "live", summary: "Install/inspect the Codex skill bridge", run: (args, context) => runCodexSkillBridgeCommand(args, { root: context.hqRoot ?? context.cwd }) },
 ];
 export const NATIVE_SCAFFOLD_COMMANDS = [
     {
@@ -183,13 +185,6 @@ export const SCAFFOLD_COMMANDS = [
         root: "cwd",
         summary: "Refresh qmd collections after a sync",
     },
-    // ---- Reporting and utilities (live tree) ----
-    {
-        name: "codex-skill-bridge",
-        asset: "core/scripts/codex-skill-bridge.sh",
-        root: "live",
-        summary: "Install/inspect the Codex skill bridge",
-    },
 ];
 /**
  * Bundled solely for HQ-root scaffolds, which still need these as loose files.
@@ -197,6 +192,7 @@ export const SCAFFOLD_COMMANDS = [
  * direct `hq core` command.
  */
 export const SCAFFOLD_ONLY_ASSETS = [
+    { asset: "core/scripts/codex-skill-bridge.sh", root: "live", summary: "Scaffold-only native utility companion" },
     { asset: "core/scripts/detect-stale-core-policy-mirror.sh", root: "live", summary: "Scaffold-only native utility companion" },
     { asset: "core/scripts/hq-status-summary.sh", root: "cwd", summary: "Scaffold-only native utility companion" },
     { asset: "core/scripts/ontology-readme-drift.sh", root: "live", summary: "Scaffold-only native utility companion" },

package/dist/lib/core-utils/codex-skill-bridge-entry.d.ts

@@ -0,0 +1,13 @@
+/** CLI adapter for the native Codex skill bridge. */
+import { type UtilityIo } from "./common.js";
+export type CodexSkillBridgeOptions = UtilityIo & {
+    root?: string;
+    home?: string;
+};
+/**
+ * Mirrors the shell entry point: usage on `--help` (exit 0) or a missing
+ * command (exit 1), single-line stderr plus exit 1 for refusals, and the
+ * unhealthy-check count as `status`/`install`'s exit code.
+ */
+export declare function runCodexSkillBridgeCommand(args?: string[], options?: CodexSkillBridgeOptions): number;
+//# sourceMappingURL=codex-skill-bridge-entry.d.ts.map

package/dist/lib/core-utils/codex-skill-bridge-entry.js

@@ -0,0 +1,48 @@
+/** CLI adapter for the native Codex skill bridge. */
+import { ioFor, line } from "./common.js";
+import { BridgeError, BridgeHelp, USAGE, parseArgs, runCodexSkillBridge, } from "./codex-skill-bridge.js";
+/**
+ * Mirrors the shell entry point: usage on `--help` (exit 0) or a missing
+ * command (exit 1), single-line stderr plus exit 1 for refusals, and the
+ * unhealthy-check count as `status`/`install`'s exit code.
+ */
+export function runCodexSkillBridgeCommand(args = [], options = {}) {
+    const { stdout, stderr } = ioFor(options);
+    const defaultRoot = options.root ?? process.env.HQ_ROOT ?? process.cwd();
+    const home = options.home ?? process.env.HOME ?? "";
+    let parsed;
+    try {
+        parsed = parseArgs(args, defaultRoot);
+    }
+    catch (error) {
+        if (error instanceof BridgeHelp) {
+            line(stdout, USAGE);
+            return 0;
+        }
+        if (error instanceof BridgeError) {
+            // An empty message is the shell's "no command given" path: usage, exit 1.
+            if (!error.message) {
+                line(stdout, USAGE);
+                return 1;
+            }
+            line(stderr, error.message);
+            return 1;
+        }
+        throw error;
+    }
+    try {
+        return runCodexSkillBridge(parsed, {
+            home,
+            out: (text) => line(stdout, text),
+            err: (text) => line(stderr, text),
+        });
+    }
+    catch (error) {
+        if (error instanceof BridgeError) {
+            line(stderr, error.message);
+            return 1;
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=codex-skill-bridge-entry.js.map

package/dist/lib/core-utils/codex-skill-bridge.d.ts

@@ -0,0 +1,31 @@
+export type BridgeCommand = "status" | "install" | "doctor";
+export type BridgeOptions = {
+    command: BridgeCommand;
+    hqRoot: string;
+    oldRoots: string[];
+    repairLocalConfig: boolean;
+    dryRun: boolean;
+};
+export type BridgeIo = {
+    home: string;
+    out: (line: string) => void;
+    err: (line: string) => void;
+};
+/** Thrown for the shell's `fail`/refusal paths: message to stderr, exit 1. */
+export declare class BridgeError extends Error {
+    name: string;
+}
+export declare const USAGE = "Usage:\n  scripts/codex-skill-bridge.sh status [--root <path>]\n  scripts/codex-skill-bridge.sh install [--root <path>] [--repair-local-config] [--old-root <path>]\n  scripts/codex-skill-bridge.sh doctor [--root <path>] [--old-root <path>] [--dry-run]\n\nCommands:\n  status   Show bridge health, output-style bridge health, and stale HQ roots without changing files.\n  install  Install or repair HQ-owned Claude -> Codex bridges.\n  doctor   Repair bridges and rewrite local machine config from old HQ roots to this root.\n\nOptions:\n  --root <path>             HQ root to repair. Defaults to this script's parent.\n  --old-root <path>         Old HQ root to rewrite. Repeatable. Auto-detected when omitted.\n  --repair-local-config     With install, also rewrite local config paths.\n  --dry-run                 With doctor, print intended config rewrites without changing files.";
+/** Signals `--help`: caller prints usage and exits 0. */
+export declare class BridgeHelp extends Error {
+}
+export declare function parseArgs(argv: string[], defaultRoot: string): BridgeOptions;
+/** `strip_known_hq_subpath`: returns undefined when no known suffix matches. */
+export declare function stripKnownHqSubpath(target: string): string | undefined;
+/** `is_hq_root_like`: basename HQ, no brace placeholders, not the bare path. */
+export declare function isHqRootLike(candidate: string): boolean;
+/** `output_style_slug`: lowercase, collapse space/underscore, strip oddities. */
+export declare function outputStyleSlug(name: string): string;
+/** Runs one bridge command; returns the process exit code. */
+export declare function runCodexSkillBridge(options: BridgeOptions, io: BridgeIo): number;
+//# sourceMappingURL=codex-skill-bridge.d.ts.map

package/dist/lib/core-utils/codex-skill-bridge.js

@@ -0,0 +1,505 @@
+/**
+ * Native port of `core/scripts/codex-skill-bridge.sh`.
+ *
+ * The bridge symlinks HQ's `.claude` sources into the places Codex and the
+ * agents runtime look for them, and repairs links (and optionally local config
+ * paths) left pointing at an HQ root that has since moved.
+ *
+ * Every path derives from the resolved HQ root and `HOME`, so callers — and
+ * the differential suite — can exercise the whole surface hermetically.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+/** Thrown for the shell's `fail`/refusal paths: message to stderr, exit 1. */
+export class BridgeError extends Error {
+    name = "BridgeError";
+}
+export const USAGE = `Usage:
+  scripts/codex-skill-bridge.sh status [--root <path>]
+  scripts/codex-skill-bridge.sh install [--root <path>] [--repair-local-config] [--old-root <path>]
+  scripts/codex-skill-bridge.sh doctor [--root <path>] [--old-root <path>] [--dry-run]
+
+Commands:
+  status   Show bridge health, output-style bridge health, and stale HQ roots without changing files.
+  install  Install or repair HQ-owned Claude -> Codex bridges.
+  doctor   Repair bridges and rewrite local machine config from old HQ roots to this root.
+
+Options:
+  --root <path>             HQ root to repair. Defaults to this script's parent.
+  --old-root <path>         Old HQ root to rewrite. Repeatable. Auto-detected when omitted.
+  --repair-local-config     With install, also rewrite local config paths.
+  --dry-run                 With doctor, print intended config rewrites without changing files.`;
+/** Signals `--help`: caller prints usage and exits 0. */
+export class BridgeHelp extends Error {
+}
+export function parseArgs(argv, defaultRoot) {
+    let command = "";
+    let hqRoot = defaultRoot;
+    const oldRoots = [];
+    let repairLocalConfig = false;
+    let dryRun = false;
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (arg === "status" || arg === "install" || arg === "doctor") {
+            if (command)
+                throw new BridgeError("Only one command may be provided.");
+            command = arg;
+        }
+        else if (arg === "--root") {
+            if (index + 1 >= argv.length)
+                throw new BridgeError("--root requires a path.");
+            hqRoot = argv[++index];
+        }
+        else if (arg.startsWith("--root=")) {
+            hqRoot = arg.slice("--root=".length);
+        }
+        else if (arg === "--old-root") {
+            if (index + 1 >= argv.length)
+                throw new BridgeError("--old-root requires a path.");
+            oldRoots.push(argv[++index]);
+        }
+        else if (arg.startsWith("--old-root=")) {
+            oldRoots.push(arg.slice("--old-root=".length));
+        }
+        else if (arg === "--repair-local-config") {
+            repairLocalConfig = true;
+        }
+        else if (arg === "--dry-run") {
+            dryRun = true;
+        }
+        else if (arg === "-h" || arg === "--help") {
+            throw new BridgeHelp();
+        }
+        else {
+            throw new BridgeError(`Unknown argument: ${arg}`);
+        }
+    }
+    if (!command)
+        throw new BridgeError("");
+    return { command, hqRoot, oldRoots, repairLocalConfig, dryRun };
+}
+/** `canonical_dir`: the shell resolves via `cd … && pwd`, so symlinks collapse. */
+function canonicalDir(directory) {
+    return fs.realpathSync(directory);
+}
+function configurePaths(hqRootInput, home) {
+    const hqRoot = canonicalDir(hqRootInput);
+    const claudeSource = path.join(hqRoot, ".claude");
+    const projectCodexDir = path.join(hqRoot, ".codex");
+    const legacyCodexDir = path.join(hqRoot, ".Codex");
+    return {
+        hqRoot,
+        skillsSource: path.join(claudeSource, "skills"),
+        claudeSource,
+        commandsSource: path.join(claudeSource, "commands"),
+        hooksSource: path.join(claudeSource, "hooks"),
+        policiesSource: path.join(claudeSource, "policies"),
+        settingsFile: path.join(claudeSource, "settings.json"),
+        outputStylesSource: path.join(claudeSource, "output-styles"),
+        globalSkillsTarget: path.join(home, ".codex", "skills", "hq"),
+        globalAgentsSkillsTarget: path.join(home, ".agents", "skills", "hq"),
+        repoAgentsSkillsTarget: path.join(hqRoot, ".agents", "skills"),
+        projectCodexDir,
+        projectClaudeTarget: path.join(projectCodexDir, "claude"),
+        projectPromptsTarget: path.join(projectCodexDir, "prompts"),
+        projectOutputStyleTarget: path.join(projectCodexDir, "output-style.md"),
+        legacyCodexDir,
+        legacyClaudeTarget: path.join(legacyCodexDir, "claude"),
+        legacyPromptsTarget: path.join(legacyCodexDir, "prompts"),
+        legacyOutputStyleTarget: path.join(legacyCodexDir, "output-style.md"),
+    };
+}
+function isSymlink(target) {
+    try {
+        return fs.lstatSync(target).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/** `[[ -e ]]`: follows links, so a dangling symlink is not "exists". */
+function exists(target) {
+    return fs.existsSync(target);
+}
+function listEntries(directory) {
+    try {
+        return fs.readdirSync(directory);
+    }
+    catch {
+        return [];
+    }
+}
+/** Directory or symlink child holding a SKILL.md, matching the shell's find. */
+function skillDirectories(skillsSource) {
+    return listEntries(skillsSource).filter((name) => {
+        const child = path.join(skillsSource, name);
+        let isDirOrLink = false;
+        try {
+            const stat = fs.lstatSync(child);
+            isDirOrLink = stat.isDirectory() || stat.isSymbolicLink();
+        }
+        catch {
+            return false;
+        }
+        return isDirOrLink && fs.existsSync(path.join(child, "SKILL.md"));
+    });
+}
+function markdownFiles(directory) {
+    return listEntries(directory).filter((name) => {
+        if (!name.endsWith(".md"))
+            return false;
+        try {
+            return fs.lstatSync(path.join(directory, name)).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function plainFiles(directory) {
+    return listEntries(directory).filter((name) => {
+        try {
+            return fs.lstatSync(path.join(directory, name)).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * `normalize_link_target`: absolute targets pass through; relative ones resolve
+ * against the link's directory, with existing paths canonicalised.
+ */
+function normalizeLinkTarget(target) {
+    const linkTarget = fs.readlinkSync(target);
+    if (path.isAbsolute(linkTarget))
+        return linkTarget;
+    const targetDir = canonicalDir(path.dirname(target));
+    const resolved = path.join(targetDir, linkTarget);
+    if (fs.existsSync(resolved)) {
+        if (fs.statSync(resolved).isDirectory())
+            return canonicalDir(resolved);
+        return path.join(canonicalDir(path.dirname(resolved)), path.basename(resolved));
+    }
+    return resolved;
+}
+/** `strip_known_hq_subpath`: returns undefined when no known suffix matches. */
+export function stripKnownHqSubpath(target) {
+    const outputStyle = target.match(/^(.*)\/\.claude\/output-styles\/[^/]*\.md$/);
+    if (outputStyle)
+        return outputStyle[1];
+    for (const suffix of ["/.claude/skills", "/.claude/commands", "/.claude"]) {
+        if (target.endsWith(suffix))
+            return target.slice(0, -suffix.length);
+    }
+    return undefined;
+}
+/** `is_hq_root_like`: basename HQ, no brace placeholders, not the bare path. */
+export function isHqRootLike(candidate) {
+    if (candidate.includes("{") || candidate.includes("}"))
+        return false;
+    if (candidate === "/Documents/HQ")
+        return false;
+    return path.basename(candidate) === "HQ";
+}
+function activeOutputStyleName(paths) {
+    let contents;
+    try {
+        contents = fs.readFileSync(paths.settingsFile, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    // The shell greps line-wise and keeps the LAST match.
+    let match;
+    for (const line of contents.split("\n")) {
+        const found = line.match(/"outputStyle"[ \t]*:[ \t]*"([^"]*)"/);
+        if (found)
+            match = found[1];
+    }
+    return match;
+}
+/** `output_style_slug`: lowercase, collapse space/underscore, strip oddities. */
+export function outputStyleSlug(name) {
+    return name
+        .toLowerCase()
+        .replace(/[ \t\n_]+/g, "-")
+        .replace(/[^a-z0-9.-]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-/, "")
+        .replace(/-$/, "");
+}
+function resolveOutputStyleSourceFile(paths) {
+    const styleName = activeOutputStyleName(paths);
+    if (!styleName)
+        return undefined;
+    const source = path.join(paths.outputStylesSource, `${outputStyleSlug(styleName)}.md`);
+    try {
+        if (!fs.lstatSync(source).isFile())
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    return source;
+}
+/** `bridge_target_is_repairable`: same suffix under a different HQ-like root. */
+function bridgeTargetIsRepairable(currentTarget, source, hqRoot) {
+    const expectedSuffix = source.startsWith(hqRoot) ? source.slice(hqRoot.length) : source;
+    const targetRoot = stripKnownHqSubpath(currentTarget);
+    if (!targetRoot)
+        return false;
+    if (!isHqRootLike(targetRoot))
+        return false;
+    if (targetRoot === hqRoot)
+        return false;
+    return currentTarget.slice(targetRoot.length) === expectedSuffix;
+}
+function printLinkStatus(io, state, paths, label, source, target) {
+    io.out(`${label}:`);
+    io.out(`  source: ${source}`);
+    io.out(`  target: ${target}`);
+    if (isSymlink(target)) {
+        const resolvedTarget = normalizeLinkTarget(target);
+        io.out("  bridge: installed");
+        io.out(`  points to: ${resolvedTarget}`);
+        if (resolvedTarget === source) {
+            io.out("  status: healthy");
+        }
+        else if (bridgeTargetIsRepairable(resolvedTarget, source, paths.hqRoot)) {
+            io.out("  status: stale HQ root (repairable)");
+            state.failures += 1;
+        }
+        else {
+            io.out("  status: unexpected target");
+            state.failures += 1;
+        }
+    }
+    else if (exists(target)) {
+        io.out("  bridge: blocked");
+        io.out("  status: target exists and is not a symlink");
+        state.failures += 1;
+    }
+    else {
+        io.out("  bridge: not installed");
+        state.failures += 1;
+    }
+}
+function repairOrCreateSymlink(io, options, paths, label, source, target) {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    if (isSymlink(target)) {
+        const resolvedTarget = normalizeLinkTarget(target);
+        if (resolvedTarget === source) {
+            io.out(`${label} already installed.`);
+            return;
+        }
+        if (bridgeTargetIsRepairable(resolvedTarget, source, paths.hqRoot)) {
+            if (options.dryRun) {
+                io.out(`Would repair ${label}: ${resolvedTarget} -> ${source}`);
+                return;
+            }
+            fs.unlinkSync(target);
+            fs.symlinkSync(source, target);
+            io.out(`Repaired ${label}: ${resolvedTarget} -> ${source}`);
+            return;
+        }
+        throw new BridgeError(`Refusing to replace existing symlink: ${target} -> ${resolvedTarget}`);
+    }
+    if (exists(target)) {
+        throw new BridgeError(`Refusing to overwrite existing path: ${target}`);
+    }
+    if (options.dryRun) {
+        io.out(`Would install ${label}: ${target} -> ${source}`);
+        return;
+    }
+    fs.symlinkSync(source, target);
+    io.out(`Installed ${label}.`);
+}
+function configFiles(paths) {
+    return [
+        path.join(paths.hqRoot, ".mcp.json"),
+        path.join(paths.claudeSource, "settings.json"),
+        path.join(paths.claudeSource, "settings.local.json"),
+        path.join(paths.projectCodexDir, "config.toml"),
+        path.join(paths.legacyCodexDir, "config.toml"),
+    ].filter((file) => {
+        try {
+            return fs.statSync(file).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** `extract_hq_roots_from_file`: absolute paths ending in `/HQ` or `/HQ/`. */
+function extractHqRootsFromFile(file) {
+    let contents;
+    try {
+        contents = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const matches = contents.match(/\/[^"\s]+\/HQ(\/|$)/gm) ?? [];
+    return matches.map((match) => (match.endsWith("/") ? match.slice(0, -1) : match));
+}
+function collectStaleRoots(paths, options, includeExplicit) {
+    const roots = [];
+    if (includeExplicit) {
+        for (const root of options.oldRoots)
+            if (root)
+                roots.push(root);
+    }
+    for (const target of [
+        paths.globalSkillsTarget,
+        paths.globalAgentsSkillsTarget,
+        paths.repoAgentsSkillsTarget,
+        paths.projectClaudeTarget,
+        paths.projectPromptsTarget,
+        paths.projectOutputStyleTarget,
+        paths.legacyClaudeTarget,
+        paths.legacyPromptsTarget,
+        paths.legacyOutputStyleTarget,
+    ]) {
+        if (!isSymlink(target))
+            continue;
+        const stripped = stripKnownHqSubpath(normalizeLinkTarget(target));
+        if (stripped)
+            roots.push(stripped);
+    }
+    for (const file of configFiles(paths))
+        roots.push(...extractHqRootsFromFile(file));
+    // `sort -u` then filter, matching the shell's ordering exactly.
+    return [...new Set(roots)]
+        .sort()
+        .filter((root) => root && root !== paths.hqRoot && isHqRootLike(root));
+}
+function printStaleRootReport(io, paths, options) {
+    const roots = collectStaleRoots(paths, options, false);
+    if (roots.length === 0) {
+        io.out("Stale HQ roots: none detected");
+        return;
+    }
+    io.out("Stale HQ roots detected:");
+    for (const root of roots)
+        io.out(`  - ${root}`);
+}
+function rewriteLocalConfigRoots(io, paths, options) {
+    const roots = collectStaleRoots(paths, options, true);
+    if (roots.length === 0) {
+        io.out("No stale local config roots to rewrite.");
+        return;
+    }
+    let rewroteAny = false;
+    for (const file of configFiles(paths)) {
+        let changedFile = false;
+        for (const oldRoot of roots) {
+            if (!oldRoot)
+                continue;
+            let contents = fs.readFileSync(file, "utf8");
+            if (!contents.includes(oldRoot))
+                continue;
+            if (options.dryRun) {
+                io.out(`Would rewrite ${file}: ${oldRoot} -> ${paths.hqRoot}`);
+                continue;
+            }
+            contents = contents.split(oldRoot).join(paths.hqRoot);
+            fs.writeFileSync(file, contents);
+            changedFile = true;
+        }
+        if (changedFile) {
+            io.out(`Rewrote local config paths in ${file}.`);
+            rewroteAny = true;
+        }
+    }
+    if (!rewroteAny && !options.dryRun)
+        io.out("No local config files needed rewriting.");
+}
+function printOutputStyleStatus(io, state, paths) {
+    const styleName = activeOutputStyleName(paths);
+    io.out(`Active output style: ${styleName || "not configured"}`);
+    const source = resolveOutputStyleSourceFile(paths);
+    if (source) {
+        printLinkStatus(io, state, paths, "Project Codex output-style bridge", source, paths.projectOutputStyleTarget);
+        if (exists(paths.legacyCodexDir) || isSymlink(paths.legacyOutputStyleTarget)) {
+            io.out("");
+            printLinkStatus(io, state, paths, "Legacy .Codex output-style bridge", source, paths.legacyOutputStyleTarget);
+        }
+        return;
+    }
+    io.out("Project Codex output-style bridge:");
+    io.out("  source: unavailable");
+    io.out(`  target: ${paths.projectOutputStyleTarget}`);
+    io.out("  status: active output style has no .claude/output-styles/*.md bridge source");
+    state.failures += 1;
+}
+/** Returns the shell's status exit code: the number of unhealthy checks. */
+function printStatus(io, paths, options) {
+    const skillTotal = skillDirectories(paths.skillsSource).length;
+    const skillWith = skillDirectories(paths.skillsSource).filter((name) => fs.existsSync(path.join(paths.skillsSource, name, "agents", "openai.yaml"))).length;
+    const state = { failures: 0 };
+    io.out(`HQ Claude source: ${paths.claudeSource}`);
+    io.out(`Skills in source: ${skillTotal} (${skillWith} with agents/openai.yaml, ${skillTotal - skillWith} without)`);
+    io.out(`Hooks in source: ${plainFiles(paths.hooksSource).length}`);
+    io.out(`Policies in source: ${markdownFiles(paths.policiesSource).length}`);
+    io.out("");
+    printLinkStatus(io, state, paths, "Global skills bridge (legacy)", paths.skillsSource, paths.globalSkillsTarget);
+    io.out("");
+    printLinkStatus(io, state, paths, "Global agents skills bridge", paths.skillsSource, paths.globalAgentsSkillsTarget);
+    io.out("");
+    printLinkStatus(io, state, paths, "Repo agents skills bridge", paths.skillsSource, paths.repoAgentsSkillsTarget);
+    io.out("");
+    printLinkStatus(io, state, paths, "Project Claude mirror", paths.claudeSource, paths.projectClaudeTarget);
+    io.out("");
+    printOutputStyleStatus(io, state, paths);
+    if (exists(paths.legacyCodexDir) ||
+        isSymlink(paths.legacyClaudeTarget) ||
+        isSymlink(paths.legacyPromptsTarget)) {
+        io.out("");
+        printLinkStatus(io, state, paths, "Legacy .Codex Claude mirror", paths.claudeSource, paths.legacyClaudeTarget);
+    }
+    io.out("");
+    printStaleRootReport(io, paths, options);
+    return state.failures;
+}
+function validateSources(paths) {
+    if (!fs.existsSync(paths.skillsSource) || !fs.statSync(paths.skillsSource).isDirectory()) {
+        throw new BridgeError(`Missing skills source directory: ${paths.skillsSource}`);
+    }
+    if (!fs.existsSync(paths.claudeSource) || !fs.statSync(paths.claudeSource).isDirectory()) {
+        throw new BridgeError(`Missing Claude source directory: ${paths.claudeSource}`);
+    }
+}
+function installBridge(io, paths, options) {
+    validateSources(paths);
+    const outputStyleSource = resolveOutputStyleSourceFile(paths);
+    if (!outputStyleSource) {
+        throw new BridgeError(`Active outputStyle must have a matching ${paths.outputStylesSource}/<style>.md file.`);
+    }
+    repairOrCreateSymlink(io, options, paths, "global Codex skill bridge (legacy)", paths.skillsSource, paths.globalSkillsTarget);
+    repairOrCreateSymlink(io, options, paths, "global agents skill bridge", paths.skillsSource, paths.globalAgentsSkillsTarget);
+    repairOrCreateSymlink(io, options, paths, "repo agents skill bridge", paths.skillsSource, paths.repoAgentsSkillsTarget);
+    repairOrCreateSymlink(io, options, paths, "project Codex Claude mirror", paths.claudeSource, paths.projectClaudeTarget);
+    repairOrCreateSymlink(io, options, paths, "project Codex output-style bridge", outputStyleSource, paths.projectOutputStyleTarget);
+    if (exists(paths.legacyCodexDir) ||
+        isSymlink(paths.legacyClaudeTarget) ||
+        isSymlink(paths.legacyPromptsTarget)) {
+        repairOrCreateSymlink(io, options, paths, "legacy .Codex Claude mirror", paths.claudeSource, paths.legacyClaudeTarget);
+        repairOrCreateSymlink(io, options, paths, "legacy .Codex output-style bridge", outputStyleSource, paths.legacyOutputStyleTarget);
+    }
+    if (options.repairLocalConfig) {
+        io.out("");
+        rewriteLocalConfigRoots(io, paths, options);
+    }
+    io.out("");
+    return printStatus(io, paths, options);
+}
+/** Runs one bridge command; returns the process exit code. */
+export function runCodexSkillBridge(options, io) {
+    const paths = configurePaths(options.hqRoot, io.home);
+    if (options.command === "status")
+        return printStatus(io, paths, options);
+    const effective = options.command === "doctor" ? { ...options, repairLocalConfig: true } : options;
+    return installBridge(io, paths, effective);
+}
+//# sourceMappingURL=codex-skill-bridge.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.90.0",
+  "version": "5.92.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -29,7 +29,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "^6.14.45",
+    "@indigoai-us/hq-cloud": "^6.14.47",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "1.0.7",