@pavel.sommer/agiter 0.0.0-stage → 0.14.1-alpha.0

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# agiter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A client-agnostic harness for spec-driven agentic development. The design is in
+[docs/design-recap.md](docs/design-recap.md).
+
+A run's pipeline is always given explicitly: a comma list of tokens, or a pipeline file
+(`*.json`, `{ "steps": [...] }`). A token is `task` (one round, no review) or `task:N` (at most
+N rounds; each round is a version and its review report).
+
+The project's tech stack lives in `agiter/config/.stack.json` (blocks and presets, `agiter
+stack --help`); the harness puts into each model's prompt only what its role needs from it, then the owner's
+`agiter/config/project.md` (structure, naming, scaffolding, rules) for every role. `--includeFile
+<file>` (repeatable) gives any file to every model call of a run. `create-epics` breaks an initiative down into its functional areas and writes one epic file per
+epic (`<run>.create-epics.<round>.E1.md`, …) next to an overview. `--lang <tag>` (an ISO tag: `cs`, `en`,
+`cs-CZ`, `en-US`, …) sets the language of the output; without it the models write in the language
+of the input. The headings the harness reads stay in English, and so do established technical
+terms and common anglicisms.
+
+Status: step 1 (inputs, artifacts, tasks, pipelines, the run engine, simulation) and a first
+real executor: `agiter run` calls the agent CLI of each role's model profile
+(`agiter/config/.models.<role>.json`, `agiter/config/.models.json`, and the agents in `agiter/config/.agents.json`, all copied from the package's defaults by `agiter init` or the first run). In a git repository
+a run works in the current checkout by default (no harness commits; the owner reviews and
+commits the changes), with `--isolation branch` on its own branch `agiter/<run>` with a commit
+per call, or with `--isolation worktree` in `agiter/.worktrees/<run>` on that branch with the
+project's `node_modules` linked in. The scope of a step is checked against what git sees, and
+`agiter finish [--merge]` ends a branch or worktree run.
+
+## Layout
+
+| Path | Content |
+| --- | --- |
+| `index.mjs` | the public API |
+| `bin/agiter.mjs` | the CLI on commander (`agiter --help`, `agiter <command> --help`) |
+| `sidecar.mjs` | JSON-RPC over stdio for long-lived clients (Far Manager) |
+| `src/` | the modules: definitions, pipelines, artifacts, engine, tools, log |
+| `defs/` | the package's artifact types, tasks, stack blocks and presets, default config |
+| `test/` | `npm test` (node:test, no dependencies) |
+
+The owner's documents stay his: any file a run did not write is an input in the owner's own form;
+the pipeline decides what it is (`create-epics`: an initiative), and its frontmatter, status and
+structure are not checked. A run is named after the input file without its leading timestamp and
+stamped in local time (`yyMMddHHmmss`); the titles of the outputs are the models' own.
+
+A project keeps everything in `agiter/`: `docs/<run>/` (the chain of each run), `runs/`,
+`logs/`, its own definitions (`artifacts/`, `tasks/`, merged over the package's) and
+`checks.json` (the required checks).
+
+## A run's files
+
+```text
+agiter/docs/<run>/<run>.md                    the input, copied as it is (never changed)
+agiter/docs/<run>/<run>.draft.1.md            round 1 of create-draft:3
+agiter/docs/<run>/<run>.draft.1.report.md     its review: Block or Done, cumulative
+agiter/docs/<run>/<run>.draft.2.md            round 2: input + draft.1 + its report
+...
+```
+
+A version is Active when another step follows and it has no review or its report is Done;
+otherwise Draft. A step takes only prose or an Active artifact whose latest report is not
+Block. The state of a run is its files: `agiter continue` walks the steps again and repeats
+nothing done.
+
+## Try it
+
+```text
+agiter list tasks
+agiter plan --pipeline "create-draft:3,create-spec:2,create-work,checks" --text "Add a login form"
+agiter simulate --pipeline "create-draft:3,create-spec:2,create-work" --text "Add a login form" --script script.json
+agiter continue --root <project printed by simulate>
+```
+
+A simulation script says what the fake model returns, per task, role and attempt:
+
+```json
+{
+	"steps": {
+		"create-draft#1/review": { "findings": [{ "text": "Problem unclear" }] },
+		"create-draft#2": { "responses": { "F-1": "fixed: Problem rewritten" } },
+		"create-work": { "changes": ["src/login.js"] }
+	}
+}
+```

package/bin/agiter.mjs

@@ -0,0 +1,417 @@
+#!/usr/bin/env node
+/**
+ * agiter: the command line, a thin layer over the API (index.mjs), parsed with commander.
+ * `agiter --help` and `agiter <command> --help` list the commands and their options.
+ * Exit codes: 0 done (or planned), 1 blocked, failed or invalid, 2 usage.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { Command, CommanderError, Option } from "commander";
+import * as api from "../index.mjs";
+import { logCli } from "../src/log.mjs";
+
+const USAGE = 2;
+
+function tokenOf(s) { return s.rounds ? `${s.task}:${s.rounds}` : s.task; }
+
+function printRun(run) {
+	const where = !run.git ? "" : (run.git.mode ?? "branch") === "none" ? "  (no isolation: the checkout itself)" : `  (${run.git.mode === "worktree" ? `worktree ${run.git.worktree}, ` : ""}branch ${run.git.branch}${run.finished ? `, finished${run.finished.merged ? ", merged" : ""}` : ""})`;
+	console.log(`run ${run.id}: ${run.status}${where}`);
+	console.log(`  pipeline ${run.pipeline.steps.map(tokenOf).join(",")}, input ${run.input.type}${run.lang ? `, output in ${run.lang}` : ""}`);
+	for (const s of run.steps) {
+		const what = s.outcome === "failed" ? `failed [${s.guard}] ${s.error}` : `${s.file ? path.posix.basename(s.file) : ""}${s.verdict ? ` ${s.verdict}` : ""}`;
+		console.log(`  ${String(s.step).padEnd(3)} ${s.task.padEnd(13)} ${(s.round ? `r${s.round}` : "").padEnd(4)}${s.role.padEnd(9)} ${what}`);
+	}
+	if (run.error) console.log(`  ${run.status} at step ${run.error.step} ${run.error.task}: ${run.error.message}\n  next: ${run.status === "blocked" ? "a new input with the answers, or " : ""}agiter continue ${run.id}`);
+	else if (run.status === "done" && run.git && (run.git.mode ?? "branch") !== "none" && !run.finished) console.log(`  next: agiter finish ${run.id} --merge (or without --merge to keep the branch)`);
+	else if (run.status === "done" && run.git?.mode === "none") console.log("  next: review the changes (git status, git diff) and commit them");
+}
+
+const pad2 = (n) => String(n).padStart(2, "0");
+/** A time in the machine's zone: yyyy-MM-dd HH:mm. */
+const local = (iso) => { const d = new Date(iso); return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())} ${pad2(d.getHours())}:${pad2(d.getMinutes())}`; };
+const duration = (s) => (s < 60 ? `${Math.round(s)} s` : s < 3600 ? `${Math.floor(s / 60)} min ${pad2(Math.round(s % 60))} s` : `${Math.floor(s / 3600)} h ${pad2(Math.floor((s % 3600) / 60))} min`);
+
+/** The RegExp of a --list or --delete value (true: no pattern), or a usage error. */
+function patternOf(value, option, cmd) {
+	if (typeof value !== "string") return null;
+	try { return new RegExp(value, "i"); } catch (e) { cmd.error(`error: --${option}: ${e.message}`, { exitCode: USAGE, code: "agiter.pattern" }); }
+}
+
+const runLine = (r) => `${local(r.created)}  ${r.status.padEnd(8)} ${duration(r.seconds).padStart(12)}  ${String(r.calls).padStart(3)} calls  ${r.id}  ${r.pipeline}${r.name ? `  "${r.name}"` : ""}${r.finished ? (r.finished.merged ? "  merged" : "  finished") : ""}${r.error ? `  [${r.error}]` : ""}`;
+
+/** run --list [pattern]: the runs, one per line. */
+function listRunsOf(opts, cmd) {
+	if (opts.failed || opts.done || opts.all || opts.yes) cmd.error(`error: options '--failed', '--done', '--all' and '--yes' belong to --delete`, { exitCode: USAGE, code: "agiter.delete" });
+	const pattern = patternOf(opts.list, "list", cmd);
+	const runs = api.listRuns(rootOf(opts), pattern, { order: opts.asc ? "asc" : "desc" });
+	print(opts, runs, () => {
+		for (const r of runs) console.log(runLine(r));
+		if (!runs.length) console.log(pattern ? `no run matches /${opts.list}/` : "no runs");
+	});
+}
+
+/** Ask a yes/no question on the terminal. */
+async function confirm(question) {
+	const { createInterface } = await import("node:readline/promises");
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	try { return /^y(es)?$/i.test((await rl.question(question)).trim()); } finally { rl.close(); }
+}
+
+/** run --delete --all [--yes]: every run and last.json, after two warnings. */
+async function deleteAllOf(opts, cmd, root) {
+	if (typeof opts.delete === "string" || opts.failed || opts.done) cmd.error("error: --all stands alone: no pattern, --failed or --done with it", { exitCode: USAGE, code: "agiter.all" });
+	const runs = api.listRuns(root);
+	const folders = fs.existsSync(path.join(root, "agiter", "runs")) ? fs.readdirSync(path.join(root, "agiter", "runs"), { withFileTypes: true }).filter((d) => d.isDirectory()).length : 0;
+	if (!folders) { print(opts, { deleted: [] }, () => console.log("no run to delete")); return; }
+	if (!opts.yes) {
+		if (!process.stdin.isTTY) cmd.error(`error: --delete --all would delete all ${folders} run(s); confirm with --yes when the input is not a terminal`, { exitCode: USAGE, code: "agiter.confirm" });
+		for (const r of runs) console.log(runLine(r));
+		if (folders > runs.length) console.log(`and ${folders - runs.length} broken run folder(s)`);
+		console.log(`\nWARNING: this deletes ALL ${folders} run(s) of ${root}: their records, audits, logs of calls and every artifact they made. It cannot be undone.`);
+		if (!(await confirm("Delete all runs? [y/N] "))) { console.log("nothing deleted"); process.exitCode = 1; return; }
+		const { createInterface } = await import("node:readline/promises");
+		const rl = createInterface({ input: process.stdin, output: process.stdout });
+		let typed;
+		try { typed = (await rl.question(`SECOND WARNING: type "delete all" to delete all ${folders} run(s): `)).trim(); } finally { rl.close(); }
+		if (typed !== "delete all") { console.log("nothing deleted"); process.exitCode = 1; return; }
+	}
+	logCli(root, process.argv.slice(2));
+	const { deleted } = api.deleteRuns(root, { all: true });
+	print(opts, { deleted }, () => console.log(`deleted all ${deleted.length} run(s); last.json cleared`));
+}
+
+/** run --delete [pattern] [--failed] [--done] [--yes]: delete runs, after showing them. */
+async function deleteRunsOf(opts, cmd) {
+	if (opts.asc || opts.desc) cmd.error(`error: options '--asc' and '--desc' belong to --list`, { exitCode: USAGE, code: "agiter.order" });
+	const root = rootOf(opts);
+	if (opts.all) return deleteAllOf(opts, cmd, root);
+	const pattern = patternOf(opts.delete, "delete", cmd);
+	const statuses = [...(opts.failed ? ["failed"] : []), ...(opts.done ? ["done"] : [])];
+	if (!pattern && !statuses.length) {
+		const all = api.listRuns(root);
+		const message = "--delete needs a restriction: a pattern, --failed or --done (a pattern \".\" selects every run)";
+		print(opts, { deleted: [], problems: [message], runs: all }, () => {
+			console.log(`${message}. The runs:`);
+			for (const r of all) console.log(`  ${runLine(r)}`);
+			if (!all.length) console.log("  no runs");
+		});
+		process.exitCode = USAGE;
+		return;
+	}
+	const runs = api.listRuns(root, pattern).filter((r) => !statuses.length || statuses.includes(r.status));
+	if (!runs.length) { print(opts, { deleted: [] }, () => console.log("no run to delete")); return; }
+	if (!opts.yes) {
+		if (!process.stdin.isTTY) cmd.error(`error: --delete would delete ${runs.length} run(s); confirm with --yes when the input is not a terminal`, { exitCode: USAGE, code: "agiter.confirm" });
+		for (const r of runs) console.log(runLine(r));
+		if (!(await confirm(`Delete these ${runs.length} run(s) with their artifacts? This cannot be undone. [y/N] `))) { console.log("nothing deleted"); process.exitCode = 1; return; }
+	}
+	logCli(root, process.argv.slice(2));
+	const { deleted } = api.deleteRuns(root, { pattern, statuses });
+	print(opts, { deleted }, () => console.log(`deleted ${deleted.length} run(s)${opts.yes ? `: ${deleted.map((r) => r.id).join(", ")}` : ""}`));
+}
+
+const clockOf = (iso) => { const d = new Date(iso); return `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`; };
+
+/**
+ * The live view of a run for the terminal: every event as it happens, and (unless quiet) the
+ * agents' output as it comes, indented under the call. None with --json (the result is JSON).
+ */
+function live(opts) {
+	if (opts.json) return {};
+	let pending = "";
+	const flush = () => { if (pending) { process.stdout.write(`    | ${pending}\n`); pending = ""; } };
+	const onEvent = (e) => {
+		flush();
+		console.log(`${clockOf(e.at)}  ${e.event.padEnd(13)} ${e.detail}`);
+	};
+	const onOutput = opts.quiet ? undefined : ({ text }) => {
+		const lines = (pending + text.replace(/\r\n?/g, "\n")).split("\n");
+		pending = lines.pop();
+		for (const l of lines) process.stdout.write(`    | ${l}\n`);
+	};
+	return { onEvent, onOutput, done: flush };
+}
+
+/** The --pipeline value: the shell may split an unquoted list ("a:2, b") into several items. */
+const pipelineOf = (items) => [].concat(items).join(" ");
+
+/** The git work tree's top of the current folder, or null. */
+function gitTop() {
+	const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8", windowsHide: true });
+	return r.status === 0 ? path.resolve(r.stdout.trim()) : null;
+}
+
+/** The project: --root, else found from the current folder (src/init.mjs findProjectRoot). */
+const rootOf = (opts) => (opts.root ? path.resolve(opts.root) : api.findProjectRoot(process.cwd(), gitTop()));
+const print = (opts, data, text) => { if (opts.json) console.log(JSON.stringify(data, null, "\t")); else text(); };
+const problems = (opts, r) => { print(opts, r, () => r.problems.forEach((p) => console.log(`problem: ${p}`))); return 1; };
+
+/** The options of a command that takes a scenario (`required`: --pipeline must be given). */
+function scenario(cmd, required = true) {
+	const pipeline = ["--pipeline <steps...>", "a pipeline file (*.json) or a comma list of task (one round, no review) and task:N (at most N rounds with review)"];
+	return (required ? cmd.requiredOption(...pipeline) : cmd.option(...pipeline))
+		.addOption(new Option("--input <file>", "the input file: prose, or an Active artifact").conflicts("text"))
+		.addOption(new Option("--text <text>", "the input as text").conflicts("input"))
+		.option("--name <name>", "the request's name (default: the input file's name; for text, each step's own heading)")
+		.option("--lang <tag>", "the language of the output, an ISO tag: cs, en, cs-CZ, en-US, … (default: the language of the input); the headings the harness reads stay in English")
+		.addOption(new Option("--isolation <mode>", "branch: a new branch agiter/<run> in this checkout; worktree: a separate checkout in agiter/.worktrees/<run> (node_modules linked). Without it: the checkout itself, no harness commits").choices(["branch", "worktree"]))
+		.option("--includeFile <file>", "a file every model call of the run gets whole in its prompt (repeat for more files); relative to the current folder, /<path> from the project's root", (v, prev) => [...prev, v], []);
+}
+
+const common = (cmd) => cmd.option("--root <dir>", "the project (default: found from the current folder: the project it is in)").option("--json", "the result as JSON");
+
+export function program() {
+	const prog = new Command("agiter")
+		.description("A harness for spec-driven agentic development.")
+		.showHelpAfterError("(agiter --help, or agiter <command> --help)")
+		.exitOverride();
+
+	common(prog.command("init").description("make the current folder (or --root) an agiter project: agiter/ with the default config in agiter/config/")).action((opts) => {
+		// The current folder, unless it is already inside a project (then that project).
+		const found = api.findProjectRoot(process.cwd());
+		const root = opts.root ? path.resolve(opts.root) : api.isProject(found) ? found : process.cwd();
+		const r = api.initProject({ root });
+		if (!opts.json && root !== process.cwd()) console.log(`project: ${root}`);
+		print(opts, r, () => {
+			for (const f of r.created) console.log(`created ${f}`);
+			for (const f of r.existed) console.log(`kept    ${f} (exists)`);
+		});
+	});
+
+	common(scenario(prog.command("plan").description("plan a scenario without running it"))).action((opts) => {
+		const r = api.planScenario({ root: rootOf(opts), pipeline: pipelineOf(opts.pipeline), input: opts.input, text: opts.text, name: opts.name, include: opts.includeFile, lang: opts.lang, isolation: opts.isolation ?? "none" });
+		print(opts, { ok: r.ok, problems: r.problems, name: r.name, lang: r.lang ?? null, include: r.include, plan: r.plan }, () => {
+			if (r.ok) console.log(`name: ${r.name ?? "(each step's own heading)"}`);
+			if (r.ok) console.log(`output language: ${r.lang ?? "(the input's)"}`);
+			if (r.include?.length) console.log(`files for every call: ${r.include.join(", ")}`);
+			for (const s of r.plan ?? []) console.log(`  ${String(s.n).padEnd(3)} ${tokenOf(s).padEnd(16)} ${(s.input ?? "-").padEnd(6)} -> ${s.output.padEnd(7)} <run>.${s.name}.<round>.md${s.rounds ? " + .report.md" : ""}`);
+			for (const p of r.problems) console.log(`problem: ${p}`);
+		});
+		process.exitCode = r.ok ? 0 : 1;
+	});
+
+	const runner = (simulate) => async (opts) => {
+		let root = rootOf(opts);
+		let simulation = null;
+		if (simulate) {
+			let script = {};
+			if (opts.script) { try { script = JSON.parse(fs.readFileSync(path.resolve(opts.script), "utf8")); } catch (e) { throw new CommanderError(USAGE, "agiter.script", `--script: ${e.message}`); } }
+			simulation = { script };
+			// Without --root: the project the current folder is in, else a new temporary project.
+			if (!opts.root && !api.isProject(root)) { root = fs.mkdtempSync(path.join(os.tmpdir(), "agiter-sim-")); fs.mkdirSync(path.join(root, "agiter")); }
+		}
+		logCli(root, process.argv.slice(2));
+		const view = live(opts);
+		if ((simulate || root !== process.cwd()) && !opts.json) console.log(`project: ${root}`);
+		const r = await api.startRun({ root, pipeline: pipelineOf(opts.pipeline), input: opts.input, text: opts.text, name: opts.name, include: opts.includeFile, lang: opts.lang, isolation: opts.isolation ?? "none", simulation, fresh: Boolean(opts.new), audit: Boolean(opts.audit), onEvent: view.onEvent, onOutput: view.onOutput });
+		view.done?.();
+		if (!r.ok) { process.exitCode = problems(opts, r); return; }
+		print(opts, { root, resumed: r.resumed, run: r.run }, () => {
+			if (r.resumed) console.log("resumed the unfinished run of the same scenario (--new starts a new one)");
+			console.log("");
+			printRun(r.run);
+		});
+		process.exitCode = r.run.status === "done" ? 0 : 1;
+	};
+	const runOptions = (cmd) => cmd
+		.option("--new", "start a new run even when an unfinished run of the same scenario exists")
+		.option("--audit", "record every executor call in agiter/runs/<run>/audit.jsonl")
+		.option("--quiet", "show only the harness's events, not the agents' output");
+
+	const run = runOptions(scenario(prog.command("run").description("run a scenario (an unfinished run of the same scenario is resumed), or list the runs with --list"), false))
+		.addOption(new Option("--list [pattern]", "list the runs (newest first; --asc for oldest first); a regular expression keeps those whose id, name or pipeline it matches (case-insensitive)")
+			.conflicts(["pipeline", "input", "text", "name", "new", "audit", "quiet", "includeFile", "isolation", "lang"]))
+		.addOption(new Option("--delete [pattern]", "delete runs (their records and artifacts) whose id, name or pipeline the regular expression matches, narrowed by --failed and --done; one restriction at least (\".\" for every run)")
+			.conflicts(["pipeline", "input", "text", "name", "new", "audit", "quiet", "includeFile", "isolation", "lang", "list"]))
+		.option("--failed", "with --delete: only failed runs (with --done: failed or done ones)")
+		.option("--done", "with --delete: only done runs (with --failed: failed or done ones)")
+		.option("--all", "with --delete: delete every run and clear last.json (asks twice)")
+		.option("--yes", "with --delete: do not ask (needed when the input is not a terminal)")
+		.addOption(new Option("--asc", "with --list: oldest first").conflicts(["desc"]))
+		.addOption(new Option("--desc", "with --list: newest first (the default)").conflicts(["asc"]));
+	common(run).action(async (opts, cmd) => {
+		if (opts.list !== undefined) return listRunsOf(opts, cmd);
+		if (opts.delete !== undefined) return deleteRunsOf(opts, cmd);
+		for (const o of ["failed", "done", "all", "yes"]) if (opts[o]) cmd.error(`error: option '--${o}' belongs to --delete`, { exitCode: USAGE, code: "agiter.delete" });
+		if (opts.asc || opts.desc) cmd.error(`error: option '--${opts.asc ? "asc" : "desc"}' belongs to --list`, { exitCode: USAGE, code: "agiter.order" });
+		if (!opts.pipeline) cmd.error("error: required option '--pipeline <steps...>' not specified (or --list)", { exitCode: USAGE, code: "agiter.pipeline" });
+		return runner(false)(opts);
+	});
+	common(runOptions(scenario(prog.command("simulate").description("run a scenario with a scripted fake model (in the project the current folder is in, or --root; outside a project in a new temporary one)")))
+		.option("--script <file>", "what the fake model returns, per task, role and attempt")).action(runner(true));
+
+	common(prog.command("continue").argument("[run]", "the run id", "last").description("walk a run's steps again from its files")
+		.option("--audit", "turn the run's audit on from now")
+		.option("--quiet", "show only the harness's events, not the agents' output")).action(async (id, opts) => {
+		const root = rootOf(opts);
+		logCli(root, process.argv.slice(2));
+		const view = live(opts);
+		if (root !== process.cwd() && !opts.json) console.log(`project: ${root}`);
+		const r = await api.continueRun({ root, run: id, audit: Boolean(opts.audit), onEvent: view.onEvent, onOutput: view.onOutput });
+		view.done?.();
+		if (!r.ok) { process.exitCode = problems(opts, r); return; }
+		print(opts, { run: r.run }, () => { console.log(""); printRun(r.run); });
+		process.exitCode = r.run.status === "done" ? 0 : 1;
+	});
+
+	common(prog.command("finish").argument("[run]", "the run id", "last").description("end a git run: back to the branch it started from, with --merge of its branch (a done run) or without")
+		.option("--merge", "merge the run's branch into the branch it started from (no fast-forward); a worktree is removed after")).action((id, opts) => {
+		const root = rootOf(opts);
+		logCli(root, process.argv.slice(2));
+		const r = api.finishRun({ root, run: id, merge: Boolean(opts.merge) });
+		if (!r.ok) { process.exitCode = problems(opts, r); return; }
+		const back = r.run.git.baseBranch ?? `detached ${r.run.git.base.slice(0, 10)}`;
+		print(opts, { run: r.run, merged: r.merged }, () => console.log(r.merged ? `merged ${r.run.git.branch} into ${back}` : `back on ${back}; ${r.run.git.branch} is kept (finish --merge later, or delete it)`));
+	});
+
+	common(prog.command("status").argument("[run]", "the run id", "last").description("show a run")).action((id, opts) => {
+		const root = rootOf(opts);
+		const run = api.loadRun(root, id);
+		if (!run) { console.error(`agiter: no run ${id} in ${root}`); process.exitCode = 1; return; }
+		print(opts, run, () => printRun(run));
+	});
+
+	common(prog.command("runs").description("list the runs, newest first")).action((opts) => {
+		const runs = api.listRuns(rootOf(opts));
+		print(opts, runs, () => runs.forEach((r) => console.log(`${r.id}  ${r.status.padEnd(8)} ${r.pipeline}`)));
+	});
+
+	common(prog.command("audit").argument("[run]", "the run id", "last").description("show a run's audit")).action((id, opts) => {
+		const root = rootOf(opts);
+		const run = api.loadRun(root, id);
+		if (!run) { console.error(`agiter: no run ${id} in ${root}`); process.exitCode = 1; return; }
+		const lines = api.readAudit(root, run.id);
+		if (!run.audit && !lines.length) { console.error(`agiter: run ${run.id} has no audit (it ran without --audit)`); process.exitCode = 1; return; }
+		print(opts, lines, () => {
+			console.log(`audit of ${run.id} (${run.status}): ${lines.length} call(s), ${lines.reduce((t, a) => t + a.seconds, 0).toFixed(1)} s`);
+			for (const a of lines) {
+				const who = a.agent ? `${a.agent}${a.model ? ` ${a.model}` : ""}` : a.executor;
+				const end = a.outcome === "ok" ? (a.verdict ? `${a.verdict} (${a.blocking} blocking)` : "ok") : `${a.outcome} [${a.guard}]`;
+				console.log(`  ${String(a.step).padEnd(3)} ${a.task.padEnd(13)} ${(a.round ? `r${a.round}` : "").padEnd(4)}${a.role.padEnd(9)} ${who.padEnd(46)} ${a.seconds.toFixed(1).padStart(7)} s  ${end}`);
+			}
+		});
+	});
+
+	common(prog.command("list").addArgument(new Command().createArgument("<kind>", "what to list").choices(["artifacts", "tasks"])).description("list the definitions")).action((kind, opts) => {
+		const defs = api.loadDefs(rootOf(opts));
+		const items = [...defs[kind].values()];
+		print(opts, { problems: defs.problems, items }, () => {
+			for (const d of items) {
+				const detail = kind === "tasks" ? `${[].concat(d.input).join("|")} -> ${d.output} [${d.executor}]${d.rounds ? ` rounds ${d.rounds}` : ""}` : d.statuses.join(" / ");
+				console.log(`${d.id.padEnd(17)} ${detail}${d.layer === "project" ? "  (project)" : ""}`);
+			}
+			for (const p of defs.problems) console.log(`problem: ${p}`);
+		});
+		process.exitCode = defs.problems.length ? 1 : 0;
+	});
+
+	common(prog.command("roles").description("the roles (for now only --list)").option("--list", "list the roles and their tasks")).action((opts, cmd) => {
+		if (!opts.list) cmd.error("error: roles: only --list is supported for now", { exitCode: USAGE, code: "agiter.roles" });
+		const defs = api.loadDefs(rootOf(opts));
+		const roles = api.listRoles(defs);
+		print(opts, { problems: defs.problems, roles }, () => {
+			for (const r of roles) console.log(`${r.role.padEnd(10)} ${[...r.tasks, ...(r.reviewsRounds ? ["every round of a step with :N"] : [])].join(", ")}`);
+			for (const p of defs.problems) console.log(`problem: ${p}`);
+		});
+		process.exitCode = defs.problems.length ? 1 : 0;
+	});
+
+	const stackCmd = prog.command("stack").description("the project's tech stack (agiter/config/.stack.json): list blocks, show what a role gets, change the selection")
+		.addOption(new Option("--list", "the blocks and presets of the package and the project").conflicts(["show", "add", "remove", "preset", "detect"]))
+		.addOption(new Option("--show [role]", "what the models get about the project (stack and project.md): everything, or only what a role gets").conflicts(["add", "remove", "preset", "detect"]))
+		.addOption(new Option("--add <blocks...>", "add blocks (id or id@version)").conflicts(["remove", "preset", "detect"]))
+		.addOption(new Option("--remove <blocks...>", "remove blocks").conflicts(["preset", "detect"]))
+		.addOption(new Option("--preset <id>", "start the selection from a preset (only when the project has none)").conflicts(["detect"]))
+		.option("--detect", "start the selection from the blocks the project's files show (only when the project has none)");
+	common(stackCmd).action((opts, cmd) => {
+		const root = rootOf(opts);
+		const { blocks, presets, problems: loadProblems } = api.loadBlocks(root);
+		if (opts.list) {
+			print(opts, { blocks: [...blocks.values()].map(({ id, title, kind, summary, layer }) => ({ id, title, kind, summary, layer })), presets: [...presets.values()].map(({ id, title, blocks: b }) => ({ id, title, blocks: b })), problems: loadProblems }, () => {
+				for (const b of [...blocks.values()].sort((a, c) => a.kind.localeCompare(c.kind) || a.id.localeCompare(c.id))) console.log(`${b.kind.padEnd(12)} ${b.id.padEnd(20)} ${b.summary ?? b.title}${b.layer === "project" ? "  (project)" : ""}`);
+				console.log("\npresets:");
+				for (const p of presets.values()) console.log(`  ${p.id.padEnd(18)} ${p.blocks.map((x) => (typeof x === "string" ? x : x.id)).join(", ")}`);
+			});
+			return;
+		}
+		const current = api.readStack(root);
+		if (current?.error) { process.exitCode = problems(opts, { problems: [current.error] }); return; }
+		const save = (stack, what) => {
+			const r = api.resolveSelection(blocks, stack.blocks);
+			if (r.problems.length) { process.exitCode = problems(opts, { problems: r.problems.map((p) => `stack: ${p}`) }); return; }
+			api.writeStack(root, stack);
+			print(opts, { stack, added: r.added, suggestions: r.suggestions }, () => {
+				console.log(`${what}: agiter/config/.stack.json`);
+				console.log(`blocks: ${[...r.chosen.values()].map((e) => (e.block.versions ? `${e.block.id}@${e.version}` : e.block.id)).join(", ")}`);
+				for (const a of r.added) console.log(`  ${a.id} added as required by ${a.by}`);
+				if (r.suggestions.length) console.log(`suggested: ${r.suggestions.map((x) => `${x.id} (by ${x.by})`).join(", ")}`);
+			});
+		};
+		if (opts.preset || opts.detect) {
+			if (current) cmd.error("error: the project has a stack already (agiter/config/.stack.json): change it with --add and --remove", { exitCode: USAGE, code: "agiter.stack" });
+			if (opts.preset) {
+				const p = presets.get(opts.preset);
+				if (!p) cmd.error(`error: no preset ${opts.preset} (agiter stack --list)`, { exitCode: USAGE, code: "agiter.stack" });
+				return save({ preset: p.id, blocks: [...p.blocks] }, `created from the preset ${p.id}`);
+			}
+			const found = api.detectBlocks(blocks, root);
+			if (!found.length) { print(opts, { detected: [] }, () => console.log("no block detected: start with --preset or --add")); process.exitCode = 1; return; }
+			if (!opts.json) for (const f of found) console.log(`detected ${f.id}: ${f.evidence.join("; ")}`);
+			return save({ blocks: found.map((f) => f.id) }, "created from the project's files");
+		}
+		if (opts.add || opts.remove) {
+			const stack = current ?? { blocks: [] };
+			const id = (e) => (typeof e === "string" ? e : e.id);
+			for (const x of opts.add ?? []) {
+				const [bid, version] = x.split("@");
+				stack.blocks = stack.blocks.filter((e) => id(e) !== bid);
+				stack.blocks.push(version ? { id: bid, version } : bid);
+			}
+			for (const x of opts.remove ?? []) {
+				if (!stack.blocks.some((e) => id(e) === x)) cmd.error(`error: ${x} is not in the selection`, { exitCode: USAGE, code: "agiter.stack" });
+				stack.blocks = stack.blocks.filter((e) => id(e) !== x);
+			}
+			return save(stack, current ? "updated" : "created");
+		}
+		const role = typeof opts.show === "string" ? opts.show : null;
+		const composed = api.composeProject(root, role);
+		if (!composed) { print(opts, { stack: null }, () => console.log("the project has no stack yet (agiter stack --preset <id>, --detect or --add <blocks...>) and no agiter/config/project.md")); return; }
+		print(opts, { role, ...composed }, () => {
+			console.log(role ? `# What the ${role} gets` : "# The project's stack (every section)");
+			console.log("");
+			console.log(composed.text);
+			console.log(`\n(${Buffer.byteLength(composed.text)} bytes in every ${role ? `${role} ` : ""}prompt)`);
+			for (const p of composed.problems) console.log(`problem: ${p}`);
+		});
+		process.exitCode = composed.problems.length ? 1 : 0;
+	});
+
+	prog.command("sidecar").description("serve the API as JSON-RPC over stdio (for Far Manager)").action(async () => {
+		const { serve } = await import("../sidecar.mjs");
+		await serve();
+	});
+
+	return prog;
+}
+
+/** Run the command line `argv` (without node and the script); the exit code. */
+export async function main(argv) {
+	const prog = program();
+	if (!argv.length) { prog.outputHelp(); return 0; }
+	try {
+		await prog.parseAsync(argv, { from: "user" });
+		return process.exitCode ?? 0;
+	} catch (e) {
+		if (!(e instanceof CommanderError)) throw e;
+		if (["commander.helpDisplayed", "commander.help", "commander.version"].includes(e.code)) return 0;
+		if (e.code === "agiter.script") console.error(`agiter: ${e.message}`);
+		return USAGE;
+	}
+}
+
+const self = process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(new URL(import.meta.url));
+if (self) process.exitCode = await main(process.argv.slice(2));

package/defs/.agents.json

@@ -0,0 +1,48 @@
+{
+	"opencode": {
+		"title": "opencode run (as in Methodology's default profile)",
+		"command": [
+			"opencode",
+			"run",
+			"--auto",
+			"--thinking"
+		],
+		"model": [
+			"-m",
+			"{model}"
+		],
+		"message": [
+			"{message}"
+		]
+	},
+	"claude": {
+		"title": "Claude Code, print mode; the prompt comes right after -p (the tool options take several values); the reviewer reads only",
+		"command": [
+			"claude",
+			"-p",
+			"{message}"
+		],
+		"model": [
+			"--model",
+			"{model}"
+		],
+		"roles": {
+			"reviewer": [
+				"--allowedTools",
+				"Read,Grep,Glob",
+				"--disallowedTools",
+				"Write,Edit,NotebookEdit"
+			],
+			"*": [
+				"--allowedTools",
+				"Read,Grep,Glob,Write,Edit"
+			]
+		},
+		"dropEnv": [
+			"ANTHROPIC_BASE_URL",
+			"ANTHROPIC_AUTH_TOKEN",
+			"ANTHROPIC_API_KEY",
+			"ANTHROPIC_MODEL"
+		]
+	}
+}

package/defs/.models.architect.json

@@ -0,0 +1,9 @@
+{
+	"default": {
+		"agent": "claude",
+		"models": [],
+		"select": "availableFirst",
+		"effort": "high",
+		"timeoutMinutes": 30
+	}
+}

package/defs/.models.author.json

@@ -0,0 +1,11 @@
+{
+	"default": {
+		"agent": "opencode",
+		"models": [
+			"openrouter/deepseek/deepseek-v4.1-flash"
+		],
+		"select": "availableFirst",
+		"effort": "high",
+		"timeoutMinutes": 30
+	}
+}

package/defs/.models.drafter.json

@@ -0,0 +1,11 @@
+{
+	"default": {
+		"agent": "opencode",
+		"models": [
+			"openrouter/deepseek/deepseek-v4.1-flash"
+		],
+		"select": "availableFirst",
+		"effort": "high",
+		"timeoutMinutes": 30
+	}
+}

package/defs/.models.json

@@ -0,0 +1,11 @@
+{
+	"default": {
+		"agent": "opencode",
+		"models": [
+			"openrouter/deepseek/deepseek-v4.1-flash"
+		],
+		"select": "availableFirst",
+		"effort": "high",
+		"timeoutMinutes": 30
+	}
+}

package/defs/.models.reviewer.json

@@ -0,0 +1,9 @@
+{
+	"default": {
+		"agent": "claude",
+		"models": [],
+		"select": "availableFirst",
+		"effort": "high",
+		"timeoutMinutes": 30
+	}
+}

package/defs/.models.worker.json

@@ -0,0 +1,11 @@
+{
+	"default": {
+		"agent": "opencode",
+		"models": [
+			"openrouter/deepseek/deepseek-v4.1-flash"
+		],
+		"select": "availableFirst",
+		"effort": "high",
+		"timeoutMinutes": 60
+	}
+}

package/defs/artifacts/checks.json

@@ -0,0 +1,12 @@
+{
+	"title": "Checks",
+	"summary": "The results of the project's required checks.",
+	"sections": [
+		"Results"
+	],
+	"statuses": [
+		"Draft",
+		"Active",
+		"Done"
+	]
+}