pi-hashline-edit-pro 6.3.1 → 6.4.1

package/src/copy-move.ts

@@ -5,6 +5,7 @@ import { constants } from "node:fs";
 import { execPipeline, noteAnchorError, previewFromPipe, previewError, type PipelineResult, type ReplaceDetails } from "./replace";
 import { commitEdit } from "./commit";
 import { readNormFile, safeSnapId, type NormFile } from "./file-reader";
+import { preEditSnapshotFor } from "./pre-edit-snapshot";
 import {
   lineHashes,
   MAX_HASH_LINES,
@@ -20,11 +21,11 @@ import {
 } from "./hashline";
 import { formatAnchorReclaimNotice, servedForPath, takeReclaimedPaths, withAnchorSession } from "./anchor-registry";
 import { batchMemberFor, batchServedFor, ensureBatchBase, executeBatchMember, noteBatchFailure, pendingBatchMemberFor, registerBatchPlanner, type BatchBase, type BatchMemberPlanner, type PlannedMember } from "./batch";
-import { loadP, loadGuide } from "./prompts";
+import { loadP, loadGuidelines } from "./prompts";
 import { assertTransferReq, normReq, type TransferReq } from "./payload-contract";
 import { abortIf, assertByteLimit, isRec, splitLines } from "./utils";
 import { toDisplayPath } from "./paths";
-import { getDiffContextLines, readConfig } from "./config";
+import { getDiffContextLines } from "./config";
 import { resolveInCwd, writeAtomic } from "./fs-write";
 import { restoreEndings, type LineEnding } from "./normalize";
 import { applyEndingOverrides, endingsForRange, joinSeparators, separatorsForSpans } from "./line-endings";
@@ -33,6 +34,7 @@ import { buildChanged, buildMetrics, type TResult } from "./replace-response";
 import { servedHashesFromDiff, serveRows } from "./served";
 import {
   assertBoundaryLinesServed,
+  assertPathOption,
   DEFAULT_EDIT_FLAGS,
   editRenderResultWrapper,
   editToolBase,
@@ -52,7 +54,8 @@ export type TransferKind = "copy" | "move";
 interface TransferRefs {
   sourceFrom: Anchor;
   sourceTo: Anchor;
-  insertAfter: Anchor;
+  anchor: Anchor;
+  direction: "before" | "after";
 }
 
 export interface TransferPlan {
@@ -69,6 +72,7 @@ interface PairFileCommit {
   absolutePath: string;
   mutationTargetPath: string;
   foldedAnchorLines: number;
+  anchorCarry?: number;
   endingOverrides?: (LineEnding | undefined)[];
 }
 
@@ -87,12 +91,13 @@ export function parseTransferAnchors(req: TransferReq): { refs: TransferRefs; wa
   const warnings: string[] = [];
   const from = stripAnchorRow(req.source_from.trim(), "source_from entry", warnings);
   const to = stripAnchorRow(req.source_to.trim(), "source_to entry", warnings);
-  const after = stripAnchorRow(req.insert_after.trim(), "insert_after entry", warnings);
+  const destination = stripAnchorRow(req.anchor.trim(), "anchor entry", warnings);
   return {
     refs: {
       sourceFrom: parseHashRef(from),
       sourceTo: parseHashRef(to),
-      insertAfter: parseHashRef(after),
+      anchor: parseHashRef(destination),
+      direction: req.direction,
     },
     warnings,
   };
@@ -118,13 +123,14 @@ export function buildTransferEdit(input: {
   const toLine = resolveAnchorLine(refs.sourceTo, fileLines, preload.fileHashes, displayPath);
   const sourceStart = Math.min(fromLine, toLine);
   const sourceEnd = Math.max(fromLine, toLine);
-  const insertLine = resolveAnchorLine(refs.insertAfter, fileLines, preload.fileHashes, displayPath);
+  const anchorLine = resolveAnchorLine(refs.anchor, fileLines, preload.fileHashes, displayPath);
+  const insertLine = refs.direction === "after" ? anchorLine : anchorLine - 1;
   if (insertLine >= sourceStart && insertLine < sourceEnd) {
     throw new Error(
-      `[E_BAD_SHAPE] "insert_after" resolves to line ${insertLine}, inside the source range (lines ${sourceStart}-${sourceEnd}). Use a line before source_from, or source_to to place the block right after itself.`,
+      `[E_BAD_SHAPE] "anchor" resolves to line ${anchorLine}, which places the block inside the source range (lines ${sourceStart}-${sourceEnd}). Use a line outside the source range.`,
     );
   }
-  assertBoundaryLinesServed(fileLines, preload.fileHashes, served, insertLine, insertLine, displayPath);
+  assertBoundaryLinesServed(fileLines, preload.fileHashes, served, anchorLine, anchorLine, displayPath);
   assertBoundaryLinesServed(fileLines, preload.fileHashes, served, sourceStart, sourceStart, displayPath);
   assertBoundaryLinesServed(fileLines, preload.fileHashes, served, sourceEnd, sourceEnd, displayPath);
   const sourceLines = fileLines.slice(sourceStart - 1, sourceEnd);
@@ -132,13 +138,17 @@ export function buildTransferEdit(input: {
   if (kind === "copy") {
     return {
       editParams: {
-        remove_from: preload.fileHashes[insertLine - 1]!,
-        remove_to: preload.fileHashes[insertLine - 1]!,
-        text: [fileLines[insertLine - 1]!, ...sourceLines],
+        remove_from: preload.fileHashes[anchorLine - 1]!,
+        remove_to: preload.fileHashes[anchorLine - 1]!,
+        text: refs.direction === "after"
+          ? [fileLines[anchorLine - 1]!, ...sourceLines]
+          : [...sourceLines, fileLines[anchorLine - 1]!],
       },
       foldedAnchorLines: 1,
-      anchorCarry: 0,
-      endingOverrides: [undefined, ...sourceEndings],
+      anchorCarry: refs.direction === "after" ? 0 : sourceLines.length,
+      endingOverrides: refs.direction === "after"
+        ? [undefined, ...sourceEndings]
+        : [...sourceEndings, undefined],
     };
   }
   if (insertLine < sourceStart) {
@@ -169,40 +179,34 @@ export function buildTransferEdit(input: {
   };
 }
 
+function describeTransferTargets(sourcePath: string, destinationPath: string): string {
+  return sourcePath === destinationPath
+    ? `the file "${sourcePath}"`
+    : `the source file "${sourcePath}" or the destination file "${destinationPath}"`;
+}
+
 async function resolveTransferTargets(req: TransferReq, cwd: string): Promise<{ sourcePath: string; destinationPath: string }> {
-  const { requirePath } = await readConfig();
-  if (!requirePath && req.path !== undefined) {
-    throw new Error("[E_BAD_SHAPE] Edit request contains unknown or unsupported fields: path. Path resolution is anchor-only; retry without `path`.");
-  }
-  if (requirePath && (typeof req.path !== "string" || req.path.length === 0)) {
-    throw new Error('[E_BAD_SHAPE] Copy/move request requires a non-empty "path" string when require-path mode is on. Provide `path` matching the source or destination file the anchors were served for.');
-  }
   const sourcePath = resolveEditTarget(req.source_from, req.source_to);
-  const destinationPath = resolveEditTarget(req.insert_after);
-  if (requirePath) {
-    const { resolved } = await resolveInCwd(req.path as string, cwd);
-    if (resolved !== sourcePath && resolved !== destinationPath) {
-      throw new Error(`[E_BAD_SHAPE] Provided "path" "${req.path}" does not match the source file "${sourcePath}" or the destination file "${destinationPath}".`);
-    }
-  }
+  const destinationPath = resolveEditTarget(req.anchor);
+  await assertPathOption({
+    providedPath: req.path,
+    cwd,
+    targets: [sourcePath, destinationPath],
+    expected: describeTransferTargets(sourcePath, destinationPath),
+    requestLabel: "Copy/move request",
+  });
   return { sourcePath, destinationPath };
 }
 
 async function assertTransferPathOption(req: TransferReq, cwd: string, member: PlannedMember): Promise<void> {
-  const { requirePath } = await readConfig();
-  if (!requirePath && req.path !== undefined) {
-    throw new Error("[E_BAD_SHAPE] Edit request contains unknown or unsupported fields: path. Path resolution is anchor-only; retry without `path`.");
-  }
-  if (requirePath && (typeof req.path !== "string" || req.path.length === 0)) {
-    throw new Error('[E_BAD_SHAPE] Copy/move request requires a non-empty "path" string when require-path mode is on. Provide `path` matching the source or destination file the anchors were served for.');
-  }
-  if (requirePath) {
-    const sourceTarget = member.sourceTarget ?? member.target;
-    const { resolved } = await resolveInCwd(req.path as string, cwd);
-    if (resolved !== sourceTarget && resolved !== member.target) {
-      throw new Error(`[E_BAD_SHAPE] Provided "path" "${req.path}" does not match the source file "${sourceTarget}" or the destination file "${member.target}".`);
-    }
-  }
+  const sourceTarget = member.sourceTarget ?? member.target;
+  await assertPathOption({
+    providedPath: req.path,
+    cwd,
+    targets: [sourceTarget, member.target],
+    expected: describeTransferTargets(sourceTarget, member.target),
+    requestLabel: "Copy/move request",
+  });
 }
 
 interface CrossTransferPreparation {
@@ -212,6 +216,7 @@ interface CrossTransferPreparation {
   destinationDisplay: string;
   destinationEdit: HTEdit;
   destinationFolded: number;
+  anchorCarry?: number;
   endingOverrides: (LineEnding | undefined)[];
   sourceEdit?: HTEdit;
 }
@@ -232,11 +237,17 @@ async function prepareCrossTransfer(input: {
   const { kind, refs, sourcePath, destinationPath, cwd, signal, noPersist } = input;
   const common = { signal, maxLines: MAX_HASH_LINES };
   const sourceAccessMode = kind === "move" ? constants.R_OK | constants.W_OK : constants.R_OK;
-  const sourcePreload = input.sourcePreload ?? (await readNormFile(sourcePath, cwd, noPersist ? { ...common, accessMode: constants.R_OK, noPersist: true, allocation: "shadow" } : { ...common, accessMode: sourceAccessMode }));
+  const candidate = kind === "copy" && input.sourcePreload === undefined ? preEditSnapshotFor(sourcePath) : undefined;
+  const snapshotPreload = candidate !== undefined
+    && candidate.fileHashes.includes(refs.sourceFrom.hash)
+    && candidate.fileHashes.includes(refs.sourceTo.hash)
+    ? candidate
+    : undefined;
+  const sourcePreload = input.sourcePreload ?? snapshotPreload ?? (await readNormFile(sourcePath, cwd, noPersist ? { ...common, accessMode: constants.R_OK, noPersist: true, allocation: "shadow" } : { ...common, accessMode: sourceAccessMode }));
   const destinationPreload = input.destinationPreload ?? (await readNormFile(destinationPath, cwd, noPersist ? { ...common, accessMode: constants.R_OK, noPersist: true, allocation: "shadow" } : { ...common, accessMode: constants.R_OK | constants.W_OK }));
   const sourceDisplay = toDisplayPath(cwd, sourcePreload.absolutePath, sourcePath);
   const destinationDisplay = toDisplayPath(cwd, destinationPreload.absolutePath, destinationPath);
-  const sourceServed = input.sourceServed ?? servedForPath(sourcePreload.absolutePath);
+  const sourceServed = input.sourceServed ?? (snapshotPreload !== undefined ? snapshotPreload.served : servedForPath(sourcePreload.absolutePath));
   const destinationServed = input.destinationServed ?? servedForPath(destinationPreload.absolutePath);
   const sourceLines = splitLines(sourcePreload.normalized);
   const destinationLines = splitLines(destinationPreload.normalized);
@@ -268,15 +279,15 @@ async function prepareCrossTransfer(input: {
     throw error;
   }
 
-  let insertLine = 0;
+  let anchorLine = 0;
   try {
-    insertLine = resolveAnchorLine(refs.insertAfter, destinationLines, destinationPreload.fileHashes, destinationDisplay);
+    anchorLine = resolveAnchorLine(refs.anchor, destinationLines, destinationPreload.fileHashes, destinationDisplay);
   } catch (error) {
     await adopt(destinationPreload.absolutePath, error);
     throw error;
   }
   try {
-    assertBoundaryLinesServed(destinationLines, destinationPreload.fileHashes, destinationServed, insertLine, insertLine, destinationDisplay);
+    assertBoundaryLinesServed(destinationLines, destinationPreload.fileHashes, destinationServed, anchorLine, anchorLine, destinationDisplay);
   } catch (error) {
     await adopt(destinationPreload.absolutePath, error);
     throw error;
@@ -289,23 +300,33 @@ async function prepareCrossTransfer(input: {
         remove_to: destinationPreload.fileHashes[0]!,
         text: [...moved],
       }
-    : {
-        remove_from: destinationPreload.fileHashes[insertLine - 1]!,
-        remove_to: destinationPreload.fileHashes[insertLine - 1]!,
-        text: [destinationLines[insertLine - 1]!, ...moved],
-      };
+    : refs.direction === "after"
+      ? {
+          remove_from: destinationPreload.fileHashes[anchorLine - 1]!,
+          remove_to: destinationPreload.fileHashes[anchorLine - 1]!,
+          text: [destinationLines[anchorLine - 1]!, ...moved],
+        }
+      : {
+          remove_from: destinationPreload.fileHashes[anchorLine - 1]!,
+          remove_to: destinationPreload.fileHashes[anchorLine - 1]!,
+          text: [...moved, destinationLines[anchorLine - 1]!],
+        };
   const destinationFolded = destinationPreload.normalized.length === 0 ? 0 : 1;
   const sourceEndings = endingsForRange(sourcePreload.endingSeparators, sourceStart, sourceEnd);
-  const endingOverrides = destinationFolded === 1 ? offsetEndings(1, sourceEndings) : sourceEndings;
+  const endingOverrides = destinationFolded === 0
+    ? sourceEndings
+    : refs.direction === "after"
+      ? offsetEndings(1, sourceEndings)
+      : sourceEndings;
   if (kind === "copy") {
-    return { sourcePreload, destinationPreload, sourceDisplay, destinationDisplay, destinationEdit, destinationFolded, endingOverrides };
+    return { sourcePreload, destinationPreload, sourceDisplay, destinationDisplay, destinationEdit, destinationFolded, ...(destinationFolded === 1 ? { anchorCarry: refs.direction === "after" ? 0 : moved.length } : {}), endingOverrides };
   }
   const sourceEdit: HTEdit = {
     remove_from: sourcePreload.fileHashes[sourceStart - 1]!,
     remove_to: sourcePreload.fileHashes[sourceEnd - 1]!,
     text: [],
   };
-  return { sourcePreload, destinationPreload, sourceDisplay, destinationDisplay, destinationEdit, destinationFolded, sourceEdit, endingOverrides };
+  return { sourcePreload, destinationPreload, sourceDisplay, destinationDisplay, destinationEdit, destinationFolded, ...(destinationFolded === 1 ? { anchorCarry: refs.direction === "after" ? 0 : moved.length } : {}), sourceEdit, endingOverrides };
 }
 
 function pairEntry(pipe: PipelineResult, separators: LineEnding[] | undefined): UndoEntry {
@@ -333,6 +354,7 @@ async function commitMovePair(input: {
   ]);
   const destinationSpan = input.destination.pipe.spans?.[0];
   const sourceSpan = input.source.pipe.spans?.[0];
+  if (destinationSpan && input.destination.anchorCarry !== undefined) destinationSpan.carry = input.destination.anchorCarry;
   const destinationSeparators = destinationSpan
     ? separatorsForSpans(input.destination.pipe.originalSeparators, input.destination.pipe.originalHashes.length, [destinationSpan], input.destination.pipe.result, input.destination.pipe.originalEnding, splitLines(input.destination.pipe.originalNormalized))
     : undefined;
@@ -558,7 +580,7 @@ async function executeCrossFile(
         absolutePath: destination.absolute,
         mutationTargetPath: destination.resolved,
         editAnchors: [prepared.destinationEdit.remove_from, prepared.destinationEdit.remove_to],
-        ...(prepared.destinationFolded === 1 ? { anchorCarry: 0 } : {}),
+        ...(prepared.anchorCarry !== undefined ? { anchorCarry: prepared.anchorCarry } : {}),
         endingOverrides: prepared.endingOverrides,
         signal,
         verb: "copied",
@@ -581,6 +603,7 @@ async function executeCrossFile(
         absolutePath: destination.absolute,
         mutationTargetPath: destination.resolved,
         foldedAnchorLines: prepared.destinationFolded,
+        ...(prepared.anchorCarry !== undefined ? { anchorCarry: prepared.anchorCarry } : {}),
         endingOverrides: prepared.endingOverrides,
       },
       signal,
@@ -624,6 +647,7 @@ function planTransferBatchMember(kind: TransferKind): BatchMemberPlanner {
       warnings: [...warnings, ...resWarnings],
       planned,
       foldedLines: transferPlan.foldedAnchorLines,
+      direction: refs.direction,
       ...(transferPlan.anchorCarry !== undefined ? { carryIndex: transferPlan.anchorCarry } : {}),
       ...(transferPlan.servedOverride !== undefined ? { servedOverride: transferPlan.servedOverride } : {}),
       ...(transferPlan.endingOverrides !== undefined ? { contentSeparators: transferPlan.endingOverrides } : {}),
@@ -650,7 +674,7 @@ async function executeBatchCrossCopy(
     const sourceMember = pendingBatchMemberFor(sourcePath);
     const sourcePreload = sourceMember
       ? preloadFromBase(await ensureBatchBase({ member: sourceMember, targetPath: sourcePath, mutationTargetPath: sourceMember.target, cwd, signal }))
-      : await readNormFile(sourcePath, cwd, { signal, accessMode: constants.R_OK, maxLines: MAX_HASH_LINES });
+      : undefined;
     prepared = await prepareCrossTransfer({
       kind: "copy",
       refs,
@@ -686,7 +710,7 @@ async function executeBatchCrossCopy(
       hedit,
       warnings: [...warnings, ...resWarnings],
       foldedLines: prepared.destinationFolded,
-      ...(prepared.destinationFolded === 1 ? { carryIndex: 0 } : {}),
+      ...(prepared.anchorCarry !== undefined ? { carryIndex: prepared.anchorCarry } : {}),
       contentSeparators: prepared.endingOverrides,
     },
   });
@@ -751,7 +775,7 @@ async function executeBatchCrossMove(
       hedit,
       warnings: [...warnings, ...resWarnings, ...sourceWarnings],
       foldedLines: prepared.destinationFolded,
-      ...(prepared.destinationFolded === 1 ? { carryIndex: 0 } : {}),
+      ...(prepared.anchorCarry !== undefined ? { carryIndex: prepared.anchorCarry } : {}),
       contentSeparators: prepared.endingOverrides,
       sourceMove: {
         displayPath: prepared.sourceDisplay,
@@ -825,7 +849,7 @@ export async function transferPreview(kind: TransferKind, request: unknown, cwd:
   }
 }
 
-function getTransferInput(args: unknown): { path?: string; source_from?: string; source_to?: string; insert_after?: string } | null {
+function getTransferInput(args: unknown): { path?: string; source_from?: string; source_to?: string; anchor?: string; direction?: string } | null {
   let normalized: unknown;
   try {
     normalized = normReq(args);
@@ -836,7 +860,8 @@ function getTransferInput(args: unknown): { path?: string; source_from?: string;
   if (
     typeof normalized.source_from !== "string" ||
     typeof normalized.source_to !== "string" ||
-    typeof normalized.insert_after !== "string"
+    typeof normalized.anchor !== "string" ||
+    typeof normalized.direction !== "string"
   ) {
     return null;
   }
@@ -844,22 +869,27 @@ function getTransferInput(args: unknown): { path?: string; source_from?: string;
     ...(typeof normalized.path === "string" ? { path: normalized.path } : {}),
     source_from: normalized.source_from,
     source_to: normalized.source_to,
-    insert_after: normalized.insert_after,
+    anchor: normalized.anchor,
+    direction: normalized.direction,
   };
 }
 
 const transferSourceFromSchema = Type.String({
   description:
-    "4-char anchor of the FIRST source line to copy (never the row content).",
+    "4-char anchor of the FIRST source line to copy.",
 });
 const transferSourceToSchema = Type.String({
   description:
     "4-char anchor of the LAST source line to copy.",
 });
-const transferInsertAfterSchema = Type.String({
+const transferAnchorSchema = Type.String({
   description:
-    "4-char anchor of the destination line; the block goes after it and may live in another file.",
+    "4-char anchor of the destination line; the block lands before or after it and it may live in another file.",
 });
+const transferDirectionSchema = Type.Union(
+  [Type.Literal("after"), Type.Literal("before")],
+  { description: '"after" places the block below the anchor line, "before" above it' },
+);
 const transferPathRequiredSchema = Type.String({
   description:
     "Path to the source or destination file the anchors were served for; required and must match anchor ownership.",
@@ -869,7 +899,8 @@ const transferToolSchema = Type.Object(
   {
     source_from: transferSourceFromSchema,
     source_to: transferSourceToSchema,
-    insert_after: transferInsertAfterSchema,
+    anchor: transferAnchorSchema,
+    direction: transferDirectionSchema,
   },
   { additionalProperties: true },
 );
@@ -881,7 +912,8 @@ export function buildTransferToolSchema(requirePath: boolean): typeof transferTo
       path: transferPathRequiredSchema,
       source_from: transferSourceFromSchema,
       source_to: transferSourceToSchema,
-      insert_after: transferInsertAfterSchema,
+      anchor: transferAnchorSchema,
+      direction: transferDirectionSchema,
     },
     { additionalProperties: true },
   ) as typeof transferToolSchema;
@@ -895,8 +927,8 @@ export function buildTransferToolDef(kind: TransferKind, flags: EditToolFlags =
       description: loadP(`../tool-prompts/${kind}.md`),
       snippet: loadP(`../tool-prompts/${kind}-snippet.md`),
       guidelines: [
-        ...loadGuide(`../tool-prompts/${kind}-guidelines.md`),
-        ...loadGuide("../tool-prompts/transfer-guidelines.md"),
+        ...loadGuidelines(`../tool-prompts/${kind}-guidelines.md`),
+        ...loadGuidelines("../tool-prompts/transfer-guidelines.md"),
       ],
     },
     flags,

package/src/edit-common.ts

@@ -6,6 +6,7 @@ import { assertRangeServed, lineChecksum, parseHashRef, stripAnchorRow } from ".
 import { readConfig } from "./config";
 import { makeRenderCall, renderEditResult, type RPreview, type FgT } from "./replace-render";
 import type { ReplaceDetails } from "./replace";
+import type { Guideline } from "./prompts";
 export const editPrepare = makePrepareArguments();
 
 export interface EditToolFlags {
@@ -46,7 +47,7 @@ export async function currentEditFlags(codemode = false): Promise<EditToolFlags>
 
 function preferenceGuideline(flags: EditToolFlags): string {
   const tools = gatedEditOps(["read", "replace", "replace_match", "insert", "copy", "move", "undo_last_change"], flags);
-  return `Prefer the hashline tools for anything that touches files: ${joinOps(tools, { backtick: true })}.`;
+  return `Prefer the hashline tools for every file read and edit: ${joinOps(tools, { backtick: true })}.`;
 }
 
 const SHARED_EDIT_OPS = ["replace", "replace_match", "insert", "copy", "move"];
@@ -61,6 +62,17 @@ const SCRIPT_TRANSFER_GUIDELINE =
 const SCRIPT_UNDO_GUIDELINE =
   "`undo_last_change`: each edit from one codemode script takes the undo slot, so only the most recent is undoable.";
 
+const READ_REREAD_ID = "read-reread";
+const READ_OUTLINE_ID = "read-outline";
+const READ_MATCH_ID = "read-match-served";
+const UNDO_WRITE_CLEARS_ID = "undo-write-clears";
+const UNDO_CROSS_FILE_MOVE_ID = "undo-cross-file-move";
+const NEUTRAL_READ_REREAD = "`read`: call again after an edit when you need anchors you lack.";
+const NEUTRAL_UNDO_WRITE_CLEARS = "`undo_last_change`: only the last `replace`/`replace_match`/`insert`/`copy`/`move` per file is undoable; a `write` clears it, so undo before any other edit or write.";
+const GREP_OPS_PHRASE = "replace, insert, copy, or move";
+const UNDO_OPS_PHRASE = "replace, replace_match, insert, copy, or move";
+const UNDO_GUIDELINE_OPS_PHRASE = "`replace`/`replace_match`/`insert`/`copy`/`move`";
+
 function operationNames(ops: string[], flags: EditToolFlags): string {
   return joinOps(gatedEditOps(ops, flags), { backtick: true, separator: "/" });
 }
@@ -69,24 +81,24 @@ function batchGuideline(flags: EditToolFlags): string {
   const tools = operationNames(SHARED_EDIT_OPS, flags);
   const outcome = flags.autoRead ? "diff" : "result";
   const script = flags.codemode ? ` ${SCRIPT_BATCH_GUIDELINE}` : "";
-  return `${tools}: same-file calls in one message are grouped into one batch; earlier calls reply \`In batch N (queued)\` and the last applied call shows the combined ${outcome}, with one undo for the whole batch. A call whose own request is invalid (anchors, shape, or \`old_string\`) fails on its own; any failure once the batch runs aborts the whole batch.${script}`;
+  return `${tools}: same-file calls in one message commit as one batch; earlier calls reply \`In batch N (queued)\`, the last shows the combined ${outcome}, and one undo reverts all. A request-invalid call (anchors, shape, or \`old_string\`) fails alone; a failure while the batch runs aborts it.${script}`;
 }
 
 function diffGuideline(flags: EditToolFlags): string {
   const tools = operationNames(SHARED_DIFF_OPS, flags);
-  return `${tools}: in the post-edit diff, \`-anchor│\` rows are dead anchors; \`+anchor│\` and \` anchor│\` rows are live anchors for the next edit.`;
+  return `${tools}: in the post-edit diff, \`-anchor│\` rows are dead anchors; \`+anchor│\` and \` anchor│\` rows carry live anchors for the next edit.`;
 }
 
 function pathGuideline(flags: EditToolFlags): string {
   const tools = operationNames(SHARED_EDIT_OPS, flags);
   return flags.requirePath
     ? `${tools}: pass \`path\` matching the file the anchors were served for; it is required and must match anchor ownership.`
-    : `${tools}: path resolution is anchor-only; do not pass \`path\`.`;
+    : `${tools}: anchors resolve the file; \`path\` is optional but must match anchor ownership when passed.`;
 }
 
 function payloadGuideline(flags: EditToolFlags): string {
   const tools = operationNames(SHARED_PAYLOAD_OPS, flags);
-  return `${tools}: write the character itself, not an escape; the tool writes \`text\` verbatim and never decodes escapes — \`\\uXXXX\` is the character, \`\\\\uXXXX\` the literal text.`;
+  return `${tools}: \`text\` is written exactly as received; escapes are decoded once when the call is parsed, and the tool never decodes again — \`\\uXXXX\` is the character, \`\\\\uXXXX\` the literal text.`;
 }
 
 function strictInputGuideline(flags: EditToolFlags): string {
@@ -109,43 +121,45 @@ function finalizePrompts(
   return { description, snippet, guidelines: [...guidelines, ...shared] };
 }
 
-export function withReplacePrompts(base: { description: string; snippet: string; guidelines: string[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
+export function withReplacePrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
   let description = base.description;
-  const guidelines = [preferenceGuideline(flags), ...base.guidelines];
+  const guidelines = [preferenceGuideline(flags), ...base.guidelines.map((guideline) => guideline.text)];
   if (!flags.replaceMatchEnabled) {
-    description = description.replace(/\n?To change only part of a line without retyping the rest, use `replace_match` instead; it preserves every character the request does not name\./, "");
+    description = description
+      .split(/(?<=\.)\s+/)
+      .filter((sentence) => !sentence.includes("`replace_match`"))
+      .join(" ");
   }
   return finalizePrompts(description, base.snippet, guidelines, flags);
 }
 
-function readGuidelineApplies(guideline: string, flags: EditToolFlags): boolean {
-  if (!flags.autoReadAllOutline && guideline.includes("[limit N]")) return false;
-  if (!flags.replaceMatchEnabled && guideline.includes("`replace_match`")) return false;
+function readGuidelineApplies(guideline: Guideline, flags: EditToolFlags): boolean {
+  if (guideline.id === READ_OUTLINE_ID) return flags.autoReadAllOutline;
+  if (guideline.id === READ_MATCH_ID) return flags.replaceMatchEnabled;
   return true;
 }
 
-export function withReadPrompts(base: { description: string; snippet: string; guidelines: string[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
+export function withReadPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
   const preference = preferenceGuideline(flags);
   const script = flags.codemode ? [RESULT_CONTRACT_GUIDELINE] : [];
-  const baseGuidelines = base.guidelines.filter((guideline) => readGuidelineApplies(guideline, flags));
+  const applicable = base.guidelines.filter((guideline) => readGuidelineApplies(guideline, flags));
   if (flags.autoReadAllActive) {
-    const rewritten = baseGuidelines
-      .filter((guideline) => !guideline.includes("call again after an edit"))
+    const rewritten = applicable.filter((guideline) => guideline.id !== READ_REREAD_ID).map((guideline) => guideline.text);
     return { description: base.description, snippet: base.snippet, guidelines: [preference, ...rewritten, ...script] };
   }
-  if (flags.autoRead) return { description: base.description, snippet: base.snippet, guidelines: [preference, ...baseGuidelines, ...script] };
-  const guidelines = [preference, ...baseGuidelines, ...script];
-  const mapped = guidelines.map((guideline) => guideline.startsWith("`read`: call again after an edit") ? "`read`: call again after an edit when you need anchors you lack." : guideline);
-  return { description: base.description, snippet: base.snippet, guidelines: mapped };
+  const guidelines = applicable.map((guideline) =>
+    guideline.id === READ_REREAD_ID && !flags.autoRead ? NEUTRAL_READ_REREAD : guideline.text,
+  );
+  return { description: base.description, snippet: base.snippet, guidelines: [preference, ...guidelines, ...script] };
 }
 
-export function withInsertPrompts(base: { description: string; snippet: string; guidelines: string[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
-  const guidelines = [preferenceGuideline(flags), ...base.guidelines];
+export function withInsertPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
+  const guidelines = [preferenceGuideline(flags), ...base.guidelines.map((guideline) => guideline.text)];
   return finalizePrompts(base.description, base.snippet, guidelines, flags);
 }
 
-export function withReplaceMatchPrompts(base: { description: string; snippet: string; guidelines: string[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
-  const guidelines = [preferenceGuideline(flags), ...base.guidelines];
+export function withReplaceMatchPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
+  const guidelines = [preferenceGuideline(flags), ...base.guidelines.map((guideline) => guideline.text)];
   return finalizePrompts(base.description, base.snippet, guidelines, flags);
 }
 
@@ -166,35 +180,34 @@ function joinOps(ops: string[], options?: { backtick?: boolean; separator?: "/"
   return formatted.length === 2 ? `${head} or ${last}` : `${head}, or ${last}`;
 }
 
-export function withGrepPrompts(base: { description: string; snippet: string; guidelines: string[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
-  const guidelines = [preferenceGuideline(flags), ...base.guidelines];
+export function withGrepPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
+  const guidelines = [preferenceGuideline(flags), ...base.guidelines.map((guideline) => guideline.text)];
   if (flags.codemode) guidelines.push(RESULT_CONTRACT_GUIDELINE);
-  if (flags.copyMoveEnabled) return { ...base, guidelines };
-  return { ...base, guidelines, description: base.description.replaceAll("replace, insert, copy, or move", joinOps(gatedEditOps(["replace", "insert", "copy", "move"], flags))) };
+  if (flags.copyMoveEnabled) return { description: base.description, snippet: base.snippet, guidelines };
+  const description = base.description.replaceAll(GREP_OPS_PHRASE, joinOps(gatedEditOps(["replace", "insert", "copy", "move"], flags)));
+  return { description, snippet: base.snippet, guidelines };
 }
 
-export function withUndoPrompts(base: { description: string; snippet: string; guidelines: string[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
+export function withUndoPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
   const ops = gatedEditOps(["replace", "replace_match", "insert", "copy", "move"], flags);
-  let description = base.description;
-  let snippet = base.snippet;
   const script = flags.codemode ? [RESULT_CONTRACT_GUIDELINE, SCRIPT_UNDO_GUIDELINE] : [];
-  let guidelines = [preferenceGuideline(flags), ...base.guidelines, ...script];
-  if (!flags.autoRead) {
-    guidelines = guidelines.map((guideline) => guideline.includes("a `write` clears the history") ? "`undo_last_change`: only the last `replace`/`replace_match`/`insert`/`copy`/`move` per file is undoable; a `write` clears it, so undo before any other edit or write." : guideline);
-  }
+  let description = base.description;
+  let guidelines = [
+    preferenceGuideline(flags),
+    ...base.guidelines
+      .filter((guideline) => flags.copyMoveEnabled || guideline.id !== UNDO_CROSS_FILE_MOVE_ID)
+      .map((guideline) => (guideline.id === UNDO_WRITE_CLEARS_ID && !flags.autoRead ? NEUTRAL_UNDO_WRITE_CLEARS : guideline.text)),
+    ...script,
+  ];
   if (ops.length !== 5) {
-    description = description.replaceAll("replace, replace_match, insert, copy, or move", joinOps(ops));
-    snippet = snippet.replaceAll("`replace`, `replace_match`, `insert`, `copy`, or `move`", joinOps(ops, { backtick: true }));
-    guidelines = guidelines.map((guideline) => guideline.replaceAll("`replace`/`replace_match`/`insert`/`copy`/`move`", joinOps(ops, { backtick: true, separator: "/" })));
+    description = description.replaceAll(UNDO_OPS_PHRASE, joinOps(ops));
+    guidelines = guidelines.map((guideline) => guideline.replaceAll(UNDO_GUIDELINE_OPS_PHRASE, joinOps(ops, { backtick: true, separator: "/" })));
   }
-  if (!flags.copyMoveEnabled) {
-    guidelines = guidelines.filter((guideline) => !guideline.includes("cross-file `move`"));
-  }
-  return { description, snippet, guidelines };
+  return { description, snippet: base.snippet, guidelines };
 }
 
-export function withTransferPrompts(base: { description: string; snippet: string; guidelines: string[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
-  const guidelines = [preferenceGuideline(flags), ...base.guidelines, ...(flags.codemode ? [SCRIPT_TRANSFER_GUIDELINE] : [])];
+export function withTransferPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
+  const guidelines = [preferenceGuideline(flags), ...base.guidelines.map((guideline) => guideline.text), ...(flags.codemode ? [SCRIPT_TRANSFER_GUIDELINE] : [])];
   return finalizePrompts(base.description, base.snippet, guidelines, flags, { stringPayload: false });
 }
 
@@ -246,24 +259,43 @@ export interface PathRequirementInput {
   anchorTarget?: string;
 }
 
-export async function resolveEditTargetWithRequirement(input: PathRequirementInput): Promise<string> {
+export interface PathOptionInput {
+  providedPath: unknown;
+  cwd: string;
+  targets: readonly string[];
+  expected: string;
+  requestLabel: string;
+}
+
+export async function assertPathOption(input: PathOptionInput): Promise<void> {
   const { requirePath } = await readConfig();
-  if (!requirePath && input.providedPath !== undefined) {
-    throw new Error("[E_BAD_SHAPE] Edit request contains unknown or unsupported fields: path. Path resolution is anchor-only; retry without `path`.");
+  if (input.providedPath === undefined || (requirePath && input.providedPath === "")) {
+    if (requirePath) {
+      throw new Error(`[E_BAD_SHAPE] ${input.requestLabel} requires a non-empty "path" string when require-path mode is on. Provide \`path\` matching ${input.expected}.`);
+    }
+    return;
+  }
+  if (typeof input.providedPath !== "string" || input.providedPath.length === 0) {
+    throw new Error(`[E_BAD_SHAPE] ${input.requestLabel} field "path" must be a non-empty string when provided.`);
   }
-  if (requirePath && (typeof input.providedPath !== "string" || input.providedPath.length === 0)) {
-    throw new Error('[E_BAD_SHAPE] Edit request requires a non-empty "path" string when require-path mode is on. Provide `path` matching the file the anchors were served for.');
+  const { resolved } = await resolveInCwd(input.providedPath, input.cwd);
+  if (!input.targets.includes(resolved)) {
+    throw new Error(`[E_BAD_SHAPE] Provided "path" "${input.providedPath}" does not match ${input.expected}.`);
   }
+}
+
+export async function resolveEditTargetWithRequirement(input: PathRequirementInput): Promise<string> {
   const anchorTarget = input.anchorTarget
     ?? (typeof input.anchor === "string"
       ? resolveEditTarget(input.anchor)
       : resolveEditTarget(input.removeFrom as string, input.removeTo));
-  if (requirePath) {
-    const { resolved } = await resolveInCwd(input.providedPath as string, input.cwd);
-    if (resolved !== anchorTarget) {
-      throw new Error(`[E_BAD_SHAPE] Provided "path" "${input.providedPath}" does not match anchor ownership "${anchorTarget}".`);
-    }
-  }
+  await assertPathOption({
+    providedPath: input.providedPath,
+    cwd: input.cwd,
+    targets: [anchorTarget],
+    expected: `anchor ownership "${anchorTarget}"`,
+    requestLabel: "Edit request",
+  });
   return anchorTarget;
 }