@indigoai-us/hq-cli 5.289.0 → 5.290.0

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

@@ -33,6 +33,8 @@ export interface MergeCopiesCommandOptions {
     variants?: boolean;
     limit?: number;
     only?: string;
+    /** Also re-point refs and links held today (flag merge-rewrite-refs). */
+    rewriteRefs?: boolean;
     json?: boolean;
 }
 /** Reads a `--only` file: a JSON array of `{ copy, original }` company-relative paths. */
@@ -44,7 +46,10 @@ export declare function readListedPairs(file: string): ListedPair[];
  * `checkpoint.ontology.merge-copies` and `checkpoint.ontology.multi-writer`.
  * With `--variants`, merges two-file duplicate groups whose names differ only
  * in case, spacing or punctuation instead, gated by
- * `checkpoint.ontology.merge-variants`.
+ * `checkpoint.ontology.merge-variants`. `--rewrite-refs` (flag
+ * `checkpoint.ontology.merge-rewrite-refs`) also re-points signal refs,
+ * invoice and bill links, source and knowledge links, and carries external
+ * ids and web domains.
  */
 export declare function runOntologyMergeCopies(hqRoot: string, slug: string | undefined, options: MergeCopiesCommandOptions, deps?: OntologyCommandDeps): Promise<string>;
 export declare function registerCoreOntologyCommand(core: Command): void;

package/dist/commands/core-ontology.js

@@ -17,7 +17,7 @@ import { applyOntologyRun, ApplyError } from "../lib/checkpoint-ontology/apply.j
 import { resolveOntologyCompany, WriteBoundsError } from "../lib/checkpoint-ontology/company.js";
 import { findDuplicateGroups, summarizeMergeBack, } from "../lib/checkpoint-ontology/multi-writer.js";
 import { buildEntityIndex } from "../lib/checkpoint-ontology/tree.js";
-import { MERGE_COPIES_FLAG, MERGE_VARIANTS_FLAG, mergeCopies, } from "../lib/checkpoint-ontology/merge-copies.js";
+import { MERGE_COPIES_FLAG, MERGE_REWRITE_REFS_FLAG, MERGE_VARIANTS_FLAG, mergeCopies, } from "../lib/checkpoint-ontology/merge-copies.js";
 import { callDeleteEndpoint } from "./files.js";
 import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
 import { registerCoreOntologyNativeCommands } from "./core-ontology-native.js";
@@ -146,11 +146,12 @@ function mergeCopiesSummary(report) {
     const held = report.plans.filter((plan) => plan.held).length;
     const lines = [
         `ontology merge-copies (${report.mode.replace("_", " ")}) in ${report.company} (${report.pair_kind}): ${report.plans.length} of ${report.copies_found} copies, ${held} held, ${report.skipped.length} skipped`,
-        `  merged ${report.merged.length}, relinked ${report.relinked.length}, deleted ${report.deleted.length}, not ready ${report.not_ready.length}, errors ${report.errors.length}`,
+        `  merged ${report.merged.length}, relinked ${report.relinked.length}${report.rewritten !== undefined ? `, rewritten ${report.rewritten.length}` : ""}, deleted ${report.deleted.length}, not ready ${report.not_ready.length}, errors ${report.errors.length}`,
         `  duplicate groups ${report.duplicate_groups_before} -> ${report.duplicate_groups_after}; broken entity links ${report.broken_links_before} -> ${report.broken_links_after}`,
     ];
-    for (const plan of report.plans.filter((entry) => entry.held))
-        lines.push(`  held ${plan.copy}: ${plan.held}`);
+    for (const plan of report.plans.filter((entry) => entry.held)) {
+        lines.push(`  held ${plan.copy}: ${plan.held}${plan.held === "external_id_conflict" ? ` (${plan.detail})` : ""}`);
+    }
     for (const error of report.errors)
         lines.push(`  error ${error.path}: ${error.error}`);
     for (const entry of report.only_unmatched ?? [])
@@ -176,7 +177,36 @@ export function readListedPairs(file) {
         })) {
         throw new OntologyUsageError("ontology: --only must be a non-empty JSON array of { copy, original } paths");
     }
-    return parsed.map((entry) => ({ copy: entry.copy, original: entry.original }));
+    return parsed.map((entry) => {
+        if (entry.resolve_external_ids === undefined)
+            return { copy: entry.copy, original: entry.original };
+        return { copy: entry.copy, original: entry.original, resolve_external_ids: readResolution(entry.copy, entry.resolve_external_ids) };
+    });
+}
+/** `{ provider: { primary, namespace, object_type? } }`, every value a non-empty string. */
+function readResolution(copy, raw) {
+    const usage = `ontology: --only entry ${copy}: resolve_external_ids must map each provider to { primary, namespace, object_type? } strings`;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw) || Object.keys(raw).length === 0)
+        throw new OntologyUsageError(usage);
+    const out = {};
+    for (const [provider, value] of Object.entries(raw)) {
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            throw new OntologyUsageError(usage);
+        const record = value;
+        const nonEmpty = (field) => typeof field === "string" && field.length > 0;
+        if (!Object.keys(record).every((key) => key === "primary" || key === "namespace" || key === "object_type") ||
+            !nonEmpty(record.primary) ||
+            !nonEmpty(record.namespace) ||
+            (record.object_type !== undefined && !nonEmpty(record.object_type))) {
+            throw new OntologyUsageError(usage);
+        }
+        out[provider] = {
+            primary: record.primary,
+            namespace: record.namespace,
+            ...(record.object_type !== undefined ? { object_type: record.object_type } : {}),
+        };
+    }
+    return out;
 }
 /**
  * `hq core ontology merge-copies`: merge `<slug> <n>.md` copies into their
@@ -185,7 +215,10 @@ export function readListedPairs(file) {
  * `checkpoint.ontology.merge-copies` and `checkpoint.ontology.multi-writer`.
  * With `--variants`, merges two-file duplicate groups whose names differ only
  * in case, spacing or punctuation instead, gated by
- * `checkpoint.ontology.merge-variants`.
+ * `checkpoint.ontology.merge-variants`. `--rewrite-refs` (flag
+ * `checkpoint.ontology.merge-rewrite-refs`) also re-points signal refs,
+ * invoice and bill links, source and knowledge links, and carries external
+ * ids and web domains.
  */
 export async function runOntologyMergeCopies(hqRoot, slug, options, deps = {}) {
     if (options.apply && options.delete) {
@@ -200,7 +233,7 @@ export async function runOntologyMergeCopies(hqRoot, slug, options, deps = {}) {
         throw new OntologyUsageError(`ontology: company rejected: ${resolution.reason}`);
     const company = resolution.company;
     const readFlag = deps.readFlag ?? registryFlagReader;
-    for (const flag of [options.variants ? MERGE_VARIANTS_FLAG : MERGE_COPIES_FLAG, MULTI_WRITER_FLAG]) {
+    for (const flag of [options.variants ? MERGE_VARIANTS_FLAG : MERGE_COPIES_FLAG, MULTI_WRITER_FLAG, ...(options.rewriteRefs ? [MERGE_REWRITE_REFS_FLAG] : [])]) {
         if (!(await readFlag(flag, company))) {
             return options.json ? JSON.stringify({ company: company.slug, skipped: `${flag} off` }) : `ontology merge-copies: skipped (${flag} is off)`;
         }
@@ -220,6 +253,7 @@ export async function runOntologyMergeCopies(hqRoot, slug, options, deps = {}) {
         ...(options.variants ? { pairKind: "variants" } : {}),
         ...(options.limit !== undefined ? { limit: options.limit } : {}),
         ...(only ? { only } : {}),
+        ...(options.rewriteRefs ? { rewriteRefs: true } : {}),
         ...(deleteVaultKey ? { deleteVaultKey } : {}),
     });
     return options.json ? JSON.stringify(report, null, 2) : mergeCopiesSummary(report);
@@ -274,6 +308,7 @@ export function registerCoreOntologyCommand(core) {
         .option("--variants", "merge two-file duplicate groups whose names differ only in case, spacing or punctuation (checkpoint.ontology.merge-variants)")
         .option("--limit <n>", "handle at most this many copies", (value) => Number(value))
         .option("--only <file>", "handle only the copy -> original pairs listed in this JSON file")
+        .option("--rewrite-refs", "also re-point signal refs, invoice, source and knowledge links to the survivor and carry external ids and web domains (checkpoint.ontology.merge-rewrite-refs)")
         .option("--json", "print JSON")
         .option("--hq-root <path>", "HQ installation to operate on")
         .action(async (options) => {

package/dist/commands/core.js

@@ -31,6 +31,7 @@
 import { Option } from "commander";
 import { registerCoreCheckpointCommand } from "./core-checkpoint.js";
 import { registerCoreDelegateCommand } from "./core-delegate.js";
+import { registerCoreHandoffCommand } from "./core-handoff.js";
 import { registerCoreOntologyCommand } from "./core-ontology.js";
 import { registerCoreKnowledgePrefsCommand } from "./core-knowledge-prefs.js";
 import { registerCorePolicyCommand } from "./core-policy.js";
@@ -241,7 +242,7 @@ export const SCAFFOLD_ONLY_ASSETS = [
     { asset: "core/scripts/ontology-source-worklist.sh", root: "live", summary: "Rollback companion for native ontology source worklist" },
     { asset: "core/scripts/source-yaml-validate.sh", root: "cwd", summary: "Rollback companion for native source YAML validation" },
     // Shared by native knowledge-prefs and the ontology candidate shell fallback.
-    { asset: "core/scripts/knowledge-prefs.sh", root: "live", summary: "Rollback companion for native knowledge-prefs and ontology candidate" },
+    { asset: "core/scripts/knowledge-prefs.sh", root: "live", summary: "Sibling dependency for ontology candidate rollback companion" },
     // Rollback companions for the default-off native knowledge and policy routes.
     // policy-retire also runs the scaffold validator in-process when native, but
     // its bundled shell fallback needs both helper assets at these exact paths.
@@ -250,6 +251,11 @@ export const SCAFFOLD_ONLY_ASSETS = [
     { asset: "core/scripts/read-policy-frontmatter.sh", root: "cwd", summary: "Rollback companion for native policy frontmatter" },
     { asset: "core/scripts/eval-trigger.sh", root: "live", summary: "Trigger grammar helper used by the policy validator companion" },
     { asset: ".claude/hooks/validate-policy-frontmatter.sh", root: "live", summary: "Policy validator companion used by policy-retire rollback" },
+    // Wave 2a handoff shells remain bundled as the default-off rollback path.
+    { asset: "core/scripts/handoff-finalize.sh", root: "live", summary: "Rollback shell for native handoff finalize" },
+    { asset: "core/scripts/handoff-post.sh", root: "live", summary: "Rollback shell for native handoff post" },
+    { asset: "core/scripts/handoff-open-steps.sh", root: "live", summary: "Rollback shell for native handoff open-steps" },
+    { asset: "core/scripts/qmd-reindex-bg.sh", root: "live", summary: "Rollback handoff reindex forwarder" },
     ...NATIVE_UTILITY_COMMANDS.map(({ asset, root, summary }) => ({
         asset,
         root,
@@ -326,6 +332,7 @@ export function registerCoreCommands(program) {
     registerCoreOntologyCommand(core);
     registerCoreCheckpointGateSettingCommand(core);
     registerCoreDelegateCommand(core);
+    registerCoreHandoffCommand(core);
     registerCoreKnowledgePrefsCommand(core);
     registerCorePolicyCommand(core);
     // Wave 2 handoff/worktree commands retain their byte-identical shell assets

package/dist/lib/checkpoint-ontology/entity-file.d.ts

@@ -66,6 +66,27 @@ export type PatchResult = {
  * change, the file is returned unchanged so a rerun writes nothing.
  */
 export declare function patchEntityFile(content: string, patch: EntityPatch): PatchResult;
+/** A namespaced record in a source system, as the cloud schema's `external_refs` holds it. */
+export interface ExternalRef {
+    system: string;
+    namespace: string;
+    objectType?: string;
+    recordId: string;
+}
+export interface IdentityPatch {
+    externalIds: Record<string, string>;
+    webDomains: string[];
+    /** When set, the whole `external_refs` list; when absent, the key is left alone. */
+    externalRefs?: ExternalRef[];
+    lastUpdated: string;
+}
+/**
+ * Set `external_ids` and `web_domains` on an existing, valid entity file.
+ * A key whose value is already equal is left as it is; an absent key is
+ * appended at the end of the front matter. Nothing else changes except
+ * `last_updated`. When neither key changes the file is returned unchanged.
+ */
+export declare function setIdentityKeys(content: string, patch: IdentityPatch): PatchResult;
 export interface SignalBackRef {
     signalType: string;
     preview: string;

package/dist/lib/checkpoint-ontology/entity-file.js

@@ -206,6 +206,106 @@ function checkPatched(original, next, aliases, signalCount, lastUpdated) {
         return "patch_last_updated";
     return null;
 }
+function renderExternalIds(ids) {
+    const entries = Object.entries(ids);
+    if (entries.length === 0)
+        return "external_ids: {}";
+    return ["external_ids:", ...entries.map(([key, value]) => `  ${key}: ${quote(value)}`)].join("\n");
+}
+function renderExternalRefs(refs) {
+    if (refs.length === 0)
+        return "external_refs: []";
+    const lines = ["external_refs:"];
+    for (const ref of refs) {
+        lines.push(`  - system: ${quote(ref.system)}`, `    namespace: ${quote(ref.namespace)}`);
+        if (ref.objectType !== undefined)
+            lines.push(`    objectType: ${quote(ref.objectType)}`);
+        lines.push(`    recordId: ${quote(ref.recordId)}`);
+    }
+    return lines.join("\n");
+}
+function renderWebDomains(domains) {
+    if (domains.length === 0)
+        return "web_domains: []";
+    return ["web_domains:", ...domains.map((domain) => `  - ${quote(domain)}`)].join("\n");
+}
+/**
+ * Set `external_ids` and `web_domains` on an existing, valid entity file.
+ * A key whose value is already equal is left as it is; an absent key is
+ * appended at the end of the front matter. Nothing else changes except
+ * `last_updated`. When neither key changes the file is returned unchanged.
+ */
+export function setIdentityKeys(content, patch) {
+    const match = FRONTMATTER_RE.exec(content);
+    const parsed = parseEntityFile(content);
+    if (!match || !parsed)
+        return { ok: false, reason: "unparseable" };
+    const before = validateEntityFrontmatter(parsed.frontmatter);
+    if (typeof before === "string")
+        return { ok: false, reason: `invalid_existing:${before}` };
+    for (const key of Object.keys(patch.externalIds)) {
+        if (!/^[A-Za-z0-9_-]+$/.test(key))
+            return { ok: false, reason: "external_ids_key" };
+    }
+    const currentIds = (parsed.frontmatter.external_ids ?? {});
+    const currentDomains = (parsed.frontmatter.web_domains ?? []);
+    const currentRefs = parsed.frontmatter.external_refs ?? [];
+    const idsChanged = !isDeepStrictEqual(currentIds, patch.externalIds);
+    const domainsChanged = !isDeepStrictEqual(currentDomains, patch.webDomains);
+    const refsChanged = patch.externalRefs !== undefined && !isDeepStrictEqual(currentRefs, patch.externalRefs);
+    if (!idsChanged && !domainsChanged && !refsChanged)
+        return { ok: true, content, changed: false };
+    const newline = content.includes("\r\n") ? "\r\n" : "\n";
+    let lines = match[1].split(/\r?\n/);
+    if (idsChanged) {
+        const rendered = renderExternalIds(patch.externalIds);
+        lines = replaceTopLevelKey(lines, "external_ids", rendered) ?? [...lines, ...rendered.split("\n")];
+    }
+    if (domainsChanged) {
+        const rendered = renderWebDomains(patch.webDomains);
+        lines = replaceTopLevelKey(lines, "web_domains", rendered) ?? [...lines, ...rendered.split("\n")];
+    }
+    if (refsChanged) {
+        const rendered = renderExternalRefs(patch.externalRefs);
+        lines = replaceTopLevelKey(lines, "external_refs", rendered) ?? [...lines, ...rendered.split("\n")];
+    }
+    const stamped = replaceTopLevelKey(lines, "last_updated", `last_updated: ${patch.lastUpdated}`);
+    if (!stamped)
+        return { ok: false, reason: "missing_owned_key" };
+    lines = stamped;
+    const head = content.slice(0, content.indexOf(match[1]));
+    const tail = content.slice(content.indexOf(match[1]) + match[1].length);
+    const next = `${head}${lines.join(newline)}${tail}`;
+    const reparsed = parseEntityFile(next);
+    if (!reparsed)
+        return { ok: false, reason: "patch_unparseable" };
+    if (typeof validateEntityFrontmatter(reparsed.frontmatter) === "string")
+        return { ok: false, reason: "patch_invalid" };
+    const keys = new Set([...Object.keys(parsed.frontmatter), ...Object.keys(reparsed.frontmatter)]);
+    for (const key of keys) {
+        if (key === "external_ids" || key === "web_domains" || key === "last_updated")
+            continue;
+        if (key === "external_refs" && patch.externalRefs !== undefined)
+            continue;
+        if (!isDeepStrictEqual(parsed.frontmatter[key], reparsed.frontmatter[key])) {
+            return { ok: false, reason: `patch_changed_key:${key}` };
+        }
+    }
+    if (!isDeepStrictEqual(reparsed.frontmatter.external_ids ?? {}, patch.externalIds)) {
+        return { ok: false, reason: "patch_external_ids" };
+    }
+    if (!isDeepStrictEqual(reparsed.frontmatter.web_domains ?? [], patch.webDomains)) {
+        return { ok: false, reason: "patch_web_domains" };
+    }
+    if (refsChanged && !isDeepStrictEqual(reparsed.frontmatter.external_refs ?? [], patch.externalRefs)) {
+        return { ok: false, reason: "patch_external_refs" };
+    }
+    if (reparsed.frontmatter.last_updated !== patch.lastUpdated)
+        return { ok: false, reason: "patch_last_updated" };
+    if (reparsed.body !== parsed.body)
+        return { ok: false, reason: "patch_body" };
+    return { ok: true, content: next, changed: true };
+}
 /** hq-pro `previewSignalContent`: first 80 characters, one line. */
 export function previewSignalContent(canonicalContent) {
     const collapsed = canonicalContent.replace(/\s+/g, " ").trim();

package/dist/lib/checkpoint-ontology/merge-copies.d.ts

@@ -26,7 +26,11 @@
  * merge cannot rewrite (a copy, a knowledge file, a signal) is held.
  *
  * A signal whose `entity_refs` names a copy holds that copy: signals are
- * server-owned, so the ref cannot be re-pointed from here.
+ * server-owned, so the ref cannot be re-pointed from here. With `rewriteRefs`
+ * (flag `checkpoint.ontology.merge-rewrite-refs`) signal refs, invoice and
+ * bill links, source and knowledge links are re-pointed at the survivor, the
+ * survivor receives the copy's `external_ids` and `web_domains`, and only a
+ * link from another copy or an external id conflict holds a pair.
  *
  * With `pairKind: "variants"` (flag `checkpoint.ontology.merge-variants`) the
  * pairs are two-file duplicate groups whose canonical names differ only in
@@ -42,6 +46,12 @@ export declare const MERGE_COPIES_FLAG = "checkpoint.ontology.merge-copies";
  * names differ only in spacing, case or punctuation (CO-65).
  */
 export declare const MERGE_VARIANTS_FLAG = "checkpoint.ontology.merge-variants";
+/**
+ * `merge-copies --rewrite-refs`: re-point signal `entity_refs`, invoice and
+ * bill links, source and knowledge links from a copy to its survivor, and
+ * carry the copy's `external_ids` and `web_domains` to the survivor.
+ */
+export declare const MERGE_REWRITE_REFS_FLAG = "checkpoint.ontology.merge-rewrite-refs";
 export type CopySkipReason = "no_original" | "original_invalid" | "identity_differs" | "not_in_duplicate_group" | "group_size" | "type_differs" | "names_differ" | "numbered_copy" | "not_listed";
 export type PairKind = "numbered" | "variants";
 export interface CopySkip {
@@ -55,10 +65,22 @@ export interface CopyPair {
     /** Company-relative path of the original it merges into. */
     original: string;
 }
+/**
+ * How to settle one provider's `external_ids` conflict: `primary` stays in
+ * `external_ids`, and the pair's other id moves to `external_refs` under
+ * `namespace` (the provider account or workspace) and `object_type`.
+ */
+export interface ExternalIdResolution {
+    primary: string;
+    namespace: string;
+    object_type?: string;
+}
 /** One entry of a `--only` list: an exact copy -> original pair. */
 export interface ListedPair {
     copy: string;
     original: string;
+    /** Provider -> resolution, applied only when `rewriteRefs` is on and the ids conflict. */
+    resolve_external_ids?: Record<string, ExternalIdResolution>;
 }
 export interface CopyPlan extends CopyPair {
     add_aliases: string[];
@@ -75,8 +97,14 @@ export interface CopyPlan extends CopyPair {
     /** Signal files whose `entity_refs` name the copy. */
     signal_refs: string[];
     /** Why the copy cannot be merged or deleted from here. */
-    held?: "signal_refs" | "linked_from_unwritable" | "merge_invalid";
+    held?: "signal_refs" | "linked_from_unwritable" | "merge_invalid" | "external_id_conflict";
     detail?: string;
+    /** Keys added to the survivor. Set only when `rewriteRefs` is on. */
+    add_external_ids?: string[];
+    /** Domains added to the survivor. Set only when `rewriteRefs` is on. */
+    add_web_domains?: string[];
+    /** `system:namespace:recordId` refs added to the survivor's `external_refs`. Set only when `rewriteRefs` is on. */
+    add_external_refs?: string[];
     /** Body lines of the copy the merged original lacks; a copy with any is never deleted. */
     unmerged_body_lines: number;
 }
@@ -105,6 +133,8 @@ export interface MergeCopiesReport {
     }[];
     /** Listed entries the finder did not produce. Absent unless `--only` was set. */
     only_unmatched?: ListedPair[];
+    /** Signal, source and knowledge files re-pointed at a survivor. Absent unless `rewriteRefs` was set. */
+    rewritten?: string[];
     /** Entity-file links whose target file does not exist. */
     broken_links_before: number;
     broken_links_after: number;
@@ -123,6 +153,8 @@ export interface MergeCopiesOptions {
     limit?: number;
     /** Handle only these exact pairs; every other found pair is skipped as `not_listed`. */
     only?: ListedPair[];
+    /** Re-point refs and links held today, and carry ids and domains (flag merge-rewrite-refs). */
+    rewriteRefs?: boolean;
     now: Date;
     deleteVaultKey?: DeleteVaultKey;
 }