@jwilger/pi-development-system 0.79.0 → 0.81.0

package/extensions/development-system.ts

@@ -5,13 +5,13 @@ import type {
   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 { DEFAULT_PUSH_MINUTES } from "../src/context/cadence.ts";
 import { createPhaseTool } from "../src/context/devsys-tool.ts";
 import { intentLineFor } from "../src/context/intent-trigger.ts";
 import { registerModelAdvice } from "../src/context/model-advice.ts";
+import { NUDGE_ENTRY_TYPE, renderNudge } from "../src/context/nudge.ts";
 import { renderStatus, renderStatusLine, STATUS_KEY } from "../src/context/status.ts";
-import { applyPromptSection } from "../src/context/system-prompt.ts";
+import { applyPromptSections } from "../src/context/system-prompt.ts";
 import { DEFAULT_VERIFIER_MAX, registerTurnVerifier } from "../src/context/turn-verifier.ts";
 import { type Exec, timeoutAsFailure } from "../src/core/exec.ts";
 import { defaultMatrix } from "../src/core/models.ts";
@@ -89,26 +89,30 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   pi.on("session_start", (_event, ctx) => rebuild(ctx));
   pi.on("session_tree", (_event, ctx) => rebuild(ctx));
 
-  // The intent line rides in the context tail for this run only: a change to the system prompt
-  // would invalidate the provider's cache for the whole conversation.
-  let intentLine: string | undefined;
+  // Prompt-cache discipline (ADR-0004): the system prompt carries two sections — static principles
+  // and a small state section pi only resends when it changes — and anything one-shot (intent
+  // nudge, cadence warning) is returned here as a persisted message. No `context` handler: an
+  // unpersisted edit at the end of the request sits on the provider's cache breakpoint.
+  let lastCadence: string | undefined;
+  let cadenceFor: string | undefined;
   pi.on("before_agent_start", async (event, ctx) => {
-    applyPromptSection(event, state.get(), nonNegotiables);
-    intentLine = await intentLineFor(event.prompt, state.get(), jevHolder.forContext(ctx));
-  });
-  pi.on("agent_end", () => {
-    intentLine = undefined;
-  });
-
-  pi.on("context", (event) => {
-    const now = Date.now();
-    const cadence = cadenceLine(state.get(), now, pushMinutes);
-    const messages = appendContextTail(
-      event.messages,
-      renderContextTail(state.get(), cadence, intentLine),
-      now,
-    );
-    return messages === undefined ? undefined : { messages };
+    const current = state.get();
+    applyPromptSections(event, current, nonNegotiables);
+    if (current.lastPushAt !== cadenceFor) {
+      cadenceFor = current.lastPushAt;
+      lastCadence = undefined;
+    }
+    const intentLine = await intentLineFor(event.prompt, current, jevHolder.forContext(ctx));
+    const nudge = renderNudge(current, Date.now(), pushMinutes, intentLine, lastCadence);
+    if (nudge === undefined) return undefined;
+    lastCadence = nudge.cadence;
+    return {
+      message: {
+        customType: NUDGE_ENTRY_TYPE,
+        content: nudge.text,
+        display: false,
+      },
+    };
   });
 
   const exec: Exec = async (command, args, options) =>

package/package.json

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

package/src/context/cadence.ts

@@ -2,7 +2,13 @@ export const DEFAULT_PUSH_MINUTES = 60;
 
 import type { DevsysState } from "../core/types.ts";
 
-/** Advisory only: a long gap since the last push while implementing hints the increment is too big. */
+/** Width of the buckets the elapsed time is reported in, so the line changes rarely. */
+const CADENCE_BUCKET_MINUTES = 30;
+
+/**
+ * Advisory only: a long gap since the last push while implementing hints the increment is too big.
+ * The minutes are rounded down to a bucket so the text stays the same across many turns.
+ */
 export function cadenceLine(
   state: DevsysState,
   now: number,
@@ -12,7 +18,10 @@ export function cadenceLine(
   const pushed = Date.parse(state.lastPushAt);
   if (!Number.isFinite(pushed)) return undefined;
   const minutes = Math.floor((now - pushed) / 60_000);
-  return minutes > pushMinutes
-    ? `⚠ ${minutes} min since last push — is this increment too big?`
-    : undefined;
+  if (minutes <= pushMinutes) return undefined;
+  const bucket = Math.max(
+    pushMinutes,
+    Math.floor(minutes / CADENCE_BUCKET_MINUTES) * CADENCE_BUCKET_MINUTES,
+  );
+  return `⚠ over ${bucket} min since last push — is this increment too big?`;
 }

package/src/context/devsys-tool.ts

@@ -3,23 +3,23 @@ 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.";
+/**
+ * Static on purpose: tool declarations head every request, so a description that changed with the
+ * phase would invalidate the provider's cache for the whole conversation. The phase lives in the
+ * system prompt's state section; calling the tool returns the guidance for it.
+ */
+export const DEVSYS_TOOL_DESCRIPTION =
+  "What the development system expects in the current workflow phase (named in the system prompt's Current state), 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. */
+/** `devsys`: a model-only tool that returns the current phase's guidance. */
 export function createPhaseTool(deps: { state: SessionState }): ToolDefinition {
   return {
     name: "devsys",
     label: "Workflow guide",
-    description: BASE,
+    description: DEVSYS_TOOL_DESCRIPTION,
     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 = [

package/src/context/nudge.ts

@@ -0,0 +1,30 @@
+import type { DevsysState } from "../core/types.ts";
+import { cadenceLine } from "./cadence.ts";
+
+export const NUDGE_ENTRY_TYPE = "devsys-nudge";
+
+/**
+ * Pure: the one-shot message for a run, or undefined when there is nothing to say.
+ *
+ * Why a message and not the system prompt or the context: pi persists the message returned from
+ * `before_agent_start` right after the user prompt, so it becomes part of the stable prefix the
+ * provider caches. A per-call context edit sits on the cache breakpoint and is never persisted,
+ * which made every request a cache miss. A system-prompt edit is resent in full to the model.
+ *
+ * `last` is the previous cadence text already in the conversation; the same text is not repeated.
+ */
+export function renderNudge(
+  state: DevsysState,
+  now: number,
+  pushMinutes: number,
+  intentLine: string | undefined,
+  lastCadence: string | undefined,
+): { text: string; cadence: string | undefined } | undefined {
+  const cadence = cadenceLine(state, now, pushMinutes);
+  const lines = [
+    ...(intentLine === undefined ? [] : [intentLine]),
+    ...(cadence === undefined || cadence === lastCadence ? [] : [cadence]),
+  ];
+  if (lines.length === 0) return undefined;
+  return { text: ["[development-system]", ...lines].join("\n"), cadence: cadence ?? lastCadence };
+}

package/src/context/system-prompt.ts

@@ -1,30 +1,60 @@
 import type { BeforeAgentStartEvent } from "@earendil-works/pi-coding-agent";
-import type { DevsysState } from "../core/types.ts";
+import type { Departure, DevsysState } from "../core/types.ts";
 
-const PROMPT_SECTION_NAME = "development-system";
+/**
+ * Two sections, kept apart on purpose. pi diffs system-prompt sections per run and appends
+ * only the ones whose text changed, so the static section is paid for once per conversation
+ * and only the small state section is resent when the workflow state moves. Nothing in either
+ * may change from call to call within a run (that would break the provider's prefix cache).
+ */
+const PRINCIPLES_SECTION = "development-system";
+const STATE_SECTION = "development-system-state";
 
-/** Pure: renders the system-prompt section from current state. */
-export function buildPromptSection(state: DevsysState, nonNegotiables: string): string {
-  const slice = state.activeSlice ?? "none";
-  return [
-    nonNegotiables.trim(),
-    "",
+const MAX_DEPARTURES = 12;
+const REMINDER =
+  "Call devsys_record_departure before acting against a default; hard stops need the user.";
+
+const scopeLabel = (d: Departure): string =>
+  d.scope.kind === "slice" ? `slice ${d.scope.slice}` : d.scope.kind;
+
+/** Pure: the static principles section — byte-identical whatever the state. */
+export function buildPrinciplesSection(nonNegotiables: string): string {
+  return nonNegotiables.trim();
+}
+
+/**
+ * Pure: the small state section. Jev availability is deliberately absent — it flaps, and the
+ * status line already shows it. Timestamps and counters that tick are absent for the same reason.
+ */
+export function buildStateSection(state: DevsysState): string {
+  const lines = [
     "## Current state",
     `- phase: ${state.phase}`,
-    `- active slice: ${slice}`,
-    `- open departures: ${state.openDepartures.length}`,
-    `- jev: ${state.jev}`,
-  ].join("\n");
+    `- sizing: ${state.sizing ?? "none"}`,
+    `- active slice: ${state.activeSlice ?? "none"}`,
+    `- profiles: ${(state.profiles?.length ?? 0) > 0 ? state.profiles?.join(", ") : "none"}`,
+  ];
+  const open = state.openDepartures;
+  if (open.length === 0) {
+    lines.push("- open departures: none");
+  } else {
+    lines.push("- open departures:");
+    const shown = open.slice(0, MAX_DEPARTURES);
+    for (const d of shown) {
+      lines.push(`  - ${d.gate} — ${d.chosen.replace(/\s+/g, " ")} (${scopeLabel(d)})`);
+    }
+    if (open.length > shown.length) lines.push(`  - …and ${open.length - shown.length} more`);
+  }
+  lines.push("", REMINDER);
+  return lines.join("\n");
 }
 
-/** Adapter: mutates the section on a before_agent_start event (never returns systemPrompt). */
-export function applyPromptSection(
+/** Adapter: sets both sections on a before_agent_start event (never returns systemPrompt). */
+export function applyPromptSections(
   event: BeforeAgentStartEvent,
   state: DevsysState,
   nonNegotiables: string,
 ): void {
-  event.systemPromptOptions.sections[PROMPT_SECTION_NAME] = buildPromptSection(
-    state,
-    nonNegotiables,
-  );
+  event.systemPromptOptions.sections[PRINCIPLES_SECTION] = buildPrinciplesSection(nonNegotiables);
+  event.systemPromptOptions.sections[STATE_SECTION] = buildStateSection(state);
 }

package/src/jev/judge-tools.ts

@@ -15,7 +15,7 @@ const JUDGE_NAMESPACE = {
   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.",
+    'Each tool returns JSON text: the judgement. When Jev is unavailable the call rejects with a message holding {"error": …}, so wrap calls in try/catch or Promise.allSettled. 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 };

package/src/jev/questions/intent.ts

@@ -23,13 +23,29 @@ export const INTENT_QUESTION: ClassifierChoiceQuestion = {
 };
 
 const PROMPT_MAX = 1500;
+const SKILL_END = "</skill>";
+const GAP = "\n…\n";
+
+/**
+ * Pi expands `/skill:name args` into `<skill …>body</skill>\n\nargs`; the body is the skill's own
+ * instructions, not the request. Judge the text after it, and when a prompt is still long keep both
+ * ends so a request that comes last is not clipped away.
+ */
+export function requestText(prompt: string): string {
+  const trimmed = prompt.trimStart();
+  const end = trimmed.startsWith("<skill ") ? trimmed.indexOf(SKILL_END) : -1;
+  const text = (end === -1 ? trimmed : trimmed.slice(end + SKILL_END.length)).trim();
+  if (text.length <= PROMPT_MAX) return text;
+  const half = Math.floor((PROMPT_MAX - GAP.length) / 2);
+  return `${text.slice(0, half)}${GAP}${text.slice(-half)}`;
+}
 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 prompt = requestText(redactSecrets(input.prompt));
   const asked = await jev.ask({ prompt, phase: input.phase }, { intent: INTENT_QUESTION });
   if (!asked.ok) return asked;
   const answer = asked.value.intent;

package/src/context/context-tail.ts

@@ -1,50 +0,0 @@
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import type { Departure, DevsysState } from "../core/types.ts";
-
-const MAX_LINES = 25;
-const REMINDER =
-  "Departures: call devsys_record_departure before acting against a default; hard stops need the user.";
-
-const scopeLabel = (d: Departure): string =>
-  d.scope.kind === "slice" ? `slice ${d.scope.slice}` : d.scope.kind;
-
-/** Small, cache-friendly reminder appended at the end of the context; undefined when nothing to say. */
-export function renderContextTail(
-  state: DevsysState,
-  cadence?: string,
-  note?: string,
-): string | undefined {
-  if (state.phase === "idle" && state.openDepartures.length === 0 && note === undefined) {
-    return undefined;
-  }
-  const head = [
-    "[development-system]",
-    `phase: ${state.phase} · slice: ${state.activeSlice ?? "none"}`,
-    `Jev: ${state.jev}`,
-    ...((state.profiles?.length ?? 0) > 0 ? [`profiles: ${state.profiles?.join(", ")}`] : []),
-  ];
-  const tailLines = [
-    ...(note === undefined ? [] : [note]),
-    ...(cadence === undefined ? [] : [cadence]),
-    REMINDER,
-  ];
-  const room = MAX_LINES - head.length - tailLines.length - 1;
-  const lines = state.openDepartures.map(
-    (d) => `- ${d.gate} — ${d.chosen.replace(/\s+/g, " ")} (${scopeLabel(d)})`,
-  );
-  const shown =
-    lines.length <= room
-      ? lines
-      : [...lines.slice(0, room - 1), `- …and ${lines.length - room + 1} more`];
-  return [...head, "Open departures:", ...shown, ...tailLines].join("\n");
-}
-
-/** Appends the tail as a user-role message at the end of `messages`. */
-export function appendContextTail(
-  messages: ReadonlyArray<AgentMessage>,
-  tail: string | undefined,
-  now: number,
-): AgentMessage[] | undefined {
-  if (tail === undefined) return undefined;
-  return [...messages, { role: "user", content: tail, timestamp: now }];
-}