@indigoai-us/hq-cli 5.238.0 → 5.239.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [5.239.0] — 2026-09-27
+
+### Added
+
+- `hq core checkpoint` can skip a knowledge link to a concept entity whose
+  name is also the name of an entity of another type, such as a concept
+  `hq-secrets` beside a project `HQ Secrets`. The report lists the skipped
+  link as rejected with reason `ambiguous_type`. Signal and session inputs,
+  other links and new entities are unchanged. Behind the hq-flags flag
+  `checkpoint.ontology.skip-ambiguous-concept-links`, off by default.
+
 ## [5.238.0] — 2026-09-27
 
 ### Added: Lane orphan reporting

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

@@ -262,6 +262,25 @@ export function applyOntologyRun(options) {
     }
     report.candidates = rawCandidates.length;
     const index = buildEntityIndex(company.dir);
+    // checkpoint.ontology.skip-ambiguous-concept-links: canonical names held by entities of more than one type.
+    // Names compare in the non-organization form for every type (lowercase, keeps + and #, no squashing),
+    // so "C++" and "C", or "AB" and "A B", stay distinct.
+    const crossTypeKey = (name) => normalizeEntityName(name, "concept");
+    const crossTypeNames = new Set();
+    if (plan.skip_ambiguous_concept_links === true) {
+        const typesByName = new Map();
+        for (const entity of index.byRel.values()) {
+            const name = crossTypeKey(entity.canonical_name);
+            if (name === "")
+                continue;
+            const types = typesByName.get(name) ?? new Set();
+            types.add(entity.type);
+            typesByName.set(name, types);
+        }
+        for (const [name, types] of typesByName)
+            if (types.size > 1)
+                crossTypeNames.add(name);
+    }
     const inputs = liveInputs(options.hqRoot, company, plan);
     const blocked = new Set();
     const updates = new Map();
@@ -313,8 +332,14 @@ export function applyOntologyRun(options) {
             continue;
         }
         if (resolved.tier === 1 || resolved.tier === 2) {
-            report.matched += 1;
             const linked = index.byRel.get(resolved.target);
+            if (input.kind === "knowledge" &&
+                linked.type === "concept" &&
+                crossTypeNames.has(crossTypeKey(linked.canonical_name))) {
+                note(report.rejected, "ambiguous_type");
+                continue;
+            }
+            report.matched += 1;
             report.links.push({ input: candidate.input, action: "link", type: linked.type, canonical_name: linked.canonical_name, path: resolved.target });
             if (resolved.tier === 1 && resolved.duplicates.length > 0) {
                 report.suspect_duplicates.push({ name: canonical, type: candidate.type, paths: [resolved.target, ...resolved.duplicates] });

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

@@ -68,6 +68,16 @@ export declare const NO_LINK_ALIASES_FLAG = "checkpoint.ontology.no-link-aliases
  * the model cannot see that `John Smith` already exists.
  */
 export declare const FIRST_NAME_PEOPLE_FLAG = "checkpoint.ontology.first-name-people";
+/**
+ * A knowledge input does not link to a concept entity whose canonical name is
+ * also the canonical name of an entity of another type (`concept/hq-secrets`
+ * beside `project/hq-secrets`). The plan carries
+ * `skip_ambiguous_concept_links: true`, and apply rejects the link as
+ * `ambiguous_type`. CO-46: 34 of the 73 false positives on the knowledge
+ * fixtures were such concept links; skipping them raised precision from 0.733
+ * to 0.803 and cost recall 0.023 on a replay of six runs.
+ */
+export declare const SKIP_AMBIGUOUS_CONCEPT_LINKS_FLAG = "checkpoint.ontology.skip-ambiguous-concept-links";
 export declare const PLAN_FILE = "ontology-plan.json";
 export declare const CANDIDATES_FILE = "ontology-candidates.json";
 export declare const REPORT_FILE = "ontology-report.json";
@@ -138,6 +148,8 @@ export interface OntologyPlan {
     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;
+    /** Set by checkpoint.ontology.skip-ambiguous-concept-links: apply rejects a knowledge link to a concept whose name another type also holds. */
+    skip_ambiguous_concept_links?: true;
     inputs: PlanInput[];
     /** The session's summary, decisions and learnings, for the `session` input. */
     session_text: string | null;

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

@@ -72,6 +72,16 @@ export const NO_LINK_ALIASES_FLAG = "checkpoint.ontology.no-link-aliases";
  * the model cannot see that `John Smith` already exists.
  */
 export const FIRST_NAME_PEOPLE_FLAG = "checkpoint.ontology.first-name-people";
+/**
+ * A knowledge input does not link to a concept entity whose canonical name is
+ * also the canonical name of an entity of another type (`concept/hq-secrets`
+ * beside `project/hq-secrets`). The plan carries
+ * `skip_ambiguous_concept_links: true`, and apply rejects the link as
+ * `ambiguous_type`. CO-46: 34 of the 73 false positives on the knowledge
+ * fixtures were such concept links; skipping them raised precision from 0.733
+ * to 0.803 and cost recall 0.023 on a replay of six runs.
+ */
+export const SKIP_AMBIGUOUS_CONCEPT_LINKS_FLAG = "checkpoint.ontology.skip-ambiguous-concept-links";
 export const PLAN_FILE = "ontology-plan.json";
 export const CANDIDATES_FILE = "ontology-candidates.json";
 export const REPORT_FILE = "ontology-report.json";
@@ -254,6 +264,7 @@ export async function planOntologyRun(options) {
     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 skipAmbiguousConceptLinks = await options.readFlag(SKIP_AMBIGUOUS_CONCEPT_LINKS_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.
@@ -368,6 +379,7 @@ export async function planOntologyRun(options) {
         ...(multiWriter ? { multi_writer: multiWriter } : {}),
         ...(noLinkAliases ? { link_aliases: false } : {}),
         ...(firstNamePeople ? { first_name_people: true } : {}),
+        ...(skipAmbiguousConceptLinks ? { skip_ambiguous_concept_links: true } : {}),
         inputs,
         session_text: sessionText,
         pending_after_run: remaining,

package/package.json

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