@gavin-hu/my-pi-agent 0.11.4 → 0.13.0

package/extensions/plan/steps.ts

@@ -5,7 +5,9 @@
  * guided to write, the top-level steps that seed `todo` and drive the review
  * gauge, the heading sections the review screen navigates, and the in-place
  * checkbox edit that keeps the file current after approval. All of it is pure so
- * the tools, the store, and the renderer agree on one parser.
+ * the tools, the store, and the renderer agree on one parser. The review's
+ * section comparison lives in `plan-text.ts`, which owns the text normalization
+ * the digest is computed over.
  *
  * Only top-level list items become steps: nested sub-bullets are notes, and the
  * shallowest list level is treated as the plan. When the plan has a `Steps`
@@ -28,7 +30,7 @@ export const PLAN_OUTLINE = [
 	"# <Title>",
 	"",
 	"## Goal",
-	"What this change achieves, in one or two sentences.",
+	"What this change achieves, and what it deliberately does not.",
 	"",
 	"## Context",
 	"The relevant code, constraints, and prior art.",
@@ -37,8 +39,8 @@ export const PLAN_OUTLINE = [
 	"The chosen approach and why; alternatives considered.",
 	"",
 	"## Steps",
-	"- [ ] First concrete step",
-	"- [ ] Next step",
+	"- [ ] Add `parseConfig` in `src/config.ts`, with a test for a missing key",
+	"- [ ] Wire it into `load()` and document the failure in the README",
 	"",
 	"## Risks",
 	"What could go wrong and how it is mitigated.",
@@ -61,6 +63,10 @@ export interface PlanSection {
 	title: string;
 	/** The section's markdown, including its heading line. */
 	text: string;
+	/** 0-based source line of the section's heading (0 for the preamble). */
+	line: number;
+	/** Heading level, or 0 for the preamble before the first heading. */
+	level: number;
 }
 
 /** A top-level list item located in the source. */
@@ -78,10 +84,19 @@ interface PlanListItem {
 /** A top-level numbered or bulleted list item, capturing its parts. */
 const LIST_ITEM = /^([ \t]*)((?:\d+[.)]|[-*+])\s+)(.*\S)\s*$/;
 const CHECKBOX = /^\[([ xX])\]\s*(.*)$/;
-/** A markdown heading outside a fence, capturing its level and text. */
-const HEADING = /^ {0,3}(#{1,6})\s+(.*?)\s*#*\s*$/;
-/** A markdown code-fence opener or closer (backticks or tildes). */
-const FENCE = /^\s{0,3}(`{3,}|~{3,})/;
+/**
+ * A markdown heading outside a fence, capturing its level and text: up to three
+ * leading spaces, a space after the hashes, and a closing hash run only when a
+ * space separates it. Shared with `blocks.ts`, so the section split and the
+ * browser outline read a heading line the same way, and `## C#` keeps its title.
+ */
+export const HEADING = /^ {0,3}(#{1,6})\s+(.*?)(?:\s+#+)?\s*$/;
+/**
+ * A markdown code-fence opener or closer (backticks or tildes). Shared with
+ * `blocks.ts`: a tab-indented fence is prose for both parsers, never code for
+ * one and prose for the other.
+ */
+export const FENCE = /^ {0,3}(`{3,}|~{3,})/;
 const DONE_MARKER = /\[DONE:\d+\]/gi;
 
 /**
@@ -211,6 +226,38 @@ function elide(content: string): string {
 	return content.length > MAX_STEP_LENGTH ? `${content.slice(0, MAX_STEP_LENGTH - 1).trimEnd()}…` : content;
 }
 
+/** A list marker with an optional checkbox, at any indent. */
+const LIST_PREFIX = /^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s*)?/;
+
+/**
+ * The plan's `Verification` section as one trailing checklist item, or
+ * `undefined` when the plan has none.
+ *
+ * The section is prose ("commands and checks"), and a todo item is one line, so
+ * the lines are stripped of list markers and inline emphasis and joined with
+ * `; `, prefixed with `Verify:` and elided like a long step. The item is
+ * deliberately *not* a plan step: it is not in the `Steps` section, so it must
+ * not count against the step cap or appear in `set_plan_steps` numbering.
+ *
+ * A plan with no `Steps` heading feeds its shallowest list as steps (the older
+ * rule), so that list already covers the verification bullets; appending a
+ * summary of them would duplicate them, and there is nothing to carry.
+ */
+export function verificationItem(plan: string): PlanStep | undefined {
+	if (stepsSection(plan) === undefined) return undefined;
+	const section = extractPlanSections(plan).find(
+		(candidate) => candidate.level > 0 && candidate.title.toLowerCase() === "verification",
+	);
+	if (!section) return undefined;
+	const items = section.text
+		.split("\n")
+		.slice(1)
+		.map((line) => plainText(line.replace(LIST_PREFIX, "")))
+		.filter(Boolean);
+	if (items.length === 0) return undefined;
+	return { content: elide(`Verify: ${items.join("; ")}`), status: "pending" };
+}
+
 /** Top-level steps from a plan, in order. */
 export function extractPlanSteps(plan: string): PlanStep[] {
 	return topLevelItems(plan).map((item) => ({ content: elide(item.step.content), status: item.step.status }));
@@ -281,32 +328,6 @@ export function setStepStatuses(plan: string, updates: StepUpdate[]): string | u
 	return lines.join("\n");
 }
 
-/**
- * Titles (normalized) whose section text differs between two plan revisions, or
- * that are new in `current`. Revision snapshots are the caller's to provide;
- * strip stored feedback first so a review comment does not look like an edit.
- * Duplicate headings are compared by occurrence, and a changed title marks every
- * section with that title — plans following the canonical outline have none.
- */
-export function changedSections(previous: string, current: string): Set<string> {
-	const before = new Map<string, string[]>();
-	for (const section of extractPlanSections(previous)) {
-		const texts = before.get(section.title);
-		if (texts) texts.push(section.text.trim());
-		else before.set(section.title, [section.text.trim()]);
-	}
-
-	const seen = new Map<string, number>();
-	const changed = new Set<string>();
-	for (const section of extractPlanSections(current)) {
-		const index = seen.get(section.title) ?? 0;
-		seen.set(section.title, index + 1);
-		const prior = before.get(section.title)?.[index];
-		if (prior === undefined || prior !== section.text.trim()) changed.add(section.title);
-	}
-	return changed;
-}
-
 /**
  * Sections of a plan, split at heading lines outside code fences. The content
  * before the first heading is a section titled `""`. Pi's `Markdown` renderer
@@ -323,7 +344,7 @@ export function extractPlanSections(plan: string): PlanSection[] {
 		current = undefined;
 	};
 
-	for (const line of plan.split("\n")) {
+	plan.split("\n").forEach((line, index) => {
 		const fenceMatch = line.match(FENCE);
 		if (fenceMatch) {
 			if (fence === undefined) fence = fenceMatch[1][0];
@@ -332,13 +353,13 @@ export function extractPlanSections(plan: string): PlanSection[] {
 			const heading = line.match(HEADING);
 			if (heading) {
 				flush();
-				current = { title: plainText(heading[2]), text: line };
-				continue;
+				current = { title: plainText(heading[2]), text: line, line: index, level: heading[1].length };
+				return;
 			}
 		}
-		if (current === undefined) current = { title: "", text: line };
+		if (current === undefined) current = { title: "", text: line, line: 0, level: 0 };
 		else current.text += `\n${line}`;
-	}
+	});
 
 	flush();
 	return sections;

package/extensions/plan/todos.ts

@@ -3,25 +3,15 @@
  *
  * `todo` is whole-list replacement, so seeding an approved plan straight over
  * the list would discard whatever the user was already tracking. This module
- * reads the last `todo` result from the session branch — the published state
- * channel, replayed the way the todo extension itself reconstructs it, with no
- * import from that extension — and merges the plan's steps into it: existing
- * items keep their place and status, a step whose text is already present is
- * skipped, and the tool's item cap is respected without dropping anything the
- * user had.
+ * merges the plan's steps into the list `lib/todo-state.ts` replays from the
+ * session branch: existing items keep their place and status, a step whose text
+ * is already present is skipped, and the tool's item cap is respected without
+ * dropping anything the user had.
  */
 
-import { TODO_TOOL } from "../../lib/tool-names.ts";
+import type { ExistingTodo } from "../../lib/todo-state.ts";
 import type { PlanStep } from "./steps.ts";
 
-/** One item in the existing todo list, as the todo tool stores it. */
-export interface ExistingTodo {
-	content: string;
-	status: "pending" | "in_progress" | "completed";
-	/** Present-continuous label the todo tool requires for an in-progress item. */
-	activeForm?: string;
-}
-
 /** The merged list plus the counts the approval message reports. */
 export interface TodoMerge {
 	todos: ExistingTodo[];
@@ -33,54 +23,16 @@ export interface TodoMerge {
 	kept: number;
 	/** Plan steps left out because the list reached its cap. */
 	deferred: number;
-}
-
-/** Minimal shape of a session entry, used for runtime narrowing. */
-interface BranchEntryLike {
-	type?: string;
-	message?: {
-		role?: string;
-		toolName?: string;
-		details?: unknown;
-	};
+	/**
+	 * What happened to the trailing checklist item (the plan's verification
+	 * summary): appended after the steps, already present, or left out by the cap.
+	 */
+	trailing?: "added" | "skipped" | "deferred";
 }
 
 /** Fallback list cap when the registered todo tool does not advertise one. */
 export const DEFAULT_TODO_MAX = 50;
 
-function isStatus(value: unknown): value is ExistingTodo["status"] {
-	return value === "pending" || value === "in_progress" || value === "completed";
-}
-
-/**
- * The last valid todo list written on the branch, or an empty list. A rejected
- * call carries the unchanged list and is not a state write, so it is skipped;
- * an entry that does not re-validate is ignored rather than wiping a good list.
- */
-export function lastTodos(entries: Iterable<unknown>): ExistingTodo[] {
-	let todos: ExistingTodo[] = [];
-	for (const raw of entries) {
-		const entry = raw as BranchEntryLike;
-		if (entry?.type !== "message") continue;
-		const message = entry.message;
-		if (message?.role !== "toolResult" || message.toolName !== TODO_TOOL) continue;
-		const details = message.details as { todos?: unknown; error?: unknown } | undefined;
-		if (!details || details.error) continue;
-		if (!Array.isArray(details.todos)) continue;
-		todos = details.todos.flatMap((item): ExistingTodo[] => {
-			if (typeof item !== "object" || item === null) return [];
-			const value = item as { content?: unknown; status?: unknown; activeForm?: unknown };
-			if (typeof value.content !== "string" || !isStatus(value.status)) return [];
-			const content = value.content.trim();
-			if (!content) return [];
-			const activeForm =
-				typeof value.activeForm === "string" && value.activeForm.trim() ? value.activeForm.trim() : undefined;
-			return [activeForm ? { content, status: value.status, activeForm } : { content, status: value.status }];
-		});
-	}
-	return todos;
-}
-
 /** Case- and whitespace-insensitive key for recognizing a repeated item. */
 function contentKey(content: string): string {
 	return content.trim().replace(/\s+/g, " ").toLowerCase();
@@ -91,8 +43,12 @@ function contentKey(content: string): string {
  * keep their status, a legacy in-progress item without an `activeForm` gets its
  * content as one so the todo tool accepts it, and the appended steps stop at
  * `max` items — the rest are counted as deferred, never dropped.
+ *
+ * `trailing` is the plan's verification summary: it is appended after every step
+ * (still subject to the same duplicate and cap rules) but is not counted as a
+ * step, because it is not one.
  */
-export function mergeTodos(existing: ExistingTodo[], steps: PlanStep[], max: number): TodoMerge {
+export function mergeTodos(existing: ExistingTodo[], steps: PlanStep[], max: number, trailing?: PlanStep): TodoMerge {
 	const limit = Number.isInteger(max) && max > 0 ? max : DEFAULT_TODO_MAX;
 	const todos: ExistingTodo[] = existing.map((todo) =>
 		todo.status === "in_progress" && !todo.activeForm ? { ...todo, activeForm: todo.content } : todo,
@@ -116,5 +72,18 @@ export function mergeTodos(existing: ExistingTodo[], steps: PlanStep[], max: num
 		todos.push({ content: step.content, status: step.status });
 		added += 1;
 	}
-	return { todos, added, skipped, kept: existing.length, deferred };
+
+	let trailingOutcome: TodoMerge["trailing"];
+	if (trailing) {
+		const key = contentKey(trailing.content);
+		if (!key) trailingOutcome = undefined;
+		else if (seen.has(key)) trailingOutcome = "skipped";
+		else if (todos.length >= limit) trailingOutcome = "deferred";
+		else {
+			todos.push({ content: trailing.content, status: trailing.status });
+			trailingOutcome = "added";
+		}
+	}
+
+	return { todos, added, skipped, kept: existing.length, deferred, trailing: trailingOutcome };
 }