@hobin/developer 0.1.2 → 0.1.3

package/README.md

@@ -3,9 +3,10 @@
 Adaptive product-development judgment for [Pi](https://pi.dev).
 
 Developer combines a small, branch-aware coordination extension with ten
-independent skills. It routes one concrete question at a time, records the
-resulting evidence, and preserves unresolved questions without turning product
-development into a fixed lifecycle.
+independent skills. It routes one concrete question or green-to-green movement
+at a time, records the resulting evidence, and preserves unresolved questions.
+Its default topology gives feature work a useful backbone without turning every
+task into a fixed lifecycle.
 
 ## Install
 
@@ -86,11 +87,26 @@ Developer adds two model-facing protocol tools:
 1. `developer_route_question` opens one route for one concrete question.
 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. A behavior-preserving structural direct route also loads the focused
-   execution profile that keeps edits small and returns to stable green landings.
+   path; a direct route declares one movement, its stable landing, and its narrow
+   verification. A behavior-preserving structural route also loads the focused
+   execution profile based on flocking-style movement and small tidyings.
 4. `developer_record_judgment` closes the route with a status, result, evidence,
-   artifacts, and any newly opened questions.
+   artifacts, and any newly opened questions. Developer then routes again from
+   the stable landing before another movement.
+
+The conditional default topology is:
+
+```text
+clarify when needed → model consequential cases
+→ sketch the first feature implementation surface OR signal existing-code movement
+→ one direct green-to-green movement → re-route from evidence
+→ verify before completion
+```
+
+This is not a mandatory phase sequence. A stage may be not applicable and new
+evidence may route backward or sideways. One guard is deliberate: a resolved
+model cannot flow straight into mutation. New feature work receives an initial
+`sketch`; existing-code structural work receives a `signal` first.
 
 Product code is still read, edited, executed, and tested with Pi's normal tools.
 Developer's tools only route and record judgment; they do not implement product
@@ -130,8 +146,12 @@ These are routing states, not product-completion claims. In particular:
 - A resolved `specify` judgment is not user acceptance.
 - A resolved `verify` judgment is not timeless proof after later changes.
 
-Pending questions receive stable IDs. A later route revisits one by passing the
-exact ID; wording similarity is never used as identity.
+Pending questions receive stable internal IDs, but users do not type them.
+Selecting `/develop questions` focuses the question in branch state; the next
+route automatically associates that focus. A sole pending question or an exact
+question match is also associated automatically. Resolved and not-applicable
+judgments remove the associated question immediately; needs-evidence and blocked
+judgments retain the same identity.
 
 ## Skills
 
@@ -184,8 +204,9 @@ stored in tool-result details. Developer reconstructs state from the current
 session branch on startup and tree navigation, so a fork inherits only the
 events on its branch.
 
-The current event contract is `developer/v2`. Legacy `developer/v1` routing
-history can be replayed, but removed inferred fields are not revived.
+The current event contract is `developer/v3`. Legacy `developer/v1` and
+`developer/v2` routing history can be replayed, but new framing and verification
+obligations are not retroactively inferred.
 
 Developer uses Pi's normal compaction. Each new agent turn receives current
 protocol state, and route results place identity and recovery metadata before

package/extensions/developer.ts

@@ -17,6 +17,7 @@ import { Type } from "typebox";
 
 import { availablePackageSkills, renderSkillMethod } from "./skills.ts";
 import {
+  FOCUS_ENTRY,
   JUDGMENT_TOOL,
   MODE_ENTRY,
   PROTOCOL,
@@ -29,6 +30,7 @@ import {
   type DeveloperMode,
   type DeveloperState,
   type DirectExecutionProfile,
+  type FocusEvent,
   type JudgmentEvent,
   type ModeEvent,
   type RouteEvent,
@@ -107,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";
@@ -117,12 +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.",
+    "- 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 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.",
+    `- 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.",
   ];
@@ -133,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}`,
@@ -149,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(
@@ -174,6 +208,7 @@ export default async function developer(pi: ExtensionAPI) {
   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", {
@@ -206,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;
     }
@@ -227,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" });
   };
@@ -283,6 +325,21 @@ export default async function developer(pi: ExtensionAPI) {
       {
         ...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",
@@ -297,11 +354,12 @@ export default async function developer(pi: ExtensionAPI) {
     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",
@@ -318,12 +376,22 @@ 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.`);
@@ -351,6 +419,23 @@ export default async function developer(pi: ExtensionAPI) {
                   "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"
+            ? {
+                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,
           kind: "route",
@@ -362,6 +447,7 @@ export default async function developer(pi: ExtensionAPI) {
           targetQuestionId,
           methodLocation: skill?.filePath,
           executionProfile,
+          directStep,
         };
         const response = [
           `Route ID: ${event.routeId}`,
@@ -369,6 +455,14 @@ export default async function developer(pi: ExtensionAPI) {
           `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",
@@ -397,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,
@@ -425,6 +519,11 @@ export default async function developer(pi: ExtensionAPI) {
         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);
@@ -503,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) {
@@ -513,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);
@@ -541,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,
@@ -668,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(
@@ -717,10 +830,12 @@ export default async function developer(pi: ExtensionAPI) {
   });
 
   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

@@ -1,8 +1,9 @@
 # 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.
+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
 
@@ -42,13 +43,14 @@ valid. Do not rely on a final large diff to explain which step changed behavior.
 
 ## Evidence Rhythm
 
-After each meaningful movement:
+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 a green, deployable state before selecting another movement;
-5. re-observe the code instead of following a predetermined final design.
+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.
@@ -63,13 +65,15 @@ A stable landing is not merely a green command. It is a state where:
 - 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.
+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
 
-Leave direct execution and open a focused judgment when the movement reveals:
+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`;

package/extensions/state.ts

@@ -1,6 +1,8 @@
-export const PROTOCOL = "developer/v2" as const;
+export const PROTOCOL = "developer/v3" as const;
+export const PREVIOUS_PROTOCOL = "developer/v2" as const;
 export const LEGACY_PROTOCOL = "developer/v1" as const;
 export const MODE_ENTRY = "developer.mode" as const;
+export const FOCUS_ENTRY = "developer.question-focus" as const;
 export const ROUTE_TOOL = "developer_route_question" as const;
 export const JUDGMENT_TOOL = "developer_record_judgment" as const;
 export const LEGACY_ROUTE_TOOL = "route_question" as const;
@@ -17,6 +19,18 @@ export interface ModeEvent {
   mode: DeveloperMode;
 }
 
+export interface FocusEvent {
+  protocol: typeof PROTOCOL;
+  kind: "focus";
+  questionId: string;
+}
+
+export interface DirectStepContract {
+  movement: string;
+  stopCondition: string;
+  verification: string;
+}
+
 export interface RouteEvent {
   protocol: typeof PROTOCOL;
   kind: "route";
@@ -28,6 +42,7 @@ export interface RouteEvent {
   targetQuestionId?: string;
   methodLocation?: string;
   executionProfile?: DirectExecutionProfile;
+  directStep?: DirectStepContract;
 }
 
 export interface PendingQuestion {
@@ -48,9 +63,10 @@ export interface JudgmentEvent {
   basis: string[];
   openedQuestions: PendingQuestion[];
   artifacts: string[];
+  changedArtifacts: boolean;
 }
 
-export type DeveloperEvent = ModeEvent | RouteEvent | JudgmentEvent;
+export type DeveloperEvent = ModeEvent | FocusEvent | RouteEvent | JudgmentEvent;
 
 export interface DeveloperState {
   mode: DeveloperMode;
@@ -58,19 +74,25 @@ export interface DeveloperState {
   lastRoute?: RouteEvent;
   lastJudgment?: JudgmentEvent;
   pendingQuestions: PendingQuestion[];
+  focusedQuestionId?: string;
+  implementationFramingRequired: boolean;
+  verificationRequired: boolean;
 }
 
 export const initialState = (): DeveloperState => ({
   mode: "off",
   pendingQuestions: [],
+  implementationFramingRequired: false,
+  verificationRequired: false,
 });
 
-export type ProtocolState = "idle" | "needs-judgment" | "needs-evidence" | "blocked";
+export type ProtocolState = "idle" | "needs-judgment" | "needs-evidence" | "needs-verification" | "blocked";
 
 export function protocolState(state: DeveloperState): ProtocolState {
   if (state.activeRoute) return "needs-judgment";
   if (state.pendingQuestions.some((question) => question.status === "blocked")) return "blocked";
   if (state.pendingQuestions.length > 0) return "needs-evidence";
+  if (state.verificationRequired) return "needs-verification";
   return "idle";
 }
 
@@ -84,12 +106,19 @@ export function applyDeveloperEvent(state: DeveloperState, event: DeveloperEvent
     return { ...state, mode: event.mode };
   }
 
+  if (event.kind === "focus") {
+    if (!state.pendingQuestions.some((question) => question.id === event.questionId)) return state;
+    return { ...state, focusedQuestionId: event.questionId };
+  }
+
   if (event.kind === "route") {
     if (state.activeRoute) return state;
     return {
       ...state,
       activeRoute: event,
       lastRoute: event,
+      focusedQuestionId:
+        event.targetQuestionId === state.focusedQuestionId ? undefined : state.focusedQuestionId,
     };
   }
 
@@ -106,7 +135,7 @@ export function applyDeveloperEvent(state: DeveloperState, event: DeveloperEvent
       pending = upsertQuestion(pending, {
         id: route.targetQuestionId,
         question: route.question,
-        status: event.status,
+        status: event.status === "blocked" ? "blocked" : "needs-evidence",
         sourceRouteId: route.routeId,
       });
     }
@@ -114,18 +143,35 @@ export function applyDeveloperEvent(state: DeveloperState, event: DeveloperEvent
     pending = upsertQuestion(pending, {
       id: `question:${route.routeId}`,
       question: route.question,
-      status: event.status,
+      status: event.status === "blocked" ? "blocked" : "needs-evidence",
       sourceRouteId: route.routeId,
     });
   }
 
   for (const question of event.openedQuestions) pending = upsertQuestion(pending, question);
 
+  const closesFramingGate =
+    (route.owner === "sketch" || route.owner === "signal") &&
+    (event.status === "resolved" || event.status === "not-applicable");
+  const opensFramingGate = route.owner === "model" && event.status === "resolved";
+  let implementationFramingRequired = state.implementationFramingRequired;
+  if (opensFramingGate) implementationFramingRequired = true;
+  if (closesFramingGate) implementationFramingRequired = false;
+
+  let verificationRequired = state.verificationRequired;
+  if (route.owner === "direct" && event.changedArtifacts) verificationRequired = true;
+  if (route.owner === "verify" && event.status === "resolved") verificationRequired = false;
+
   return {
     ...state,
     activeRoute: undefined,
     lastJudgment: judgment,
     pendingQuestions: pending,
+    focusedQuestionId: pending.some((question) => question.id === state.focusedQuestionId)
+      ? state.focusedQuestionId
+      : undefined,
+    implementationFramingRequired,
+    verificationRequired,
   };
 }
 
@@ -149,6 +195,22 @@ function isDirectExecutionProfile(value: unknown): value is DirectExecutionProfi
   return value === "ordinary" || value === "behavior-preserving-structure";
 }
 
+function parseDirectStep(value: unknown): DirectStepContract | undefined {
+  if (!isObject(value)) return undefined;
+  if (
+    typeof value.movement !== "string" ||
+    typeof value.stopCondition !== "string" ||
+    typeof value.verification !== "string"
+  ) {
+    return undefined;
+  }
+  return {
+    movement: value.movement,
+    stopCondition: value.stopCondition,
+    verification: value.verification,
+  };
+}
+
 function parsePendingQuestion(value: unknown): PendingQuestion | undefined {
   if (!isObject(value)) return undefined;
   if (
@@ -169,13 +231,22 @@ function parsePendingQuestion(value: unknown): PendingQuestion | undefined {
 
 export function normalizeDeveloperEvent(value: unknown): DeveloperEvent | undefined {
   if (!isObject(value)) return undefined;
-  if (value.protocol !== PROTOCOL && value.protocol !== LEGACY_PROTOCOL) return undefined;
+  if (
+    value.protocol !== PROTOCOL &&
+    value.protocol !== PREVIOUS_PROTOCOL &&
+    value.protocol !== LEGACY_PROTOCOL
+  ) return undefined;
 
   if (value.kind === "mode") {
     if (!isMode(value.mode)) return undefined;
     return { protocol: PROTOCOL, kind: "mode", mode: value.mode };
   }
 
+  if (value.kind === "focus") {
+    if (value.protocol !== PROTOCOL || typeof value.questionId !== "string") return undefined;
+    return { protocol: PROTOCOL, kind: "focus", questionId: value.questionId };
+  }
+
   if (value.kind === "route") {
     if (
       typeof value.routeId !== "string" ||
@@ -185,7 +256,8 @@ export function normalizeDeveloperEvent(value: unknown): DeveloperEvent | undefi
       !isStringArray(value.knownEvidence) ||
       (value.targetQuestionId !== undefined && typeof value.targetQuestionId !== "string") ||
       (value.methodLocation !== undefined && typeof value.methodLocation !== "string") ||
-      (value.executionProfile !== undefined && !isDirectExecutionProfile(value.executionProfile))
+      (value.executionProfile !== undefined && !isDirectExecutionProfile(value.executionProfile)) ||
+      (value.directStep !== undefined && !parseDirectStep(value.directStep))
     ) {
       return undefined;
     }
@@ -200,6 +272,7 @@ export function normalizeDeveloperEvent(value: unknown): DeveloperEvent | undefi
       targetQuestionId: value.targetQuestionId,
       methodLocation: value.methodLocation,
       executionProfile: value.executionProfile,
+      directStep: value.directStep === undefined ? undefined : parseDirectStep(value.directStep),
     };
   }
 
@@ -231,9 +304,10 @@ export function normalizeDeveloperEvent(value: unknown): DeveloperEvent | undefi
         id: `question:${value.routeId}:legacy:${index + 1}`,
         question,
         status: "needs-evidence",
-        sourceRouteId: value.routeId,
+        sourceRouteId: String(value.routeId),
       })),
       artifacts: value.artifacts,
+      changedArtifacts: false,
     };
   }
 
@@ -251,6 +325,7 @@ export function normalizeDeveloperEvent(value: unknown): DeveloperEvent | undefi
     basis: value.basis,
     openedQuestions: openedQuestions as PendingQuestion[],
     artifacts: value.artifacts,
+    changedArtifacts: typeof value.changedArtifacts === "boolean" ? value.changedArtifacts : false,
   };
 }
 
@@ -261,7 +336,7 @@ interface BranchEntryLike {
   message?: { role?: string; toolName?: string; details?: unknown };
 }
 
-const DEVELOPER_TOOL_NAMES = new Set([
+const DEVELOPER_TOOL_NAMES = new Set<string>([
   ROUTE_TOOL,
   JUDGMENT_TOOL,
   LEGACY_ROUTE_TOOL,
@@ -269,7 +344,10 @@ const DEVELOPER_TOOL_NAMES = new Set([
 ]);
 
 export function eventFromBranchEntry(entry: BranchEntryLike): DeveloperEvent | undefined {
-  if (entry.type === "custom" && entry.customType === MODE_ENTRY) {
+  if (
+    entry.type === "custom" &&
+    (entry.customType === MODE_ENTRY || entry.customType === FOCUS_ENTRY)
+  ) {
     return normalizeDeveloperEvent(entry.data);
   }
   if (

package/extensions/tui.ts

@@ -5,6 +5,7 @@ import {
   type ThemeColor,
 } from "@earendil-works/pi-coding-agent";
 import {
+  Box,
   Container,
   matchesKey,
   type SelectItem,
@@ -32,7 +33,7 @@ function modeName(mode: DeveloperMode): string {
 
 function protocolColor(value: ProtocolState): ThemeColor {
   if (value === "blocked") return "error";
-  if (value === "needs-evidence") return "warning";
+  if (value === "needs-evidence" || value === "needs-verification") return "warning";
   if (value === "needs-judgment") return "accent";
   return "dim";
 }
@@ -109,6 +110,51 @@ interface SelectDialogOptions {
   maxPrimaryColumnWidth?: number;
 }
 
+class SelectionPreview {
+  private item?: SelectItem;
+  private offset = 0;
+  private lastWidth = 40;
+  private readonly theme: Theme;
+  private readonly maxLines: number;
+
+  constructor(theme: Theme, maxLines = 5) {
+    this.theme = theme;
+    this.maxLines = maxLines;
+  }
+
+  setItem(item: SelectItem): void {
+    this.item = item;
+    this.offset = 0;
+  }
+
+  scroll(delta: number): void {
+    const total = this.contentLines(this.lastWidth).length;
+    this.offset = Math.max(0, Math.min(this.offset + delta, Math.max(0, total - this.maxLines)));
+  }
+
+  render(width: number): string[] {
+    this.lastWidth = width;
+    const lines = this.contentLines(width);
+    const visible = lines.slice(this.offset, this.offset + this.maxLines);
+    if (lines.length > this.maxLines) {
+      const end = Math.min(lines.length, this.offset + this.maxLines);
+      visible.push(this.theme.fg("dim", `  detail ${this.offset + 1}–${end}/${lines.length} · shift+↑↓ scroll`));
+    }
+    return visible;
+  }
+
+  invalidate(): void {}
+
+  private contentLines(width: number): string[] {
+    if (!this.item) return [];
+    const content = [
+      this.theme.fg("accent", this.theme.bold(this.item.label)),
+      ...(this.item.description ? [this.theme.fg("muted", this.item.description)] : []),
+    ].join("\n");
+    return new Text(content, 1, 0).render(width);
+  }
+}
+
 async function showSelectDialog(
   ctx: ExtensionCommandContext,
   options: SelectDialogOptions,
@@ -116,13 +162,17 @@ async function showSelectDialog(
   const result = await ctx.ui.custom<string | null>(
     (tui, theme, _keybindings, done) => {
       const container = new Container();
+      const surface = new Box(1, 0, (text) => theme.bg("customMessageBg", text));
+      surface.addChild(container);
       const title = new Text("", 1, 0);
       const subtitle = new Text("", 1, 0);
       const hint = new Text("", 1, 0);
+      const previewLabel = new Text(theme.fg("dim", "Selected detail"), 1, 0);
+      const preview = new SelectionPreview(theme);
       const updateText = () => {
-        title.setText(theme.fg("accent", theme.bold(options.title)));
+        title.setText(theme.fg("accent", theme.bold(`◆ ${options.title}`)));
         subtitle.setText(theme.fg("muted", options.subtitle));
-        hint.setText(theme.fg("dim", "↑↓ navigate · enter select · esc cancel"));
+        hint.setText(theme.fg("dim", "↑↓ navigate · shift+↑↓ scroll detail · enter select · esc cancel"));
       };
       updateText();
 
@@ -142,24 +192,32 @@ async function showSelectDialog(
       );
       list.onSelect = (item) => done(item.value);
       list.onCancel = () => done(null);
+      list.onSelectionChange = (item) => preview.setItem(item);
+      const initialItem = list.getSelectedItem();
+      if (initialItem) preview.setItem(initialItem);
 
       container.addChild(new DynamicBorder((text) => theme.fg("borderAccent", text)));
       container.addChild(title);
       container.addChild(subtitle);
       container.addChild(list);
+      container.addChild(new DynamicBorder((text) => theme.fg("borderMuted", text)));
+      container.addChild(previewLabel);
+      container.addChild(preview);
       container.addChild(hint);
       container.addChild(new DynamicBorder((text) => theme.fg("borderAccent", text)));
 
       return {
         render(width: number) {
-          return container.render(width);
+          return surface.render(width);
         },
         invalidate() {
           updateText();
-          container.invalidate();
+          surface.invalidate();
         },
         handleInput(data: string) {
-          list.handleInput(data);
+          if (matchesKey(data, "shift+up")) preview.scroll(-1);
+          else if (matchesKey(data, "shift+down")) preview.scroll(1);
+          else list.handleInput(data);
           tui.requestRender();
         },
       };
@@ -169,7 +227,7 @@ async function showSelectDialog(
       overlayOptions: {
         anchor: "center",
         width: options.width,
-        maxHeight: Math.min(options.maxVisible + 7, 20),
+        maxHeight: Math.min(options.maxVisible + 15, 26),
         margin: 1,
       },
     },
@@ -241,6 +299,12 @@ export class DeveloperWidget {
     if (this.state.pendingQuestions.length > 3) {
       lines.push(this.theme.fg("dim", `  +${this.state.pendingQuestions.length - 3} more open questions`));
     }
+    if (this.state.implementationFramingRequired) {
+      lines.push(this.theme.fg("warning", "→ next · sketch feature shape or signal structural movement"));
+    }
+    if (this.state.verificationRequired) {
+      lines.push(this.theme.fg("warning", "→ next · verify changed artifacts before completion"));
+    }
     return lines;
   }
 
@@ -259,17 +323,35 @@ export class DeveloperStatusPanel {
   private readonly view: DeveloperStatusView;
   private readonly theme: Theme;
   private readonly onClose: () => void;
-
-  constructor(view: DeveloperStatusView, theme: Theme, onClose: () => void) {
+  private readonly requestRender: () => void;
+  private readonly viewportHeight: number;
+  private scrollOffset = 0;
+  private maxScrollOffset = 0;
+
+  constructor(
+    view: DeveloperStatusView,
+    theme: Theme,
+    onClose: () => void,
+    options: { viewportHeight?: number; requestRender?: () => void } = {},
+  ) {
     this.view = view;
     this.theme = theme;
     this.onClose = onClose;
+    this.viewportHeight = options.viewportHeight ?? 24;
+    this.requestRender = options.requestRender ?? (() => {});
   }
 
   handleInput(data: string): void {
     if (matchesKey(data, "escape") || matchesKey(data, "enter") || matchesKey(data, "ctrl+c")) {
       this.onClose();
+      return;
     }
+    if (matchesKey(data, "up")) this.scrollOffset = Math.max(0, this.scrollOffset - 1);
+    else if (matchesKey(data, "down")) {
+      this.scrollOffset = Math.min(this.maxScrollOffset, this.scrollOffset + 1);
+    } else return;
+    this.invalidate();
+    this.requestRender();
   }
 
   render(width: number): string[] {
@@ -278,17 +360,22 @@ export class DeveloperStatusPanel {
     const panelWidth = Math.max(20, width);
     const innerWidth = Math.max(18, panelWidth - 2);
     const rows: string[] = [];
-    const border = (text: string) => this.theme.fg("borderMuted", text);
-    const row = (content = "") => `${border("│")}${truncateToWidth(content, innerWidth, "…", true)}${border("│")}`;
-    const addWrapped = (label: string, value: string, color: ThemeColor = "muted", maxLines = 2) => {
+    const background = (text: string) => this.theme.bg("customMessageBg", text);
+    const border = (text: string) => this.theme.fg("borderAccent", text);
+    const row = (content = "") => {
+      const clipped = truncateToWidth(content, innerWidth, "…", true);
+      const padding = " ".repeat(Math.max(0, innerWidth - visibleWidth(clipped)));
+      return background(`${border("│")}${clipped}${padding}${border("│")}`);
+    };
+    const addWrapped = (label: string, value: string, color: ThemeColor = "muted", _maxLines?: number) => {
       const prefix = `  ${this.theme.fg("dim", `${label} ·`)} `;
-      const wrapped = wrapTextWithAnsi(prefix + this.theme.fg(color, value), innerWidth).slice(0, maxLines);
+      const wrapped = wrapTextWithAnsi(prefix + this.theme.fg(color, value), innerWidth);
       for (const line of wrapped) rows.push(row(line));
     };
     const section = (title: string) => rows.push(row(`  ${this.theme.fg("accent", this.theme.bold(title))}`));
 
-    rows.push(border(`╭${"─".repeat(innerWidth)}╮`));
-    rows.push(row(`  ${this.theme.fg("accent", this.theme.bold("Developer status"))}`));
+    rows.push(background(border(`╭${"─".repeat(innerWidth)}╮`)));
+    rows.push(row(`  ${this.theme.fg("accent", this.theme.bold("◆ Developer status"))}`));
     rows.push(row());
 
     const state = this.view.state;
@@ -320,7 +407,7 @@ export class DeveloperStatusPanel {
     if (state.pendingQuestions.length === 0) {
       addWrapped("state", "No unresolved Developer questions.", "dim", 1);
     } else {
-      for (const question of state.pendingQuestions.slice(0, 4)) {
+      for (const question of state.pendingQuestions) {
         addWrapped(
           question.status === "blocked" ? "blocked" : "needs evidence",
           question.question,
@@ -328,9 +415,6 @@ export class DeveloperStatusPanel {
           1,
         );
       }
-      if (state.pendingQuestions.length > 4) {
-        addWrapped("more", String(state.pendingQuestions.length - 4), "dim", 1);
-      }
     }
 
     rows.push(row());
@@ -363,11 +447,27 @@ export class DeveloperStatusPanel {
     );
     rows.push(row());
     rows.push(row(`  ${this.theme.fg("dim", "enter/esc close · /develop questions revisits open work")}`));
-    rows.push(border(`╰${"─".repeat(innerWidth)}╯`));
+    rows.push(background(border(`╰${"─".repeat(innerWidth)}╯`)));
+
+    const header = rows.slice(0, 2);
+    const body = rows.slice(2, -2);
+    const bodyCapacity = Math.max(1, this.viewportHeight - 4);
+    this.maxScrollOffset = Math.max(0, body.length - bodyCapacity);
+    this.scrollOffset = Math.min(this.scrollOffset, this.maxScrollOffset);
+    const visibleBody = body.slice(this.scrollOffset, this.scrollOffset + bodyCapacity);
+    const position = body.length > bodyCapacity
+      ? `↑↓ scroll · ${this.scrollOffset + 1}–${Math.min(body.length, this.scrollOffset + bodyCapacity)}/${body.length} · enter/esc close`
+      : "enter/esc close · /develop questions revisits open work";
+    const visibleRows = [
+      ...header,
+      ...visibleBody,
+      row(`  ${this.theme.fg("dim", position)}`),
+      background(border(`╰${"─".repeat(innerWidth)}╯`)),
+    ];
 
     this.cachedWidth = width;
-    this.cachedLines = rows;
-    return rows;
+    this.cachedLines = visibleRows;
+    return visibleRows;
   }
 
   invalidate(): void {
@@ -380,12 +480,27 @@ export async function showDeveloperStatus(
   ctx: ExtensionCommandContext,
   view: DeveloperStatusView,
 ): Promise<void> {
-  await ctx.ui.custom<void>((_tui, theme, _keybindings, done) =>
-    new DeveloperStatusPanel(view, theme, () => done()));
+  await ctx.ui.custom<void>(
+    (tui, theme, _keybindings, done) =>
+      new DeveloperStatusPanel(view, theme, () => done(), {
+        viewportHeight: Math.max(12, Math.floor(tui.terminal.rows * 0.8)),
+        requestRender: () => tui.requestRender(),
+      }),
+    {
+      overlay: true,
+      overlayOptions: {
+        anchor: "center",
+        width: "82%",
+        minWidth: 56,
+        maxHeight: "85%",
+        margin: 1,
+      },
+    },
+  );
 }
 
 export function prepareQuestionPrompt(ctx: ExtensionCommandContext, question: PendingQuestion): void {
-  const prompt = `Revisit Developer question ${question.id}: ${question.question}`;
+  const prompt = `Revisit this Developer question: ${question.question}`;
   const current = ctx.ui.getEditorText();
   ctx.ui.setEditorText(current.trim() ? `${current.trimEnd()}\n\n${prompt}` : prompt);
 }

package/package.json

@@ -1,14 +1,9 @@
 {
   "name": "@hobin/developer",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Adaptive product-development reasoning and evidence for Pi.",
   "type": "module",
-  "keywords": [
-    "pi-package",
-    "pi",
-    "developer",
-    "skills"
-  ],
+  "keywords": ["pi-package", "pi", "developer", "skills"],
   "license": "MIT",
   "author": {
     "name": "dev-hobin",
@@ -26,33 +21,23 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "extensions",
-    "skills",
-    "README.md",
-    "SOURCES.md",
-    "LICENSE"
-  ],
+  "files": ["extensions", "skills", "README.md", "SOURCES.md", "LICENSE"],
   "engines": {
     "node": ">=22.19.0"
   },
+  "scripts": {
+    "check": "node scripts/check-package.mjs && node --test tests/*.test.ts",
+    "eval": "node scripts/eval-rpc.mjs",
+    "eval:json": "node scripts/eval-json.mjs"
+  },
   "pi": {
-    "extensions": [
-      "./extensions/developer.ts"
-    ],
-    "skills": [
-      "./skills"
-    ]
+    "extensions": ["./extensions/developer.ts"],
+    "skills": ["./skills"]
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
-  },
-  "scripts": {
-    "check": "node scripts/check-package.mjs && node --test tests/*.test.ts",
-    "eval": "node scripts/eval-rpc.mjs",
-    "eval:json": "node scripts/eval-json.mjs"
   }
-}
+}