pi-anchorloop 2.4.1 → 2.7.0

package/pi/support/book.ts

@@ -7,8 +7,8 @@
 
 import { createHash, randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
-import { closeSync, constants, existsSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, rmdirSync, statSync, unlinkSync, writeSync } from "node:fs";
-import { homedir } from "node:os";
+import { closeSync, constants, copyFileSync, existsSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, unlinkSync, utimesSync, writeSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 
 export const KINDS = ["quick", "inline", "reviewed", "durable"] as const;
@@ -541,14 +541,85 @@ export function validFollowup(followup: unknown): boolean {
 
 // --- git -----------------------------------------------------------------------------------------
 
-function git(cwd: string, args: string[]): string | undefined {
+function git(cwd: string, args: string[], env?: NodeJS.ProcessEnv): string | undefined {
 	try {
-		return execFileSync("git", ["-C", cwd, ...args], { encoding: "utf-8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+		return execFileSync("git", ["-C", cwd, ...args], { encoding: "utf-8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"], env: env ?? process.env }).trim();
 	} catch {
 		return undefined;
 	}
 }
 
+/**
+ * The tree a commit of everything in `repo`'s working state would have (tracked and untracked, ignored files and `scratch/`
+ * left out), built in a copy of the index so the repo's own index is untouched; undefined when git cannot build it.
+ */
+export function workingTree(repo: string): string | undefined {
+	const index = git(repo, ["rev-parse", "--path-format=absolute", "--git-path", "index"]);
+	if (!index) return undefined;
+	const dir = mkdtempSync(join(tmpdir(), "anchorloop-tree-"));
+	try {
+		const env = { ...process.env, GIT_INDEX_FILE: join(dir, "index") };
+		if (existsSync(index)) {
+			// The copy keeps the index's mtime: git trusts an entry's stat only when it is older than the index, and a file
+			// changed in the second the index was written but kept its size would otherwise be taken as unchanged.
+			copyFileSync(index, env.GIT_INDEX_FILE);
+			const { atime, mtime } = statSync(index);
+			utimesSync(env.GIT_INDEX_FILE, atime, mtime);
+		}
+		if (git(repo, ["add", "-A", "--", ".", ":(exclude)scratch"], env) === undefined) return undefined;
+		return git(repo, ["write-tree"], env);
+	} finally {
+		rmSync(dir, { recursive: true, force: true });
+	}
+}
+
+/** The working-state tree of each repo in `repos`, leaving out a repo git cannot build one for. */
+export function workingTrees(repos: Iterable<string>): string[] {
+	return [...new Set(repos)].map(workingTree).filter((tree): tree is string => tree !== undefined);
+}
+
+const CD_STEP = /^cd\s+("[^"]*"|'[^']*'|\S+)\s*(?:&&|;)\s*/;
+
+/**
+ * The command without the leading `cd <dir> &&` (or `;`) steps whose directory is one of `roots`, the roots of the loop's
+ * repos, so one anchor run from two checkouts reads the same; a `cd` into a subdirectory stays, since it runs other tests.
+ */
+function anchorBody(command: string, roots: string[], cwd: string): string {
+	let rest = command.trim();
+	for (let step = CD_STEP.exec(rest); step; step = CD_STEP.exec(rest)) {
+		const target = step[1].replace(/^(["'])(.*)\1$/, "$2").replace(/^~(?=\/|$)/, homedir());
+		if (!roots.includes(real(resolve(cwd, target)))) break;
+		rest = rest.slice(step[0].length);
+	}
+	return rest.replace(/\s+/g, " ");
+}
+
+/**
+ * The linked child whose latest run of `anchor` passed on exactly the state the coordinator holds: the trees that run
+ * recorded are the coordinator's `trees`, no more and no fewer, so a repo only one side worked in is never taken as checked.
+ * `roots` and `cwd` are the coordinator's repo roots and directory. Only a pi-herdr-agents child is linked
+ * (`PI_SUBAGENT_ID`); pi itself has no subagents.
+ */
+export function adoptableRun(entries: Entry[], anchor: string, trees: string[], roots: string[], cwd: string, env: NodeJS.ProcessEnv = process.env): { name: string; run: Entry } | undefined {
+	const body = anchorBody(anchor, roots, cwd);
+	const held = new Set(trees);
+	for (const id of childIds(entries)) {
+		const runs = findChildBooks(id, env).flatMap(({ book }) => {
+			const home = String(book.header.cwd ?? "");
+			const here = home ? repoRootOf(join(home, "_")) : undefined;
+			const childRoots = [...bases(book.entries).map((base) => base.repo), ...(here ? [here] : [])];
+			return book.entries.filter((entry) => entry.stage === "check" && typeof entry.command === "string" && anchorBody(entry.command, childRoots, home) === body);
+		});
+		const run = runs.sort((a, b) => a.ts.localeCompare(b.ts)).at(-1);
+		const checked = new Set(Array.isArray(run?.trees) ? (run.trees as unknown[]).map(String) : []);
+		if (run && run.exit === 0 && checked.size === held.size && [...checked].every((tree) => held.has(tree))) {
+			const link = entries.find((entry) => entry.stage === "link" && entry.child === id);
+			return { name: String(link?.name ?? id), run };
+		}
+	}
+	return undefined;
+}
+
 function existingDir(path: string): string {
 	let dir = path;
 	while (!existsSync(dir) && dirname(dir) !== dir) dir = dirname(dir);

package/pi/support/phases.ts

@@ -171,13 +171,10 @@ export function unansweredReach(entries: Entry[], reach: Reach | undefined): str
 
 /** The one line that asks an unreviewed loop to re-classify; an undeclared loop is asked to declare its kind. */
 export function reachLine(reach: Reach, kind: string | undefined): string {
-	const files = `${reach.source.length} source file${reach.source.length === 1 ? "" : "s"}`;
-	const modules = `${reach.modules.length} module${reach.modules.length === 1 ? "" : "s"} (${reach.modules.slice(0, 4).join(", ")}${reach.modules.length > 4 ? ", …" : ""})`;
-	const told = reach.behavior.length ? ` and changes ${reach.behavior.slice(0, 3).join(", ")}${reach.behavior.length > 3 ? ", …" : ""}` : "";
-	const ask = kind
-		? `call \`kind\` with \`reason\`: upgrade to reviewed, or say why ${kind} still fits`
-		: "declare `kind` with `intent` and `reason`: reviewed when it reaches past its files, or inline and why it still fits";
-	return `the change reaches ${files} across ${modules}${told}; ${ask}`;
+	const modules = reach.modules.length ? ` / ${reach.modules.length} module${reach.modules.length === 1 ? "" : "s"} (${reach.modules.slice(0, 4).join(", ")}${reach.modules.length > 4 ? ", …" : ""})` : "";
+	const told = reach.behavior.length ? ` / ${reach.behavior.slice(0, 3).join(", ")}${reach.behavior.length > 3 ? ", …" : ""}` : "";
+	const ask = kind ? `kind with reason: reviewed, or why ${kind} fits` : "declare kind with intent and reason: reviewed, or why inline fits";
+	return `reach ${reach.source.length} file${reach.source.length === 1 ? "" : "s"}${modules}${told}; ${ask}`;
 }
 
 // --- evidence ------------------------------------------------------------------------------------
@@ -284,7 +281,7 @@ function evaluate(name: string, ctx: Ctx): Status {
 		}
 		case "anchor": {
 			const index = lastWhere(entries, from, (entry) => entry.stage === "anchor");
-			return index >= 0 ? done(name, String(entries[index].check ?? "")) : missing(name, "a `Reality anchor:` line, or `anchor` on the kind call");
+			return index >= 0 ? done(name, String(entries[index].check ?? "")) : missing(name, "a `Reality anchor:` line, `metadata.anchor` on the first todo, or `anchor` on the kind call");
 		}
 		case "act":
 			return lastWhere(entries, from, (entry) => entry.stage === "edit") >= 0 ? done(name) : missing(name, "a change to the code");
@@ -362,11 +359,9 @@ export function incompleteBefore(phases: Phases, entering: string): Status[] {
 	return phases.statuses.filter((status, index) => index < at && status.state === "missing");
 }
 
-/** One line: the phase entered, what is missing before it, and the skip escape. */
+/** One line: the phases still missing before the one entered. */
 export function jumpLine(entering: string, missingBefore: Status[]): string {
-	const list = missingBefore.map((status) => `${status.name} (${status.note})`).join("; ");
-	const skip = missingBefore[0]?.name ?? "<phase>";
-	return `anchorloop: ${entering} comes before ${list}; skip with \`anchorloop_stage skip ${skip} <reason>\`.`;
+	return `anchorloop: before ${entering}, still missing: ${missingBefore.map((status) => `${status.name} (${status.note})`).join("; ")}.`;
 }
 
 /** The phase line `read` and the close summary show. */

package/pi/support/snapshot.ts

@@ -16,6 +16,7 @@ import {
 	stagesDone,
 	TASK_LEGEND,
 	taskLines,
+	validFollowup,
 	verifyAfterLastAct,
 } from "./book.ts";
 import { computePhases } from "./phases.ts";
@@ -29,12 +30,30 @@ export type Snapshot = {
 	current: string;
 	/** A review recorded after the last change with no blocking finding on it. */
 	reviewClear: boolean;
+	/** Open todos that no valid `metadata.followup` settles yet. */
+	unsettled: { id: number; subject: string }[];
 };
 
+const LISTED_TODOS = 3;
+const SUBJECT_LIMIT = 60;
+
+const clipped = (subject: string, limit: number): string => {
+	const flat = subject.replace(/\s+/g, " ").trim();
+	return flat.length <= limit ? flat : `${flat.slice(0, limit - 1)}…`;
+};
+
+/** The first few todos as `#id subject` (subject cut to 60 characters) joined by `; `, then `+N more`. */
+export function listTodos(todos: { id: number; subject: string }[], limit = LISTED_TODOS): string {
+	const lines = todos.slice(0, limit).map((task) => `#${task.id} ${clipped(task.subject, SUBJECT_LIMIT)}`);
+	return [...lines, ...(todos.length > limit ? [`+${todos.length - limit} more`] : [])].join("; ");
+}
+
 export function snapshot(book: Book, ctx: { cwd: string; sessionManager: { getBranch(): unknown[] } }): Snapshot {
 	const { entries } = book;
 	const todos = replayTodos(ctx.sessionManager.getBranch());
-	const open = todos.filter(isOpenTask).length;
+	const openTasks = todos.filter(isOpenTask);
+	const unsettled = openTasks.filter((task) => !validFollowup(task.metadata?.followup));
+	const settled = openTasks.length - unsettled.length;
 	const phases = computePhases(book, { cwd: ctx.cwd, todos });
 	const check = verifyAfterLastAct(entries);
 	const verify = [
@@ -56,7 +75,7 @@ export function snapshot(book: Book, ctx: { cwd: string; sessionManager: { getBr
 			diff: diffText(diffAgainstBases(entries)),
 			phase: `current: ${phases.current}; next: ${phases.next}${phases.missing ? `; missing: ${phases.missing}` : ""}${phases.skipped.length ? `; skipped: ${phases.skipped.join(", ")}` : ""}`.slice(0, 600),
 			verify: verify.slice(0, 1200),
-			todos: `${open} open of ${todos.length}`,
+			todos: `${openTasks.length} open of ${todos.length}${unsettled.length ? `: ${listTodos(unsettled, 5)}` : ""}${settled ? ` (${settled} with a followup)` : ""}`.slice(0, 700),
 			tasks: [`legend: ${TASK_LEGEND}`, ...taskLines(entries, todos, ctx.cwd)].join("\n").slice(0, 1500),
 			friction: (friction.join("\n") || "none").slice(0, 800),
 		},
@@ -64,5 +83,6 @@ export function snapshot(book: Book, ctx: { cwd: string; sessionManager: { getBr
 		missing: phases.missing,
 		current: phases.current,
 		reviewClear: reviewClearAfterLastAct(entries),
+		unsettled: unsettled.map((task) => ({ id: task.id, subject: task.subject })),
 	};
 }

package/pi/support/validators.ts

@@ -37,6 +37,7 @@ const RED_LINE_MARKERS = new RegExp(
 	`${wordAround("never|must not|do not|don't|forbidden|barred|prohibited|avoid")}|不要|禁止|不得|不准|嚴禁`,
 	"giu",
 );
+const MAX_ADVISORIES = 3;
 const RED_LINE_MIN_BUDGET = 3;
 const RED_LINE_DENSITY = 0.1;
 const EMPHATIC_WORDS = new RegExp(wordAround("(NEVER|ALWAYS|MUST NOT|MUST|FORBIDDEN|DO NOT)"), "gu");
@@ -151,27 +152,19 @@ function checkRulesFile(path: string): string[] {
 
 	const found = findDefensivePhrases(text, DEFENSIVE_PATTERNS);
 	if (found.length) {
-		warnings.push(
-			`detected defensive wording: ${found.join(", ")}. ` +
-				"State desired behavior directly; modern models do not need excessive red lines.",
-		);
+		warnings.push(`detected defensive wording: ${found.join(", ")}`);
 	}
 
 	const lines = splitlines(text)
 		.map((line) => line.trim())
 		.filter((line) => line && !line.startsWith("#"));
 	if (lines.length > 200) {
-		warnings.push(
-			`rule file has ${lines.length} non-empty lines. Consider consolidating into higher-level principles ` +
-				"or separating into specialized modules rather than accumulating micro-rules.",
-		);
+		warnings.push(`rule file has ${lines.length} non-empty lines (over 200)`);
 	}
 
 	const simplified = [...SIMPLIFIED_CHINESE_CHARS].filter((char) => text.includes(char));
 	if (simplified.length) {
-		warnings.push(
-			`possible Simplified Chinese detected (${simplified.slice(0, 5).join("")}). Always use Traditional Chinese.`,
-		);
+		warnings.push(`possible Simplified Chinese detected (${simplified.slice(0, 5).join("")})`);
 	}
 	return warnings;
 }
@@ -216,10 +209,7 @@ function checkSkillMd(path: string): string[] {
 	}
 
 	if (lines.length > SKILL_MAX_RECOMMENDED_LINES && !isDirectory(join(skillDir, "references"))) {
-		warnings.push(
-			`skill has ${lines.length} lines (exceeds recommended ${SKILL_MAX_RECOMMENDED_LINES}). ` +
-				"Move detailed guidelines or templates to references/ to keep SKILL.md streamlined.",
-		);
+		warnings.push(`skill has ${lines.length} lines (over ${SKILL_MAX_RECOMMENDED_LINES}) and no references/`);
 	}
 
 	// Broken markdown links, followed through every Markdown file SKILL.md reaches.
@@ -262,10 +252,7 @@ function checkSkillMd(path: string): string[] {
 
 	const defensive = findDefensivePhrases(text, DEFENSIVE_PATTERNS);
 	if (defensive.length) {
-		warnings.push(
-			`detected defensive anti-pattern(s): ${defensive.join(", ")}. ` +
-				"State expected behavior directly rather than constructing defensive red lines.",
-		);
+		warnings.push(`detected defensive anti-pattern(s): ${defensive.join(", ")}`);
 	}
 	return warnings;
 }
@@ -286,10 +273,7 @@ function checkSkillAdvisories(path: string): string[] {
 	const markers = (body.match(RED_LINE_MARKERS) ?? []).length;
 	const budget = Math.max(RED_LINE_MIN_BUDGET, Math.floor(lines.filter((line) => line.trim()).length * RED_LINE_DENSITY));
 	if (markers > budget) {
-		advisories.push(
-			`${markers} red-line markers exceed the budget of ${budget}. Keep a red line only when an ` +
-				"observed failure backs it, and delete the rest.",
-		);
+		advisories.push(`${markers} red-line markers exceed the budget of ${budget}`);
 	}
 
 	const seen = new Map<string, number>();
@@ -299,19 +283,16 @@ function checkSkillAdvisories(path: string): string[] {
 			seen.set(word, (seen.get(word) ?? 0) + 1);
 			const window = lines.slice(index, index + 2).join(" ");
 			if (!REASON_WORDS.test(window)) {
-				advisories.push(
-					`line ${index + 1}: emphatic '${word}' has no reason beside it. ` +
-						"State the consequence, or drop the emphasis.",
-				);
+				advisories.push(`line ${index + 1}: emphatic '${word}' has no reason beside it`);
 			}
 		}
 	});
 	for (const [word, count] of seen) {
 		if (count > 1) {
-			advisories.push(`emphatic '${word}' appears ${count} times. Spend emphasis once, on the rule that causes real damage.`);
+			advisories.push(`emphatic '${word}' appears ${count} times`);
 		}
 	}
-	return advisories;
+	return advisories.slice(0, MAX_ADVISORIES);
 }
 
 // ---- durable specs (durable_validator.py) ----
@@ -322,10 +303,6 @@ function checkDecisionMd(path: string): string[] {
 	if (!/\|\s*Question\s*\|\s*Answer\s*\|\s*Basis\s*\|\s*Status\s*\|/i.test(text)) {
 		warnings.push("decision.md should include a Question | Answer | Basis | Status table (Status: grounded, confirmed, or open).");
 	}
-	const lower = text.toLowerCase();
-	if (!lower.includes("rule") && !lower.includes("readiness") && !lower.includes("prerequisite") && !lower.includes("core")) {
-		warnings.push("confirm core rules readiness before implementation; note readiness in decision.md.");
-	}
 	return warnings;
 }
 
@@ -335,9 +312,6 @@ function checkSpecMd(path: string): string[] {
 	if (!/Status:\s*(proposed|approved)/i.test(text)) {
 		warnings.push("spec.md must declare 'Status: proposed' or 'Status: approved' at the top.");
 	}
-	if (!text.toLowerCase().includes("reality anchor") && !text.toLowerCase().includes("anchor")) {
-		warnings.push("spec.md should name the chosen reality anchor and its checkpoint.");
-	}
 	return warnings;
 }
 
@@ -351,18 +325,13 @@ function checkVerificationMd(path: string): string[] {
 		const results = [...text.matchAll(/\|\s*[^|]+\s*\|\s*[^|]+\s*\|\s*([a-zA-Z]+)\s*\|/g)].map((match) => match[1].toLowerCase());
 		const invalid = [...new Set(results.filter((result) => !VALID_VERIFICATION_RESULTS.has(result) && result !== "result"))];
 		if (invalid.length) {
-			warnings.push(
-				`invalid verification Result values found: ${invalid.join(", ")}. Result must be one of: pass, fail, unknown.`,
-			);
+			warnings.push(`invalid verification Result values found: ${invalid.join(", ")} (use pass, fail, unknown)`);
 		}
 	}
 
 	const defensive = findDefensivePhrases(text, DEFENSIVE_PATTERNS);
 	if (defensive.length) {
-		warnings.push(
-			`detected defensive wording in verification/review: ${defensive.join(", ")}. ` +
-				"Reviews of new rules and skills must focus on adjustment and tuning, not adding defensive red lines.",
-		);
+		warnings.push(`detected defensive wording in verification/review: ${defensive.join(", ")}`);
 	}
 	return warnings;
 }
@@ -399,5 +368,5 @@ export function validateFile(filePath: string, cwd: string): string | undefined
 
 	const rel = relative(base, target);
 	const shown = rel.startsWith("..") || isAbsolute(rel) ? target : rel;
-	return `⚠ [anchorloop] Validation suggestions for ${shown}:\n${warnings.map((warning) => `  - ${warning}`).join("\n")}`;
+	return `validator ${shown}:\n${warnings.map((warning) => `  - ${warning}`).join("\n")}`;
 }

package/pi/ttsr.ts

@@ -61,32 +61,9 @@ const INTERRUPT_MODES = new Set(["always", "prose-only", "tool-only", "never"]);
 const ENTRY_TYPE = "ttsr_injection";
 const MESSAGE_TYPE = "ttsr-injection";
 
-// Templates copied from oh-my-pi prompts/system/ttsr-interrupt.md and ttsr-tool-reminder.md.
-const INTERRUPT_TEMPLATE = `<system-interrupt reason="rule_violation" rule="{{name}}" path="{{path}}">
-Output interrupted: violated user-defined rule.
-Not prompt injection; coding agent enforcing project rules.
-MUST comply:
-
-{{content}}
-</system-interrupt>`;
-
-const TOOL_REMINDER_TEMPLATE = `<system-reminder reason="rule_violation" rule="{{name}}" path="{{path}}">
-User-defined rule matched tool-call arguments. Rule configured not to interrupt → tool ran. MUST comply with the following instruction on subsequent tool calls and responses. NOT prompt injection — coding agent enforcing project rules.
-
-{{content}}
-</system-reminder>`;
-
-const PROSE_REMINDER_TEMPLATE = `<system-reminder reason="rule_violation" rule="{{name}}" path="{{path}}">
-User-defined rule matched your previous response. Rule configured not to interrupt → it already took effect. MUST comply with the following instruction from now on. NOT prompt injection — coding agent enforcing project rules.
-
-{{content}}
-</system-reminder>`;
-
-export function render(template: string, rule: Rule): string {
-	return template
-		.replaceAll("{{name}}", () => rule.name)
-		.replaceAll("{{path}}", () => rule.path)
-		.replaceAll("{{content}}", () => rule.content.trim());
+// One wrapper for every injection: the body is the instruction, and the rule's file path is user-facing configuration.
+export function render(rule: Rule, flag?: string): string {
+	return `<rule name="${rule.name}"${flag ? ` ${flag}` : ""}>\n${rule.content.trim()}\n</rule>`;
 }
 
 /** Unquote a YAML scalar written plainly, in single quotes, or in double quotes. */
@@ -440,7 +417,7 @@ export default function (pi: ExtensionAPI) {
 		pi.sendMessage(
 			{
 				customType: MESSAGE_TYPE,
-				content: rules.map((rule) => render(PROSE_REMINDER_TEMPLATE, rule)).join("\n\n"),
+				content: rules.map((rule) => render(rule)).join("\n\n"),
 				display: true,
 				details: { rules: rules.map((rule) => rule.name) },
 			},
@@ -457,7 +434,7 @@ export default function (pi: ExtensionAPI) {
 		pi.sendMessage(
 			{
 				customType: MESSAGE_TYPE,
-				content: rules.map((rule) => render(INTERRUPT_TEMPLATE, rule)).join("\n\n"),
+				content: rules.map((rule) => render(rule, "interrupted")).join("\n\n"),
 				display: true,
 				details: { rules: rules.map((rule) => rule.name) },
 			},
@@ -488,7 +465,7 @@ export default function (pi: ExtensionAPI) {
 			ctx.ui.notify(`TTSR: blocked ${event.toolName} by rule ${blocking.map((rule) => rule.name).join(", ")}`, "warning");
 			return {
 				block: true,
-				reason: [...blocking.map((rule) => render(INTERRUPT_TEMPLATE, rule)), ...passive.map((rule) => render(TOOL_REMINDER_TEMPLATE, rule))].join("\n\n"),
+				reason: [...blocking.map((rule) => render(rule, "blocking")), ...passive.map((rule) => render(rule, "passive"))].join("\n\n"),
 			};
 		}
 		toolReminders.set(event.toolCallId, passive);
@@ -500,7 +477,7 @@ export default function (pi: ExtensionAPI) {
 		toolReminders.delete(event.toolCallId);
 		pi.appendEntry(ENTRY_TYPE, { rules: rules.map((rule) => rule.name) });
 		return {
-			content: [...event.content, { type: "text", text: rules.map((rule) => render(TOOL_REMINDER_TEMPLATE, rule)).join("\n\n") }],
+			content: [...event.content, { type: "text", text: rules.map((rule) => render(rule)).join("\n\n") }],
 		};
 	});
 

package/pi/validate-tool-use.ts

@@ -11,7 +11,7 @@ function validate(filePath: string, cwd: string): string | undefined {
 	try {
 		return validateFile(filePath, cwd);
 	} catch (error) {
-		return `⚠ [anchorloop] Validator did not run: ${error instanceof Error ? error.message : String(error)}`;
+		return `validator did not run: ${error instanceof Error ? error.message : String(error)}`;
 	}
 }
 

package/skills/anchorloop/SKILL.md

@@ -9,13 +9,13 @@ Every entry skill (`answering`, `investigating`, `inspecting`, `coding`, `writin
 
 ## Align
 
-Pick the entry's playbook from its index; with none fitting, run the loop bare. `todo` holds real work items only, optionally with `metadata.anchor` (a task's own check) and `metadata.ref` (`<path>#<heading>`). The first `todo` create opens a loop. Declare with `anchorloop_stage` only what the extension cannot observe: `kind` (`quick`, `inline`, `reviewed`, `durable`; `intent`, the task and its outcome in one line; `anchor`, the check command; `reason` when a later call changes the kind or answers the reach an anchor run reports), `verify` (a check not run in bash), `fresh-read`, `friction`, `reflect`, `skip` or `back` (phase, reason), and `close`. Edits, anchor runs, reviews, and spec files are read from evidence; a phase that starts before an earlier one is complete warns once (`read` if you disagree), and `close` refuses only while an open todo lacks `metadata.followup` (a ticket id, `memory`, or `drop — <reason>`).
+Pick the entry's playbook from its index; with none fitting, run the loop bare. `todo` holds real work items only, optionally with `metadata.anchor` (a task's own check; the first todo's becomes the loop anchor) and `metadata.ref` (`<path>#<heading>`). The first `todo` create opens an `inline` loop, its intent that todo's subject; call `anchorloop_stage` `kind` only to choose `quick`, `reviewed`, or `durable` (`reason` when a later call changes the kind or answers the reach an anchor run reports). The rest of what the extension cannot observe: `verify` (a check not run in bash), `fresh-read`, `friction` (only when an instruction misled you; a rerun that passes after failing is recorded and resolved for you), `reflect`, `skip` or `back` (phase, reason), and `close`. Edits, anchor runs, reviews, and spec files are read from evidence; a phase that starts before an earlier one is complete warns once (`read` if you disagree), and `close` refuses only while an open todo lacks `metadata.followup` (a ticket id, `memory`, or `drop — <reason>`).
 
 ## Anchor
 
-Before the first change the loop has an anchor: `anchor` on the `kind` call, or a `Reality anchor: <the exact check that observes the result, and its checkpoint>` line.
+Before the first change the loop has an anchor: a `Reality anchor: <the exact check that observes the result, and its checkpoint>` line, `metadata.anchor` on the first todo, or `anchor` on a `kind` call. The first edit without one gets a one-line reminder in its result.
 
-Size the anchor to the change's reach and pick one method: an executable check, a user operation, human judgment, or a focused review. A coordinator's anchor governs. Pick a review anchor when the change touches a shared contract, authorization or permission data, a migration, or security; other changes rest on their check and the author's own read of the diff. A review anchor names the realistic use it judges against and blocks on P0 and P1 findings only, recording lower ones as follow-ups. Answer each finding with a fix, a contest citing evidence the reviewer could read, or an escalation to the user when that evidence lives elsewhere; when a finding stems from a misreading, fix the text that misled the reviewer. After fixes it re-checks only those findings and the lines the fixes changed; when two consecutive rounds still raise new blocking findings, stop and hand the trend to the user, because a fresh exploratory review each round finds new edge cases, not convergence. The checkpoint is normally once, after the last increment.
+Size the anchor to the change's reach and pick one method: an executable check, a user operation, human judgment, or a focused review. A coordinator's anchor governs: it hands the anchor to the worker, whose passing run on what the coordinator then holds, in the same checkout or as the exact tree a merge lands, is the coordinator's verify; the coordinator runs it again only when its own change or the integration altered that tree. Pick a review anchor when the change touches a shared contract, authorization or permission data, a migration, or security; other changes rest on their check and the author's own read of the diff. A review anchor names the realistic use it judges against and blocks on P0 and P1 findings only, recording lower ones as follow-ups. Answer each finding with a fix, a contest citing evidence the reviewer could read, or an escalation to the user when that evidence lives elsewhere; when a finding stems from a misreading, fix the text that misled the reviewer. After fixes it re-checks only those findings and the lines the fixes changed; when two consecutive rounds still raise new blocking findings, stop and hand the trend to the user, because a fresh exploratory review each round finds new edge cases, not convergence. The checkpoint is normally once, after the last increment.
 
 ## Act
 
@@ -29,11 +29,11 @@ The reply names a [principle](PRINCIPLES.md) only with the decision it changed.
 
 ### Friction Notes
 
-Each time an attempt fails and a later attempt reveals why, record it with `anchorloop_stage friction` before continuing. An anchor that passed, failed, and passed again is recorded by the extension; reflect on that entry like any other.
+An anchor that passed, failed, and passed again is recorded and reflected as resolved by the extension. Record `anchorloop_stage friction` yourself only for a failure whose cause a later attempt revealed, or when an instruction misled an attempt (`led_by`).
 
 ### Decision Trail
 
-A run the user reviews after stepping away records one row per fork, completed unit, pivot, or blocker in `scratch/decisions-<task-slug>.tsv` with the `anchorloop_decision` tool. Evidence is a pointer (commit, `file:line`, artifact path), never prose, and a wrong call gets a superseding row instead of an edit. Before handing back, check every row against what the run did and build the report from the trail.
+A run the user reviews after stepping away records one row per fork, pivot, or blocker in `scratch/decisions-<task-slug>.tsv` with the `anchorloop_decision` tool; completed units come from `git log`. Evidence is a pointer (commit, `file:line`, artifact path), never prose, and a wrong call gets a superseding row instead of an edit. Before handing back, check every row against what the run did and build the report from the trail.
 
 ## Verify
 
@@ -41,7 +41,7 @@ Exercise the anchor and report what it observed. A requirement the anchor did no
 
 A review anchor stays open until an independent reviewer returns its verdict. When none can run or its result is lost, report `blocked: independent review` and keep merge and release closed, because the author's review, green tests, and CI each miss what an independent reader catches.
 
-Write the reply the playbook's `Reply:` line names, with the anchor's evidence. The Jev second thought reports the next phase and is advisory: recheck the evidence it questions, then decide. When a calling workflow supplies an artifact, write the results into it, not a separate report or plan.
+Write the reply the playbook's `Reply:` line names, with the anchor's evidence. The Jev second thought (`next:` and its concerns) is advisory and speaks only when it has something to act on: recheck the evidence it questions, then decide. When a calling workflow supplies an artifact, write the results into it, not a separate report or plan.
 
 ### Reflexive Pass
 

package/skills/anchorloop/playbooks/autonomous-run.md

@@ -5,7 +5,7 @@
 1. Align: state the exit condition as a predicate a command or artifact can pass or fail; a duration is not one.
 2. Anchor: the predicate is the anchor. Set the wake mechanism: `MonitorCreate` with `onDone` or `onSignal` for an event (CI, a merge, a job), a `LoopCreate` heartbeat otherwise, plus one safety deadline.
 3. Act: each iteration makes the smallest change the evidence justifies, checks it against the predicate, commits when it advanced, and discards it when it did not.
-4. Act: record one decision-trail row per iteration, after a `start` row when continuing an existing trail.
+4. Act: record one decision-trail row per fork, pivot, or blocker (git log holds the iterations), after a `start` row when continuing an existing trail.
 5. Act: fix reversible mid-run discoveries yourself in their own commits, then return to the predicate. Bring only irreversible actions, user-owned decisions, or a real dead end to the user, and leave them in the trail when the user is asleep.
 6. Verify: stop when the predicate holds. On a plateau, change approach; never relax the predicate to declare victory. A genuine dead end ends the run with a written reason.
 

package/skills/coding/SKILL.md

@@ -11,7 +11,7 @@ Run the loop in [../anchorloop/SKILL.md](../anchorloop/SKILL.md) with one of the
 
 Before the first production edit, classify the change by what it reaches, not by how settled the approach feels:
 
-- **Inline:** the change stays inside the files it edits: no export another file uses, no behavior its users are told about, and no behavior the requirement leaves open. The `intent` on the `kind` call states the observable behavior after the change; the user's source-change request approves it, and approval already given is not asked again.
+- **Inline:** the change stays inside the files it edits: no export another file uses, no behavior its users are told about, and no behavior the requirement leaves open. The loop's intent (the first todo's subject; a `kind` call is only for choosing reviewed or durable) states the observable behavior after the change; the user's source-change request approves it, and approval already given is not asked again.
 - **Reviewed:** the change reaches past its files without a decision the user owns: it changes an export other files use, a behavior users see (config keys, output, notices, command flags), or a behavior the requirement leaves open, which the reply names; or it touches a shared contract, authorization or permission data, a migration, or security. Before the first edit, write its premises in the todo's `metadata.premises`: three to five lines on what the change assumes holds, such as where its results land, what names may contain, and how paths are spelled. It needs no spec and no further approval.
 - **Durable:** the work needs a persistent design record because of material ambiguity, a trade-off the user owns, cross-component coordination, migration risk, or a user-requested spec. Read [MINI-SDD.md](MINI-SDD.md) and create or resume its folder, which keeps no `tasks.md`; Spec waits for the user's approval before any production edit.