@jwilger/pi-development-system 0.0.0 → 0.1.0

package/extensions/development-system.ts

@@ -0,0 +1,48 @@
+import { readFileSync } from "node:fs";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { renderStatus, renderStatusLine, STATUS_KEY } from "../src/context/status.ts";
+import { applyPromptSection } from "../src/context/system-prompt.ts";
+import { createSessionState } from "../src/state/session-state.ts";
+
+const nonNegotiables = readFileSync(
+  new URL("../principles/NON-NEGOTIABLES.md", import.meta.url),
+  "utf8",
+);
+
+/** Composition root: wires modules, holds no logic. */
+export default function developmentSystem(pi: ExtensionAPI): void {
+  const state = createSessionState(pi);
+
+  const refreshStatus = (ctx: ExtensionContext) => {
+    ctx.ui.setStatus(STATUS_KEY, renderStatusLine(state.get()));
+  };
+
+  pi.on("session_start", (_event, ctx) => {
+    state.rebuildFrom(ctx.sessionManager.getBranch().flatMap(toCustomEntry));
+    refreshStatus(ctx);
+  });
+
+  pi.on("session_tree", (_event, ctx) => {
+    state.rebuildFrom(ctx.sessionManager.getBranch().flatMap(toCustomEntry));
+    refreshStatus(ctx);
+  });
+
+  pi.on("before_agent_start", (event) => {
+    applyPromptSection(event, state.get(), nonNegotiables);
+  });
+
+  pi.registerCommand("devsys-status", {
+    description: "Show development-system phase, sizing, slice, departures and Jev status",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(renderStatus(state.get()), "info");
+    },
+  });
+}
+
+function toCustomEntry(entry: unknown): Array<{ customType: string; data: unknown }> {
+  if (typeof entry !== "object" || entry === null) return [];
+  const e = entry as { type?: unknown; customType?: unknown; data?: unknown };
+  return e.type === "custom" && typeof e.customType === "string"
+    ? [{ customType: e.customType, data: e.data }]
+    : [];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "A pi extension package representing a seasoned approach to software development using a full AI SDLC.",
   "keywords": [
     "pi-package"
@@ -13,14 +13,48 @@
   "type": "module",
   "files": [
     "extensions",
+    "src",
     "skills",
     "prompts",
+    "principles",
+    "agents",
     "themes"
   ],
+  "pi": {
+    "extensions": [
+      "./extensions/development-system.ts"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts"
+    ]
+  },
+  "dependencies": {
+    "smol-toml": "^1.4.0"
+  },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "@typesafe-ai/sdk": "^0.6.0",
+    "typescript": "^7.0.2"
+  },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "check:build-gate": "node scripts/build-gate.ts",
+    "check:version": "node scripts/check-version.ts"
   }
 }

package/principles/DEFAULTS.md

@@ -0,0 +1,20 @@
+# Defaults (recommended; judgement allowed, departure recorded)
+
+Follow these unless you have a grounded reason not to. If you depart, record
+why (what / why / cost if wrong) with the departure tool before continuing.
+
+- **RED first.** Write a failing test before behaviour changes. Why: it proves the test can fail.
+- **Functional core, imperative shell.** Pure decisions, thin effects. Why: logic stays testable without the world.
+- **Semantic types.** Parse at the boundary; illegal states unrepresentable. Why: the type is the proof.
+- **Typed errors as values.** No stringly errors for expected failures. Why: callers can handle what they can name.
+- **Structural and behavioural changes never share a commit.** Why: reviewable, revertable.
+- **Artifact set sized to the work.** Brief, decisions, journeys, event model, lens review, ADR — only what the work needs. Why: planning is not the product.
+- **Fresh-context review before commit.** Why: the author is the worst reviewer of their own diff.
+- **Clean-streak review depth.** Three consecutive clean rounds before final delivery. Why: later rounds catch what earlier ones missed.
+- **Scope stays what was asked.** Expansion from a finding is recorded. Why: scope is the steering wheel.
+- **Lint suppression needs a rationale comment.** Why: a bare suppression is a hidden quality shortcut.
+- **Model matches phase.** Stronger model to plan, review and advise; faster to implement. Why: cost where judgement is.
+- **Threat model proportional to exposure.** Why: trust single owners, harden shared surfaces.
+- **Keep context small.** Load skills lazily; one slice per clean context. Why: instruction following decays with context size.
+- **Push at least hourly.** If an hour passes without a push, challenge whether the increment is too big. Why: small steps expose bad plans early.
+- **Language-profile idioms** (Rust, TypeScript). Why: concrete idioms beat abstract principles for weaker models.

package/principles/NON-NEGOTIABLES.md

@@ -0,0 +1,35 @@
+# Non-negotiables
+
+Departing from any item below requires an explicit decision from the author
+(John). Do not decide it yourself, do not route around it. If you believe a
+departure is warranted: stop, say which item and why, and ask.
+
+## 1. Never rewrite pushed history or force-push
+Amend/rebase/reset of pushed refs, `--force*`, deleting shared branches. Because it destroys other people's basis for trust.
+
+## 2. Never weaken verification to make a gate pass
+Deleting, skipping or loosening tests; suppressing a lint; editing expected values to match output; `--no-verify`. Because a green gate must mean the same thing afterwards. (Changing a test because the *requirement* changed is a recorded departure, not this.)
+
+## 3. Never claim something was verified, run or green when it was not
+Because the record of evidence is the product. Evidence comes before claims.
+
+## 4. Never push on a red trunk
+Except a change whose purpose is fixing that failure. Because unrelated work on red hides the signal.
+
+## 5. Never work around an unresolved gate
+Stop, record, ask. Because a gate you can route around is not a gate.
+
+## 6. Never violate repo-local delivery policy
+Delivery mode, protected branches, required reviews. Because the repo, not this tool, owns policy.
+
+## 7. Never let secrets leave the machine unsanitised
+Commits, logs, eval cases, subagent prompts. Because exfiltration is irreversible.
+
+## 8. Never commit without a rationale-bearing Conventional Commit, or add AI attribution trailers
+No `Co-Authored-By`, no `Generated-by`. Because the message is the durable why; attribution noise is not.
+
+## 9. Never make an architecture-shaping decision without an ADR
+New dependency class, boundary change, persistence model, public contract. Because "Revisit when" is how decisions stay honest.
+
+## 10. Never ship model-visible instructions without an evidence check
+Skills, prompts, Jev questions need a fixture or eval. Because effectiveness is eval-driven, not vibes.

package/src/context/status.ts

@@ -0,0 +1,16 @@
+import type { DevsysState } from "../core/types.ts";
+
+export const STATUS_KEY = "devsys";
+
+export const renderStatusLine = (state: DevsysState): string =>
+  `devsys: ${state.phase} · jev ${state.jev}`;
+
+export const renderStatus = (state: DevsysState): string =>
+  [
+    "Development system status",
+    `- phase: ${state.phase}`,
+    `- sizing: ${state.sizing ?? "unset"}`,
+    `- active slice: ${state.activeSlice ?? "none"}`,
+    `- open departures: ${state.openDepartures.length}`,
+    `- jev: ${state.jev}`,
+  ].join("\n");

package/src/context/system-prompt.ts

@@ -0,0 +1,30 @@
+import type { BeforeAgentStartEvent } from "@earendil-works/pi-coding-agent";
+import type { DevsysState } from "../core/types.ts";
+
+export const PROMPT_SECTION_NAME = "development-system";
+
+/** 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(),
+    "",
+    "## Current state",
+    `- phase: ${state.phase}`,
+    `- active slice: ${slice}`,
+    `- open departures: ${state.openDepartures.length}`,
+    `- jev: ${state.jev}`,
+  ].join("\n");
+}
+
+/** Adapter: mutates the section on a before_agent_start event (never returns systemPrompt). */
+export function applyPromptSection(
+  event: BeforeAgentStartEvent,
+  state: DevsysState,
+  nonNegotiables: string,
+): void {
+  event.systemPromptOptions.sections[PROMPT_SECTION_NAME] = buildPromptSection(
+    state,
+    nonNegotiables,
+  );
+}

package/src/core/types.ts

@@ -0,0 +1,74 @@
+/** Pure domain types for the development system. No I/O lives here. */
+
+export type ParseError = { readonly kind: "parse-error"; readonly message: string };
+
+export const parseError = (message: string): ParseError => ({ kind: "parse-error", message });
+
+export const isParseError = (value: unknown): value is ParseError =>
+  typeof value === "object" &&
+  value !== null &&
+  (value as { kind?: unknown }).kind === "parse-error";
+
+export type Tier = "hard" | "soft" | "advisory";
+
+export type GateId = string & { readonly __brand: "GateId" };
+
+const GATE_ID = /^[a-z][a-z0-9-]*(\.[a-z0-9-]+)+(:[a-z0-9-]+)?$/;
+
+/** Gate ids are dotted kebab-case, optionally qualified: `artifact.skipped:brief`. */
+export function parseGateId(input: string): GateId | ParseError {
+  return GATE_ID.test(input)
+    ? (input as GateId)
+    : parseError(`invalid gate id "${input}": expected dotted kebab-case like "git.force-push"`);
+}
+
+export type GateDecision =
+  | { readonly kind: "allow" }
+  | { readonly kind: "block"; readonly reason: string }
+  | { readonly kind: "require-departure"; readonly gate: GateId; readonly reason: string }
+  | { readonly kind: "require-user"; readonly gate: GateId; readonly reason: string };
+
+export type Phase = "intake" | "planning" | "implementing" | "reviewing" | "delivering" | "idle";
+
+export type Sizing = "fix" | "change" | "capability" | "product";
+
+export type SliceRef = string & { readonly __brand: "SliceRef" };
+
+export type DepartureId = string & { readonly __brand: "DepartureId" };
+
+export type DepartureScope =
+  | { readonly kind: "slice"; readonly slice: SliceRef }
+  | { readonly kind: "session" }
+  | { readonly kind: "once"; readonly toolCallId: string };
+
+/** A recorded departure from a default or non-negotiable (plan Appendix A). */
+export type Departure = {
+  readonly id: DepartureId;
+  readonly gate: GateId;
+  readonly tier: "soft" | "hard";
+  readonly default: string;
+  readonly chosen: string;
+  readonly why: string;
+  readonly costIfWrong: string;
+  readonly approver: "agent" | "user";
+  readonly scope: DepartureScope;
+  readonly revisitWhen?: string;
+  readonly recordedAt: string;
+};
+
+export type JevStatus = "online" | "offline" | "unknown";
+
+export type DevsysState = {
+  readonly phase: Phase;
+  readonly sizing?: Sizing;
+  readonly activeSlice?: SliceRef;
+  readonly openDepartures: ReadonlyArray<Departure>;
+  readonly jev: JevStatus;
+  readonly lastPushAt?: string;
+};
+
+export const initialState = (): DevsysState => ({
+  phase: "idle",
+  openDepartures: [],
+  jev: "unknown",
+});

package/src/state/session-state.ts

@@ -0,0 +1,85 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  type Departure,
+  type DevsysState,
+  initialState,
+  isParseError,
+  type JevStatus,
+  type ParseError,
+  type Phase,
+  parseError,
+  type Sizing,
+  type SliceRef,
+} from "../core/types.ts";
+
+export const STATE_ENTRY_TYPE = "devsys-state";
+
+const PHASES: ReadonlyArray<Phase> = [
+  "intake",
+  "planning",
+  "implementing",
+  "reviewing",
+  "delivering",
+  "idle",
+];
+const SIZINGS: ReadonlyArray<Sizing> = ["fix", "change", "capability", "product"];
+const JEV: ReadonlyArray<JevStatus> = ["online", "offline", "unknown"];
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** 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;
+  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");
+  if (sizing !== undefined && !SIZINGS.includes(sizing as Sizing)) {
+    return parseError(`unknown sizing: ${String(sizing)}`);
+  }
+  if (activeSlice !== undefined && typeof activeSlice !== "string") {
+    return parseError("activeSlice must be a string");
+  }
+  if (lastPushAt !== undefined && typeof lastPushAt !== "string") {
+    return parseError("lastPushAt must be a string");
+  }
+  return {
+    phase: phase as Phase,
+    jev: jev as JevStatus,
+    openDepartures: openDepartures as Departure[],
+    ...(sizing !== undefined ? { sizing: sizing as Sizing } : {}),
+    ...(activeSlice !== undefined ? { activeSlice: activeSlice as SliceRef } : {}),
+    ...(lastPushAt !== undefined ? { lastPushAt } : {}),
+  };
+}
+
+export type SessionState = {
+  get(): DevsysState;
+  update(fn: (s: DevsysState) => DevsysState): void;
+  rebuildFrom(entries: ReadonlyArray<{ customType: string; data: unknown }>): void;
+};
+
+/**
+ * In-session authority for development-system state. Every update appends the
+ * full (small) state as a custom entry; on rebuild the last valid entry wins.
+ */
+export function createSessionState(api: ExtensionAPI): SessionState {
+  let current: DevsysState = initialState();
+  return {
+    get: () => current,
+    update(fn) {
+      current = fn(current);
+      api.appendEntry(STATE_ENTRY_TYPE, current);
+    },
+    rebuildFrom(entries) {
+      let rebuilt: DevsysState = initialState();
+      for (const entry of entries) {
+        if (entry.customType !== STATE_ENTRY_TYPE) continue;
+        const parsed = parseDevsysState(entry.data);
+        if (!isParseError(parsed)) rebuilt = parsed;
+      }
+      current = rebuilt;
+    },
+  };
+}