@pavel.sommer/agiter 0.14.1-alpha.0 → 0.27.0-alpha.0

package/README.md

@@ -3,6 +3,23 @@
 A client-agnostic harness for spec-driven agentic development. The design is in
 [docs/design-recap.md](docs/design-recap.md).
 
+## The key idea: diverse points of view
+
+Every step of a run is done by separate agents, each starting with a fresh context: the author
+writes, the reviewer judges what was written against the input and the criteria, without the
+author's reasoning in view, so it has nothing to anchor on and no decision of its own to
+defend. A next round's author gets its version and the review, not its earlier train of
+thought. One long prompting session cannot give this: there a model judges its own work with
+the whole path to it still in context, like a person proofreading what he wrote a minute ago.
+
+Context diversity works with the same model too. Model diversity adds a second layer: a
+model's blind spots come from its training, and a fresh context does not remove them, a
+different model does. That is why each role has its own model profile
+(`agiter/config/.models.<role>.json`): a cheap author and a stronger reviewer of another family
+make a good pair.
+
+## How it works
+
 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).
@@ -36,7 +53,8 @@ project's `node_modules` linked in. The scope of a step is checked against what
 | `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 owner's documents stay his: any file a run did not write is an input in the owner's own form
+(with a frontmatter `type` it runs only with status `Active`; without one it runs as it is);
 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.
@@ -48,13 +66,41 @@ A project keeps everything in `agiter/`: `docs/<run>/` (the chain of each run),
 ## 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
+agiter/docs/<run>/.<run>.md                   the input, copied as it is (never changed; a dot file)
+agiter/docs/<run>/.<run>.draft.1.md           round 1 of create-draft:3 (a dot file)
+agiter/docs/<run>/.<run>.draft.1.report.md    its review: Block or Done, cumulative (a dot file)
+agiter/docs/<run>/.<run>.draft.2.md           round 2: input + draft.1 + its report
+agiter/docs/<run>/<run>.create-work.1.md      the record of create-work
+docs/<run>.draft.md                           the result of a step, published
+docs/<run>.draft.report.md                    the step's last report, published
+docs/<run>.decisions.md                       the decisions report, for the owner to answer
+docs/<run>.epic.E1.md                         an epic of create-epics, published
 ...
 ```
 
+Two kinds of output. Methodical artifacts (initiative, epic, draft, spec) are the documents a
+next run builds on: the result of each step (no review, or its report Done) is published to
+`docs/` (`agiter/config/.settings.json` `{ "docs": "<folder>" }` changes it), never over a
+file there, and agents never change them. Task records (`create-epics`, `create-work`,
+`create-tests`, `checks`) and the reports stay in `agiter/docs/<run>/` with every round; the versions of methodical
+artifacts there are dot files, so a client like Tolaria shows each document once (in `docs/`).
+Where the input does not say something, the models decide on their own and record it under
+"Decisions" (`[owner]` or `[author]`); at the end of a run the harness collects them into
+`docs/<run>.decisions.md` (beside the owner's documents), the owner's first, each with an `Answer:` line, so the
+answered file can be the input of a next run.
+A run on a document an earlier run wrote (an epic, a spec) gets that run's answered decisions in
+its prompt by itself: they override the document where they differ.
+Each document's frontmatter has the `model` that wrote it and the `cost` of that call.
+Every model call's cost and tokens come from the agent's JSON output (opencode `--format json`,
+claude `--output-format json`): `status` shows them per call and for the run, `run --list` per run.
+At the end of a run the file names in its documents become wikilinks (`[[name]]`, as Tolaria
+resolves them), to the notes in view: a version of the chain links to its published document.
+Their frontmatter gets Tolaria's relationships too: `belongs_to` and `related_to` as wikilinks.
+The owner's input file gets `has` (wikilinks to what runs made from it and keep), `model` (the
+models they used) and `cost` (their total).
+Frontmatter types are TitleCase and singular (`Spec`, `Epic`, `Report`, `Decision`); every task's
+record is `Pipeline`, its `task` (`create-epics`, `create-work`, …) tells which.
+
 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

package/bin/agiter.mjs

@@ -6,6 +6,7 @@
  */
 
 import fs from "node:fs";
+import { money, tokens } from "../src/usage.mjs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
@@ -23,7 +24,16 @@ function printRun(run) {
 	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}`);
+		console.log(`  ${String(s.step).padEnd(3)} ${s.task.padEnd(13)} ${(s.round ? `r${s.round}` : "").padEnd(4)}${s.role.padEnd(9)} ${what}${s.usage ? `  ${money(s.usage)}` : ""}`);
+	}
+	if (run.steps.some((s) => s.executor === "model" || s.executor === "fake")) {
+		const calls = run.steps.filter((s) => s.executor === "model");
+		const missing = calls.filter((s) => !s.usage).length;
+		console.log(`  cost: ${run.usage ? `${money(run.usage)} (${tokens(run.usage)})` : "no usage data"}${missing && run.usage ? `; ${missing} call(s) without usage data` : ""}`);
+	}
+	if (run.decisions) {
+		const d = run.decisions;
+		console.log(`  decisions: ${d.owner ?? 0} for you${d.review ? `, ${d.review} open from the review` : ""}, ${(d.owner ?? 0) + (d.review ?? 0) + (d.unmarked ?? 0) + (d.author ?? 0)} in all -> ${d.file}`);
 	}
 	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)`);
@@ -41,7 +51,7 @@ function patternOf(value, option, cmd) {
 	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}]` : ""}`;
+const runLine = (r) => `${local(r.created)}  ${r.status.padEnd(8)} ${duration(r.seconds).padStart(12)}  ${String(r.calls).padStart(3)} calls ${money(r.usage).padStart(9)}  ${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) {

package/defs/.agents.json

@@ -13,7 +13,12 @@
 		],
 		"message": [
 			"{message}"
-		]
+		],
+		"format": [
+			"--format",
+			"json"
+		],
+		"output": "opencode-json"
 	},
 	"claude": {
 		"title": "Claude Code, print mode; the prompt comes right after -p (the tool options take several values); the reviewer reads only",
@@ -43,6 +48,11 @@
 			"ANTHROPIC_AUTH_TOKEN",
 			"ANTHROPIC_API_KEY",
 			"ANTHROPIC_MODEL"
-		]
+		],
+		"format": [
+			"--output-format",
+			"json"
+		],
+		"output": "claude-json"
 	}
 }

package/defs/artifacts/checks.json

@@ -1,4 +1,10 @@
 {
+	"name": "Pipeline",
+	"shared": true,
+	"record": true,
+	"aliases": [
+		"Check"
+	],
 	"title": "Checks",
 	"summary": "The results of the project's required checks.",
 	"sections": [

package/defs/artifacts/create-epics.json

@@ -1,4 +1,11 @@
 {
+	"name": "Pipeline",
+	"shared": true,
+	"record": true,
+	"aliases": [
+		"epics",
+		"CreateEpic"
+	],
 	"title": "Breakdown into epics",
 	"summary": "The result of create-epics, not a methodical artifact: the input's functional areas and the epics that deliver them; each epic is in its own file (type epic).",
 	"sections": [

package/defs/artifacts/create-tests.json

@@ -0,0 +1,22 @@
+{
+	"name": "Pipeline",
+	"shared": true,
+	"record": true,
+	"aliases": [
+		"CreateTest"
+	],
+	"title": "Tests record",
+	"summary": "The record of create-tests, not a methodical artifact: the tests written for a spec.",
+	"sections": [
+		"Changes"
+	],
+	"criteria": [
+		"The tests cover every acceptance criterion of the spec.",
+		"Nothing outside the spec's scope changed."
+	],
+	"statuses": [
+		"Draft",
+		"Active",
+		"Done"
+	]
+}

package/defs/artifacts/{work.json → create-work.json}

@@ -1,6 +1,13 @@
 {
-	"title": "Work",
-	"summary": "The record of a change made to the code, tests included.",
+	"name": "Pipeline",
+	"shared": true,
+	"record": true,
+	"aliases": [
+		"work",
+		"CreateWork"
+	],
+	"title": "Work record",
+	"summary": "The record of create-work, not a methodical artifact: the change made to the code, tests included.",
 	"sections": [
 		"Changes"
 	],

package/defs/artifacts/decisions.json

@@ -0,0 +1,12 @@
+{
+	"name": "Decision",
+	"record": true,
+	"title": "Decisions",
+	"summary": "The record of a run's autonomous decisions: what the models decided that the input did not say, those that belong to the owner first, for him to answer.",
+	"sections": [],
+	"statuses": [
+		"Draft",
+		"Active",
+		"Done"
+	]
+}

package/defs/artifacts/report.json

@@ -1,4 +1,5 @@
 {
+	"record": true,
 	"title": "Report",
 	"summary": "The review of one version: its findings, cumulative over the rounds.",
 	"statuses": [

package/defs/tasks/create-tests.json

@@ -6,8 +6,7 @@
 		"spec",
 		"idea"
 	],
-	"output": "work",
-	"name": "tests",
+	"output": "create-tests",
 	"scope": [
 		"**"
 	]

package/defs/tasks/create-work.json

@@ -6,7 +6,7 @@
 		"spec",
 		"idea"
 	],
-	"output": "work",
+	"output": "create-work",
 	"scope": [
 		"**"
 	]

package/index.mjs

@@ -5,9 +5,9 @@
 
 export { loadDefs, lintDefs, PACKAGE_DEFS } from "./src/defs.mjs";
 export { resolvePipeline, planRun, parseToken } from "./src/pipeline.mjs";
-export { readDoc, readInput, validateDoc, parseReport } from "./src/artifacts.mjs";
+export { readDoc, readInput, validateDoc, parseReport, typeId, typeName } from "./src/artifacts.mjs";
 export { parseFrontmatter, formatFrontmatter } from "./src/frontmatter.mjs";
-export { planScenario, startRun, continueRun, finishRun, loadRun, listRuns, deleteRuns, readAudit, ISOLATION, modeOf } from "./src/engine.mjs";
+export { planScenario, startRun, continueRun, finishRun, loadRun, listRuns, deleteRuns, readAudit, ISOLATION, modeOf, docsDir } from "./src/engine.mjs";
 export { fakeExecutor } from "./src/fake.mjs";
 export { listRoles } from "./src/roles.mjs";
 export { initProject, findProjectRoot, isProject } from "./src/init.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pavel.sommer/agiter",
-	"version": "0.14.1-alpha.0",
+	"version": "0.27.0-alpha.0",
 	"description": "Client-agnostic harness for spec-driven agentic development.",
 	"keywords": [
 		"agentic",
@@ -36,7 +36,7 @@
 	},
 	"license": "UNLICENSED",
 	"scripts": {
-		"test": "node --test test/*.test.mjs"
+		"test": "node --test --import ./test/setup.mjs test/*.test.mjs"
 	},
 	"dependencies": {
 		"commander": "^15.1.0"

package/src/agents.mjs

@@ -2,9 +2,12 @@
  * The real model executor: runs an agent CLI for a step's author or reviewer.
  *
  * Agents are defined in the project's agiter/config/.agents.json (from the package's
- * defs/.agents.json): { id: { command, model (args added when a model is set; {model}), message (args
- * with {message}, added last; or {message} inside command, where the CLI needs it earlier),
- * roles (extra args per role, "*" for the others), dropEnv } }.
+ * defs/.agents.json): { id: { command, format (args for a structured output, after the
+ * command), output (its parser: opencode-json, claude-json; src/usage.mjs), model (args added
+ * when a model is set; {model}), message (args with {message}, added last; or {message} inside
+ * command, where the CLI needs it earlier), roles (extra args per role, "*" for the others),
+ * dropEnv } }. The project's definition of an agent is merged over the package's, so a key the
+ * package adds later (format, output) reaches a project whose file is older.
  *
  * The step's instructions are written to a prompt file in agiter/runs/<run>/steps/; the agent
  * gets one short message pointing to it. The author writes its result to the file the harness
@@ -21,6 +24,7 @@ import { AGENTS_FILE, CONFIG, resolveModels } from "./models.mjs";
 import { parseFrontmatter } from "./frontmatter.mjs";
 import { buildPrompt } from "./prompt.mjs";
 import { composeProject } from "./stack.mjs";
+import { addUsage, parserOf } from "./usage.mjs";
 
 const readJson = (file) => (fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8").replace(/^/, "")) : {});
 
@@ -30,8 +34,12 @@ const readJson = (file) => (fs.existsSync(file) ? JSON.parse(fs.readFileSync(fil
  * package's defs/.agents.json without a project or before the project has its file.
  */
 export function loadAgents(root) {
+	const base = readJson(path.join(PACKAGE_DEFS, AGENTS_FILE));
 	const own = root && path.join(root, CONFIG, AGENTS_FILE);
-	return readJson(own && fs.existsSync(own) ? own : path.join(PACKAGE_DEFS, AGENTS_FILE));
+	if (!own || !fs.existsSync(own)) return base;
+	const project = readJson(own);
+	// The project's keys win; a key only the package has (a newer one) is added.
+	return Object.fromEntries(Object.entries(project).map(([id, def]) => [id, base[id] && def && typeof def === "object" ? { ...base[id], ...def } : def]));
 }
 
 const fill = (args, values) => args.map((a) => a.replace(/\{(\w+)\}/g, (all, k) => values[k] ?? all));
@@ -40,27 +48,33 @@ const fill = (args, values) => args.map((a) => a.replace(/\{(\w+)\}/g, (all, k)
 export function argvOf(agent, role, model, message) {
 	const extra = agent.roles?.[role] ?? agent.roles?.["*"] ?? [];
 	const inCommand = agent.command.some((a) => a.includes("{message}"));
-	return [...fill(agent.command, { message }), ...(model ? fill(agent.model ?? [], { model }) : []), ...extra, ...(inCommand ? [] : fill(agent.message ?? ["{message}"], { message }))];
+	return [...fill(agent.command, { message }), ...(agent.format ?? []), ...(model ? fill(agent.model ?? [], { model }) : []), ...extra, ...(inCommand ? [] : fill(agent.message ?? ["{message}"], { message }))];
 }
 
 /** One argument for cmd.exe (spawn with shell on Windows, so .cmd shims run). */
 const quoteWin = (a) => (/^[\w@%+=:,./\\-]+$/.test(a) ? a : `"${a.replace(/(\\*)"/g, "$1$1\\\"").replace(/(\\+)$/, "$1$1")}"`);
 
 /**
- * Run argv in `cwd`: { exit, stdout, stderr, error, seconds } (killed after `timeoutMs`).
- * `onData(text, stream)` gets the output as it comes; `log` (a file) gets the command line at
- * once, then every piece of output as it comes (stderr lines marked "! "), then the exit.
+ * Run argv in `cwd`: { exit, stdout, stderr, error, seconds, text, usage } (killed after
+ * `timeoutMs`). `parser` (src/usage.mjs) turns a structured stdout into the text shown and the
+ * call's usage; stdout stays raw (and goes to `raw`, a file, when given). `onData(text,
+ * stream)` gets the shown output as it comes; `log` (a file) gets the command line at once,
+ * then the shown output as it comes (stderr lines marked "! "), then the exit.
  */
-export function spawnAgent(argv, { cwd, timeoutMs, env, onData, log }) {
+export function spawnAgent(argv, { cwd, timeoutMs, env, onData, log, raw, parser = parserOf(null) }) {
 	return new Promise((resolve) => {
 		const started = Date.now();
 		const win = process.platform === "win32";
 		const write = (text) => { if (log) try { fs.appendFileSync(log, text); } catch {} };
 		if (log) fs.writeFileSync(log, `$ ${argv.join(" ")}\n\n`);
+		if (raw) try { fs.writeFileSync(raw, ""); } catch {}
+		const show = (text) => { if (!text) return; write(text); try { onData?.(text, "stdout"); } catch {} };
 		const finish = (exit, error) => {
 			const seconds = (Date.now() - started) / 1000;
+			const parsed = parser.end();
+			show(parsed.shown);
 			write(`\n--- exit ${exit} in ${seconds.toFixed(1)} s${error ? `, ${error}` : ""}\n`);
-			resolve({ exit, stdout, stderr, error, seconds });
+			resolve({ exit, stdout, stderr, error, seconds, text: parsed.text, usage: parsed.usage, model: parsed.model ?? null });
 		};
 		let stdout = "";
 		let stderr = "";
@@ -75,7 +89,7 @@ export function spawnAgent(argv, { cwd, timeoutMs, env, onData, log }) {
 		}
 		child.stdout.setEncoding("utf8");
 		child.stderr.setEncoding("utf8");
-		child.stdout.on("data", (d) => { stdout += d; write(d); try { onData?.(d, "stdout"); } catch {} });
+		child.stdout.on("data", (d) => { stdout += d; if (raw) try { fs.appendFileSync(raw, d); } catch {} show(parser.feed(d)); });
 		child.stderr.on("data", (d) => { stderr += d; write(d.replace(/^(?=.)/gm, "! ")); try { onData?.(d, "stderr"); } catch {} });
 		const timer = setTimeout(() => { child.kill(); stderr += `\n[agiter: killed after ${timeoutMs / 60000} min]`; }, timeoutMs);
 		child.on("error", (e) => { clearTimeout(timer); finish(-1, e.message); });
@@ -119,7 +133,7 @@ export function agentExecutor(root) {
 		fs.mkdirSync(dir, { recursive: true });
 		const versionPath = ctx.role === "reviewer" ? ctx.version.file : ctx.output.file;
 		// Every call keeps its own files: the attempt is part of the name, nothing is overwritten.
-		const base = `${path.posix.basename(versionPath, ".md")}.${ctx.role}.${ctx.attempt}`;
+		const base = `${path.posix.basename(versionPath, ".md").replace(/^\./, "")}.${ctx.role}.${ctx.attempt}`;
 		const outFile = path.join(dir, `${base}.out.md`);
 		// An output with items (epics): the overview in outFile, each item in its own file in this folder.
 		const itemsDir = ctx.role !== "reviewer" && ctx.output?.items ? path.join(dir, `${base}.out`) : null;
@@ -137,14 +151,18 @@ export function agentExecutor(root) {
 		for (const model of models) {
 			const argv = argvOf(agent, ctx.role, model, message);
 			const log = path.join(dir, `${base}.${model ? model.replace(/[^\w.-]+/g, "_") : "default"}.log`);
-			const r = await spawnAgent(argv, { cwd: root, env, timeoutMs: (res.profile.timeoutMinutes ?? 30) * 60000, log, onData: ctx.onOutput });
+			// A structured output is kept raw next to the log (the log has the text shown).
+			const raw = agent.output ? log.replace(/\.log$/, ".jsonl") : null;
+			const r = await spawnAgent(argv, { cwd: root, env, timeoutMs: (res.profile.timeoutMinutes ?? 30) * 60000, log, raw, parser: parserOf(agent), onData: ctx.onOutput });
 			const label = `${res.profile.agent}${model ? ` ${model}` : ""}`;
-			const tried = { model, exit: r.exit, seconds: r.seconds, stdoutBytes: Buffer.byteLength(r.stdout), stderrBytes: Buffer.byteLength(r.stderr), log: rel(log) };
+			const tried = { model, exit: r.exit, seconds: r.seconds, stdoutBytes: Buffer.byteLength(r.stdout), stderrBytes: Buffer.byteLength(r.stderr), log: rel(log), usage: r.usage };
 			meta.tries.push(tried);
-			Object.assign(meta, { model, log: tried.log, exit: r.exit });
+			// What a call used counts also for the tries that failed: they were paid for.
+			// The profile's model, else the one the agent says answered (its default).
+			Object.assign(meta, { model: model ?? r.model, log: tried.log, exit: r.exit, usage: addUsage(meta.tries.map((t) => t.usage)) });
 			if (r.exit !== 0) { errors.push(`${label}: exit ${r.exit}${r.error ? ` (${r.error})` : ""}`); continue; }
 			if (ctx.role === "reviewer") {
-				const findings = findingsOf(r.stdout);
+				const findings = findingsOf(r.text ?? r.stdout);
 				if (findings) return { outcome: "ok", findings, meta: { ...meta, outputBytes: tried.stdoutBytes } };
 				errors.push(`${label}: no JSON findings in the answer`);
 				continue;

package/src/artifacts.mjs

@@ -2,7 +2,7 @@
  * Process artifacts: Markdown files, with frontmatter (type, title, status, …) or without it
  * (prose: type idea). A run keeps its whole chain in agiter/docs/<run>/:
  *
- *   <run>.md                     the run's input, copied as it is (never changed)
+ *   .<run>.md                    the run's input, copied as it is (never changed; a dot file)
  *   <run>.<name>.<round>.md      the version a step wrote in a round
  *   <run>.<name>.<round>.report.md   its review report (steps with :N)
  *   <run>.<name>.<round>.<id>.md the items of a version whose type has items (the epics of
@@ -57,12 +57,19 @@ export function h1Of(body) {
 // ── files of a run ──────────────────────────────────────────────────────────
 
 export const runFolder = (runId) => `${DOCS}/${runId}`;
-export const inputFile = (runId) => `${runFolder(runId)}/${runId}.md`;
-export const versionFile = (runId, name, round) => `${runFolder(runId)}/${runId}.${name}.${round}.md`;
-/** An item `id` (E1, …) of the version file `file`: <file without .md>.<id>.md. */
-export const itemFile = (file, id) => file.replace(/\.md$/i, `.${id}.md`);
-/** The report of an artifact file: the same path with .report.md. */
-export const reportFile = (file) => file.replace(/\.md$/i, ".report.md");
+/** The copy of the run's input: a dot file, so a client like Tolaria leaves it out (the owner has the original). */
+export const inputFile = (runId) => `${runFolder(runId)}/.${runId}.md`;
+/** A version a step wrote in a round; `hidden`: a dot file (a methodical artifact: its result is published to docs/). */
+export const versionFile = (runId, name, round, hidden = false) => `${runFolder(runId)}/${hidden ? "." : ""}${runId}.${name}.${round}.md`;
+const split = (file) => { const at = file.lastIndexOf("/") + 1; return [file.slice(0, at), file.slice(at).replace(/^\./, "").replace(/\.md$/i, "")]; };
+/** An item `id` (E1, …) of the version file `file`: <file without .md>.<id>.md; `hidden`: a dot file. */
+export const itemFile = (file, id, hidden = false) => { const [dir, base] = split(file); return `${dir}${hidden ? "." : ""}${base}.${id}.md`; };
+/**
+ * The report of an artifact file: the same name with .report.md. `hidden`: a dot file (runs since
+ * 0.26.0: every report of the chain; the step's last one is published to docs/); else never one
+ * (older runs kept every report in view, and a published document's report is beside it).
+ */
+export const reportFile = (file, hidden = false) => { const [dir, base] = split(file); return `${dir}${hidden ? "." : ""}${base}.report.md`; };
 
 /** { data, body, text } of the file at `rel` under `root` (data null for prose), or null. */
 export function readDoc(root, rel) {
@@ -82,6 +89,33 @@ export function writeDoc(root, rel, data, body) {
 /** The type of a document: its frontmatter type, idea for prose. */
 export const typeOf = (doc) => String(doc.data?.type ?? "idea").toLowerCase();
 
+// ── type names ──────────────────────────────────────────────────────────────
+// A definition's id is its file name (spec, create-work); the frontmatter carries its name, in
+// TitleCase and singular (Spec, Epic, Report: a client like Tolaria makes a view of
+// it and adds the plural). Reading takes the name, the id or an alias, in any case. The records
+// of tasks share one name, Pipeline ("shared": true); the frontmatter's `task` tells them apart.
+
+const squash = (s) => String(s ?? "").toLowerCase().replace(/[^a-z0-9]/g, "");
+const titleCase = (id) => String(id).split(/[^A-Za-z0-9]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join("");
+
+/** The frontmatter type of the definition `id` (its name, else its id in TitleCase). */
+export const typeName = (defs, id) => defs.artifacts.get(id)?.name ?? titleCase(id);
+
+/**
+ * The definition id of a frontmatter `type` (name, id or alias, any case), or its lower case
+ * when unknown. A name several definitions share (Pipeline) is resolved by `task`: the output
+ * of that task.
+ */
+export function typeId(defs, type, task = null) {
+	const key = squash(type);
+	const ids = [...defs.artifacts].filter(([id, def]) => [id, def.name, ...(def.aliases ?? [])].some((n) => n && squash(n) === key)).map(([id]) => id);
+	if (ids.length > 1 && task) {
+		const out = defs.tasks.get(String(task))?.output;
+		if (ids.includes(out)) return out;
+	}
+	return ids[0] ?? String(type ?? "").toLowerCase();
+}
+
 /** The status of the latest report of the artifact file `rel`, or null. */
 export const reportStatus = (root, rel) => readDoc(root, reportFile(rel))?.data?.status ?? null;
 
@@ -106,7 +140,7 @@ export function sectionsOf(body) {
 
 /** The problems of a document of `type` (`data` null for prose) against its definition. */
 export function validateDoc(defs, type, data, body, where) {
-	const def = defs.artifacts.get(String(type).toLowerCase());
+	const def = defs.artifacts.get(typeId(defs, type, data?.task));
 	if (!def) return [`${where}: unknown type "${type}"`];
 	const out = [];
 	if (data) {
@@ -226,9 +260,9 @@ export function readInput(defs, root, file) {
 	if (!text.trim()) return { error: `${file}: the file is empty` };
 	const { data, body } = parseFrontmatter(text);
 	if (!isHarnessDoc(data)) return { type: null, owner: true, data, body, text, status: null, blocked: false };
-	const type = String(data?.type ?? "idea").toLowerCase();
+	const type = typeId(defs, data?.type ?? "idea", data?.task);
 	if (!defs.artifacts.has(type)) return { error: `${file}: unknown artifact type "${type}"` };
-	const report = file.replace(/\.md$/i, ".report.md");
+	const report = reportFile(file);
 	const blocked = fs.existsSync(report) && parseFrontmatter(fs.readFileSync(report, "utf8")).data?.status === "Block";
 	return { type, data, body, text, status: data?.status ?? null, blocked };
 }

package/src/defs.mjs

@@ -56,6 +56,7 @@ export function lintDefs(defs) {
 	for (const a of defs.artifacts.values()) {
 		if (!Array.isArray(a.statuses) || !a.statuses.length) out.push(`artifact ${a.id}: statuses missing`);
 		if (a.sections !== undefined && !Array.isArray(a.sections)) out.push(`artifact ${a.id}: sections must be a list`);
+		if (a.name !== undefined && !/^[A-Z][A-Za-z0-9]*$/.test(a.name)) out.push(`artifact ${a.id}: name "${a.name}" must be TitleCase, letters and digits only`);
 		if (a.items !== undefined) {
 			const i = a.items;
 			if (!isObject(i) || !i.type || !i.prefix || !i.section) out.push(`artifact ${a.id}: items needs type, prefix and section`);
@@ -65,6 +66,17 @@ export function lintDefs(defs) {
 			}
 		}
 	}
+	// A name is one definition's, unless every definition that has it is "shared" and the
+	// output of a task (Pipeline: the frontmatter's task tells them apart).
+	const outputs = new Set([...defs.tasks.values()].map((t) => t.output));
+	const names = new Map();
+	for (const a of defs.artifacts.values()) for (const n of [a.name ?? a.id, ...(a.aliases ?? [])]) {
+		const k = String(n).toLowerCase().replace(/[^a-z0-9]/g, "");
+		const other = names.get(k);
+		if (other && other.id !== a.id && !(other.shared && a.shared && n === a.name)) out.push(`artifact ${a.id}: the name "${n}" is taken by ${other.id}`);
+		names.set(k, a);
+	}
+	for (const a of defs.artifacts.values()) if (a.shared && !outputs.has(a.id)) out.push(`artifact ${a.id}: a shared name needs the artifact to be a task's output`);
 	for (const a of defs.artifacts.values()) if (isObject(a.items) && a.items.type && !defs.artifacts.has(a.items.type)) out.push(`artifact ${a.id}: items.type "${a.items.type}" is unknown`);
 	if (!defs.artifacts.has("idea")) out.push("artifact idea is missing: it is the type of prose input");
 	if (!defs.artifacts.has("report")) out.push("artifact report is missing: reviews write it");