@indigoai-us/hq-cli 5.119.13 → 5.119.15

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [5.119.15] — 2026-09-18
+
+### Fixed
+
+- `hq people resolve <name>` now reports ambiguity when the name matches more
+  than one person instead of selecting the first match.
+
 ## [5.119.13] — 2026-09-18
 
 ### Added
@@ -11,6 +18,16 @@
   out it says to run `/update-hq`; if the lookup cannot reach the network it
   says so instead of going quiet. `hq version --json` prints the same payload.
 
+### Fixed
+
+- `hq core rebuild-index company-knowledge` no longer silently replaces a
+  hand-written company knowledge INDEX. If the file is not the last generated
+  output, the command refuses, prints a short diff, and asks for `--accept`.
+  `<!-- hq:keep -->` opts the whole file out; `<!-- hq:keep -->` … `<!-- /hq:keep -->`
+  fences are kept while the table regenerates. Subdirectory README headings
+  are projected into the description column so the generated index is usable
+  without hand edits.
+
 ## [5.119.12] — 2026-09-18
 
 ### Fixed

package/assets/scaffold/core/scripts/rebuild-company-knowledge-index.sh

@@ -8,7 +8,7 @@
 #   - .md files → first `#` heading (stripped)
 #   - .yaml files → `description:` field if present
 #   - .json files → `description` field if present
-#   - directories → "{N} item(s)"
+#   - directories → README.md `#` heading plus "{N} item(s)", or "{N} item(s)"
 #
 # Most company knowledge dirs are embedded git repos (160000 gitlinks). The
 # generated INDEX.md lives inside the inner repo; HQ git won't track its
@@ -42,7 +42,15 @@ describe_item() {
   if [[ -d "$path" ]]; then
     local n
     n=$(find "$path" -mindepth 1 -maxdepth 1 ! -name '.*' 2>/dev/null | wc -l | tr -d ' ')
-    echo "${n} item(s)"
+    local h=""
+    if [[ -f "$path/README.md" ]]; then
+      h=$(awk '/^# / { sub(/^# +/, ""); print; exit }' "$path/README.md" 2>/dev/null || true)
+    fi
+    if [[ -n "$h" ]]; then
+      echo "${h} (${n} item(s))"
+    else
+      echo "${n} item(s)"
+    fi
     return
   fi
   case "$name" in
@@ -70,6 +78,26 @@ describe_item() {
   esac
 }
 
+sha256_file() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$1" | awk '{print $1}'
+  else
+    shasum -a 256 "$1" | awk '{print $1}'
+  fi
+}
+
+stamp_generated() {
+  local tmp="$1"
+  local out="$2"
+  local norm
+  norm=$(mktemp)
+  sed 's/^> Auto-generated. Updated: [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]$/> Auto-generated. Updated: <date>/' "$tmp" > "$norm"
+  local hash
+  hash=$(sha256_file "$norm")
+  rm -f "$norm"
+  awk -v h="$hash" '{print} /^> Auto-generated. Updated: / {print "<!-- hq-generated-sha256: " h " -->"}' "$tmp" > "$out"
+}
+
 write_knowledge_index() {
   local co="$1"
   local kdir="companies/${co}/knowledge"
@@ -77,6 +105,8 @@ write_knowledge_index() {
   local out="${kdir}/INDEX.md"
   local title
   title="$(titleize "$co") Knowledge"
+  local tmp
+  tmp=$(mktemp)
 
   {
     echo "# ${title}"
@@ -108,7 +138,10 @@ write_knowledge_index() {
         find -L "$kdir" -mindepth 1 -maxdepth 1 -type f 2>/dev/null | sort
       }
     )
-  } > "$out"
+  } > "$tmp"
+
+  stamp_generated "$tmp" "$out"
+  rm -f "$tmp"
 
   echo "rebuild-company-knowledge-index: wrote ${out}" >&2
 }

package/dist/commands/core.js

@@ -408,7 +408,19 @@ export function registerCoreCommands(program) {
         const scope = core.opts();
         const hqRoot = resolveLiveRoot({ hqRoot: scope.hqRoot });
         const operands = cmd.args.length > 0 ? cmd.args : args;
-        renderIndexTarget(entry.renderer, { root: hqRoot, log: (message) => process.stderr.write(`${message}\n`) }, operands.slice(1));
+        const passthrough = operands.slice(1);
+        const force = passthrough.includes("--accept");
+        const rendererArgs = passthrough.filter((arg) => arg !== "--accept");
+        const refused = [];
+        renderIndexTarget(entry.renderer, {
+            root: hqRoot,
+            log: (message) => process.stderr.write(`${message}\n`),
+            force,
+            refused,
+        }, rendererArgs);
+        if (refused.length > 0) {
+            throw expectedUserError(`rebuild-index: refused to overwrite ${refused.length} hand-edited INDEX.md file(s). Re-run with --accept to overwrite.`);
+        }
     });
     for (const entry of SCAFFOLD_COMMANDS) {
         core

package/dist/lib/index-render/company-knowledge.js

@@ -1,11 +1,13 @@
-import { basename, date, immediateEntries, isHidden, log, readJson, readText, sanitize, titleize, truncate, write } from "./shared.js";
+import * as fs from "fs";
+import { at, basename, date, extractKeepFences, generatedFingerprint, generatedStamp, hasUnclosedKeepMarker, heading, immediateEntries, isHidden, log, looksAutoGenerated, readJson, readText, sanitize, stampGenerated, titleize, truncate, write, } from "./shared.js";
 function describe(item) {
     const name = basename(item);
-    // `find -L` follows a symlink only for its direct target. fs.statSync mirrors that.
     try {
-        if ((awaitStat(item)).isDirectory()) {
-            const fs = requireFs();
-            return `${fs.readdirSync(item).filter((entry) => !entry.startsWith(".")).length} item(s)`;
+        if (fs.statSync(item).isDirectory()) {
+            const entries = fs.readdirSync(item).filter((entry) => !entry.startsWith("."));
+            const n = entries.length;
+            const summary = heading(`${item}/README.md`);
+            return summary ? `${summary} (${n} item(s))` : `${n} item(s)`;
         }
     }
     catch {
@@ -23,13 +25,55 @@ function describe(item) {
     }
     return name;
 }
-// Avoid a heavier tree abstraction here: the source script's `find -L` is
-// specifically about knowledge gitlinks, so stat is intentionally local.
-function requireFs() { return fsModule; }
-import * as fsModule from "fs";
-function awaitStat(file) { return fsModule.statSync(file); }
+function briefDiff(existing, next) {
+    const oldLines = existing.split("\n");
+    const newLines = next.split("\n");
+    const lines = ["--- existing", "+++ generated"];
+    const limit = Math.max(oldLines.length, newLines.length);
+    let shown = 0;
+    for (let i = 0; i < limit && shown < 20; i += 1) {
+        const a = oldLines[i];
+        const b = newLines[i];
+        if (a === b)
+            continue;
+        if (a !== undefined)
+            lines.push(`- ${a}`);
+        if (b !== undefined)
+            lines.push(`+ ${b}`);
+        shown += 1;
+    }
+    if (shown === 20)
+        lines.push("…");
+    return lines.join("\n");
+}
+function composeIndex(raw, existing) {
+    const stamped = stampGenerated(raw);
+    const fences = existing ? extractKeepFences(existing) : "";
+    if (!fences)
+        return stamped;
+    return `${stamped.replace(/\n+$/, "\n")}\n${fences}\n`;
+}
+function shouldOverwrite(context, existing, next) {
+    if (!existing)
+        return "write";
+    if (context.force)
+        return "write";
+    if (hasUnclosedKeepMarker(existing))
+        return "skip";
+    const stored = generatedStamp(existing);
+    if (stored && stored === generatedFingerprint(existing))
+        return "write";
+    if (stored)
+        return "refuse";
+    if (looksAutoGenerated(existing))
+        return "write";
+    if (generatedFingerprint(existing) === generatedFingerprint(next))
+        return "write";
+    return "refuse";
+}
 export function renderCompanyKnowledge(context) {
     const written = [];
+    let refused = 0;
     for (const companyDir of immediateEntries(context.root, "companies", "dir")) {
         const company = basename(companyDir);
         if (company.startsWith("_") || isHidden(company))
@@ -37,24 +81,24 @@ export function renderCompanyKnowledge(context) {
         const relative = `companies/${company}/knowledge`;
         const knowledge = `${companyDir}/knowledge`;
         try {
-            if (!fsModule.statSync(knowledge).isDirectory())
+            if (!fs.statSync(knowledge).isDirectory())
                 continue;
         }
         catch {
             continue;
         }
-        const entries = fsModule.readdirSync(knowledge).flatMap((name) => {
+        const entries = fs.readdirSync(knowledge).flatMap((name) => {
             const item = `${knowledge}/${name}`;
             try {
-                return fsModule.statSync(item).isDirectory() ? [item] : [];
+                return fs.statSync(item).isDirectory() ? [item] : [];
             }
             catch {
                 return [];
             }
-        }).sort().concat(fsModule.readdirSync(knowledge).flatMap((name) => {
+        }).sort().concat(fs.readdirSync(knowledge).flatMap((name) => {
             const item = `${knowledge}/${name}`;
             try {
-                return fsModule.statSync(item).isFile() ? [item] : [];
+                return fs.statSync(item).isFile() ? [item] : [];
             }
             catch {
                 return [];
@@ -68,18 +112,37 @@ export function renderCompanyKnowledge(context) {
             const value = truncate(sanitize(describe(item)), 100) || "—";
             let directory = false;
             try {
-                directory = fsModule.statSync(item).isDirectory();
+                directory = fs.statSync(item).isDirectory();
             }
             catch { /* omitted */ }
             lines.push(`| \`${name}${directory ? "/" : ""}\` | ${value} |`);
         }
         lines.push("");
         const output = `${relative}/INDEX.md`;
-        write(context, output, lines.join("\n"));
+        const raw = lines.join("\n");
+        const existing = readText(at(context.root, output));
+        const next = composeIndex(raw, existing);
+        const decision = shouldOverwrite(context, existing, next);
+        if (decision === "skip") {
+            log(context, `rebuild-company-knowledge-index: skipped ${output} (<!-- hq:keep -->)`);
+            continue;
+        }
+        if (decision === "refuse") {
+            refused += 1;
+            context.refused?.push(output);
+            log(context, `rebuild-company-knowledge-index: refused ${output} (hand-written or edited; differs from last generated output)`);
+            log(context, briefDiff(existing ?? "", next));
+            log(context, "Re-run with --accept to overwrite, or add <!-- hq:keep --> to opt out.");
+            continue;
+        }
+        write(context, output, next);
         written.push(output);
         log(context, `rebuild-company-knowledge-index: wrote ${output}`);
     }
     log(context, `rebuild-company-knowledge-index: regenerated ${written.length} knowledge INDEX.md file(s)`);
+    if (refused > 0) {
+        log(context, `rebuild-company-knowledge-index: refused to overwrite ${refused} hand-edited INDEX.md file(s)`);
+    }
     return { written };
 }
 //# sourceMappingURL=company-knowledge.js.map

package/dist/lib/index-render/shared.d.ts

@@ -3,6 +3,10 @@ export type RenderContext = {
     now?: Date;
     log?: (message: string) => void;
     output?: (message: string) => void;
+    /** Overwrite hand-edited INDEX.md files (`rebuild-index … --accept`). */
+    force?: boolean;
+    /** Relative paths that were not overwritten because they differ from last generated output. */
+    refused?: string[];
 };
 export type RenderResult = {
     written: string[];
@@ -26,6 +30,14 @@ export declare function timestamp(now?: Date): string;
 /** Write via a same-directory temporary file, then atomically replace the destination. */
 export declare function atomicWrite(file: string, content: string): void;
 export declare function write(context: RenderContext, relative: string, content: string): string;
+/** Drop keep fences, the generated stamp, and the rolling date so two generated bodies can be compared. */
+export declare function generatedFingerprint(content: string): string;
+/** Insert a content stamp after the Auto-generated line. Idempotent. */
+export declare function stampGenerated(content: string): string;
+export declare function extractKeepFences(content: string): string;
+export declare function hasUnclosedKeepMarker(content: string): boolean;
+export declare function looksAutoGenerated(content: string): boolean;
+export declare function generatedStamp(content: string): string | undefined;
 export declare function log(context: RenderContext, message: string): void;
 export declare function projectStatus(root: string, project: string, prdPath: string, fallback: string): string;
 export declare function basename(file: string): string;

package/dist/lib/index-render/shared.js

@@ -1,3 +1,4 @@
+import { createHash } from "crypto";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
@@ -96,6 +97,42 @@ export function write(context, relative, content) {
     atomicWrite(at(context.root, relative), content);
     return relative;
 }
+const GENERATED_DATE_LINE = /^> Auto-generated\. Updated: \d{4}-\d{2}-\d{2}$/m;
+const GENERATED_STAMP_LINE = /^<!-- hq-generated-sha256: [a-f0-9]{64} -->\n?/m;
+function keepFencePattern() {
+    return /<!-- hq:keep -->\r?\n?[\s\S]*?<!-- \/hq:keep -->/g;
+}
+/** Drop keep fences, the generated stamp, and the rolling date so two generated bodies can be compared. */
+export function generatedFingerprint(content) {
+    const normalized = content
+        .replace(keepFencePattern(), "")
+        .replace(GENERATED_STAMP_LINE, "")
+        .replace(GENERATED_DATE_LINE, "> Auto-generated. Updated: <date>")
+        .replace(/\n+$/, "\n");
+    return createHash("sha256").update(normalized, "utf8").digest("hex");
+}
+/** Insert a content stamp after the Auto-generated line. Idempotent. */
+export function stampGenerated(content) {
+    const unstamped = content.replace(GENERATED_STAMP_LINE, "");
+    const hash = generatedFingerprint(unstamped);
+    return unstamped.replace(GENERATED_DATE_LINE, (line) => `${line}\n<!-- hq-generated-sha256: ${hash} -->`);
+}
+export function extractKeepFences(content) {
+    return (content.match(keepFencePattern()) ?? []).join("\n\n");
+}
+export function hasUnclosedKeepMarker(content) {
+    const opens = content.match(/<!-- hq:keep -->/g)?.length ?? 0;
+    if (opens === 0)
+        return false;
+    const closes = content.match(/<!-- \/hq:keep -->/g)?.length ?? 0;
+    return opens > closes;
+}
+export function looksAutoGenerated(content) {
+    return GENERATED_DATE_LINE.test(content);
+}
+export function generatedStamp(content) {
+    return content.match(/^<!-- hq-generated-sha256: ([a-f0-9]{64}) -->/m)?.[1];
+}
 export function log(context, message) { context.log?.(message); }
 export function projectStatus(root, project, prdPath, fallback) {
     const state = readJson(at(root, `workspace/orchestrator/${project}/state.json`));

package/dist/utils/people.d.ts

@@ -86,17 +86,10 @@ export type ResolveResult = {
 /**
  * Resolve a person NAME to their email, built on top of {@link searchPeople}.
  *
- * Match precedence (narrowest first) so a precise query isn't drowned out by
- * looser substring hits:
- *   1. exact name match (case-insensitive, trimmed)
- *   2. exact folder-slug match
- *   3. substring search over name/email/slug
- *
- * The first tier that yields any match decides the result:
- *   - exactly one match with an email  → `found`
- *   - exactly one match, no email      → `no_email`
- *   - more than one match              → `ambiguous` (caller disambiguates)
- *   - no match in any tier             → `not_found`
+ * Resolution is deliberately stricter than a convenience ranking. Every
+ * case-insensitive name, email, or slug substring match is a candidate; an
+ * exact name never silently selects one person when the query also names
+ * other people. The caller must disambiguate any multi-person result.
  */
 export declare function resolveNameToEmail(people: PersonRecord[], name: string): ResolveResult;
 //# sourceMappingURL=people.d.ts.map

package/dist/utils/people.js

@@ -122,31 +122,16 @@ export function searchPeople(people, keyword) {
 /**
  * Resolve a person NAME to their email, built on top of {@link searchPeople}.
  *
- * Match precedence (narrowest first) so a precise query isn't drowned out by
- * looser substring hits:
- *   1. exact name match (case-insensitive, trimmed)
- *   2. exact folder-slug match
- *   3. substring search over name/email/slug
- *
- * The first tier that yields any match decides the result:
- *   - exactly one match with an email  → `found`
- *   - exactly one match, no email      → `no_email`
- *   - more than one match              → `ambiguous` (caller disambiguates)
- *   - no match in any tier             → `not_found`
+ * Resolution is deliberately stricter than a convenience ranking. Every
+ * case-insensitive name, email, or slug substring match is a candidate; an
+ * exact name never silently selects one person when the query also names
+ * other people. The caller must disambiguate any multi-person result.
  */
 export function resolveNameToEmail(people, name) {
     const query = name.trim();
     if (!query)
         return { status: "not_found" };
-    const lowered = query.toLowerCase();
-    const exactName = people.filter((p) => p.name.toLowerCase() === lowered);
-    const exactSlug = people.filter((p) => p.slug.toLowerCase() === lowered);
-    const substring = searchPeople(people, query);
-    const matches = exactName.length > 0
-        ? exactName
-        : exactSlug.length > 0
-            ? exactSlug
-            : substring;
+    const matches = searchPeople(people, query);
     if (matches.length === 0)
         return { status: "not_found" };
     if (matches.length > 1)

package/package.json

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