@mmerterden/multi-agent-pipeline 20.8.3 → 20.9.0

package/pipeline/schemas/token-budget.json

@@ -7,7 +7,7 @@
       "max_tokens": 13400
     },
     "phase-1-plan": {
-      "max_tokens": 10000
+      "max_tokens": 10250
     },
     "phase-2-dev": {
       "max_tokens": 10650
@@ -16,11 +16,11 @@
       "max_tokens": 17200
     },
     "phase-4-commit": {
-      "max_tokens": 6500
+      "max_tokens": 6600
     },
     "phase-5-report": {
-      "max_tokens": 5550
+      "max_tokens": 5700
     }
   },
-  "total_max_tokens": 63300
+  "total_max_tokens": 63550
 }

package/pipeline/scripts/agent-guard.py

@@ -594,6 +594,33 @@ def git_subcommand_mode() -> None:
             print(subs)
 
 
+def commit_scope_mode() -> None:
+    """`agent-guard.py --commit-scope`: read a Bash payload and print what its
+    commit takes beyond the index (unattended_policy.git_commit_scope), one
+    item per line. Never executes anything. At the deadline or on an error it
+    prints `ADD_ALL` and `COMMIT_ALL`, so the caller scans the widest set rather
+    than missing a path the commit could include."""
+    widest = "ADD_ALL\nCOMMIT_ALL"
+    _arm_deadline(lambda: _exit_with(widest))
+    try:
+        data = json.load(sys.stdin)
+        cmd = (data.get("tool_input") or {}).get("command", "")
+    except Exception:
+        cmd = ""
+    if not isinstance(cmd, str) or not cmd:
+        return
+    try:
+        sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+        import unattended_policy
+
+        items = unattended_policy.git_commit_scope(cmd)
+    except Exception:
+        print(widest)
+        return
+    for item in items:
+        print(item)
+
+
 def commit_dir_mode() -> None:
     """`agent-guard.py --commit-dir`: read a Bash payload and print the
     directory the first commit-writing git command on the line runs in, after
@@ -624,6 +651,9 @@ def main() -> None:
     if len(sys.argv) > 1 and sys.argv[1] == "--git-subcommand":
         git_subcommand_mode()
         return
+    if len(sys.argv) > 1 and sys.argv[1] == "--commit-scope":
+        commit_scope_mode()
+        return
     if len(sys.argv) > 1 and sys.argv[1] == "--commit-dir":
         commit_dir_mode()
         return

package/pipeline/scripts/owned-path-gate.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+
+/**
+ * @file owned-path-gate.mjs  -  block a change to a path the repo profile says
+ * an automated account owns (pipeline/lib/owned-path-gate.mjs).
+ *
+ * Usage:
+ *   owned-path-gate.mjs --help
+ *   owned-path-gate.mjs [--repo <dir>]
+ *                       [--staged | --range <base>..<head> | --paths <a,b|-> | --base <ref>]
+ *                       [--pr-labels <a,b>] [--author "<name> <email>"] [--no-gh]
+ *                       [--state <agent-state.json|auto>] [--out <file>]
+ *
+ * `--state auto` (the commit hook) reads the newest agent-state.json under the
+ * log root whose worktreePath is this checkout and whose run is still going
+ * (in_progress, awaiting_input or paused, no finishedAt), then
+ * <worktree>/agent-state.json; none means an attended run.
+ *
+ * The change set is one of: the index (--staged); the commits of a range, from
+ * their merge-base (--range); a given list (--paths, comma separated, or `-`
+ * for a NUL or newline separated list on stdin); by default everything since
+ * the merge-base with the profile's work branch (origin/HEAD when it has none,
+ * or the ref given with --base) plus uncommitted and untracked files. Without
+ * --base the default branch, origin/HEAD, origin/main, origin/master, main and
+ * master are tried in turn; when none shares history with HEAD an attended run
+ * skips with a note (a shallow clone is named as such) and an unattended run
+ * scans the index and working tree instead. A default change set above
+ * MAX_CHANGED paths is a wrong base, exit 2, not thousands of violations.
+ *
+ * The profile comes from repo-profile.mjs and its policy: attended runs honour
+ * owned entries that are confirmed, manual, or derived at high or medium
+ * confidence; runs that ask no confirmation (MULTI_AGENT_UNATTENDED=1, or a
+ * terminal autopilot run with state.autopilot) honour all of them
+ * (policyMode). Without a stored profile an attended run skips with a note,
+ * and a run that asks nothing derives one first (stored outside the repo).
+ *
+ * `gh` is asked for the PR's labels only when a violation has a bypass label
+ * that --pr-labels did not supply, and never makes the gate fail. --no-gh (or
+ * OWNED_PATH_GATE_NO_GH=1) turns it off.
+ *
+ * Output: JSON {violations, exempt, findings, ignored, checked, mode, skipped,
+ * profileSource, profileAction[, note]} on stdout, or in --out; one line per
+ * violation on stderr, the first MAX_PRINTED and a count of the rest. Exit 0
+ * clean or skipped, 1 violations, 2 usage or environment error. An existing
+ * --out file is removed first, so an error never leaves a stale result.
+ *
+ * @module pipeline/scripts/owned-path-gate
+ */
+
+import { mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { repoTop, runGate } from "../lib/owned-path-gate.mjs";
+import { listRuns } from "./_run-paths.mjs";
+
+const NAME = "owned-path-gate";
+const VALUE_FLAGS = new Set([
+  "repo",
+  "range",
+  "paths",
+  "base",
+  "pr-labels",
+  "author",
+  "state",
+  "out",
+]);
+const BOOL_FLAGS = new Set(["staged", "no-gh", "help"]);
+const MAX_PRINTED = 50;
+
+const USAGE = `Usage:
+  owned-path-gate.mjs [--repo <dir>]
+                      [--staged | --range <base>..<head> | --paths <a,b|-> | --base <ref>]
+                      [--pr-labels <a,b>] [--author "<name> <email>"] [--no-gh]
+                      [--state <agent-state.json|auto>] [--out <file>]
+
+Blocks a change to a path the repo profile says an automated account owns.
+  --staged        the index only
+  --range a..b    the commits of a range, from their merge-base
+  --paths a,b|-   a given list (- reads a NUL or newline separated list on stdin)
+  --base <ref>    the default diff (merge-base..HEAD plus uncommitted and
+                  untracked files) starts from this ref
+  --pr-labels     PR labels for bypass.label; --no-gh stops the read through gh
+  --author        the identity uncommitted changes are attributed to
+  --state         agent-state.json, for the run's mode; \`auto\` finds the live
+                  run whose worktree is this repo
+  --out <file>    write the JSON there instead of stdout
+
+Exit 0 clean or skipped, 1 violations, 2 usage or environment error.
+`;
+
+function parseArgs(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (!a.startsWith("--")) throw new Error(`unexpected argument: ${a}`);
+    const [k, inline] = a.slice(2).split(/=(.*)/s);
+    if (VALUE_FLAGS.has(k)) {
+      const v = inline ?? argv[(i += 1)];
+      if (v === undefined) throw new Error(`--${k} needs a value`);
+      flags[k] = v;
+    } else if (BOOL_FLAGS.has(k)) flags[k] = true;
+    else throw new Error(`unknown flag: --${k}`);
+  }
+  const sources = ["staged", "range", "paths", "base"].filter((k) => flags[k] !== undefined);
+  if (sources.length > 1) {
+    throw new Error(`pick one of --staged, --range, --paths, --base (got ${sources.join(", ")})`);
+  }
+  return flags;
+}
+
+function readPaths(value) {
+  const text = value === "-" ? readFileSync(0, "utf8") : value;
+  const sep = value === "-" ? /[\0\n]/ : /,/;
+  return text
+    .split(sep)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+const LIVE = new Set(["in_progress", "awaiting_input", "paused"]);
+
+function realOrNull(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return null;
+  }
+}
+
+/** The state of the live run working in `repo`, or null. */
+export function findRunState(repo) {
+  const top = realOrNull(repoTop(repo));
+  if (!top) return null;
+  let best = null;
+  for (const run of listRuns()) {
+    const file = join(run.dir, "agent-state.json");
+    let state;
+    let mtime;
+    try {
+      state = JSON.parse(readFileSync(file, "utf8"));
+      mtime = statSync(file).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (!state || !LIVE.has(state.status) || state.finishedAt) continue;
+    const trees = [state.worktreePath, ...(state.projects ?? []).map((p) => p?.worktreePath)];
+    if (!trees.some((t) => typeof t === "string" && realOrNull(t) === top)) continue;
+    if (!best || mtime > best.mtime) best = { state, mtime };
+  }
+  return best ? best.state : readState(join(top, "agent-state.json"));
+}
+
+function readState(path) {
+  if (!path) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function main() {
+  const flags = parseArgs(process.argv.slice(2));
+  if (flags.help) {
+    process.stdout.write(USAGE);
+    return;
+  }
+  if (flags.out) rmSync(flags.out, { force: true });
+  const result = runGate(flags.repo || process.cwd(), {
+    staged: Boolean(flags.staged),
+    range: flags.range || null,
+    paths: flags.paths !== undefined ? readPaths(flags.paths) : null,
+    base: flags.base || null,
+    author: flags.author || null,
+    labels: flags["pr-labels"]
+      ? flags["pr-labels"]
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : [],
+    gh: !flags["no-gh"] && process.env.OWNED_PATH_GATE_NO_GH !== "1",
+    state:
+      flags.state === "auto" ? findRunState(flags.repo || process.cwd()) : readState(flags.state),
+  });
+  const { exitCode, ...body } = result;
+  const text = `${JSON.stringify(body, null, 2)}\n`;
+  if (flags.out) {
+    mkdirSync(dirname(flags.out), { recursive: true });
+    writeFileSync(flags.out, text);
+  } else {
+    process.stdout.write(text);
+  }
+  for (const v of body.violations.slice(0, MAX_PRINTED)) {
+    process.stderr.write(`${NAME}: BLOCKED ${v.path} (owned: ${v.glob}): ${v.fix}\n`);
+  }
+  const rest = body.violations.length - MAX_PRINTED;
+  if (rest > 0) {
+    process.stderr.write(`${NAME}: ... and ${rest} more owned path(s), listed in the JSON\n`);
+  }
+  if (body.skipped && body.note) process.stderr.write(`${NAME}: ${body.note}\n`);
+  process.exitCode = exitCode;
+}
+
+if (invokedDirectly(import.meta.url)) runMain(NAME, main, { code: 2 });

package/pipeline/scripts/pre-commit-check.sh

@@ -1,7 +1,8 @@
 #!/bin/bash
 # Pre-commit secret detection for multi-agent pipeline
 # Scans staged git changes for accidentally committed secrets
-# Exit 0 = clean, Exit 2 = secrets found. The PreToolUse hook contract
+# Exit 0 = clean, Exit 2 = secrets found or, on a commit, a path an automated
+# account owns (owned_path_gate below). The PreToolUse hook contract
 # (install/templates/claude-hooks.json, agent-guard.sh) blocks the tool call
 # only on exit 2, with the reason on stderr.
 #
@@ -547,6 +548,155 @@ if [ $FOUND -eq 1 ]; then
   exit 2
 fi
 
+# Owned-path gate: a commit must not carry a path the repo profile says an
+# automated account owns. Commit hook only; a direct run stays the secret scan.
+# The profile's globs are read with sed, so a commit that touches no owned
+# prefix never reaches the gate itself. Anything missing (profile, node, a
+# readable result) lets the commit through with one line.
+# The literal directory part of each glob on stdin, before its first wildcard
+# (lib/owned-path-gate.mjs ownedPrefix), normalized the way the gate does:
+# doubled slashes collapsed, leading `./` and `/` and trailing slashes trimmed. Each line
+# carries a `P:` sentinel so an empty prefix (a glob that starts with a
+# wildcard, which every path matches) survives command substitution.
+owned_prefixes() {
+  local glob
+  while IFS= read -r glob; do
+    while [ "${glob#*//}" != "$glob" ]; do glob="${glob%%//*}/${glob#*//}"; done
+    while [ "${glob#./}" != "$glob" ]; do glob="${glob#./}"; done
+    glob="${glob#/}"
+    while [ "${glob%/}" != "$glob" ]; do glob="${glob%/}"; done
+    case "$glob" in
+      *[\*\?\[]*)
+        glob="${glob%%[\*\?\[]*}"
+        case "$glob" in
+          */*) printf 'P:%s\n' "${glob%/*}/" ;;
+          *) printf 'P:\n' ;;
+        esac
+        ;;
+      *) printf 'P:%s\n' "$glob" ;;
+    esac
+  done
+}
+# The host's project slug for an absolute path (lib/repo-profile.mjs
+# projectSlug): every UTF-16 code unit outside [A-Za-z0-9] becomes `-`. sed
+# counts bytes or characters depending on the locale, so a path that is not
+# plain ASCII goes through node, which counts the way the library does.
+owned_slug() {
+  if printf '%s' "$1" | LC_ALL=C grep -q '[^ -~]'; then
+    command -v node >/dev/null 2>&1 || return 1
+    node -e 'process.stdout.write(process.argv[1].replace(/[^A-Za-z0-9]/g, "-"))' "$1"
+  else
+    printf '%s' "$1" | LC_ALL=C sed 's/[^A-Za-z0-9]/-/g'
+  fi
+}
+owned_path_gate() {
+  local common main slug profile profiles prefixes list="" p hit=0 always=0 out rc glob top
+  local scope item add_all=0 tracked_all=0 add_specs commit_specs
+  top="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+  [ -n "$top" ] || top="$PWD"
+  # The commit's own paths: the index, plus what the same command adds or
+  # `commit -a` / `commit <pathspec>` takes (agent-guard.py --commit-scope).
+  # A dirty file the commit leaves out is not judged. Without the helper the
+  # widest set is scanned, as the secret scan above does.
+  scope="ADD_ALL"$'\n'"COMMIT_ALL"
+  if command -v python3 >/dev/null 2>&1 && [ -f "$PRE_COMMIT_DIR/agent-guard.py" ] && [ -n "${HOOK_INPUT:-}" ]; then
+    scope="$(printf '%s' "$HOOK_INPUT" | python3 "$PRE_COMMIT_DIR/agent-guard.py" --commit-scope 2>/dev/null)" \
+      || scope="ADD_ALL"$'\n'"COMMIT_ALL"
+  fi
+  add_specs=()
+  commit_specs=()
+  while IFS= read -r item; do
+    case "$item" in
+      ADD_ALL) add_all=1 ;;
+      ADD_UPDATE | COMMIT_ALL) tracked_all=1 ;;
+      "ADD "*) add_specs+=("${item#ADD }") ;;
+      "COMMIT "*) commit_specs+=("${item#COMMIT }") ;;
+    esac
+  done <<<"$scope"
+  while IFS= read -r -d '' p; do
+    list="$list$p"$'\n'
+  done < <(
+    git -C "$top" diff --cached --name-only --no-renames -z 2>/dev/null
+    if [ "$add_all" = "1" ] || [ "$tracked_all" = "1" ]; then
+      git -C "$top" diff HEAD --name-only --no-renames -z 2>/dev/null
+    fi
+    if [ "$add_all" = "1" ]; then
+      git -C "$top" ls-files --others --exclude-standard --full-name -z 2>/dev/null
+    fi
+    if [ "${#add_specs[@]}" -gt 0 ]; then
+      git ls-files --modified --others --exclude-standard --full-name -z -- "${add_specs[@]}" 2>/dev/null
+    fi
+    if [ "${#commit_specs[@]}" -gt 0 ]; then
+      git ls-files --modified --full-name -z -- "${commit_specs[@]}" 2>/dev/null
+    fi
+  )
+  [ -n "$list" ] || return 0
+  common="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null || true)"
+  if [ -n "$common" ] && [ "$(basename "$common")" = ".git" ]; then
+    main="$(cd "$(dirname "$common")" 2>/dev/null && pwd -P)"
+  else
+    main="$(cd "$top" 2>/dev/null && pwd -P)"
+  fi
+  [ -n "$main" ] || return 0
+  if ! slug="$(owned_slug "$main")" || [ -z "$slug" ]; then
+    echo "pre-commit-check: node unavailable to locate the repo profile for $main - owned-path gate skipped" >&2
+    return 0
+  fi
+  profiles=""
+  for profile in "${HOME:-}/.claude/projects/$slug/repo-profile.json" \
+    "${MA_UNATTENDED_RUN_ROOT:-${HOME:-}/.multi-agent-unattended}/repo-profiles/$slug/repo-profile.json"; do
+    [ -f "$profile" ] && profiles="$profiles$profile"$'\n'
+  done
+  if [ -z "$profiles" ]; then
+    echo "pre-commit-check: no repo profile for $main - owned-path gate skipped" >&2
+    return 0
+  fi
+  prefixes="$(while IFS= read -r profile; do
+    [ -n "$profile" ] && sed -n 's/^ *"glob": *"\(.*\)",\{0,1\} *$/\1/p' "$profile"
+  done <<<"$profiles" | owned_prefixes)"
+  if [ -z "$prefixes" ]; then
+    echo "pre-commit-check: the repo profile for $main lists no owned path - owned-path gate skipped" >&2
+    return 0
+  fi
+  while IFS= read -r glob; do
+    [ "$glob" = "P:" ] && always=1
+  done <<<"$prefixes"
+  if [ "$always" = "1" ]; then
+    hit=1
+  else
+    while IFS= read -r p; do
+      [ -z "$p" ] && continue
+      while IFS= read -r glob; do
+        glob="${glob#P:}"
+        case "$p" in "$glob"*) hit=1; break ;; esac
+      done <<<"$prefixes"
+      [ "$hit" = "1" ] && break
+    done <<<"$list"
+  fi
+  [ "$hit" = "1" ] || return 0
+  if ! command -v node >/dev/null 2>&1 || [ ! -f "$PRE_COMMIT_DIR/owned-path-gate.mjs" ]; then
+    echo "pre-commit-check: node or owned-path-gate.mjs unavailable - owned-path gate skipped" >&2
+    return 0
+  fi
+  # --state auto finds the live pipeline run working in this checkout, so an
+  # autopilot run's commit gets the policy of a run that asks nothing.
+  out="$(printf '%s' "$list" | node "$PRE_COMMIT_DIR/owned-path-gate.mjs" \
+    --repo "$top" --paths - --state auto 2>&1 >/dev/null)"
+  rc=$?
+  if [ "$rc" = "1" ]; then
+    printf '%s\n' "$out" >&2
+    echo "BLOCKED: the commit edits paths an automated account owns (see above)." >&2
+    return 2
+  fi
+  if [ "$rc" != "0" ]; then
+    echo "pre-commit-check: owned-path gate could not run (exit $rc) - skipped" >&2
+  fi
+  return 0
+}
+if [ "$IS_COMMIT_HOOK" = "1" ]; then
+  owned_path_gate || exit 2
+fi
+
 # Unattended commit: the verification gates must have passed for this HEAD.
 # The environment is the hook's own, inherited from the process the launcher
 # started, so the run cannot talk its way past it by editing its state. An

package/pipeline/scripts/repo-profile.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+
+/**
+ * @file repo-profile.mjs  -  derive, store, confirm and read the per-repo
+ * project profile (pipeline/schemas/repo-profile.schema.json).
+ *
+ * Subcommands (every one takes --repo <path>, default the current directory):
+ *   derive   [--bot-pattern <re>] [--history <n>] [--conventions <file>]
+ *            [--with-conventions <ios|android|backend|web>]
+ *              Print a draft profile. Reads the repo, writes nothing.
+ *   save     [--from <file|->] [--replace] [derive flags]
+ *              Store a profile. With --from, the file is the edited profile and
+ *              replaces the stored one as given: a manual value wins over a
+ *              confirmed one, and an entry left out is removed. Without it, a
+ *              fresh derive merges into the stored one (confirmed and manual
+ *              roles survive) unless --replace. Prints the path written.
+ *   confirm    Mark the stored profile confirmed. Exit 2 when there is none.
+ *   ensure   [--state <agent-state.json>] [--max-behind <n>] [derive flags]
+ *              Run-start entry point: derive when missing, re-derive when stale,
+ *              and say whether to ask the user. MULTI_AGENT_UNATTENDED=1 and
+ *              state.autopilot never ask. Prints {action, mode, policy, gatesActive,
+ *              path, persisted, writeError, confirmed, needsConfirmation, stale,
+ *              report}; a profile the OS would not let it save is used from
+ *              memory with persisted false.
+ *   show       Print the stored profile. Exit 2 when there is none.
+ *   get <field>
+ *              Print one field of the stored profile, e.g. commit.format.
+ *   resolve <field> [--state <agent-state.json>]
+ *              Print what a consumer may act on under the confidence policy:
+ *              {use, value, reason, ignored}.
+ *   report   [--state <agent-state.json>]
+ *              Print the run-report view: derived / confirmed / manual / used /
+ *              ignored fields.
+ *   path       Print where the profile is stored.
+ *
+ * Storage: ~/.claude/projects/<slug>/repo-profile.json, 0600, never inside the
+ * repo; an unattended run that cannot write there uses
+ * <unattended run root>/repo-profiles/<slug>/repo-profile.json. `--help` prints
+ * the usage. Exit codes: 0 ok; 1 usage or IO; 2 no stored profile.
+ *
+ * @module pipeline/scripts/repo-profile
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import {
+  confirmProfile,
+  consumptionReport,
+  deriveProfile,
+  ensureProfile,
+  loadProfile,
+  policyMode,
+  mergeProfiles,
+  profileMode,
+  profilePath,
+  readField,
+  resolveField,
+  saveProfile,
+} from "../lib/repo-profile.mjs";
+
+const USAGE = `Usage: repo-profile <subcommand> [--repo <path>] [flags]
+
+  derive   [--bot-pattern <re>] [--history <n>] [--conventions <file>]
+           [--with-conventions <ios|android|backend|web>]   print a draft, write nothing
+  save     [--from <file|->] [--replace] [derive flags]      store a profile; --from replaces
+  confirm                                                    mark the stored profile confirmed
+  ensure   [--state <file>] [--max-behind <n>] [derive flags]
+                                                             run-start: derive, re-derive, report
+  show                                                       print the stored profile
+  get <field>                                                print one field
+  resolve <field> [--state <file>]                           what a consumer may act on
+  report   [--state <file>]                                  derived / confirmed / used / ignored
+  path                                                       where the profile is stored
+
+Exit codes: 0 ok; 1 usage or IO; 2 no stored profile.
+`;
+
+const NAME = "repo-profile";
+const SUBCOMMANDS = [
+  "derive",
+  "save",
+  "confirm",
+  "ensure",
+  "show",
+  "get",
+  "resolve",
+  "report",
+  "path",
+];
+const VALUE_FLAGS = new Set([
+  "repo",
+  "bot-pattern",
+  "history",
+  "conventions",
+  "with-conventions",
+  "from",
+  "state",
+  "max-behind",
+]);
+
+function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (!a.startsWith("--")) {
+      positional.push(a);
+      continue;
+    }
+    const [k, inline] = a.slice(2).split(/=(.*)/s);
+    if (VALUE_FLAGS.has(k)) {
+      const v = inline ?? argv[(i += 1)];
+      if (v === undefined) throw new Error(`--${k} needs a value`);
+      flags[k] = v;
+    } else if (k === "replace") flags.replace = true;
+    else if (k === "help") flags.help = true;
+    else throw new Error(`unknown flag: --${k}`);
+  }
+  return { flags, positional };
+}
+
+function readJsonArg(src) {
+  const text = src === "-" ? readFileSync(0, "utf8") : readFileSync(src, "utf8");
+  return JSON.parse(text);
+}
+
+function conventionsFrom(flags, repo) {
+  if (flags.conventions) return readJsonArg(flags.conventions);
+  if (!flags["with-conventions"]) return null;
+  const here = dirname(fileURLToPath(import.meta.url));
+  const script = join(here, "..", "lib", "extract-conventions.sh");
+  if (!existsSync(script)) throw new Error("extract-conventions.sh not found next to this script");
+  const out = execFileSync("bash", [script, repo, flags["with-conventions"]], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return JSON.parse(out);
+}
+
+function positiveInt(flags, name) {
+  const n = Number(flags[name]);
+  if (!Number.isInteger(n) || n < 1) throw new Error(`--${name} must be a positive integer`);
+  return n;
+}
+
+function deriveOpts(flags, repo) {
+  const opts = {};
+  if (flags["bot-pattern"]) opts.botPattern = flags["bot-pattern"];
+  if (flags.history !== undefined) opts.historyWindow = positiveInt(flags, "history");
+  const conventions = conventionsFrom(flags, repo);
+  if (conventions) opts.conventions = conventions;
+  return opts;
+}
+
+function stateFrom(flags) {
+  if (!flags.state) return null;
+  try {
+    return JSON.parse(readFileSync(flags.state, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+const print = (v) =>
+  process.stdout.write(`${typeof v === "string" ? v : JSON.stringify(v, null, 2)}\n`);
+
+function missing(repo) {
+  process.stderr.write(
+    `${NAME}: no stored profile for ${repo}; run \`save\` or \`ensure\` first\n`,
+  );
+  process.exitCode = 2;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
+    process.stdout.write(USAGE);
+    return undefined;
+  }
+  const [sub, ...rest] = argv;
+  if (!SUBCOMMANDS.includes(sub)) {
+    throw new Error(`unknown subcommand: ${sub ?? "(none)"} (expected ${SUBCOMMANDS.join("|")})`);
+  }
+  const { flags, positional } = parseArgs(rest);
+  const repo = flags.repo || process.cwd();
+  const mode = () => profileMode(process.env, stateFrom(flags));
+  const stored = () => loadProfile(repo, { mode: mode() });
+
+  switch (sub) {
+    case "derive":
+      return print(deriveProfile(repo, deriveOpts(flags, repo)));
+    case "path":
+      return print(profilePath(repo));
+    case "save": {
+      if (flags.from) return print(saveProfile(repo, readJsonArg(flags.from)));
+      const next = deriveProfile(repo, deriveOpts(flags, repo));
+      return print(
+        saveProfile(repo, flags.replace ? next : mergeProfiles(loadProfile(repo), next)),
+      );
+    }
+    case "confirm": {
+      if (!loadProfile(repo)) return missing(repo);
+      confirmProfile(repo);
+      return print(profilePath(repo));
+    }
+    case "ensure": {
+      const opts = { state: stateFrom(flags), ...deriveOpts(flags, repo) };
+      if (flags["max-behind"] !== undefined) opts.maxBehind = positiveInt(flags, "max-behind");
+      const result = ensureProfile(repo, opts);
+      delete result.profile;
+      return print(result);
+    }
+    case "show": {
+      const p = stored();
+      return p ? print(p) : missing(repo);
+    }
+    case "get":
+    case "resolve": {
+      const field = positional[0];
+      if (!field) throw new Error(`${sub} needs a field, e.g. commit.format`);
+      const p = stored();
+      if (!p) return missing(repo);
+      if (sub === "resolve")
+        return print(resolveField(p, field, { mode: policyMode(process.env, stateFrom(flags)) }));
+      const v = readField(p, field);
+      if (v === undefined) throw new Error(`no field ${field} in the profile`);
+      return print(v);
+    }
+    case "report": {
+      const p = stored();
+      if (!p) return missing(repo);
+      return print(consumptionReport(p, { mode: policyMode(process.env, stateFrom(flags)) }));
+    }
+    default:
+      throw new Error(`unhandled subcommand: ${sub}`);
+  }
+}
+
+if (invokedDirectly(import.meta.url)) runMain(NAME, main);