@hobin/developer 0.1.1 → 0.1.3

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,12 +15,9 @@ import {
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
+import { availablePackageSkills, renderSkillMethod } from "./skills.ts";
 import {
-  availablePackageSkills,
-  loadCandidateSkills,
-  renderSkillMethod,
-} from "./skills.ts";
-import {
+  FOCUS_ENTRY,
   JUDGMENT_TOOL,
   MODE_ENTRY,
   PROTOCOL,
@@ -31,6 +29,8 @@ import {
   reconstructState,
   type DeveloperMode,
   type DeveloperState,
+  type DirectExecutionProfile,
+  type FocusEvent,
   type JudgmentEvent,
   type ModeEvent,
   type RouteEvent,
@@ -50,7 +50,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;
@@ -103,6 +109,25 @@ function compactLine(value: string, maxChars = 160): string {
   return line.length <= maxChars ? line : `${line.slice(0, maxChars - 1)}…`;
 }
 
+function normalizedQuestion(value: string): string {
+  return value.toLocaleLowerCase().replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+}
+
+function inferredQuestionId(
+  state: DeveloperState,
+  question: string,
+  explicitQuestionId?: string,
+): string | undefined {
+  if (explicitQuestionId) return explicitQuestionId;
+  if (state.focusedQuestionId) return state.focusedQuestionId;
+  const normalized = normalizedQuestion(question);
+  const exact = state.pendingQuestions.filter(
+    (pending) => normalizedQuestion(pending.question) === normalized,
+  );
+  if (exact.length === 1) return exact[0]?.id;
+  return state.pendingQuestions.length === 1 ? state.pendingQuestions[0]?.id : undefined;
+}
+
 function summarizeState(state: DeveloperState): string {
   if (state.mode === "off") return "developer: off";
   const target = state.activeRoute ? state.activeRoute.owner : "none";
@@ -113,11 +138,14 @@ function protocolPrompt(state: DeveloperState, availableSkillNames: string[]): s
   const lines = [
     "",
     `Developer protocol (${state.mode}) is active.`,
-    "- 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.",
-    `- 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.",
+    "- 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 direct 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.",
+    `- Call ${ROUTE_TOOL} for exactly one concrete judgment or one green-to-green direct movement.`,
+    "- Use owner=direct 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.",
+    "- A direct 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 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 routed method, then close the route with ${JUDGMENT_TOOL}. After every direct stable landing, route again from the new evidence before selecting another movement.`,
+    "- Do not carry a predetermined implementation queue through multiple direct steps. Re-observe after each stable landing and reroute to a skill whenever meaning, cases, design, structural direction, timing, naming, or evidence becomes uncertain.",
     "- Protocol state is routing bookkeeping. Idle never proves product completion, user acceptance, or current verification.",
     "- Product files are changed with Pi implementation tools. Developer protocol tools only route and record judgments.",
   ];
@@ -128,6 +156,17 @@ function protocolPrompt(state: DeveloperState, availableSkillNames: string[]): s
     );
   }
 
+  if (state.implementationFramingRequired) {
+    lines.push(
+      "Required next framing: the latest resolved model exposed implementation work. Route sketch before new feature mutation, or signal before an existing-code structural movement; direct is not ready yet.",
+    );
+  }
+  if (state.verificationRequired) {
+    lines.push(
+      "Verification debt: a direct route changed artifacts after the last resolved verify judgment. Route verify before claiming completion or handing off as done.",
+    );
+  }
+
   if (state.activeRoute) {
     lines.push(
       `Active route: ${state.activeRoute.routeId} · ${state.activeRoute.owner} · ${state.activeRoute.question}`,
@@ -144,7 +183,7 @@ function protocolPrompt(state: DeveloperState, availableSkillNames: string[]): s
       lines.push(`- ${question.id} · ${question.status} · ${question.question}`);
     }
     lines.push(
-      `- To revisit one, pass its exact ID as open_question_id to ${ROUTE_TOOL}. Report any question that remains open at handoff.`,
+      "- Revisit questions naturally. Developer automatically associates a focused, sole, or exactly matching pending question; open_question_id is an internal disambiguator only when several questions remain.",
     );
   }
   lines.push(
@@ -156,7 +195,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,10 +205,10 @@ 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;
+  const routesWithMutation = new Set<string>();
   let toolPolicyMemory: ToolPolicyMemory = { withheldBuiltins: new Set() };
 
   pi.registerFlag("develop-mode", {
@@ -201,7 +241,12 @@ export default async function developer(pi: ExtensionAPI) {
       "developer",
       ctx.mode === "tui" ? renderDeveloperFooter(state, ctx.ui.theme) : summarizeState(state),
     );
-    if (!state.activeRoute && state.pendingQuestions.length === 0) {
+    if (
+      !state.activeRoute &&
+      state.pendingQuestions.length === 0 &&
+      !state.implementationFramingRequired &&
+      !state.verificationRequired
+    ) {
       ctx.ui.setWidget("developer", undefined);
       return;
     }
@@ -222,6 +267,8 @@ export default async function developer(pi: ExtensionAPI) {
         .slice(0, 3)
         .map((question) => `open · ${question.id} · ${compactLine(question.question)}`),
       ...(state.pendingQuestions.length > 3 ? [`open · +${state.pendingQuestions.length - 3} more`] : []),
+      ...(state.implementationFramingRequired ? ["next · sketch feature shape or signal structural movement"] : []),
+      ...(state.verificationRequired ? ["next · verify changed artifacts before completion"] : []),
     ];
     ctx.ui.setWidget("developer", lines, { placement: "belowEditor" });
   };
@@ -240,17 +287,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,17 +307,59 @@ 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" }),
+        movement: Type.String({
+          minLength: 1,
+          maxLength: MAX_QUESTION_CHARS,
+          description: "One locally explainable behavioral or structural movement; not a multi-step implementation queue",
+        }),
+        stop_condition: Type.String({
+          minLength: 1,
+          maxLength: MAX_QUESTION_CHARS,
+          description: "The green, pausable, reviewable stable landing that ends this direct route",
+        }),
+        verification: Type.String({
+          minLength: 1,
+          maxLength: MAX_EVIDENCE_CHARS,
+          description: "The narrowest check that can catch the likely break in this movement",
+        }),
+        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,
     label: "Developer Route Question",
     description:
-      "Route one concrete development question to direct action or one currently available @hobin/developer skill. This is adaptive routing, not a workflow sequence.",
+      "Route one concrete judgment or one green-to-green direct movement. Uses an adaptive default topology: model, then sketch for feature shape or signal for structural movement, direct 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; use owner=direct for an already-justified local action.`,
+      `Use ${ROUTE_TOOL} with the most focused skill supported by current evidence; owner=direct requires one movement, one stable landing, and one narrow verification.`,
+      `After a resolved model, use sketch for first feature implementation framing or signal for existing-code structural movement before direct mutation.`,
     ],
     parameters: RouteParams,
     executionMode: "sequential",
@@ -292,25 +376,65 @@ export default async function developer(pi: ExtensionAPI) {
         const reason = params.reason.trim();
         if (!question || !reason) fail("Question and reason must contain non-whitespace text.");
 
-        const targetQuestionId = params.open_question_id?.trim() || undefined;
+        const explicitQuestionId = params.open_question_id?.trim() || undefined;
+        const targetQuestionId = inferredQuestionId(state, question, explicitQuestionId);
         if (targetQuestionId && !state.pendingQuestions.some((item) => item.id === targetQuestionId)) {
           fail(`Unknown pending question ID: ${targetQuestionId}`);
         }
 
         const owner = params.owner;
+        if (
+          owner === "direct" &&
+          state.implementationFramingRequired &&
+          (availableSkills.has("sketch") || availableSkills.has("signal"))
+        ) {
+          fail(
+            "The latest resolved model requires implementation framing before direct work. Route sketch for new feature shape or signal for existing-code structural movement.",
+          );
+        }
         const skill = owner === "direct" ? undefined : availableSkills.get(owner);
         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"
+            ? 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 directStep =
           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!);
+            ? {
+                movement: ("movement" in params ? params.movement : question).trim(),
+                stopCondition: (
+                  "stop_condition" in params
+                    ? params.stop_condition
+                    : "Reach a green, pausable, reviewable stable landing."
+                ).trim(),
+                verification: (
+                  "verification" in params
+                    ? params.verification
+                    : "Run the narrowest relevant check and inspect the resulting diff or output."
+                ).trim(),
+              }
+            : undefined;
 
         const event: RouteEvent = {
           protocol: PROTOCOL,
@@ -322,12 +446,23 @@ export default async function developer(pi: ExtensionAPI) {
           knownEvidence: (params.known_evidence ?? []).map((item) => item.trim()).filter(Boolean),
           targetQuestionId,
           methodLocation: skill?.filePath,
+          executionProfile,
+          directStep,
         };
         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",
+          ...(directStep
+            ? [
+                `Movement: ${directStep.movement}`,
+                `Stable landing: ${directStep.stopCondition}`,
+                `Narrow verification: ${directStep.verification}`,
+                "Stop this direct route at that landing, record the evidence, and route again before another movement.",
+              ]
+            : []),
           `Reason: ${event.reason}`,
           `Known evidence: ${event.knownEvidence.length > 0 ? event.knownEvidence.join(" | ") : "none"}`,
           targetQuestionId ? `Revisits pending question: ${targetQuestionId}` : "Revisits pending question: none",
@@ -356,11 +491,11 @@ export default async function developer(pi: ExtensionAPI) {
         context.lastComponent,
       );
     },
-    renderResult(result, { expanded, isPartial, isError }, theme, context) {
+    renderResult(result, { expanded, isPartial }, theme, context) {
       if (isPartial) {
         return reusableText(theme.fg("warning", "routing development question…"), context.lastComponent);
       }
-      if (isError) {
+      if (context.isError) {
         return reusableText(
           theme.fg("error", resultText(result) || "Developer route failed"),
           context.lastComponent,
@@ -381,6 +516,14 @@ 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 (event.directStep) {
+          text += `\n${theme.fg("dim", `movement · ${event.directStep.movement}`)}`;
+          text += `\n${theme.fg("dim", `landing · ${event.directStep.stopCondition}`)}`;
+          text += `\n${theme.fg("dim", `verify · ${event.directStep.verification}`)}`;
+        }
       }
       if (!expanded && event) text += ` · ${keyHint("app.tools.expand", "details")}`;
       return reusableText(text, context.lastComponent);
@@ -459,6 +602,7 @@ export default async function developer(pi: ExtensionAPI) {
         basis,
         openedQuestions,
         artifacts: (params.artifacts ?? []).map((item) => item.trim()).filter(Boolean),
+        changedArtifacts: routesWithMutation.has(params.route_id),
       };
       const nextState = applyDeveloperEvent(state, event);
       if (nextState.pendingQuestions.length > MAX_PENDING_QUESTIONS) {
@@ -469,12 +613,17 @@ export default async function developer(pi: ExtensionAPI) {
 
       const next = protocolState(nextState);
       const nextMessage =
-        next === "idle"
-          ? "Developer protocol is idle. This is routing state only and does not prove task completion."
-          : `Developer protocol is ${next}. Address or report the pending question before handoff.`;
+        event.owner === "direct"
+          ? nextState.verificationRequired
+            ? "Stable landing recorded. Route again from the new evidence; verify is required before claiming completion."
+            : "Stable landing recorded. Route again from the new evidence before selecting another movement."
+          : next === "idle"
+            ? "Developer protocol is idle. This is routing state only and does not prove task completion."
+            : `Developer protocol is ${next}. Address the current routing obligation before handoff.`;
       const response = `Recorded ${event.status} judgment for ${event.routeId}: ${event.result}\n${nextMessage}`;
       ensureSafeToolText(response, "Developer judgment result");
 
+      routesWithMutation.delete(params.route_id);
       state = nextState;
       syncProtocolTools();
       refreshUI(ctx);
@@ -497,11 +646,11 @@ export default async function developer(pi: ExtensionAPI) {
         context.lastComponent,
       );
     },
-    renderResult(result, { expanded, isPartial, isError }, theme, context) {
+    renderResult(result, { expanded, isPartial }, theme, context) {
       if (isPartial) {
         return reusableText(theme.fg("warning", "recording development judgment…"), context.lastComponent);
       }
-      if (isError) {
+      if (context.isError) {
         return reusableText(
           theme.fg("error", resultText(result) || "Developer judgment failed"),
           context.lastComponent,
@@ -537,7 +686,6 @@ export default async function developer(pi: ExtensionAPI) {
     if (typeof ctx.getSystemPromptOptions !== "function") return;
     availableSkills = availablePackageSkills(
       ctx.getSystemPromptOptions().skills ?? [],
-      candidates,
       skillsRoot,
     );
   };
@@ -625,8 +773,16 @@ export default async function developer(pi: ExtensionAPI) {
           if (!questionId) return;
           const question = state.pendingQuestions.find((item) => item.id === questionId);
           if (!question) return;
+          const focusEvent: FocusEvent = {
+            protocol: PROTOCOL,
+            kind: "focus",
+            questionId: question.id,
+          };
+          pi.appendEntry(FOCUS_ENTRY, focusEvent);
+          state = applyDeveloperEvent(state, focusEvent);
+          refreshUI(ctx);
           prepareQuestionPrompt(ctx, question);
-          ctx.ui.notify("Open question loaded into the editor for review.", "info");
+          ctx.ui.notify("Open question focused and loaded into the editor for review.", "info");
           return;
         }
         ctx.ui.notify(
@@ -668,16 +824,18 @@ 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()]) };
   });
 
   pi.on("tool_call", (event) => {
-    if (state.mode !== "strict") return;
     const mutationBuiltins = builtinMutationToolNames(pi.getAllTools());
-    if (!mutationBuiltins.has(event.toolName)) return;
-    if (state.activeRoute?.owner === "direct") return;
+    if (mutationBuiltins.has(event.toolName) && state.activeRoute?.owner === "direct") {
+      routesWithMutation.add(state.activeRoute.routeId);
+      return;
+    }
+    if (state.mode !== "strict" || !mutationBuiltins.has(event.toolName)) return;
     return {
       block: true,
       reason: `Developer strict mode requires an active ${ROUTE_TOOL} targeting direct action (owner=direct) before Pi built-in edit, write, or bash.`,

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

@@ -0,0 +1,149 @@
+# Behavior-Preserving Structural Change
+
+Use this protocol only after a `direct` route has justified one concrete structural
+movement and its stable landing. It governs that single green-to-green mutation;
+it does not discover the move, approve an abstraction, decide its timing, or carry
+a multi-step implementation queue across landings.
+
+## 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
+
+Within the routed 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 the declared green, deployable stable landing;
+5. close the direct route there and let Developer re-observe and route the next
+   question 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 and close the direct route there even when the wider accepted task still has
+work remaining. Developer must select the next movement or focused judgment from
+the new evidence. Further caller movement, cleanup, polymorphism, factory design,
+or public abstraction requires another route and its own current pressure.
+
+## Reroute Conditions
+
+Close direct execution at the latest stable landing 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);
   }