@hobin/developer 0.1.8 → 0.1.10

package/extensions/state.ts

@@ -16,6 +16,7 @@ export const PROTOCOL = "developer/v5" as const;
 export const ACTIVATION_ENTRY = "developer.activation" as const;
 export const FOCUS_ENTRY = "developer.question-focus" as const;
 export const ROUTE_TOOL = "developer_route_question" as const;
+export const REFERENCE_TOOL = "developer_load_reference" as const;
 export const JUDGMENT_TOOL = "developer_record_judgment" as const;
 export const MAX_RESPONSE_FIELDS = 20;
 export const MAX_RESPONSE_OPTIONS = 20;
@@ -69,6 +70,38 @@ export interface RouteAlternative {
 	reason: string;
 }
 
+export interface ReferencePolicyRoute {
+	id: string;
+	question: string;
+	trigger: string;
+	methodStep: string;
+	references: string[];
+	readOrder: "any" | "listed";
+	artifacts: string[];
+	stop: string;
+	separateWhen: string;
+}
+
+export interface ReferencePolicyExemption {
+	when: string;
+	evidence: string[];
+}
+
+export interface ReferenceLoad {
+	path: string;
+	reason: string;
+	contentSha256: string;
+	sourceTrace: string;
+	referenceRouteIds: string[];
+}
+
+export interface ReferenceLoadEvent extends ReferenceLoad {
+	protocol: typeof PROTOCOL;
+	kind: "reference-load";
+	routeId: string;
+	target: string;
+}
+
 export interface RouteEvent {
 	protocol: typeof PROTOCOL;
 	kind: "route";
@@ -78,6 +111,11 @@ export interface RouteEvent {
 	reason: string;
 	knownEvidence: string[];
 	consideredAlternatives: RouteAlternative[];
+	availableReferences: string[];
+	referenceRoutes: ReferencePolicyRoute[];
+	referenceExemptionCriteria?: ReferencePolicyExemption;
+	referencePolicySha256?: string;
+	loadedReferences: ReferenceLoad[];
 	targetQuestionId?: string;
 	methodLocation?: string;
 	executionProfile?: ImplementationProfile;
@@ -122,6 +160,17 @@ export interface QuestionUpdate {
 	basis: string[];
 }
 
+export interface ReferenceBasis extends ReferenceLoad {
+	trigger: string;
+	appliedRule: string;
+	artifact: string;
+}
+
+export interface ReferenceExemption {
+	reason: string;
+	evidence: string[];
+}
+
 export interface JudgmentEvent {
 	protocol: typeof PROTOCOL;
 	kind: "judgment";
@@ -131,6 +180,8 @@ export interface JudgmentEvent {
 	status: JudgmentStatus;
 	result: string;
 	basis: string[];
+	referenceBasis: ReferenceBasis[];
+	referenceExemption?: ReferenceExemption;
 	openedQuestions: PendingQuestion[];
 	questionUpdates: QuestionUpdate[];
 	artifacts: string[];
@@ -141,6 +192,7 @@ export type DeveloperEvent =
 	| ActivationEvent
 	| FocusEvent
 	| RouteEvent
+	| ReferenceLoadEvent
 	| JudgmentEvent;
 
 export interface DeveloperState {
@@ -240,6 +292,118 @@ function parseRouteAlternative(value: unknown): RouteAlternative | undefined {
 	return { target: value.target, reason: value.reason };
 }
 
+function parseReferencePolicyRoute(
+	value: unknown,
+): ReferencePolicyRoute | undefined {
+	if (
+		!isObject(value) ||
+		typeof value.id !== "string" ||
+		typeof value.trigger !== "string" ||
+		!isStringArray(value.references) ||
+		(value.readOrder !== undefined &&
+			value.readOrder !== "any" &&
+			value.readOrder !== "listed") ||
+		!isStringArray(value.artifacts) ||
+		(value.question !== undefined && typeof value.question !== "string") ||
+		(value.methodStep !== undefined && typeof value.methodStep !== "string") ||
+		(value.stop !== undefined && typeof value.stop !== "string") ||
+		(value.separateWhen !== undefined && typeof value.separateWhen !== "string")
+	) {
+		return undefined;
+	}
+	return {
+		id: value.id,
+		question:
+			typeof value.question === "string" ? value.question : value.trigger,
+		trigger: value.trigger,
+		methodStep:
+			typeof value.methodStep === "string"
+				? value.methodStep
+				: "legacy route without a recorded integration step",
+		references: value.references,
+		readOrder: value.readOrder === "listed" ? "listed" : "any",
+		artifacts: value.artifacts,
+		stop:
+			typeof value.stop === "string"
+				? value.stop
+				: "legacy route without a recorded stop",
+		separateWhen:
+			typeof value.separateWhen === "string"
+				? value.separateWhen
+				: "re-route against the current policy before extending this judgment",
+	};
+}
+
+function parseReferencePolicyExemption(
+	value: unknown,
+): ReferencePolicyExemption | undefined {
+	if (
+		!isObject(value) ||
+		typeof value.when !== "string" ||
+		!isStringArray(value.evidence)
+	) {
+		return undefined;
+	}
+	return { when: value.when, evidence: value.evidence };
+}
+
+function parseReferenceLoad(value: unknown): ReferenceLoad | undefined {
+	if (
+		!isObject(value) ||
+		typeof value.path !== "string" ||
+		typeof value.reason !== "string" ||
+		typeof value.contentSha256 !== "string" ||
+		typeof value.sourceTrace !== "string"
+	) {
+		return undefined;
+	}
+	if (
+		value.referenceRouteIds !== undefined &&
+		!isStringArray(value.referenceRouteIds)
+	) {
+		return undefined;
+	}
+	return {
+		path: value.path,
+		reason: value.reason,
+		contentSha256: value.contentSha256,
+		sourceTrace: value.sourceTrace,
+		referenceRouteIds: value.referenceRouteIds ?? [],
+	};
+}
+
+function parseReferenceBasis(value: unknown): ReferenceBasis | undefined {
+	const load = parseReferenceLoad(value);
+	if (
+		!load ||
+		!isObject(value) ||
+		typeof value.trigger !== "string" ||
+		typeof value.appliedRule !== "string" ||
+		typeof value.artifact !== "string"
+	) {
+		return undefined;
+	}
+	return {
+		...load,
+		trigger: value.trigger,
+		appliedRule: value.appliedRule,
+		artifact: value.artifact,
+	};
+}
+
+function parseReferenceExemption(
+	value: unknown,
+): ReferenceExemption | undefined {
+	if (
+		!isObject(value) ||
+		typeof value.reason !== "string" ||
+		!isStringArray(value.evidence)
+	) {
+		return undefined;
+	}
+	return { reason: value.reason, evidence: value.evidence };
+}
+
 function isQuestionResolutionOwner(
 	value: unknown,
 ): value is QuestionResolutionOwner {
@@ -437,6 +601,16 @@ export function normalizeDeveloperEvent(
 			!isStringArray(value.knownEvidence) ||
 			(value.consideredAlternatives !== undefined &&
 				!Array.isArray(value.consideredAlternatives)) ||
+			(value.availableReferences !== undefined &&
+				!isStringArray(value.availableReferences)) ||
+			(value.referenceRoutes !== undefined &&
+				!Array.isArray(value.referenceRoutes)) ||
+			(value.referenceExemptionCriteria !== undefined &&
+				!parseReferencePolicyExemption(value.referenceExemptionCriteria)) ||
+			(value.referencePolicySha256 !== undefined &&
+				typeof value.referencePolicySha256 !== "string") ||
+			(value.loadedReferences !== undefined &&
+				!Array.isArray(value.loadedReferences)) ||
 			(value.targetQuestionId !== undefined &&
 				typeof value.targetQuestionId !== "string") ||
 			(value.methodLocation !== undefined &&
@@ -453,6 +627,14 @@ export function normalizeDeveloperEvent(
 			: [];
 		if (consideredAlternatives.some((alternative) => !alternative))
 			return undefined;
+		const referenceRoutes = Array.isArray(value.referenceRoutes)
+			? value.referenceRoutes.map(parseReferencePolicyRoute)
+			: [];
+		if (referenceRoutes.some((route) => !route)) return undefined;
+		const loadedReferences = Array.isArray(value.loadedReferences)
+			? value.loadedReferences.map(parseReferenceLoad)
+			: [];
+		if (loadedReferences.some((reference) => !reference)) return undefined;
 		return {
 			protocol: PROTOCOL,
 			kind: "route",
@@ -462,6 +644,14 @@ export function normalizeDeveloperEvent(
 			reason: value.reason,
 			knownEvidence: value.knownEvidence,
 			consideredAlternatives: consideredAlternatives as RouteAlternative[],
+			availableReferences: value.availableReferences ?? [],
+			referenceRoutes: referenceRoutes as ReferencePolicyRoute[],
+			referenceExemptionCriteria:
+				value.referenceExemptionCriteria === undefined
+					? undefined
+					: parseReferencePolicyExemption(value.referenceExemptionCriteria),
+			referencePolicySha256: value.referencePolicySha256,
+			loadedReferences: loadedReferences as ReferenceLoad[],
 			targetQuestionId: value.targetQuestionId,
 			methodLocation: value.methodLocation,
 			executionProfile: value.executionProfile,
@@ -472,6 +662,24 @@ export function normalizeDeveloperEvent(
 		};
 	}
 
+	if (value.kind === "reference-load") {
+		const reference = parseReferenceLoad(value);
+		if (
+			!reference ||
+			typeof value.routeId !== "string" ||
+			typeof value.target !== "string"
+		) {
+			return undefined;
+		}
+		return {
+			protocol: PROTOCOL,
+			kind: "reference-load",
+			routeId: value.routeId,
+			target: value.target,
+			...reference,
+		};
+	}
+
 	if (value.kind !== "judgment") return undefined;
 	if (
 		typeof value.routeId !== "string" ||
@@ -481,13 +689,21 @@ export function normalizeDeveloperEvent(
 		typeof value.result !== "string" ||
 		!isStringArray(value.basis) ||
 		!isStringArray(value.artifacts) ||
-		!Array.isArray(value.openedQuestions)
+		!Array.isArray(value.openedQuestions) ||
+		(value.referenceBasis !== undefined &&
+			!Array.isArray(value.referenceBasis)) ||
+		(value.referenceExemption !== undefined &&
+			!parseReferenceExemption(value.referenceExemption))
 	) {
 		return undefined;
 	}
 
 	const openedQuestions = value.openedQuestions.map(parsePendingQuestion);
 	if (openedQuestions.some((question) => !question)) return undefined;
+	const referenceBasis = Array.isArray(value.referenceBasis)
+		? value.referenceBasis.map(parseReferenceBasis)
+		: [];
+	if (referenceBasis.some((basis) => !basis)) return undefined;
 	if (
 		value.questionUpdates !== undefined &&
 		!Array.isArray(value.questionUpdates)
@@ -506,6 +722,11 @@ export function normalizeDeveloperEvent(
 		status: value.status,
 		result: value.result,
 		basis: value.basis,
+		referenceBasis: referenceBasis as ReferenceBasis[],
+		referenceExemption:
+			value.referenceExemption === undefined
+				? undefined
+				: parseReferenceExemption(value.referenceExemption),
 		openedQuestions: openedQuestions as PendingQuestion[],
 		questionUpdates: questionUpdates as QuestionUpdate[],
 		artifacts: value.artifacts,
@@ -523,7 +744,11 @@ interface BranchEntryLike {
 	message?: { role?: string; toolName?: string; details?: unknown };
 }
 
-const DEVELOPER_TOOL_NAMES = new Set<string>([ROUTE_TOOL, JUDGMENT_TOOL]);
+const DEVELOPER_TOOL_NAMES = new Set<string>([
+	ROUTE_TOOL,
+	REFERENCE_TOOL,
+	JUDGMENT_TOOL,
+]);
 
 export function eventFromBranchEntry(
 	entry: BranchEntryLike,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hobin/developer",
-  "version": "0.1.8",
-  "description": "Adaptive product-development reasoning and evidence for Pi.",
+  "version": "0.1.10",
+  "description": "Branch-aware judgment routing, evidence gates, and focused development skills for Pi.",
   "type": "module",
   "keywords": ["pi-package", "pi", "developer", "skills"],
   "license": "MIT",
@@ -21,7 +21,13 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["extensions", "skills", "README.md", "SOURCES.md", "LICENSE"],
+  "files": [
+    "extensions",
+    "skills",
+    "README.md",
+    "REFERENCE_ROUTING.md",
+    "LICENSE"
+  ],
   "engines": {
     "node": ">=22.19.0"
   },

package/skills/abstraction-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: abstraction-review
-description: "Judge whether a concrete wished interface, helper, API, workflow rule, boundary, or structural candidate is stable enough to keep, revise, split, reject, or defer. Use when a concrete candidate and the pressure behind it can be inspected, including when its contract or evidence may be incomplete."
+description: "Judge whether an already-shaped wished interface, helper, API, workflow rule, boundary, or structural candidate is stable enough to keep, revise, split, reject, or defer. Use when concrete caller-facing shape and pressure can be inspected, even if evidence is incomplete. A desired representation or requested property list without an interface shape belongs to sketch, not abstraction review."
 ---
 
 # Abstraction Review
@@ -12,6 +12,19 @@ Decide whether a concrete abstraction candidate is safe to rely on.
 Is this candidate stable enough to keep, or should it be revised, split,
 rejected, or deferred?
 
+## Judgment Spine
+
+```text
+existing candidate + current pressure
+-> caller-visible promise and hidden detail
+-> smallest plausible counterexample
+-> observable stop and evidence
+-> keep | revise-surface | revise-model | split | reject | defer
+```
+
+Review only promises the candidate already makes. When operations, ownership, or
+rules still need to be invented, hand off instead of constructing them here.
+
 ## Inputs
 
 - Concrete candidate and the pressure it should remove
@@ -41,13 +54,9 @@ routing to the caller.
 
 ## Completion
 
-Finish when the candidate can satisfy this sentence or is rejected/deferred for
-failing it:
-
-```text
-Given <input artifact>, derive <output artifact> by <rule>, then check
-<observable stop>. If it fails, repair the named layer or contract.
-```
+Finish when each declared candidate promise is supported, contradicted, or left
+as an explicit gap, and one observable stop can fail the candidate. A failed stop
+produces a decision and owning-skill handoff, not an in-leaf redesign.
 
 Revisit when new callers, cases, implementation evidence, or failures change
 the contract or stop check.
@@ -57,13 +66,16 @@ the contract or stop check.
 1. Identify the candidate, its source, and confidence.
 2. State the pressure it is supposed to remove. Bias toward `reject` or `defer`
    when no pressure is visible.
-3. Review pre-implementation intent or post-implementation evidence explicitly.
-4. Choose the tested layer: Language, Unit, Law, Boundary, Engine, Time, or Run.
-5. State the contract in caller language and the detail callers may ignore.
-6. Name the reusable output artifact left by the review.
-7. Define an observable stop check using cases, properties, tests, diffs,
-   behavior, traces, or command output.
-8. Decide without converting missing evidence into polished approval.
+3. State the contract in caller language, its relevant observers, and the detail
+   callers may ignore.
+4. Name only the promises the candidate makes: representation, responsibility,
+   substitution, closure, extension, process, state, or stable sense.
+5. Construct the smallest plausible counterexample to one promise.
+6. Define an observable stop using cases, properties, tests, diffs, traces, cost,
+   or command output.
+7. Decide and name the owning handoff for any missing model, design, timing,
+   naming, or verification artifact.
+8. Do not convert missing evidence into polished approval or a shadow design.
 
 ## Missing Evidence
 
@@ -75,14 +87,16 @@ human-owned.
 ## Boundary
 
 Do not discover structural movement, create the original design surface, decide
-timing, implement the change, or perform final completion review.
+timing, implement the change, or perform final completion review. A desire such
+as “replace this array with an object” is pressure, not yet a reviewable
+abstraction, when public operations, caller shape, ownership, and hidden detail
+still have to be invented; route that work to `sketch`.
 
 ## Reference Routing
 
-- Read [the field card](references/field-card.md) for substantial or auditable
-  reviews.
-- Read [the recipe cards](references/recipe-cards.md) when the candidate needs a construction or
-  repair rule.
-- Read [the repair table](references/repair-table.md) when a stop check fails.
-- Read [the worked examples](references/worked-examples.md) for concrete
-  calibration.
+The machine-readable [reference policy](reference-policy.json) is the routing
+authority. Each route answers one narrower review question, identifies the exact
+judgment step it refines, names its artifacts and stop, and states when to
+separate or hand off. Select only routes that deepen this candidate judgment;
+never use a review reference to recreate another skill's construction method.
+Use the exemption only when no route trigger applies and cite its evidence.

package/skills/abstraction-review/reference-policy.json

@@ -0,0 +1,66 @@
+{
+  "version": 2,
+  "routes": [
+    {
+      "id": "candidate-contract-review",
+      "question": "Does this already-shaped candidate make a truthful, evidence-backed promise to its callers?",
+      "trigger": "A concrete caller-facing interface, helper, boundary, role, or workflow candidate exists and needs an auditable keep, revise, split, reject, or defer decision.",
+      "method_step": "evaluate the candidate contract, hidden detail, owner, counterexample, and observable stop after confirming that the surface already exists",
+      "references": [
+        "references/field-card.md"
+      ],
+      "artifacts": [
+        "a completed candidate field card",
+        "one explicit promise and plausible counterexample",
+        "an observable stop check and bounded decision"
+      ],
+      "stop": "The candidate's declared promises are supported, contradicted, or left as explicit evidence gaps without constructing a missing surface.",
+      "separate_when": "No concrete caller-facing surface exists, product rules are unresolved, only structural movement is visible, timing is the question, or completion evidence is the question; hand off to sketch, model, signal, schedule, naming-judgment, or verify."
+    },
+    {
+      "id": "failed-candidate-check",
+      "question": "Which candidate promise failed, and which skill owns the missing repair artifact?",
+      "trigger": "An observable candidate stop check failed or current evidence directly contradicts one of the candidate's promises.",
+      "method_step": "localize the earliest broken promise after the field-card review, then choose one revision class and handoff",
+      "read_order": "listed",
+      "references": [
+        "references/field-card.md",
+        "references/repair-table.md"
+      ],
+      "artifacts": [
+        "the reviewed candidate field card",
+        "a failure log naming the contradicted promise and observation",
+        "one revision class and owning-skill handoff"
+      ],
+      "stop": "The failed stop is localized to one promise and the same check can be rerun after the owning skill produces a revised candidate.",
+      "separate_when": "Repair requires inventing operations, settling policy, changing implementation, or gathering completion evidence; do not perform that work inside abstraction review."
+    },
+    {
+      "id": "candidate-calibration",
+      "question": "Which known promise-and-falsifier shape best calibrates an otherwise complete but ambiguous candidate review?",
+      "trigger": "The field card is complete, but keep versus revise, split, reject, or defer remains ambiguous and a matching candidate-promise example can resolve the interpretation.",
+      "method_step": "calibrate the completed review by promise and falsifier, never by superficial API resemblance",
+      "read_order": "listed",
+      "references": [
+        "references/field-card.md",
+        "references/worked-examples.md"
+      ],
+      "artifacts": [
+        "the reviewed candidate field card",
+        "the selected calibration's matching promise and counterexample",
+        "a case-calibrated decision with an open consequence"
+      ],
+      "stop": "One calibration changes or confirms the decision for a stated reason; unmatched examples do not expand the candidate.",
+      "separate_when": "No calibration shares the candidate's promise and falsifier; use the field card directly or hand off instead of extending the example catalog."
+    }
+  ],
+  "exemption": {
+    "when": "The candidate is small and concrete, and the SKILL.md judgment spine already exposes its pressure, caller promise, hidden detail, counterexample, stop check, decision, and handoff without an audit, failure-localization, or calibration gap.",
+    "evidence": [
+      "the exact existing candidate surface",
+      "the current pressure and caller-visible promise",
+      "the falsifying case and observable stop",
+      "why no routed review extension adds a missing distinction"
+    ]
+  }
+}