@dieulc/workflow 0.3.1 → 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
 
@@ -190,10 +192,81 @@ The reviewer is an in-process child session created with `createAgentSession`, a
 
 An environment marker (`PI_WORKFLOW_REVIEW_CHILD`) is set only for the duration of session creation and restored immediately — the child runs in the same process, so leaking it would affect a later `/reload`.
 
+### Provider seeding
+
+The isolation above has one consequence: a provider that exists **only** because an extension registered it in the parent session (`pi.registerProvider(...)`) does not exist in the reviewer's freshly created runtime — every review round would fail with `No API key found for <provider>.` even though `/login` had stored a valid credential.
+
+Pi composes providers from three sources: the **built-in catalog**, the **static `~/.pi/agent/models.json`**, and **extension registrations** on the parent runtime. Only the last one is parent-only. Review Mode bridges it with a **present-probe**, not layer names (`review-providers.ts`):
+
+1. **Probe the parent** for a provider-registration surface: the session's model registry (`ctx.modelRegistry`) first, then the underlying runtime (`ctx.modelRuntime`). Both expose the same three accessors; a future Pi surface is picked up by adding one entry to the probe list.
+2. **Compare with the child.** Providers the child already composes are skipped. The built-in catalog and `~/.pi/agent/models.json` are loaded by *every* runtime by construction, so for them the seeder is a guaranteed no-op — and any future globally-composed provider source is skipped automatically, with zero layer-name drift.
+3. **Seed the difference, native-first.** For every provider the parent knows and the child does not, the seeder registers the parent's provider *object* when there is one, otherwise its config — each in its own try/catch, so a broken unrelated provider can never block a review. Idempotent: already-seeded ids are skipped on a second pass.
+4. **Preflight auth, provider-agnostically.** After seeding and before the session is created, the reviewer runtime is asked `hasConfiguredAuth(provider) || checkAuth(provider)` for the *reviewer model's own* provider. On absence the review fails fast with the provider name, the seed report, and the universal escape hatch below — never the bare mid-review error.
+
+Every bridged method is feature-detected: on a Pi version without a given accessor the seeder degrades to "nothing to seed" and the preflight reports the escape hatch instead of crashing.
+
+**The universal escape hatch (works for any provider, even without this fix):** `~/.pi/agent/models.json` is loaded by every runtime, including the reviewer's:
+
+```json
+{
+  "providers": {
+    "<provider>": {
+      "baseUrl": "https://…/v1",
+      "apiKey": "$MY_API_KEY",
+      "api": "openai-completions",
+      "models": [
+        {
+          "id": "<model-id>",
+          "name": "<display name>",
+          "reasoning": true,
+          "input": ["text"],
+          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
+          "contextWindow": 200000,
+          "maxTokens": 65536
+        }
+      ]
+    }
+  }
+}
+```
+
+A stored credential (`/login <provider>` → `auth.json`) always wins over the `apiKey` template, so `$MY_API_KEY` needs no environment variable while you are logged in. Extensions that register the same provider at runtime keep working: their live model list replaces the static one in the parent, so nothing regresses there.
+
 ### Configuration
 
 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`.
@@ -220,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-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)
 
@@ -232,6 +321,34 @@ See `index.ts`, `checkpoint.ts` (shadow bare-repo), `utils.ts` (safe-command gat
 - **Reminder cadence** (Claude Code-style throttle): a hidden `[TODO LIST]` context block is injected only when `turnsSinceLastTodoWrite ≥ TURNS_SINCE_WRITE` **and** `turnsSinceLastReminder ≥ TURNS_BETWEEN_REMINDERS` (`=3`). Unresolved `[DONE:…]` refs from the previous turn bypass the throttle once so the model learns the right numbers. A one-line `[TODO …]` footer is appended to the first successful `edit`/`write`/`bash` result of each turn.
 - **Stale notice (no forced turns)**: if a run mutated files but recorded no todo progress, the user gets one `⚠` status marker + a `ctx.ui.notify` (30 s dedupe); plan-file `- [x]` ticks are reconciled at `agent_end` in all modes, skipped when the plan content is unchanged (path+hash guard). No auto-completion — the list is never marked done based on intent. Legacy lists that already contain duplicate rows are not auto-merged; run `/todos clear` (or approve a new plan) to reset.
 
+## Troubleshooting
+
+### `No API key found for <provider>.` in a Review Mode round
+
+The transcript shows `Review Mode: … (could not prompt the reviewer: No API key found for <provider>.)`. This means the **reviewer session** could not compose auth for the provider — your login itself is fine (Plan/Build keep working off the same `auth.json`).
+
+The reviewer runs in an isolated session without ambient extensions by design (see [Provider seeding](#provider-seeding)), so a provider registered only by an extension in the parent session is invisible to it unless seeded, and its auth must resolve on its own. Since 0.3.2 the provider is seeded automatically and a missing auth fails fast with a message naming the provider, what the seed found, and the escape hatch.
+
+Fixes, in order of preference:
+
+1. **`/login <provider>`** — a stored credential in `~/.pi/agent/auth.json` is read by every runtime, including the reviewer's. No environment variable needed.
+2. **Static provider in `~/.pi/agent/models.json`** — the universal workaround (works even on an installed version without the seeding fix): add the provider under `"providers"` with `baseUrl`, `apiKey: "$MY_API_KEY"`, `api` and its `models` (template in [Provider seeding](#provider-seeding)).
+3. **`export MY_API_KEY=…`** — only needed when the provider config references `"$MY_API_KEY"` and no credential is stored.
+
+After editing `models.json`, run `/reload` or restart `pi` so every runtime picks it up.
+
+### `the reviewer's provider failed after N retry attempt(s): …` in a Review Mode round
+
+The warning reads `review skipped (the reviewer's provider failed after 3 retry attempt(s): 429 Too Many Requests …)` and the reviewer pane shows the provider's error text live. This is the reviewer's **model provider** failing mid-run — its API returned errors until Pi's auto-retry budget (`settings.retry.maxRetries`, default 3) ran out, so the run settled without ever reaching `review_submit_plan`. It is **not** a Review Mode fault and nothing was written; the author's plan is handed over unchanged.
+
+Earlier versions mislabeled this as `the reviewer finished without submitting a plan — it has no write path…`; since 0.3.3 the real provider error is captured from the reviewer session and reported here, in the pane, and via `/review-status` (the old message now appears only when the reviewer genuinely settled without calling `review_submit_plan`).
+
+What to do:
+
+1. **Check the provider** — the truncated message is the provider's own reply (rate limit, quota, overloaded, auth). Retry the review with `/review` once the provider recovers; a review that dies this way can simply be re-run.
+2. **A long review shares one API key with the parent** — planner + reviewer often hit the same key, so a long review can exhaust rate limits. Stagger heavy Plan Mode work or raise the provider's quota.
+3. **Switch the reviewer model** if the failures recur — `/role set reviewer <provider/model>` (see [Review Mode](#review-mode)); pick a model whose provider is currently healthy.
+
 ## Development
 
 ```bash

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