pi-anchorloop 2.1.1 → 2.2.1

package/pi/support/jev.ts

@@ -0,0 +1,28 @@
+/** Shared access to Jev (TypeSafe's typed-decision model) through pi's classifier registry. */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export const TIMEOUT_MS = 15_000;
+
+export type Question = { type: "bool" | "choice" | "score"; instructions: string; criteria: unknown };
+export type Answers = Record<string, { type: string; probability?: number; choice?: string; probabilities?: Record<string, number>; score?: number }>;
+
+/** The classification answers, or the reason none came: no key, a timeout, or a failure. */
+export async function classify(ctx: ExtensionContext, state: Record<string, string>, questions: Record<string, Question>): Promise<{ answers?: Answers; reason: string }> {
+	const jev = ctx.modelRegistry.findOfType("classifier", "typesafe", "jev-latest");
+	type AuthModel = Parameters<typeof ctx.modelRegistry.hasConfiguredAuth>[0];
+	if (!jev) return { reason: "no-auth" };
+	// SAFETY: hasConfiguredAuth is typed for chat models but reads only `provider`, which a classifier has too.
+	const authModel = jev as unknown as AuthModel;
+	if (!ctx.modelRegistry.hasConfiguredAuth(authModel)) return { reason: "no-auth" };
+	try {
+		const result = await ctx.modelRegistry.classify(
+			jev,
+			{ state, questions } as Parameters<typeof ctx.modelRegistry.classify>[1],
+			{ signal: AbortSignal.any([AbortSignal.timeout(TIMEOUT_MS), ...(ctx.signal ? [ctx.signal] : [])]) },
+		);
+		return result.stopReason === "stop" ? { answers: result.answers as Answers, reason: "stop" } : { reason: result.stopReason };
+	} catch (error) {
+		return { reason: error instanceof Error ? error.message : String(error) };
+	}
+}

package/pi/support/phases.ts

@@ -0,0 +1,301 @@
+/**
+ * The phase machine: each loop kind runs a fixed sequence of phases, and the book's evidence says which
+ * phases are complete. Nothing here blocks; a phase entered while an earlier one is incomplete yields
+ * one warning line that names what is missing and the `skip` escape. Phases regress by themselves when
+ * evidence changes (a diff after verify, a spec edited back to proposed) and by `back` on request.
+ */
+
+import { existsSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import {
+	type Book,
+	type Entry,
+	type Kind,
+	type Task,
+	allFriction,
+	anchorCommand,
+	artifactOnDisk,
+	currentKind,
+	lastActIndex,
+	lastIndex,
+	repoRootOf,
+	retryWithoutFriction,
+	specFolder,
+	withChildActs,
+} from "./book.ts";
+
+export const SEQUENCES: Record<Kind, readonly string[]> = {
+	quick: ["act", "check", "reflect", "close"],
+	inline: ["anchor", "act", "verify", "reflect", "close"],
+	reviewed: ["anchor", "act", "verify", "review", "reflect", "close"],
+	durable: ["decide", "grill", "spec", "read", "approve", "design", "anchor", "act", "verify", "review", "reflect", "close"],
+};
+
+export type Status = { name: string; state: "done" | "skipped" | "missing"; note: string; /** Skipped by the evidence itself (no open rows, no friction), not by a `skip` declaration. */ auto?: boolean };
+
+export type Phases = {
+	kind: Kind | "undeclared";
+	statuses: Status[];
+	/** The last phase of the complete prefix, or `start`. */
+	current: string;
+	/** The first incomplete phase, `fix` when a check or review failed after the last change, else `close`. */
+	next: string;
+	missing: string;
+	skipped: string[];
+	backs: string[];
+	/** Advisory hints that are not phases. */
+	hints: string[];
+};
+
+export type Inputs = { entries: Entry[]; cwd: string; todos: Task[]; env?: NodeJS.ProcessEnv };
+
+// --- paths ---------------------------------------------------------------------------------------
+
+const EXEMPT_IN_PROJECT = ["scratch", "docs/specs"];
+const EXEMPT_ROOTS = [tmpdir(), "/tmp", "/var/folders"];
+const EXEMPT_EXTENSIONS = [".md", ".txt", ".html", ".htm"];
+
+/** The real path of `path`, resolving symlinks such as /var → /private/var through its nearest existing parent. */
+function real(path: string): string {
+	if (existsSync(path)) return realpathSync(path);
+	const parent = dirname(path);
+	return parent === path ? path : join(real(parent), basename(path));
+}
+
+function within(root: string, target: string): boolean {
+	const rel = relative(root, target);
+	return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+/**
+ * True for a file that is not code work: scratch and spec folders of the project or of any git repo the file lives in, and
+ * temp files outside every repo. A file inside a git repo counts as work wherever the repo is, even under a temp dir.
+ */
+export function outsideWork(filePath: string, cwd: string): boolean {
+	const root = real(cwd);
+	const target = real(resolve(cwd, filePath));
+	const inFolders = (base: string) => EXEMPT_IN_PROJECT.some((dir) => within(join(base, dir), target));
+	if (within(root, target)) return inFolders(root);
+	const repo = repoRootOf(target);
+	if (repo) return inFolders(repo);
+	return EXEMPT_ROOTS.some((tmp) => within(real(tmp), target));
+}
+
+/** Markdown, text, and HTML files and everything `outsideWork` names: an edit the anchor gate does not warn about. */
+export function exempt(filePath: string, cwd: string): boolean {
+	return EXEMPT_EXTENSIONS.includes(extname(filePath).toLowerCase()) || outsideWork(filePath, cwd);
+}
+
+// --- evidence ------------------------------------------------------------------------------------
+
+type Ctx = Inputs & { seq: readonly string[]; folder?: string; lastAct: number };
+
+const done = (name: string, note = ""): Status => ({ name, state: "done", note });
+const missing = (name: string, note: string): Status => ({ name, state: "missing", note });
+
+function same(a: string, b: string): boolean {
+	const group = (name: string) => (name === "check" ? "verify" : name);
+	return group(a) === group(b);
+}
+
+/** Entries before this index do not count for `name`: the latest `back` to this phase or an earlier one. */
+function floor(entries: Entry[], seq: readonly string[], name: string): number {
+	const at = seq.indexOf(name);
+	let from = 0;
+	entries.forEach((entry, index) => {
+		if (entry.stage !== "back" || typeof entry.phase !== "string") return;
+		const target = seq.findIndex((candidate) => same(candidate, entry.phase as string));
+		if (target >= 0 && at >= target) from = index + 1;
+	});
+	return from;
+}
+
+function lastWhere(entries: Entry[], from: number, test: (entry: Entry) => boolean): number {
+	for (let i = entries.length - 1; i >= from; i--) if (test(entries[i])) return i;
+	return -1;
+}
+
+function skipEntry(entries: Entry[], from: number, name: string): Entry | undefined {
+	const index = lastWhere(entries, from, (entry) => entry.stage === "skip" && typeof entry.phase === "string" && same(entry.phase, name));
+	return index >= 0 ? entries[index] : undefined;
+}
+
+/** The latest recorded summary of an artifact since `from`; a loop that never wrote it falls back to the file on disk. */
+function artifact(ctx: Ctx, name: string, from: number): Entry | undefined {
+	const index = lastWhere(ctx.entries, from, (entry) => entry.stage === name && entry.auto === true);
+	if (index >= 0) return ctx.entries[index];
+	const wrote = ctx.entries.some((entry) => entry.stage === name && entry.auto === true);
+	return from === 0 && !wrote && ctx.folder ? artifactOnDisk(ctx.folder, name, ctx.cwd) : undefined;
+}
+
+const total = (counts: unknown): number => Object.values((counts ?? {}) as Record<string, number>).reduce((sum, n) => sum + Number(n), 0);
+
+/** The index of the first spec entry in the latest run of proposed-or-approved spec entries, -1 when there is no entry for it, or undefined when the spec is not proposed. */
+function proposedSince(ctx: Ctx): number | undefined {
+	let start: number | undefined;
+	let seen = false;
+	ctx.entries.forEach((entry, index) => {
+		if (entry.stage !== "spec" || entry.auto !== true) return;
+		seen = true;
+		const live = entry.status === "proposed" || entry.status === "approved";
+		if (!live) start = undefined;
+		else if (start === undefined) start = index;
+	});
+	if (seen) return start;
+	const disk = ctx.folder ? artifactOnDisk(ctx.folder, "spec", ctx.cwd) : undefined;
+	return disk && (disk.status === "proposed" || disk.status === "approved") ? -1 : undefined;
+}
+
+function evaluate(name: string, ctx: Ctx): Status {
+	const { entries } = ctx;
+	const from = floor(entries, ctx.seq, name);
+	const skip = skipEntry(entries, from, name);
+	if (skip) return { name, state: "skipped", note: String(skip.reason ?? skip.skip ?? "") };
+	switch (name) {
+		case "decide": {
+			const decision = artifact(ctx, "decision", from);
+			return total(decision?.counts) > 0 ? done(name) : missing(name, ctx.folder ? `${ctx.folder}/decision.md with decision rows` : "decision.md with decision rows (no spec folder: name it in `intent` by calling `kind` again)");
+		}
+		case "grill": {
+			const decision = artifact(ctx, "decision", from);
+			if (!decision || total(decision.counts) === 0) return missing(name, "decision rows to grill");
+			const open = Number((decision.counts as Record<string, number>).open ?? 0);
+			if (open > 0) return missing(name, `${open} open decision row${open === 1 ? "" : "s"}`);
+			const first = entries.find((entry) => entry.stage === "decision" && entry.auto === true);
+			return first && Number((first.counts as Record<string, number>).open ?? 0) === 0 ? { name, state: "skipped", note: "no open rows", auto: true } : done(name);
+		}
+		case "spec": {
+			const spec = artifact(ctx, "spec", from);
+			return spec?.status === "proposed" || spec?.status === "approved" ? done(name) : missing(name, "spec.md with Status: proposed");
+		}
+		case "read": {
+			const start = proposedSince(ctx);
+			if (start === undefined) return missing(name, "a proposed spec to read");
+			const index = lastWhere(entries, Math.max(from, start + 1), (entry) => entry.stage === "goldfish" && entry.ok !== false);
+			if (index >= 0) return done(name, String(entries[index].source ?? ""));
+			const wrote = entries.some((entry) => entry.stage === "spec" && entry.auto === true);
+			const specs = entries.filter((entry) => entry.stage === "spec" && entry.auto === true);
+			if (specs.length > 0 && start >= 0 && entries[start].status === "approved" && !entries.slice(0, start).some((entry) => entry.stage === "spec" && entry.status === "proposed")) return done(name, "spec approved");
+			if (!wrote && from === 0 && artifact(ctx, "spec", 0)?.status === "approved") return done(name, "spec approved before this loop");
+			return missing(name, "a fresh-context read of the spec (dispatch a subagent, or `anchorloop_stage fresh-read`)");
+		}
+		case "approve": {
+			const spec = artifact(ctx, "spec", from);
+			return spec?.status === "approved" && spec.approvedFrom === true ? done(name) : missing(name, `spec.md Status: approved with Approved from${spec?.status ? ` (now ${spec.status})` : ""}`);
+		}
+		case "design": {
+			const design = artifact(ctx, "design", from);
+			return design?.approach === true ? done(name) : missing(name, "design.md with its approach section filled");
+		}
+		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");
+		}
+		case "act":
+			return lastWhere(entries, from, (entry) => entry.stage === "edit") >= 0 ? done(name) : missing(name, "a change to the code");
+		case "check":
+		case "verify": {
+			const index = lastWhere(entries, Math.max(from, ctx.lastAct + 1), (entry) => entry.stage === "verify" || entry.stage === "check");
+			if (index < 0) {
+				const command = anchorCommand(entries);
+				return missing(name, command ? `a passing run of \`${command}\` after the last change` : "a verify declaration or a run of the anchor");
+			}
+			const entry = entries[index];
+			if (entry.declared === true && entry.result === "fail") return missing(name, "the declared verify failed");
+			if (entry.declared !== true && entry.exit !== 0) return missing(name, `the anchor exited ${entry.exit ?? "unknown"} after the last change`);
+			if (ctx.seq.includes("decide") && !artifact(ctx, "verification", from)) return missing(name, `${ctx.folder ?? "docs/specs/<folder>"}/verification.md (a durable loop's verify also needs it)`);
+			return done(name, entry.declared === true ? "declared" : "");
+		}
+		case "review": {
+			const index = lastWhere(entries, Math.max(from, ctx.lastAct + 1), (entry) => entry.stage === "review");
+			if (index < 0) return missing(name, "a review round after the last change with Blocking: P0=0 P1=0");
+			const round = entries[index];
+			if (round.blocking === false) return done(name);
+			const rounds = entries.filter((entry) => entry.stage === "review");
+			const stalled = rounds.length >= 2 && rounds.at(-1)?.blocking === true && rounds.at(-2)?.blocking === true;
+			return missing(name, stalled ? "two consecutive review rounds still blocking: hand the trend to the user" : round.blocking === true ? "blocking review findings are open" : "the review verdict is unknown");
+		}
+		case "reflect": {
+			const items = allFriction(entries, ctx.env);
+			if (items.length === 0) return { name, state: "skipped", note: "no friction", auto: true };
+			const open = items.filter((item) => !item.reflected).length;
+			return open === 0 ? done(name) : missing(name, `${open} friction entr${open === 1 ? "y" : "ies"} without a reflect`);
+		}
+		default:
+			return missing(name, name);
+	}
+}
+
+/** The phase state of the loop kind recorded in the book. */
+export function computePhases(book: Pick<Book, "entries">, inputs: Omit<Inputs, "entries">): Phases {
+	const kind = currentKind(book.entries);
+	const seq = SEQUENCES[kind ?? "inline"];
+	const entries = withChildActs(book.entries);
+	const ctx: Ctx = { ...inputs, entries, seq, folder: specFolder(entries, inputs.todos, inputs.cwd), lastAct: lastActIndex(entries) };
+	const statuses = seq.filter((name) => name !== "close").map((name) => evaluate(name, ctx));
+	let prefix = 0;
+	while (prefix < statuses.length && statuses[prefix].state !== "missing") prefix++;
+	const first = statuses[prefix];
+	const reached = statuses.slice(0, prefix).filter((status) => status.state === "done").at(-1);
+	let next = first ? first.name : "close";
+	let note = first ? first.note : "";
+	const last = ctx.lastAct;
+	const verify = entries.map((entry, index) => ({ entry, index })).filter(({ entry, index }) => index > last && (entry.stage === "verify" || entry.stage === "check")).at(-1)?.entry;
+	const review = entries.map((entry, index) => ({ entry, index })).filter(({ entry, index }) => index > last && entry.stage === "review").at(-1)?.entry;
+	if ((next === "verify" || next === "check") && last >= 0 && verify && verify.exit !== 0 && verify.declared !== true) next = "fix";
+	else if (next === "review" && last >= 0 && review?.blocking === true) next = "fix";
+	if (next === "fix") note = first?.note ?? "";
+	const skipped = statuses.filter((status) => status.state === "skipped" && status.note !== "no friction").map((status) => `${status.name} (${status.note})`);
+	const backs = book.entries.filter((entry) => entry.stage === "back").map((entry) => `${entry.phase} (${entry.reason})`);
+	const hints = retryWithoutFriction(book.entries) ? ["friction: a failed run was retried and passed, with no friction entry after it"] : [];
+	return {
+		kind: kind ?? "undeclared",
+		statuses,
+		current: reached?.name ?? "start",
+		next,
+		missing: note,
+		skipped,
+		backs,
+		hints,
+	};
+}
+
+/** The statuses of phases before `entering` that are incomplete. */
+export function incompleteBefore(phases: Phases, entering: string): Status[] {
+	const order = phases.statuses.map((status) => status.name);
+	const at = entering === "close" ? order.length : order.findIndex((name) => same(name, entering));
+	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. */
+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>\`.`;
+}
+
+/** The phase line `read` and the close summary show. */
+export function describe(phases: Phases): string {
+	const parts = [`${phases.kind} · phase ${phases.current}${phases.current === "start" ? "" : " ✓"} → ${phases.next}${phases.missing ? ` (missing: ${phases.missing})` : ""}`];
+	if (phases.skipped.length) parts.push(`skipped: ${phases.skipped.join(", ")}`);
+	if (phases.backs.length) parts.push(`back: ${phases.backs.join(", ")}`);
+	return parts.join(" · ");
+}
+
+/** Remembers which incomplete phases a jump already warned about; a regression adds one and warns again. */
+export class JumpMemory {
+	private warned = new Map<string, Set<string>>();
+
+	/** True when `missingNames` holds a phase not yet warned about for this book and entering phase. */
+	fresh(bookId: string, entering: string, missingNames: string[]): boolean {
+		const key = `${bookId}|${entering}`;
+		const before = this.warned.get(key) ?? new Set<string>();
+		const news = missingNames.some((name) => !before.has(name));
+		if (missingNames.length === 0) this.warned.delete(key);
+		else this.warned.set(key, new Set(missingNames));
+		return news;
+	}
+}
+
+export { lastIndex };

package/pi/support/snapshot.ts

@@ -0,0 +1,71 @@
+/** The loop state Jev judges, read from the book, the todo list, and the phase machine. */
+
+import {
+	type Book,
+	allFriction,
+	childLines,
+	currentIntent,
+	currentKind,
+	diffAgainstBases,
+	diffText,
+	isOpenTask,
+	latestAnchor,
+	replayTodos,
+	reviewClearAfterLastAct,
+	reviewTrend,
+	stagesDone,
+	TASK_LEGEND,
+	taskLines,
+	verifyAfterLastAct,
+} from "./book.ts";
+import { computePhases } from "./phases.ts";
+
+export type Snapshot = {
+	state: Record<string, string>;
+	/** The program's next phase and what it lacks, in a few words. */
+	next: string;
+	missing: string;
+	/** Advisory hints that are not phases, such as an unrecorded friction. */
+	hints: string[];
+	/** The last phase the book shows complete. */
+	current: string;
+	/** A review recorded after the last change with no blocking finding on it. */
+	reviewClear: boolean;
+};
+
+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 phases = computePhases(book, { cwd: ctx.cwd, todos });
+	const check = verifyAfterLastAct(entries);
+	const verify = [
+		`stages: ${stagesDone(entries).join(", ") || "none"}`,
+		`last check: ${check ? `${check.declared ? `declared ${check.result}` : `exit ${check.exit ?? "unknown"}`}${check.last ? ` — ${check.last}` : ""}` : "none after the last change"}`,
+		`reviews: ${reviewTrend(entries)}`,
+		...childLines(entries).map((line) => `child ${line}`),
+	].join("; ");
+	const items = allFriction(entries);
+	const friction = [
+		...(items.length ? [`${items.length} recorded, ${items.filter((item) => item.reflected).length} reflected`] : []),
+		...items.map((item) => `${item.ref}: ${item.tried} → ${item.found} [${item.reflected ? `${item.class}${item.action ? `: ${item.action}` : ""}` : "unreflected"}]`),
+	];
+	return {
+		state: {
+			kind: currentKind(entries) ?? "not declared",
+			intent: (currentIntent(entries) ?? "not declared").slice(0, 500),
+			anchor: (latestAnchor(entries) ?? "none").slice(0, 500),
+			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}`,
+			tasks: [`legend: ${TASK_LEGEND}`, ...taskLines(entries, todos, ctx.cwd)].join("\n").slice(0, 1500),
+			friction: (friction.join("\n") || "none").slice(0, 800),
+		},
+		next: phases.next,
+		missing: phases.missing,
+		hints: phases.hints,
+		current: phases.current,
+		reviewClear: reviewClearAfterLastAct(entries),
+	};
+}

package/pi/support/subagent.ts

@@ -0,0 +1,5 @@
+// pi-herdr-agents marks its children with PI_SUBAGENT_ID, pi-subagents with PI_SUBAGENT_CHILD,
+// and avtc's pi-subagent with PI_SUBAGENT_CHILD_AGENT plus PI_SUBAGENT_PARENT_PID.
+export function isSubagent(env: NodeJS.ProcessEnv = process.env): boolean {
+	return Boolean(env.PI_SUBAGENT_ID) || env.PI_SUBAGENT_CHILD === "1" || Boolean(env.PI_SUBAGENT_CHILD_AGENT && env.PI_SUBAGENT_PARENT_PID);
+}

package/skills/anchorloop/SKILL.md

@@ -9,59 +9,45 @@ Every entry skill (`answering`, `investigating`, `inspecting`, `coding`, `writin
 
 ## Align
 
-Open with one working interpretation in your own words:
-
-    Alignment: <the requested task and intended outcome>
-
-Pick the entry's playbook from its index; with none fitting, run the loop bare. For work longer than one increment, copy the playbook's steps verbatim into `todo`, keeping each step you will not run as `skip: <reason>`, so the plan shows what was left out and why.
+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), `verify` (a check not run in bash), `fresh-read`, `friction`, `reflect`, `skip` or `back` (phase, reason), `close`, and the query `read`. Edits, anchor runs, reviews, and spec files are read from evidence; a phase that starts before an earlier one is complete warns once, and `close` refuses only while an open todo lacks `metadata.followup` (a ticket id, `memory`, or `drop — <reason>`).
 
 ## Anchor
 
-Before the first change, state:
-
-    Reality anchor: <the exact check that observes the result, and its checkpoint>
+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.
 
-The anchorloop extension holds `write` and `edit` outside `scratch/` and `docs/specs/` until this line appears after the user's latest message.
-
-Size the anchor to the change's actual reach and pick one method: an executable check, a user operation, human judgment, or a focused review. An anchor assigned by a coordinator governs. Pick a review anchor when the change touches a shared contract, authorization or permission data, a migration, or security, or when the Jev second thought rates its review `full`; 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, and when two consecutive rounds still raise new blocking findings the run stops and hands the trend to the user, because a fresh exploratory review each round finds new edge cases instead of converging. 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. 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
 
 Work in the smallest useful increments through the project's native practices, deleting before adding (**Subtract before you add**).
 
-Give follow-up work (a fix round, a retry, the next item) to a fresh subagent carrying the original brief, every later directive, and the prior report and branch, because a resumed chain silently drops directives; resume an existing subagent only for state it alone holds, such as uncommitted changes or a running process. Write briefs, follow-ups, and messages to agents by [agent-terse](../agent-terse/SKILL.md); read each subagent's output and write its summary yourself.
+Make a small fix you hold full context for yourself; give larger follow-up work to a fresh subagent carrying the original brief, every later directive, and the prior report and branch, because a resumed chain silently drops directives. Resume a subagent only for state it alone holds, such as uncommitted changes or a running process. Write briefs, follow-ups, and messages to agents by [agent-terse](../agent-terse/SKILL.md); read each subagent's output and write its summary yourself.
 
-Report problems outside the contract as follow-ups rather than fixing them in this change, because each extra fix reopens review on code the round never meant to touch.
+Report problems outside the contract as follow-ups, because each extra fix reopens review on code the round never touched.
 
-The reply names a [principle](PRINCIPLES.md) only when it changed a decision, together with that decision.
+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, append a note before continuing:
-
-    - Tried: <the attempt that failed>
-      Found: <what the failure revealed>
-      Led by: <the skill or instruction line that prompted the attempt, or `none`>
-
-Keep them in `scratch/friction.md` unless the entry names another home.
+Each time an attempt fails and a later attempt reveals why, record it with `anchorloop_stage friction` before continuing.
 
 ### 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 actually did and build the report from the 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.
 
 ## Verify
 
-Exercise the anchor and report what it observed. A requirement the anchor did not exercise is `unknown`, whatever unrelated checks show. Report local tests, builds, interactive runs, commit, push, CI, and deployment as separate claims; one never stands in for another. A criterion that needs human judgment is a human checkpoint: propose a `human-feedback` pass when it is still `unknown`, and record its verdict apart from executable or review evidence.
+Exercise the anchor and report what it observed. A requirement the anchor did not exercise is `unknown`, whatever other checks show. Report local tests, builds, interactive runs, commit, push, CI, and deployment as separate claims; one never stands in for another. A criterion that needs human judgment is a human checkpoint: propose a `human-feedback` pass when it is still `unknown`, and record its verdict apart from executable or review evidence.
 
-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 own review, green tests, and CI each miss what an independent reader catches.
+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. A Jev second thought the extension may add after a changing run is advisory: recheck the evidence it questions, then decide. When a calling workflow supplies an artifact, write the results into it instead of a separate report or plan.
+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.
 
 ### Reflexive Pass
 
-Run only when friction notes exist, and say nothing about it otherwise. Classify each note: **misdirection** when the `Led by` line states or implies something `Found` contradicts; **gap** when no instruction in use states the `Found` fact. A gap the change itself resolved, or a tool slip no instruction owns, is recorded as resolved. Invoke `solid-loop` with the rest.
+Run only when the book holds friction (`read` lists it); otherwise say nothing. Classify each entry with `reflect`: **misdirection** when the `led_by` line states or implies something `found` contradicts; **gap** when no instruction in use states the `found` fact. A gap the change itself resolved, or a tool slip no instruction owns, is `resolved`. Invoke `solid-loop` with the rest.
 
-**Complete when:** every requirement has evidence from its anchor or is reported `unknown`, and every friction note is applied through `solid-loop` or recorded as resolved.
+**Complete when:** every requirement has evidence from its anchor or is reported `unknown`, and every friction entry is applied through `solid-loop` or reflected as resolved.
 
 ## Playbooks
 
@@ -69,7 +55,7 @@ Run only when friction notes exist, and say nothing about it otherwise. Classify
 - [pause](playbooks/pause.md): an explicit pause, going offline, a restart, or imminent compaction.
 - [pickup](playbooks/pickup.md): resuming or taking over a prior run's work.
 
-Lifecycle playbooks wrap the entry playbook that does the work.
+Lifecycle playbooks wrap the entry playbook.
 
 ---
 

package/skills/coding/MINI-SDD.md

@@ -36,7 +36,7 @@ Approved from: <the user reply that approved it, empty while proposed>
 
 Choose the smallest approach that fits the approved spec and architecture. Follow the matching playbook's design steps ([feature](playbooks/feature.md) for interfaces and seams, [prototype](playbooks/prototype.md) when a named question is cheaper to settle by experiment) and the project's exact skill.
 
-The file holds the chosen approach; interfaces and data flow affected; existing precedent; decisions, trade-offs, and risks; the method selected inside the reality anchor. Friction notes recorded during Act go under `## Friction Notes`.
+The file holds the chosen approach; interfaces and data flow affected; existing precedent; decisions, trade-offs, and risks; the method selected inside the reality anchor.
 
 **Complete when:** implementation invents no product behavior or architecture.
 
@@ -54,7 +54,7 @@ Review the diff against project standards, the approved spec, and the confirmed
 - **fail**: The anchor observed a deviation from the spec or an error.
 - **unknown**: No anchor exercised the requirement in this run.
 
-Then human appropriateness verdicts; deviations from the approved spec or design; unresolved verification gaps and their impact. When friction notes exist, include a Reflexive section listing each with its classification (`misdirection` or `gap`) and its action.
+Then human appropriateness verdicts; deviations from the approved spec or design; unresolved verification gaps and their impact. When the loop book holds friction, include a Reflexive section listing each entry with its class (`misdirection`, `gap`, or `resolved`) and its action.
 
 ## Updates
 

package/skills/coding/SKILL.md

@@ -11,8 +11,8 @@ Run the loop in [../anchorloop/SKILL.md](../anchorloop/SKILL.md) with one of the
 
 Before the first production edit, declare the change **Inline** or **Durable**:
 
-- **Inline:** requirements and approach are clear, impact is bounded, and implementation and verification fit this run; a lasting behavior or public contract can still be Inline when the change is simple. Follow Alignment with `Inline — Contract: <one sentence of the observable behavior after the change>`; the user's source-change request approves it, and approval already given is not asked again.
-- **Durable:** the work needs a persistent design record because of material ambiguity, consequential trade-offs, cross-component coordination, migration risk, continuity across sessions, 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.
+- **Inline:** requirements and approach are clear, impact is bounded, and implementation and verification fit this run; a lasting behavior or public contract can still be Inline when the change is simple. 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.
+- **Durable:** the work needs a persistent design record because of material ambiguity, consequential trade-offs, 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.
 
 ## Anchor
 

package/skills/coding/playbooks/feature.md

@@ -4,7 +4,7 @@
 
 1. Align: learn how the affected subsystem works now, and name the data shape and its organizing structure (**Model the domain**, **Foundational thinking**) before any logic.
 2. Act: when the change crosses a module, settle its interface first. Place the seam at an existing boundary; add one only for real variation, because one adapter is hypothetical and two demonstrate variation. Hide invariants and ordering behind the interface, and make it the test surface. A module whose removal makes complexity vanish rather than move to callers is a pass-through; delete it. With no precedent and a costly-to-reverse choice, compare two interface shapes on depth, locality, compatibility, and testability, or settle it with the `prototype` playbook; a user-owned trade-off goes to the user.
-3. Act: for more than one unit, write the throughput checkpoint as four `todo` items, each `n/a: <reason>` when it does not apply: blocking first steps; independent workstreams; shared mutable state, split before serializing; the smallest safe decomposition.
+3. Act: when dispatching parallel workers, write the throughput checkpoint as four `todo` items, each `n/a: <reason>` when it does not apply: blocking first steps; independent workstreams; shared mutable state, split before serializing; the smallest safe decomposition.
 4. Act: build in units that each end in a check (**Sequence verifiable units**).
 5. Verify: on the surface the user will use; an inconclusive or wrong-surface result is not a pass.