@hobin/developer 0.1.8 → 0.1.10

package/extensions/machine.ts

@@ -7,6 +7,7 @@ import type {
 	FocusEvent,
 	JudgmentEvent,
 	PendingQuestion,
+	ReferenceLoadEvent,
 	RouteEvent,
 } from "./state.ts";
 
@@ -14,6 +15,7 @@ type DeveloperMachineEvent =
 	| { type: "ACTIVATION"; event: ActivationEvent }
 	| { type: "FOCUS"; event: FocusEvent }
 	| { type: "ROUTE"; event: RouteEvent }
+	| { type: "REFERENCE_LOAD"; event: ReferenceLoadEvent }
 	| { type: "JUDGMENT"; event: JudgmentEvent };
 
 export type DeveloperMachineTag =
@@ -82,6 +84,37 @@ function applyRouteContext(
 	};
 }
 
+function applyReferenceLoadContext(
+	state: DeveloperState,
+	event: ReferenceLoadEvent,
+): DeveloperState {
+	const route = state.activeRoute;
+	if (!route || route.routeId !== event.routeId) return state;
+	const existingIndex = route.loadedReferences.findIndex(
+		(reference) => reference.path === event.path,
+	);
+	const existingReference = route.loadedReferences[existingIndex];
+	const loadedReference = {
+		path: event.path,
+		reason: event.reason,
+		contentSha256: event.contentSha256,
+		sourceTrace: event.sourceTrace,
+		referenceRouteIds: [
+			...new Set([
+				...(existingReference?.referenceRouteIds ?? []),
+				...event.referenceRouteIds,
+			]),
+		],
+	};
+	const loadedReferences = [...route.loadedReferences];
+	if (existingIndex === -1) loadedReferences.push(loadedReference);
+	else loadedReferences[existingIndex] = loadedReference;
+	return {
+		...state,
+		activeRoute: { ...route, loadedReferences },
+	};
+}
+
 function questionsAfterJudgment(
 	state: DeveloperState,
 	route: RouteEvent,
@@ -207,6 +240,8 @@ function reduceDeveloperContext(
 			return { ...state, focusedQuestionId: event.questionId };
 		case "route":
 			return applyRouteContext(state, event);
+		case "reference-load":
+			return applyReferenceLoadContext(state, event);
 		case "judgment":
 			return applyJudgmentContext(state, event);
 		default:
@@ -222,6 +257,8 @@ function machineEvent(event: DeveloperEvent): DeveloperMachineEvent {
 			return { type: "FOCUS", event };
 		case "route":
 			return { type: "ROUTE", event };
+		case "reference-load":
+			return { type: "REFERENCE_LOAD", event };
 		case "judgment":
 			return { type: "JUDGMENT", event };
 		default:
@@ -252,6 +289,13 @@ function canApplyEvent(
 						(question) => question.gate === "before-implementation",
 					))
 			);
+		case "REFERENCE_LOAD":
+			return (
+				context.enabled &&
+				context.activeRoute?.routeId === event.event.routeId &&
+				context.activeRoute.target === event.event.target &&
+				context.activeRoute.target !== "implementation"
+			);
 		case "JUDGMENT":
 			return (
 				context.enabled && context.activeRoute?.routeId === event.event.routeId
@@ -322,6 +366,7 @@ export const developerMachine = machineSetup.createMachine({
 		ACTIVATION: { guard: "eventAllowed", actions: "applyEvent" },
 		FOCUS: { guard: "eventAllowed", actions: "applyEvent" },
 		ROUTE: { guard: "eventAllowed", actions: "applyEvent" },
+		REFERENCE_LOAD: { guard: "eventAllowed", actions: "applyEvent" },
 		JUDGMENT: { guard: "eventAllowed", actions: "applyEvent" },
 	},
 	states: {

package/extensions/references/behavior-preserving-structural-change.md

@@ -15,11 +15,16 @@ Structural move: one concrete rearrangement
 Pressure: why the accepted task needs or benefits from it now
 Baseline evidence: the cheapest relevant check that is currently green
 Affected surface: files, callers, persisted forms, or public boundaries
+Runtime semantics: effects, evaluation/order, numeric representation, failure, termination
+Resource claim: unchanged / deliberately changed / not part of preserved behavior
 Stop: the next stable, pausable state
 ```
 
 If the behavior claim, timing, or candidate is still under judgment, close or
 pause the implementation route and route that question to the appropriate leaf.
+The behavior/structure distinction is observer-relative. Equal return values do
+not make a movement structural when it changes effects, exception timing,
+ordering, resource use, persistence, compatibility, or another admitted observer.
 
 ## Smallest Green Transformation
 
@@ -40,6 +45,52 @@ new shape parses
 For movement across a boundary, update one sender or caller at a time when the
 old and new forms can safely coexist. Confirm that each intermediate state is
 valid. Do not rely on a final large diff to explain which step changed behavior.
+A forwarding interface over the old implementation can be a temporary seam, but
+it is not evidence that the interface is a stable public abstraction.
+
+For suspected dead code, combine static references, dynamic reachability, and a
+scoped observation window appropriate to rare jobs, reflection, configuration,
+and external entry points. A log with no hits narrows uncertainty; it does not
+prove absence. Delete in a separately reversible step and retain the recovery
+path and residual risk.
+
+## Derive Completely, Then Simplify
+
+When a change affects cases or data shape, first make the complete case space
+explicit. Derive branches, selectors, candidate recursive calls, and failure
+cases from the accepted model; only then merge clauses or remove redundant guards
+with a stated preserving law. Guessing the compact version can omit a case while
+remaining green on a narrow suite.
+
+Propagate a changed data definition through:
+
+```text
+data and persisted examples
+-> behavior examples
+-> templates and collaborations
+-> implementations
+-> tests and properties
+-> callers, serializers, and public compatibility surfaces
+```
+
+A local type edit is not a stable landing while an old accepted form remains
+unhandled. Conversely, a structurally available selector or recursion may be
+absent from the final body when purpose explicitly proves it irrelevant.
+
+## Runtime-Semantic Boundary
+
+A source-level rearrangement is not behavior-preserving merely because an
+algebraic identity holds mathematically. Check whether the move changes:
+
+- short-circuiting, exception timing, effects, or repeated external reads;
+- floating-point association, overflow, underflow, or non-finite propagation;
+- collection order, duplicate handling, sharing, or mutation;
+- termination, branch starvation, or failure-versus-divergence behavior;
+- time, stack, allocation, or query/update complexity when resource behavior is
+  part of the accepted claim.
+
+If any item is intentionally changed, split that claim from the structural move
+and route it explicitly.
 
 ## Evidence Rhythm
 
@@ -49,9 +100,16 @@ Within the routed movement:
 2. inspect the diff for mixed behavior and structural changes;
 3. reduce the step when the failure cannot be explained locally;
 4. return to the declared green, deployable stable landing;
-5. close the implementation route there and let Developer re-observe and route
+5. distinguish local integration evidence from production deployment and
+   external-effect evidence;
+6. close the implementation route there and let Developer re-observe and route
    the next question instead of following a predetermined final design.
 
+Separate commits or pull requests can expose structural purpose, but repository
+policy, review latency, deployment independence, and team evidence determine the
+actual batch. Never infer “absolute safety” from a small diff or omit review only
+because a change is labeled a tidying.
+
 A passing test is useful only when it exercises the preserved behavior. When no
 cheap verifier exists, keep the movement smaller and record the residual risk.
 
@@ -139,12 +197,33 @@ The protocol is being misused when:
 ## Source Trace
 
 - Sandi Metz, Katrina Owen, and TJ Stankus, *99 Bottles of OOP*, Second
-  Edition, version 2.2.2, 2024: chapters 3-5 on methodical transformations,
-  flocking, gradual refactoring, stable landings, and sender-by-sender movement.
+  Edition, version 2.2.2, 2024: Chapters 3-5, pp. 51-137, especially
+  pp. 58-71, 84-101, and 113-125, on methodical transformations, flocking,
+  gradual refactoring, stable landings, and sender-by-sender movement.
 - Kent Beck, *Tidy First?: A Personal Exercise in Empirical Software Design*,
-  O'Reilly Media, 2023: separating behavior and structure, keeping tidyings
-  small, and managing structural change as optionality.
+  First Edition, Second Release, O'Reilly Media, 2025-12-12:
+  Part I, Chapters 1-15, pp. 3-32, for small structural moves, reversible seams,
+  dead-code observation, dependency-preserving reorder, extraction, inlining,
+  and communication; Part II, Chapters 16-20, pp. 35-50, for separating change
+  purposes, chaining, batches, rhythm, and untangling; and Chapter 28,
+  pp. 75-76, for reversibility pressure. The protocol narrows the source's
+  behavior observer and qualifies its PR, review, deployment, telemetry, and
+  absolute-safety claims; production recovery remains a Developer adaptation.
 - Matthias Felleisen, Robert Bruce Findler, Matthew Flatt, and Shriram
-  Krishnamurthi, *How to Design Programs, Second Edition*, MIT Press, 2018:
-  iterative refinement and propagating a changed data design through dependent
-  artifacts.
+  Krishnamurthi, *How to Design Programs*, official living build 9.2.0.3,
+  released 2026-05-28 and audited 2026-05-28:
+  Chapter 19
+  and Chapter 20
+  for model stabilization and staged simplification;
+  Chapter 23
+  for exhaustive case derivation followed by algebraic simplification;
+  Intermezzo 4
+  for order-sensitive inexact arithmetic;
+  Intermezzo 5
+  for resource-class changes; and
+  Chapter 31,
+  Chapter 32,
+  Chapter 33,
+  and Chapter 34
+  for accumulator transformations that may change order, totality, time, and
+  space.

package/extensions/skills.ts

@@ -1,74 +1,352 @@
-import { realpathSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { realpathSync, type Dirent } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
 import { isAbsolute, relative, resolve } from "node:path";
 
 import {
-  DEFAULT_MAX_BYTES,
-  DEFAULT_MAX_LINES,
-  stripFrontmatter,
-  type Skill,
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	stripFrontmatter,
+	type Skill,
 } from "@earendil-works/pi-coding-agent";
 
 const METHOD_OUTPUT_OVERHEAD_BYTES = 4096;
 const METHOD_OUTPUT_OVERHEAD_LINES = 20;
+const REFERENCE_PATH_PATTERN = /^references\/[^/]+\.md$/u;
+
+export interface LoadedSkillReference {
+	path: string;
+	filePath: string;
+	content: string;
+	contentSha256: string;
+	sourceTrace: string;
+}
+
+export interface SkillReferenceRoute {
+	id: string;
+	question: string;
+	trigger: string;
+	methodStep: string;
+	references: string[];
+	readOrder: "any" | "listed";
+	artifacts: string[];
+	stop: string;
+	separateWhen: string;
+}
+
+export interface SkillReferenceExemption {
+	when: string;
+	evidence: string[];
+}
+
+export interface SkillReferencePolicy {
+	routes: SkillReferenceRoute[];
+	exemption?: SkillReferenceExemption;
+	contentSha256?: string;
+}
 
 function escapeAttribute(value: string): string {
-  return value
-    .replaceAll("&", "&")
-    .replaceAll('"', """)
-    .replaceAll("<", "&lt;")
-    .replaceAll(">", "&gt;");
+	return value
+		.replaceAll("&", "&amp;")
+		.replaceAll('"', "&quot;")
+		.replaceAll("<", "&lt;")
+		.replaceAll(">", "&gt;");
 }
 
 export function isWithinRoot(root: string, path: string): boolean {
-  const canonical = (value: string) => {
-    try {
-      return realpathSync.native(value);
-    } catch {
-      return resolve(value);
-    }
-  };
-  const relation = relative(canonical(root), canonical(path));
-  return relation === "" || (!relation.startsWith("..") && !isAbsolute(relation));
+	const canonical = (value: string) => {
+		try {
+			return realpathSync.native(value);
+		} catch {
+			return resolve(value);
+		}
+	};
+	const relation = relative(canonical(root), canonical(path));
+	return (
+		relation === "" || (!relation.startsWith("..") && !isAbsolute(relation))
+	);
 }
 
 export function availablePackageSkills(
-  loadedSkills: Skill[],
-  skillsRoot: string,
+	loadedSkills: Skill[],
+	skillsRoot: string,
 ): Map<string, Skill> {
-  const available = new Map<string, Skill>();
+	const available = new Map<string, Skill>();
+
+	for (const skill of loadedSkills) {
+		if (skill.disableModelInvocation) continue;
+		if (!isWithinRoot(skillsRoot, skill.filePath)) continue;
+		if (available.has(skill.name))
+			throw new Error(
+				`Duplicate Pi-loaded Developer skill name: ${skill.name}`,
+			);
+		available.set(skill.name, skill);
+	}
+
+	return available;
+}
+
+export async function skillReferencePaths(skill: Skill): Promise<string[]> {
+	const referencesRoot = resolve(skill.baseDir, "references");
+	let entries: Dirent[];
+	try {
+		entries = await readdir(referencesRoot, { withFileTypes: true });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+
+	const paths: string[] = [];
+	for (const entry of entries) {
+		if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+		if (!isWithinRoot(referencesRoot, resolve(referencesRoot, entry.name)))
+			continue;
+		paths.push(`references/${entry.name}`);
+	}
+	return paths.sort((left, right) => left.localeCompare(right));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function parseNonEmptyStrings(value: unknown, label: string): string[] {
+	if (
+		!Array.isArray(value) ||
+		value.length === 0 ||
+		!value.every((item) => typeof item === "string" && item.trim().length > 0)
+	) {
+		throw new Error(`${label} must be a non-empty string array.`);
+	}
+	const strings = value.map((item) => item.trim());
+	if (new Set(strings).size !== strings.length) {
+		throw new Error(`${label} must not contain duplicates.`);
+	}
+	return strings;
+}
+
+function parseReferenceRoutes(
+	skill: Skill,
+	value: unknown,
+	catalog: string[],
+): SkillReferenceRoute[] {
+	if (!Array.isArray(value) || value.length === 0) {
+		throw new Error(
+			`Reference policy for ${skill.name} must contain at least one route.`,
+		);
+	}
+	const routes: SkillReferenceRoute[] = value.map((candidate, index) => {
+		if (
+			!isRecord(candidate) ||
+			typeof candidate.id !== "string" ||
+			!/^[a-z][a-z0-9-]*$/u.test(candidate.id) ||
+			typeof candidate.question !== "string" ||
+			candidate.question.trim().length === 0 ||
+			typeof candidate.trigger !== "string" ||
+			candidate.trigger.trim().length === 0 ||
+			typeof candidate.method_step !== "string" ||
+			candidate.method_step.trim().length === 0 ||
+			typeof candidate.stop !== "string" ||
+			candidate.stop.trim().length === 0 ||
+			typeof candidate.separate_when !== "string" ||
+			candidate.separate_when.trim().length === 0 ||
+			(candidate.read_order !== undefined &&
+				candidate.read_order !== "any" &&
+				candidate.read_order !== "listed")
+		) {
+			throw new Error(
+				`Reference policy for ${skill.name} has an invalid route at index ${index}.`,
+			);
+		}
+		const references = parseNonEmptyStrings(
+			candidate.references,
+			`Reference route ${candidate.id} references`,
+		);
+		if (
+			references.some(
+				(path) => !REFERENCE_PATH_PATTERN.test(path) || !catalog.includes(path),
+			)
+		) {
+			throw new Error(
+				`Reference route ${candidate.id} for ${skill.name} names an unavailable reference.`,
+			);
+		}
+		return {
+			id: candidate.id,
+			question: candidate.question.trim(),
+			trigger: candidate.trigger.trim(),
+			methodStep: candidate.method_step.trim(),
+			references,
+			readOrder: candidate.read_order === "listed" ? "listed" : "any",
+			artifacts: parseNonEmptyStrings(
+				candidate.artifacts,
+				`Reference route ${candidate.id} artifacts`,
+			),
+			stop: candidate.stop.trim(),
+			separateWhen: candidate.separate_when.trim(),
+		};
+	});
+	if (new Set(routes.map((route) => route.id)).size !== routes.length) {
+		throw new Error(
+			`Reference policy for ${skill.name} must use unique route IDs.`,
+		);
+	}
+	const covered = new Set(routes.flatMap((route) => route.references));
+	const unmapped = catalog.filter((path) => !covered.has(path));
+	if (unmapped.length > 0) {
+		throw new Error(
+			`Reference policy for ${skill.name} leaves references unrouted: ${unmapped.join(", ")}.`,
+		);
+	}
+	return routes;
+}
+
+function parseReferencePolicy(
+	skill: Skill,
+	source: string,
+	catalog: string[],
+): Omit<SkillReferencePolicy, "contentSha256"> {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(source);
+	} catch (error) {
+		throw new Error(`Invalid reference policy JSON for ${skill.name}.`, {
+			cause: error,
+		});
+	}
+	if (
+		!isRecord(parsed) ||
+		parsed.version !== 2 ||
+		!isRecord(parsed.exemption) ||
+		typeof parsed.exemption.when !== "string" ||
+		parsed.exemption.when.trim().length === 0
+	) {
+		throw new Error(
+			`Reference policy for ${skill.name} must declare version 2, judgment-integrated routes, and exemption criteria.`,
+		);
+	}
+	return {
+		routes: parseReferenceRoutes(skill, parsed.routes, catalog),
+		exemption: {
+			when: parsed.exemption.when.trim(),
+			evidence: parseNonEmptyStrings(
+				parsed.exemption.evidence,
+				`Reference policy ${skill.name} exemption evidence`,
+			),
+		},
+	};
+}
+
+export async function loadSkillReferencePolicy(
+	skill: Skill,
+	availableReferences?: string[],
+): Promise<SkillReferencePolicy> {
+	let catalog = availableReferences;
+	if (!catalog) catalog = await skillReferencePaths(skill);
+	const policyPath = resolve(skill.baseDir, "reference-policy.json");
+	let source: string;
+	try {
+		source = await readFile(policyPath, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			if (catalog.length > 0) {
+				throw new Error(
+					`Developer skill ${skill.name} has references but no reference-policy.json.`,
+				);
+			}
+			return { routes: [] };
+		}
+		throw error;
+	}
+
+	return {
+		...parseReferencePolicy(skill, source, catalog),
+		contentSha256: createHash("sha256")
+			.update(source.trim(), "utf8")
+			.digest("hex"),
+	};
+}
+
+function extractSourceTrace(content: string): string {
+	const lines = content.split(/\r?\n/);
+	const start = lines.findIndex((line) => line.trim() === "## Source Trace");
+	if (start === -1) return "";
+	const end = lines.findIndex(
+		(line, index) => index > start && /^##\s+/u.test(line),
+	);
+	return lines
+		.slice(start + 1, end === -1 ? undefined : end)
+		.join("\n")
+		.trim();
+}
+
+export async function loadSkillReference(
+	skill: Skill,
+	requestedPath: string,
+): Promise<LoadedSkillReference> {
+	const path = requestedPath.replaceAll("\\", "/").replace(/^\.\/+/, "");
+	if (!REFERENCE_PATH_PATTERN.test(path)) {
+		throw new Error(
+			`Developer references must use a direct skill-relative path such as references/example.md: ${requestedPath}`,
+		);
+	}
+
+	const available = await skillReferencePaths(skill);
+	if (!available.includes(path)) {
+		throw new Error(
+			`Reference ${path} is unavailable for ${skill.name}. Available references: ${available.join(", ") || "none"}.`,
+		);
+	}
 
-  for (const skill of loadedSkills) {
-    if (skill.disableModelInvocation) continue;
-    if (!isWithinRoot(skillsRoot, skill.filePath)) continue;
-    if (available.has(skill.name)) throw new Error(`Duplicate Pi-loaded Developer skill name: ${skill.name}`);
-    available.set(skill.name, skill);
-  }
+	const filePath = resolve(skill.baseDir, path);
+	if (!isWithinRoot(resolve(skill.baseDir, "references"), filePath)) {
+		throw new Error(
+			`Reference path escapes the ${skill.name} references directory.`,
+		);
+	}
+	const source = await readFile(filePath, "utf8");
+	const content = source.trim();
+	const contentBytes = Buffer.byteLength(content, "utf8");
+	const contentLines = content.split(/\r?\n/).length;
+	if (
+		contentBytes > DEFAULT_MAX_BYTES - METHOD_OUTPUT_OVERHEAD_BYTES ||
+		contentLines > DEFAULT_MAX_LINES - METHOD_OUTPUT_OVERHEAD_LINES
+	) {
+		throw new Error(
+			`Developer reference ${path} is too large for safe forced loading. Split it into focused direct references.`,
+		);
+	}
 
-  return available;
+	return {
+		path,
+		filePath,
+		content,
+		contentSha256: createHash("sha256").update(content, "utf8").digest("hex"),
+		sourceTrace: extractSourceTrace(content),
+	};
 }
 
 export async function renderSkillMethod(skill: Skill): Promise<string> {
-  const source = await readFile(skill.filePath, "utf8");
-  const body = stripFrontmatter(source).trim();
-  const bodyBytes = Buffer.byteLength(body, "utf8");
-  const bodyLines = body.split(/\r?\n/).length;
-  if (
-    bodyBytes > DEFAULT_MAX_BYTES - METHOD_OUTPUT_OVERHEAD_BYTES ||
-    bodyLines > DEFAULT_MAX_LINES - METHOD_OUTPUT_OVERHEAD_LINES
-  ) {
-    throw new Error(
-      `Developer skill ${skill.name} is too large for safe forced loading. Move detail into relative references before routing it.`,
-    );
-  }
-  const name = escapeAttribute(skill.name);
-  const location = escapeAttribute(skill.filePath);
-  const baseDir = escapeAttribute(skill.baseDir);
-  return [
-    `<developer-method name="${name}" location="${location}" base-dir="${baseDir}">`,
-    body,
-    "</developer-method>",
-    "",
-    `Resolve relative references from ${skill.baseDir}.`,
-  ].join("\n");
+	const source = await readFile(skill.filePath, "utf8");
+	const body = stripFrontmatter(source).trim();
+	const bodyBytes = Buffer.byteLength(body, "utf8");
+	const bodyLines = body.split(/\r?\n/).length;
+	if (
+		bodyBytes > DEFAULT_MAX_BYTES - METHOD_OUTPUT_OVERHEAD_BYTES ||
+		bodyLines > DEFAULT_MAX_LINES - METHOD_OUTPUT_OVERHEAD_LINES
+	) {
+		throw new Error(
+			`Developer skill ${skill.name} is too large for safe forced loading. Move detail into relative references before routing it.`,
+		);
+	}
+	const name = escapeAttribute(skill.name);
+	const location = escapeAttribute(skill.filePath);
+	const baseDir = escapeAttribute(skill.baseDir);
+	return [
+		`<developer-method name="${name}" location="${location}" base-dir="${baseDir}">`,
+		body,
+		"</developer-method>",
+		"",
+		`Resolve relative references from ${skill.baseDir}.`,
+	].join("\n");
 }