@hobin/developer 0.1.10 → 0.1.12

package/extensions/state.ts

@@ -46,6 +46,36 @@ export type QuestionUpdateStatus =
 export type ImplementationProfile =
 	| "ordinary"
 	| "behavior-preserving-structure";
+export type InvariantHandling =
+	| {
+			kind: "not-applicable";
+			reason: string;
+	  }
+	| {
+			kind: "evidence-preserving-boundary";
+			rawRepresentation: string;
+			refinedRepresentation: string;
+			producer: string;
+			failure: string;
+			firstEffect: string;
+	  }
+	| {
+			kind: "trusted-compiler-gap";
+			assertion: string;
+			establishedBy: string;
+			limitation: string;
+			containment: string;
+			verification: string;
+	  };
+
+export function formatInvariantHandling(value: InvariantHandling): string {
+	if (value.kind === "not-applicable")
+		return `not applicable — ${value.reason}`;
+	if (value.kind === "evidence-preserving-boundary") {
+		return `${value.rawRepresentation} -> ${value.refinedRepresentation} via ${value.producer}; failure=${value.failure}; first effect=${value.firstEffect}`;
+	}
+	return `trusted compiler gap — ${value.assertion}; established by ${value.establishedBy}; limitation=${value.limitation}; contained at ${value.containment}; check=${value.verification}`;
+}
 
 export interface ActivationEvent {
 	protocol: typeof PROTOCOL;
@@ -63,6 +93,7 @@ export interface ImplementationStepContract {
 	movement: string;
 	stopCondition: string;
 	verification: string;
+	invariantHandling: InvariantHandling;
 }
 
 export interface RouteAlternative {
@@ -248,6 +279,20 @@ function isStringArray(value: unknown): value is string[] {
 	);
 }
 
+function parseArray<T>(
+	value: unknown,
+	parse: (item: unknown) => T | undefined,
+): T[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	const parsed: T[] = [];
+	for (const item of value) {
+		const result = parse(item);
+		if (result === undefined) return undefined;
+		parsed.push(result);
+	}
+	return parsed;
+}
+
 function isJudgmentStatus(value: unknown): value is JudgmentStatus {
 	return (
 		value === "resolved" ||
@@ -263,6 +308,51 @@ function isImplementationProfile(
 	return value === "ordinary" || value === "behavior-preserving-structure";
 }
 
+function parseInvariantHandling(value: unknown): InvariantHandling | undefined {
+	if (!isObject(value) || typeof value.kind !== "string") return undefined;
+	if (value.kind === "not-applicable") {
+		if (typeof value.reason !== "string") return undefined;
+		return { kind: value.kind, reason: value.reason };
+	}
+	if (value.kind === "evidence-preserving-boundary") {
+		if (
+			typeof value.rawRepresentation !== "string" ||
+			typeof value.refinedRepresentation !== "string" ||
+			typeof value.producer !== "string" ||
+			typeof value.failure !== "string" ||
+			typeof value.firstEffect !== "string"
+		) {
+			return undefined;
+		}
+		return {
+			kind: value.kind,
+			rawRepresentation: value.rawRepresentation,
+			refinedRepresentation: value.refinedRepresentation,
+			producer: value.producer,
+			failure: value.failure,
+			firstEffect: value.firstEffect,
+		};
+	}
+	if (value.kind !== "trusted-compiler-gap") return undefined;
+	if (
+		typeof value.assertion !== "string" ||
+		typeof value.establishedBy !== "string" ||
+		typeof value.limitation !== "string" ||
+		typeof value.containment !== "string" ||
+		typeof value.verification !== "string"
+	) {
+		return undefined;
+	}
+	return {
+		kind: value.kind,
+		assertion: value.assertion,
+		establishedBy: value.establishedBy,
+		limitation: value.limitation,
+		containment: value.containment,
+		verification: value.verification,
+	};
+}
+
 function parseImplementationStep(
 	value: unknown,
 ): ImplementationStepContract | undefined {
@@ -274,10 +364,20 @@ function parseImplementationStep(
 	) {
 		return undefined;
 	}
+	const invariantHandling =
+		value.invariantHandling === undefined
+			? {
+					kind: "not-applicable" as const,
+					reason:
+						"Legacy implementation route predates the invariant-handling declaration.",
+				}
+			: parseInvariantHandling(value.invariantHandling);
+	if (!invariantHandling) return undefined;
 	return {
 		movement: value.movement,
 		stopCondition: value.stopCondition,
 		verification: value.verification,
+		invariantHandling,
 	};
 }
 
@@ -622,19 +722,21 @@ export function normalizeDeveloperEvent(
 		) {
 			return undefined;
 		}
-		const consideredAlternatives = Array.isArray(value.consideredAlternatives)
-			? value.consideredAlternatives.map(parseRouteAlternative)
-			: [];
-		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;
+		const consideredAlternatives =
+			value.consideredAlternatives === undefined
+				? []
+				: parseArray(value.consideredAlternatives, parseRouteAlternative);
+		if (!consideredAlternatives) return undefined;
+		const referenceRoutes =
+			value.referenceRoutes === undefined
+				? []
+				: parseArray(value.referenceRoutes, parseReferencePolicyRoute);
+		if (!referenceRoutes) return undefined;
+		const loadedReferences =
+			value.loadedReferences === undefined
+				? []
+				: parseArray(value.loadedReferences, parseReferenceLoad);
+		if (!loadedReferences) return undefined;
 		return {
 			protocol: PROTOCOL,
 			kind: "route",
@@ -643,15 +745,15 @@ export function normalizeDeveloperEvent(
 			target: value.target,
 			reason: value.reason,
 			knownEvidence: value.knownEvidence,
-			consideredAlternatives: consideredAlternatives as RouteAlternative[],
+			consideredAlternatives,
 			availableReferences: value.availableReferences ?? [],
-			referenceRoutes: referenceRoutes as ReferencePolicyRoute[],
+			referenceRoutes,
 			referenceExemptionCriteria:
 				value.referenceExemptionCriteria === undefined
 					? undefined
 					: parseReferencePolicyExemption(value.referenceExemptionCriteria),
 			referencePolicySha256: value.referencePolicySha256,
-			loadedReferences: loadedReferences as ReferenceLoad[],
+			loadedReferences,
 			targetQuestionId: value.targetQuestionId,
 			methodLocation: value.methodLocation,
 			executionProfile: value.executionProfile,
@@ -698,21 +800,21 @@ export function normalizeDeveloperEvent(
 		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)
-	)
-		return undefined;
-	const questionUpdates = Array.isArray(value.questionUpdates)
-		? value.questionUpdates.map(parseQuestionUpdate)
-		: [];
-	if (questionUpdates.some((update) => !update)) return undefined;
+	const openedQuestions = parseArray(
+		value.openedQuestions,
+		parsePendingQuestion,
+	);
+	if (!openedQuestions) return undefined;
+	const referenceBasis =
+		value.referenceBasis === undefined
+			? []
+			: parseArray(value.referenceBasis, parseReferenceBasis);
+	if (!referenceBasis) return undefined;
+	const questionUpdates =
+		value.questionUpdates === undefined
+			? []
+			: parseArray(value.questionUpdates, parseQuestionUpdate);
+	if (!questionUpdates) return undefined;
 	return {
 		protocol: PROTOCOL,
 		kind: "judgment",
@@ -722,13 +824,13 @@ export function normalizeDeveloperEvent(
 		status: value.status,
 		result: value.result,
 		basis: value.basis,
-		referenceBasis: referenceBasis as ReferenceBasis[],
+		referenceBasis,
 		referenceExemption:
 			value.referenceExemption === undefined
 				? undefined
 				: parseReferenceExemption(value.referenceExemption),
-		openedQuestions: openedQuestions as PendingQuestion[],
-		questionUpdates: questionUpdates as QuestionUpdate[],
+		openedQuestions,
+		questionUpdates,
 		artifacts: value.artifacts,
 		changedArtifacts:
 			typeof value.changedArtifacts === "boolean"

package/extensions/tui.ts

@@ -22,6 +22,7 @@ import {
 } from "@earendil-works/pi-tui";
 
 import {
+	formatInvariantHandling,
 	protocolState,
 	type ChoiceResponseField,
 	type ChoiceResponseOption,
@@ -1416,6 +1417,10 @@ export class DeveloperHistoryDetailPanel {
 				addField("movement", route.implementationStep.movement);
 				addField("stop condition", route.implementationStep.stopCondition);
 				addField("verification", route.implementationStep.verification);
+				addField(
+					"invariant handling",
+					formatInvariantHandling(route.implementationStep.invariantHandling),
+				);
 			}
 			addValues("known evidence", route.knownEvidence);
 			addValues(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hobin/developer",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Branch-aware judgment routing, evidence gates, and focused development skills for Pi.",
   "type": "module",
   "keywords": ["pi-package", "pi", "developer", "skills"],

package/skills/doctor/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: doctor
+description: "Diagnose a user-selected or explicitly bounded existing codebase scope and produce an evidence-backed improvement plan. Use for repository, package, directory, module, runtime-flow, boundary, or feature-slice review when behavior to preserve, invariant risk, structural pressure, evidence gaps, and justified now/next/later/leave-alone work must be assessed together. Not for pull-request diff review, environment setup checks, speculative cleanup, or automatic repair."
+---
+
+# Doctor
+
+Diagnose one bounded existing-code scope, consult the focused Developer judgments
+that its evidence actually triggers, and synthesize a treatment plan without
+turning age, style, or code smells into disease.
+
+## Core Question
+
+Within this explicit codebase scope, what must be preserved, what is at risk or
+obstructing change, and what should be treated now, prepared next, observed, or
+left alone?
+
+## Judgment Spine
+
+```text
+requested target and change horizon
+-> requested / inspected / claim scope
+-> behavior-preservation baseline
+-> broad, shallow disposition of every Developer judgment lens
+-> narrow, deep owner-skill consultations and triggered references
+-> evidence-backed mechanisms and treatment candidates
+-> treat-now | prepare-next | observe | leave-alone | needs-decision
+-> first concrete handoff
+```
+
+Doctor is broad in lens coverage and bounded in code coverage. It is not a fixed
+prelude for ordinary tasks.
+
+## Inputs
+
+- User-selected target, or evidence sufficient to propose one
+- Repository structure, entry points, callers, runtime flows, and public boundaries
+- Accepted behavior, tests, traces, incidents, schemas, and compatibility evidence
+- Current change pressure and intended horizon when available
+- Explicit review depth, lenses, exclusions, and evidence budget
+
+## Scope Contract
+
+Establish scope before diagnosis. Separate what was requested from what was
+actually inspected and from the area to which conclusions may apply.
+
+| Field | Required meaning |
+| --- | --- |
+| Requested target | What the user asked Doctor to review |
+| Selected scope | Path, symbol, runtime flow, boundary, feature slice, subsystem, or repository sample |
+| Included | Concrete paths, symbols, entry points, flows, or collaborators admitted |
+| Excluded | Nearby areas this review does not cover |
+| Depth | `local`, `collaborators`, `flow`, `subsystem`, or `repository-sample` |
+| Lenses | Requested concerns, or `balanced` when no concern dominates |
+| Evidence budget | Bounded files, history, commands, traces, or sampling rule |
+| Inspected scope | Evidence actually read or executed |
+| Claim boundary | The largest area current evidence can support conclusions about |
+
+If the user did not select a useful scope, perform only a cheap orientation pass:
+inspect manifests, subsystem boundaries, entry points, current failures or
+requests, recent change pressure, dependency hubs, and irreversible effects.
+Then propose the smallest valuable scope with evidence. Do not call an
+orientation sample a whole-repository diagnosis.
+
+A dependency outside scope may be inspected when the declared depth includes it.
+Otherwise present a scope-expansion candidate with the trigger, added surface,
+expected value, and cost. Never expand recursively by curiosity.
+
+## Review Mode
+
+Use `thorough-within-scope` unless the user explicitly asks for a faster pass.
+
+- `quick`: inspect the strongest observable risk and label all omitted lenses and
+  code surfaces as unreviewed;
+- `standard`: disposition every Developer lens, then deepen only the
+  highest-consequence or currently pressured consultations;
+- `thorough-within-scope`: disposition every available Developer lens, route
+  every triggered distinct consultation, inspect every policy-route trigger in
+  each selected owner skill, and apply every reference required by every
+  selected route.
+
+Exhaustiveness applies to judgment coverage inside the claim boundary, not to
+unbounded file traversal or unsupported whole-system claims.
+
+## Evidence Order
+
+Prefer evidence in this order while keeping disagreements visible:
+
+1. accepted user or product contract;
+2. observed externally meaningful behavior, production trace, incident, or
+   compatibility obligation;
+3. executable tests and fixtures whose observers match the claim;
+4. callers, state transitions, persisted representations, and effect order;
+5. implementation structure and static relationships;
+6. history, churn, coverage counts, complexity, and code smells as scope or
+   pressure clues only.
+
+A smell becomes a finding only when it is connected to a behavior, invariant,
+change cost, failure mode, evidence gap, or compatibility consequence. Age,
+language fashion, low coverage, duplication, or a long function alone does not
+justify treatment.
+
+## Preservation Baseline
+
+Before finding defects, record behavior and obligations that treatment must not
+break.
+
+| Behavior or contract | Owner / observers | Evidence | Confidence | Failure consequence |
+| --- | --- | --- | --- | --- |
+
+Cover relevant public APIs, critical user flows, persisted or legacy data,
+external input boundaries, state transitions, effect order, failure and retry
+behavior, and compatibility surfaces. Record `baseline evidence gap` when an
+important obligation has no distinguishing observer; do not silently treat it
+as absent.
+
+## Universal Lens Sweep
+
+In `standard` and `thorough-within-scope`, give every available Developer skill
+other than Doctor one disposition: `triggered`, `no-trigger`, `needs-evidence`,
+`out-of-scope`, or `blocked`. Each disposition requires concrete scope evidence.
+
+| Owner skill | Diagnostic question | Representative trigger |
+| --- | --- | --- |
+| `specify` | Is code deciding unresolved product meaning or scope? | docs, tests, callers, or defaults imply different product senses |
+| `model` | Are admitted, forbidden, absent, replacement, relational, or temporal conditions unsettled? | null/default/legacy combinations, invalid states, retries, ordering, solver or query semantics |
+| `sketch` | Is an implementable owner, boundary, representation, data flow, state flow, or collaboration missing? | unchecked narrowing, shotgun parsing, navigation leaks, mixed effects, repeated ownership decisions |
+| `signal` | Is observable structural movement present rather than mere similarity? | repeated change, closest parallel cases, model-code mismatch, boundary pressure |
+| `naming-judgment` | Do names preserve stable domain sense and expose consequential effects? | filler names, effect-hiding verbs, implementation-shaped names, sense collisions |
+| `abstraction-review` | Can callers safely rely on an already-shaped helper, API, interface, boundary, or workflow rule? | a concrete candidate makes unstable or leaking promises |
+| `schedule` | When does a stable concrete structural candidate belong? | current invariant pressure, nested work, delay cost, or lost reversibility |
+| `verify` | What do current checks prove, and what plausible wrong shape still passes? | green checks with observer, source, branch, construction-path, or effect-order gaps |
+| `adversarial-eval` | Does a consequential claim need escalating finite counterexamples? | ordinary checks can pass while security, data, compatibility, or workflow behavior is wrong |
+| `visualize` | Would a visual surface materially lower the cost of judging relationships? | state, ownership, flow, dependency, or ordering is hard to inspect in prose |
+
+Use this inspection surface:
+
+| Skill | Disposition | Scope evidence | Concrete consultation question or exemption |
+| --- | --- | --- | --- |
+
+`no-trigger` means observed evidence makes the compact question irrelevant here;
+it does not mean the entire codebase is healthy. `needs-evidence` names the
+smallest observation that could change the disposition.
+
+## Consultation Workflow
+
+Doctor does not impersonate all other skills and must not read sibling skill
+references inside a Doctor route.
+
+For every `triggered` disposition:
+
+1. write one concrete consultation question and its trigger evidence;
+2. close the Doctor triage route;
+3. route the question to its owning Developer skill;
+4. inspect every reference-policy route in that skill;
+5. select every route whose observable trigger answers a distinct unresolved
+   question;
+6. load and apply every co-required reference in the declared order;
+7. preserve the owner skill's artifact, stop, separation boundary, and
+   `reference_basis`;
+8. return to Doctor only after consultations resolve or become explicit gaps.
+
+Use dependency only when evidence requires it: unresolved meaning or condition
+space precedes a design that depends on it; `signal` precedes promotion of a
+new structural candidate; `sketch` creates an original surface;
+`abstraction-review` judges an existing surface; `schedule` requires a stable
+candidate; `verify` and `adversarial-eval` challenge the resulting claims. Do
+not run this as a mandatory phase sequence when a lens is `no-trigger`.
+
+When Developer protocol is active and consultations remain, keep one
+agent-owned `before-completion` Doctor synthesis question rather than opening one
+pending question per lens. Owner-skill judgments may resolve their narrow
+question while retaining that synthesis question with updated remaining work.
+The final Doctor route resolves it after integrating the consultation ledger.
+
+Use a consultation ledger:
+
+| Skill / policy route | Trigger evidence | Judgment artifact | Result | Residual gap |
+| --- | --- | --- | --- | --- |
+
+## Diagnosis
+
+Synthesize consultations into findings without erasing disagreement or evidence
+limits.
+
+| ID | Observation | Consequence | Mechanism | Evidence | Confidence | Affected scope | Owner judgment |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+
+A valid diagnosis names:
+
+- the observable behavior, invariant risk, change obstruction, or evidence gap;
+- the mechanism connecting code shape to that consequence;
+- supporting and contradicting evidence;
+- confidence and the exact claim boundary;
+- the smallest plausible falsifier;
+- a concrete candidate only when enough meaning and shape are stable.
+
+Do not merge independent findings merely because one treatment could touch the
+same files.
+
+## Treatment Plan
+
+Use ordinal decisions rather than pseudo-precise health scores.
+
+| Candidate | Diagnosis | Behavior to preserve | Guarantee gained | Current pressure | Dependencies / reversibility | Stable landing | Verifier | Decision |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+Decide:
+
+- `treat-now`: current correctness, security, data, compatibility, or invariant
+  risk justifies the smallest stable treatment;
+- `prepare-next`: the treatment is needed before the next related change to
+  avoid nested work or prevent a known recurrence;
+- `observe`: current pressure is insufficient; record an observable reopen
+  condition;
+- `leave-alone`: treatment is speculative, destroys useful freedom, or costs
+  more than the evidenced problem;
+- `needs-decision`: product, operational, or risk ownership cannot be inferred.
+
+Do not turn the treatment plan into a predetermined multi-step implementation
+queue. Provide one first handoff with its owner skill, preserved behavior,
+smallest stable landing, narrow verifier, and explicitly deferred work. Reobserve
+and reroute after that landing.
+
+## Output
+
+Lead with scope and the user's actual change or risk, not a health score. A
+resolved Doctor report contains:
+
+1. Doctor scope and actual coverage;
+2. preservation baseline;
+3. all required lens dispositions;
+4. consultation ledger with policy-route and reference provenance;
+5. diagnosis table;
+6. treatment plan;
+7. first concrete handoff and residual unknowns;
+8. an ASCII flow, ownership, state, or dependency map when relationships are
+   materially consequential.
+
+When used inside a larger task, return:
+
+```text
+Status: resolved | needs-evidence | not-applicable | blocked
+Result: scope-bound diagnosis and treatment order, or the consultation plan still required
+Basis: inspected code, behavior, callers, tests, traces, history, and owner-skill judgments
+Open questions: unresolved consultations, scope choices, product decisions, or none
+Artifacts: scope/coverage map, preservation baseline, lens matrix, consultation ledger, findings, treatment plan, and first handoff
+```
+
+Return only Doctor's scope, triage, or synthesis judgment for the current route;
+leave owner-skill consultation and implementation routing to the caller.
+
+## Completion
+
+A `thorough-within-scope` diagnosis is resolved only when:
+
+- requested, selected, inspected, and claim scopes are explicit;
+- every available non-Doctor skill has an evidence-backed disposition;
+- every triggered consultation is resolved or retained as an explicit gap;
+- every selected owner-skill policy route loaded and applied all required
+  references;
+- every finding has an observable consequence, mechanism, evidence, confidence,
+  scope, and falsifier;
+- every treatment preserves named behavior and has an owner and verifier;
+- every `treat-now` item has a smallest stable landing;
+- every `observe` item has a reopen condition;
+- intentionally unchanged areas are visible.
+
+Return `needs-evidence` after triage when owner-skill consultations, a baseline
+observer, or bounded repository evidence can settle the diagnosis. Return
+`blocked` when required product, operational, access, or risk ownership cannot
+be obtained. Return `not-applicable` when the request is a local diff review,
+environment check, already-shaped single judgment, or implementation task better
+owned directly by another skill.
+
+## Boundary
+
+Do not implement treatment, automatically repair files, recommend a rewrite
+because code is old, equate style or metrics with risk, invent product meaning,
+promote every duplication into an abstraction, flatten sibling skills into a
+checklist, load all references without triggers, or claim coverage beyond the
+inspected scope. Doctor owns scope, lens coverage, consultation planning,
+diagnostic synthesis, and treatment ordering; focused Developer skills own the
+actual judgments and their routed references.

package/skills/model/SKILL.md

@@ -78,8 +78,12 @@ states, transitions, or policy decisions invalidate the model.
 5. Select one specialized model only when contract, relation, time, exhaustive
    evidence, or search has an independent artifact and stop condition.
 6. State the ability lost and guarantee gained by the chosen representation.
-7. Place each guarantee at the appropriate type, boundary, validation, test,
-   property, proof, model check, or human decision.
+7. Place each guarantee at the appropriate type, boundary, parser, constructor,
+   database constraint, test, property, proof, model check, or human decision.
+   A validation result that carries no refined value and an unchecked assertion,
+   cast, non-null claim, or typed deserialization target cannot own a
+   representable-state guarantee. When raw and admitted domains differ, require
+   an evidence-bearing transition without designing its API.
 8. Derive counterexamples and verification targets without designing the API.
 
 ## Missing Evidence

package/skills/model/references/problem-modeling.md

@@ -134,8 +134,10 @@ to remain aligned.
 
 For every important rule, name the cheapest trustworthy owner and evidence target:
 
-- type for representable-state restrictions;
-- constructor or runtime validation for hostile input;
+- type or abstract representation for representable-state restrictions, but only
+  when every construction path establishes the restriction;
+- parser or smart constructor for hostile or broader input, returning the
+  invariant-carrying value or explicit failure rather than discarding the check;
 - contract for caller/callee meaning;
 - database constraint for persisted relational facts;
 - state transition owner for history-sensitive rules;
@@ -144,7 +146,11 @@ For every important rule, name the cheapest trustworthy owner and evidence targe
 - model, solver, or proof for bounded exhaustive relationships;
 - human decision for policy.
 
-An unchecked statement may guide design, but it is not evidence.
+An unchecked statement may guide design, but it is not evidence. Validation that
+returns only success, `Unit`, or `Bool` cannot by itself place a guarantee at a
+stronger type, and an assertion, cast, non-null claim, ignored conversion result,
+or typed deserialization target does not repair that gap. Record the required
+raw-to-refined transition and hand its concrete caller surface to `sketch`.
 
 ## Model Artifact
 
@@ -177,6 +183,10 @@ Separate rather than expanding this reference when:
 
 ## Source Trace
 
+- Alexis King, “Parse, don’t validate,” published November 5, 2019, for the
+  distinction between checks that discard learned information and fallible
+  transitions that return a refined representation. Concrete parser and
+  smart-constructor surfaces remain owned by `sketch`.
 - Hillel Wayne, *Logic for Programmers*, v0.14.0, 2026-05-04:
   Chapters 2-4, pp. 5-46, for predicates, quantifiers, ability/guarantee,
   specifications, and logic/runtime boundaries. Recorded beta defects are

package/skills/sketch/SKILL.md

@@ -50,10 +50,13 @@ sketch must be inspectable as an implementation shape, not only narrated in
 paragraphs. Produce:
 
 1. a compact case/check table;
-2. concrete data or state definitions;
+2. concrete data or state definitions, including raw and refined forms when an
+   input's provenance is broader than the accepted domain;
 3. wishful top-level code, pseudocode, or an interaction skeleton in a fenced
    code block;
 4. a wished-interface table with contract, owner, hidden detail, and stop check;
+   when raw and refined forms differ, show the parser or smart constructor whose
+   success returns the refined value and whose failure precedes dependent effects;
 5. a small ordered implementation queue and explicitly deferred abstractions;
 6. an ASCII flow, relation map, state transition, or boundary diagram whenever
    two or more components, states, or collaborations are materially related.
@@ -78,7 +81,10 @@ routing to the caller.
 
 Finish when the first implementation item is small enough to execute and check,
 and non-local or invariant-bearing candidates are explicit rather than silently
-assumed. `resolved` is not valid for a prose-only sketch: the output must show
+assumed. If broader, external, persisted, legacy, or otherwise less-trusted data
+enters the surface, `resolved` also requires an evidence-preserving transition to
+the domain representation; validation followed by an assertion is not such a
+transition. `resolved` is not valid for a prose-only sketch: the output must show
 the code or interaction skeleton and the checks that make the first item
 executable. Revisit when implementation evidence breaks the ownership or
 data-flow assumptions.
@@ -87,7 +93,9 @@ data-flow assumptions.
 
 1. Choose the strongest available source of intent and state its confidence.
 2. State the design unit's purpose in the user's language.
-3. Derive relevant data or state definitions and their ownership pressure.
+3. Derive relevant data or state definitions and their ownership pressure. Mark
+   provenance and the raw-to-refined boundary whenever callers cannot already
+   supply an invariant-carrying value. Treat unchecked narrowing as no evidence.
 4. List representative cases before choosing code shape.
 5. Name each independently unresolved design question and select only its routed
    extension; keep disputed meaning in `model`.