@indigoai-us/hq-cli 5.228.4 → 5.229.0

package/CHANGELOG.md

@@ -2,7 +2,16 @@
 
 ## [Unreleased]
 
-## [5.228.4] — 2026-09-27
+## [5.229.0] — 2026-09-27
+
+### Added
+
+- Behind the off-by-default `checkpoint.ontology.entity-hints` flag, each
+  knowledge input in the checkpoint ontology plan lists up to 25 existing
+  entities whose name appears in the text the model reads
+  (`known_entities`). The model is told to use those names instead of naming a
+  new entity, and to skip glossary or translation table rows, paths and names
+  built from tags or slugs.
 
 ### Fixed
 

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

@@ -0,0 +1,41 @@
+/**
+ * Existing entities an input names, for `checkpoint.ontology.entity-hints`.
+ *
+ * The model never sees the company's entities, so it can only link one when it
+ * happens to pick a name or alias the index holds. On the CO-39 fixtures it
+ * created `SpaceXAI` beside `xAI`, `Indigo desktop app` beside `indigo-nx`
+ * (alias `Indigo desktop repo`) and `hq-work-site` beside `Indigo Workspace`
+ * (workspace/checkpoint-ontology/analysis/co41-wrong-creates.json). Each
+ * input's plan entry lists the existing entities whose name the input text
+ * contains, so the model can use that name.
+ */
+import type { EntityIndex } from "./tree.js";
+export declare const ENTITY_HINTS: {
+    /** Entities listed per input. */
+    readonly perInput: 25;
+    /** An alias match counts this fraction of a canonical-name match with the same words. */
+    readonly aliasWeight: 0.5;
+    /** Aliases shown per entity. */
+    readonly aliases: 3;
+    /** Longest name, in words, matched through the n-gram set. Longer names use a phrase search. */
+    readonly maxGram: 4;
+};
+export interface EntityHint {
+    type: string;
+    name: string;
+    aliases: string[];
+}
+/**
+ * Inverse document frequency of each word over the entities' match names, so
+ * `Sentry` outranks `HQ Build` in a document that names both.
+ */
+export declare function wordWeights(index: EntityIndex): Map<string, number>;
+/**
+ * Up to `ENTITY_HINTS.perInput` writable entities whose canonical name or
+ * qualifying alias appears in `text` as whole words within one sentence, table
+ * cell or markdown block, highest weight first (ties by path). A match scores the summed word weights, halved for an alias.
+ * Entities with the same type and canonical name are listed once. Only
+ * entities from `index`, which is the plan's own company.
+ */
+export declare function entityHints(index: EntityIndex, weights: Map<string, number>, text: string): EntityHint[];
+//# sourceMappingURL=hints.d.ts.map

package/dist/lib/checkpoint-ontology/hints.js

@@ -0,0 +1,146 @@
+/**
+ * Existing entities an input names, for `checkpoint.ontology.entity-hints`.
+ *
+ * The model never sees the company's entities, so it can only link one when it
+ * happens to pick a name or alias the index holds. On the CO-39 fixtures it
+ * created `SpaceXAI` beside `xAI`, `Indigo desktop app` beside `indigo-nx`
+ * (alias `Indigo desktop repo`) and `hq-work-site` beside `Indigo Workspace`
+ * (workspace/checkpoint-ontology/analysis/co41-wrong-creates.json). Each
+ * input's plan entry lists the existing entities whose name the input text
+ * contains, so the model can use that name.
+ */
+export const ENTITY_HINTS = {
+    /** Entities listed per input. */
+    perInput: 25,
+    /** An alias match counts this fraction of a canonical-name match with the same words. */
+    aliasWeight: 0.5,
+    /** Aliases shown per entity. */
+    aliases: 3,
+    /** Longest name, in words, matched through the n-gram set. Longer names use a phrase search. */
+    maxGram: 4,
+};
+const HINT_TYPES = new Set(["person", "project", "company", "concept"]);
+/** Token that stands for a sentence, cell or block boundary. A name never matches across one it does not contain. */
+const BOUNDARY = "\n";
+const TOKEN = /[\p{L}\p{N}]+|[.!?;:](?=\s|$)|\|/gu;
+/**
+ * A line that continues the previous one when the previous one is prose or a
+ * list item: hard-wrapped markdown keeps a name that wraps across the line
+ * break. Blank lines, headings, list items, table rows, quotes and fences start
+ * a new block.
+ */
+function continuesProse(line) {
+    return line.trim() !== "" && !/^\s*(#|[-*+]\s|\d+[.)]\s|\||>|```|~~~)/.test(line);
+}
+/**
+ * Lowercased words, with `BOUNDARY` between sentences (`.`, `!`, `?`, `;` or
+ * `:` before whitespace), table cells and markdown blocks. Names and text are
+ * split the same way, so a name that holds a boundary, such as `Tip 001:
+ * checkpoint`, still matches its own text.
+ */
+function tokens(text) {
+    const out = [];
+    const push = (token) => {
+        if (token !== BOUNDARY || (out.length > 0 && out[out.length - 1] !== BOUNDARY))
+            out.push(token);
+    };
+    let prevProse = null;
+    for (const line of text.toLowerCase().split("\n")) {
+        const prose = continuesProse(line);
+        if (prevProse !== null && !(prose && prevProse))
+            push(BOUNDARY);
+        for (const match of line.matchAll(TOKEN))
+            push(/^[\p{L}\p{N}]/u.test(match[0]) ? match[0] : BOUNDARY);
+        prevProse = prose || /^\s*([-*+]|\d+[.)])\s/.test(line);
+    }
+    while (out[0] === BOUNDARY)
+        out.shift();
+    while (out[out.length - 1] === BOUNDARY)
+        out.pop();
+    return out;
+}
+function words(name) {
+    return name.filter((token) => token !== BOUNDARY);
+}
+function matchNames(entity) {
+    const out = [];
+    const canonical = tokens(entity.canonical_name);
+    if (words(canonical).length > 0)
+        out.push({ tokens: canonical, weight: 1 });
+    for (const alias of entity.aliases) {
+        const aliasTokens = tokens(alias);
+        const count = words(aliasTokens).length;
+        if (count >= 2 || (count === 1 && /[-_./0-9]/.test(alias))) {
+            out.push({ tokens: aliasTokens, weight: ENTITY_HINTS.aliasWeight, alias });
+        }
+    }
+    return out;
+}
+/**
+ * Inverse document frequency of each word over the entities' match names, so
+ * `Sentry` outranks `HQ Build` in a document that names both.
+ */
+export function wordWeights(index) {
+    const counts = new Map();
+    let total = 0;
+    for (const entity of index.byRel.values()) {
+        if (!HINT_TYPES.has(entity.type))
+            continue;
+        total += 1;
+        for (const word of new Set(matchNames(entity).flatMap((name) => words(name.tokens))))
+            counts.set(word, (counts.get(word) ?? 0) + 1);
+    }
+    const weights = new Map();
+    for (const [word, count] of counts)
+        weights.set(word, Math.log((total + 1) / count));
+    return weights;
+}
+/**
+ * Up to `ENTITY_HINTS.perInput` writable entities whose canonical name or
+ * qualifying alias appears in `text` as whole words within one sentence, table
+ * cell or markdown block, highest weight first (ties by path). A match scores the summed word weights, halved for an alias.
+ * Entities with the same type and canonical name are listed once. Only
+ * entities from `index`, which is the plan's own company.
+ */
+export function entityHints(index, weights, text) {
+    const textTokens = tokens(text);
+    const grams = new Set();
+    for (let i = 0; i < textTokens.length; i += 1) {
+        for (let n = 1; n <= ENTITY_HINTS.maxGram && i + n <= textTokens.length; n += 1) {
+            grams.add(textTokens.slice(i, i + n).join(" "));
+        }
+    }
+    const padded = ` ${textTokens.join(" ")} `;
+    const best = new Map();
+    for (const entity of index.byRel.values()) {
+        if (!HINT_TYPES.has(entity.type))
+            continue;
+        let score = 0;
+        const matched = [];
+        for (const name of matchNames(entity)) {
+            const phrase = name.tokens.join(" ");
+            const found = name.tokens.length <= ENTITY_HINTS.maxGram ? grams.has(phrase) : padded.includes(` ${phrase} `);
+            if (!found)
+                continue;
+            if (name.alias !== undefined)
+                matched.push(name.alias);
+            score = Math.max(score, name.weight * words(name.tokens).reduce((sum, word) => sum + (weights.get(word) ?? 0), 0));
+        }
+        if (score <= 0)
+            continue;
+        const key = `${entity.type}\0${entity.canonical_name.toLowerCase()}`;
+        const held = best.get(key);
+        if (!held || score > held.score || (score === held.score && entity.rel < held.entity.rel))
+            best.set(key, { entity, score, matched });
+    }
+    return [...best.values()]
+        .sort((a, b) => b.score - a.score || (a.entity.rel < b.entity.rel ? -1 : a.entity.rel > b.entity.rel ? 1 : 0))
+        .slice(0, ENTITY_HINTS.perInput)
+        .map(({ entity, matched }) => ({
+        type: entity.type,
+        name: entity.canonical_name,
+        // Aliases the text used come first, so the model sees the name it read.
+        aliases: [...matched, ...entity.aliases.filter((alias) => !matched.includes(alias))].slice(0, ENTITY_HINTS.aliases),
+    }));
+}
+//# sourceMappingURL=hints.js.map

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

@@ -10,6 +10,7 @@
 import { type CompanyBriefResult } from "./company-brief.js";
 import { type OntologyCompany } from "./company.js";
 import { type MultiWriterStart } from "./multi-writer.js";
+import { type EntityHint } from "./hints.js";
 export declare const ONTOLOGY_FLAG = "checkpoint.ontology";
 export declare const COMPANY_BRIEF_FLAG = "checkpoint.ontology.company-brief";
 /**
@@ -31,6 +32,13 @@ export declare const GROK_BACKEND_FLAG = "checkpoint.ontology.grok-backend";
  * duplicate entities.
  */
 export declare const MULTI_WRITER_FLAG = "checkpoint.ontology.multi-writer";
+/**
+ * Each knowledge input lists the existing entities its text names
+ * (`known_entities`), and the model is told to use those names and to skip
+ * table rows, paths and slugs. CO-41: 11 of 93 creates in the CO-39 grok-4.6
+ * runs were model errors, 5 of them duplicates of an existing entity.
+ */
+export declare const ENTITY_HINTS_FLAG = "checkpoint.ontology.entity-hints";
 export declare const PLAN_FILE = "ontology-plan.json";
 export declare const CANDIDATES_FILE = "ontology-candidates.json";
 export declare const REPORT_FILE = "ontology-report.json";
@@ -80,6 +88,8 @@ export interface PlanInput {
     missing_refs?: string[];
     /** Run-directory-relative copy of `path` with annotator entity lists removed; same line numbers. */
     read_path?: string;
+    /** Existing entities this input's text names; only when `checkpoint.ontology.entity-hints` is on. */
+    known_entities?: EntityHint[];
 }
 export interface OntologyPlan {
     schema: typeof PLAN_SCHEMA;
@@ -138,6 +148,7 @@ export type PlanOutcome = {
     companyBrief?: CompanyBriefResult;
 };
 export declare const READ_PATH_INSTRUCTION = "When an input has read_path, read that file (relative to the run directory) instead of path, with the same line range. It is the same text with an older annotator's entity lists and entity links removed.";
+export declare const ENTITY_HINTS_INSTRUCTIONS: string[];
 export declare function ledgerPath(hqRoot: string, company: OntologyCompany): string;
 export declare function readLedger(hqRoot: string, company: OntologyCompany): Ledger | null;
 export declare function writeLedger(hqRoot: string, company: OntologyCompany, ledger: Ledger): void;

package/dist/lib/checkpoint-ontology/plan.js

@@ -13,6 +13,7 @@ import * as path from "node:path";
 import { writeCompanyBrief } from "./company-brief.js";
 import { resolveOntologyCompany, safeWriteFile, stateRoot } from "./company.js";
 import { startMultiWriterRun } from "./multi-writer.js";
+import { entityHints, wordWeights } from "./hints.js";
 import { buildEntityIndex, listKnowledgeFiles, listSignalFiles, readSignal } from "./tree.js";
 export const ONTOLOGY_FLAG = "checkpoint.ontology";
 export const COMPANY_BRIEF_FLAG = "checkpoint.ontology.company-brief";
@@ -35,6 +36,13 @@ export const GROK_BACKEND_FLAG = "checkpoint.ontology.grok-backend";
  * duplicate entities.
  */
 export const MULTI_WRITER_FLAG = "checkpoint.ontology.multi-writer";
+/**
+ * Each knowledge input lists the existing entities its text names
+ * (`known_entities`), and the model is told to use those names and to skip
+ * table rows, paths and slugs. CO-41: 11 of 93 creates in the CO-39 grok-4.6
+ * runs were model errors, 5 of them duplicates of an existing entity.
+ */
+export const ENTITY_HINTS_FLAG = "checkpoint.ontology.entity-hints";
 export const PLAN_FILE = "ontology-plan.json";
 export const CANDIDATES_FILE = "ontology-candidates.json";
 export const REPORT_FILE = "ontology-report.json";
@@ -47,6 +55,10 @@ export const BUDGET = {
     chunkTokens: 12_000,
 };
 export const READ_PATH_INSTRUCTION = "When an input has read_path, read that file (relative to the run directory) instead of path, with the same line range. It is the same text with an older annotator's entity lists and entity links removed.";
+export const ENTITY_HINTS_INSTRUCTIONS = [
+    "A knowledge input's known_entities lists entities that already exist in the company and whose names appear in its text. When the input refers to one of them, under that name or another, use that entity's name and type exactly and do not name a new entity for it.",
+    "Skip rows of a glossary or translation table, file and directory paths, and names built from tags or slugs.",
+];
 const CANDIDATE_INSTRUCTIONS = [
     `Write ${CANDIDATES_FILE} in the run directory as {"schema":"${CANDIDATES_SCHEMA}","candidates":[...]} and nothing else.`,
     "Each candidate: {input, type, name, aliases, confidence, evidence}. input is one of this plan's input ids; type is person, project, company or concept; name is the entity's full proper name; aliases are other names the input uses for it (at most 5); confidence is 0 to 1; evidence is a short quote from the input.",
@@ -206,6 +218,7 @@ export async function planOntologyRun(options) {
     const ignoreAnnotations = (await options.readFlag(IGNORE_ANNOTATIONS_FLAG, company)) && payload.backend === "grok";
     recordBackendPreference(hqRoot, company, await options.readFlag(GROK_BACKEND_FLAG, company));
     const multiWriterOn = await options.readFlag(MULTI_WRITER_FLAG, company);
+    const hintsOn = await options.readFlag(ENTITY_HINTS_FLAG, company);
     const touched = sessionTouched(hqRoot, company, payload.files);
     // A first run takes its boundary from the entity tree, so the ledger is
     // refreshed before merge-back moves any `last_updated` forward.
@@ -218,6 +231,15 @@ export async function planOntologyRun(options) {
     const pending = Object.entries(ledger.entries)
         .filter(([, entry]) => entry.state === "pending" && entry.reason === "session-touched")
         .sort(([aRel, a], [bRel, b]) => a.mtime_ms - b.mtime_ms || aRel.localeCompare(bRel));
+    // Built after merge-back, so merged entities are hinted too.
+    let hintIndex = null;
+    const hintsFor = (text) => {
+        if (!hintIndex) {
+            const index = buildEntityIndex(company.dir);
+            hintIndex = { index, weights: wordWeights(index) };
+        }
+        return entityHints(hintIndex.index, hintIndex.weights, text);
+    };
     const inputs = [];
     let tokens = 0;
     let remaining = 0;
@@ -242,6 +264,10 @@ export async function planOntologyRun(options) {
             const cost = estTokens(Buffer.byteLength(lines.slice(start - 1, end).join("\n"), "utf8"));
             if (inputs.length >= BUDGET.maxInputs || tokens + cost > BUDGET.maxTokens)
                 break;
+            // The model reads the stripped copy when there is one; its line numbers match.
+            const knownEntities = hintsOn && kind === "knowledge"
+                ? hintsFor((cleaned ?? text).split("\n").slice(start - 1, end).join("\n"))
+                : null;
             inputs.push({
                 id: chunks.length > 1 ? `${rel}#${index}` : rel,
                 kind,
@@ -254,6 +280,7 @@ export async function planOntologyRun(options) {
                 chunk: chunks.length > 1 ? { index, count: chunks.length } : null,
                 ...(kind === "signal" ? { missing_refs: missingRefs(company.dir, rel) } : {}),
                 ...(readPath !== null ? { read_path: readPath } : {}),
+                ...(knownEntities !== null ? { known_entities: knownEntities } : {}),
             });
             tokens += cost;
         }
@@ -314,9 +341,13 @@ export async function planOntologyRun(options) {
             planned_tokens: tokens,
         },
         candidates_file: CANDIDATES_FILE,
-        instructions: inputs.some((input) => input.read_path)
-            ? [...CANDIDATE_INSTRUCTIONS.slice(0, 3), READ_PATH_INSTRUCTION, ...CANDIDATE_INSTRUCTIONS.slice(3)]
-            : CANDIDATE_INSTRUCTIONS,
+        instructions: [
+            ...CANDIDATE_INSTRUCTIONS.slice(0, 3),
+            ...(inputs.some((input) => input.read_path) ? [READ_PATH_INSTRUCTION] : []),
+            CANDIDATE_INSTRUCTIONS[3],
+            ...(inputs.some((input) => input.known_entities) ? ENTITY_HINTS_INSTRUCTIONS : []),
+            ...CANDIDATE_INSTRUCTIONS.slice(4),
+        ],
     };
     fs.mkdirSync(runDir, { recursive: true });
     const planPath = path.join(runDir, PLAN_FILE);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.228.4",
+  "version": "5.229.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {