@dieulc/workflow 0.3.3 → 0.5.0

package/README.md

@@ -12,6 +12,7 @@ Plan↔Build mode with an independent **Review Mode** reviewer, questionnaire, s
 - **Rewind** — shadow bare-repo checkpoints per cwd (`agent/checkpoints/checkpoint-<slug>.git`), `isDirty` + `createSafetySnapshot` + `restoreCode`
 - **Plannotator bridge** — `plannotator:request/review-result/plan-approved` events, inline markdown handoff (`ScrollView` → inline scrollback), `getUtcDatePrefix` / `normalizePlanPath` for `.pi/plans/<UTC-date>-<slug>.md`
 - **Model roles** — Planner/Explorer/Builder roles with one model + thinking level each (`roles.ts`, `~/.pi/agent/roles.json` v2). `/plan` switches to the planner model, `/build` to the builder model, `explore` subagents use the explorer model. `/role` opens a tabbed picker (scoped models first, `Ctrl+O` for all).
+- **Model profiles** — named combinations of role models (`profiles.ts`, `~/.pi/agent/profiles.json` v1). Create a profile per provider or per budget, switch with `/profile` — activation is session-scoped, so two concurrent sessions can run different profiles. With no profile active the roles.json flow applies unchanged. See [Model Profiles](#model-profiles).
 
 ## Install
 
@@ -34,11 +35,41 @@ Manage it with `pi list`, `pi update --extensions`, `pi remove npm:@dieulc/workf
 | `/todos` | Show todo list |
 | `/btw` | Queue note for next turn |
 | `/role` | Config screen: one model + thinking per role (planner/explorer/builder/reviewer tabs, custom roles included). CLI: `list`, `set <role> <provider/model> [thinking]`, `use <role\|auto>`, `add/remove/reset` |
+| `/profile` | Switch or manage model profiles (named role-model combinations). Picker: activate / edit / rename / delete / New profile… / Default…. CLI: `list`, `show <name>`, `use <name\|none>`, `create <name>`, `edit <name>`, `rename <old> <new>`, `delete <name>`, `default [name\|none] [global\|project]` |
 | `/review-mode [on\|off] [global\|project]` | Enable/disable Review Mode (default `off`). `status` prints the effective config, naming the settings file that supplied the timeout |
 | `/review-mode timeout <seconds\|unlimited> [global\|project]` | Set or show the per-pass time cap (`unlimited`/`0` = no cap). Writes to global settings by default |
 | `/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`) |
+
+## Model Profiles
+
+A profile is a **named combination of role model settings** — one `{provider, id, thinking}` each for planner, explorer, builder and reviewer. Profiles layer on top of Model Roles: role identity (tools, system prompts, custom roles) stays global in `roles.json`; a profile only overrides models while it is active.
+
+```text
+/profile                    # picker: activate / edit / rename / delete / New profile… / Default…
+/profile create budget      # name it, then pick model + thinking per role (same flow as /role)
+/profile use budget         # activate for THIS session (none = back to the roles.json flow)
+/profile edit budget        # re-open the tabbed model editor
+/profile rename budget cheap
+/profile delete budget      # confirm dialog; deleting the active profile falls back to base roles
+/profile default budget     # workflow.defaultProfile — new sessions start on it (global|project)
+```
+
+### Semantics
+
+- **What a profile overrides**: model + thinking for the four built-in roles only. Tools, `systemPromptAddendum` and custom roles are global (roles.json) and are never touched by a profile. Partial profiles are allowed in hand-edited files — roles a profile does not name fall back to the base role model.
+- **Activation is session-scoped.** `/profile use` changes only the current session and rides the session's `workflow` entry, so `/resume` restores it and **two concurrent sessions can run different profiles** — session 1 on a cheap provider, session 2 on a premium one. There is deliberately no global "active profile" file.
+- **Optional default**: `workflow.defaultProfile` (see [Settings](#settings)) seeds sessions that never made an explicit choice; an explicit `/profile use <name|none>` always wins for that session.
+- **Effect**: `/plan` switches to the profile's planner, `/build` to the profile's builder, `explore` subagents run on the profile's explorer, and Review Mode's reviewer session uses the profile's reviewer (planner fallback preserved). Activating while in plan/build re-applies the mode model immediately; in Default mode nothing switches until the next plan/build/explore/review use — the manual chat model is never touched by activation.
+- **`/role` keeps editing the base roles.** With a profile active, the `/role` picker shows a notice and `/role list` prints the profile's overrides; `/profile edit <name>` is the way to change what actually runs.
+- **Fallback**: no profiles (or none active) → the roles.json flow, identical to before profiles existed. A profile referencing a model missing from the registry is warned about at save time and refused at switch time ("staying on current model"), same as `/role`.
+
+**Why**: mix models from different providers in one workflow (frontier planner + cheap explorer), keep one profile per provider to control budget per provider, run concurrent sessions on different providers to work around per-provider concurrency limits, and exploit cheaper starter plans across several providers.
+
+Profile config lives in `~/.pi/agent/profiles.json` v1 (user) with optional per-project override at `<cwd>/.pi/profiles.json` (per-profile replace, project wins). Names are case-insensitively unique, ≤ 40 chars, no whitespace (keep them CLI-addressable), and `none`/`auto` are reserved. A missing file is the normal empty state; a corrupt or wrong-version file is never rewritten (warning + in-memory empty config).
 
 ## Review Mode
 
@@ -234,10 +265,55 @@ 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`.
 
+Profile config lives in `~/.pi/agent/profiles.json` v1 (user) with optional per-project override at `<cwd>/.pi/profiles.json` (per-profile replace). Each profile holds `{name, description, roles}` where `roles` maps any of the four built-in role names to one `{provider, id, thinking}` — see [Model Profiles](#model-profiles).
+
+The default profile lives under `workflow.defaultProfile` (global/project precedence like the other workflow settings):
+
+```json
+{
+  "workflow": {
+    "defaultProfile": "cheap"
+  }
+}
+```
+
+`/profile default <name|none> [global|project]` writes this key read-modify-write, preserving every other settings key. Sessions that never picked explicitly (fresh or resumed) re-read it at every start, so changing the default applies to them; an explicit `/profile use` in a session pins that session until changed.
+
 Review Mode settings live under `workflow.reviewMode`:
 
 | Key | Default | Meaning |
@@ -260,9 +336,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), `profiles.ts` (profile registry, the model overlay and the `workflow.defaultProfile` setting — no Pi runtime needed, unit-testable), 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)
 
@@ -306,7 +398,7 @@ What to do:
 cd agent/extensions/workflow
 npm install
 npm run typecheck   # tsc --noEmit (covers every source file, including the review modules)
-npm test            # node --test utils.todo.test.ts review.test.ts review-ui.test.ts
+npm test            # node --test utils.todo.test.ts permissions.test.ts roles.test.ts profiles.test.ts review.test.ts review-ui.test.ts commit-policy.test.ts
 ```
 
 Plain TypeScript, no build step — Pi loads `index.ts` directly (via jiti). From the repo root, `npm run verify` checks this package's manifest, tarball contents, tests and load path before a release. Live reload: edit the `.ts` file and run `/reload` in Pi.

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),
+    };
+  }
+}