@jwilger/pi-development-system 0.74.2 → 0.76.0

package/extensions/development-system.ts

@@ -1,8 +1,14 @@
 // pi-lens-ignore: high-import-coupling -- composition root: it imports every module it wires, by design
 import { readFileSync } from "node:fs";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
 import { cadenceLine, DEFAULT_PUSH_MINUTES } from "../src/context/cadence.ts";
 import { appendContextTail, renderContextTail } from "../src/context/context-tail.ts";
+import { createPhaseTool } from "../src/context/devsys-tool.ts";
+import { applyIntentGuideline } from "../src/context/intent-trigger.ts";
 import { registerModelAdvice } from "../src/context/model-advice.ts";
 import { renderStatus, renderStatusLine, STATUS_KEY } from "../src/context/status.ts";
 import { applyPromptSection } from "../src/context/system-prompt.ts";
@@ -11,6 +17,7 @@ import { type Exec, timeoutAsFailure } from "../src/core/exec.ts";
 import { defaultMatrix } from "../src/core/models.ts";
 import { createApprovalStore } from "../src/gates/approvals.ts";
 import { registerCommitGuard } from "../src/gates/commit-guard.ts";
+import { declareWithoutCodemode } from "../src/gates/exposure.ts";
 import { registerGitGuard } from "../src/gates/git-guard.ts";
 import { registerLintSuppressionGuard } from "../src/gates/lint-suppression-guard.ts";
 import { registerPushGuard } from "../src/gates/push-guard.ts";
@@ -19,6 +26,7 @@ import { registerRedFirstGuard } from "../src/gates/red-first-guard.ts";
 import { createRequestApprovalTool } from "../src/gates/request-approval-tool.ts";
 import { registerTestGuard } from "../src/gates/test-guard.ts";
 import { createJevHolder } from "../src/jev/holder.ts";
+import { createJudgeTools } from "../src/jev/judge-tools.ts";
 import { createBeginWorkTool } from "../src/planning/begin-tool.ts";
 import { createIntakeTool } from "../src/planning/intake-tool.ts";
 import { createTaskCheckTool } from "../src/planning/task-check-tool.ts";
@@ -81,8 +89,9 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   pi.on("session_start", (_event, ctx) => rebuild(ctx));
   pi.on("session_tree", (_event, ctx) => rebuild(ctx));
 
-  pi.on("before_agent_start", (event) => {
+  pi.on("before_agent_start", async (event, ctx) => {
     applyPromptSection(event, state.get(), nonNegotiables);
+    await applyIntentGuideline(event, state.get(), jevHolder.forContext(ctx));
   });
 
   pi.on("context", (event) => {
@@ -140,12 +149,19 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   registerLintSuppressionGuard({ pi, state });
   pi.registerTool(createRecordDepartureTool({ pi, state }));
   pi.registerTool(createRequestApprovalTool({ pi, approvals }));
-  pi.registerTool(createModelsTool());
-  pi.registerTool(createRouteTaskTool({ jev: (ctx) => jevHolder.forContext(ctx) }));
+  // Rarely used tools: reached through codemode when it is on, declared directly when it is not.
+  const rarelyUsed: ToolDefinition[] = [
+    createModelsTool(),
+    createRouteTaskTool({ jev: (ctx) => jevHolder.forContext(ctx) }),
+    createTaskCheckTool({ jev: (ctx) => jevHolder.forContext(ctx) }),
+    createWorkItemTool({ exec }),
+    ...createJudgeTools({ jev: (ctx) => jevHolder.forContext(ctx) }),
+  ];
+  for (const tool of rarelyUsed) pi.registerTool(tool);
+  pi.on("session_start", () => declareWithoutCodemode(pi, rarelyUsed));
+  pi.registerTool(createPhaseTool({ state }));
   pi.registerTool(createBeginWorkTool({ state }));
   pi.registerTool(createIntakeTool({ pi, state, jev: (ctx) => jevHolder.forContext(ctx) }));
-  pi.registerTool(createTaskCheckTool({ jev: (ctx) => jevHolder.forContext(ctx) }));
-  pi.registerTool(createWorkItemTool({ exec }));
   const reviewDeps = {
     state,
     jev: (ctx: ExtensionContext) => jevHolder.forContext(ctx),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.74.2",
+  "version": "0.76.0",
   "description": "A pi extension package representing a seasoned approach to software development using a full AI SDLC.",
   "keywords": [
     "pi-package"

package/src/context/devsys-tool.ts

@@ -0,0 +1,34 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { SessionState } from "../state/session-state.ts";
+import { phaseGuide } from "./phase-guide.ts";
+
+const BASE =
+  "What the development system expects in the current workflow phase, and which tools to use. Call it when unsure what comes next.";
+
+/** `devsys`: a model-only tool whose description is rewritten each turn with the current phase's guidance. */
+export function createPhaseTool(deps: { state: SessionState }): ToolDefinition {
+  return {
+    name: "devsys",
+    label: "Workflow guide",
+    description: BASE,
+    promptSnippet: "Show what the workflow expects in the current phase",
+    parameters: Type.Object({}),
+    exposure: "model-only",
+    prepareLoadout: () => ({
+      descriptions: {
+        devsys: `${BASE} Current phase (${deps.state.get().phase}): ${phaseGuide(deps.state.get().phase)}`,
+      },
+    }),
+    execute() {
+      const { phase, sizing, activeSlice } = deps.state.get();
+      const text = [
+        `phase: ${phase}`,
+        `sizing: ${sizing ?? "none"}`,
+        `slice: ${activeSlice ?? "none"}`,
+        phaseGuide(phase),
+      ].join("\n");
+      return Promise.resolve({ content: [{ type: "text" as const, text }], details: undefined });
+    },
+  };
+}

package/src/context/intent-trigger.ts

@@ -0,0 +1,43 @@
+import type { BeforeAgentStartEvent } from "@earendil-works/pi-coding-agent";
+import type { DevsysState } from "../core/types.ts";
+import type { Jev } from "../jev/client.ts";
+import { type Intent, judgeIntent } from "../jev/questions/intent.ts";
+
+/** Probability at or above which an intent is acted on. */
+export const INTENT_AT = 0.7;
+
+/** Pure: the one guideline line an intent earns in a phase, or undefined. Questions and continuations earn none. */
+export function intentGuideline(
+  intent: Intent,
+  confidence: number,
+  phase: DevsysState["phase"],
+): string | undefined {
+  if (confidence < INTENT_AT) return undefined;
+  const idle = phase === "idle";
+  if ((intent === "new-work" || intent === "fix") && (idle || intent === "new-work")) {
+    return "This prompt asks for new work: call devsys_intake with the request before editing anything, so it is sized and the planning artifacts it needs are named.";
+  }
+  if (intent === "review" && idle) {
+    return "This prompt asks for a review: call devsys_review_start for a fresh-context review instead of reviewing in this conversation.";
+  }
+  return undefined;
+}
+
+/** Slash commands and empty prompts are not judged. */
+const judgeable = (prompt: string): boolean => {
+  const trimmed = prompt.trim();
+  return trimmed !== "" && !trimmed.startsWith("/");
+};
+
+/** Adapter: judge the prompt, and add the line to this run's guidelines. Jev trouble adds nothing. */
+export async function applyIntentGuideline(
+  event: BeforeAgentStartEvent,
+  state: DevsysState,
+  jev: Jev,
+): Promise<void> {
+  if (!judgeable(event.prompt)) return;
+  const judged = await judgeIntent(jev, { prompt: event.prompt, phase: state.phase });
+  if (!judged.ok) return;
+  const line = intentGuideline(judged.value.intent, judged.value.confidence, state.phase);
+  if (line !== undefined) event.systemPromptOptions.promptGuidelines.push(line);
+}

package/src/context/phase-guide.ts

@@ -0,0 +1,21 @@
+import { assertNever } from "../core/exhaustive.ts";
+import type { Phase } from "../core/types.ts";
+
+/** What to do in each phase, in one paragraph. Pure; the `devsys` tool and its description both use it. */
+export function phaseGuide(phase: Phase): string {
+  switch (phase) {
+    case "idle":
+      return "Nothing is in flight. For new work or a fix, call devsys_intake with the user's request before editing: it sizes the work and names the planning artifacts it needs.";
+    case "intake":
+    case "planning":
+      return "Planning. Produce the artifacts the sizing asked for, write task records (check each with devsys_task_check), and when the user approves the plan call devsys_begin_work.";
+    case "implementing":
+      return "Implementing one slice. Write a failing test first, make it pass with the least code, run the tests and read the result before claiming anything. Push small, verified increments.";
+    case "reviewing":
+      return "Reviewing. Call devsys_review_start for a fresh-context review, pass its packet and diffDigest to devsys_review_record, fix every blocking and should-fix finding, and repeat until the round is clean.";
+    case "delivering":
+      return "Delivering. Commit with a rationale, push to trunk, wait for CI to go green, and release before starting the next slice. A red trunk is repaired first.";
+    default:
+      return assertNever(phase);
+  }
+}

package/src/gates/exposure.ts

@@ -0,0 +1,11 @@
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Tools registered with `exposure: "codemode"` are reachable only through the `codemode` tool.
+ * When that tool is not active, the model could not reach them at all, so declare them directly.
+ * Runs at session start: pi's tool state cannot be read while an extension loads.
+ */
+export function declareWithoutCodemode(pi: ExtensionAPI, tools: readonly ToolDefinition[]): void {
+  if (pi.getActiveTools().includes("codemode")) return;
+  for (const tool of tools) pi.registerTool({ ...tool, exposure: "direct" });
+}

package/src/gates/request-approval-tool.ts

@@ -30,7 +30,7 @@ export function createRequestApprovalTool(
       "only valid for the exact command text. Unavailable when running headless.",
     promptSnippet: "Ask the user to approve an irreversible git command (hard stop)",
     parameters: Parameters,
-    exposure: "direct",
+    exposure: "model-only",
     async execute(toolCallId, params: Static<typeof Parameters>, _signal, _onUpdate, ctx) {
       const gate = parseGateId(params.gate);
       if (params.gate === "commit.forbidden-trailer") {

package/src/jev/judge-tools.ts

@@ -0,0 +1,122 @@
+import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Static, type TSchema, Type } from "typebox";
+import type { Result } from "../core/result.ts";
+import { isParseError } from "../core/types.ts";
+import { parseTaskRecord } from "../planning/task-record.ts";
+import type { Jev, JevError } from "./client.ts";
+import { judgeTaskReadiness } from "./questions/readiness.ts";
+import { judgeLenses } from "./questions/review.ts";
+import { judgeSizing } from "./questions/sizing.ts";
+import { judgeTestChange } from "./questions/test-change.ts";
+
+/** Tool namespace that groups the Jev judgements for codemode scripts. */
+const JUDGE_NAMESPACE = {
+  name: "devsys-judge",
+  description:
+    "Jev judgements as data: probabilities and labels a script can branch on (sizing, test-change, lenses, task readiness).",
+  instructions:
+    "Each tool returns JSON text: the judgement, or {error} when Jev is unavailable. Inputs are redacted and clipped before they reach Jev. Use these inside codemode scripts; they change no state.",
+} as const;
+
+type Deps = { jev: (ctx: ExtensionContext) => Jev };
+
+const reply = (payload: unknown, isError = false) => ({
+  content: [{ type: "text" as const, text: JSON.stringify(payload) }],
+  details: undefined,
+  isError,
+});
+
+const fromResult = (result: Result<unknown, JevError>) =>
+  result.ok ? reply(result.value) : reply({ error: result.error }, true);
+
+function judgeTool<P extends TSchema>(
+  spec: {
+    name: string;
+    label: string;
+    description: string;
+    parameters: P;
+  },
+  run: (deps: Deps, params: Static<P>, ctx: ExtensionContext) => Promise<ReturnType<typeof reply>>,
+  deps: Deps,
+): ToolDefinition<P> {
+  return {
+    ...spec,
+    exposure: "codemode",
+    namespace: JUDGE_NAMESPACE,
+    execute: (_id, params, _signal, _onUpdate, ctx) => run(deps, params, ctx),
+  };
+}
+
+export function createJudgeTools(deps: Deps): ToolDefinition[] {
+  const sizing = judgeTool(
+    {
+      name: "judge_sizing",
+      label: "Judge sizing",
+      description:
+        "Size a request as fix, change, capability or product, with the probability each planning artifact is needed.",
+      parameters: Type.Object({
+        request: Type.String(),
+        repoSummary: Type.Optional(Type.String()),
+      }),
+    },
+    async (d, p, ctx) =>
+      fromResult(
+        await judgeSizing(d.jev(ctx), { request: p.request, repoSummary: p.repoSummary ?? "" }),
+      ),
+    deps,
+  );
+  const testChange = judgeTool(
+    {
+      name: "judge_test_change",
+      label: "Judge test change",
+      description:
+        "Judge whether a change to a test file weakens what the tests verify. Omit `after` for a deleted file.",
+      parameters: Type.Object({
+        path: Type.String(),
+        before: Type.Optional(Type.String()),
+        after: Type.Optional(Type.String()),
+        recentFailure: Type.Optional(Type.String()),
+      }),
+    },
+    async (d, p, ctx) => fromResult(await judgeTestChange(d.jev(ctx), p)),
+    deps,
+  );
+  const lenses = judgeTool(
+    {
+      name: "judge_lenses",
+      label: "Judge review lenses",
+      description: "Probability per review lens that it applies to a diff.",
+      parameters: Type.Object({
+        diffStat: Type.String(),
+        diffSample: Type.String(),
+        profiles: Type.Optional(Type.Array(Type.String())),
+      }),
+    },
+    async (d, p, ctx) =>
+      fromResult(
+        await judgeLenses(d.jev(ctx), {
+          diffStat: p.diffStat,
+          diffSample: p.diffSample,
+          profiles: p.profiles ?? [],
+        }),
+      ),
+    deps,
+  );
+  const readiness = judgeTool(
+    {
+      name: "judge_task_readiness",
+      label: "Judge task readiness",
+      description:
+        "Judge whether a task record (markdown, optionally one id out of a plan) is ready for an implementer: ready, needs-detail or too-big.",
+      parameters: Type.Object({ markdown: Type.String(), id: Type.Optional(Type.String()) }),
+    },
+    async (d, p, ctx) => {
+      const record = parseTaskRecord(p.markdown, p.id);
+      if (isParseError(record)) return reply({ error: record.message }, true);
+      return fromResult(await judgeTaskReadiness(d.jev(ctx), record));
+    },
+    deps,
+  );
+  // SAFETY: pi stores tools as ToolDefinition<TSchema>; each tool here only reads its own validated params.
+  return [sizing, testChange, lenses, readiness] as unknown as ToolDefinition[];
+}

package/src/jev/questions/intent.ts

@@ -0,0 +1,40 @@
+import type { ClassifierChoiceQuestion } from "@earendil-works/pi-ai";
+import { redactSecrets } from "../../core/redact.ts";
+import { err, ok, type Result } from "../../core/result.ts";
+import type { Jev, JevError } from "../client.ts";
+
+export const INTENTS = ["new-work", "fix", "review", "question", "continuation"] as const;
+export type Intent = (typeof INTENTS)[number];
+
+export const INTENT_QUESTION: ClassifierChoiceQuestion = {
+  type: "choice",
+  instructions:
+    "What does the user's `prompt` ask the assistant to do, given the workflow `phase` the session is in? Judge the request itself, not its tone. A short reply that answers or approves what the assistant just said is a continuation.",
+  criteria: {
+    "new-work":
+      "Asks to build, add, change, remove, rename or restructure something in the code, docs or configuration",
+    fix: "Reports something broken, failing or wrong and wants it repaired",
+    review: "Asks for existing work, a diff, a plan or a document to be reviewed or checked",
+    question:
+      "Asks for an explanation, information or an opinion and does not ask for any change to be made",
+    continuation:
+      "A short reply to the assistant's last message: a confirmation, a choice, 'continue', 'yes', 'go ahead', or an answer to its question",
+  },
+};
+
+const PROMPT_MAX = 1500;
+const isIntent = (value: string): value is Intent => INTENTS.some((i) => i === value);
+
+export async function judgeIntent(
+  jev: Jev,
+  input: { prompt: string; phase: string },
+): Promise<Result<{ intent: Intent; confidence: number }, JevError>> {
+  const prompt = redactSecrets(input.prompt.slice(0, PROMPT_MAX * 2)).slice(0, PROMPT_MAX);
+  const asked = await jev.ask({ prompt, phase: input.phase }, { intent: INTENT_QUESTION });
+  if (!asked.ok) return asked;
+  const answer = asked.value.intent;
+  if (answer?.type !== "choice" || !isIntent(answer.choice)) {
+    return err({ kind: "provider", message: "missing or unknown intent answer" });
+  }
+  return ok({ intent: answer.choice, confidence: answer.confidence });
+}

package/src/planning/begin-tool.ts

@@ -25,7 +25,7 @@ export function createBeginWorkTool(deps: {
       "Move from planning to implementing once the user has approved the plan. This switches on the review and red-first gates for the active slice.",
     promptSnippet: "Start implementing after the plan is approved",
     parameters: Parameters,
-    exposure: "direct",
+    exposure: "model-only",
     execute(_id, _params: Static<typeof Parameters>) {
       const { phase, activeSlice } = deps.state.get();
       if (phase === "implementing" && activeSlice !== undefined) {

package/src/planning/intake-tool.ts

@@ -123,7 +123,7 @@ export function createIntakeTool(deps: {
       "The user confirms the size; then phase, sizing and the active slice are set. Call at the start of any non-trivial work.",
     promptSnippet: "Size new work and propose the planning artifacts it needs",
     parameters: Parameters,
-    exposure: "direct",
+    exposure: "model-only",
     async execute(_id, params: Static<typeof Parameters>, _signal, _onUpdate, ctx) {
       const request = params.request.trim();
       if (request === "") return reply("request must not be empty", true);

package/src/planning/task-check-tool.ts

@@ -50,7 +50,7 @@ export function createTaskCheckTool(deps: {
       "Run before handing a task record to an implementer subagent.",
     promptSnippet: "Check a task record is ready for an implementer",
     parameters: Parameters,
-    exposure: "direct",
+    exposure: "codemode",
     async execute(_id, params: Static<typeof Parameters>, _signal, _onUpdate, ctx) {
       const target = resolve(ctx.cwd, params.path);
       if (!insideRepo(ctx.cwd, target))

package/src/review/review-tools.ts

@@ -215,7 +215,7 @@ export function createReviewStartTool(
       "Begin a review round for a slice: computes the diff digest, chooses review lenses, and returns the agent_spawn payload for a fresh-context reviewer. Run that spawn, then pass the reviewer's packet to devsys_review_record.",
     promptSnippet: "Start a fresh-context review round for a slice",
     parameters: StartParameters,
-    exposure: "direct",
+    exposure: "model-only",
     async execute(
       _id,
       params: Static<typeof StartParameters>,

package/src/state/models-command.ts

@@ -199,7 +199,7 @@ export function createModelsTool(): ToolDefinition<typeof Parameters> {
       "Return the model this project's matrix resolves each slot to (frontier, strong, fast, planning, advisor, implementer, reviewer, lens, researcher, jev) given the credentials on this machine.",
     promptSnippet: "Look up which model a development-system slot resolves to",
     parameters: Parameters,
-    exposure: "direct",
+    exposure: "codemode",
     async execute(
       _id,
       params: Static<typeof Parameters>,

package/src/state/route-task-tool.ts

@@ -36,7 +36,7 @@ export function createRouteTaskTool(deps: {
       "Recommend which model and thinking level a subagent should use for a task. Call before agent_spawn for implementer or reviewer work and pass the returned model and thinkingLevel.",
     promptSnippet: "Recommend model and thinking level for a subagent task",
     parameters: Parameters,
-    exposure: "direct",
+    exposure: "codemode",
     async execute(
       _id,
       params: Static<typeof Parameters>,

package/src/tracker/work-item-tool.ts

@@ -120,7 +120,7 @@ export function createWorkItemTool(deps: { exec: Exec }): ToolDefinition<typeof
       "Use it for the backlog instead of editing tracker files or running gh by hand.",
     promptSnippet: "Read and write the project's work items",
     parameters: Parameters,
-    exposure: "direct",
+    exposure: "codemode",
     async execute(
       _id,
       params: Static<typeof Parameters>,