@jwilger/pi-development-system 0.75.0 → 0.77.0

package/extensions/development-system.ts

@@ -7,6 +7,8 @@ import type {
 } 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";
@@ -87,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) => {
@@ -156,6 +159,7 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   ];
   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) }));
   const reviewDeps = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.75.0",
+  "version": "0.77.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/context/turn-verifier.ts

@@ -5,6 +5,7 @@ import type {
   ToolResultEvent,
 } from "@earendil-works/pi-coding-agent";
 import { redactSecrets } from "../core/redact.ts";
+import { reviewOf } from "../core/review-flow.ts";
 import { exitCodeOf, summarizeOutput } from "../core/test-runner.ts";
 import type { DevsysState, Phase } from "../core/types.ts";
 import type { Jev } from "../jev/client.ts";
@@ -58,6 +59,9 @@ export function asksUser(text: string): boolean {
   return QUESTION_END.test(lead) || (LIST_ITEM.test(last) && CHOICE_LEAD_IN.test(lead));
 }
 
+const hasReviewRound = (state: DevsysState, slice: DevsysState["activeSlice"] & string): boolean =>
+  (reviewOf(state, slice)?.rounds.length ?? 0) > 0;
+
 /** True when a scope.expansion departure already covers the slice: the remedy the note asks for exists. */
 const expansionRecorded = (state: DevsysState, slice: string): boolean =>
   state.openDepartures.some(
@@ -72,6 +76,9 @@ const claimMessage = (): string =>
 const driftMessage = (slice: string): string =>
   `Development system: your last message describes work beyond the active slice "${slice}". Either return to the slice, or call devsys_record_departure (gate scope.expansion) to record why the scope is growing.`;
 
+const reviewMessage = (slice: string): string =>
+  `Development system: your last message calls the slice "${slice}" finished, but no review round has been recorded for it. Call devsys_review_start for a fresh-context review before committing.`;
+
 const TARGET_MAX = 120;
 
 const note = (content: string) => ({
@@ -107,7 +114,7 @@ function evidenceOf(event: ToolResultEvent): ToolEvidence {
 
 /** The corrective notes a judged turn earns: an unverified claim, and drift not yet covered by a departure. */
 function correctionsFor(
-  judged: { unverifiedClaim: number; driftFromSlice: number },
+  judged: { unverifiedClaim: number; driftFromSlice: number; sliceDone: number },
   state: DevsysState,
 ) {
   const slice = state.activeSlice;
@@ -118,6 +125,11 @@ function correctionsFor(
   return [
     ...(judged.unverifiedClaim >= VERIFIER_THRESHOLD ? [note(claimMessage())] : []),
     ...(drifted && slice !== undefined ? [note(driftMessage(slice))] : []),
+    ...(slice !== undefined &&
+    judged.sliceDone >= VERIFIER_THRESHOLD &&
+    !hasReviewRound(state, slice)
+      ? [note(reviewMessage(slice))]
+      : []),
   ];
 }
 
@@ -163,6 +175,10 @@ export function registerTurnVerifier(deps: TurnVerifierDeps): void {
       assistantText: parts.text,
       toolEvidence: evidence,
       ...(state.activeSlice === undefined ? {} : { activeSlice: state.activeSlice }),
+      checkDone:
+        state.phase === "implementing" &&
+        state.activeSlice !== undefined &&
+        !hasReviewRound(state, state.activeSlice),
     });
     if (!judged.ok) return undefined;
     const entries = correctionsFor(judged.value, state);

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/jev/questions/turn.ts

@@ -24,13 +24,31 @@ export const DRIFT_QUESTION: ClassifierBoolQuestion = {
   },
 };
 
+export const DONE_QUESTION: ClassifierBoolQuestion = {
+  type: "bool",
+  instructions:
+    "`activeSlice` names the one slice of work the agent is doing. Does `assistantText` say that the slice's work is finished and ready to commit or hand over, rather than reporting progress, planning more work or asking something?",
+  criteria: {
+    true: "The message presents the slice as complete: implemented, tested and ready to commit, push or review",
+    false:
+      "The message reports partial progress, plans next steps, asks a question or is unrelated to finishing the slice",
+  },
+};
+
 export type ToolEvidence = { tool: string; summary: string; exitCode?: number };
 export type TurnInput = {
   assistantText: string;
   toolEvidence: readonly ToolEvidence[];
   activeSlice?: string;
+  /** Also ask whether the message calls the slice finished (only meaningful with an active slice). */
+  checkDone?: boolean;
+};
+export type TurnJudgement = {
+  unverifiedClaim: number;
+  driftFromSlice: number;
+  /** 0 unless `checkDone` was set and a slice is active. */
+  sliceDone: number;
 };
-export type TurnJudgement = { unverifiedClaim: number; driftFromSlice: number };
 
 const TEXT_MAX = 4000;
 const SUMMARY_MAX = 240;
@@ -54,7 +72,7 @@ const probability = (
     : err({ kind: "provider", message: `malformed ${name} answer` });
 };
 
-/** Two independent narrow questions; drift is only asked when a slice is active. */
+/** Narrow questions asked together; drift and done only when a slice is active (done only on request). */
 export async function judgeTurn(
   jev: Jev,
   input: TurnInput,
@@ -65,17 +83,23 @@ export async function judgeTurn(
     toolEvidence: input.toolEvidence.slice(-EVIDENCE_MAX).map(evidenceLine),
     ...(slice === undefined ? {} : { activeSlice: slice }),
   };
-  const asked = await jev.ask(
-    state,
-    slice === undefined
-      ? { claim: CLAIM_QUESTION }
-      : { claim: CLAIM_QUESTION, drift: DRIFT_QUESTION },
-  );
+  const wantDone = slice !== undefined && input.checkDone === true;
+  const asked = await jev.ask(state, {
+    claim: CLAIM_QUESTION,
+    ...(slice === undefined ? {} : { drift: DRIFT_QUESTION }),
+    ...(wantDone ? { done: DONE_QUESTION } : {}),
+  });
   if (!asked.ok) return asked;
   const claim = probability(asked.value.claim, "claim");
   if (!claim.ok) return claim;
-  if (slice === undefined) return ok({ unverifiedClaim: claim.value, driftFromSlice: 0 });
+  if (slice === undefined)
+    return ok({ unverifiedClaim: claim.value, driftFromSlice: 0, sliceDone: 0 });
   const drift = probability(asked.value.drift, "drift");
   if (!drift.ok) return drift;
-  return ok({ unverifiedClaim: claim.value, driftFromSlice: drift.value });
+  if (!wantDone) {
+    return ok({ unverifiedClaim: claim.value, driftFromSlice: drift.value, sliceDone: 0 });
+  }
+  const done = probability(asked.value.done, "done");
+  if (!done.ok) return done;
+  return ok({ unverifiedClaim: claim.value, driftFromSlice: drift.value, sliceDone: done.value });
 }