@indigoai-us/hq-cli 5.193.1 → 5.194.1

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## [Unreleased]
 
+## [5.194.1] — 2026-09-25
+
+### Fixed
+
+- `hq core ontology apply` no longer creates a new entity that is probably an
+  existing one. A candidate whose alias is already another entity's name or
+  alias, or a person whose name contains every word of an existing person's
+  full name (for example "Chaudhry Hassaan Saleem" and "Hassaan Saleem"), is
+  held back and reported as a suspect duplicate.
+
+## [5.194.0] — 2026-09-25
+
+### Added
+
+- `hq core checkpoint` can now maintain the company ontology, the job the
+  cloud ontology gardener did. It is off unless the hq-flags flag
+  `checkpoint.ontology` is on for the checkpoint's company
+  (`HQ_FLAG_CHECKPOINT_ONTOLOGY` is the local override). When a checkpoint
+  names a company, the background sibling runs `hq core ontology plan`, which
+  checks the flag and lists the company knowledge and signal files that
+  changed since the last run, within a fixed input and token budget. The
+  sibling writes entity candidates for those files, and
+  `hq core ontology apply` validates them and writes them. It updates an
+  existing entity rather than creating a duplicate, and keeps entity ids in
+  the cloud's format. It writes only to the checkpoint's own company and never
+  follows a symlink. It adds a back-reference to each signal that names an
+  entity, skipping signals the gardener already linked, and a rerun changes
+  nothing. Files under `@{key}` audience folders are not read.
+
 ## [5.193.1] — 2026-09-25
 
 ### Fixed

package/dist/command-catalog.generated.d.ts

@@ -5101,6 +5101,45 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly description: "print the planned checkpoint without writing";
         }];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "ontology";
+        readonly description: "Checkpoint ontology steps run by the checkpoint sibling (gated by checkpoint.ontology)";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options] [command]";
+        readonly arguments: readonly [];
+        readonly options: readonly [];
+        readonly subcommands: readonly [{
+            readonly name: "plan";
+            readonly description: "Check the flag and list the changed company files for this checkpoint run";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--run-dir <path>";
+                readonly description: "checkpoint sibling run directory holding payload.json";
+            }, {
+                readonly flags: "--hq-root <path>";
+                readonly description: "HQ installation to operate on";
+            }];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "apply";
+            readonly description: "Validate the run's entity candidates and write them to the payload company";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--run-dir <path>";
+                readonly description: "checkpoint sibling run directory holding the plan and candidates";
+            }, {
+                readonly flags: "--hq-root <path>";
+                readonly description: "HQ installation to operate on";
+            }];
+            readonly subcommands: readonly [];
+        }];
     }, {
         readonly name: "generate-workers-registry";
         readonly description: "Regenerate the derived workers registry";

package/dist/command-catalog.generated.js

@@ -6598,6 +6598,55 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "ontology",
+                "description": "Checkpoint ontology steps run by the checkpoint sibling (gated by checkpoint.ontology)",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] [command]",
+                "arguments": [],
+                "options": [],
+                "subcommands": [
+                    {
+                        "name": "plan",
+                        "description": "Check the flag and list the changed company files for this checkpoint run",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--run-dir <path>",
+                                "description": "checkpoint sibling run directory holding payload.json"
+                            },
+                            {
+                                "flags": "--hq-root <path>",
+                                "description": "HQ installation to operate on"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "apply",
+                        "description": "Validate the run's entity candidates and write them to the payload company",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--run-dir <path>",
+                                "description": "checkpoint sibling run directory holding the plan and candidates"
+                            },
+                            {
+                                "flags": "--hq-root <path>",
+                                "description": "HQ installation to operate on"
+                            }
+                        ],
+                        "subcommands": []
+                    }
+                ]
+            },
             {
                 "name": "generate-workers-registry",
                 "description": "Regenerate the derived workers registry",

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

@@ -40,8 +40,19 @@ export declare const CHECKPOINT_IDLE_REPLY_REMINDER: string;
  * 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   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;
+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.\n<ontologyStep>6. 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";
+/**
+ * Rendered into the sibling prompt only when the payload names a company. The
+ * flag check happens inside `hq core ontology plan`, in the sibling, because
+ * the checkpoint parent performs no network I/O. Only this run's own payload
+ * gets the step; claimed queue payloads are covered by the next run, since the
+ * plan works from file hashes rather than from the payload's file list.
+ */
+export declare const SIBLING_ONTOLOGY_STEP = "5b. ONTOLOGY (this run's own payload only; skip it for claimed queue payloads).\n   Run: hq core ontology plan --run-dir \"<runDir>\" --hq-root \"<hqRoot>\"\n   If it prints \"ontology: skipped\", do nothing more for this step. Otherwise\n   read <runDir>/ontology-plan.json, follow its \"instructions\" exactly, and\n   write <runDir>/ontology-candidates.json. Read only the files and line\n   ranges the plan lists. Then run:\n   hq core ontology apply --run-dir \"<runDir>\" --hq-root \"<hqRoot>\"\n   Never write under the company's ontology/ folder yourself, and never edit\n   payload.json or ontology-plan.json. Copy the command's one-line output into\n   the report. If either command fails, record the error and continue.\n";
+export declare function renderSiblingPrompt(runDir: string, payloadPath: string, options?: {
+    company?: string | null;
+    hqRoot?: string;
+}): string;
 export type WriteStampsOptions = {
     /**
      * Filesystem seam (default the real `node:fs`); injected in tests to force a

package/dist/commands/core-checkpoint.js

@@ -165,7 +165,7 @@ report instead of guessing.
    core/knowledge/public/hq-core/index-md-spec.md. Mechanical index generation
    is allowed for those companies, but knowledge/policy content writes remain
    restricted to the payload's named company.
-6. Run .claude/skills/document-release/SKILL.md best-effort when it exists;
+<ontologyStep>6. Run .claude/skills/document-release/SKILL.md best-effort when it exists;
    skip silently on any failure. Hook or automation improvements go ONLY under
    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.
@@ -182,10 +182,31 @@ report instead of guessing.
    NEVER read the queue and truncate it in place: a payload appended between
    your read and the truncate is lost, and its checkpoint is never enriched.
 `;
-export function renderSiblingPrompt(runDir, payloadPath) {
+/**
+ * Rendered into the sibling prompt only when the payload names a company. The
+ * flag check happens inside `hq core ontology plan`, in the sibling, because
+ * the checkpoint parent performs no network I/O. Only this run's own payload
+ * gets the step; claimed queue payloads are covered by the next run, since the
+ * plan works from file hashes rather than from the payload's file list.
+ */
+export const SIBLING_ONTOLOGY_STEP = `5b. ONTOLOGY (this run's own payload only; skip it for claimed queue payloads).
+   Run: hq core ontology plan --run-dir "<runDir>" --hq-root "<hqRoot>"
+   If it prints "ontology: skipped", do nothing more for this step. Otherwise
+   read <runDir>/ontology-plan.json, follow its "instructions" exactly, and
+   write <runDir>/ontology-candidates.json. Read only the files and line
+   ranges the plan lists. Then run:
+   hq core ontology apply --run-dir "<runDir>" --hq-root "<hqRoot>"
+   Never write under the company's ontology/ folder yourself, and never edit
+   payload.json or ontology-plan.json. Copy the command's one-line output into
+   the report. If either command fails, record the error and continue.
+`;
+export function renderSiblingPrompt(runDir, payloadPath, options = {}) {
+    const ontologyStep = options.company && options.hqRoot ? SIBLING_ONTOLOGY_STEP : "";
     return SIBLING_PROMPT_TEMPLATE
+        .replaceAll("<ontologyStep>", () => ontologyStep)
         .replaceAll("<runDir>", () => runDir)
-        .replaceAll("<payloadPath>", () => payloadPath);
+        .replaceAll("<payloadPath>", () => payloadPath)
+        .replaceAll("<hqRoot>", () => options.hqRoot ?? "");
 }
 function collect(value, previous) {
     return [...previous, value];
@@ -946,7 +967,7 @@ function startSibling(liveRoot, input, threadPath, backend) {
     payload.pending_payloads = claimPending(pendingPath, path.join(runDir, "pending-claimed.jsonl"));
     const payloadPath = path.join(runDir, "payload.json");
     fs.writeFileSync(payloadPath, `${JSON.stringify(payload, null, 2)}\n`);
-    const prompt = renderSiblingPrompt(runDir, payloadPath);
+    const prompt = renderSiblingPrompt(runDir, payloadPath, { company: payload.company, hqRoot: liveRoot });
     fs.writeFileSync(path.join(runDir, "prompt.md"), prompt);
     const logPath = path.join(runDir, "run.log");
     const logFd = fs.openSync(logPath, "a");

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

@@ -0,0 +1,22 @@
+/**
+ * `hq core ontology plan|apply` — the checkpoint sibling's ontology steps.
+ *
+ * The checkpoint parent never runs these: `plan` reads the hq-flags registry,
+ * which is network I/O. The detached sibling runs `plan`, writes candidates
+ * from the files the plan lists, then runs `apply`. Both commands take the
+ * company from the run's `payload.json`, never from the agent, so an agent
+ * cannot point the writes at another company.
+ */
+import { Command } from "commander";
+import { type FlagReader } from "../lib/checkpoint-ontology/plan.js";
+export declare const ONTOLOGY_PAYLOAD_FILE = "payload.json";
+/** The hq-flags read, scoped to the payload company. */
+export declare const registryFlagReader: FlagReader;
+export interface OntologyCommandDeps {
+    readFlag?: FlagReader;
+    now?: () => Date;
+}
+export declare function runOntologyPlan(hqRoot: string, runDirOption: string | undefined, deps?: OntologyCommandDeps): Promise<string>;
+export declare function runOntologyApply(hqRoot: string, runDirOption: string | undefined, deps?: OntologyCommandDeps): string;
+export declare function registerCoreOntologyCommand(core: Command): void;
+//# sourceMappingURL=core-ontology.d.ts.map

package/dist/commands/core-ontology.js

@@ -0,0 +1,114 @@
+/**
+ * `hq core ontology plan|apply` — the checkpoint sibling's ontology steps.
+ *
+ * The checkpoint parent never runs these: `plan` reads the hq-flags registry,
+ * which is network I/O. The detached sibling runs `plan`, writes candidates
+ * from the files the plan lists, then runs `apply`. Both commands take the
+ * company from the run's `payload.json`, never from the agent, so an agent
+ * cannot point the writes at another company.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { resolveLiveRoot } from "../utils/hq-roots.js";
+import { readLanesRegistryFlag } from "../lib/lanes/registry-flag.js";
+import { planOntologyRun } from "../lib/checkpoint-ontology/plan.js";
+import { applyOntologyRun, ApplyError } from "../lib/checkpoint-ontology/apply.js";
+import { WriteBoundsError } from "../lib/checkpoint-ontology/company.js";
+export const ONTOLOGY_PAYLOAD_FILE = "payload.json";
+class OntologyUsageError extends Error {
+}
+function readPayload(runDir) {
+    const file = path.join(runDir, ONTOLOGY_PAYLOAD_FILE);
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new OntologyUsageError(`ontology: cannot read ${file} (${error.name})`);
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new OntologyUsageError(`ontology: ${file} is not a JSON object`);
+    }
+    return raw;
+}
+function requireRunDir(runDir) {
+    if (!runDir)
+        throw new OntologyUsageError("ontology: --run-dir is required");
+    const resolved = path.resolve(runDir);
+    if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+        throw new OntologyUsageError(`ontology: run directory not found: ${resolved}`);
+    }
+    return resolved;
+}
+/** The hq-flags read, scoped to the payload company. */
+export const registryFlagReader = (flagKey, company) => readLanesRegistryFlag(flagKey, {
+    company: company.cloudUid ? { slug: company.slug, uid: company.cloudUid } : null,
+});
+export async function runOntologyPlan(hqRoot, runDirOption, deps = {}) {
+    const runDir = requireRunDir(runDirOption);
+    const outcome = await planOntologyRun({
+        hqRoot,
+        runDir,
+        payload: readPayload(runDir),
+        readFlag: deps.readFlag ?? registryFlagReader,
+        now: deps.now?.(),
+    });
+    if (outcome.status === "skipped")
+        return `ontology: skipped (${outcome.reason})`;
+    const { plan } = outcome;
+    return (`ontology: planned ${plan.inputs.length} input(s), ~${plan.budget.planned_tokens} tokens, ` +
+        `${plan.pending_after_run} left for later runs; plan at ${outcome.planPath}`);
+}
+export function runOntologyApply(hqRoot, runDirOption, deps = {}) {
+    const runDir = requireRunDir(runDirOption);
+    const company = readPayload(runDir).company;
+    if (typeof company !== "string" || company === "") {
+        throw new OntologyUsageError("ontology: the run payload names no company");
+    }
+    const report = applyOntologyRun({ hqRoot, runDir, company, now: deps.now?.() });
+    if (report.status !== "applied")
+        return `ontology: ${report.status.replaceAll("_", " ")}; nothing written`;
+    return (`ontology: ${report.created.length} created, ${report.updated.length} updated, ` +
+        `${report.matched} matched, ${report.rejected.length} rejected, ${report.deferred.length} deferred, ` +
+        `${report.suspect_duplicates.length} suspect duplicate(s), ${report.write_errors.length} write error(s)`);
+}
+function fail(error) {
+    if (error instanceof OntologyUsageError || error instanceof ApplyError || error instanceof WriteBoundsError) {
+        process.stderr.write(`${error.message}\n`);
+        process.exit(1);
+    }
+    throw error;
+}
+export function registerCoreOntologyCommand(core) {
+    const ontology = core
+        .command("ontology")
+        .description("Checkpoint ontology steps run by the checkpoint sibling (gated by checkpoint.ontology)");
+    const rootFor = (options) => resolveLiveRoot({ hqRoot: options.hqRoot ?? core.opts().hqRoot });
+    ontology
+        .command("plan")
+        .description("Check the flag and list the changed company files for this checkpoint run")
+        .option("--run-dir <path>", "checkpoint sibling run directory holding payload.json")
+        .option("--hq-root <path>", "HQ installation to operate on")
+        .action(async (options) => {
+        try {
+            process.stdout.write(`${await runOntologyPlan(rootFor(options), options.runDir)}\n`);
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+    ontology
+        .command("apply")
+        .description("Validate the run's entity candidates and write them to the payload company")
+        .option("--run-dir <path>", "checkpoint sibling run directory holding the plan and candidates")
+        .option("--hq-root <path>", "HQ installation to operate on")
+        .action((options) => {
+        try {
+            process.stdout.write(`${runOntologyApply(rootFor(options), options.runDir)}\n`);
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+}
+//# sourceMappingURL=core-ontology.js.map

package/dist/commands/core.js

@@ -30,6 +30,7 @@
  */
 import { Option } from "commander";
 import { registerCoreCheckpointCommand } from "./core-checkpoint.js";
+import { registerCoreOntologyCommand } from "./core-ontology.js";
 import { resolveLiveRoot } from "../utils/hq-roots.js";
 import { runBundledScript } from "../utils/run-bundled-script.js";
 import { renderIndexTarget } from "../lib/index-render/index.js";
@@ -322,6 +323,7 @@ export function registerCoreCommands(program) {
     // This group primarily hosts manifest-driven bundled assets, but it also
     // hosts native TypeScript plumbing when a scaffold contract needs it.
     registerCoreCheckpointCommand(core);
+    registerCoreOntologyCommand(core);
     // These command names intentionally own native implementations. Their
     // similarly named scaffold assets are forwarders, so sending them through
     // runEntry would recurse back into this command forever.

package/dist/lib/checkpoint-ontology/apply.d.ts

@@ -0,0 +1,120 @@
+/**
+ * `hq core ontology apply`: turn the model's candidates into entity writes.
+ *
+ * Every rule that affects identity, scope or cost lives here (design
+ * sections 4.3, 5 and 14). The model output is untrusted input: a malformed
+ * candidate is rejected and counted, never repaired.
+ */
+import { type WritableEntityType } from "./identity.js";
+import { type EntityIndex } from "./tree.js";
+export declare const CAPS: {
+    readonly creates: 25;
+    readonly updates: 100;
+    readonly bytes: number;
+    readonly newAliasesPerEntity: 3;
+    readonly aliasesPerCandidate: 5;
+    readonly nameLength: 200;
+};
+export declare const MIN_CREATE_CONFIDENCE = 0.7;
+export interface Candidate {
+    input: string;
+    type: WritableEntityType;
+    name: string;
+    aliases: string[];
+    confidence: number;
+    evidence: string;
+}
+export interface ApplyReport {
+    schema: "hq-checkpoint-ontology-report.v1";
+    company: string;
+    run_id: string;
+    status: "applied" | "no_candidates" | "invalid_candidates";
+    planned_inputs: number;
+    planned_tokens: number;
+    candidates: number;
+    created: string[];
+    updated: string[];
+    matched: number;
+    session_links: Array<{
+        type: string;
+        canonical_name: string;
+        path: string;
+    }>;
+    /** Per input, the entities it resolved to: `link` for an existing entity, `create` for a new file. */
+    links: Array<{
+        input: string;
+        action: "link" | "create";
+        type: string;
+        canonical_name: string;
+        path: string;
+    }>;
+    rejected: Array<{
+        input: string;
+        type: string;
+        name: string;
+        reason: string;
+    }>;
+    deferred: Array<{
+        input: string;
+        type: string;
+        name: string;
+        reason: string;
+    }>;
+    suspect_duplicates: Array<{
+        name: string;
+        type: string;
+        paths: string[];
+    }>;
+    backrefs_added: number;
+    bytes_written: number;
+    inputs_done: string[];
+    inputs_pending: string[];
+    write_errors: Array<{
+        path: string;
+        reason: string;
+    }>;
+    duration_ms: number;
+}
+export interface ApplyOptions {
+    hqRoot: string;
+    runDir: string;
+    /** The payload company. Must equal the plan's company. */
+    company: string;
+    now?: Date;
+}
+export declare class ApplyError extends Error {
+    constructor(message: string);
+}
+/** Validate one raw candidate. Returns the candidate or a rejection reason. */
+export declare function parseCandidate(raw: unknown): Candidate | string;
+type Resolution = {
+    tier: 1;
+    target: string;
+    duplicates: string[];
+} | {
+    tier: 2;
+    target: string;
+} | {
+    tier: "ambiguous_alias";
+    paths: string[];
+} | {
+    tier: "suspect_duplicate";
+    paths: string[];
+} | {
+    tier: "type_conflict";
+    types: string[];
+} | {
+    tier: "new";
+};
+/** Design section 5.3, tiers 1 to 4. */
+export declare function resolveCandidate(index: EntityIndex, type: string, canonical: string): Resolution;
+/**
+ * Existing entities of `type` that a new candidate probably is: one of the
+ * candidate's aliases is already their name or alias, or, for people, every
+ * word of their name (two words or more) is in the candidate's name
+ * (`Chaudhry Hassaan Saleem` and `Hassaan Saleem`).
+ */
+export declare function overlappingEntities(index: EntityIndex, type: string, canonical: string, aliases: string[]): string[];
+export declare function applyOntologyRun(options: ApplyOptions): ApplyReport;
+export {};
+//# sourceMappingURL=apply.d.ts.map