@jwilger/pi-development-system 0.84.0 → 0.85.0

package/README.md

@@ -27,6 +27,13 @@ terminology, journeys). `devsys_lens_review` plans a review of the brief by five
 writes the packets to `docs/product/reviews/`; `devsys_adr_new` creates the next numbered ADR, and
 a commit that shapes the architecture without one is stopped by the soft gate `adr.missing`.
 
+A slice has a life cycle: `implementing` → `reviewing` (when a review round starts) → `delivering`
+(review satisfied) → `idle`. Editing production source while delivering reopens `implementing`,
+and red-first stays on throughout. A push of a clean tree closes a delivered slice by itself (a commit
+in `local-only` mode; CI is not awaited), and `devsys_finish_slice` closes it explicitly or, with a
+reason, abandons it. A plan's increments each end in a push, so each increment is its own slice: the
+next one starts with `devsys_intake`.
+
 With `codemode` enabled (`"defaultTools": ["+codemode"]` in pi settings), rarely used tools are
 reached through scripts and the `judge_*` Jev wrappers exist for scripts only; without codemode
 the rarely used tools are declared directly and the wrappers are absent.

package/extensions/development-system.ts

@@ -30,6 +30,7 @@ import { createJudgeTools } from "../src/jev/judge-tools.ts";
 import { createAdrNewTool } from "../src/planning/adr-tool.ts";
 import { createBeginWorkTool } from "../src/planning/begin-tool.ts";
 import { createIntakeTool } from "../src/planning/intake-tool.ts";
+import { createFinishSliceTool, registerSliceClose } from "../src/planning/slice-close.ts";
 import { createTaskCheckTool } from "../src/planning/task-check-tool.ts";
 import { createLensReviewTool } from "../src/review/lens-review-tool.ts";
 import { createReviewRecordTool, createReviewStartTool } from "../src/review/review-tools.ts";
@@ -158,6 +159,7 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
     },
   });
   registerRedFirstGuard({ pi, state });
+  registerSliceClose({ pi, state, exec });
   registerLintSuppressionGuard({ pi, state });
   pi.registerTool(createRecordDepartureTool({ pi, state }));
   pi.registerTool(createRequestApprovalTool({ pi, approvals }));
@@ -177,6 +179,7 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   pi.registerTool(createPhaseTool({ state }));
   pi.registerTool(createBeginWorkTool({ state }));
   pi.registerTool(createAdrNewTool({ now: () => new Date() }));
+  pi.registerTool(createFinishSliceTool({ state, exec }));
   pi.registerTool(
     createLensReviewTool({ state, jev: (ctx) => jevHolder.forContext(ctx), now: () => new Date() }),
   );

package/package.json

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

package/prompts/devsys-plan.md

@@ -9,4 +9,4 @@ Write the plan for the current work with the work-intake-and-slicing skill.
 3. Write each task so that someone who sees only that task could finish it. Never write `TBD`.
 4. Run `devsys_task_check` on every task record you wrote and fix each one until it says ready. Split any that come back too-big.
 5. Stop and ask the user to review the plan before any implementation starts. Do not start a goal yet: a goal tool may continue on its own and begin implementing before the review.
-6. Only after the user approves the plan: call `devsys_begin_work` (so the review and red-first gates are on while the plan is built; it does nothing if the work is already implementing). Then, if a `create_goal` tool exists in this session, call it with the objective "complete docs/plan/<slug>.md honouring its Constraints and Progress checklist, one increment at a time, stopping after each increment's Release step". Otherwise tell the user the plan path so they can start a goal on it. Do not depend on any goal tool's file format.
+6. Only after the user approves the plan: call `devsys_begin_work` (so the review and red-first gates are on while the increment is built; it does nothing if the work is already implementing). A push of a clean, reviewed tree closes the slice, so each later increment starts with `devsys_intake`. Then, if a `create_goal` tool exists in this session, call it with the objective "complete docs/plan/<slug>.md honouring its Constraints and Progress checklist, one increment at a time, stopping after each increment's Release step". Otherwise tell the user the plan path so they can start a goal on it. Do not depend on any goal tool's file format.

package/src/context/phase-guide.ts

@@ -10,11 +10,11 @@ export function phaseGuide(phase: Phase): string {
     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.";
+      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 when the slice is complete and reviewed: a push of a clean tree closes it (devsys_finish_slice closes it explicitly).";
     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.";
+      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 (red-first still applies), and repeat until the review is satisfied; then the slice moves to delivering.";
     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.";
+      return "Delivering. The review is satisfied. Commit with a rationale, push, and release; a push of a clean tree closes the slice (devsys_finish_slice closes it explicitly, or abandons it with a reason). Editing source reopens implementing. A red trunk (CI) is repaired first.";
     default:
       return assertNever(phase);
   }

package/src/context/turn-verifier.ts

@@ -149,17 +149,23 @@ export function registerTurnVerifier(deps: TurnVerifierDeps): void {
   let evidence: ToolEvidence[] = [];
   let corrected = 0;
   let justCorrected = false;
+  let inFlightThisRun = false;
 
   deps.pi.on("session_start", () => {
     corrected = 0;
     justCorrected = false;
+    inFlightThisRun = false;
     evidence = [];
   });
   deps.pi.on("agent_start", () => {
+    // A push in this run may close the slice; its delivery report is still the claim to check.
+    inFlightThisRun = VERIFIED_PHASES.has(deps.state.get().phase);
     evidence = [];
     justCorrected = false;
   });
   deps.pi.on("tool_result", (event) => {
+    // The slice can start inside this run (intake, begin) and be closed by its own push; note it was open.
+    if (VERIFIED_PHASES.has(deps.state.get().phase)) inFlightThisRun = true;
     evidence = [...evidence, evidenceOf(event)].slice(-MAX_EVIDENCE);
   });
 
@@ -167,7 +173,7 @@ export function registerTurnVerifier(deps: TurnVerifierDeps): void {
     // An aborted or errored turn is dropped by pi; judging it would delay the abort and spend a correction.
     if (event.outcome !== "completed") return undefined;
     const state = deps.state.get();
-    if (!VERIFIED_PHASES.has(state.phase)) return undefined;
+    if (!(VERIFIED_PHASES.has(state.phase) || inFlightThisRun)) return undefined;
     const parts = assistantParts(event.message);
     if (parts === undefined || parts.callsTools || parts.text.trim() === "") return undefined;
     if (justCorrected) {

package/src/core/lifecycle.ts

@@ -0,0 +1,51 @@
+import type { ReviewAction } from "./review.ts";
+import type { DevsysState, SliceRef } from "./types.ts";
+
+/**
+ * How a slice moves through the phases once it is implementing. Pure: the tools and guards that observe the
+ * events (a review round, an edit, a push) call these and write the result to state.
+ *
+ *   implementing → reviewing   a review round starts or is recorded without being satisfied
+ *   reviewing    → delivering  the review is satisfied on the current diff
+ *   delivering   → reviewing   a later round finds something again
+ *   delivering   → implementing  production source is edited (the review no longer covers it)
+ *   any open     → idle        the slice is delivered or abandoned (`closeSlice`)
+ */
+
+const IN_FLIGHT = new Set<DevsysState["phase"]>(["implementing", "reviewing", "delivering"]);
+
+/** The state after a review round was started or recorded; `action` is `nextAction` for the diff as it is now. */
+export function afterReviewRound(
+  state: DevsysState,
+  action: ReviewAction,
+  slice: SliceRef | undefined = state.activeSlice,
+): DevsysState {
+  if (state.activeSlice === undefined || slice !== state.activeSlice) return state;
+  if (!IN_FLIGHT.has(state.phase)) return state;
+  return { ...state, phase: action === "done" ? "delivering" : "reviewing" };
+}
+
+/** Editing production source after review reopens the slice, so red-first applies to the edit again. */
+export const afterSourceEdit = (state: DevsysState): DevsysState =>
+  state.phase === "delivering" ? { ...state, phase: "implementing" } : state;
+
+/** Back to idle: the slice, its sizing and its slice-scoped departures are done. Review history is kept. */
+export function closeSlice(state: DevsysState): DevsysState {
+  const { activeSlice, sizing: _sizing, ...rest } = state;
+  return {
+    ...rest,
+    phase: "idle",
+    openDepartures: state.openDepartures.filter(
+      (d) => d.scope.kind !== "slice" || d.scope.slice !== activeSlice,
+    ),
+  };
+}
+
+/** A recorded `review.unsatisfied` departure covers this slice, so no review is owed before it ships. */
+export const reviewWaived = (state: DevsysState): boolean =>
+  state.openDepartures.some(
+    (d) =>
+      d.gate === "review.unsatisfied" &&
+      (d.scope.kind === "session" ||
+        (d.scope.kind === "slice" && d.scope.slice === state.activeSlice)),
+  );

package/src/gates/commit-guard.ts

@@ -194,7 +194,8 @@ async function reviewNeeds(
   command: string,
 ): Promise<Need[]> {
   const { phase, activeSlice } = deps.state.get();
-  if ((phase !== "implementing" && phase !== "reviewing") || activeSlice === undefined) return [];
+  const inFlight = phase === "implementing" || phase === "reviewing" || phase === "delivering";
+  if (!inFlight || activeSlice === undefined) return [];
   const snap = await snapshotDiff(deps.exec, ctx.cwd, "HEAD");
   // An unreadable diff cannot be compared; the gate asks for a departure rather than guessing.
   const gap = reviewGap(

package/src/gates/red-first-guard.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { type ExtensionAPI, isToolCallEventType } from "@earendil-works/pi-coding-agent";
+import { afterSourceEdit } from "../core/lifecycle.ts";
 import { classifyPath } from "../core/path-class.ts";
 import { normalizeRepoPath } from "../core/test-paths.ts";
 import type { SessionState } from "../state/session-state.ts";
@@ -57,7 +58,7 @@ const JUDGED_EXEMPTIONS =
   "straightforward CI scripting, a simple dev-environment utility, or a behaviour-preserving refactor with green coverage";
 
 /**
- * Soft gate `tdd.red-first`: while implementing, production source is edited only after a failing
+ * Soft gate `tdd.red-first`: while a slice is in flight (implementing, reviewing, delivering), production source is edited only after a failing
  * test run has been observed. Test, docs, config and generated files are exempt by path; the
  * judged exemptions go through one recorded departure, which covers its whole slice.
  */
@@ -69,11 +70,13 @@ export function registerRedFirstGuard(deps: RedFirstGuardDeps): void {
   deps.pi.on("tool_call", (event, ctx) => {
     if (!(isToolCallEventType("edit", event) || isToolCallEventType("write", event)))
       return undefined;
-    const { phase, lastTestRun, activeSlice } = deps.state.get();
-    if (phase !== "implementing") return undefined;
-    if (lastTestRun !== undefined && lastTestRun.exitCode !== 0) return undefined;
+    const { phase, activeSlice } = deps.state.get();
+    if (phase !== "implementing" && phase !== "reviewing" && phase !== "delivering")
+      return undefined;
     const path = normalizeRepoPath(ctx.cwd, event.input.path, homedir());
     if (classifyPath(path) !== "source") return undefined;
+    const { lastTestRun } = deps.state.get();
+    if (lastTestRun !== undefined && lastTestRun.exitCode !== 0) return undefined;
     if (touchesInlineTest(event.input, () => existing(ctx.cwd, path))) return undefined;
     if (departure.covers()) return undefined;
     const seen =
@@ -90,4 +93,17 @@ export function registerRedFirstGuard(deps: RedFirstGuardDeps): void {
         `departure covers the rest of the ${scope}.`,
     };
   });
+
+  // The review covered the code as it was: source that was really written puts the slice back to implementing.
+  deps.pi.on("tool_result", (event, ctx) => {
+    if (event.isError || (event.toolName !== "edit" && event.toolName !== "write"))
+      return undefined;
+    if (deps.state.get().phase !== "delivering") return undefined;
+    const given = (event.input as { path?: unknown }).path;
+    if (typeof given !== "string") return undefined;
+    if (classifyPath(normalizeRepoPath(ctx.cwd, given, homedir())) === "source") {
+      deps.state.update(afterSourceEdit);
+    }
+    return undefined;
+  });
 }

package/src/planning/intake-tool.ts

@@ -60,12 +60,11 @@ async function declinedToReplace(
   before: DevsysState,
 ): Promise<string | undefined> {
   const { activeSlice, phase } = before;
-  if (activeSlice === undefined || (phase !== "implementing" && phase !== "reviewing")) {
-    return undefined;
-  }
+  const inFlight = phase === "implementing" || phase === "reviewing" || phase === "delivering";
+  if (activeSlice === undefined || !inFlight) return undefined;
   const go = await ctx.ui.confirm(
     "Slice already in flight",
-    `Slice "${activeSlice}" is still ${phase}. Its uncommitted changes would be committed under the new slice's rules. Start new work anyway?`,
+    `Slice "${activeSlice}" is still ${phase}. Its uncommitted or unpushed changes would ship under the new slice's rules. Start new work anyway?`,
   );
   return go ? undefined : `Intake cancelled; slice "${activeSlice}" is unchanged.`;
 }

package/src/planning/slice-close.ts

@@ -0,0 +1,195 @@
+import {
+  type ExtensionAPI,
+  type ExtensionContext,
+  isBashToolResult,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { extractCommits } from "../core/commit-command.ts";
+import type { Exec } from "../core/exec.ts";
+import { closeSlice, reviewWaived } from "../core/lifecycle.ts";
+import { pushTargets } from "../core/push-command.ts";
+import { isSatisfied } from "../core/review.ts";
+import { reviewOf } from "../core/review-flow.ts";
+import type { DevsysState } from "../core/types.ts";
+import { loadConfig } from "../state/config.ts";
+import type { SessionState } from "../state/session-state.ts";
+
+const SLICE_ENTRY_TYPE = "devsys-slice";
+
+export type SliceCloseDeps = { pi: ExtensionAPI; state: SessionState; exec: Exec };
+
+const IN_FLIGHT = new Set<DevsysState["phase"]>(["implementing", "reviewing", "delivering"]);
+
+/** True when `git status` shows nothing to commit; `undefined` when git could not say. */
+async function treeIsClean(exec: Exec, cwd: string): Promise<boolean | undefined> {
+  const r = await exec("git", ["status", "--porcelain"], { cwd, timeout: 15_000 });
+  return r.code === 0 ? r.stdout.trim() === "" : undefined;
+}
+
+/** Commits on HEAD that no branch of `remote` has; works without an upstream, `undefined` when git could not say. */
+async function unpushedCommits(
+  exec: Exec,
+  cwd: string,
+  remote: string,
+): Promise<number | undefined> {
+  const r = await exec("git", ["rev-list", "--count", "HEAD", "--not", `--remotes=${remote}`], {
+    cwd,
+    timeout: 15_000,
+  });
+  const n = Number(r.stdout.trim());
+  return r.code === 0 && Number.isInteger(n) ? n : undefined;
+}
+
+/** No review is owed before this slice ships: its review is satisfied, or a departure waives it. */
+function reviewCleared(state: DevsysState): boolean {
+  if (state.activeSlice === undefined) return false;
+  const review = reviewOf(state, state.activeSlice);
+  return reviewWaived(state) || (review !== undefined && isSatisfied(review));
+}
+
+/** What delivered the slice: a commit when nothing leaves the machine, otherwise a push. */
+const shipped = (mode: string, command: string): boolean =>
+  mode === "local-only" ? extractCommits(command).length > 0 : pushTargets(command).length > 0;
+
+const closedMessage = (slice: string, how: string): string =>
+  `Slice ${slice} ${how}. Phase: idle; the next request starts new work with devsys_intake.`;
+
+/**
+ * Closes the slice when it ships: in any in-flight phase whose review is satisfied (`delivering`, or a session
+ * saved before the life cycle existed) or waived by a recorded departure, a successful push (trunk, pull-request) or commit (local-only) that
+ * leaves a clean working tree. CI is not awaited; the push guard already refuses to build on a red trunk.
+ */
+export function registerSliceClose(deps: SliceCloseDeps): void {
+  deps.pi.on("tool_result", async (event, ctx) => {
+    if (!isBashToolResult(event) || event.isError) return undefined;
+    const state = deps.state.get();
+    const { activeSlice, phase } = state;
+    if (activeSlice === undefined || !IN_FLIGHT.has(phase)) return undefined;
+    if (!reviewCleared(state)) return undefined;
+    const config = await loadConfig(ctx.cwd);
+    if (!(config.ok && shipped(config.value.delivery.mode, String(event.input.command)))) {
+      return undefined;
+    }
+    if ((await treeIsClean(deps.exec, ctx.cwd)) !== true) return undefined;
+    // A tags-only push, or a push of another branch, leaves this slice's commits where they were.
+    if (config.value.delivery.mode !== "local-only") {
+      if ((await unpushedCommits(deps.exec, ctx.cwd, config.value.delivery.remote)) !== 0)
+        return undefined;
+    }
+    // The checks above awaited git; close only the slice they were about.
+    if (deps.state.get().activeSlice !== activeSlice) return undefined;
+    deps.state.update(closeSlice);
+    deps.pi.sendMessage(
+      {
+        customType: SLICE_ENTRY_TYPE,
+        content: closedMessage(activeSlice, "was delivered"),
+        display: true,
+      },
+      { triggerTurn: false },
+    );
+    return undefined;
+  });
+}
+
+const Parameters = Type.Object({
+  abandon: Type.Optional(
+    Type.Boolean({
+      description:
+        "Close the slice without delivering it. Needs a reason; the working tree is left as it is.",
+    }),
+  ),
+  reason: Type.Optional(Type.String({ description: "Why the slice is abandoned (with abandon)." })),
+});
+
+const reply = (text: string, isError = false) => ({
+  content: [{ type: "text" as const, text }],
+  details: undefined,
+  isError,
+});
+
+/** Another slice became active while this one waited on the user or on git: leave it alone. */
+const changedMeanwhile = (slice: string) =>
+  reply(`Slice ${slice} is no longer the active slice; nothing was closed.`, true);
+
+/** Why a slice cannot be finished yet, or `undefined` when it is reviewed, clean and pushed. */
+async function finishBlocker(deps: Pick<SliceCloseDeps, "state" | "exec">, cwd: string) {
+  const state = deps.state.get();
+  const { activeSlice } = state;
+  if (activeSlice === undefined) return undefined;
+  if (!reviewCleared(state)) {
+    return `slice ${activeSlice} has no satisfied review: finish the review rounds (devsys_review_start), or record a review.unsatisfied departure`;
+  }
+  const clean = await treeIsClean(deps.exec, cwd);
+  if (clean !== true) {
+    return clean === false
+      ? "there are uncommitted changes: commit them first"
+      : "git could not report the working tree status";
+  }
+  const config = await loadConfig(cwd);
+  if (!config.ok) return `cannot read the delivery mode: ${config.error.message}`;
+  if (config.value.delivery.mode === "local-only") return undefined;
+  const ahead = await unpushedCommits(deps.exec, cwd, config.value.delivery.remote);
+  if (ahead === undefined) {
+    return "git could not say whether the commits are pushed";
+  }
+  return ahead > 0 ? `${ahead} commit(s) are not pushed yet: push first` : undefined;
+}
+
+/**
+ * `devsys_finish_slice`: the explicit way to close a slice. The push guard closes a delivered slice by itself;
+ * this covers what it cannot see (a push made outside pi, a slice that is dropped) and checks the same facts.
+ */
+export function createFinishSliceTool(
+  deps: Pick<SliceCloseDeps, "state" | "exec">,
+): ToolDefinition<typeof Parameters> {
+  return {
+    name: "devsys_finish_slice",
+    label: "Finish slice",
+    description:
+      "Close the active slice and return to idle. Checks that its review is satisfied (or waived by a recorded departure), the tree is clean and the commits are pushed. With abandon and a reason it drops the slice without delivering it, after the user confirms.",
+    promptSnippet: "Close the active slice once it is delivered, or abandon it",
+    parameters: Parameters,
+    exposure: "model-only",
+    async execute(
+      _id,
+      params: Static<typeof Parameters>,
+      _signal,
+      _onUpdate,
+      ctx: ExtensionContext,
+    ) {
+      const { activeSlice } = deps.state.get();
+      if (activeSlice === undefined) {
+        return reply("There is no active slice to finish. Start work with devsys_intake.", true);
+      }
+      if (params.abandon === true) {
+        const reason = params.reason?.trim() ?? "";
+        if (reason === "") return reply("abandoning a slice needs a reason: pass `reason`.", true);
+        // Idle switches the review and red-first gates off, so only the user may drop an unfinished slice.
+        if (!ctx.hasUI) {
+          return reply(
+            `Abandoning slice ${activeSlice} needs the user's confirmation and there is no interactive session; ask the user to run it.`,
+            true,
+          );
+        }
+        const go = await ctx.ui.confirm(
+          "Abandon slice?",
+          `Slice "${activeSlice}" would be closed without being delivered (${reason}). Its review and red-first gates stop applying; the working tree is left as it is.`,
+        );
+        if (!go) return reply(`Abandon declined; slice ${activeSlice} is unchanged.`, true);
+        if (deps.state.get().activeSlice !== activeSlice) return changedMeanwhile(activeSlice);
+        deps.state.update(closeSlice);
+        return reply(
+          `${closedMessage(activeSlice, `was abandoned (${reason})`)} The working tree was not touched.`,
+        );
+      }
+      const blocker = await finishBlocker(deps, ctx.cwd);
+      if (blocker !== undefined) {
+        return reply(`Slice ${activeSlice} is not finished: ${blocker}.`, true);
+      }
+      if (deps.state.get().activeSlice !== activeSlice) return changedMeanwhile(activeSlice);
+      deps.state.update(closeSlice);
+      return reply(closedMessage(activeSlice, "is finished"));
+    },
+  };
+}

package/src/review/review-tools.ts

@@ -1,6 +1,7 @@
 import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import type { Exec } from "../core/exec.ts";
+import { afterReviewRound } from "../core/lifecycle.ts";
 import { resolveSlot } from "../core/models.ts";
 import type { Lens } from "../core/review.ts";
 import {
@@ -181,6 +182,7 @@ async function startRound(
   const existing = reviewOf(deps.state.get(), p.slice) ?? startReview(p.slice, required);
   const review: ReviewState = { ...existing, required };
   deps.state.update((s) => upsertReview(s, review));
+  deps.state.update((s) => afterReviewRound(s, nextAction(review, p.snap.digest), p.slice));
   const refusal = startRefusal(review, p);
   if (refusal !== undefined) return refusal;
 
@@ -345,6 +347,7 @@ async function recordRound(
     },
   );
   deps.state.update((s) => upsertReview(s, review));
+  deps.state.update((s) => afterReviewRound(s, nextAction(review, p.snap.digest), p.slice));
   return reply(recordSummary(review, findings, notes, p));
 }