@jwilger/pi-development-system 0.7.0 → 0.8.0

package/extensions/development-system.ts

@@ -11,6 +11,7 @@ import { createRecordDepartureTool } from "../src/gates/record-departure-tool.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 { registerCiCommand } from "../src/state/ci-command.ts";
 import { createModelsTool, registerModelsCommand } from "../src/state/models-command.ts";
 import { createSessionState } from "../src/state/session-state.ts";
 
@@ -66,6 +67,11 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
     jev: (ctx) => jevHolder.forContext(ctx),
     exec: (command, args, options) => pi.exec(command, args, options),
   });
+  registerCiCommand({
+    pi,
+    state,
+    exec: (command, args, options) => pi.exec(command, args, options),
+  });
   registerPushGuard({
     pi,
     state,

package/package.json

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

package/skills/delivery-discipline/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: delivery-discipline
+description: How to commit, push and release in this development system - trunk-based delivery, Conventional Commit messages that carry their rationale, handling a red build, and when worktrees are warranted. Use before committing, pushing, opening a pull request, or when CI is red.
+---
+
+# Delivery discipline
+
+Delivery mode comes from `.development-system.toml` (`[delivery] mode`):
+`trunk` (default), `pull-request`, or `local-only`. The repository's own policy
+wins over any habit. The extension enforces the hard parts; this skill is how
+to work with them.
+
+## Commit messages
+
+Shape: `type(scope): subject` then a body that says **why**.
+
+```text
+fix(auth): reject expired refresh tokens
+
+Expired tokens were accepted for up to a minute because the clock check used
+the issue time. Sessions outliving their grant is a security defect, so the
+check now uses expiry; clock-skew tolerance is deliberately not added.
+```
+
+- Do not write a body that only restates the diff. The diff already says what;
+  the body is the only place the reason survives.
+- Do not add `Co-Authored-By`, "Generated with" or any AI trailer. This is
+  never a departure; the guard blocks it outright.
+- Do not mix structural changes (rename, move, reformat) with behavioural ones
+  in one commit. Reviewers cannot see the behaviour change inside the noise.
+  Tidy first, commit, then change behaviour.
+- A body-less commit is allowed only through a recorded departure
+  (`devsys_record_departure`, gate `commit.rationale`); say why in it.
+
+## Trunk flow
+
+1. Small increment, tests green locally, commit with rationale.
+2. Push to trunk, then watch CI (`/devsys-ci`). A push is not done until CI is green.
+3. If an hour passes without a pushed commit, stop and ask whether the
+   increment is too big; split it.
+
+Do not start unrelated work while trunk CI is red. Fix it first; a red build
+hides every later failure. A push to a red trunk is a hard stop unless the
+commit is `fix(ci): ...` and its diff only repairs the failing build.
+
+## Pull-request mode
+
+Never push to the trunk directly (hard stop, gate `push.delivery-mode`). Push a
+branch, open the PR, and wait for its checks.
+
+## Local-only
+
+Pushes are blocked. Commit locally, tell the user what is unpublished.
+
+## Worktrees
+
+Use `.worktrees/<name>` only when two pieces of work genuinely run in
+parallel. One increment at a time needs none; they add cleanup and confusion.
+
+## Never
+
+- `--no-verify`, `git push --force`, rewriting published history, deleting
+  remote branches: hard stops needing the user's explicit approval each time.
+- Weakening or deleting tests to get green (gate `tests.weaken`).
+- Claiming CI passed without having looked at it.
+
+## Checklist
+
+Copy and tick:
+
+```text
+- [ ] Commit is one kind of change (structural or behavioural)
+- [ ] Subject is Conventional; body explains why
+- [ ] No AI trailer
+- [ ] Local gates green (see references/lefthook.yml for the template)
+- [ ] Pushed per delivery mode; CI watched to green
+```

package/skills/delivery-discipline/references/lefthook.yml

@@ -0,0 +1,18 @@
+---
+# Template: local gates that mirror CI so a red build is found before the push.
+# Adapt the commands to the repository's toolchain.
+# Keep CI re-running every gate.
+commit-msg:
+  commands:
+    conventional:
+      run: your-commit-message-check {1}
+
+pre-commit:
+  parallel: true
+  commands:
+    typecheck:
+      run: npx tsc --noEmit
+    lint:
+      run: biome check .
+    test:
+      run: npm test

package/src/context/status.ts

@@ -5,8 +5,17 @@ export const STATUS_KEY = "devsys";
 const jevLabel = (state: DevsysState, model: string | undefined): string =>
   state.jev === "online" && model !== undefined ? `online (${model})` : state.jev;
 
+const ciLabel = (state: DevsysState): string | undefined => {
+  const { ci } = state;
+  if (ci === undefined || ci.status === "unknown") return undefined;
+  const sha = ci.sha === undefined ? "" : ` (${ci.sha.slice(0, 7)})`;
+  return `ci ${ci.status}${sha}`;
+};
+
 export const renderStatusLine = (state: DevsysState, jevModel?: string): string =>
-  `devsys: ${state.phase} · jev ${jevLabel(state, jevModel)}`;
+  [`devsys: ${state.phase}`, `jev ${jevLabel(state, jevModel)}`, ciLabel(state)]
+    .filter((part) => part !== undefined)
+    .join(" · ");
 
 export const renderStatus = (state: DevsysState, jevModel?: string): string =>
   [
@@ -16,4 +25,5 @@ export const renderStatus = (state: DevsysState, jevModel?: string): string =>
     `- active slice: ${state.activeSlice ?? "none"}`,
     `- open departures: ${state.openDepartures.length}`,
     `- jev: ${jevLabel(state, jevModel)}`,
+    `- ci: ${ciLabel(state)?.slice(3) ?? "unknown"}`,
   ].join("\n");

package/src/core/types.ts

@@ -56,6 +56,12 @@ export type Departure = {
 
 export type JevStatus = "online" | "offline" | "unknown";
 
+export type CiStatusName = "green" | "red" | "pending" | "unknown";
+export const CI_STATUSES: readonly CiStatusName[] = ["green", "red", "pending", "unknown"];
+
+/** Last observed CI state of the trunk (see `/devsys-ci`). */
+export type CiState = { readonly status: CiStatusName; readonly sha?: string };
+
 export type DevsysState = {
   readonly phase: Phase;
   readonly sizing?: Sizing;
@@ -63,6 +69,7 @@ export type DevsysState = {
   readonly openDepartures: ReadonlyArray<Departure>;
   readonly jev: JevStatus;
   readonly lastPushAt?: string;
+  readonly ci?: CiState;
 };
 
 export const initialState = (): DevsysState => ({

package/src/state/ci-command.ts

@@ -0,0 +1,66 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { Exec } from "../core/exec.ts";
+import type { CiState } from "../core/types.ts";
+import { watchCi } from "./ci-watch.ts";
+import { loadConfig } from "./config.ts";
+import type { SessionState } from "./session-state.ts";
+
+export const CI_ENTRY_TYPE = "devsys-ci";
+
+export type CiCommandDeps = {
+  pi: ExtensionAPI;
+  state: SessionState;
+  exec: Exec;
+  sleep?: (ms: number) => Promise<void>;
+  intervalMs?: number;
+  maxPolls?: number;
+};
+
+const sameCi = (a: CiState | undefined, b: CiState): boolean =>
+  a?.status === b.status && a?.sha === b.sha;
+
+/** Observes trunk CI until it settles, mirroring each change into state (status line) and a `devsys-ci` entry. */
+export async function runCiWatch(
+  deps: CiCommandDeps,
+  ctx: Pick<ExtensionCommandContext, "cwd" | "ui">,
+): Promise<CiState | undefined> {
+  const config = await loadConfig(ctx.cwd);
+  if (!config.ok) {
+    ctx.ui.notify(`cannot read the delivery policy: ${config.error.message}`, "error");
+    return undefined;
+  }
+  const final = await watchCi({
+    exec: deps.exec,
+    branch: config.value.delivery.trunk,
+    cwd: ctx.cwd,
+    sleep: deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+    intervalMs: deps.intervalMs ?? 15_000,
+    maxPolls: deps.maxPolls ?? 120,
+    onObserved: (observed) => {
+      if (sameCi(deps.state.get().ci, observed)) return;
+      deps.state.update((s) => ({ ...s, ci: observed }));
+      deps.pi.appendEntry(CI_ENTRY_TYPE, observed);
+    },
+  });
+  ctx.ui.notify(
+    `CI on ${config.value.delivery.trunk}: ${final.status}${final.sha === undefined ? "" : ` (${final.sha.slice(0, 7)})`}`,
+    final.status === "red" ? "error" : "info",
+  );
+  return final;
+}
+
+/** `/devsys-ci`: watch the trunk's CI without blocking the session. */
+export function registerCiCommand(deps: CiCommandDeps): void {
+  deps.pi.registerCommand("devsys-ci", {
+    description: "Watch CI on the trunk and show its state in the status line",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify("watching CI on the trunk…", "info");
+      runCiWatch(deps, ctx).catch((cause: unknown) => {
+        ctx.ui.notify(
+          `CI watch failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+          "error",
+        );
+      });
+    },
+  });
+}

package/src/state/ci-watch.ts

@@ -0,0 +1,33 @@
+import type { Exec } from "../core/exec.ts";
+import type { CiState } from "../core/types.ts";
+import { getTrunkStatus } from "./ci.ts";
+
+export type WatchOptions = {
+  exec: Exec;
+  branch: string;
+  cwd: string;
+  /** Called with every observation, including the first. */
+  onObserved: (observed: CiState) => void;
+  sleep: (ms: number) => Promise<void>;
+  intervalMs: number;
+  maxPolls: number;
+};
+
+/** Observes the trunk's newest run until it settles (not pending) or the poll budget is spent. */
+export async function watchCi(options: WatchOptions): Promise<CiState> {
+  let last: CiState = { status: "unknown" };
+  for (let poll = 0; poll < options.maxPolls; poll++) {
+    const trunk = await getTrunkStatus(options.exec, {
+      branch: options.branch,
+      cwd: options.cwd,
+    });
+    last =
+      trunk.headSha === undefined
+        ? { status: trunk.status }
+        : { status: trunk.status, sha: trunk.headSha };
+    options.onObserved(last);
+    if (last.status !== "pending") return last;
+    await options.sleep(options.intervalMs);
+  }
+  return last;
+}

package/src/state/session-state.ts

@@ -1,6 +1,9 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { parseDeparture } from "../core/departure.ts";
 import {
+  CI_STATUSES,
+  type CiState,
+  type CiStatusName,
   type Departure,
   type DevsysState,
   initialState,
@@ -29,10 +32,20 @@ const JEV: ReadonlyArray<JevStatus> = ["online", "offline", "unknown"];
 const isRecord = (v: unknown): v is Record<string, unknown> =>
   typeof v === "object" && v !== null && !Array.isArray(v);
 
+function parseCi(input: unknown): CiState | ParseError {
+  if (!isRecord(input)) return parseError("ci must be an object");
+  const { status, sha } = input;
+  if (!CI_STATUSES.includes(status as CiStatusName)) {
+    return parseError(`unknown ci status: ${String(status)}`);
+  }
+  if (sha !== undefined && typeof sha !== "string") return parseError("ci.sha must be a string");
+  return { status: status as CiStatusName, ...(sha !== undefined ? { sha } : {}) };
+}
+
 /** Boundary parse for persisted state: the only place state is cast from `unknown`. */
 export function parseDevsysState(input: unknown): DevsysState | ParseError {
   if (!isRecord(input)) return parseError("devsys state must be an object");
-  const { phase, sizing, activeSlice, openDepartures, jev, lastPushAt } = input;
+  const { phase, sizing, activeSlice, openDepartures, jev, lastPushAt, ci } = input;
   if (!PHASES.includes(phase as Phase)) return parseError(`unknown phase: ${String(phase)}`);
   if (!JEV.includes(jev as JevStatus)) return parseError(`unknown jev status: ${String(jev)}`);
   if (!Array.isArray(openDepartures)) return parseError("openDepartures must be an array");
@@ -51,6 +64,8 @@ export function parseDevsysState(input: unknown): DevsysState | ParseError {
   if (lastPushAt !== undefined && typeof lastPushAt !== "string") {
     return parseError("lastPushAt must be a string");
   }
+  const parsedCi = ci === undefined ? undefined : parseCi(ci);
+  if (isParseError(parsedCi)) return parsedCi;
   return {
     phase: phase as Phase,
     jev: jev as JevStatus,
@@ -58,6 +73,7 @@ export function parseDevsysState(input: unknown): DevsysState | ParseError {
     ...(sizing !== undefined ? { sizing: sizing as Sizing } : {}),
     ...(activeSlice !== undefined ? { activeSlice: activeSlice as SliceRef } : {}),
     ...(lastPushAt !== undefined ? { lastPushAt } : {}),
+    ...(parsedCi !== undefined ? { ci: parsedCi } : {}),
   };
 }