@jwilger/pi-development-system 0.35.0 → 0.36.0

package/extensions/development-system.ts

@@ -1,10 +1,14 @@
 import { readFileSync } from "node:fs";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { cadenceLine, DEFAULT_PUSH_MINUTES } from "../src/context/cadence.ts";
+import { registerCompactionResync } from "../src/context/compaction.ts";
 import { appendContextTail, renderContextTail } from "../src/context/context-tail.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";
 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";
 import { detectProfiles } from "../src/core/profile.ts";
 import { createApprovalStore } from "../src/gates/approvals.ts";
 import { registerCommitGuard } from "../src/gates/commit-guard.ts";
@@ -38,6 +42,7 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   const jevHolder = createJevHolder();
   let jevModel: string | undefined;
   let lastCtx: ExtensionContext | undefined;
+  let pushMinutes = DEFAULT_PUSH_MINUTES;
 
   const refreshStatus = () => {
     lastCtx?.ui.setStatus(STATUS_KEY, renderStatusLine(state.get(), jevModel));
@@ -45,6 +50,7 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
 
   const refreshProfiles = async (ctx: ExtensionContext) => {
     const config = await loadConfig(ctx.cwd);
+    pushMinutes = config.ok ? config.value.cadence.pushMinutes : DEFAULT_PUSH_MINUTES;
     const override = config.ok ? config.value.profiles.override : [];
     const profiles = await detectProfiles(ctx.cwd, override);
     const current = state.get().profiles ?? [];
@@ -75,7 +81,13 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   });
 
   pi.on("context", (event) => {
-    const messages = appendContextTail(event.messages, renderContextTail(state.get()), Date.now());
+    const now = Date.now();
+    const cadence = cadenceLine(state.get(), now, pushMinutes);
+    const messages = appendContextTail(
+      event.messages,
+      renderContextTail(state.get(), cadence),
+      now,
+    );
     return messages === undefined ? undefined : { messages };
   });
 
@@ -102,6 +114,15 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   });
   registerTestGuard({ pi, state, approvals, jev: (ctx) => jevHolder.forContext(ctx) });
   registerTestEvidence({ pi, state });
+  registerCompactionResync({ pi, state });
+  registerModelAdvice({
+    pi,
+    state,
+    matrix: async (ctx) => {
+      const config = await loadConfig(ctx.cwd);
+      return config.ok ? config.value.models : defaultMatrix();
+    },
+  });
   registerTurnVerifier({
     pi,
     state,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.35.0",
+  "version": "0.36.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

@@ -0,0 +1,18 @@
+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. */
+export function cadenceLine(
+  state: DevsysState,
+  now: number,
+  pushMinutes: number,
+): string | undefined {
+  if (state.phase !== "implementing" || state.lastPushAt === undefined) return undefined;
+  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;
+}

package/src/context/compaction.ts

@@ -0,0 +1,24 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { SessionState } from "../state/session-state.ts";
+import { renderStateBlock } from "./state-block.ts";
+
+export const RESYNC_ENTRY_TYPE = "devsys-resync";
+
+/**
+ * pi lets `session_before_compact` only REPLACE the whole summary (summary, firstKeptEntryId,
+ * tokensBefore), which would mean writing our own summariser and paying another model call. So the
+ * summary is left to pi, and once it lands we re-state the working state as one message the next
+ * request sees. State itself lives in session entries and the per-turn context tail, so nothing is
+ * lost; this just makes it visible to the model again.
+ */
+export function registerCompactionResync(deps: { pi: ExtensionAPI; state: SessionState }): void {
+  deps.pi.on("session_compact", () => {
+    const state = deps.state.get();
+    if (state.phase === "idle" && state.openDepartures.length === 0) return;
+    deps.pi.sendMessage({
+      customType: RESYNC_ENTRY_TYPE,
+      content: `[devsys resync] Context was compacted. Current working state:\n\n${renderStateBlock(state)}`,
+      display: true,
+    });
+  });
+}

package/src/context/context-tail.ts

@@ -9,7 +9,7 @@ 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): string | undefined {
+export function renderContextTail(state: DevsysState, cadence?: string): string | undefined {
   if (state.phase === "idle" && state.openDepartures.length === 0) return undefined;
   const head = [
     "[development-system]",
@@ -17,7 +17,7 @@ export function renderContextTail(state: DevsysState): string | undefined {
     `Jev: ${state.jev}`,
     ...((state.profiles?.length ?? 0) > 0 ? [`profiles: ${state.profiles?.join(", ")}`] : []),
   ];
-  const tailLines = [REMINDER];
+  const tailLines = [...(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)})`,

package/src/context/model-advice.ts

@@ -0,0 +1,58 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { adviseModel } from "../core/model-advice.ts";
+import type { ModelMatrix } from "../core/models.ts";
+import type { Phase } from "../core/types.ts";
+import { availableModels } from "../state/models-command.ts";
+import type { SessionState } from "../state/session-state.ts";
+
+const ADVICE_ENTRY_TYPE = "devsys-model-advice";
+
+export type ModelAdviceDeps = {
+  pi: ExtensionAPI;
+  state: SessionState;
+  matrix(ctx: ExtensionContext): Promise<ModelMatrix>;
+};
+
+type Seen = { ctx: ExtensionContext; model: { provider: string; id: string } | undefined };
+
+/**
+ * Recommends — never switches — when the coordinator's model tier is below what the phase's slot
+ * resolves to. Runs on model_select and on phase change, at most once per (phase, model).
+ */
+export function registerModelAdvice(deps: ModelAdviceDeps): void {
+  const told = new Set<string>();
+  let last: Seen | undefined;
+  let phase: Phase = deps.state.get().phase;
+
+  const check = async (seen: Seen): Promise<void> => {
+    const { model } = seen;
+    const current = deps.state.get().phase;
+    if (model === undefined) return;
+    const ref = `${model.provider}/${model.id}`;
+    const key = `${current}|${ref}`;
+    if (told.has(key)) return;
+    const advice = adviseModel({
+      matrix: await deps.matrix(seen.ctx),
+      available: availableModels(seen.ctx.modelRegistry),
+      phase: current,
+      model: ref,
+    });
+    if (advice === undefined) return;
+    told.add(key);
+    deps.pi.sendMessage({ customType: ADVICE_ENTRY_TYPE, content: advice, display: true });
+  };
+
+  deps.pi.on("session_start", (_event, ctx) => {
+    last = { ctx, model: ctx.model };
+    phase = deps.state.get().phase;
+  });
+  deps.pi.on("model_select", async (event, ctx) => {
+    last = { ctx, model: event.model };
+    await check(last);
+  });
+  deps.state.onChange((state) => {
+    if (state.phase === phase) return;
+    phase = state.phase;
+    if (last !== undefined) void check(last).catch(() => undefined);
+  });
+}

package/src/context/state-block.ts

@@ -0,0 +1,30 @@
+import type { DevsysState } from "../core/types.ts";
+import { activeReview } from "./status.ts";
+
+const MAX_DEPARTURES = 8;
+
+/** The durable working state as a short markdown block, for compaction resync and the like. */
+export function renderStateBlock(state: DevsysState): string {
+  const departures = state.openDepartures.map(
+    (d) => `  - ${d.gate} — ${d.chosen.replace(/\s+/g, " ")}`,
+  );
+  const shown =
+    departures.length <= MAX_DEPARTURES
+      ? departures
+      : [
+          ...departures.slice(0, MAX_DEPARTURES - 1),
+          `  - …and ${departures.length - MAX_DEPARTURES + 1} more`,
+        ];
+  const run = state.lastTestRun;
+  return [
+    "## Development System State",
+    `- phase: ${state.phase}`,
+    `- sizing: ${state.sizing ?? "unset"}`,
+    `- slice: ${state.activeSlice ?? "none"}`,
+    `- open departures: ${state.openDepartures.length === 0 ? "none" : state.openDepartures.length}`,
+    ...shown,
+    `- ${activeReview(state) ?? "review: none"}`,
+    `- last test run: ${run === undefined ? "none" : `exit ${run.exitCode} — ${run.summary}`}`,
+    `- last push: ${state.lastPushAt ?? "none"}`,
+  ].join("\n");
+}

package/src/context/status.ts

@@ -13,7 +13,7 @@ const ciLabel = (state: DevsysState): string | undefined => {
   return `ci ${ci.status}${sha}`;
 };
 
-const activeReview = (state: DevsysState): string | undefined => {
+export const activeReview = (state: DevsysState): string | undefined => {
   // Without an active slice (before /devsys-start exists) show the most recent review instead of nothing.
   const review =
     state.activeSlice === undefined ? state.reviews?.at(-1) : reviewOf(state, state.activeSlice);

package/src/core/model-advice.ts

@@ -0,0 +1,81 @@
+import {
+  type Available,
+  flattenSlot,
+  type ModelMatrix,
+  matchesPattern,
+  resolveSlot,
+  type Slot,
+} from "./models.ts";
+import type { Phase } from "./types.ts";
+
+/** Highest first. */
+export const TIERS = ["frontier", "strong", "fast"] as const;
+export type Tier = (typeof TIERS)[number];
+
+const PHASE_SLOT: Partial<Record<Phase, Slot>> = {
+  planning: "planning",
+  implementing: "implementer",
+  reviewing: "reviewer",
+};
+
+export const requiredSlot = (phase: Phase): Slot | undefined => PHASE_SLOT[phase];
+
+const split = (ref: string): { provider: string; id: string } | undefined => {
+  const slash = ref.indexOf("/");
+  return slash <= 0 || slash === ref.length - 1
+    ? undefined
+    : { provider: ref.slice(0, slash), id: ref.slice(slash + 1) };
+};
+
+const matches = (candidates: readonly string[], model: string): boolean => {
+  const ref = split(model);
+  return (
+    ref !== undefined &&
+    candidates.some((candidate) => {
+      const c = split(candidate);
+      return c !== undefined && c.provider === ref.provider && matchesPattern(c.id, ref.id);
+    })
+  );
+};
+
+/**
+ * The lowest tier whose candidates include `provider/id`: a model that appears as a fallback in a
+ * higher tier (sol in frontier) still belongs to the tier it is natively listed in. Undefined when
+ * the model is in none of them.
+ */
+export function tierOf(matrix: ModelMatrix, model: string): Tier | undefined {
+  // Direct candidates only: `fast` falls back to `@strong`, which must not make strong models fast.
+  return [...TIERS].reverse().find((tier) =>
+    matches(
+      matrix[tier].filter((c) => !c.startsWith("@")),
+      model,
+    ),
+  );
+}
+
+export type AdviceInput = {
+  matrix: ModelMatrix;
+  available: readonly Available[];
+  phase: Phase;
+  /** The coordinator's current model as `provider/id`. */
+  model: string;
+};
+
+/**
+ * One recommendation when the coordinator's tier is below what the phase's slot resolves to; never
+ * a model switch. Silent when the phase has no slot, the slot cannot be resolved here, or either
+ * model is outside the three tiers (nothing to compare).
+ */
+export function adviseModel(input: AdviceInput): string | undefined {
+  const slot = requiredSlot(input.phase);
+  if (slot === undefined) return undefined;
+  const wanted = resolveSlot(input.matrix, slot, input.available);
+  if (!wanted.ok) return undefined;
+  // Anything the slot itself lists is acceptable for the phase, whatever tier it natively sits in.
+  if (matches(flattenSlot(input.matrix, slot), input.model)) return undefined;
+  const have = tierOf(input.matrix, input.model);
+  const need = tierOf(input.matrix, wanted.value.model);
+  if (have === undefined || need === undefined) return undefined;
+  if (TIERS.indexOf(have) <= TIERS.indexOf(need)) return undefined;
+  return `${input.phase} on ${input.model} (${have} tier) — the matrix prefers ${wanted.value.model} (${need} tier) for the ${slot} slot. Consider asking an advisor subagent for the hard decisions, or continue and record a departure (gate models.phase-mismatch). The system never switches your model for you.`;
+}

package/src/core/models.ts

@@ -80,7 +80,7 @@ export function compareModelVersions(a: string, b: string): number {
 }
 
 /** `*`-only glob over a model id (no regular expressions built from configuration). */
-function matchesPattern(pattern: string, id: string): boolean {
+export function matchesPattern(pattern: string, id: string): boolean {
   const parts = pattern.split("*");
   if (parts.length === 1) return pattern === id;
   const first = parts[0] ?? "";