@dieulc/workflow 0.3.3 → 0.4.0

package/README.md

@@ -39,6 +39,8 @@ Manage it with `pi list`, `pi update --extensions`, `pi remove npm:@dieulc/workf
 | `/review-prompt [global]` | Edit the reviewer's guidance (defaults to "align with the existing framework and industry best practice") |
 | `/review-status` | Show review phase, model, plan hash, findings and any error |
 | `/review` | Run one review round against the current plan file now |
+| `/commit` | Commit staged changes with an AI-summarized message (`-a`: stage tracked changes first). Confirmation-gated |
+| `/commit-policy [never\|ask\|allow] [global\|project]` | View or set the commit policy (default `never`: the agent cannot `git add`/`commit`/`push` — you commit, or use `/commit`) |
 
 ## Review Mode
 
@@ -234,6 +236,37 @@ A stored credential (`/login <provider>` → `auth.json`) always wins over the `
 
 Settings live under `workflow.reviewMode` in `~/.pi/agent/settings.json` (global) or `<cwd>/.pi/settings.json` (project). Project values win field-by-field over global. Writing them preserves every other key in the file.
 
+## Commit policy
+
+By default the agent **cannot touch your git history**: the tool gate deterministically blocks `git add`, `git commit` and `git push` — including compound commands (`git add -A && git commit -m x`), global-option forms (`git -C path add`) and `powershell` wrappers. You commit manually, or run `/commit` for an AI-summarized, confirmation-gated commit (its own `git commit` runs under a one-turn bypass; `push` is never bypassed). Read-only git (`status`, `log`, `diff`, `branch -a`, `config --get`, …) stays free, and plan mode keeps its stricter read-only rules regardless.
+
+The default exists because prompt-only rules are soft: models habitually commit per plan step, and "never commit unless asked" instructions in CLAUDE.md-style files are famously ignored (anthropics/claude-code#58883, #68724, #7029). Claude Code, Codex CLI and OpenCode all treat agent-initiated commits as something to gate or approve — so the policy here is enforced where commands execute, not in prose:
+
+| Agent | Default commit behavior | Control |
+| --- | --- | --- |
+| Claude Code | never auto-commits | CLAUDE.md rules (soft, documentedly ignored) + PreToolUse hooks (hard) |
+| Codex CLI | approval-gated git mutations | sandbox + `--approval-mode` |
+| OpenCode | no auto-commit | ordered `permission` rules (`git push *` → `deny`), global + project config |
+| Aider | auto-commits every edit | `--no-auto-commits`, `--commit-prompt` (the configurable-commit pole) |
+
+### Modes
+
+| Mode | Meaning |
+| --- | --- |
+| `never` (default) | `git add` / `git commit` / `git push` are blocked with a policy reason that tells the model to leave changes uncommitted for review |
+| `ask` | The agent may commit; every `git commit` / `git push` pops an Allow once / Deny dialog (headless sessions fail closed). `git add` stays free — staging alone pollutes nothing |
+| `allow` | **Automatic per-step commits.** While a plan todo list is active the extension itself makes exactly **one commit per completed step** (at the `workflow_todo` completion boundary, before the model starts the next step; subject `step N: <step text>`), and the model cannot run `git add`/`commit`/`push` at all. Outside a plan (no todos) the model may commit as before. `/commit` always works |
+
+The status line always shows the active policy (`▶ build 2/5 · commits:never`), so you can see at a glance what the agent may do to history.
+
+```text
+/commit-policy                # status: mode, which scope supplied it, both settings paths
+/commit-policy never          # set globally (~/.pi/agent/settings.json)
+/commit-policy allow project  # this repo only (<cwd>/.pi/settings.json)
+```
+
+Known limits (accepted, same trade-off OpenCode/Claude Code make): a configured git alias (e.g. `ci` → `commit`) is not recognized, and exotic obfuscations (`sh -c 'git commit'`) are caught only when the plain text survives. Plan-mode and subagent read-only gating are unaffected by the policy; the shadow-checkpoint rewind commits live in a separate bare repo and never appear in your history.
+
 ## Settings
 
 Role config lives in `~/.pi/agent/roles.json` v2 (user) with optional per-project override at `<cwd>/.pi/roles.json` (per-role replace). Each role holds exactly one `{provider, id, thinking}`. v1 `modelPool` files are discarded and reseeded on load. Seeded with defaults on first run. Respects `theme`, `modelRegistry`, and `plannotator` phases from `agent/plannotator.json`.
@@ -260,9 +293,25 @@ Review Mode settings live under `workflow.reviewMode`:
 
 `"reviewMode": true` is accepted as shorthand for `{ "enabled": true }`.
 
+Commit Policy settings live under `workflow.commitPolicy` (same global/project precedence, project wins field-by-field):
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `mode` | `"never"` | `"never"` = gate blocks `git add`/`commit`/`push`; `"ask"` = each `git commit`/`push` asks first; `"allow"` = automatic per-step commits (extension-driven, one per completed step; the model cannot commit during a plan) |
+
+```json
+{
+  "workflow": {
+    "commitPolicy": { "mode": "ask" }
+  }
+}
+```
+
+`"commitPolicy": "ask"` (a bare mode string) is accepted as shorthand for `{ "mode": "ask" }`. Booleans, numbers and unknown modes fall back to the default. `/commit-policy` writes this key read-modify-write, preserving every other settings key.
+
 ## How it works
 
-See `index.ts`, `checkpoint.ts` (shadow bare-repo), `utils.ts` (safe-command gating, todo/plan extraction, plan hashing), `roles.ts` (role registry, one model per role), and the Review Mode modules: `review.ts` (config, prompt, state, transcript, child session — no runtime imports, so it is unit-testable), `review-providers.ts` (parent→reviewer provider seeding and the provider-agnostic auth preflight), `review-tools.ts` (the reviewer's tool set), `review-runtime.ts` (round orchestration), `review-ui.ts` (the main-transcript entries: line buffer, formatters, renderers). Hot-reload via `/reload` when placed in `~/.pi/agent/extensions/workflow/` or loaded via `pi.extensions` manifest.
+See `index.ts`, `checkpoint.ts` (shadow bare-repo), `commit-policy.ts` (commit policy config, coercion and write — no runtime imports, unit-testable), `utils.ts` (safe-command gating, todo/plan extraction, plan hashing), `roles.ts` (role registry, one model per role), and the Review Mode modules: `review.ts` (config, prompt, state, transcript, child session — no runtime imports, so it is unit-testable), `review-providers.ts` (parent→reviewer provider seeding and the provider-agnostic auth preflight), `review-tools.ts` (the reviewer's tool set), `review-runtime.ts` (round orchestration), `review-ui.ts` (the main-transcript entries: line buffer, formatters, renderers). Hot-reload via `/reload` when placed in `~/.pi/agent/extensions/workflow/` or loaded via `pi.extensions` manifest.
 
 ### Todo protocol (industry-aligned)
 

package/commit-policy.ts

@@ -0,0 +1,358 @@
+/**
+ * Workflow Extension — Commit Policy
+ *
+ * User-controllable policy for agent-initiated git commits:
+ *
+ *   "never"  (default) — the agent may NOT run `git add` / `git commit` /
+ *            `git push`. The deterministic tool_call gate blocks them; the
+ *            user commits manually or via /commit (which uses a bypass).
+ *   "ask"     — every `git commit` / `git push` attempt pops a confirmation
+ *            dialog (`git add` stays free — staging alone pollutes nothing).
+ *   "allow"   — the agent may commit freely; during plan execution the
+ *            handoff prompt instructs per-step commits (user opted in).
+ *
+ * This module holds the pure, I/O-light parts (config, coercion, merge,
+ * read, write) so they can be unit-tested without a Pi runtime. Nothing
+ * here imports the Pi SDK at module scope — same discipline as review.ts.
+ *
+ * Settings live under `workflow.commitPolicy` in `~/.pi/agent/settings.json`
+ * (global) or `<cwd>/.pi/settings.json` (project). Project wins field-by-field
+ * over global; global wins over defaults. Writes preserve every other key in
+ * the file (Pi owns settings.json — we must not clobber it).
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** Pi's project config directory. Mirrors WORKFLOW_CONFIG_DIR without importing review.ts (which pulls provider modules). */
+export const COMMIT_CONFIG_DIR = ".pi";
+
+/** Top-level key in settings.json that namespaces all workflow settings. Mirrors WORKFLOW_SETTINGS_KEY. */
+export const WORKFLOW_SETTINGS_KEY = "workflow";
+
+/** Nested key under WORKFLOW_SETTINGS_KEY. */
+export const COMMIT_POLICY_KEY = "commitPolicy";
+
+/** How the agent may interact with git's staging/commit/push surface. */
+export type CommitPolicyMode = "never" | "ask" | "allow";
+
+export interface CommitPolicyConfig {
+  mode: CommitPolicyMode;
+}
+
+export const DEFAULT_COMMIT_POLICY_CONFIG: Readonly<CommitPolicyConfig> = {
+  mode: "never",
+};
+
+const COMMIT_POLICY_MODES: readonly CommitPolicyMode[] = [
+  "never",
+  "ask",
+  "allow",
+];
+
+/** A JSON object parsed from an untrusted source (settings file, fragment). */
+export type JsonObject = Record<string, unknown>;
+
+/**
+ * A raw `workflow.commitPolicy` fragment. A bare mode string ("never" |
+ * "ask" | "allow") is accepted as shorthand for `{ mode: <string> }` so a
+ * minimal settings file stays readable.
+ */
+export type RawCommitPolicySetting = JsonObject | string;
+
+/** Coerce an unknown value into a CommitPolicyMode, or undefined. */
+function coerceMode(value: unknown): CommitPolicyMode | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().toLowerCase();
+  return (COMMIT_POLICY_MODES as readonly string[]).includes(normalized)
+    ? (normalized as CommitPolicyMode)
+    : undefined;
+}
+
+/**
+ * Coerce an untrusted settings fragment into a complete CommitPolicyConfig.
+ * Accepts an object (`{ mode: "never" }`) or a bare mode string shorthand.
+ * Booleans, numbers, garbage and wrong types all fall back to `base`
+ * (defaults) — there is no boolean shorthand for commit policy. Never throws.
+ */
+export function coerceCommitPolicyConfig(
+  raw: unknown,
+  base: CommitPolicyConfig = DEFAULT_COMMIT_POLICY_CONFIG as CommitPolicyConfig,
+): CommitPolicyConfig {
+  if (typeof raw === "string") {
+    const mode = coerceMode(raw);
+    return mode ? { mode } : { ...base };
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return { ...base };
+  }
+  const mode = coerceMode((raw as JsonObject).mode);
+  return { mode: mode ?? base.mode };
+}
+
+/** Extract the `workflow.commitPolicy` fragment from a raw settings object. */
+export function extractCommitPolicyRaw(
+  settings: unknown,
+): RawCommitPolicySetting | undefined {
+  if (!settings || typeof settings !== "object" || Array.isArray(settings))
+    return undefined;
+  const wf = (settings as JsonObject)[WORKFLOW_SETTINGS_KEY];
+  if (!wf || typeof wf !== "object" || Array.isArray(wf)) return undefined;
+  const raw = (wf as JsonObject)[COMMIT_POLICY_KEY];
+  if (typeof raw === "string") return raw;
+  if (raw && typeof raw === "object" && !Array.isArray(raw))
+    return raw as JsonObject;
+  return undefined;
+}
+
+/**
+ * Merge global then project settings fragments, then coerce onto defaults.
+ * Project wins field-by-field over global; global wins over defaults.
+ */
+export function mergeCommitPolicyConfig(
+  globalRaw: unknown,
+  projectRaw: unknown,
+): CommitPolicyConfig {
+  const fromGlobal = coerceCommitPolicyConfig(globalRaw);
+  return coerceCommitPolicyConfig(projectRaw, fromGlobal);
+}
+
+export interface CommitConfigPaths {
+  global: string;
+  project: string;
+}
+
+/**
+ * Settings file locations. `agentDir` is passed in rather than read from the
+ * Pi SDK so this stays pure and testable.
+ */
+export function commitConfigPaths(
+  cwd: string,
+  agentDir: string,
+): CommitConfigPaths {
+  return {
+    global: path.join(agentDir, "settings.json"),
+    project: path.join(cwd, COMMIT_CONFIG_DIR, "settings.json"),
+  };
+}
+
+function readJsonSafe(fp: string): JsonObject | undefined {
+  try {
+    if (!fs.existsSync(fp)) return undefined;
+    const parsed: unknown = JSON.parse(fs.readFileSync(fp, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      return undefined;
+    return parsed as JsonObject;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Which settings scope supplied a field's effective value. */
+export type CommitPolicyScopeSource = "default" | "global" | "project";
+
+/**
+ * Which raw fragment supplied the effective `mode`: the project fragment when
+ * it carries the key, else the global fragment, else the built-in default.
+ * Pure and total.
+ */
+export function modeSourceOf(
+  globalRaw: RawCommitPolicySetting | undefined,
+  projectRaw: RawCommitPolicySetting | undefined,
+): CommitPolicyScopeSource {
+  const hasModeKey = (raw: unknown): boolean =>
+    typeof raw === "string"
+      ? coerceMode(raw) !== undefined
+      : Boolean(raw) &&
+        typeof raw === "object" &&
+        !Array.isArray(raw) &&
+        coerceMode((raw as JsonObject).mode) !== undefined;
+  if (hasModeKey(projectRaw)) return "project";
+  if (hasModeKey(globalRaw)) return "global";
+  return "default";
+}
+
+export interface ResolvedCommitPolicy {
+  config: CommitPolicyConfig;
+  /** Which files contributed (for /commit-policy status and debugging). */
+  sources: {
+    global: boolean;
+    project: boolean;
+    /** Which scope supplied the effective `mode` value. */
+    mode: CommitPolicyScopeSource;
+  };
+}
+
+/**
+ * Resolve the effective Commit Policy config from disk.
+ * Never throws — a corrupt or missing file falls back to defaults.
+ */
+export function readCommitPolicyConfig(
+  cwd: string,
+  agentDir: string,
+): ResolvedCommitPolicy {
+  const paths = commitConfigPaths(cwd, agentDir);
+  const globalSettings = readJsonSafe(paths.global);
+  const projectSettings = readJsonSafe(paths.project);
+  const globalRaw = extractCommitPolicyRaw(globalSettings);
+  const projectRaw = extractCommitPolicyRaw(projectSettings);
+  const config = mergeCommitPolicyConfig(globalRaw, projectRaw);
+  return {
+    config,
+    sources: {
+      global: globalRaw !== undefined,
+      project: projectRaw !== undefined,
+      mode: modeSourceOf(globalRaw, projectRaw),
+    },
+  };
+}
+
+/** One-line human-readable summary of a policy mode (for status output). */
+export function describeCommitPolicyMode(mode: CommitPolicyMode): string {
+  switch (mode) {
+    case "never":
+      return "agent cannot git add/commit/push — you commit (or /commit)";
+    case "ask":
+      return "agent may commit; each git commit/push asks first";
+    case "allow":
+      return "automatic: exactly one commit per completed plan step — the model itself never runs git commit";
+    default:
+      return "agent cannot git add/commit/push — you commit (or /commit)";
+  }
+}
+
+// ── Deterministic per-step commits (allow mode) ─────────────────────
+
+/** A completed plan step that may be due for its automatic commit. */
+export interface StepCommitCandidate {
+  /** Canonical global ref ("1", "2", …). */
+  ref: string;
+  /** Global step number when known (preferred for the message). */
+  step?: number;
+  /** Plan label fallback (e.g. "2.1"). */
+  label?: string;
+  /** Step text — becomes the commit subject. */
+  text: string;
+}
+
+export interface StepCommitDecisionInput {
+  mode: CommitPolicyMode;
+  /** A plan todo list is active (per-step automation only makes sense then). */
+  hasTodos: boolean;
+  /** Working tree has changes worth committing. */
+  dirty: boolean;
+  isInRepo: boolean;
+  /** Done steps not yet committed (already diffed against committed refs). */
+  completed: StepCommitCandidate[];
+}
+
+export interface StepCommitDecision {
+  commit: boolean;
+  refs: string[];
+  message: string;
+  /** Why no commit happens (for logs and notifications). */
+  skipReason?:
+    | "mode"
+    | "no-todos"
+    | "clean"
+    | "no-repo"
+    | "nothing-new";
+}
+
+/** Git subject lines should stay ≤ 72 chars. */
+const STEP_COMMIT_SUBJECT_MAX = 72;
+
+/**
+ * Build the deterministic commit subject for one completed step (or one
+ * batch): `step 3: implement parser` / `steps 2,3: first text (+1 more)`.
+ * Pure and total — the same steps always produce the same message.
+ */
+export function stepCommitMessage(items: StepCommitCandidate[]): string {
+  const first = items[0];
+  const text = String(first?.text ?? "").replace(/\s+/g, " ").trim();
+  if (items.length === 1) {
+    const num = first?.step ?? Number(first?.label) ?? 0;
+    const prefix = `step ${num > 0 ? num : (first?.ref ?? "?")}: `;
+    const room = STEP_COMMIT_SUBJECT_MAX - prefix.length;
+    const body = text.length > room ? `${text.slice(0, Math.max(0, room - 1))}…` : text;
+    return `${prefix}${body}`.slice(0, STEP_COMMIT_SUBJECT_MAX);
+  }
+  const nums = items
+    .map((i) => i.step ?? Number(i.label) ?? 0)
+    .filter((n) => n > 0);
+  const label = nums.length ? `steps ${nums.join(",")}` : "steps";
+  const suffix = ` (+${items.length - 1} more)`;
+  const room = STEP_COMMIT_SUBJECT_MAX - label.length - 2 - suffix.length;
+  const body = text.length > room ? `${text.slice(0, Math.max(0, room - 1))}…` : text;
+  return `${label}: ${body}${suffix}`.slice(0, STEP_COMMIT_SUBJECT_MAX);
+}
+
+/**
+ * Decide whether the extension itself should commit right now — the core of
+ * the per-step guarantee in `allow` mode. Exactly one commit per batch of
+ * newly completed steps; the CALLER owns idempotence by never passing a step
+ * twice (see committedStepRefs in index.ts). Never throws.
+ */
+export function stepCommitDecision(
+  input: StepCommitDecisionInput,
+): StepCommitDecision {
+  const none = (skipReason: NonNullable<StepCommitDecision["skipReason"]>): StepCommitDecision => ({
+    commit: false,
+    refs: [],
+    message: "",
+    skipReason,
+  });
+  if (!input?.isInRepo) return none("no-repo");
+  if (input.mode !== "allow") return none("mode");
+  if (!input.hasTodos) return none("no-todos");
+  const seen = new Set<string>();
+  const completed = (input.completed ?? []).filter((c) => {
+    if (!c || typeof c.ref !== "string" || !c.ref) return false;
+    if (seen.has(c.ref)) return false;
+    seen.add(c.ref);
+    return true;
+  });
+  if (completed.length === 0) return none("nothing-new");
+  if (!input.dirty) return none("clean");
+  return {
+    commit: true,
+    refs: completed.map((c) => c.ref),
+    message: stepCommitMessage(completed),
+  };
+}
+
+/**
+ * Read-modify-write `workflow.commitPolicy` into a settings file, preserving
+ * every other key in that file (Pi owns settings.json — we must not clobber it).
+ */
+export function writeCommitPolicyConfig(
+  scope: "global" | "project",
+  cwd: string,
+  agentDir: string,
+  patch: Partial<CommitPolicyConfig>,
+): { path: string; ok: boolean; error?: string } {
+  const paths = commitConfigPaths(cwd, agentDir);
+  const fp = scope === "project" ? paths.project : paths.global;
+  try {
+    const existing = readJsonSafe(fp);
+    const root: JsonObject = existing ? { ...existing } : {};
+    const wfExisting = root[WORKFLOW_SETTINGS_KEY];
+    const wf: JsonObject =
+      wfExisting && typeof wfExisting === "object" && !Array.isArray(wfExisting)
+        ? { ...(wfExisting as JsonObject) }
+        : {};
+    const current = coerceCommitPolicyConfig(wf[COMMIT_POLICY_KEY]);
+    const next = coerceCommitPolicyConfig({ ...current, ...patch }, current);
+    wf[COMMIT_POLICY_KEY] = next;
+    root[WORKFLOW_SETTINGS_KEY] = wf;
+    fs.mkdirSync(path.dirname(fp), { recursive: true });
+    fs.writeFileSync(fp, JSON.stringify(root, null, 2) + "\n", "utf8");
+    return { path: fp, ok: true };
+  } catch (e: unknown) {
+    return {
+      path: fp,
+      ok: false,
+      error: e instanceof Error ? e.message : String(e),
+    };
+  }
+}

package/index.ts

@@ -82,11 +82,21 @@ import {
 import {
   WORKFLOW_ROLE_ENV,
   explainCommandRefusal,
+  gitCommitPolicyHit,
   policyForRole,
   resolveSessionRole,
   subagentEnv,
   type WorkflowRole,
 } from "./permissions.ts";
+import {
+  commitConfigPaths,
+  describeCommitPolicyMode,
+  readCommitPolicyConfig,
+  stepCommitDecision,
+  writeCommitPolicyConfig,
+  type CommitPolicyMode,
+  type StepCommitCandidate,
+} from "./commit-policy.ts";
 import {
   isGitRepo,
   isGitRepoSync,
@@ -372,6 +382,21 @@ export default function workflowExtension(pi: ExtensionAPI) {
   let todoItems: TodoItem[] = [];
   // Plan file the current todo list was derived from (drives merge vs replace).
   let todoPlanPath: string | undefined;
+  // Armed while the user-invoked /commit flow's agent turn is running: its
+  // `git commit` bypasses the commit-policy gate (staging already happened
+  // extension-side via piExecGit, outside the tool gate). Cleared on
+  // turn_end/agent_settled so the window stays one turn wide.
+  let commitBypassActive = false;
+  // ── Deterministic per-step commits (allow mode) ──
+  // In 'allow' mode the EXTENSION — not the model — owns commit timing:
+  // exactly one commit per batch of newly completed plan steps, made at the
+  // workflow_todo tool_result boundary (the runner awaits tool_result
+  // handlers, so the commit lands before the model starts the next step).
+  // committedStepRefs makes the guarantee idempotent; stepCommitsSeeded
+  // marks pre-existing done steps (session resume, re-executed plan) as
+  // already accounted for so they never trigger a spurious commit.
+  const committedStepRefs = new Set<string>();
+  let stepCommitsSeeded = false;
   // ── Reminder throttle + staleness tracking (passive enforcement layer) ──
   let turnsSinceLastTodoWrite = 0;
   let turnsSinceLastReminder = 0;
@@ -600,14 +625,27 @@ export default function workflowExtension(pi: ExtensionAPI) {
   function updateStatus(ctx: ExtensionContext) {
     const roleLabel = activeRoleLabel();
     const suffix = roleLabel ? ` | ${roleLabel}` : "";
+    // Commit-policy surfacing (workflow.commitPolicy): always visible so the
+    // user can see at a glance what the agent may do to git history. Read
+    // live so /commit-policy changes show up without a reload.
+    let commitMode: CommitPolicyMode = "never";
+    try {
+      commitMode = readCommitPolicyConfig(
+        (ctx as any).cwd ?? process.cwd(),
+        getAgentDir(),
+      ).config.mode;
+    } catch {
+      commitMode = "never";
+    }
+    const policy = ` · commits:${commitMode}`;
     const staleMarker = todoStale ? " ⚠" : "";
     const done = todoItems.filter((t) => isDone(t)).length;
     const total = todoItems.length;
     if (workflowMode === "build") {
       const label =
         total > 0
-          ? `▶ build ${done}/${total}${staleMarker}${suffix}`
-          : `▶ build${suffix}`;
+          ? `▶ build ${done}/${total}${staleMarker}${suffix}${policy}`
+          : `▶ build${suffix}${policy}`;
       ctx.ui.setStatus("workflow", ctx.ui.theme.fg("accent", label));
     } else if (workflowMode === "plan") {
       const base = plannotatorActive
@@ -615,16 +653,22 @@ export default function workflowExtension(pi: ExtensionAPI) {
         : "⏸ plan";
       const label =
         total > 0
-          ? `${base} ${done}/${total}${staleMarker}${suffix}`
-          : `${base}${suffix}`;
+          ? `${base} ${done}/${total}${staleMarker}${suffix}${policy}`
+          : `${base}${suffix}${policy}`;
       ctx.ui.setStatus("workflow", ctx.ui.theme.fg("warning", label));
     } else if (total > 0) {
       ctx.ui.setStatus(
         "workflow",
-        ctx.ui.theme.fg("muted", `◦ ${done}/${total}${staleMarker}${suffix}`),
+        ctx.ui.theme.fg(
+          "muted",
+          `◦ ${done}/${total}${staleMarker}${suffix}${policy}`,
+        ),
       );
     } else {
-      ctx.ui.setStatus("workflow", undefined);
+      ctx.ui.setStatus(
+        "workflow",
+        ctx.ui.theme.fg("muted", `◦ commits:${commitMode}`),
+      );
     }
     if (todoItems.length > 0) {
       ctx.ui.setWidget("workflow-todos", (_tui, theme) => {
@@ -1200,6 +1244,112 @@ export default function workflowExtension(pi: ExtensionAPI) {
     },
   });
 
+  // ── /commit-policy: view/set the commit policy (workflow.commitPolicy) ──
+  // Available in every mode: it only writes settings JSON; the gate itself
+  // lives in tool_call and plan mode keeps its own stricter rules.
+  pi.registerCommand("commit-policy", {
+    description:
+      "View or set the commit policy (what the agent may git add/commit/push): /commit-policy never|ask|allow [global|project]",
+    handler: async (args, ctx) => {
+      const cwd = (ctx as any)?.cwd ?? process.cwd();
+      const agentDir = getAgentDir();
+      const tokens = String(args || "")
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean);
+      const sub = (tokens[0] || "").toLowerCase();
+      const scope: "global" | "project" =
+        tokens.includes("project") && !tokens.includes("global")
+          ? "project"
+          : "global";
+
+      if (!sub || sub === "status") {
+        const resolved = readCommitPolicyConfig(cwd, agentDir);
+        const paths = commitConfigPaths(cwd, agentDir);
+        const where =
+          resolved.sources.mode === "default"
+            ? "default — no settings file supplies it"
+            : `${resolved.sources.mode} settings`;
+        ctx.ui.notify(
+          [
+            `Commit policy: ${resolved.config.mode} (${where})`,
+            `  ${describeCommitPolicyMode(resolved.config.mode)}`,
+            `Global settings: ${paths.global}`,
+            `Project settings: ${paths.project}`,
+            "Usage: /commit-policy never|ask|allow [global|project]",
+          ].join("\n"),
+          "info",
+        );
+        updateStatus(ctx as any);
+        return;
+      }
+
+      if (sub !== "never" && sub !== "ask" && sub !== "allow") {
+        ctx.ui.notify(
+          [
+            "Usage: /commit-policy never|ask|allow [global|project]",
+            "  never  agent cannot git add/commit/push — you commit (or /commit)",
+            "  ask    agent may commit; each git commit/push asks first",
+            "  allow  agent may commit freely (per-step during plan execution)",
+          ].join("\n"),
+          "info",
+        );
+        return;
+      }
+
+      const res = writeCommitPolicyConfig(scope, cwd, agentDir, {
+        mode: sub as CommitPolicyMode,
+      });
+      if (!res.ok) {
+        ctx.ui.notify(
+          `Could not write commit-policy settings: ${res.error ?? "unknown error"}`,
+          "error",
+        );
+        return;
+      }
+      ctx.ui.notify(
+        `Commit policy → ${sub} (${scope})\n${describeCommitPolicyMode(
+          sub as CommitPolicyMode,
+        )}\nSettings: ${res.path}`,
+        "info",
+      );
+      updateStatus(ctx as any);
+    },
+    getArgumentCompletions: (prefix: string) => {
+      const flags = [
+        {
+          value: "never",
+          label: "never",
+          description:
+            "agent cannot git add/commit/push — you commit (or /commit)",
+        },
+        {
+          value: "ask",
+          label: "ask",
+          description: "agent may commit; each git commit/push asks first",
+        },
+        {
+          value: "allow",
+          label: "allow",
+          description:
+            "agent may commit freely (per-step during plan execution)",
+        },
+        {
+          value: "global",
+          label: "global",
+          description: "write to ~/.pi/agent/settings.json",
+        },
+        {
+          value: "project",
+          label: "project",
+          description: "write to <cwd>/.pi/settings.json",
+        },
+      ];
+      const filtered = flags.filter((f) => f.value.startsWith(prefix));
+      return filtered.length ? filtered : null;
+    },
+  });
+
   pi.registerCommand("review-prompt", {
     description:
       "Edit the reviewer's guidance (framework alignment / best practice) used by Review Mode",
@@ -1845,7 +1995,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
       };
       const firstTodo = todoItems[0];
       const feedbackBlock = feedback ? `\n\nFeedback: ${feedback}` : "";
-      const execMessage = `Execute the plan.\n\nRemaining steps:\n${remainingList}\n\nStart with: ${firstTodo ? firstTodo.text : (todoItems[0]?.text ?? "first step")}${feedbackBlock}\nAfter completing a step, include a [DONE:<ref>] tag in your response (use the numbers shown above).`;
+      const execMessage = `Execute the plan.\n\nRemaining steps:\n${remainingList}\n\nStart with: ${firstTodo ? firstTodo.text : (todoItems[0]?.text ?? "first step")}${feedbackBlock}${commitDirectiveLine(ctx)}\nAfter completing a step, include a [DONE:<ref>] tag in your response (use the numbers shown above).`;
       (pi as any).sendMessage?.(planTodoListMessage, { deliverAs: "followUp" });
       (pi as any).sendMessage?.(
         {
@@ -2121,6 +2271,10 @@ export default function workflowExtension(pi: ExtensionAPI) {
 
     // Inject a user message → triggers an agent turn that proposes + confirms + commits
     const message = buildCommitPrompt(statSummary, stageAll);
+    // Arm the commit-policy bypass for exactly this agent turn: its `git
+    // commit` must run even under policy 'never'. Disarmed on turn_end /
+    // agent_settled, so the window is one turn wide.
+    commitBypassActive = true;
     if ((pi as any).sendUserMessage) {
       (pi as any).sendUserMessage(message);
     } else {
@@ -4594,6 +4748,118 @@ export default function workflowExtension(pi: ExtensionAPI) {
     updateStatus(ctx as any);
   });
 
+  // ── Commit policy gate (workflow.commitPolicy) ──────────────────
+
+  /**
+   * Deterministic enforcement of the user's commit policy. Returns a block
+   * result for `git add` / `git commit` / `git push` per the active mode, or
+   * undefined when the command may proceed:
+   *   never → block; ask → confirmation overlay (headless: fail closed);
+   *   allow → automatic per-step commits while a plan todo list is active
+   * (the extension owns commit timing — model-initiated git add/commit/push
+   * are blocked); outside a plan the model may commit as before. The
+   * user-invoked /commit flow arms `commitBypassActive` so its own `git
+   * commit` runs (staging is extension-side; `push` and `add` are never
+   * bypassed).
+   */
+  async function commitPolicyGate(
+    event: any,
+    ctx: any,
+    cwd: string,
+  ): Promise<{ block: true; reason: string } | undefined> {
+    const policy = readCommitPolicyConfig(cwd, getAgentDir()).config.mode;
+    // allow outside a plan: no per-step automation to own commit timing, so
+    // the model keeps its previous freedom.
+    if (policy === "allow" && todoItems.length === 0) return undefined;
+    const cmd = String(event?.input?.command ?? "");
+    const hit = gitCommitPolicyHit(cmd);
+    if (!hit) return undefined;
+    // `add` is only gated in `never` mode; `ask` prompts on commit/push only
+    // (staging alone pollutes nothing).
+    if (policy === "ask" && hit === "add") return undefined;
+    // /commit bypass: only the flow's own `git commit` is exempt — `add` and
+    // `push` are not.
+    if (commitBypassActive && hit === "commit") {
+      return undefined;
+    }
+
+    if (policy === "never" || policy === "allow") {
+      return {
+        block: true,
+        reason:
+          policy === "never"
+            ? `Commit policy is 'never' (workflow.commitPolicy): \`git ${hit}\` is blocked. ` +
+              "Finish your steps and leave changes uncommitted for user review — the user commits manually or runs /commit. " +
+              `Change the policy with /commit-policy allow.\nCommand: ${cmd}`
+            : `Commit policy is 'allow' with an active plan: a commit is made AUTOMATICALLY after each completed step — do not run \`git ${hit}\` yourself. ` +
+              "Finish the step, mark it done via workflow_todo, and continue; the extension commits it (exactly one commit per step). " +
+              "/commit always works for user-invoked commits.\nCommand: " +
+              cmd,
+      };
+    }
+    // policy === "ask" → confirmation overlay. Headless has no one to ask →
+    // fail closed rather than commit unbidden.
+    const ui = ctx?.ui;
+    if (!ui || !ctx.hasUI) {
+      return {
+        block: true,
+        reason:
+          `Commit policy is 'ask' (workflow.commitPolicy): \`git ${hit}\` needs user approval, ` +
+          "but no interactive UI is available. Leave the change uncommitted and let the user decide.",
+      };
+    }
+    let sel: unknown;
+    try {
+      sel = await ui.select(
+        `Commit policy 'ask': allow \`git ${hit}\`?`,
+        ["Allow once", "Deny"],
+      );
+    } catch {
+      sel = undefined;
+    }
+    if (String(sel ?? "").startsWith("Allow")) return undefined;
+    return {
+      block: true,
+      reason:
+        `Commit policy 'ask': the user declined \`git ${hit}\`. Do not retry — ` +
+        "leave the changes uncommitted for the user.",
+    };
+  }
+
+  /**
+   * Policy-aware commit directive appended to the plan-execute handoff
+   * message. Empty string when the policy cannot be read (a config hiccup
+   * never blocks the handoff itself).
+   */
+  function commitDirectiveLine(ctx: any): string {
+    try {
+      const cwd = ctx?.cwd ?? process.cwd();
+      const mode = readCommitPolicyConfig(cwd, getAgentDir()).config.mode;
+      switch (mode) {
+        case "never":
+          return (
+            "\n\nCommit policy is 'never' (workflow.commitPolicy): do NOT run `git add`, `git commit`, or `git push`. " +
+            "Complete all steps and leave every change uncommitted for user review — the user commits manually or via /commit."
+          );
+        case "ask":
+          return (
+            "\n\nCommit policy is 'ask' (workflow.commitPolicy): you may commit after each completed step " +
+            "(`git add` + `git commit` with a concise conventional message); each `git commit`/`git push` will prompt the user for approval."
+          );
+        case "allow":
+          return (
+            "\n\nCommit policy is 'allow' (workflow.commitPolicy): do NOT run `git add`, `git commit`, or `git push` yourself — " +
+            "after each completed step the extension automatically makes exactly ONE commit containing the changes so far. " +
+            "Just finish a step, mark it done via workflow_todo, and move to the next step."
+          );
+        default:
+          return "";
+      }
+    } catch {
+      return "";
+    }
+  }
+
   // Block edits/writes + bash gating
   pi.on("tool_call", async (event, ctx) => {
     const cwd = (ctx as ExtensionContext).cwd;
@@ -4652,6 +4918,18 @@ export default function workflowExtension(pi: ExtensionAPI) {
         } as any;
       }
     }
+    // ── Commit policy gate ── Independent of the role gate: it also governs
+    // the unrestricted builder role — that is the point (user-controlled
+    // commit behavior). Plan mode is excluded: planner gating already blocks
+    // every mutating git command. Covers bash and powershell so a powershell
+    // wrapper cannot bypass the policy.
+    if (
+      (event.toolName === "bash" || event.toolName === "powershell") &&
+      workflowMode !== "plan"
+    ) {
+      const policyBlock = await commitPolicyGate(event, ctx, cwd);
+      if (policyBlock) return policyBlock as any;
+    }
     if (
       (event.toolName === "edit" || event.toolName === "write") &&
       workflowMode === "plan"
@@ -4735,6 +5013,104 @@ export default function workflowExtension(pi: ExtensionAPI) {
   });
 
   // ── Checkpoint lifecycle: track leaf entryId and prompt header ─
+  // ── Deterministic per-step commit executor (allow mode) ──────────
+
+  /** Mark pre-existing done steps (session resume, re-executed plan) as already accounted for. Called once per session. */
+  function seedCommittedStepRefs(): void {
+    if (stepCommitsSeeded) return;
+    stepCommitsSeeded = true;
+    for (const t of todoItems) {
+      if (!isDone(t) || itemStatus(t) === "cancelled") continue;
+      committedStepRefs.add(todoRef(t));
+    }
+  }
+
+  /** Done steps that have not been committed yet (in canonical order). */
+  function uncommittedDoneSteps(): StepCommitCandidate[] {
+    const out: StepCommitCandidate[] = [];
+    for (const t of todoItems) {
+      if (!isDone(t) || itemStatus(t) === "cancelled") continue;
+      const ref = todoRef(t);
+      if (committedStepRefs.has(ref)) continue;
+      out.push({ ref, step: t.step, label: t.label, text: t.text });
+    }
+    return out;
+  }
+
+  /**
+   * Make the automatic per-step commit when the policy calls for it.
+   * Deterministic: driven by the step-completion signal (workflow_todo
+   * tool_result / [DONE:ref] tags), never by model whimsy; the committed
+   * ref set makes it exactly-once per step. Never throws — a commit hiccup
+   * must not break the run.
+   */
+  async function autoCommitCompletedSteps(
+    ctx: any,
+    trigger: string,
+  ): Promise<void> {
+    try {
+      const cwd = ctx?.cwd ?? process.cwd();
+      if (!isGitRepoSync(cwd)) return;
+      seedCommittedStepRefs();
+      const completed = uncommittedDoneSteps();
+      const dirty = await isDirty(pi as any, cwd);
+      const mode = readCommitPolicyConfig(cwd, getAgentDir()).config.mode;
+      const decision = stepCommitDecision({
+        mode,
+        hasTodos: todoItems.length > 0,
+        dirty,
+        isInRepo: true,
+        completed,
+      });
+      if (!decision.commit) return;
+      const addRes = await piExecGit(["add", "-A"], cwd);
+      if (addRes.exitCode !== 0) {
+        try {
+          ctx?.ui?.notify?.(
+            `Per-step commit failed (git add): ${addRes.stderr.trim()}`,
+            "error",
+          );
+        } catch (_e) {
+          void _e;
+        }
+        return;
+      }
+      const commitRes = await piExecGit(["commit", "-m", decision.message], cwd);
+      if (commitRes.exitCode !== 0) {
+        try {
+          ctx?.ui?.notify?.(
+            `Per-step commit failed: ${commitRes.stderr.trim()}`,
+            "error",
+          );
+        } catch (_e) {
+          void _e;
+        }
+        return;
+      }
+      for (const ref of decision.refs) committedStepRefs.add(ref);
+      try {
+        ctx?.ui?.notify?.(
+          `Committed ${decision.refs.join(", ")} — ${decision.message}`,
+          "info",
+        );
+      } catch (_e) {
+        void _e;
+      }
+      try {
+        pi.appendEntry("workflow-step-commit", {
+          refs: decision.refs,
+          message: decision.message,
+          trigger,
+          at: Date.now(),
+        });
+      } catch (_e) {
+        void _e;
+      }
+    } catch {
+      // never break the agent run on a commit hiccup
+    }
+  }
+
   pi.on("tool_result", async (_event, ctx) => {
     try {
       const leaf =
@@ -4746,8 +5122,30 @@ export default function workflowExtension(pi: ExtensionAPI) {
     }
   });
 
+  // Per-step commit trigger: the runner AWAITS tool_result handlers, so the
+  // commit lands after the step is marked done and BEFORE the model starts
+  // the next step — exactly one commit per step, at the moment of completion.
+  pi.on("tool_result", async (event, ctx) => {
+    try {
+      const ev = event as any;
+      if (ev?.toolName !== "workflow_todo") return;
+      const action = String(ev?.input?.action ?? ev?.details?.action ?? "");
+      if (!action || action === "list" || action === "clear") return;
+      await autoCommitCompletedSteps(ctx, `workflow_todo:${action}`);
+    } catch (_e) {
+      void _e;
+    }
+  });
+
   pi.on("turn_start", async (_event, ctx) => {
     footerInjectedThisTurn = false;
+    // Seed the per-step commit ledger once per session: steps already done
+    // (restored sessions, re-executed plans) never trigger a spurious commit.
+    try {
+      seedCommittedStepRefs();
+    } catch (_e) {
+      void _e;
+    }
     if (!currentEntryId) return;
     const cwd = (ctx as any).cwd as string;
     try {
@@ -4778,6 +5176,9 @@ export default function workflowExtension(pi: ExtensionAPI) {
   });
 
   pi.on("agent_settled", async () => {
+    // Belt-and-braces: the run is over (completed, aborted or errored) — the
+    // /commit bypass must not leak into whatever runs next.
+    commitBypassActive = false;
     // keep persisted CustomEntry for reload, clear in-memory tombstone only on explicit prune; for now no clear to survive fork
   });
 
@@ -4956,10 +5357,24 @@ export default function workflowExtension(pi: ExtensionAPI) {
 
   // Track progress (all modes, whenever todos exist)
   pi.on("turn_end", async (event, ctx) => {
+    // Disarm the /commit bypass as soon as any turn ends: the /commit flow's
+    // `git commit` runs as a tool call WITHIN its turn, so this never disarms
+    // too early — and nothing after the turn inherits the exemption.
+    commitBypassActive = false;
     if (todoItems.length === 0) return;
     if (!isAssistantMessage(event.message as AgentMessage)) return;
     const text = getTextContent(event.message as AssistantMessage);
     const result = markCompletedRefs(text, todoItems);
+    // Fallback per-step commit for steps completed via [DONE:ref] tags in the
+    // response text (the workflow_todo path already committed at its
+    // tool_result; the committed-ref set makes this a no-op then).
+    if (result.marked > 0) {
+      try {
+        await autoCommitCompletedSteps(ctx, "turn_end:done-tags");
+      } catch (_e) {
+        void _e;
+      }
+    }
     if (result.unknown.length > 0 || result.ambiguous.length > 0) {
       lastRefMisses = { refs: [...result.unknown, ...result.ambiguous] };
       try {
@@ -5516,7 +5931,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
           const list = formatTodoNumberedList(todoItems);
           const content = plannotatorActive
             ? `**Plan ready** (${todoItems.length} steps)\\n\\nTo review in browser, ensure SSH port forwarding is active:\\n\`\`\`\\nLocalForward 9999 localhost:9999\\n\`\`\`\\nThen set \`PLANNOTATOR_REMOTE=1\` and \`PLANNOTATOR_PORT=9999\`.\\n\\nOr type "Execute the plan" to build directly.\\n\\nRemaining:\\n${list}`
-            : `**Plan ready** (${todoItems.length} steps)\\n\\n${preview.slice(0, 500)}...\\n\\nRemaining:\\n${list}\\n\\nType "Execute the plan" to build, or tell me what to refine.`;
+            : `**Plan ready** (${todoItems.length} steps)\\n\\n${preview.slice(0, 500)}...\\n\\nRemaining:\\n${list}\\n\\nType "Execute the plan" to build, or tell me what to refine.${commitDirectiveLine(ctx)}`;
           (pi as any).sendMessage?.(
             {
               customType: "workflow-handoff-fallback",
@@ -5932,7 +6347,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
                 display: true,
               };
               const firstTodo = todoItems[0];
-              const execMessage = `Execute the plan.\n\nRemaining steps:\n${remainingList}\n\nStart with: ${firstTodo ? firstTodo.text : todoItems[0].text}\nAfter completing a step, include a [DONE:<ref>] tag in your response (use the numbers shown above).`;
+              const execMessage = `Execute the plan.\n\nRemaining steps:\n${remainingList}\n\nStart with: ${firstTodo ? firstTodo.text : todoItems[0].text}${commitDirectiveLine(ctx)}\nAfter completing a step, include a [DONE:<ref>] tag in your response (use the numbers shown above).`;
               (pi as any).sendMessage?.(planTodoListMessage, {
                 deliverAs: "followUp",
               });

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@dieulc/workflow",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "type": "module",
   "private": false,
   "keywords": ["pi-package", "workflow", "plan-mode", "review-mode", "questionnaire", "rewind"],
   "description": "Plan↔Build mode with an independent Review Mode reviewer, questionnaire, subagent explore, todos and shadow-checkpoint rewind for Pi.",
   "license": "MIT",
   "scripts": {
-    "test": "node --test utils.todo.test.ts permissions.test.ts roles.test.ts review.test.ts review-ui.test.ts",
+    "test": "node --test utils.todo.test.ts permissions.test.ts roles.test.ts review.test.ts review-ui.test.ts commit-policy.test.ts",
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "repository": {
@@ -26,6 +26,7 @@
     "index.ts",
     "utils.ts",
     "checkpoint.ts",
+    "commit-policy.ts",
     "roles.ts",
     "permissions.ts",
     "review.ts",

package/permissions.ts

@@ -824,6 +824,104 @@ function classifyGit(s: string): CommandClass {
   return GIT_READ_ONLY_SUBCOMMANDS.has(sub) ? "read-only" : "full";
 }
 
+// ── Commit-policy classification ─────────────────────────────────
+
+/** Git subcommands the commit policy gates (`workflow.commitPolicy`). */
+export type CommitPolicyHit = "add" | "commit" | "push";
+
+const COMMIT_POLICY_SUBCOMMANDS: ReadonlySet<string> = new Set([
+  "add",
+  "commit",
+  "push",
+]);
+
+/** Global `git` options that take a separate value (`git -C path status`). */
+const GIT_GLOBAL_VALUE_OPTIONS: ReadonlySet<string> = new Set([
+  "-C",
+  "--git-dir",
+  "--work-tree",
+  "--namespace",
+  "--super-prefix",
+  "--exec-path",
+]);
+
+/** Global `git` flags that take no value (`git --no-pager log`). */
+const GIT_GLOBAL_FLAG_OPTIONS: ReadonlySet<string> = new Set([
+  "--no-pager",
+  "--paginate",
+  "--no-replace-objects",
+  "--bare",
+  "--no-optional-locks",
+  "--literal-pathspecs",
+  "--html-path",
+  "--man-path",
+  "--info-path",
+  "--version",
+]);
+
+/**
+ * Extract the subcommand a `git …` invocation resolves to, skipping global
+ * options. `null` when no subcommand is found. Mirrors classifyGit's
+ * option-skipping, but deliberately parses *through* `-c key=value` pairs:
+ * a config pair cannot turn a read-only subcommand into a commit, and the
+ * policy classifier must see the real subcommand (`git -c x=y commit`).
+ */
+function gitSubcommandAt(words: string[], gitIndex: number): string | null {
+  let i = gitIndex + 1;
+  while (i < words.length) {
+    const w = unquote(words[i]);
+    if (!w) {
+      i += 1;
+      continue;
+    }
+    if (w === "-c") {
+      i += 2; // -c key=value pair
+      continue;
+    }
+    if (w.startsWith("-c") && w.includes("=")) {
+      i += 1; // fused -ckey=value (defensive; git wants a space)
+      continue;
+    }
+    if (w.startsWith("--") && w.includes("=")) {
+      i += 1; // --git-dir=/x fused form
+      continue;
+    }
+    if (GIT_GLOBAL_VALUE_OPTIONS.has(w)) {
+      i += 2;
+      continue;
+    }
+    if (GIT_GLOBAL_FLAG_OPTIONS.has(w)) {
+      i += 1;
+      continue;
+    }
+    return w.toLowerCase();
+  }
+  return null;
+}
+
+/**
+ * Commit-policy classifier: does this command invoke `git add`, `git commit`
+ * or `git push` — in any segment of a compound command, including wrapper
+ * forms (`env git commit`, `nice -n 5 git add`) and global-option forms
+ * (`git -C path add`, `git.exe push`)? Returns the first matched subcommand,
+ * or null. Fail-closed by design: false positives (an unquoted
+ * `echo git commit`) are acceptable; false negatives are not.
+ */
+export function gitCommitPolicyHit(command: string): CommitPolicyHit | null {
+  if (typeof command !== "string" || !command.trim()) return null;
+  for (const segment of splitCommandSegments(command)) {
+    const words = wordsOf(segment);
+    for (let g = 0; g < words.length; g++) {
+      if (normalizeBinary(words[g]) !== "git") continue;
+      const sub = gitSubcommandAt(words, g);
+      if (sub && COMMIT_POLICY_SUBCOMMANDS.has(sub)) {
+        return sub as CommitPolicyHit;
+      }
+    }
+  }
+  return null;
+}
+
 function classifyDocker(s: string): CommandClass {
   const sub = wordAt(s, 1)?.toLowerCase();
   if (!sub) return "full";