@hobin/developer 0.1.10 → 0.1.12

package/README.md

@@ -7,7 +7,7 @@ Use it when a task may hide product rules, consequential cases, ownership,
 compatibility, structural timing, or pass-but-wrong verification. Developer:
 
 - turns consequential uncertainty into explicit questions;
-- routes Pi to one of ten focused judgment skills;
+- routes Pi to one of eleven focused judgment skills;
 - loads deeper references only when an observable trigger calls for them;
 - keeps implementation, unresolved questions, and verification evidence visible
   on the current session branch.
@@ -70,6 +70,19 @@ The tests pass after this cache rewrite.
 Check what they do not prove before calling it done.
 ```
 
+For a scope-bound existing-code diagnosis and improvement plan, ask for Doctor
+explicitly and name a path, flow, boundary, package, or subsystem when you can:
+
+```text
+Run a thorough Doctor review of the checkout request-to-persistence flow.
+Preserve current external behavior, consult every triggered Developer judgment,
+and produce a now/next/observe/leave-alone plan without modifying files.
+```
+
+When no useful scope is supplied, Doctor performs a cheap orientation pass and
+proposes one. It distinguishes requested, inspected, and claim scope rather than
+presenting a repository sample as an exhaustive review.
+
 ## Why Developer
 
 Ordinary coding requests often contain decisions that look like implementation
@@ -84,7 +97,10 @@ details but are actually product, model, boundary, or evidence questions.
 | Branches lose rationale | Evidence replays with its branch |
 
 Developer coordinates judgment; Pi still reads, edits, runs, and tests the
-product with its normal tools.
+product with its normal tools. Across those judgments, an unchecked assertion,
+cast, non-null claim, or typed decode is never treated as evidence that a domain
+invariant holds: broader input must cross an owned parser or smart-constructor
+boundary whose success returns the refined value.
 
 ## How it works
 
@@ -115,9 +131,11 @@ and the plausible judgment routes add no useful information.
 
 | Need | Developer helps Pi… |
 | --- | --- |
+| Diagnose existing code | Bound the review, preserve behavior, consult triggered judgments, and order justified improvements |
 | Clarify a feature | Separate meaning, constraints, examples, and blockers |
 | Model behavior | Enumerate cases, contracts, transitions, and guarantees |
 | Shape code | Expose data, interfaces, collaboration, state, and checks |
+| Refine input safely | Turn broader input into invariant-carrying domain values before dependent effects |
 | Inspect a design | Identify structural movement and model-code mismatch |
 | Review an abstraction | Keep, revise, split, reject, or defer the candidate |
 | Time a refactor | Separate behavior work and judge the cost of delay |
@@ -133,6 +151,7 @@ directly with `/skill:<name>`.
 
 | Skill | Helps decide |
 | --- | --- |
+| `doctor` | What a bounded existing-code scope must preserve, treat, observe, or leave alone |
 | `specify` | Product meaning, scope, invariants, and blockers |
 | `model` | Cases, contracts, transitions, guarantees, and checks |
 | `sketch` | Data, interfaces, collaboration, flow, state, and code shape |
@@ -148,6 +167,14 @@ Each skill produces an artifact suited to its question instead of defaulting to
 undifferentiated prose. Simple judgments remain compact when prose is genuinely
 clearer.
 
+Doctor is an explicit coordination workflow, not the default front door for
+ordinary tasks. It first makes a broad, shallow disposition of every available
+Developer judgment lens inside a declared scope. It then closes so each
+triggered question can run through its owning skill and all reference-policy
+routes supported by observable evidence. A final Doctor route synthesizes those
+owner judgments into a treatment plan; Doctor never reads sibling references or
+replaces their methods with one giant checklist.
+
 ## Commands
 
 | Command | Effect |

package/REFERENCE_ROUTING.md

@@ -198,9 +198,10 @@ separation behavior, and pass-but-wrong cases.
 
 | Skill | Policy routes | Shape |
 | --- | --- | --- |
+| `doctor` | none | scope, preservation baseline, universal lens disposition, consultation ledger, diagnosis, and treatment order; owner skills select and apply their own references |
 | `abstraction-review` | `candidate-contract-review`, `failed-candidate-check`, `candidate-calibration` | review, failure localization, or promise-based calibration; no shadow construction |
 | `model` | `condition-space`, `contract-replacement`, `relational-constraints`, `temporal-behavior`, `proof-obligation`, `solver-result-boundary`, `logic-query-semantics`, `planning-model` | one model artifact per uncertainty and stop condition |
-| `sketch` | `data-driven-design`, `data-shape-template`, `composition-by-wishes`, `earned-abstraction`, `generative-recursion`, `accumulator-invariant`, `design-levels`, `representation-barrier`, `closure-interface`, `process-resources`, `state-history-order`, `generic-dispatch`, `meaning-preserving-conversion`, `language-semantics`, `runtime-compilation`, `responsibility-collaboration`, `variation-role`, `type-transition`, `selection-creation` | one implementable design question per route, with route-local common kernels only where required |
+| `sketch` | `data-driven-design`, `data-shape-template`, `composition-by-wishes`, `earned-abstraction`, `generative-recursion`, `accumulator-invariant`, `evidence-preserving-boundary`, `design-levels`, `representation-barrier`, `closure-interface`, `process-resources`, `state-history-order`, `generic-dispatch`, `meaning-preserving-conversion`, `language-semantics`, `runtime-compilation`, `responsibility-collaboration`, `variation-role`, `type-transition`, `selection-creation` | one implementable design question per route, with route-local common kernels only where required |
 | `signal` | `behavior-preserving-movement` | singleton |
 | `schedule` | `structural-timing-tradeoff` | singleton |
 | `naming-judgment` | `domain-sense-boundary` | singleton |
@@ -209,6 +210,14 @@ separation behavior, and pass-but-wrong cases.
 | `visualize` | none | no packaged reference |
 | `adversarial-eval` | none | no packaged reference |
 
+Doctor does not aggregate sibling reference files into its own policy. In a
+thorough Doctor review it dispositions every available skill, closes the Doctor
+triage route, and hands each triggered question to its owner skill. The owner
+route then applies this contract to every independently triggered policy route
+and co-required reference set before Doctor synthesizes the recorded judgments.
+This makes all references eligible without loading unrelated methods or losing
+route-local provenance.
+
 The implementation execution profile under `extensions/references/` is selected
 by `execution_profile`, not by skill reference routing, and remains a separate
 contract.

package/extensions/compaction-language.ts

@@ -264,7 +264,7 @@ export function reconstructCompactionLanguage(
 }
 
 export function continuityMarkerText(tag: LanguageTag): string {
-	return `Post-compaction continuity: user-visible prose language=${tag}; explicit language requests win.`;
+	return `Silent control: do not acknowledge or quote this marker; continue the current task. User-visible prose language=${tag}; explicit user language requests win.`;
 }
 
 export function continuityContextMessage(
@@ -295,9 +295,11 @@ export function projectCompactionContinuity<T>(
 			state: CompactionLanguageState;
 	  }
 	| undefined {
-	if (!state.pending) return undefined;
+	if (!state.pending || state.pending.injected) return undefined;
+	// Pi presents custom messages to the model as user messages. Prepend this
+	// one-shot control so the retained task remains the latest request.
 	return {
-		messages: [...messages, continuityContextMessage(state.pending, timestamp)],
+		messages: [continuityContextMessage(state.pending, timestamp), ...messages],
 		state: markContinuityInjected(state),
 	};
 }

package/extensions/developer.ts

@@ -53,6 +53,7 @@ import {
 	applyDeveloperEvent,
 	canApplyDeveloperEvent,
 	developerSnapshot,
+	formatInvariantHandling,
 	initialState,
 	normalizeDeveloperEvent,
 	parseChoiceResponseSpec,
@@ -62,6 +63,7 @@ import {
 	type ChoiceResponseSpec,
 	type DeveloperState,
 	type ImplementationProfile,
+	type InvariantHandling,
 	type FocusEvent,
 	type JudgmentEvent,
 	type PendingQuestion,
@@ -215,6 +217,59 @@ interface ChoiceResponseSpecInput {
 	fields: ChoiceResponseFieldInput[];
 }
 
+type InvariantHandlingInput =
+	| {
+			kind: "not-applicable";
+			reason: string;
+	  }
+	| {
+			kind: "evidence-preserving-boundary";
+			raw_representation: string;
+			refined_representation: string;
+			producer: string;
+			failure: string;
+			first_effect: string;
+	  }
+	| {
+			kind: "trusted-compiler-gap";
+			assertion: string;
+			established_by: string;
+			limitation: string;
+			containment: string;
+			verification: string;
+	  };
+
+function invariantHandlingFromInput(
+	input: InvariantHandlingInput | undefined,
+): InvariantHandling {
+	if (!input) {
+		return {
+			kind: "not-applicable",
+			reason:
+				"Legacy direct tool execution omitted the now-required invariant-handling declaration.",
+		};
+	}
+	if (input.kind === "not-applicable") return input;
+	if (input.kind === "evidence-preserving-boundary") {
+		return {
+			kind: input.kind,
+			rawRepresentation: input.raw_representation,
+			refinedRepresentation: input.refined_representation,
+			producer: input.producer,
+			failure: input.failure,
+			firstEffect: input.first_effect,
+		};
+	}
+	return {
+		kind: input.kind,
+		assertion: input.assertion,
+		establishedBy: input.established_by,
+		limitation: input.limitation,
+		containment: input.containment,
+		verification: input.verification,
+	};
+}
+
 interface OpenQuestionInput {
 	question: string;
 	context?: string;
@@ -460,9 +515,14 @@ function protocolPrompt(
 		"Developer protocol is active.",
 		"- Use the default topology as a conditional backbone, not a rigid lifecycle: clarify meaning when needed -> model consequential cases -> sketch the first implementation surface for new behavior or signal the smallest structural movement in existing code -> execute one implementation step -> verify current claims.",
 		"- Adapt away from that topology when evidence makes a stage not applicable, but never jump directly from a resolved model to mutation: use sketch for feature implementation or signal for existing-code structural movement first.",
+		"- Route doctor only for an explicitly requested scope-bound diagnosis and improvement plan across several judgment kinds; it is not a mandatory prelude, pull-request review, environment check, or synonym for ordinary implementation.",
+		"- A thorough Doctor review is broad and shallow before it is narrow and deep: establish requested, inspected, and claim scope; disposition every other available Developer skill with evidence; close Doctor triage; route every triggered distinct consultation to its owning skill; let that owner select and apply every triggered policy route and co-required reference; then return to Doctor to synthesize diagnosis and treatment order. Doctor must not load sibling references or flatten their methods into one checklist.",
+		"- While Doctor consultations remain, keep one agent-owned before-completion synthesis question and update its remaining consultation evidence after each owner judgment; do not open one pending question per lens. Resolve it only in the final Doctor synthesis route.",
 		"- Route by the requested work product, not keywords: use sketch to create an original caller-facing interface, representation boundary, ownership map, or collaboration; use abstraction-review only when a concrete candidate surface already exists to keep/revise/split/reject/defer; use model first only when unresolved cases, rules, or policy can materially change that surface.",
 		`- Call ${ROUTE_TOOL} for exactly one concrete judgment or one green-to-green implementation movement.`,
-		"- Use target=implementation only when the next local movement, stable landing, and narrow verification are already justified; otherwise choose the focused skill whose scope fits the current question.",
+		"- Use target=implementation only when the next local movement, stable landing, narrow verification, and invariant handling are already justified; otherwise choose the focused skill whose scope fits the current question.",
+		"- Invariant gate: an unchecked assertion, cast, non-null claim, ignored conversion result, or typed deserialization target is not evidence that broader, external, persisted, legacy, or otherwise less-trusted input satisfies a domain invariant. Parse or construct a refined value whose success carries the learned information before dependent effects; validation followed by narrowing does not satisfy this gate.",
+		"- Every implementation route must classify invariant handling as not applicable, an evidence-preserving boundary, or a trusted compiler gap. A trusted compiler gap is valid only after a complete check or trusted contract already established the fact, the language cannot retain it, the unsafe operation is isolated to one owner, and a falsifier is named. Encountering a missing boundary requires sketch, not an implementation assertion.",
 		"- An implementation step has one observable difference and one structural or behavioral purpose. Stop when its failure is locally explainable and the repository is green, pausable, and reviewable.",
 		"- For implementation structural work intended to preserve behavior, set execution_profile=behavior-preserving-structure; omit the field for other implementation actions and every skill route.",
 		`- Follow the routed method, then close the route with ${JUDGMENT_TOOL}. After every implementation stable landing, route again from the new evidence before selecting another movement.`,
@@ -511,6 +571,11 @@ function protocolPrompt(
 		lines.push(
 			`Active route: ${state.activeRoute.routeId} · ${state.activeRoute.target} · ${state.activeRoute.question}`,
 		);
+		if (state.activeRoute.implementationStep) {
+			lines.push(
+				`Active invariant handling: ${formatInvariantHandling(state.activeRoute.implementationStep.invariantHandling)}. Stop and route sketch instead of mutating if this declaration is contradicted by the code.`,
+			);
+		}
 		if (state.activeRoute.methodLocation) {
 			lines.push(
 				`Active skill location: ${state.activeRoute.methodLocation}. Read it again if compaction or a later turn no longer contains the full instructions.`,
@@ -825,6 +890,83 @@ export default async function developer(pi: ExtensionAPI) {
 		},
 		{ additionalProperties: false },
 	);
+	const InvariantHandlingParam = Type.Union([
+		Type.Object(
+			{
+				kind: Type.Literal("not-applicable"),
+				reason: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+					description:
+						"Why this movement neither creates nor narrows broader or less-trusted data into an invariant-carrying value",
+				}),
+			},
+			{ additionalProperties: false },
+		),
+		Type.Object(
+			{
+				kind: Type.Literal("evidence-preserving-boundary"),
+				raw_representation: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+				}),
+				refined_representation: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+				}),
+				producer: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+					description:
+						"Parser, refinement function, or smart constructor whose success returns the refined value",
+				}),
+				failure: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+				}),
+				first_effect: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+					description:
+						"First dependent domain effect allowed only after successful refinement",
+				}),
+			},
+			{ additionalProperties: false },
+		),
+		Type.Object(
+			{
+				kind: Type.Literal("trusted-compiler-gap"),
+				assertion: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+				}),
+				established_by: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+					description:
+						"Complete check or trusted runtime contract that already established the asserted fact",
+				}),
+				limitation: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+					description:
+						"Why ordinary language narrowing cannot retain the established fact",
+				}),
+				containment: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+					description: "Single parser or constructor owner containing the gap",
+				}),
+				verification: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+					description:
+						"Falsifier for the claimed prior evidence and containment",
+				}),
+			},
+			{ additionalProperties: false },
+		),
+	]);
 	const RouteParams = Type.Union([
 		Type.Object(
 			{
@@ -867,6 +1009,7 @@ export default async function developer(pi: ExtensionAPI) {
 					description:
 						"The narrowest check that can catch the likely break in this movement",
 				}),
+				invariant_handling: InvariantHandlingParam,
 				alternatives_considered: Type.Optional(
 					Type.Array(RouteAlternativeParam, {
 						maxItems: 6,
@@ -892,11 +1035,11 @@ export default async function developer(pi: ExtensionAPI) {
 		name: ROUTE_TOOL,
 		label: "Developer Route Question",
 		description:
-			"Route one concrete judgment or one green-to-green implementation movement. Route by work product: sketch creates an original design surface, abstraction-review judges an already-shaped candidate, and model settles unresolved conditions before design. Then use implementation stable landings and verify before completion.",
+			"Route one concrete judgment or one green-to-green implementation movement. Route by work product: doctor coordinates an explicitly requested scope-bound existing-code diagnosis, sketch creates an original design surface, abstraction-review judges an already-shaped candidate, and model settles unresolved conditions before design. Implementation must declare how invariant-bearing values are constructed without unchecked narrowing. Then use stable landings and verify before completion.",
 		promptSnippet: "Choose how to handle one development question",
 		promptGuidelines: [
 			`Call ${ROUTE_TOOL} only when there is no active Developer route.`,
-			`Use ${ROUTE_TOOL} with the most focused skill supported by current evidence; choose sketch for an original interface or boundary, abstraction-review only for an already-shaped candidate, and model only for unresolved condition space. target=implementation requires one movement, one stable landing, and one narrow verification.`,
+			`Use ${ROUTE_TOOL} with the most focused skill supported by current evidence; choose doctor only for an explicit scope-bound existing-code diagnosis and improvement plan, choose sketch for an original interface or boundary, abstraction-review only for an already-shaped candidate, and model only for unresolved condition space. target=implementation requires one movement, one stable landing, one narrow verification, and a truthful invariant_handling declaration. Validation followed by an assertion is not an evidence-preserving boundary.`,
 			`When ${ROUTE_TOOL} follows an implementation judgment with another implementation route, cite the previous landing in known_evidence and record plausible skill routes in alternatives_considered instead of selecting implementation by momentum.`,
 			`After a resolved model, use sketch for first feature implementation framing or signal for existing-code structural movement before implementation mutation.`,
 		],
@@ -1041,6 +1184,10 @@ export default async function developer(pi: ExtensionAPI) {
 						"# Implementation action",
 						"",
 						"The next local action is already justified. Keep this route open while using Pi implementation tools and collecting evidence.",
+						"",
+						"## Invariant gate",
+						"",
+						"Follow the route's invariant-handling declaration. Broader or less-trusted input must become an invariant-carrying value through a parser, refinement function, or smart constructor before dependent effects. Validation followed by an assertion, cast, non-null claim, ignored conversion result, or typed decode is not evidence. If the declared handling is incomplete, stop without mutation and route sketch. Keep any trusted compiler gap isolated to its declared owner and verify its prior evidence and containment.",
 					].join("\n");
 				}
 
@@ -1059,6 +1206,11 @@ export default async function developer(pi: ExtensionAPI) {
 									? params.verification
 									: "Run the narrowest relevant check and inspect the resulting diff or output."
 								).trim(),
+								invariantHandling: invariantHandlingFromInput(
+									"invariant_handling" in params
+										? params.invariant_handling
+										: undefined,
+								),
 							}
 						: undefined;
 
@@ -1096,6 +1248,7 @@ export default async function developer(pi: ExtensionAPI) {
 								`Movement: ${implementationStep.movement}`,
 								`Stable landing: ${implementationStep.stopCondition}`,
 								`Narrow verification: ${implementationStep.verification}`,
+								`Invariant handling: ${formatInvariantHandling(implementationStep.invariantHandling)}`,
 								"Stop this implementation route at that landing, record the evidence, and route again before another movement.",
 							]
 						: []),
@@ -1111,6 +1264,11 @@ export default async function developer(pi: ExtensionAPI) {
 								`Reference contract: choose policy routes by observable trigger, use ${REFERENCE_TOOL} for every reference in each selected route's co-required set, and provide reference_basis for every loaded path; use reference_exemption only when no policy route applies.`,
 							]
 						: []),
+					...(skill && event.availableReferences.length === 0
+						? [
+								"Reference contract: this skill has no packaged references; omit both reference_basis and reference_exemption from its judgment.",
+							]
+						: []),
 					`Known evidence: ${event.knownEvidence.length > 0 ? event.knownEvidence.join(" | ") : "none"}`,
 					`Alternatives reconsidered: ${
 						event.consideredAlternatives.length > 0
@@ -1173,7 +1331,8 @@ export default async function developer(pi: ExtensionAPI) {
 					context.lastComponent,
 				);
 			}
-			const event = result.details as RouteEvent | undefined;
+			const normalized = normalizeDeveloperEvent(result.details);
+			const event = normalized?.kind === "route" ? normalized : undefined;
 			let text = theme.fg("success", `routed ${routeRenderText(event)}`);
 			if (expanded && event) {
 				text += `\n${detailLine(theme, "route", event.routeId, "text")}`;
@@ -1207,6 +1366,7 @@ export default async function developer(pi: ExtensionAPI) {
 					text += `\n${detailLine(theme, "movement", event.implementationStep.movement, "text")}`;
 					text += `\n${detailLine(theme, "landing", event.implementationStep.stopCondition)}`;
 					text += `\n${detailLine(theme, "verify", event.implementationStep.verification)}`;
+					text += `\n${detailLine(theme, "invariant", formatInvariantHandling(event.implementationStep.invariantHandling))}`;
 				}
 			}
 			if (!expanded && event)
@@ -1382,7 +1542,9 @@ export default async function developer(pi: ExtensionAPI) {
 					context.lastComponent,
 				);
 			}
-			const event = result.details as ReferenceLoadEvent | undefined;
+			const normalized = normalizeDeveloperEvent(result.details);
+			const event =
+				normalized?.kind === "reference-load" ? normalized : undefined;
 			let text = theme.fg(
 				"success",
 				`loaded ${event?.path ?? "Developer reference"}`,
@@ -1619,7 +1781,7 @@ export default async function developer(pi: ExtensionAPI) {
 		promptGuidelines: [
 			`Use ${JUDGMENT_TOOL} with the exact active Developer route ID.`,
 			`Use ${JUDGMENT_TOOL} result as Markdown and preserve the routed skill's inspectable tables, diagrams, matrices, timelines, and code blocks instead of reducing them to prose.`,
-			`For a resolved skill route with available references, use ${JUDGMENT_TOOL} reference_basis to connect each relied-on ${REFERENCE_TOOL} load to its trigger, applied rule, and resulting artifact, or use reference_exemption when no reference is relevant. Never provide both.`,
+			`For a resolved skill route with available references, use ${JUDGMENT_TOOL} reference_basis to connect each relied-on ${REFERENCE_TOOL} load to its trigger, applied rule, and resulting artifact, or use reference_exemption when no reference is relevant. Never provide both. For a skill with no packaged references, omit both fields.`,
 			`Use ${JUDGMENT_TOOL} open_questions with resolution_owner, gate, and resolution_criteria. User-owned gated questions require explanatory context before controls; for finite required decisions, add a choice-form response_spec with one field per decision. Use question_updates whenever current evidence settles or changes any existing pending question.`,
 			`Do not use ${JUDGMENT_TOOL} with resolved, not-applicable, or blocked status without at least one concrete basis.`,
 		],
@@ -2011,7 +2173,8 @@ export default async function developer(pi: ExtensionAPI) {
 					context.lastComponent,
 				);
 			}
-			const event = result.details as JudgmentEvent | undefined;
+			const normalized = normalizeDeveloperEvent(result.details);
+			const event = normalized?.kind === "judgment" ? normalized : undefined;
 			const summary = judgmentRenderText(event);
 			let text =
 				event?.status === "resolved"

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

@@ -46,7 +46,10 @@ 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.
+it is not evidence that the interface is a stable public abstraction. An
+assertion, cast, non-null claim, or unchecked typed decode is not a compatibility
+seam: if old or external data is broader than the new invariant, an adapter must
+parse and return the new representation or explicit failure.
 
 For suspected dead code, combine static references, dynamic reachability, and a
 scoped observation window appropriate to rare jobs, reflection, configuration,
@@ -192,10 +195,15 @@ The protocol is being misused when:
 - behavior work is hidden inside a structural label;
 - the route continues after a new human-owned policy question appears;
 - an intermediate state cannot safely run or be reviewed;
-- cleanup continues past the accepted pressure because the code could be nicer.
+- cleanup continues past the accepted pressure because the code could be nicer;
+- validation is preserved while its result is discarded and an assertion claims
+  the new representation.
 
 ## Source Trace
 
+- Alexis King, “Parse, don’t validate,” published November 5, 2019, for
+  evidence-preserving refinement before execution. The compatibility-seam and
+  migration wording is a Developer adaptation.
 - Sandi Metz, Katrina Owen, and TJ Stankus, *99 Bottles of OOP*, Second
   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,

package/extensions/skills.ts

@@ -86,13 +86,17 @@ export function availablePackageSkills(
 	return available;
 }
 
+function hasErrorCode(error: unknown, code: string): boolean {
+	return isRecord(error) && error.code === code;
+}
+
 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 [];
+		if (hasErrorCode(error, "ENOENT")) return [];
 		throw error;
 	}
 
@@ -248,7 +252,7 @@ export async function loadSkillReferencePolicy(
 	try {
 		source = await readFile(policyPath, "utf8");
 	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+		if (hasErrorCode(error, "ENOENT")) {
 			if (catalog.length > 0) {
 				throw new Error(
 					`Developer skill ${skill.name} has references but no reference-policy.json.`,