@hone-ai/cli 1.38.0 → 1.39.0

package/lib/bundle-paths.js

@@ -259,6 +259,22 @@ function extractPathRefs(text) {
 /** Backticked spans in a story, longest first — the longest is the most specific anchor. */
 const BACKTICKED_RE = /`([^`\n]{3,200})`/g;
 
+/**
+ * The terms a story quotes that could locate code, longest first — one copy of the filter.
+ * HC-GF-206-followup-3: three readers now ask this question (`anchorLineForStory`,
+ * `anchorSitesForStory` and `unanchoredTerms`), and two hand-typed copies of it is how one
+ * reader ends up judging a different set of terms than the others. Path-shaped spans and the
+ * extensionless filenames are dropped: a story always quotes the file's own path.
+ */
+function storyTermsOf(storyText) {
+  return [...String(storyText || '').matchAll(BACKTICKED_RE)]
+    .map((m) => m[1].trim())
+    .filter((c) => c.length >= 3
+      && !new RegExp(`^[\\w.\\-/]+\\.(?:${FILE_EXT})$`).test(c)
+      && !new RegExp(`^(?:${EXTENSIONLESS})$`).test(c))
+    .sort((a, b) => b.length - a.length);
+}
+
 /**
  * The line of the first thing the STORY quoted that actually occurs in this file — HC-GF-188.
  *
@@ -286,12 +302,7 @@ function anchorLineForStory(content, storyText) {
   const story = String(storyText || '');
   if (!text || !story) return null;
 
-  const candidates = [...story.matchAll(BACKTICKED_RE)]
-    .map((m) => m[1].trim())
-    .filter((c) => c.length >= 3
-      && !new RegExp(`^[\\w.\\-/]+\\.(?:${FILE_EXT})$`).test(c)
-      && !new RegExp(`^(?:${EXTENSIONLESS})$`).test(c))
-    .sort((a, b) => b.length - a.length);
+  const candidates = storyTermsOf(story);
 
   for (const anchor of candidates) {
     const at = definitionIndexOf(text, anchor);
@@ -314,6 +325,17 @@ function anchorLineForStory(content, storyText) {
  *
  * The fallback is the OLD behaviour on purpose: a term that is only ever mentioned still
  * gets the operator a window near it, which beats none.
+ *
+ * HC-GF-203-followup-1: a MENTION is the term standing whole, not the term's letters inside a
+ * longer identifier. The fallback was a bare `indexOf`, so `info` landed in `information`,
+ * `auth` in `authorize` and `Promise.all` in `Promise.allSettled` — and each such offset became
+ * a site in `anchorSitesForStory`, spending one of its 6 slots and a window on text that does
+ * not contain the term. Measured 2026-10-07 at the production cap over every roadmap row
+ * against cli/hone-cli.js and server/src/services/orchestrator.js: 187 of 6,210 sites, in 161
+ * of 1,224 windowed excerpts, 106 of them at the 6-site limit, where the wasted slot cost
+ * another term its window. A term that never stands whole is now -1, exactly like a term
+ * the file lacks: HC-GF-188's rule, "could not anchor" stays distinguishable from "anchored
+ * here", applies to a window around `information` as much as to one around line 1.
  */
 /**
  * HC-GF-206-followup-1: a collapsed hit is a real site — the collapse only means it EXPECTS to
@@ -334,12 +356,7 @@ function anchorSitesForStory(content, storyText, max = 6) {
   const text = String(content || '');
   const story = String(storyText || '');
   if (!text || !story) return { sites: [], collapsed: [] };
-  const candidates = [...story.matchAll(BACKTICKED_RE)]
-    .map((m) => m[1].trim())
-    .filter((c) => c.length >= 3
-      && !new RegExp(`^[\\w.\\-/]+\\.(?:${FILE_EXT})$`).test(c)
-      && !new RegExp(`^(?:${EXTENSIONLESS})$`).test(c))
-    .sort((a, b) => b.length - a.length);
+  const candidates = storyTermsOf(story);
 
   const seenLine = new Set();
   const sites = [];
@@ -349,6 +366,11 @@ function anchorSitesForStory(content, storyText, max = 6) {
     if (def === -1) continue;
     const t = anchor.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     const offsets = [def];
+    // The STRICT form on purpose, unlike `wholeTerm`. HC-GF-206-followup-5 measured `wholeTerm` here:
+    // a term with a punctuation edge (`/prompts/`, `.json`) then takes every occurrence as a site and
+    // crowds the rest out of the 6 — 74 of 1,218 excerpts changed, 9 terms gained a window, 28 lost one.
+    // With the strict form such a term gets its first whole occurrence (`def`), and the marker names
+    // it when no window shows it.
     for (const m of text.matchAll(new RegExp(`(?<![\\w$])${t}(?![\\w$])`, 'g'))) offsets.push(m.index);
     for (const off of offsets) {
       const line = text.slice(0, off).split('\n').length;
@@ -364,8 +386,29 @@ function anchorSitesForStory(content, storyText, max = 6) {
   return { sites, collapsed };
 }
 
+/**
+ * A term standing WHOLE — HC-GF-203-followup-1: no identifier character touches an edge of the term
+ * that is itself an identifier character. `checkBudget(` stands whole in `checkBudget(orgId)` — its
+ * own `(` is the boundary on that side — and `info` does not in `information`.
+ *
+ * HC-GF-206-followup-5: one copy, read by `definitionIndexOf` and `unanchoredTerms`. With the strict
+ * `(?<![\w$])…(?![\w$])` in `unanchoredTerms`, the two disagreed on every term with a punctuation
+ * edge: `definitionIndexOf` found `checkBudget(` and the marker said nothing, because the strict
+ * form calls it absent. `anchorSitesForStory`'s scan for further hits deliberately keeps the strict
+ * form; see there.
+ *
+ * @returns {{t: string, before: string, after: string}} the escaped term and the two lookarounds
+ */
+function wholeTerm(term) {
+  return {
+    t: term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'),
+    before: /^[\w$]/.test(term) ? '(?<![\\w$])' : '',
+    after: /[\w$]$/.test(term) ? '(?![\\w$])' : '',
+  };
+}
+
 function definitionIndexOf(text, term) {
-  const t = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const { t, before, after } = wholeTerm(term);
   // Ordered by how strongly each shape asserts "this is where it lives".
   const DEFINITION_FORMS = [
     `\\.command\\(\\s*['"\`]${t}\\b`,           // CLI command registration
@@ -373,13 +416,98 @@ function definitionIndexOf(text, term) {
     `class\\s+${t}\\b`,                           // class declaration
     `(?:const|let|var)\\s+${t}\\s*=`,             // binding
     `exports\\.${t}\\s*=`,                        // named export
-    `${t}\\s*[:=]\\s*(?:async\\s*)?(?:function|\\()`, // property holding a function
+    // The one form with nothing in front of the term: without `before`, `name` is "defined"
+    // by `basename = (` and `run` by `rerun: function`.
+    `${before}${t}\\s*[:=]\\s*(?:async\\s*)?(?:function|\\()`, // property holding a function
   ];
   for (const form of DEFINITION_FORMS) {
     const m = new RegExp(form).exec(text);
     if (m) return m.index;
   }
-  return text.indexOf(term);
+  const mention = new RegExp(`${before}${t}${after}`).exec(text);
+  return mention ? mention.index : -1;
+}
+
+/**
+ * The story's terms that occur in this file but in NONE of the windows bundled — HC-GF-206-followup-3.
+ *
+ * `anchorSitesForStory` stops at 6 sites, and terms are tried longest first, so every hit after
+ * the sixth site — including every hit of a shorter term — is neither a site nor a collapsed hit.
+ * A window can also be dropped for budget with its term in it. The notice counted neither, and
+ * nothing told the agent: a term absent from the excerpt reads exactly like a term absent from the
+ * FILE. Measured 2026-10-05 at the production cap over every roadmap row against cli/hone-cli.js and
+ * server/src/services/orchestrator.js: 425 of 1,198 windowed excerpts left out 901 whole-word terms,
+ * none named.
+ *
+ * Judged against the FINAL windows, not the site list, so it holds whatever dropped the term — the
+ * site limit, the budget, a collapse — and needs no knowledge of how the layout was chosen.
+ *
+ * A term counts as occurring only where it stands whole (`wholeTerm`); reporting `info` inside
+ * `information` as "`info` is at line N" would send an agent to a line that does not contain it.
+ * `definitionIndexOf` applies the same rule since HC-GF-203-followup-1 (its fallback was a bare
+ * `indexOf`); the check here stays, because this is what names a term to the agent.
+ *
+ * HC-GF-206-followup-5: this read the strict form, which calls every term with a punctuation edge
+ * absent unless that edge happens to sit next to a non-identifier character. Measured 2026-10-07 at
+ * the production cap over every roadmap row against cli/hone-cli.js and orchestrator.js: 44 such
+ * terms in 40 of 1,218 windowed excerpts were in the file, in no window, and not named; and 42
+ * were named as outside every window while a window showed them (`.md` in `README.md`). After: 0 and
+ * 0, with every window byte-identical and no term pushed out of the marker or the notice.
+ *
+ * @param {string} content full file contents
+ * @param {string} storyText
+ * @param {Array<[number, number]>} ranges the bundled windows' [startLine, endLine], 1-indexed
+ * @returns {Array<{term: string, line: number}>} story order (longest first); `line` is the
+ *   definition's line when the definition is a whole-word occurrence, else the first mention
+ */
+function unanchoredTerms(content, storyText, ranges) {
+  const text = String(content || '');
+  if (!text) return [];
+  const starts = [0];
+  for (let i = text.indexOf('\n'); i !== -1; i = text.indexOf('\n', i + 1)) starts.push(i + 1);
+  const lineOf = (off) => {
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (starts[mid] <= off) lo = mid; else hi = mid - 1; }
+    return lo + 1;
+  };
+  const covered = (l) => ranges.some(([a, b]) => a <= l && l <= b);
+  const out = [];
+  for (const term of new Set(storyTermsOf(storyText))) {
+    const def = definitionIndexOf(text, term);
+    if (def === -1) continue;
+    const { t, before, after } = wholeTerm(term);
+    const mentions = [...text.matchAll(new RegExp(`${before}${t}${after}`, 'g'))].map((m) => lineOf(m.index));
+    if (!mentions.length) continue;
+    // Covered only by a whole occurrence.
+    if (mentions.some(covered)) continue;
+    const defLine = lineOf(def);
+    out.push({ term, line: mentions.includes(defLine) ? defLine : mentions[0] });
+  }
+  return out;
+}
+
+/**
+ * The excerpt's first line when story terms were left out — HC-GF-206-followup-3. It goes FIRST
+ * because step_0's premise check keeps only the first 2,000 chars of each file
+ * (`STEP_0_CODE_CAP_PER_FILE`, server/src/services/orchestrator.js), and "this symbol already
+ * exists" is exactly what that step looks for. It must fit the room the windows left under the cap:
+ * terms are listed longest first and the tail is folded into "+N more"; with no room for even that,
+ * it is omitted and only the operator's notice carries the list.
+ */
+function unanchoredMarker(unanchored, room) {
+  if (!unanchored.length) return '';
+  const head = `# [HC-GF-206-followup-3: ${unanchored.length} term(s) the story names occur in this file `
+    + 'OUTSIDE every excerpt below: ';
+  const tail = '. They exist; you were not shown them, so do not conclude they are absent.]\n';
+  const items = unanchored.map(({ term, line }) => `\`${term}\` (line ${line})`);
+  for (let k = items.length; k >= 0; k -= 1) {
+    const rest = items.length - k;
+    const list = items.slice(0, k).join(', ') + (rest ? `${k ? ', ' : ''}+${rest} more` : '');
+    const marker = head + list + tail;
+    if (marker.length <= room) return marker;
+  }
+  return '';
 }
 
 /**
@@ -401,7 +529,9 @@ function definitionIndexOf(text, term) {
  *
  * @param {{content: string, cap: number, line?: number|null, lines?: number[], storyText?: string, path?: string}} input
  * @returns {{mode: 'full'|'window'|'truncate', content: string, notice: string|null, anchor?: string,
- *   unhonoured: Array<{line: number, reason: 'past-eof'|'budget', totalLines: number}>}}
+ *   unhonoured: Array<{line: number, reason: 'past-eof'|'budget', totalLines: number}>,
+ *   unanchored: Array<{term: string, line: number}>}} — HC-GF-206-followup-3: story terms the file
+ *   has that no bundled window carries; always empty outside `window` mode
  */
 function planFileExcerpt({ content, cap, line = null, lines = null, storyText = '', path: filePath = 'file' } = {}) {
   const text = String(content || '');
@@ -415,7 +545,7 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
   const stated = requested.filter((n) => n <= totalLines);
   const unhonoured = requested.filter((n) => n > totalLines)
     .map((n) => ({ line: n, reason: 'past-eof', totalLines }));
-  if (text.length <= limit) return { mode: 'full', content: text, notice: null, unhonoured };
+  if (text.length <= limit) return { mode: 'full', content: text, notice: null, unhonoured, unanchored: [] };
 
   // An explicit line wins: the author stated it, the anchor is inferred from prose.
   const hit = stated.length ? { line: stated[0], anchor: null } : anchorLineForStory(text, storyText);
@@ -698,14 +828,30 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
         ? ` — ${unreached} near-duplicate hit(s) collapsed into a window that did not reach them`
         : '');
 
+    const body = windows.map(({ w, anchor, line: siteLine }) =>
+      header(w, anchor, siteLine) + w.excerpt + footer).join('\n');
+    // HC-GF-206-followup-3: a story term the file has and no window carries is NAMED, to the agent
+    // first and the operator second. Only the room the windows left is spent: the layout above is
+    // untouched, so what every run already bundled stays exactly what it was.
+    const unanchored = unanchoredTerms(text, storyText, windows.map(({ w }) => [w.startLine, w.endLine]));
+    const marker = unanchoredMarker(unanchored, limit - body.length);
+    const SHOWN = 8;
+    const termsNote = unanchored.length
+      ? ` — ${unanchored.length} story term(s) in the file but in no bundled window: `
+        + unanchored.slice(0, SHOWN).map(({ term, line: l }) => `\`${term}\` (line ${l})`).join(', ')
+        + (unanchored.length > SHOWN ? `, +${unanchored.length - SHOWN} more` : '')
+        + `; name them as ${filePath}:<line> to anchor them`
+        + (marker ? '' : ' (the excerpt had no room left to tell the agent)')
+      : '';
+
     return {
       mode: 'window',
       unhonoured,
+      unanchored,
       anchor: windows[0].anchor || null,
-      content: windows.map(({ w, anchor, line: siteLine }) =>
-        header(w, anchor, siteLine) + w.excerpt + footer).join('\n'),
+      content: marker + body,
       notice: `  ⚠ ${filePath} is ${text.length} chars (cap ${limit}) — bundled lines `
-        + `${ranges} of ${windows[0].w.totalLines}, ${because}${shortfall}`,
+        + `${ranges} of ${windows[0].w.totalLines}, ${because}${shortfall}${termsNote}`,
     };
   }
 
@@ -718,6 +864,7 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
   return {
     mode: 'truncate',
     unhonoured,
+    unanchored: [], // reached only when no story term occurs in the file at all
     content: text.slice(0, keep) + marker(keep),
     notice: `  ⚠ ${filePath} is ${text.length} chars (cap ${limit}) — head-truncated, ${dropped} chars `
       + `DROPPED and nothing in the story text matched inside the file, so the region you care about `
@@ -932,7 +1079,7 @@ function classifyStoryPaths(text, named) {
 module.exports = {
   BARE_FILE_RE, extractBareNames, extractBareRefs, resolveBareName, alreadyCovered, windowAroundLine,
   PATH_REF_RE, extractPathRefs, anchorLineForStory, planFileExcerpt, definitionIndexOf, anchorSitesForStory,
-  windowBetweenLines, mergeIntersectingWindows,
+  windowBetweenLines, mergeIntersectingWindows, storyTermsOf, unanchoredTerms, unanchoredMarker,
   // HC-GF-229 — classification. Pinned byte-for-byte against the server copy.
   LABEL_RE, maskCodeSpans, targetSpans, classifyStoryPaths,
 };