@jwilger/pi-development-system 0.1.2 → 0.2.0

package/extensions/development-system.ts

@@ -1,7 +1,12 @@
 import { readFileSync } from "node:fs";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { appendContextTail, renderContextTail } from "../src/context/context-tail.ts";
 import { renderStatus, renderStatusLine, STATUS_KEY } from "../src/context/status.ts";
 import { applyPromptSection } from "../src/context/system-prompt.ts";
+import { createApprovalStore } from "../src/gates/approvals.ts";
+import { registerGitGuard } from "../src/gates/git-guard.ts";
+import { createRecordDepartureTool } from "../src/gates/record-departure-tool.ts";
+import { createRequestApprovalTool } from "../src/gates/request-approval-tool.ts";
 import { createSessionState } from "../src/state/session-state.ts";
 
 const nonNegotiables = readFileSync(
@@ -12,6 +17,7 @@ const nonNegotiables = readFileSync(
 /** Composition root: wires modules, holds no logic. */
 export function createDevelopmentSystem(pi: ExtensionAPI) {
   const state = createSessionState(pi);
+  const approvals = createApprovalStore(pi);
 
   let lastCtx: ExtensionContext | undefined;
 
@@ -21,11 +27,11 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
 
   const rebuild = (ctx: ExtensionContext) => {
     lastCtx = ctx;
-    state.rebuildFrom(
-      ctx.sessionManager
-        .getBranch()
-        .flatMap((e) => (e.type === "custom" ? [{ customType: e.customType, data: e.data }] : [])),
-    );
+    const entries = ctx.sessionManager
+      .getBranch()
+      .flatMap((e) => (e.type === "custom" ? [{ customType: e.customType, data: e.data }] : []));
+    state.rebuildFrom(entries);
+    approvals.rebuildFrom(entries);
     refreshStatus();
   };
 
@@ -37,6 +43,15 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
     applyPromptSection(event, state.get(), nonNegotiables);
   });
 
+  pi.on("context", (event) => {
+    const messages = appendContextTail(event.messages, renderContextTail(state.get()), Date.now());
+    return messages === undefined ? undefined : { messages };
+  });
+
+  registerGitGuard({ pi, approvals });
+  pi.registerTool(createRecordDepartureTool({ pi, state }));
+  pi.registerTool(createRequestApprovalTool({ pi, approvals }));
+
   pi.registerCommand("devsys-status", {
     description: "Show development-system phase, sizing, slice, departures and Jev status",
     handler: async (_args, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "A pi extension package representing a seasoned approach to software development using a full AI SDLC.",
   "keywords": [
     "pi-package"
@@ -32,11 +32,12 @@
     ]
   },
   "dependencies": {
+    "shell-quote": "^1.12.0",
     "smol-toml": "^1.4.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
@@ -46,6 +47,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.6.4",
+    "@types/shell-quote": "^1.7.5",
     "@typesafe-ai/sdk": "^0.6.0",
     "typescript": "^7.0.2"
   },

package/src/context/context-tail.ts

@@ -0,0 +1,37 @@
+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): string | undefined {
+  if (state.phase === "idle" && state.openDepartures.length === 0) return undefined;
+  const head = [
+    "[development-system]",
+    `phase: ${state.phase} · slice: ${state.activeSlice ?? "none"}`,
+    `Jev: ${state.jev}`,
+  ];
+  const tailLines = [REMINDER];
+  const room = MAX_LINES - head.length - tailLines.length - 1;
+  const lines = state.openDepartures.map((d) => `- ${d.gate} — ${d.chosen} (${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 }];
+}

package/src/core/departure.ts

@@ -0,0 +1,96 @@
+import {
+  type Departure,
+  type DepartureId,
+  type DepartureScope,
+  type GateId,
+  isParseError,
+  type ParseError,
+  parseError,
+  parseGateId,
+  type SliceRef,
+} from "./types.ts";
+
+export type { Departure } from "./types.ts";
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+function parseScope(input: unknown): DepartureScope | ParseError {
+  if (!isRecord(input)) return parseError("scope must be an object");
+  const { kind, slice, toolCallId } = input;
+  if (kind === "session") return { kind: "session" };
+  if (kind === "slice" && typeof slice === "string") {
+    return { kind: "slice", slice: slice as SliceRef };
+  }
+  if (kind === "once" && typeof toolCallId === "string") return { kind: "once", toolCallId };
+  return parseError(`invalid scope: ${JSON.stringify(input)}`);
+}
+
+const TEXT_FIELDS = ["id", "default", "chosen", "why", "costIfWrong", "recordedAt"] as const;
+
+/** Boundary parse for a Departure (persisted entries, tool input). */
+export function parseDeparture(input: unknown): Departure | ParseError {
+  if (!isRecord(input)) return parseError("departure must be an object");
+  for (const field of TEXT_FIELDS) {
+    if (typeof input[field] !== "string") return parseError(`departure.${field} must be a string`);
+  }
+  const { id, gate: rawGate, tier, approver, revisitWhen } = input;
+  const gate = parseGateId(String(rawGate));
+  if (isParseError(gate)) return gate;
+  if (tier !== "soft" && tier !== "hard") return parseError(`departure.tier invalid: ${tier}`);
+  if (approver !== "agent" && approver !== "user") {
+    return parseError(`departure.approver invalid: ${approver}`);
+  }
+  if (revisitWhen !== undefined && typeof revisitWhen !== "string") {
+    return parseError("departure.revisitWhen must be a string");
+  }
+  const scope = parseScope(input.scope);
+  if (isParseError(scope)) return scope;
+  return {
+    id: id as DepartureId,
+    gate,
+    tier,
+    default: String(input.default),
+    chosen: String(input.chosen),
+    why: String(input.why),
+    costIfWrong: String(input.costIfWrong),
+    approver,
+    scope,
+    ...(revisitWhen !== undefined ? { revisitWhen } : {}),
+    recordedAt: String(input.recordedAt),
+  };
+}
+
+function renderScope(scope: DepartureScope): string {
+  switch (scope.kind) {
+    case "slice":
+      return `slice \`${scope.slice}\``;
+    case "session":
+      return "session";
+    case "once":
+      return `once (${scope.toolCallId})`;
+  }
+}
+
+/** Decision-log entry (plan Appendix A). Ends with a newline. */
+export function renderDepartureMarkdown(d: Departure): string {
+  const revisit = d.revisitWhen !== undefined ? ` · **Revisit when:** ${d.revisitWhen}` : "";
+  return [
+    `### ${d.recordedAt} · ${d.gate} · ${d.tier} · ${d.approver}`,
+    `- **Default:** ${d.default}`,
+    `- **Chosen:** ${d.chosen}`,
+    `- **Why:** ${d.why}`,
+    `- **Cost if wrong:** ${d.costIfWrong}`,
+    `- **Scope:** ${renderScope(d.scope)}${revisit}`,
+    "",
+  ].join("\n");
+}
+
+/** The first departure recorded for `gate` at or before `now` (ISO-8601 UTC strings compare lexically). */
+export function matchesPending(
+  departures: ReadonlyArray<Departure>,
+  gate: GateId,
+  now: string,
+): Departure | undefined {
+  return departures.find((d) => d.gate === gate && d.recordedAt <= now);
+}

package/src/core/gates.ts

@@ -0,0 +1,42 @@
+import type { Tier } from "./types.ts";
+
+export type GateInfo = { readonly tier: Tier; readonly default: string };
+
+/** Registered gate ids (plan Appendix A); grows per increment. Qualified ids use their base entry. */
+export const GATES: Readonly<Record<string, GateInfo>> = {
+  "git.history-rewrite": { tier: "hard", default: "never rewrite published history" },
+  "git.force-push": { tier: "hard", default: "never force-push" },
+  "git.branch-delete-remote": { tier: "hard", default: "never delete remote branches" },
+  "git.destructive-reset": {
+    tier: "hard",
+    default: "never discard uncommitted work with reset --hard",
+  },
+  "git.no-verify": { tier: "hard", default: "never skip commit hooks" },
+  "tests.weaken": { tier: "soft", default: "never weaken, skip or delete tests to get green" },
+  "commit.rationale": { tier: "soft", default: "commit messages carry their rationale" },
+  "commit.mixed-change": {
+    tier: "soft",
+    default: "structural and behavioural changes go in separate commits",
+  },
+  "commit.forbidden-trailer": { tier: "soft", default: "no Co-Authored-By or AI trailers" },
+  "push.red-trunk": { tier: "soft", default: "do not push unrelated work onto a red trunk" },
+  "push.delivery-mode": { tier: "soft", default: "follow the repository's delivery mode" },
+  "tdd.red-first": { tier: "soft", default: "write a failing test before changing behaviour" },
+  "lints.suppression": { tier: "soft", default: "do not suppress lints without a reasoned note" },
+  "review.unsatisfied": { tier: "soft", default: "finish the fresh-context review before release" },
+  "scope.expansion": { tier: "soft", default: "stay within the agreed scope" },
+  "models.phase-mismatch": { tier: "soft", default: "use the model slot routed for this phase" },
+  "artifact.skipped": {
+    tier: "soft",
+    default: "produce the planning artifact for this size of work",
+  },
+  "adr.missing": { tier: "soft", default: "record an ADR for architecture-shaping decisions" },
+};
+
+/** Looks up a gate by id, ignoring any `:qualifier`. */
+export function lookupGate(id: string): GateInfo | undefined {
+  const base = id.split(":")[0] ?? id;
+  return GATES[base];
+}
+
+export const gateIds = (): string[] => Object.keys(GATES);

package/src/core/git-intent.ts

@@ -0,0 +1,161 @@
+import { parse } from "shell-quote";
+
+export type GitIntent =
+  | "history-rewrite"
+  | "force-push"
+  | "branch-delete-remote"
+  | "destructive-reset"
+  | "no-verify"
+  | "ordinary"
+  | "unknown";
+
+/** Highest severity first. */
+const SEVERITY: ReadonlyArray<GitIntent> = [
+  "force-push",
+  "branch-delete-remote",
+  "history-rewrite",
+  "destructive-reset",
+  "no-verify",
+  "unknown",
+  "ordinary",
+];
+
+const worst = (a: GitIntent, b: GitIntent): GitIntent =>
+  SEVERITY.indexOf(a) <= SEVERITY.indexOf(b) ? a : b;
+
+/** Splits a command string on newlines that are outside quotes. */
+function splitLines(command: string): string[] {
+  const lines: string[] = [];
+  let current = "";
+  let quote: "'" | '"' | undefined;
+  for (const ch of command) {
+    if (quote !== undefined) {
+      if (ch === quote) quote = undefined;
+      current += ch;
+    } else if (ch === "'" || ch === '"') {
+      quote = ch;
+      current += ch;
+    } else if (ch === "\n") {
+      lines.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  lines.push(current);
+  return lines;
+}
+
+/** Tokens of one line grouped into simple commands (operators separate segments). */
+function segments(line: string): string[][] {
+  const result: string[][] = [[]];
+  for (const token of parse(line, (name) => `$${name}`)) {
+    if (typeof token === "string") result[result.length - 1]?.push(token);
+    else if ("pattern" in token) result[result.length - 1]?.push(token.pattern);
+    else if (!("comment" in token)) result.push([]);
+  }
+  return result.filter((s) => s.length > 0);
+}
+
+const WRAPPERS = new Set(["command", "sudo", "env", "time", "nohup", "exec", "builtin", "nice"]);
+const SHELLS = new Set(["bash", "sh", "zsh", "dash", "ksh"]);
+const OPAQUE = new Set(["xargs", "ssh", "find", "parallel", "watch"]);
+const GLOBAL_WITH_VALUE = new Set(["-c", "-C", "--git-dir", "--work-tree", "--namespace"]);
+const HOOK_SKIP_ENV = new Set(["LEFTHOOK=0", "HUSKY=0"]);
+
+const basename = (path: string): string => path.slice(path.lastIndexOf("/") + 1);
+const isAssignment = (t: string): boolean => /^[A-Za-z_][A-Za-z0-9_]*=/.test(t);
+
+function classifyGitArgs(globals: string[], sub: string | undefined, args: string[]): GitIntent {
+  let intent: GitIntent = "ordinary";
+  if (globals.some((g) => /^core\.hooksPath=/.test(g))) intent = worst(intent, "no-verify");
+  if (args.includes("--no-verify")) intent = worst(intent, "no-verify");
+  switch (sub) {
+    case "push": {
+      const shortFlags = args.filter((a) => /^-[A-Za-z]+$/.test(a));
+      if (
+        args.some((a) => /^--(force|force-with-lease|force-if-includes|mirror)\b/.test(a)) ||
+        shortFlags.some((a) => a.includes("f")) ||
+        args.some((a) => /^\+\S/.test(a))
+      ) {
+        return worst(intent, "force-push");
+      }
+      if (
+        args.includes("--delete") ||
+        shortFlags.includes("-d") ||
+        args.some((a) => /^:\S/.test(a))
+      ) {
+        return worst(intent, "branch-delete-remote");
+      }
+      return intent;
+    }
+    case "commit":
+      if (args.includes("--amend")) return worst(intent, "history-rewrite");
+      if (args.some((a) => /^-[A-Za-z]*n[A-Za-z]*$/.test(a))) return worst(intent, "no-verify");
+      return intent;
+    case "rebase":
+      return args.some((a) => ["--abort", "--continue", "--skip", "--quit"].includes(a))
+        ? intent
+        : worst(intent, "history-rewrite");
+    case "filter-branch":
+    case "filter-repo":
+      return worst(intent, "history-rewrite");
+    case "reset":
+      return args.includes("--hard") ? worst(intent, "destructive-reset") : intent;
+    default:
+      return intent;
+  }
+}
+
+function classifySegment(tokens: string[]): GitIntent {
+  let hookSkip = false;
+  let i = 0;
+  for (;;) {
+    const t = tokens[i];
+    if (t === undefined) return "ordinary";
+    if (isAssignment(t)) {
+      if (HOOK_SKIP_ENV.has(t)) hookSkip = true;
+      i++;
+    } else if (WRAPPERS.has(t)) {
+      i++;
+    } else {
+      break;
+    }
+  }
+  const head = tokens[i] ?? "";
+  const rest = tokens.slice(i + 1);
+  const base = basename(head);
+  const withHookSkip = (intent: GitIntent): GitIntent =>
+    hookSkip ? worst(intent, "no-verify") : intent;
+  if (head.startsWith("$") || base === "$GIT") return "unknown";
+  if (SHELLS.has(base)) {
+    const c = rest.indexOf("-c");
+    const script = c >= 0 ? rest[c + 1] : undefined;
+    return script !== undefined ? classifyGitCommand(script) : "ordinary";
+  }
+  if (base === "eval") return classifyGitCommand(rest.join(" "));
+  if (OPAQUE.has(base)) return rest.some((t) => basename(t) === "git") ? "unknown" : "ordinary";
+  if (base !== "git") return "ordinary";
+  const globals: string[] = [];
+  let j = 0;
+  while (j < rest.length && (rest[j] ?? "").startsWith("-")) {
+    const opt = rest[j] ?? "";
+    if (GLOBAL_WITH_VALUE.has(opt)) {
+      globals.push(rest[j + 1] ?? "");
+      j += 2;
+    } else {
+      j++;
+    }
+  }
+  const sub = rest[j];
+  return withHookSkip(classifyGitArgs(globals, sub, rest.slice(j + 1)));
+}
+
+/** Classifies the most severe git intent in a shell command (deterministic fast path). */
+export function classifyGitCommand(command: string): GitIntent {
+  let intent: GitIntent = "ordinary";
+  for (const line of splitLines(command)) {
+    for (const segment of segments(line)) intent = worst(intent, classifySegment(segment));
+  }
+  return intent;
+}

package/src/gates/approvals.ts

@@ -0,0 +1,100 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type Departure, parseDeparture } from "../core/departure.ts";
+import { lookupGate } from "../core/gates.ts";
+import { type GateId, isParseError } from "../core/types.ts";
+import { appendDecision } from "../state/decision-log.ts";
+import { DEPARTURE_ENTRY_TYPE } from "./record-departure-tool.ts";
+
+export const APPROVAL_ENTRY_TYPE = "devsys-approval";
+
+type Approval = { id: string; gate: string; command: string; used: boolean };
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** Pre-granted, single-use approvals for an exact (gate, command) pair, persisted as session entries. */
+export type ApprovalStore = {
+  grant(gate: string, command: string, id: string): void;
+  /** True (and marks the approval used) when an unused approval exists for this exact pair. */
+  consume(gate: string, command: string): boolean;
+  rebuildFrom(entries: ReadonlyArray<{ customType: string; data: unknown }>): void;
+};
+
+export function createApprovalStore(pi: ExtensionAPI): ApprovalStore {
+  let approvals: Approval[] = [];
+  const persist = (a: Approval) => pi.appendEntry(APPROVAL_ENTRY_TYPE, a);
+  return {
+    grant(gate, command, id) {
+      const approval = { id, gate, command: command.trim(), used: false };
+      approvals.push(approval);
+      persist(approval);
+    },
+    consume(gate, command) {
+      const found = approvals.find(
+        (a) => !a.used && a.gate === gate && a.command === command.trim(),
+      );
+      if (found === undefined) return false;
+      found.used = true;
+      persist(found);
+      return true;
+    },
+    rebuildFrom(entries) {
+      const byId = new Map<string, Approval>();
+      for (const e of entries) {
+        if (e.customType !== APPROVAL_ENTRY_TYPE || !isRecord(e.data)) continue;
+        const { id, gate, command, used } = e.data;
+        if (
+          typeof id === "string" &&
+          typeof gate === "string" &&
+          typeof command === "string" &&
+          typeof used === "boolean"
+        ) {
+          byId.set(id, { id, gate, command, used });
+        }
+      }
+      approvals = [...byId.values()];
+    },
+  };
+}
+
+export type HardStopRequest = {
+  pi: ExtensionAPI;
+  ctx: ExtensionContext;
+  gate: GateId;
+  command: string;
+  why: string;
+  toolCallId: string;
+  now?: () => Date;
+};
+
+export type HardStopOutcome =
+  | { kind: "approved"; departure: Departure }
+  | { kind: "declined" }
+  | { kind: "unavailable" };
+
+/** Asks the user to approve one irreversible action; on approval records it (hard · user · once). */
+export async function requestHardStop(req: HardStopRequest): Promise<HardStopOutcome> {
+  if (!req.ctx.hasUI) return { kind: "unavailable" };
+  const approved = await req.ctx.ui.confirm(
+    "Development system — hard stop",
+    `${req.command}\nGate: ${req.gate}\nThis is irreversible. Approve once?`,
+  );
+  if (!approved) return { kind: "declined" };
+  const at = (req.now ?? (() => new Date()))();
+  const departure = parseDeparture({
+    id: `dep-${at.getTime()}-${req.toolCallId}`,
+    gate: req.gate,
+    tier: "hard",
+    default: lookupGate(req.gate)?.default ?? "hard stop",
+    chosen: req.command,
+    why: req.why,
+    costIfWrong: "an irreversible git operation is performed",
+    approver: "user",
+    scope: { kind: "once", toolCallId: req.toolCallId },
+    recordedAt: at.toISOString().replace(/\.\d{3}Z$/, "Z"),
+  });
+  if (isParseError(departure)) throw new Error(departure.message);
+  await appendDecision(req.ctx.cwd, departure, at);
+  req.pi.appendEntry(DEPARTURE_ENTRY_TYPE, departure);
+  return { kind: "approved", departure };
+}

package/src/gates/git-guard.ts

@@ -0,0 +1,44 @@
+import { type ExtensionAPI, isToolCallEventType } from "@earendil-works/pi-coding-agent";
+import { classifyGitCommand, type GitIntent } from "../core/git-intent.ts";
+import { isParseError, parseGateId } from "../core/types.ts";
+import { type ApprovalStore, requestHardStop } from "./approvals.ts";
+
+const HARD: ReadonlySet<GitIntent> = new Set([
+  "history-rewrite",
+  "force-push",
+  "branch-delete-remote",
+  "destructive-reset",
+  "no-verify",
+]);
+
+export type GitGuardDeps = { pi: ExtensionAPI; approvals: ApprovalStore; now?: () => Date };
+
+/** Registers the `tool_call` hard stop for irreversible git operations in bash. */
+export function registerGitGuard(deps: GitGuardDeps): void {
+  deps.pi.on("tool_call", async (event, ctx) => {
+    if (!isToolCallEventType("bash", event)) return undefined;
+    const command = event.input.command;
+    const intent = classifyGitCommand(command);
+    if (!HARD.has(intent)) return undefined;
+    const gate = parseGateId(`git.${intent}`);
+    if (isParseError(gate)) return { block: true, reason: gate.message };
+    if (deps.approvals.consume(gate, command)) return undefined;
+    const outcome = await requestHardStop({
+      pi: deps.pi,
+      ctx,
+      gate,
+      command,
+      why: "approved interactively at the hard-stop dialog",
+      toolCallId: event.toolCallId,
+      ...(deps.now !== undefined ? { now: deps.now } : {}),
+    });
+    if (outcome.kind === "approved") return undefined;
+    return {
+      block: true,
+      reason:
+        outcome.kind === "unavailable"
+          ? `hard stop ${gate}: requires user approval; run interactively`
+          : `hard stop ${gate}: the user declined this command. Do not retry it; propose a reversible alternative.`,
+    };
+  });
+}

package/src/gates/record-departure-tool.ts

@@ -0,0 +1,99 @@
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { parseDeparture, renderDepartureMarkdown } from "../core/departure.ts";
+import { gateIds, lookupGate } from "../core/gates.ts";
+import { isParseError, parseGateId } from "../core/types.ts";
+import { appendDecision } from "../state/decision-log.ts";
+import type { SessionState } from "../state/session-state.ts";
+
+export const DEPARTURE_ENTRY_TYPE = "devsys-departure";
+
+const Parameters = Type.Object({
+  gate: Type.String({ description: `Gate id. One of: ${gateIds().join(", ")}` }),
+  chosen: Type.String({ description: "What you are doing instead of the default" }),
+  why: Type.String({ description: "Why the default does not fit here" }),
+  costIfWrong: Type.String({ description: "What goes wrong if this judgement is mistaken" }),
+  scope: Type.Union([Type.Literal("slice"), Type.Literal("session"), Type.Literal("once")], {
+    description: "How long the departure applies",
+  }),
+  revisitWhen: Type.Optional(Type.String({ description: "Condition that should reopen this" })),
+});
+
+export type RecordDepartureDeps = {
+  pi: ExtensionAPI;
+  state: SessionState;
+  now?: () => Date;
+};
+
+const fail = (text: string) => ({
+  content: [{ type: "text" as const, text }],
+  details: undefined,
+  isError: true,
+});
+
+function resolveScope(kind: "slice" | "session" | "once", toolCallId: string, slice?: string) {
+  if (kind === "once") return { kind, toolCallId };
+  if (kind === "session") return { kind };
+  return slice !== undefined ? { kind, slice } : undefined;
+}
+
+/** `devsys_record_departure`: the sanctioned escape hatch for soft gates. */
+export function createRecordDepartureTool(
+  deps: RecordDepartureDeps,
+): ToolDefinition<typeof Parameters> {
+  const now = deps.now ?? (() => new Date());
+  return {
+    name: "devsys_record_departure",
+    label: "Record departure",
+    description:
+      "Record a deliberate departure from a soft default before acting against it. " +
+      "Hard stops (git history/force/no-verify) cannot be recorded here; use devsys_request_approval.",
+    promptSnippet: "Record a departure from a development-system default (soft gates only)",
+    parameters: Parameters,
+    exposure: "direct",
+    async execute(toolCallId, params: Static<typeof Parameters>, _signal, _onUpdate, ctx) {
+      const gate = parseGateId(params.gate);
+      const info = isParseError(gate) ? undefined : lookupGate(gate);
+      if (isParseError(gate) || info === undefined) {
+        return fail(`Unknown gate "${params.gate}". Registered gates: ${gateIds().join(", ")}`);
+      }
+      if (info.tier === "hard") {
+        return fail(
+          `Gate ${gate} is a hard stop: it needs the user. Call devsys_request_approval with the command and your reason.`,
+        );
+      }
+      const current = deps.state.get();
+      const scope = resolveScope(params.scope, toolCallId, current.activeSlice);
+      if (scope === undefined) {
+        return fail('scope "slice" needs an active slice; use "session" or "once" instead.');
+      }
+      const recordedAt = now();
+      const departure = parseDeparture({
+        id: `dep-${recordedAt.getTime()}-${toolCallId}`,
+        gate,
+        tier: info.tier,
+        default: info.default,
+        chosen: params.chosen,
+        why: params.why,
+        costIfWrong: params.costIfWrong,
+        approver: "agent",
+        scope,
+        ...(params.revisitWhen !== undefined ? { revisitWhen: params.revisitWhen } : {}),
+        recordedAt: recordedAt.toISOString().replace(/\.\d{3}Z$/, "Z"),
+      });
+      if (isParseError(departure)) return fail(departure.message);
+      const { path } = await appendDecision(ctx.cwd, departure, recordedAt);
+      deps.pi.appendEntry(DEPARTURE_ENTRY_TYPE, departure);
+      deps.state.update((s) => ({ ...s, openDepartures: [...s.openDepartures, departure] }));
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Recorded in ${path}:\n\n${renderDepartureMarkdown(departure)}`,
+          },
+        ],
+        details: undefined,
+      };
+    },
+  };
+}

package/src/gates/request-approval-tool.ts

@@ -0,0 +1,62 @@
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { gateIds, lookupGate } from "../core/gates.ts";
+import { isParseError, parseGateId } from "../core/types.ts";
+import { type ApprovalStore, requestHardStop } from "./approvals.ts";
+
+const Parameters = Type.Object({
+  gate: Type.String({ description: "A hard gate id, e.g. git.force-push" }),
+  command: Type.String({ description: "The exact command you intend to run afterwards" }),
+  why: Type.String({ description: "Why this irreversible action is needed" }),
+});
+
+const text = (t: string, isError = false) => ({
+  content: [{ type: "text" as const, text: t }],
+  details: undefined,
+  isError,
+});
+
+export type RequestApprovalDeps = { pi: ExtensionAPI; approvals: ApprovalStore; now?: () => Date };
+
+/** `devsys_request_approval`: ask the user ahead of time to approve one hard-stop command. */
+export function createRequestApprovalTool(
+  deps: RequestApprovalDeps,
+): ToolDefinition<typeof Parameters> {
+  return {
+    name: "devsys_request_approval",
+    label: "Request approval",
+    description:
+      "Ask the user to approve one irreversible command (hard stop). Approval is single-use and " +
+      "only valid for the exact command text. Unavailable when running headless.",
+    promptSnippet: "Ask the user to approve an irreversible git command (hard stop)",
+    parameters: Parameters,
+    exposure: "direct",
+    async execute(toolCallId, params: Static<typeof Parameters>, _signal, _onUpdate, ctx) {
+      const gate = parseGateId(params.gate);
+      if (isParseError(gate) || lookupGate(gate)?.tier !== "hard") {
+        const hard = gateIds().filter((id) => lookupGate(id)?.tier === "hard");
+        return text(`"${params.gate}" is not a hard gate. Hard gates: ${hard.join(", ")}`, true);
+      }
+      const outcome = await requestHardStop({
+        pi: deps.pi,
+        ctx,
+        gate,
+        command: params.command,
+        why: params.why,
+        toolCallId,
+        ...(deps.now !== undefined ? { now: deps.now } : {}),
+      });
+      if (outcome.kind === "unavailable") {
+        return text("unavailable headless: hard stops need an interactive user.", true);
+      }
+      if (outcome.kind === "declined") {
+        return text(
+          "The user declined. Do not run this command; propose a reversible alternative.",
+          true,
+        );
+      }
+      deps.approvals.grant(gate, params.command, outcome.departure.id);
+      return text(`Approved once for gate ${gate}. Run exactly: ${params.command}`);
+    },
+  };
+}

package/src/state/decision-log.ts

@@ -0,0 +1,28 @@
+import { appendFile, mkdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { type Departure, renderDepartureMarkdown } from "../core/departure.ts";
+
+const exists = async (path: string): Promise<boolean> =>
+  stat(path).then(
+    () => true,
+    () => false,
+  );
+
+/** Appends a departure to `docs/decisions/YYYY-MM.md` (UTC month of `now`), creating it with a header. */
+export async function appendDecision(
+  repoRoot: string,
+  d: Departure,
+  now: Date,
+): Promise<{ path: string }> {
+  const month = now.toISOString().slice(0, 7);
+  const dir = join(repoRoot, "docs", "decisions");
+  const path = join(dir, `${month}.md`);
+  await mkdir(dir, { recursive: true });
+  const entry = renderDepartureMarkdown(d);
+  if (await exists(path)) {
+    await appendFile(path, `\n${entry}`);
+  } else {
+    await appendFile(path, `# Decisions — ${month}\n\n${entry}`);
+  }
+  return { path };
+}

package/src/state/session-state.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { parseDeparture } from "../core/departure.ts";
 import {
   type Departure,
   type DevsysState,
@@ -28,36 +29,18 @@ const JEV: ReadonlyArray<JevStatus> = ["online", "offline", "unknown"];
 const isRecord = (v: unknown): v is Record<string, unknown> =>
   typeof v === "object" && v !== null && !Array.isArray(v);
 
-const isString = (v: unknown): v is string => typeof v === "string";
-
-/** Structural check for a persisted Departure; I1.1's parseDeparture should supersede it. */
-function isDeparture(v: unknown): v is Departure {
-  if (!isRecord(v)) return false;
-  const scope = v["scope"];
-  const scopeOk =
-    isRecord(scope) &&
-    (scope["kind"] === "session" ||
-      (scope["kind"] === "slice" && isString(scope["slice"])) ||
-      (scope["kind"] === "once" && isString(scope["toolCallId"])));
-  return (
-    scopeOk &&
-    ["id", "gate", "default", "chosen", "why", "costIfWrong", "recordedAt"].every((k) =>
-      isString(v[k]),
-    ) &&
-    (v["tier"] === "soft" || v["tier"] === "hard") &&
-    (v["approver"] === "agent" || v["approver"] === "user") &&
-    (v["revisitWhen"] === undefined || isString(v["revisitWhen"]))
-  );
-}
-
 /** 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) || !openDepartures.every(isDeparture)) {
-    return parseError("openDepartures must be an array of valid departures");
+  if (!Array.isArray(openDepartures)) return parseError("openDepartures must be an array");
+  const departures: Departure[] = [];
+  for (const raw of openDepartures) {
+    const departure = parseDeparture(raw);
+    if (isParseError(departure)) return departure;
+    departures.push(departure);
   }
   if (sizing !== undefined && !SIZINGS.includes(sizing as Sizing)) {
     return parseError(`unknown sizing: ${String(sizing)}`);
@@ -71,7 +54,7 @@ export function parseDevsysState(input: unknown): DevsysState | ParseError {
   return {
     phase: phase as Phase,
     jev: jev as JevStatus,
-    openDepartures: openDepartures,
+    openDepartures: departures,
     ...(sizing !== undefined ? { sizing: sizing as Sizing } : {}),
     ...(activeSlice !== undefined ? { activeSlice: activeSlice as SliceRef } : {}),
     ...(lastPushAt !== undefined ? { lastPushAt } : {}),