@cueloop/schema 0.1.0-alpha.2 → 0.1.0-alpha.20

package/src/feedback.ts

@@ -1,11 +1,11 @@
 /**
  * feedback.md: the ONE structured markdown document the agent receives on
- * resolve (map #2, verified in the edit-mode deep-dive). Directive framing -
- * soft phrasing gets ignored by models: the plan diff is applied verbatim
- * first, then every annotation is addressed, located by quoted text.
+ * resolve. Directive framing - soft phrasing gets ignored by models: the plan
+ * diff is applied verbatim first, then every annotation is addressed, located
+ * by quoted text.
  */
 
-import type { Annotation, ReviewSession, VerdictKind } from "./types";
+import { isAgentNote, type Annotation, type ReviewSession, type VerdictKind } from "./types";
 import { parseBlocks, sectionOf } from "./markdown";
 import { resolveAnchor } from "./anchor";
 import { unifiedDiffText } from "./diff";
@@ -22,10 +22,12 @@ export interface FeedbackInput {
   planPath?: string;
 }
 
-const quoteLines = (s: string) => "> " + s.replace(/\n/g, "\n> ");
+const quoteLines = (text: string) => "> " + text.replace(/\n/g, "\n> ");
 
 export function renderFeedback(input: FeedbackInput): string {
   const path = input.planPath ?? "plan.md";
+  // agent notes are the submitter's own context - never echoed back as feedback
+  const annotations = input.annotations.filter((annotation) => !isAgentNote(annotation));
   const blocks = parseBlocks(input.workingCopy ?? input.artifactContent);
   const lines: string[] = [];
   lines.push("# Review: " + input.verdictKind.replace("_", " "));
@@ -49,35 +51,35 @@ export function renderFeedback(input: FeedbackInput): string {
     lines.push("");
   }
 
-  if (input.annotations.length) {
-    lines.push(`## Annotations (${input.annotations.length})`);
+  if (annotations.length) {
+    lines.push(`## Annotations (${annotations.length})`);
     lines.push("");
     lines.push(`Address every item. Locate each one in ${path} by its quoted text.`);
     lines.push("");
-    input.annotations.forEach((a, i) => {
-      const res = resolveAnchor(a.anchor, blocks);
-      const sec = res ? sectionOf(blocks, res.blockIndex) : "";
-      const loc = sec ? ` (§ ${sec})` : "";
-      const flag = res === null ? " [orphaned anchor: the quoted text is no longer present]" : "";
-      if (a.kind === "suggestion") {
-        lines.push(`### ${i + 1}. Suggested change${loc}${flag}`);
+    annotations.forEach((annotation, annotationIndex) => {
+      const resolved = resolveAnchor(annotation.anchor, blocks);
+      const sectionTitle = resolved ? sectionOf(blocks, resolved.blockIndex) : "";
+      const location = sectionTitle ? ` (§ ${sectionTitle})` : "";
+      const orphanFlag = resolved === null ? " [orphaned anchor: the quoted text is no longer present]" : "";
+      if (annotation.kind === "suggestion") {
+        lines.push(`### ${annotationIndex + 1}. Suggested change${location}${orphanFlag}`);
         lines.push("");
         lines.push("Replace:");
-        lines.push(quoteLines(a.anchor.quote));
+        lines.push(quoteLines(annotation.anchor.quote));
         lines.push("With:");
-        lines.push(quoteLines(a.body));
+        lines.push(quoteLines(annotation.body));
       } else {
-        lines.push(`### ${i + 1}. ${capitalize(a.kind)}${loc}${flag}`);
+        lines.push(`### ${annotationIndex + 1}. ${capitalize(annotation.kind)}${location}${orphanFlag}`);
         lines.push("");
-        lines.push(quoteLines(a.anchor.quote));
+        lines.push(quoteLines(annotation.anchor.quote));
         lines.push("");
-        lines.push(a.body);
+        lines.push(annotation.body);
       }
       lines.push("");
     });
   }
 
-  if (!diff && !input.annotations.length) {
+  if (!diff && !annotations.length) {
     lines.push("_No edits or annotations._");
     lines.push("");
   }
@@ -95,6 +97,6 @@ export function feedbackForSession(session: ReviewSession, verdictKind: VerdictK
   });
 }
 
-function capitalize(s: string): string {
-  return s.charAt(0).toUpperCase() + s.slice(1);
+function capitalize(word: string): string {
+  return word.charAt(0).toUpperCase() + word.slice(1);
 }

package/src/herdr.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { detectHerdr, insideHerdr, returnPaneFor } from "./herdr";
+
+describe("detectHerdr", () => {
+  test("null outside herdr, context inside", () => {
+    expect(detectHerdr({})).toBeNull();
+    expect(detectHerdr({ HERDR_ENV: "1", HERDR_PANE_ID: "p1" })).toBeNull();
+    expect(detectHerdr({ HERDR_ENV: "1", HERDR_PANE_ID: "p1", HERDR_BIN_PATH: "/x/herdr" })).toEqual({
+      paneId: "p1",
+      binPath: "/x/herdr",
+    });
+  });
+});
+
+describe("insideHerdr", () => {
+  test("true only when HERDR_ENV is exactly 1", () => {
+    expect(insideHerdr({})).toBeFalse();
+    expect(insideHerdr({ HERDR_ENV: "0" })).toBeFalse();
+    expect(insideHerdr({ HERDR_ENV: "1" })).toBeTrue();
+  });
+});
+
+describe("returnPaneFor", () => {
+  test("outside herdr there is never a return target", () => {
+    expect(returnPaneFor("w1:p1", {})).toBeUndefined();
+  });
+
+  test("env override wins, session meta is the fallback", () => {
+    const inside = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p9" };
+    expect(returnPaneFor("w1:p1", inside)).toBe("w1:p1");
+    expect(returnPaneFor("w1:p1", { ...inside, CUELOOP_RETURN_PANE: "w1:p2" })).toBe("w1:p2");
+  });
+
+  test("returning to our own pane is a no-op", () => {
+    expect(returnPaneFor("w1:p1", { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1" })).toBeUndefined();
+  });
+});

package/src/herdr.ts

@@ -0,0 +1,43 @@
+/**
+ * The herdr ambient env contract, single-sourced. A process running inside a
+ * herdr pane sees HERDR_ENV=1 plus the pane id and the herdr binary path.
+ * Both the agent-side reporter (adapters) and the reviewer-side return-focus
+ * (client) read this contract; decoding it in one place stops the two sides
+ * drifting on which vars are required. Pure: no IO, env is only the default
+ * argument so callers can pass a fixture.
+ */
+
+export interface HerdrContext {
+  paneId: string;
+  binPath: string;
+}
+
+export type HerdrEnv = Record<string, string | undefined>;
+
+/**
+ * The pane's full contract - pane id and binary path - or null outside a
+ * functioning herdr. Required by anything that spawns the herdr CLI.
+ */
+export function detectHerdr(env: HerdrEnv = process.env): HerdrContext | null {
+  if (env.HERDR_ENV !== "1") return null;
+  const paneId = env.HERDR_PANE_ID;
+  const binPath = env.HERDR_BIN_PATH;
+  if (!paneId || !binPath) return null;
+  return { paneId, binPath };
+}
+
+/** True whenever this process runs inside a herdr pane. */
+export function insideHerdr(env: HerdrEnv = process.env): boolean {
+  return env.HERDR_ENV === "1";
+}
+
+/**
+ * The pane a closing review should hand focus back to: the opener's
+ * CUELOOP_RETURN_PANE, or the session's recorded pane, but never this pane
+ * itself. Undefined outside herdr or when the only candidate is our own pane.
+ */
+export function returnPaneFor(sessionHerdrPane?: string, env: HerdrEnv = process.env): string | undefined {
+  if (!insideHerdr(env)) return undefined;
+  const pane = env.CUELOOP_RETURN_PANE ?? sessionHerdrPane;
+  return pane && pane !== env.HERDR_PANE_ID ? pane : undefined;
+}

package/src/index.ts

@@ -1,5 +1,7 @@
 export * from "./types";
 export * from "./markdown";
+export * from "./working-copy";
 export * from "./diff";
 export * from "./anchor";
 export * from "./feedback";
+export * from "./herdr";

package/src/markdown.test.ts

@@ -30,7 +30,7 @@ const y = 2;
 describe("parseBlocks", () => {
   test("parses every block kind with source line ranges", () => {
     const blocks = parseBlocks(SAMPLE);
-    expect(blocks.map((b) => b.kind)).toEqual([
+    expect(blocks.map((block) => block.kind)).toEqual([
       "h1",
       "h2",
       "p",
@@ -43,7 +43,7 @@ describe("parseBlocks", () => {
       "quote",
       "hr",
     ]);
-    const code = blocks.find((b) => b.kind === "code")!;
+    const code = blocks.find((block) => block.kind === "code")!;
     expect(code.lang).toBe("ts");
     expect(code.text).toBe("const x = 1;\nconst y = 2;");
     // fence lines included in the source range
@@ -52,49 +52,49 @@ describe("parseBlocks", () => {
 
   test("multi-line paragraph keeps its text and range", () => {
     const blocks = parseBlocks(SAMPLE);
-    const p = blocks.find((b) => b.kind === "p")!;
-    expect(p.text).toBe("A paragraph that\nspans two lines.");
-    expect(p.lineEnd - p.lineStart).toBe(1);
+    const paragraph = blocks.find((block) => block.kind === "p")!;
+    expect(paragraph.text).toBe("A paragraph that\nspans two lines.");
+    expect(paragraph.lineEnd - paragraph.lineStart).toBe(1);
   });
 
   test("line ranges index into the source", () => {
     const lines = SAMPLE.split("\n");
-    for (const b of parseBlocks(SAMPLE)) {
-      if (b.kind === "code") {
-        expect(lines[b.lineStart]!.startsWith("```")).toBe(true);
-      } else if (b.kind === "h2") {
-        expect(lines[b.lineStart]!.startsWith("## ")).toBe(true);
+    for (const block of parseBlocks(SAMPLE)) {
+      if (block.kind === "code") {
+        expect(lines[block.lineStart]!.startsWith("```")).toBe(true);
+      } else if (block.kind === "h2") {
+        expect(lines[block.lineStart]!.startsWith("## ")).toBe(true);
       }
     }
   });
 
   test("round-trips through blockToMd", () => {
     const blocks = parseBlocks(SAMPLE);
-    let oli = 0;
+    let orderedItemCount = 0;
     const rebuilt = blocks
-      .map((b) => {
-        oli = b.kind === "oli" ? oli + 1 : 0;
-        return blockToMd(b, oli || 1);
+      .map((block) => {
+        orderedItemCount = block.kind === "oli" ? orderedItemCount + 1 : 0;
+        return blockToMd(block, orderedItemCount || 1);
       })
       .join("\n\n");
     // re-parsing the rebuild yields the same kinds and texts
     const again = parseBlocks(rebuilt);
-    expect(again.map((b) => [b.kind, b.text])).toEqual(blocks.map((b) => [b.kind, b.text]));
+    expect(again.map((block) => [block.kind, block.text])).toEqual(blocks.map((block) => [block.kind, block.text]));
   });
 
   test("unknown constructs degrade to paragraphs, no content lost", () => {
     const md = "| a | b |\n|---|---|\n| 1 | 2 |";
     const blocks = parseBlocks(md);
-    expect(blocks.map((b) => b.text).join("\n")).toContain("| a | b |");
+    expect(blocks.map((block) => block.text).join("\n")).toContain("| a | b |");
   });
 });
 
 describe("sectionOf", () => {
   test("returns the nearest preceding heading", () => {
     const blocks = parseBlocks(SAMPLE);
-    const oliIdx = blocks.findIndex((b) => b.kind === "oli");
-    expect(sectionOf(blocks, oliIdx)).toBe("Steps");
-    const pIdx = blocks.findIndex((b) => b.kind === "p");
-    expect(sectionOf(blocks, pIdx)).toBe("Context");
+    const orderedItemIndex = blocks.findIndex((block) => block.kind === "oli");
+    expect(sectionOf(blocks, orderedItemIndex)).toBe("Steps");
+    const paragraphIndex = blocks.findIndex((block) => block.kind === "p");
+    expect(sectionOf(blocks, paragraphIndex)).toBe("Context");
   });
 });

package/src/markdown.ts

@@ -1,6 +1,6 @@
 /**
- * Markdown block model (map #22): parse source into addressable blocks that
- * record their source line ranges. Rendered→source mapping is block+line
+ * Markdown block model: parse source into addressable blocks that record
+ * their source line ranges. Rendered-to-source mapping is block+line
  * granular; the quote carries sub-block precision. Round-trip safe for the
  * subset cueloop plans use; unknown constructs fall back to paragraph blocks
  * so no content is ever lost.
@@ -19,113 +19,113 @@ export interface Block {
   lineEnd: number;
 }
 
-function isMarkerLine(l: string): boolean {
+function isMarkerLine(line: string): boolean {
   return (
-    l.startsWith("```") ||
-    l.startsWith("# ") ||
-    l.startsWith("## ") ||
-    l.startsWith("### ") ||
-    l.startsWith("> ") ||
-    /^- /.test(l) ||
-    /^\d+\. /.test(l) ||
-    /^(---|\*\*\*|___)\s*$/.test(l)
+    line.startsWith("```") ||
+    line.startsWith("# ") ||
+    line.startsWith("## ") ||
+    line.startsWith("### ") ||
+    line.startsWith("> ") ||
+    /^- /.test(line) ||
+    /^\d+\. /.test(line) ||
+    /^(---|\*\*\*|___)\s*$/.test(line)
   );
 }
 
-export function parseBlocks(md: string): Block[] {
-  const lines = md.split("\n");
+export function parseBlocks(markdown: string): Block[] {
+  const lines = markdown.split("\n");
   const blocks: Block[] = [];
-  let i = 0;
-  while (i < lines.length) {
-    const l = lines[i]!;
-    if (l.trim() === "") {
-      i++;
+  let lineIndex = 0;
+  while (lineIndex < lines.length) {
+    const line = lines[lineIndex]!;
+    if (line.trim() === "") {
+      lineIndex++;
       continue;
     }
-    if (l.startsWith("```")) {
-      const start = i;
-      const lang = l.slice(3).trim() || undefined;
-      i++;
+    if (line.startsWith("```")) {
+      const start = lineIndex;
+      const lang = line.slice(3).trim() || undefined;
+      lineIndex++;
       const body: string[] = [];
-      while (i < lines.length && !lines[i]!.startsWith("```")) {
-        body.push(lines[i]!);
-        i++;
+      while (lineIndex < lines.length && !lines[lineIndex]!.startsWith("```")) {
+        body.push(lines[lineIndex]!);
+        lineIndex++;
       }
-      const end = Math.min(i, lines.length - 1);
-      i++;
+      const end = Math.min(lineIndex, lines.length - 1);
+      lineIndex++;
       blocks.push({ kind: "code", text: body.join("\n"), lang, lineStart: start, lineEnd: end });
-    } else if (l.startsWith("### ")) {
-      blocks.push({ kind: "h3", text: l.slice(4), lineStart: i, lineEnd: i });
-      i++;
-    } else if (l.startsWith("## ")) {
-      blocks.push({ kind: "h2", text: l.slice(3), lineStart: i, lineEnd: i });
-      i++;
-    } else if (l.startsWith("# ")) {
-      blocks.push({ kind: "h1", text: l.slice(2), lineStart: i, lineEnd: i });
-      i++;
-    } else if (/^(---|\*\*\*|___)\s*$/.test(l)) {
-      blocks.push({ kind: "hr", text: "", lineStart: i, lineEnd: i });
-      i++;
-    } else if (l.startsWith("> ")) {
-      const start = i;
+    } else if (line.startsWith("### ")) {
+      blocks.push({ kind: "h3", text: line.slice(4), lineStart: lineIndex, lineEnd: lineIndex });
+      lineIndex++;
+    } else if (line.startsWith("## ")) {
+      blocks.push({ kind: "h2", text: line.slice(3), lineStart: lineIndex, lineEnd: lineIndex });
+      lineIndex++;
+    } else if (line.startsWith("# ")) {
+      blocks.push({ kind: "h1", text: line.slice(2), lineStart: lineIndex, lineEnd: lineIndex });
+      lineIndex++;
+    } else if (/^(---|\*\*\*|___)\s*$/.test(line)) {
+      blocks.push({ kind: "hr", text: "", lineStart: lineIndex, lineEnd: lineIndex });
+      lineIndex++;
+    } else if (line.startsWith("> ")) {
+      const start = lineIndex;
       const body: string[] = [];
-      while (i < lines.length && lines[i]!.startsWith("> ")) {
-        body.push(lines[i]!.slice(2));
-        i++;
+      while (lineIndex < lines.length && lines[lineIndex]!.startsWith("> ")) {
+        body.push(lines[lineIndex]!.slice(2));
+        lineIndex++;
       }
-      blocks.push({ kind: "quote", text: body.join("\n"), lineStart: start, lineEnd: i - 1 });
-    } else if (/^- /.test(l)) {
-      blocks.push({ kind: "li", text: l.slice(2), lineStart: i, lineEnd: i });
-      i++;
-    } else if (/^\d+\. /.test(l)) {
-      blocks.push({ kind: "oli", text: l.replace(/^\d+\. /, ""), lineStart: i, lineEnd: i });
-      i++;
+      blocks.push({ kind: "quote", text: body.join("\n"), lineStart: start, lineEnd: lineIndex - 1 });
+    } else if (/^- /.test(line)) {
+      blocks.push({ kind: "li", text: line.slice(2), lineStart: lineIndex, lineEnd: lineIndex });
+      lineIndex++;
+    } else if (/^\d+\. /.test(line)) {
+      blocks.push({ kind: "oli", text: line.replace(/^\d+\. /, ""), lineStart: lineIndex, lineEnd: lineIndex });
+      lineIndex++;
     } else {
-      const start = i;
+      const start = lineIndex;
       const body: string[] = [];
-      while (i < lines.length && lines[i]!.trim() !== "" && !isMarkerLine(lines[i]!)) {
-        body.push(lines[i]!);
-        i++;
+      while (lineIndex < lines.length && lines[lineIndex]!.trim() !== "" && !isMarkerLine(lines[lineIndex]!)) {
+        body.push(lines[lineIndex]!);
+        lineIndex++;
       }
-      blocks.push({ kind: "p", text: body.join("\n"), lineStart: start, lineEnd: i - 1 });
+      blocks.push({ kind: "p", text: body.join("\n"), lineStart: start, lineEnd: lineIndex - 1 });
     }
   }
   return blocks;
 }
 
 /** Serialize one block back to its markdown chunk. */
-export function blockToMd(b: Block, ordinal = 1): string {
-  switch (b.kind) {
+export function blockToMd(block: Block, ordinal = 1): string {
+  switch (block.kind) {
     case "h1":
-      return "# " + b.text;
+      return "# " + block.text;
     case "h2":
-      return "## " + b.text;
+      return "## " + block.text;
     case "h3":
-      return "### " + b.text;
+      return "### " + block.text;
     case "li":
-      return "- " + b.text;
+      return "- " + block.text;
     case "oli":
-      return `${ordinal}. ` + b.text;
+      return `${ordinal}. ` + block.text;
     case "quote":
-      return b.text
+      return block.text
         .split("\n")
-        .map((l) => "> " + l)
+        .map((line) => "> " + line)
         .join("\n");
     case "code":
-      return "```" + (b.lang ?? "") + "\n" + b.text + "\n```";
+      return "```" + (block.lang ?? "") + "\n" + block.text + "\n```";
     case "hr":
       return "---";
     default:
-      return b.text;
+      return block.text;
   }
 }
 
 /** The section (nearest preceding heading) a block belongs to. */
 export function sectionOf(blocks: Block[], index: number): string {
-  let sec = "";
-  for (let i = 0; i <= index && i < blocks.length; i++) {
-    const b = blocks[i]!;
-    if (b.kind === "h1" || b.kind === "h2" || b.kind === "h3") sec = b.text;
+  let sectionTitle = "";
+  for (let blockIndex = 0; blockIndex <= index && blockIndex < blocks.length; blockIndex++) {
+    const block = blocks[blockIndex]!;
+    if (block.kind === "h1" || block.kind === "h2" || block.kind === "h3") sectionTitle = block.text;
   }
-  return sec;
+  return sectionTitle;
 }

package/src/types.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from "bun:test";
+import { newAnnotationId, verdictAllows } from "./types";
+
+describe("verdictAllows", () => {
+  test("only approve maps to allow", () => {
+    expect(verdictAllows("approve")).toBe(true);
+    expect(verdictAllows("comment")).toBe(false);
+    expect(verdictAllows("request_changes")).toBe(false);
+  });
+});
+
+describe("newAnnotationId", () => {
+  test("unique by construction within a process, even on one millisecond", () => {
+    const ids = new Set(Array.from({ length: 10_000 }, () => newAnnotationId()));
+    expect(ids.size).toBe(10_000);
+    for (const id of ids) expect(id).toMatch(/^a_[0-9a-z]+_[0-9a-z]+$/);
+  });
+});

package/src/types.ts

@@ -1,7 +1,7 @@
 /**
- * The ReviewSession primitive (map #2, #9). Everything in cueloop renders,
- * annotates, or resolves this one noun. This module is pure data shapes -
- * no IO, no dependencies.
+ * The ReviewSession primitive. Everything in cueloop renders, annotates, or
+ * resolves this one noun. This module is pure data shapes - no IO, no
+ * dependencies.
  */
 
 export const SCHEMA_VERSION = "1";
@@ -23,6 +23,8 @@ export interface ArtifactMeta {
   planPath?: string;
   /** Pull request reference the diff came from, so the verdict can be posted back. */
   pr?: string;
+  /** herdr pane the submitting agent runs in - the review returns focus there. */
+  herdrPane?: string;
   title?: string;
 }
 
@@ -49,9 +51,19 @@ export interface Anchor {
   end?: number;
 }
 
-/** The annotation kind set is open (map #2); these are the built-ins. */
+/** The annotation kind set is open; these are the built-ins. */
 export type AnnotationKind = "comment" | "suggestion" | (string & {});
 
+/**
+ * Agent-authored context, not reviewer feedback: the guided walk's per-file
+ * notes (kind "note", anchored by the file path). Excluded from the feedback
+ * document and the reviewer's pending counts - an agent must never receive
+ * its own notes back as items to address.
+ */
+export function isAgentNote(annotation: Pick<Annotation, "kind">): boolean {
+  return annotation.kind === "note";
+}
+
 export interface Annotation {
   id: string;
   kind: AnnotationKind;
@@ -95,6 +107,12 @@ export interface ReviewSession {
    * Undefined = no direct edits.
    */
   workingCopy?: string;
+  /**
+   * File paths the reviewer marked viewed during the guided walk (diff
+   * sessions). Persisting with the session means a resumed review keeps its
+   * progress. Undefined = the walk never started.
+   */
+  viewedPaths?: string[];
   verdict: Verdict | null;
   status: SessionStatus;
   createdAt: string;
@@ -104,3 +122,13 @@ export interface ReviewSession {
 export function verdictAllows(kind: VerdictKind): boolean {
   return kind === "approve";
 }
+
+/**
+ * Annotation ids are minted client-side. The counter makes ids unique within
+ * a process by construction; the random suffix separates concurrent
+ * annotators in different processes on the same millisecond.
+ */
+let annotationSeq = 0;
+export function newAnnotationId(): string {
+  return `a_${Date.now().toString(36)}${(annotationSeq++).toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+}

package/src/working-copy.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, test } from "bun:test";
+import { cutBlock, restoreBlock, restoreLine, sourceChunk } from "./working-copy";
+import { parseBlocks, type Block } from "./markdown";
+
+const BASE = `# Plan
+
+## Context
+
+A paragraph that
+spans two lines.
+
+- first item
+- second item
+
+\`\`\`ts
+const x = 1;
+const y = 2;
+\`\`\`
+`;
+
+function block(markdown: string, text: string): Block {
+  return parseBlocks(markdown).find((block) => block.text.includes(text))!;
+}
+
+describe("sourceChunk", () => {
+  test("returns the exact source lines a block occupies", () => {
+    expect(sourceChunk(BASE, block(BASE, "first item"))).toBe("- first item");
+    expect(sourceChunk(BASE, block(BASE, "spans two lines"))).toBe("A paragraph that\nspans two lines.");
+  });
+
+  test("code block chunk includes both fence lines", () => {
+    expect(sourceChunk(BASE, block(BASE, "const x"))).toBe("```ts\nconst x = 1;\nconst y = 2;\n```");
+  });
+});
+
+describe("cutBlock", () => {
+  test("removes the block lines and the blank line before it", () => {
+    const cut = cutBlock(BASE, block(BASE, "spans two lines"));
+    expect(cut).not.toContain("spans two lines");
+    expect(cut).toContain("## Context\n\n- first item");
+  });
+
+  test("cut at the start of the document leaves the leading blank line", () => {
+    const cut = cutBlock(BASE, block(BASE, "Plan"));
+    expect(cut).not.toContain("# Plan");
+    expect(cut.trimStart().startsWith("## Context")).toBe(true);
+  });
+
+  test("cut at the end of the document keeps the rest intact", () => {
+    const cut = cutBlock(BASE, block(BASE, "const x"));
+    expect(cut).not.toContain("const x");
+    expect(cut).toContain("- second item");
+  });
+});
+
+describe("restoreBlock", () => {
+  test("restoring the only cut returns undefined - back to pristine", () => {
+    const listItem = block(BASE, "second item");
+    const cut = cutBlock(BASE, listItem);
+    // the cut block re-enters before the code fence, the next surviving block
+    const next = parseBlocks(cut).find((candidate) => candidate.kind === "code");
+    const restored = restoreBlock(BASE, cut, listItem, restoreLine(next, cut.split("\n").length));
+    expect(restored).toBeUndefined();
+  });
+
+  test("restore after another edit returns the merged working copy", () => {
+    const listItem = block(BASE, "second item");
+    const edited = cutBlock(BASE, listItem).replace("first item", "first item reworded");
+    const next = parseBlocks(edited).find((candidate) => candidate.kind === "code");
+    const restored = restoreBlock(BASE, edited, listItem, restoreLine(next, edited.split("\n").length));
+    expect(restored).toContain("- second item");
+    expect(restored).toContain("first item reworded");
+  });
+
+  test("restore at the end of the document (no next block)", () => {
+    const code = block(BASE, "const x");
+    const cut = cutBlock(BASE, code);
+    const restored = restoreBlock(BASE, cut, code, restoreLine(undefined, cut.split("\n").length));
+    expect(restored).toBeUndefined();
+  });
+
+  test("restore a multi-line block round-trips to pristine", () => {
+    const paragraph = block(BASE, "spans two lines");
+    const cut = cutBlock(BASE, paragraph);
+    const next = parseBlocks(cut).find((block) => block.text === "first item");
+    const restored = restoreBlock(BASE, cut, paragraph, restoreLine(next, cut.split("\n").length));
+    expect(restored).toBeUndefined();
+  });
+
+  test("signature rule ignores blank-line layout but not text changes", () => {
+    const listItem = block(BASE, "second item");
+    const cut = cutBlock(BASE, listItem);
+    const next = parseBlocks(cut).find((candidate) => candidate.kind === "code");
+    const line = restoreLine(next, cut.split("\n").length);
+    // extra blank lines elsewhere do not block pristine detection
+    expect(restoreBlock(BASE, cut.replace("## Context", "## Context\n"), listItem, line)).toBeUndefined();
+    // a real text change keeps the working copy alive
+    const changed = restoreBlock(BASE, cut.replace("first", "1st"), listItem, line);
+    expect(changed).toContain("1st item");
+  });
+});
+
+describe("restoreLine", () => {
+  test("next surviving block's start, or the line count at the end", () => {
+    const listItem = block(BASE, "first item");
+    expect(restoreLine(listItem, 99)).toBe(listItem.lineStart);
+    expect(restoreLine(undefined, 99)).toBe(99);
+  });
+});