@indigoai-us/hq-cli 5.230.2 → 5.231.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [5.231.0] — 2026-09-27
+
+### Added
+
+- Behind the off-by-default `checkpoint.ontology.first-name-people` flag, the
+  checkpoint ontology instructions tell the model to name a person by their
+  first name when neither the input nor the company's entities give more,
+  instead of leaving them out. With the flag on, apply also defers a one-word
+  person whose word starts an existing person's fuller name or alias (`John`
+  when `John Smith` exists), since the model cannot see the entity tree. With
+  the flag off the instructions and apply are unchanged.
+
 ## [5.230.2] — 2026-09-27
 
 ### Fixed

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

@@ -128,6 +128,13 @@ export declare function resolveCandidate(index: EntityIndex, type: string, canon
  * (`Chaudhry Hassaan Saleem` and `Hassaan Saleem`).
  */
 export declare function overlappingEntities(index: EntityIndex, type: string, canonical: string, aliases: string[]): string[];
+/**
+ * Existing people a one-word person candidate may be: the word is the first
+ * word of their name or of one of their aliases, and that name has two words
+ * or more (`John` and `John Smith`). The model never sees the entity tree, so
+ * it cannot tell a first name that the company already holds in full.
+ */
+export declare function firstNameOverlap(index: EntityIndex, canonical: string): string[];
 export declare function applyOntologyRun(options: ApplyOptions): ApplyReport;
 export {};
 //# sourceMappingURL=apply.d.ts.map

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

@@ -113,6 +113,30 @@ export function overlappingEntities(index, type, canonical, aliases) {
     }
     return [...paths].sort();
 }
+/**
+ * Existing people a one-word person candidate may be: the word is the first
+ * word of their name or of one of their aliases, and that name has two words
+ * or more (`John` and `John Smith`). The model never sees the entity tree, so
+ * it cannot tell a first name that the company already holds in full.
+ */
+export function firstNameOverlap(index, canonical) {
+    const words = normalizeEntityName(canonical, "person").split(" ");
+    if (words.length !== 1 || !words[0])
+        return [];
+    const prefix = entityKey("person", "");
+    const paths = new Set();
+    for (const map of [index.canonical, index.alias]) {
+        for (const [name, rels] of map) {
+            if (!name.startsWith(prefix))
+                continue;
+            const other = name.slice(prefix.length).split(" ");
+            if (other.length >= 2 && other[0] === words[0])
+                for (const rel of rels)
+                    paths.add(rel);
+        }
+    }
+    return [...paths].sort();
+}
 function readJson(file) {
     return JSON.parse(fs.readFileSync(file, "utf8"));
 }
@@ -335,6 +359,12 @@ export function applyOntologyRun(options) {
             report.suspect_duplicates.push({ name: canonical, type: candidate.type, paths: overlap });
             continue;
         }
+        const firstName = plan.first_name_people === true && candidate.type === "person" ? firstNameOverlap(index, canonical) : [];
+        if (firstName.length > 0) {
+            note(report.deferred, "suspect_duplicate");
+            report.suspect_duplicates.push({ name: canonical, type: candidate.type, paths: firstName });
+            continue;
+        }
         // Tier 5: create.
         if (candidate.confidence < MIN_CREATE_CONFIDENCE) {
             note(report.rejected, "low_confidence");

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

@@ -48,6 +48,17 @@ export declare const ENTITY_HINTS_FLAG = "checkpoint.ontology.entity-hints";
  * hinted runs).
  */
 export declare const NO_LINK_ALIASES_FLAG = "checkpoint.ontology.no-link-aliases";
+/**
+ * A person the input and the company's entities give only a first name for is
+ * named by that first name instead of being left out. CO-44: on the CO-41
+ * grok-4.6 runs the model read "not a first name alone" as "skip them", and
+ * dropped people such as Amir and Sebastian, whose own entities carry only a
+ * first name. People were 24 of the 138 missed gold entities over three runs.
+ * The plan carries `first_name_people: true`, and apply then defers a one-word
+ * person whose word starts an existing person's fuller name or alias, since
+ * the model cannot see that `John Smith` already exists.
+ */
+export declare const FIRST_NAME_PEOPLE_FLAG = "checkpoint.ontology.first-name-people";
 export declare const PLAN_FILE = "ontology-plan.json";
 export declare const CANDIDATES_FILE = "ontology-candidates.json";
 export declare const REPORT_FILE = "ontology-report.json";
@@ -116,6 +127,8 @@ export interface OntologyPlan {
     multi_writer?: MultiWriterStart;
     /** Present, as false, only when `checkpoint.ontology.no-link-aliases` was on for this plan. */
     link_aliases?: false;
+    /** Set by checkpoint.ontology.first-name-people: apply defers a one-word person who may be an existing fuller name. */
+    first_name_people?: true;
     inputs: PlanInput[];
     /** The session's summary, decisions and learnings, for the `session` input. */
     session_text: string | null;
@@ -160,6 +173,8 @@ export type PlanOutcome = {
 };
 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 const PERSON_NAME_INSTRUCTION = "Name a person by the full name the input or the company's entities give, not a first name alone.";
+export declare const FIRST_NAME_PEOPLE_INSTRUCTION = "Name a person by the full name the input or the company's entities give. When neither gives more than a first name, name the person by that first name; do not leave them out.";
 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

@@ -52,6 +52,17 @@ export const ENTITY_HINTS_FLAG = "checkpoint.ontology.entity-hints";
  * hinted runs).
  */
 export const NO_LINK_ALIASES_FLAG = "checkpoint.ontology.no-link-aliases";
+/**
+ * A person the input and the company's entities give only a first name for is
+ * named by that first name instead of being left out. CO-44: on the CO-41
+ * grok-4.6 runs the model read "not a first name alone" as "skip them", and
+ * dropped people such as Amir and Sebastian, whose own entities carry only a
+ * first name. People were 24 of the 138 missed gold entities over three runs.
+ * The plan carries `first_name_people: true`, and apply then defers a one-word
+ * person whose word starts an existing person's fuller name or alias, since
+ * the model cannot see that `John Smith` already exists.
+ */
+export const FIRST_NAME_PEOPLE_FLAG = "checkpoint.ontology.first-name-people";
 export const PLAN_FILE = "ontology-plan.json";
 export const CANDIDATES_FILE = "ontology-candidates.json";
 export const REPORT_FILE = "ontology-report.json";
@@ -68,11 +79,13 @@ 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.",
 ];
+export const PERSON_NAME_INSTRUCTION = "Name a person by the full name the input or the company's entities give, not a first name alone.";
+export const FIRST_NAME_PEOPLE_INSTRUCTION = "Name a person by the full name the input or the company's entities give. When neither gives more than a first name, name the person by that first name; do not leave them out.";
 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.",
     "Read only the files and line ranges this plan lists. For a signal, read its body and name the entities in missing_refs if the signal supports them.",
-    "Name the specific people, projects, products, companies and named concepts that the input says something about. That includes the company that owns this knowledge and its own products when the input describes them. Name a third-party tool, vendor or service only when a section of the input is about it; skip ones that appear in a list, a stack summary or a passing mention. Skip generic words, file names and headings. Name a person by the full name the input or the company's entities give, not a first name alone.",
+    "Name the specific people, projects, products, companies and named concepts that the input says something about. That includes the company that owns this knowledge and its own products when the input describes them. Name a third-party tool, vendor or service only when a section of the input is about it; skip ones that appear in a list, a stack summary or a passing mention. Skip generic words, file names and headings.",
     "For the session input (its text is session_text in this plan), name only entities that already exist in the company and that the session did work on. Session candidates are recorded as links, never created.",
     "Do not create, edit, move or delete anything under ontology/, signals/ or sources/ yourself.",
 ];
@@ -229,6 +242,7 @@ export async function planOntologyRun(options) {
     const multiWriterOn = await options.readFlag(MULTI_WRITER_FLAG, company);
     const hintsOn = await options.readFlag(ENTITY_HINTS_FLAG, company);
     const noLinkAliases = await options.readFlag(NO_LINK_ALIASES_FLAG, company);
+    const firstNamePeople = await options.readFlag(FIRST_NAME_PEOPLE_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.
@@ -342,6 +356,7 @@ export async function planOntologyRun(options) {
             : {}),
         ...(multiWriter ? { multi_writer: multiWriter } : {}),
         ...(noLinkAliases ? { link_aliases: false } : {}),
+        ...(firstNamePeople ? { first_name_people: true } : {}),
         inputs,
         session_text: sessionText,
         pending_after_run: remaining,
@@ -355,7 +370,7 @@ export async function planOntologyRun(options) {
         instructions: [
             ...CANDIDATE_INSTRUCTIONS.slice(0, 3),
             ...(inputs.some((input) => input.read_path) ? [READ_PATH_INSTRUCTION] : []),
-            CANDIDATE_INSTRUCTIONS[3],
+            `${CANDIDATE_INSTRUCTIONS[3]} ${firstNamePeople ? FIRST_NAME_PEOPLE_INSTRUCTION : PERSON_NAME_INSTRUCTION}`,
             ...(inputs.some((input) => input.known_entities) ? ENTITY_HINTS_INSTRUCTIONS : []),
             ...CANDIDATE_INSTRUCTIONS.slice(4),
         ],

package/package.json

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