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

package/README.md

@@ -7,11 +7,23 @@ A run's pipeline is always given explicitly: a comma list of tokens, or a pipeli
 (`*.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`, copied from the package's defaults on the first run; agents in `defs/agents.json`). In a git repository
-every run works on its own branch `agiter/<run>`, the harness commits every call, the scope
-of a step is checked against what git sees, and `agiter finish [--merge]` ends the run.
+(`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
 
@@ -21,20 +33,25 @@ of a step is checked against what git sees, and `agiter finish [--merge]` ends t
 | `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 and tasks |
+| `defs/` | the package's artifact types, tasks, stack blocks and presets, default config |
 | `test/` | `npm test` (node:test, no dependencies) |
 
-A project keeps everything in `.agiter/`: `docs/<run>/` (the chain of each run), `runs/`,
+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
+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
 ...
 ```
 

package/bin/agiter.mjs

@@ -8,6 +8,7 @@
 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";
@@ -17,14 +18,16 @@ const USAGE = 2;
 function tokenOf(s) { return s.rounds ? `${s.task}:${s.rounds}` : s.task; }
 
 function printRun(run) {
-	console.log(`run ${run.id}: ${run.status}${run.git ? `  (branch ${run.git.branch}${run.finished ? `, finished${run.finished.merged ? ", merged" : ""}` : ""})` : ""}`);
-	console.log(`  pipeline ${run.pipeline.steps.map(tokenOf).join(",")}, input ${run.input.type}`);
+	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.finished) console.log(`  next: agiter finish ${run.id} --merge (or without --merge to keep the branch)`);
+	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");
@@ -62,7 +65,7 @@ async function confirm(question) {
 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;
+	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" });
@@ -136,7 +139,14 @@ function live(opts) {
 /** The --pipeline value: the shell may split an unquoted list ("a:2, b") into several items. */
 const pipelineOf = (items) => [].concat(items).join(" ");
 
-const rootOf = (opts) => path.resolve(opts.root ?? ".");
+/** 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; };
 
@@ -146,10 +156,13 @@ function scenario(cmd, required = true) {
 	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("--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: the current folder)").option("--json", "the result as JSON");
+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")
@@ -157,8 +170,12 @@ export function program() {
 		.showHelpAfterError("(agiter --help, or agiter <command> --help)")
 		.exitOverride();
 
-	common(prog.command("init").description("make the folder an agiter project: .agiter/ with the default model config in .agiter/config/")).action((opts) => {
-		const r = api.initProject({ root: rootOf(opts) });
+	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)`);
@@ -166,9 +183,11 @@ export function program() {
 	});
 
 	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 });
-		print(opts, { ok: r.ok, problems: r.problems, name: r.name, plan: r.plan }, () => {
+		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}`);
 		});
@@ -182,12 +201,13 @@ export function program() {
 			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 };
-			if (!opts.root) { root = fs.mkdtempSync(path.join(os.tmpdir(), "agiter-sim-")); fs.mkdirSync(path.join(root, ".agiter")); }
+			// 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 && !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, simulation, fresh: Boolean(opts.new), audit: Boolean(opts.audit), onEvent: view.onEvent, onOutput: view.onOutput });
+		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 }, () => {
@@ -199,14 +219,14 @@ export function program() {
 	};
 	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("--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"]))
+			.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", "list"]))
+			.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)")
@@ -221,7 +241,7 @@ export function program() {
 		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 (a new temporary project without --root)")))
+	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")
@@ -230,6 +250,7 @@ export function program() {
 		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; }
@@ -238,7 +259,7 @@ export function program() {
 	});
 
 	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)")).action((id, opts) => {
+		.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) });
@@ -299,6 +320,76 @@ export function program() {
 		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();

package/defs/artifacts/create-epics.json

@@ -0,0 +1,25 @@
+{
+	"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": [
+		"Functional areas",
+		"Epics"
+	],
+	"criteria": [
+		"Every functional area of the input is listed, and every one is covered by exactly one epic.",
+		"The epics do not overlap: nothing is in the scope of two epics.",
+		"Each epic can be delivered and checked on its own; where one needs another, its scope says which.",
+		"There are as many epics as the input needs: no epic for a trivial part, no epic that bundles unrelated areas.",
+		"Nothing outside the input is added."
+	],
+	"items": {
+		"type": "epic",
+		"prefix": "E",
+		"section": "Epics"
+	},
+	"statuses": [
+		"Draft",
+		"Active",
+		"Done"
+	]
+}

package/defs/blocks/ado-net.json

@@ -0,0 +1,130 @@
+{
+	"id": "ado-net",
+	"title": "ADO.NET (Microsoft.Data.SqlClient)",
+	"kind": "library",
+	"slot": "dotnet-data-access",
+	"detect": {
+		"text": [
+			{
+				"files": "**/*.csproj",
+				"match": "Microsoft\\.Data\\.SqlClient"
+			},
+			{
+				"files": "**/packages.config",
+				"match": "id=\"Microsoft\\.Data\\.SqlClient\""
+			}
+		]
+	},
+	"summary": "explicit SQL and row mapping, no ORM",
+	"requires": [
+		{
+			"anyOf": [
+				"dotnet",
+				"dotnet-framework"
+			]
+		},
+		"sql-server"
+	],
+	"fragments": {
+		"stack": [
+			{
+				"id": "ado.stack",
+				"text": "Direct ADO.NET through `Microsoft.Data.SqlClient`. No EF Core, Dapper or reflection-based object mappers.",
+				"unless": [
+					"dotnet-framework"
+				]
+			},
+			{
+				"id": "ado.stack-framework",
+				"text": "Direct ADO.NET through the SqlClient the project references (`System.Data.SqlClient` or `Microsoft.Data.SqlClient`). No Entity Framework, Dapper or reflection-based object mappers.",
+				"when": [
+					"dotnet-framework"
+				]
+			}
+		],
+		"rules": [
+			{
+				"id": "ado.explicit",
+				"group": "ADO.NET and SQL Server",
+				"text": "Keep SQL and row mapping explicit. Parameterize values; set `SqlDbType` and relevant size, precision and scale deliberately."
+			},
+			{
+				"id": "ado.async",
+				"group": "ADO.NET and SQL Server",
+				"text": "Use `OpenAsync`, `ExecuteReaderAsync`/`ExecuteNonQueryAsync` and `ReadAsync` where available, propagating the request's `CancellationToken`."
+			},
+			{
+				"id": "ado.dispose",
+				"group": "ADO.NET and SQL Server",
+				"text": "Dispose connections, commands and readers deterministically; use asynchronous disposal where supported. Use connection pooling rather than a shared mutable `SqlConnection` singleton."
+			},
+			{
+				"id": "ado.typed",
+				"group": "ADO.NET and SQL Server",
+				"text": "Use typed reader access and handle `DBNull` explicitly. Select required columns; avoid `DataSet`/`DataTable` unless the named spec requires them."
+			},
+			{
+				"id": "ado.transactions",
+				"group": "ADO.NET and SQL Server",
+				"text": "Define transaction boundaries, isolation, timeout and concurrency behavior in the spec. Pass the transaction to every participating command."
+			},
+			{
+				"id": "ado.retry",
+				"group": "ADO.NET and SQL Server",
+				"text": "Do not retry non-idempotent writes without an explicit idempotency strategy. Cancellation does not prove a transaction was rolled back; test the chosen behavior."
+			},
+			{
+				"id": "ado.scripts",
+				"group": "ADO.NET and SQL Server",
+				"text": "Store schema changes as ordered SQL scripts with verification."
+			},
+			{
+				"id": "ado.aot",
+				"group": "Native AOT",
+				"text": "Validate the exact SqlClient version, native dependencies and database authentication mode in the published artifact. Do not infer full compatibility from target framework support alone.",
+				"when": [
+					"native-aot"
+				]
+			}
+		],
+		"paths": [
+			{
+				"id": "ado.database",
+				"path": "`database/`",
+				"content": "Ordered SQL scripts and schema documentation"
+			}
+		],
+		"scopes": [
+			{
+				"id": "ado.schema",
+				"scope": "schema-only change",
+				"folder": "`docs/spec/database/`"
+			}
+		],
+		"commands": [
+			{
+				"id": "ado.integration",
+				"purpose": "SQL integration tests",
+				"command": "`{{option.integration}}`",
+				"after": "unit tests"
+			}
+		],
+		"environment": [
+			{
+				"id": "ado.sqlclient",
+				"setting": "SqlClient",
+				"value": "`<pinned version and required native/authentication dependencies>`"
+			}
+		],
+		"notes": {
+			"commands": "SQL integration and native acceptance commands are mandatory for changes exercising those paths; do not report them as passed when credentials, SQL Server or the native toolchain are absent."
+		}
+	},
+	"options": {
+		"integration": {
+			"title": "the isolated-SQL-Server test command",
+			"type": "text",
+			"default": "<existing isolated-SQL-Server test command>"
+		}
+	}
+}

package/defs/blocks/agent-browser.json

@@ -0,0 +1,59 @@
+{
+	"id": "agent-browser",
+	"title": "agent-browser",
+	"kind": "tool",
+	"summary": "interactive acceptance in a real browser",
+	"requires": [
+		"browser"
+	],
+	"fragments": {
+		"stack": [
+			{
+				"id": "ab.stack",
+				"text": "Browser automation: the existing `agent-browser` CLI with the installed Google Chrome."
+			}
+		],
+		"rules": [
+			{
+				"id": "ab.help",
+				"group": "Dependencies and tools",
+				"text": "`agent-browser`: run `agent-browser --help` before first use. Never report that visual verification is impossible; report what was run and what could not be driven, as `not run` with the reason."
+			}
+		],
+		"commands": [
+			{
+				"id": "ab.acceptance",
+				"purpose": "interactive acceptance tool",
+				"command": "`agent-browser`"
+			},
+			{
+				"id": "ab.clipboard",
+				"purpose": "clipboard access",
+				"command": "`node tools/grant-clipboard.mjs --origin <app url> --session <name>` after opening the session",
+				"after": "interactive acceptance tool"
+			},
+			{
+				"id": "ab.readiness",
+				"purpose": "browser readiness",
+				"command": "`agent-browser --version`",
+				"after": "interactive acceptance tool"
+			}
+		],
+		"environment": [
+			{
+				"id": "ab.version",
+				"setting": "agent-browser",
+				"value": "`<existing executable path and version>`"
+			}
+		],
+		"notes": {
+			"environment": "Use a separate browser session or ephemeral context per run; do not reuse the user's personal profile."
+		}
+	},
+	"files": [
+		{
+			"from": "templates/stacks/html-javascript/tools/grant-clipboard.mjs",
+			"to": "tools/grant-clipboard.mjs"
+		}
+	]
+}