@hobin/developer 0.1.1 → 0.1.2

package/README.md

@@ -87,7 +87,8 @@ Developer adds two model-facing protocol tools:
 2. The route target is `direct` or one currently available Developer skill.
 3. A skill route returns the exact Pi-discovered `SKILL.md` instructions and canonical
    path; a direct route keeps implementation tools available for the justified
-   action.
+   action. A behavior-preserving structural direct route also loads the focused
+   execution profile that keeps edits small and returns to stable green landings.
 4. `developer_record_judgment` closes the route with a status, result, evidence,
    artifacts, and any newly opened questions.
 
@@ -140,12 +141,12 @@ or the user may invoke one directly with `/skill:<name>`.
 | Skill | Helps decide |
 | --- | --- |
 | `specify` | Product meaning, scope, invariants, risks, and blocking unknowns |
-| `model` | Logic for Programmers-style condition spaces, guarantees, and verification targets |
-| `sketch` | SICP-style abstraction barriers and HtDP-style data-directed design recipes |
-| `signal` | Flocking-style small structural movement and model-code mismatch |
-| `naming-judgment` | Elements of Clojure-style domain sense and change-preserving names |
+| `model` | Condition spaces, contracts, replacement, transitions, guarantees, and verification targets |
+| `sketch` | Data-driven skeletons, abstraction and composition boundaries, state, responsibility, and variation |
+| `signal` | Evidence-backed structural movement and model-code mismatch |
+| `naming-judgment` | Domain sense, honest effects, and change-preserving names |
 | `abstraction-review` | Whether a candidate should be kept, revised, split, rejected, or deferred |
-| `schedule` | Tidy First-style behavior/structure timing: now, after, or never |
+| `schedule` | Behavior/structure timing: now, after, or never |
 | `verify` | Verifier selection, evidence relevance, and pass-but-wrong risk |
 | `visualize` | The smallest visual surface that lowers judgment cost |
 | `adversarial-eval` | Finite, escalating attempts to falsify a skill or implementation claim |
@@ -154,10 +155,27 @@ Pi's loaded resource metadata is authoritative. If package configuration filters
 or disables a skill, Developer cannot route to it even if its file exists in the
 npm package.
 
-Several skills link to detailed documents under their own `references/`
-directory. Pi loads the `SKILL.md` instructions on demand; the instructions say
-when the additional reference is worth reading and resolve it relative to the
-skill directory. Small, already-settled judgments do not need the extra context.
+Several skills link to detailed capability documents under their own
+`references/` directory. Pi loads the `SKILL.md` instructions on demand; the
+instructions say when each reference is worth reading and resolve it relative to
+the skill directory. A reference may synthesize several sources because the
+leaf's question, not a book title, owns the capability. Each source-derived
+reference includes a source trace, and [SOURCES.md](./SOURCES.md) maps the full
+book coverage across leaves and the direct path. Small, settled judgments do not
+need the extra context.
+
+Primary references retain the capability's core insight and one complete case.
+When a question has materially different derivation rules, the skill routes a
+more focused supporting reference—for example, data-shape templates separately
+from generative recursion, or representation barriers separately from state and
+time. This follows Pi's documented progressive-disclosure structure: supporting
+files stay relative to their skill and load only when the unresolved question
+needs them. `SOURCES.md` also records the reference-quality contract used to
+prevent source summaries from replacing executable judgment recipes.
+
+Developer treats Pi's loaded `systemPromptOptions.skills` metadata as the skill
+SSOT. It does not rescan the package and cannot route a skill Pi filtered,
+disabled, or replaced through resource configuration.
 
 ## State, branches, and compaction
 
@@ -201,11 +219,13 @@ pinning, and security behavior.
 ```text
 extensions/
 ├── developer.ts    # command, protocol tools, events, and Pi integration
+├── references/     # direct execution profiles loaded through tool results
 ├── state.ts        # replayable developer/v2 branch state
-├── skills.ts       # Pi-native skill discovery and instruction loading
+├── skills.ts       # loaded-skill filtering and instruction rendering
 ├── tool-policy.ts  # strict-mode active-tool reconciliation
 └── tui.ts          # selectors, widget, status panel, and prompt preparation
 skills/             # ten independently loadable Pi skills
+SOURCES.md          # source-to-capability maintenance trace
 evals/              # model-dependent scenarios and workspace assertions
 tests/              # deterministic state, policy, extension, and TUI tests
 ```

package/SOURCES.md

@@ -0,0 +1,104 @@
+# Source-to-Capability Trace
+
+Developer is organized around questions the agent must answer, not around books.
+This maintainer document records how source material is decomposed across leaf
+skills and the direct execution path. It is not a Pi runtime resource or a
+required workflow.
+
+## Ownership Rule
+
+A source idea belongs where its observable job is performed:
+
+- product meaning and change pressure go to `specify`;
+- cases, rules, contracts, and transitions go to `model`;
+- implementable boundaries and collaborations go to `sketch`;
+- visible structural movement goes to `signal`;
+- candidate stability goes to `abstraction-review`;
+- timing goes to `schedule`;
+- names go to `naming-judgment`;
+- claim-to-evidence judgment goes to `verify`;
+- already-justified mutation goes to the `direct` route.
+
+No source implies a mandatory route order. Several leaves may use different
+parts of the same source because they answer different questions.
+
+## Runtime Reference Quality
+
+`SKILL.md` owns discovery, the core question, output, completion, and conditional
+routing. A reference loaded through that route must be usable without reopening
+the original source or reconstructing unstated steps.
+
+Match detail to the reference's job:
+
+- a concept or design reference needs the core insight, input, derivation rule,
+  completed example, counterexample or failure diagnosis, output, and boundary;
+- a recipe card needs a trigger, input artifact, construction rule, output
+  artifact, observable stop, and repair direction;
+- a diagnostic table needs a symptom, evidence path, repair artifact, and
+  re-check;
+- a worked-example file needs enough context to show why the decision follows,
+  not only a polished final answer;
+- a mutation protocol needs an entry contract, safe intermediate states,
+  evidence rhythm, reroute conditions, and a stable landing.
+
+Split a reference when independent questions would otherwise make it expensive
+to load, but keep the central insight and one complete example in the primary
+reference. Splitting by chapter title or merely to shorten a file is not a
+capability boundary.
+
+## Capability Matrix
+
+| Source | Capability extracted | Primary owner | Supporting owner or execution path |
+| --- | --- | --- | --- |
+| *99 Bottles of OOP*, ch. 1-2 | simple concrete baseline, Shameless Green, cost-effective and intention-revealing tests | `verify` | `signal`, `schedule` |
+| *99 Bottles of OOP*, ch. 3-4 | real change pressure, point of attack, closest pair, smallest difference, horizontal movement | `signal` | `direct` behavior-preserving protocol |
+| *99 Bottles of OOP*, ch. 4-5 | stable landings, responsibility-derived names, argument and data movement | `abstraction-review`, `naming-judgment` | `direct` behavior-preserving protocol |
+| *99 Bottles of OOP*, ch. 5-8 | responsibility separation, messages, type transitions, polymorphism, dependency direction, object creation at the edge, factory tradeoffs | `sketch`, `abstraction-review` | `model`, `schedule` |
+| *99 Bottles of OOP*, ch. 9 | unit boundaries, context independence, role verification, obsolete-test removal | `verify` | `sketch` |
+| *How to Design Programs* | information analysis, data definitions, examples, templates, structural and generative recursion, accumulators, iterative refinement | `sketch` | `model`, `verify`, `signal`, `abstraction-review` |
+| *Structure and Interpretation of Computer Programs*, ch. 1-2 | procedural abstraction, process shape, higher-order composition, data abstraction, closure, conventional interfaces, multiple representations | `sketch`, `abstraction-review` | `model` |
+| *Structure and Interpretation of Computer Programs*, ch. 3 | state, identity, history, concurrency, streams, constraint propagation | `model`, `sketch` | `abstraction-review`, `verify` |
+| *Structure and Interpretation of Computer Programs*, ch. 4-5 | language/evaluator boundaries and explicit execution machinery | `sketch`, `abstraction-review` | imported only when a real DSL, interpreter, compiler, or runtime boundary exists |
+| *Logic for Programmers*, ch. 2-3 | predicates, sets, quantifiers, logical refactoring, runtime-semantic caveats | `model` | `verify` |
+| *Logic for Programmers*, ch. 4-6 | partial specifications, properties, contracts, replacement, proof limits | `model`, `verify` | `abstraction-review` |
+| *Logic for Programmers*, ch. 7-12 | relational constraints, decision tables, domain/time/system models, solvers, logic programming | `model` | `verify` |
+| *Elements of Clojure*: Names | narrow and consistent sense, honest effects and scope crossing | `naming-judgment` | `model` |
+| *Elements of Clojure*: Idioms | language-specific conventions and explicit operational semantics | project conventions or `direct` | generalized only when the semantic lesson survives the language |
+| *Elements of Clojure*: Indirection | abstraction cost, module environment/model/interface/assumptions, principled versus adaptable systems | `sketch`, `abstraction-review` | `schedule` |
+| *Elements of Clojure*: Composition | units of computation and pull-transform-push process boundaries | `sketch` | `naming-judgment`, `verify` |
+| *Tidy First?* | separate behavior from structure, small tidyings, optionality, reversibility, first/after/later/never | `schedule` | `direct` behavior-preserving protocol, `signal` |
+
+## Intentionally Not Imported As Universal Rules
+
+Source coverage does not mean copying every example or language idiom into every
+task. The following remain contextual:
+
+- Ruby class and factory shapes from *99 Bottles* are evidence about
+  responsibility and variation, not a destination for every design.
+- Scheme evaluators, register machines, and compiler details from SICP are used
+  only for tasks that actually expose those runtime or language boundaries.
+- Clojure-specific arities, option maps, atoms, macros, and interop idioms stay
+  subordinate to the target project's language and conventions.
+- Logic solvers, formal proof, TLA+, Prolog, and answer-set programming are
+  selected only when the modeled uncertainty and risk justify their cost.
+- HtDP recipes are adapted to existing repositories; they do not require adding
+  pedagogical comments, signatures, or templates to production code.
+
+These exclusions prevent a respected source from becoming a framework-shaped
+answer imposed on unrelated product work.
+
+## Reassembly Check
+
+When adding or revising a source-derived reference, record:
+
+```text
+Source location: book, edition/version, chapter or section
+Capability: the question or action the idea improves
+Owner: one leaf or the direct path
+Boundary: what the owner must not absorb
+Observable effect: the artifact, decision, or safer execution behavior expected
+```
+
+Create a new leaf only when a recurring question has a distinct input, output,
+completion condition, and boundary that no existing owner can express. A new
+source, technique, or vocabulary is not by itself evidence for a new leaf.

package/extensions/developer.ts

@@ -1,3 +1,4 @@
+import { readFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -14,11 +15,7 @@ import {
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
-import {
-  availablePackageSkills,
-  loadCandidateSkills,
-  renderSkillMethod,
-} from "./skills.ts";
+import { availablePackageSkills, renderSkillMethod } from "./skills.ts";
 import {
   JUDGMENT_TOOL,
   MODE_ENTRY,
@@ -31,6 +28,7 @@ import {
   reconstructState,
   type DeveloperMode,
   type DeveloperState,
+  type DirectExecutionProfile,
   type JudgmentEvent,
   type ModeEvent,
   type RouteEvent,
@@ -50,7 +48,13 @@ import {
 } from "./tui.ts";
 
 const PROTOCOL_TOOLS = [ROUTE_TOOL, JUDGMENT_TOOL] as const;
-const skillsRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "skills");
+const extensionRoot = dirname(fileURLToPath(import.meta.url));
+const skillsRoot = resolve(extensionRoot, "..", "skills");
+const structuralChangeMethodPath = resolve(
+  extensionRoot,
+  "references",
+  "behavior-preserving-structural-change.md",
+);
 const MAX_PENDING_QUESTIONS = 20;
 const MAX_QUESTION_CHARS = 2_000;
 const MAX_EVIDENCE_CHARS = 2_000;
@@ -116,6 +120,7 @@ function protocolPrompt(state: DeveloperState, availableSkillNames: string[]): s
     "- Treat the protocol as adaptive routing, never as a fixed sequence of skills.",
     `- Call ${ROUTE_TOOL} only when one concrete development question needs focused judgment or direct action.`,
     "- Use owner=direct when the next local action is already justified; otherwise set owner to the available skill whose scope best fits the question.",
+    "- For direct structural work intended to preserve behavior, set execution_profile=behavior-preserving-structure; omit the field for other direct actions and every skill route.",
     `- Follow the skill instructions returned by ${ROUTE_TOOL}, then close that route with ${JUDGMENT_TOOL}.`,
     "- Keep a direct route open through implementation and evidence collection; record its judgment afterward.",
     "- Protocol state is routing bookkeeping. Idle never proves product completion, user acceptance, or current verification.",
@@ -156,7 +161,8 @@ function protocolPrompt(state: DeveloperState, availableSkillNames: string[]): s
 function routeRenderText(event: RouteEvent | undefined): string {
   if (!event) return "Route unavailable";
   const target = event.targetQuestionId ? ` · revisits ${event.targetQuestionId}` : "";
-  return `${event.owner} · ${compactLine(event.question)}${target}`;
+  const profile = event.executionProfile ? `/${event.executionProfile}` : "";
+  return `${event.owner}${profile} · ${compactLine(event.question)}${target}`;
 }
 
 function judgmentRenderText(event: JudgmentEvent | undefined): string {
@@ -165,7 +171,6 @@ function judgmentRenderText(event: JudgmentEvent | undefined): string {
 }
 
 export default async function developer(pi: ExtensionAPI) {
-  const candidates = loadCandidateSkills(skillsRoot);
   let availableSkills = new Map<string, Skill>();
   let state = initialState();
   let routeOpening = false;
@@ -240,17 +245,12 @@ export default async function developer(pi: ExtensionAPI) {
     refreshUI(ctx);
   };
 
-  const RouteParams = Type.Object({
+  const SharedRouteParams = {
     question: Type.String({
       minLength: 1,
       maxLength: MAX_QUESTION_CHARS,
       description: "The single concrete judgment or action question to route",
     }),
-    owner: Type.String({
-      minLength: 1,
-      maxLength: 64,
-      description: "direct, or an exact skill name from the current Available Developer skills list",
-    }),
     reason: Type.String({
       minLength: 1,
       maxLength: MAX_QUESTION_CHARS,
@@ -265,7 +265,33 @@ export default async function developer(pi: ExtensionAPI) {
     open_question_id: Type.Optional(
       Type.String({ maxLength: 512, description: "Exact pending question ID when this route revisits one" }),
     ),
-  });
+  };
+  const RouteParams = Type.Union([
+    Type.Object(
+      {
+        ...SharedRouteParams,
+        owner: Type.String({
+          minLength: 1,
+          maxLength: 64,
+          pattern: "^(?!direct$)[a-z0-9]+(?:-[a-z0-9]+)*$",
+          description: "Exact skill name from the current Available Developer skills list",
+        }),
+      },
+      { additionalProperties: false, description: "Route one question to a Developer skill" },
+    ),
+    Type.Object(
+      {
+        ...SharedRouteParams,
+        owner: Type.Literal("direct", { description: "Use Pi implementation tools for an already-justified action" }),
+        execution_profile: Type.Optional(
+          Type.Literal("behavior-preserving-structure", {
+            description: "Load the focused structural-mutation protocol; omit for ordinary direct action",
+          }),
+        ),
+      },
+      { additionalProperties: false, description: "Route one already-justified direct action" },
+    ),
+  ]);
 
   pi.registerTool({
     name: ROUTE_TOOL,
@@ -302,15 +328,28 @@ export default async function developer(pi: ExtensionAPI) {
         if (owner !== "direct" && !skill) {
           fail(`Developer skill ${owner} is unavailable or disabled in the current Pi resource configuration.`);
         }
+        const requestedExecutionProfile =
+          "execution_profile" in params ? params.execution_profile : undefined;
+        if (owner !== "direct" && requestedExecutionProfile !== undefined) {
+          fail("execution_profile is valid only when owner=direct.");
+        }
+        const executionProfile: DirectExecutionProfile | undefined =
+          owner === "direct" ? (requestedExecutionProfile ?? "ordinary") : undefined;
 
         const method =
-          owner === "direct"
-            ? [
-                "# Direct action",
-                "",
-                "The next local action is already justified. Keep this route open while using Pi implementation tools and collecting evidence.",
-              ].join("\n")
-            : await renderSkillMethod(skill!);
+          owner !== "direct"
+            ? await renderSkillMethod(skill!)
+            : executionProfile === "behavior-preserving-structure"
+              ? [
+                  '<developer-direct-profile name="behavior-preserving-structure">',
+                  (await readFile(structuralChangeMethodPath, "utf8")).trim(),
+                  "</developer-direct-profile>",
+                ].join("\n")
+              : [
+                  "# Direct action",
+                  "",
+                  "The next local action is already justified. Keep this route open while using Pi implementation tools and collecting evidence.",
+                ].join("\n");
 
         const event: RouteEvent = {
           protocol: PROTOCOL,
@@ -322,12 +361,14 @@ export default async function developer(pi: ExtensionAPI) {
           knownEvidence: (params.known_evidence ?? []).map((item) => item.trim()).filter(Boolean),
           targetQuestionId,
           methodLocation: skill?.filePath,
+          executionProfile,
         };
         const response = [
           `Route ID: ${event.routeId}`,
           `Question: ${event.question}`,
           `Target: ${event.owner}`,
           skill ? `Skill location: ${skill.filePath}` : "Skill location: direct action; no skill file",
+          executionProfile ? `Execution profile: ${executionProfile}` : "Execution profile: skill judgment",
           `Reason: ${event.reason}`,
           `Known evidence: ${event.knownEvidence.length > 0 ? event.knownEvidence.join(" | ") : "none"}`,
           targetQuestionId ? `Revisits pending question: ${targetQuestionId}` : "Revisits pending question: none",
@@ -381,6 +422,9 @@ export default async function developer(pi: ExtensionAPI) {
         }
         text += `\n${theme.fg("dim", `revisits · ${event.targetQuestionId ?? "none"}`)}`;
         text += `\n${theme.fg("dim", `skill · ${event.methodLocation ?? "direct action"}`)}`;
+        if (event.executionProfile) {
+          text += `\n${theme.fg("dim", `profile · ${event.executionProfile}`)}`;
+        }
       }
       if (!expanded && event) text += ` · ${keyHint("app.tools.expand", "details")}`;
       return reusableText(text, context.lastComponent);
@@ -537,7 +581,6 @@ export default async function developer(pi: ExtensionAPI) {
     if (typeof ctx.getSystemPromptOptions !== "function") return;
     availableSkills = availablePackageSkills(
       ctx.getSystemPromptOptions().skills ?? [],
-      candidates,
       skillsRoot,
     );
   };
@@ -668,7 +711,7 @@ export default async function developer(pi: ExtensionAPI) {
   });
 
   pi.on("before_agent_start", (event) => {
-    availableSkills = availablePackageSkills(event.systemPromptOptions.skills ?? [], candidates, skillsRoot);
+    availableSkills = availablePackageSkills(event.systemPromptOptions.skills ?? [], skillsRoot);
     if (state.mode === "off") return;
     return { systemPrompt: event.systemPrompt + protocolPrompt(state, [...availableSkills.keys()]) };
   });

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

@@ -0,0 +1,145 @@
+# Behavior-Preserving Structural Change
+
+Use this protocol only after a `direct` route has justified a concrete structural
+move. It governs mutation; it does not discover the move, approve an abstraction,
+or decide its timing.
+
+## Entry Contract
+
+Before editing, state:
+
+```text
+Behavior to preserve: the narrow observable claim
+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
+Stop: the next stable, pausable state
+```
+
+If the behavior claim, timing, or candidate is still under judgment, close or
+pause the direct route and route that question to the appropriate leaf.
+
+## Smallest Green Transformation
+
+Keep behavior and structure distinct in reasoning even if they eventually share
+a commit. Prefer the smallest movement whose failure can be localized.
+
+For replacement-shaped refactors, use this progression:
+
+```text
+new shape parses
+-> new shape executes
+-> callers use its result
+-> replaced code becomes unreachable
+-> replaced code is deleted
+-> relevant evidence is green
+```
+
+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.
+
+## Evidence Rhythm
+
+After each meaningful movement:
+
+1. run the narrowest check that can catch the likely break;
+2. inspect the diff for mixed behavior and structural changes;
+3. reduce the step when the failure cannot be explained locally;
+4. return to a green, deployable state before selecting another movement;
+5. re-observe the code instead of following a predetermined final design.
+
+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.
+
+## Stable Landing
+
+A stable landing is not merely a green command. It is a state where:
+
+- the preserved behavior has relevant evidence;
+- names and intermediate compatibility shapes are honest enough to pause;
+- no dead replacement path or half-moved caller remains accidentally active;
+- the diff has one explainable structural purpose;
+- the next decision can be made from the new evidence.
+
+Stop there when the accepted structural purpose is complete. Further cleanup,
+polymorphism, factory design, or public abstraction requires its own current
+pressure and judgment.
+
+## Reroute Conditions
+
+Leave direct execution and open a focused judgment when the movement reveals:
+
+- an unexpected product behavior or policy choice: `specify`;
+- missing cases, transition rules, or replacement obligations: `model`;
+- unresolved ownership, collaboration, or data flow: `sketch`;
+- a new comparison or uncertain structural direction: `signal`;
+- a responsibility, role, boundary, or abstraction candidate: `abstraction-review`;
+- a disputed name or vocabulary boundary: `naming-judgment`;
+- a question of now, after, or never: `schedule`;
+- weak or irrelevant evidence: `verify`.
+
+This is adaptive rerouting, not a required sequence.
+
+## Worked Mutation Trace
+
+Accepted move: replace duplicated schedule conversion in two callers with the
+already-reviewed pure `toScheduleContent` function.
+
+```text
+Behavior to preserve:
+  both callers produce the same ScheduleContent or domain error for the
+  characterized table of variants
+Structural move:
+  introduce the function, move one caller, then the second, then delete the
+  duplicate expressions
+Baseline evidence:
+  focused table test plus both caller integration tests are green
+Affected surface:
+  converter module, two callers, no persistence format
+Stop:
+  both callers use the converter; old expressions are unreachable and removed
+```
+
+Mutation sequence:
+
+```text
+1. add the pure function with one characterized caller's exact behavior
+2. run the conversion table
+3. switch caller A; run its integration and inspect the diff
+4. switch caller B; run its integration and inspect the diff
+5. search for the replaced expression and remove dead code
+6. run the focused table, integrations, typecheck, and packed-source check
+```
+
+If caller B reveals that `null` and missing have different product meanings, do
+not broaden the helper until everything passes. Return that policy to `model`;
+caller A remains at a stable landing. If both callers move cleanly, stop.
+Creating a converter class or registry is a new judgment, not “finishing” this
+refactor.
+
+## Failure Checks
+
+The protocol is being misused when:
+
+- tests are changed merely to preserve green output after behavior drift;
+- several differences are removed before the first can be inspected;
+- a class, strategy, polymorphic hierarchy, or factory was chosen in advance;
+- 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.
+
+## 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.
+- 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.
+- 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.

package/extensions/skills.ts

@@ -5,7 +5,6 @@ import { isAbsolute, relative, resolve } from "node:path";
 import {
   DEFAULT_MAX_BYTES,
   DEFAULT_MAX_LINES,
-  loadSkillsFromDir,
   stripFrontmatter,
   type Skill,
 } from "@earendil-works/pi-coding-agent";
@@ -33,30 +32,16 @@ export function isWithinRoot(root: string, path: string): boolean {
   return relation === "" || (!relation.startsWith("..") && !isAbsolute(relation));
 }
 
-export function loadCandidateSkills(skillsRoot: string): Map<string, Skill> {
-  const loaded = loadSkillsFromDir({ dir: skillsRoot, source: "@hobin/developer" });
-  const candidates = new Map<string, Skill>();
-
-  for (const skill of loaded.skills) {
-    if (candidates.has(skill.name)) throw new Error(`Duplicate Developer skill name: ${skill.name}`);
-    candidates.set(skill.name, skill);
-  }
-
-  if (candidates.size === 0) throw new Error(`No Developer skills found in ${skillsRoot}`);
-  return candidates;
-}
-
 export function availablePackageSkills(
   loadedSkills: Skill[],
-  candidates: ReadonlyMap<string, Skill>,
   skillsRoot: string,
 ): Map<string, Skill> {
   const available = new Map<string, Skill>();
 
   for (const skill of loadedSkills) {
     if (skill.disableModelInvocation) continue;
-    if (!candidates.has(skill.name)) 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);
   }
 

package/extensions/state.ts

@@ -9,6 +9,7 @@ export const LEGACY_JUDGMENT_TOOL = "record_judgment" as const;
 export type DeveloperMode = "off" | "on" | "strict";
 export type JudgmentStatus = "resolved" | "needs-evidence" | "not-applicable" | "blocked";
 export type PendingQuestionStatus = "needs-evidence" | "blocked";
+export type DirectExecutionProfile = "ordinary" | "behavior-preserving-structure";
 
 export interface ModeEvent {
   protocol: typeof PROTOCOL;
@@ -26,6 +27,7 @@ export interface RouteEvent {
   knownEvidence: string[];
   targetQuestionId?: string;
   methodLocation?: string;
+  executionProfile?: DirectExecutionProfile;
 }
 
 export interface PendingQuestion {
@@ -143,6 +145,10 @@ function isJudgmentStatus(value: unknown): value is JudgmentStatus {
   return value === "resolved" || value === "needs-evidence" || value === "not-applicable" || value === "blocked";
 }
 
+function isDirectExecutionProfile(value: unknown): value is DirectExecutionProfile {
+  return value === "ordinary" || value === "behavior-preserving-structure";
+}
+
 function parsePendingQuestion(value: unknown): PendingQuestion | undefined {
   if (!isObject(value)) return undefined;
   if (
@@ -178,7 +184,8 @@ export function normalizeDeveloperEvent(value: unknown): DeveloperEvent | undefi
       typeof value.reason !== "string" ||
       !isStringArray(value.knownEvidence) ||
       (value.targetQuestionId !== undefined && typeof value.targetQuestionId !== "string") ||
-      (value.methodLocation !== undefined && typeof value.methodLocation !== "string")
+      (value.methodLocation !== undefined && typeof value.methodLocation !== "string") ||
+      (value.executionProfile !== undefined && !isDirectExecutionProfile(value.executionProfile))
     ) {
       return undefined;
     }
@@ -192,6 +199,7 @@ export function normalizeDeveloperEvent(value: unknown): DeveloperEvent | undefi
       knownEvidence: value.knownEvidence,
       targetQuestionId: value.targetQuestionId,
       methodLocation: value.methodLocation,
+      executionProfile: value.executionProfile,
     };
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hobin/developer",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Adaptive product-development reasoning and evidence for Pi.",
   "type": "module",
   "keywords": [
@@ -30,6 +30,7 @@
     "extensions",
     "skills",
     "README.md",
+    "SOURCES.md",
     "LICENSE"
   ],
   "engines": {

package/skills/abstraction-review/references/field-card.md

@@ -30,6 +30,12 @@ The wish opens freedom; the stop check brings the review back to evidence.
 Failure is not handled by a better name. Failure exposes a broken layer,
 contract, or missing artifact.
 
+Use [the recipe cards](recipe-cards.md) when the derivation rule is missing,
+[the repair table](repair-table.md) when the stop check fails, and
+[the worked examples](worked-examples.md) when a completed calibration case is
+needed. The field card remains the auditable summary; these files supply focused
+construction, repair, and examples.
+
 ## Field Card
 
 Fill this card for serious reviews.
@@ -153,6 +159,7 @@ If the sentence cannot be filled:
 | --- | --- | --- |
 | The problem vocabulary is missing or misleading | Language | Notation As Data |
 | Similar functions, workflows, or tests move together | Language/Unit | Movement Pattern Extraction |
+| Data, methods, messages, or change reasons suggest a misplaced owner | Unit/Boundary | Responsibility Boundary |
 | Operation results do not remain composable | Unit | Closure Composition Unit |
 | A loop, state transition, or contract has no preserved meaning | Law | Invariant Iteration |
 | Callers must know raw representation or hidden policy | Boundary | Data Abstraction Boundary |