@afokapu/atdd-bun 0.1.0

package/planner-schemas/wmbt.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "WMBT (What Must Be True) Schema",
+  "description": "Schema for What Must Be True statements that define measurable outcomes",
+  "type": "object",
+  "$comment": "This schema is a file-level gate in @afokapu/atdd-bun. WMBT correctness beyond local shape remains the responsibility of Bun cross-artifact validators. The `acceptances` property describes the real embedded-acceptance shape carried by WMBT files; its definition is resolved from acceptance.schema.json.",
+  "required": ["urn", "step", "direction", "dimension", "object_of_control", "lens"],
+  "additionalProperties": false,
+  "properties": {
+    "urn": {
+      "type": "string",
+      "pattern": "^wmbt:[a-z][a-z0-9-]*:[DLPCEMYRK][0-9]{3}$",
+      "description": "WMBT URN: wmbt:{wagon}:{step_coded_id} (e.g., wmbt:burn-timebank:E001) - step-coded sequence"
+    },
+    "step": {
+      "type": "string",
+      "enum": ["define", "locate", "prepare", "confirm", "execute", "monitor", "modify", "resolve", "conclude"],
+      "description": "JTBD decomposition step indicating where in the job flow this outcome matters"
+    },
+    "direction": {
+      "type": "string",
+      "enum": ["minimize", "maximize", "increase", "decrease"],
+      "description": "Optimization direction indicating how to improve the outcome"
+    },
+    "dimension": {
+      "type": "string",
+      "enum": ["time", "effort", "likelihood", "frequency", "quantity", "financial value"],
+      "description": "Measurement dimension - exactly one per WMBT to maintain focus"
+    },
+    "object_of_control": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "minLength": 2,
+      "description": "Descriptive of what is being controlled or measured"
+    },
+    "context_clarifier": {
+      "type": "string",
+      "pattern": "^[a-z].{1,250}$",
+      "description": "Detailed situational phrase specifying when/where/how this applies (one line maximum)"
+    },
+    "lens": {
+      "type": "string",
+      "pattern": "^(functional|emotional|social)\\.[a-z][a-z0-9-]*$",
+      "description": "Specific lens aspect reference (e.g., functional.efficiency, emotional.trust, social.belong)"
+    },
+    "statement": {
+      "type": "string",
+      "minLength": 10,
+      "description": "Human-readable statement: direction + dimension + object_of_control + context_clarifier"
+    },
+
+    "acceptances": {
+      "type": "array",
+      "description": "Embedded acceptances for this WMBT. They use the lighter acceptance.schema.json definitions.embedded_acceptance shape: identity/harness/given/when/then with `abstract` fields plus metadata.author/created, and no standalone root acceptance requirement.",
+      "items": {
+        "$ref": "acceptance.schema.json#/definitions/embedded_acceptance"
+      }
+    },
+
+    "appendices": {
+      "type": "array",
+      "description": "Supplementary files specific to this WMBT scenario",
+      "items": {
+        "$ref": "appendix.schema.json#/definitions/appendix_reference"
+      }
+    }
+  }
+}

package/src/ci.ts

@@ -0,0 +1,9 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const root = resolve(import.meta.dir, "..");
+const template = join(root, "templates/github/atdd-bun.yml");
+const version = (await Bun.file(join(root, "package.json")).json() as { version: string }).version;
+export async function ciInit(repo = process.cwd(), replace = false) { const output = join(repo, ".github/workflows/atdd-bun.yml"); if (existsSync(output) && !replace) return { ok: false, message: `${output} exists; use --replace` }; await mkdir(join(repo, ".github/workflows"), { recursive: true }); await writeFile(output, (await readFile(template, "utf8")).replace("{{VERSION}}", version)); return { ok: true, message: output }; }
+export async function ciStatus(repo = process.cwd()) { const output = join(repo, ".github/workflows/atdd-bun.yml"); return { ok: existsSync(output), message: output }; }

package/src/cli.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env bun
+import { enforce, profileNames, type Profile } from "./enforce";
+import { finishWorktree, hookEvents, hooksStatus, installHooks, runHook, startWorktree, uninstallHooks, worktreeStatus } from "./hooks";
+import { ciInit, ciStatus } from "./ci";
+import { releaseCheck } from "./release";
+import { initializeRepository } from "./setup";
+
+const args = process.argv.slice(2);
+const usage = {
+  command: "atdd-bun",
+  usage: [
+    "atdd-bun [profile ...] [--root <path>]",
+    "atdd-bun init [--replace]",
+    "atdd-bun hooks <install|uninstall|status> [--replace]",
+    "atdd-bun worktree <start|finish|status>",
+    "atdd-bun ci <init|status> [--replace]",
+    "atdd-bun release check",
+  ],
+  profiles: profileNames,
+  note: "Use a profile directly, for example: atdd-bun planner. --profile planner remains supported for compatibility.",
+};
+
+function printHelp(): void {
+  if (args.includes("--json")) { console.log(JSON.stringify(usage, null, 2)); return; }
+  console.log([
+    "ATdd Bun enforcement",
+    "",
+    "Usage:",
+    ...usage.usage.map(line => "  " + line),
+    "",
+    "Profiles: " + profileNames.join(", "),
+    "",
+    usage.note,
+  ].join("\n"));
+}
+
+function fail(message: string): never {
+  console.error([message, "Run atdd-bun help for available commands and profiles."].join("\n"));
+  process.exit(1);
+}
+
+if (args[0] === "help" || args[0] === "--help" || args[0] === "-h") {
+  printHelp();
+  process.exit(0);
+}
+if (args[0] === "hooks") {
+  const result = args[1] === "install" ? await installHooks(process.cwd(), args.includes("--replace")) : args[1] === "uninstall" ? await uninstallHooks() : args[1] === "status" ? await hooksStatus() : fail("hooks requires install, uninstall, or status");
+  console[result.ok ? "log" : "error"](result.message); process.exit(result.ok ? 0 : 1);
+}
+if (args[0] === "init") {
+  const result = await initializeRepository(process.cwd(), args.includes("--replace"));
+  console[result.ok ? "log" : "error"](result.message); process.exit(result.ok ? 0 : 1);
+}
+if (args[0] === "hook") {
+  if (!hookEvents.includes(args[1] as typeof hookEvents[number])) fail("unknown hook event: " + (args[1] ?? "(missing)"));
+  const result = await runHook(args[1] as typeof hookEvents[number], process.cwd(), args.slice(2), await new Response(Bun.stdin.stream()).text());
+  if (result.message) console[result.ok ? "log" : "error"](result.message); process.exit(result.ok ? 0 : 1);
+}
+if (args[0] === "worktree") {
+  const result = args[1] === "start" ? await startWorktree(process.cwd(), args[2] ?? "") : args[1] === "finish" ? await finishWorktree(process.cwd(), args.includes("--delete-branch")) : args[1] === "status" ? await worktreeStatus(process.cwd()) : fail("worktree requires start, finish, or status");
+  console[result.ok ? "log" : "error"](result.message); process.exit(result.ok ? 0 : 1);
+}
+if (args[0] === "ci") {
+  const result = args[1] === "init" ? await ciInit(process.cwd(), args.includes("--replace")) : args[1] === "status" ? await ciStatus() : fail("ci requires init or status");
+  console[result.ok ? "log" : "error"](result.message); process.exit(result.ok ? 0 : 1);
+}
+if (args[0] === "release") {
+  if (args[1] !== "check") fail("release requires check");
+  const result = await releaseCheck(); console[result.ok ? "log" : "error"](result.message); process.exit(result.ok ? 0 : 1);
+}
+
+const valueAfter = (flag: string) => args[args.indexOf(flag) + 1];
+const root = args.includes("--root") ? valueAfter("--root") : process.cwd();
+if (args.includes("--root") && !root) fail("--root requires a path");
+const positional: string[] = [];
+for (let index = 0; index < args.length; index += 1) {
+  const arg = args[index];
+  if (arg === "--root" || arg === "--profile") { index += 1; continue; }
+  if (!arg.startsWith("-")) positional.push(arg);
+}
+const profileValue = args.includes("--profile") ? valueAfter("--profile") : undefined;
+if (args.includes("--profile") && !profileValue) fail("--profile requires one or more comma-separated profiles");
+const requested = profileValue ? profileValue.split(",").filter(Boolean) : positional.length ? positional : ["all"];
+const invalid = requested.find(profile => !profileNames.includes(profile as Profile));
+if (invalid) fail("unknown command or profile: " + invalid);
+const violations = await enforce({ root, profiles: requested as Profile[] });
+for (const violation of violations) {
+  console.error([violation.file, violation.line, violation.col].join(":") + " " + violation.rule_id + " — " + violation.evidence);
+}
+if (violations.length) console.error("\nUse the rule ID and evidence above to correct the affected artifact. Run atdd-bun help for commands and profiles.");
+process.exitCode = violations.length ? 1 : 0;

package/src/docs-capability.ts

@@ -0,0 +1,156 @@
+import { existsSync } from "node:fs";
+import { mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, isAbsolute, join, relative, resolve } from "node:path";
+
+export const DOC_RULE_IDS = [
+  "planner.docs.asciidoc-only", "planner.docs.identity-required", "planner.docs.doc-id-unique",
+  "planner.docs.graph-target-resolves", "planner.docs.area-index-required", "planner.docs.adr-registry-derived",
+  "planner.docs.artifact-path-shape", "planner.docs.undeclared-change", "planner.docs.reference-integrity",
+] as const;
+export type DocumentationRuleId = typeof DOC_RULE_IDS[number];
+export type DocumentationViolation = { rule_id: DocumentationRuleId; file: string; line: number; col: number; evidence: string; source_line: string };
+export type DocumentationDeclaration = { impact?: "change" | "none" | string; artifacts?: Array<{ action?: string; path?: string; from?: string }> };
+export type DocumentationCheck = { verdict: "PASS" | "FAIL" | "COULD_NOT_CHECK" | "NOT_APPLICABLE"; findings: Array<DocumentationViolation | { rule_id: null; where: string; message: string }>; checked: string[] };
+export type DocumentationRender = { findings: DocumentationViolation[]; couldNotCheck?: string };
+
+const DOCS = "docs";
+const DIST = "docs/dist";
+const AREAS = ["docs", "docs/purpose", "docs/architecture", "docs/architecture/decisions", "docs/delivery", "docs/archive"];
+const VERBS = ["decides", "supersedes", "implements", "depends-on"];
+const ADR_DIR = "docs/architecture/decisions";
+const ADR_INDEX = `${ADR_DIR}/index.adoc`;
+type Document = { path: string; text: string; attrs: Record<string, string>; lines: Record<string, number> };
+
+const generated = (path: string) => path === DIST || path.startsWith(`${DIST}/`);
+const lineAt = (text: string, line: number) => text.split(/\r?\n/)[line - 1] ?? "";
+const violation = (rule_id: DocumentationRuleId, file: string, line: number, evidence: string, source_line = ""): DocumentationViolation => ({ rule_id, file, line, col: 1, evidence, source_line });
+
+async function walk(root: string, suffix: string): Promise<string[]> {
+  if (!existsSync(root)) return [];
+  const entries = await readdir(root, { withFileTypes: true });
+  return (await Promise.all(entries.map(async entry => {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) return walk(path, suffix);
+    return entry.isFile() && entry.name.endsWith(suffix) ? [path] : [];
+  }))).flat().sort();
+}
+
+export function parseAttributes(text: string): { attrs: Record<string, string>; lines: Record<string, number> } {
+  const attrs: Record<string, string> = {}, lines: Record<string, number> = {};
+  let sawAttribute = false;
+  for (const [index, line] of text.split(/\r?\n/).entries()) {
+    const match = line.match(/^:([A-Za-z][A-Za-z0-9_-]*):[ \t]*(.*?)[ \t]*$/);
+    if (match) { sawAttribute = true; if (!(match[1] in attrs)) { attrs[match[1]] = match[2]; lines[match[1]] = index + 1; } continue; }
+    if (!line.trim()) { if (sawAttribute) break; continue; }
+    if (line.startsWith("=")) continue;
+    break;
+  }
+  return { attrs, lines };
+}
+
+async function documents(root: string): Promise<Document[]> {
+  const paths = await walk(join(root, DOCS), ".adoc");
+  return Promise.all(paths.filter(path => !generated(relative(root, path).replaceAll("\\", "/"))).map(async path => {
+    const text = await readFile(path, "utf8"); const parsed = parseAttributes(text);
+    return { path: relative(root, path).replaceAll("\\", "/"), text, ...parsed };
+  }));
+}
+
+function graphViolations(docs: Document[]): DocumentationViolation[] {
+  const ids = new Set(docs.map(d => d.attrs["doc-id"]).filter(Boolean)); const output: DocumentationViolation[] = [];
+  for (const doc of docs) for (const verb of VERBS) for (const target of (doc.attrs[verb] ?? "").split(",").map(x => x.trim()).filter(Boolean)) {
+    if (!ids.has(target)) output.push(violation("planner.docs.graph-target-resolves", doc.path, doc.lines[verb] ?? 1, `${doc.attrs["doc-id"]} :${verb}: ${target} — no document declares the doc-id ${JSON.stringify(target)}. The target was REPORTED and no node was created for it; declare the target document, or fix the reference.`, lineAt(doc.text, doc.lines[verb] ?? 1)));
+  }
+  return output;
+}
+
+function registryText(text: string): string {
+  const regions = [...text.matchAll(/^\/\/\s*BEGIN GENERATED:\s*(?<name>[a-z0-9-]*).*?^\/\/\s*END GENERATED:\s*\k<name>\b/gms)].map(m => m[0]);
+  const named = regions.filter(region => region.split("\n", 1)[0].includes("adr-register"));
+  return named.length ? named.join("\n") : text.replace(/^----\s*$.*?^----\s*$/gms, "");
+}
+
+function adrViolations(docs: Document[]): DocumentationViolation[] {
+  const adr = docs.filter(d => d.path.startsWith(`${ADR_DIR}/`) && /^adr-\d{8}-\d{3}-[a-z0-9][a-z0-9-]*\.adoc$/.test(basename(d.path)));
+  const output: DocumentationViolation[] = [];
+  for (const doc of adr.filter(d => !d.attrs["adr-id"])) output.push(violation("planner.docs.adr-registry-derived", doc.path, 1, `${doc.path} is named as an ADR but declares no :adr-id:, so it cannot be projected into the registry and no rule can see it. Declare :adr-id: matching its filename.`));
+  const derived = new Set(adr.map(d => d.attrs["adr-id"]).filter(Boolean));
+  const registry = docs.find(d => d.path === ADR_INDEX);
+  if (!registry) return derived.size ? [...output, violation("planner.docs.adr-registry-derived", ADR_INDEX, 1, `${derived.size} ADR(s) exist and there is no registry to project them into: ${[...derived].sort().join(", ")}.`)] : output;
+  const listed = new Set(registryText(registry.text).match(/\bADR-\d{8}-\d{3}\b/g) ?? []);
+  if (registry.attrs["adr-id"] && !derived.has(registry.attrs["adr-id"])) listed.delete(registry.attrs["adr-id"]);
+  const missing = [...derived].filter(id => !listed.has(id)).sort(), stale = [...listed].filter(id => !derived.has(id)).sort();
+  if (missing.length || stale.length) output.push(violation("planner.docs.adr-registry-derived", ADR_INDEX, 1, `the ADR registry has drifted from the :decides: edges it is projected from — ${[missing.length && `missing from the registry: ${missing.join(", ")}`, stale.length && `listed but no such ADR exists: ${stale.join(", ")}`].filter(Boolean).join("; ")}. Regenerate it; do not type the entry.`));
+  return output;
+}
+
+export async function scanDocumentation(root: string): Promise<DocumentationViolation[]> {
+  const absolute = resolve(root), docs = await documents(absolute), output: DocumentationViolation[] = [];
+  for (const path of await walk(join(absolute, DOCS), ".md")) { const file = relative(absolute, path).replaceAll("\\", "/"); if (!generated(file)) output.push(violation("planner.docs.asciidoc-only", file, 1, `authored markdown beneath docs/: ${file}. AsciiDoc is the only authored format; convert it, and convert a historical document INTO docs/archive/ rather than into a current area.`, lineAt(await readFile(path, "utf8"), 1))); }
+  for (const doc of docs) { const missing = ["doc-id", "status"].filter(name => !doc.attrs[name]); if (missing.length) output.push(violation("planner.docs.identity-required", doc.path, 1, `document declares no ${missing.map(name => `:${name}:`).join(" and no ")}. Identity and currency are both required: an id with no status is a node whose currency is unknown, a status with no id is a claim nothing can reference.`, lineAt(doc.text, 1))); }
+  const byId = new Map<string, Document[]>(); for (const doc of docs) if (doc.attrs["doc-id"]) byId.set(doc.attrs["doc-id"], [...(byId.get(doc.attrs["doc-id"]) ?? []), doc]);
+  for (const [id, group] of byId) if (group.length > 1) for (const doc of group) { const line = doc.lines["doc-id"] ?? 1; output.push(violation("planner.docs.doc-id-unique", doc.path, line, `doc-id ${JSON.stringify(id)} is declared by ${group.length} documents: ${group.map(d => d.path).join(", ")}. Resolution needs exactly one target per id.`, lineAt(doc.text, line))); }
+  output.push(...graphViolations(docs));
+  for (const area of AREAS) if (existsSync(join(absolute, area)) && !existsSync(join(absolute, area, "index.adoc"))) output.push(violation("planner.docs.area-index-required", `${area}/index.adoc`, 1, `canonical area ${area}/ exists and carries no index.adoc. The rendered site cannot navigate into an area with no entry point.`));
+  output.push(...adrViolations(docs));
+  return output;
+}
+
+export function declarationViolations(declaration: DocumentationDeclaration | null, changeSet?: string[]): DocumentationViolation[] {
+  if (!declaration) return [];
+  const artifacts = Array.isArray(declaration.artifacts) ? declaration.artifacts : []; const output: DocumentationViolation[] = [];
+  if (declaration.impact !== "change" && declaration.impact !== "none") output.push(violation("planner.docs.artifact-path-shape", "<declaration>", 1, `declaration carries impact=${JSON.stringify(declaration.impact)}; the two total forms are ["change", "none"]. A malformed declaration is reported, never treated as nothing-to-check.`));
+  for (const [index, artifact] of artifacts.entries()) { const path = artifact.path ?? "", problems: string[] = []; if (!path) problems.push("declares no path"); else { if (!path.startsWith("docs/")) problems.push(`path ${JSON.stringify(path)} is outside the canonical tree (must begin "docs/")`); if (!path.endsWith(".adoc")) problems.push(`path ${JSON.stringify(path)} is not AsciiDoc (must end ".adoc")`); if (artifact.action === "archive" && !path.startsWith("docs/archive/")) problems.push(`archive destination ${JSON.stringify(path)} is outside "docs/archive/" — archiving must preserve history, never promote it into a current area`); } if (problems.length) output.push(violation("planner.docs.artifact-path-shape", path || "<declaration>", 1, `declared artifact[${index}] (action: ${artifact.action || "unset"}): ${problems.join("; ")}`)); }
+  if (changeSet) { const covered = new Set(artifacts.flatMap(a => [a.path, a.from]).filter((p): p is string => Boolean(p))); for (const path of [...new Set(changeSet)].sort()) if (path.startsWith("docs/") && !generated(path) && !covered.has(path)) output.push(violation("planner.docs.undeclared-change", path, 1, `the change set touches ${path} and no declared artifact covers it. Declare it at RATIFY; if the change was not planned, the declaration was wrong at RATIFY and re-ratifying is the honest correction.`)); }
+  return output;
+}
+
+export function parseAsciidoctorDiagnostics(stderr: string, root: string): DocumentationRender {
+  const findings: DocumentationViolation[] = [], noise: string[] = [];
+  for (const raw of stderr.split(/\r?\n/)) {
+    const text = raw.trim(); if (!text) continue;
+    const match = text.match(/^asciidoctor:\s*(?:WARNING|ERROR|FAILED):\s*([^:]+?):\s*(?:line\s*(\d+):\s*)?(.*)$/);
+    if (!match) { noise.push(text); continue; }
+    const reported = match[1].trim(); let file = reported;
+    if (isAbsolute(reported)) file = relative(root, reported).replaceAll("\\", "/");
+    // A bare basename remains the renderer's evidence; we never invent a target.
+    findings.push(violation("planner.docs.reference-integrity", file, Number(match[2] ?? 1), `asciidoctor: ${match[3]}`));
+  }
+  return noise.length ? { findings, couldNotCheck: `asciidoctor emitted output it could not attribute to a document, so part of the corpus was not validated: ${noise.join("; ")}` } : { findings };
+}
+
+export async function renderDocumentation(root: string, timeoutMs = 120_000): Promise<DocumentationRender> {
+  const docsRoot = join(root, DOCS);
+  if (!existsSync(docsRoot)) return { findings: [], couldNotCheck: "docs/ is not a readable directory" };
+  const tool = Bun.which("asciidoctor");
+  if (!tool) return { findings: [], couldNotCheck: "asciidoctor is not installed, so the corpus was not rendered and reference integrity could not be established. This is COULD_NOT_CHECK and it BLOCKS; install the toolchain rather than suppressing it." };
+  const sources = (await walk(docsRoot, ".adoc")).filter(path => !relative(docsRoot, path).replaceAll("\\", "/").startsWith("dist/"));
+  if (!sources.length) return { findings: [] };
+  const output = await mkdtemp(join(tmpdir(), "atdd-docs-render-"));
+  try {
+    const child = Bun.spawn({ cmd: [tool, "--failure-level", "WARN", "--base-dir", docsRoot, "--destination-dir", output, ...sources], stdout: "pipe", stderr: "pipe" });
+    const timed = await Promise.race([child.exited, new Promise<"timeout">(done => setTimeout(() => done("timeout"), timeoutMs))]);
+    if (timed === "timeout") { child.kill(); return { findings: [], couldNotCheck: `asciidoctor exceeded ${timeoutMs / 1000}s and was abandoned; the corpus was not rendered` }; }
+    const parsed = parseAsciidoctorDiagnostics(await new Response(child.stderr).text(), root);
+    if (parsed.couldNotCheck) return parsed;
+    if (timed !== 0 && !parsed.findings.length) return { findings: [], couldNotCheck: `asciidoctor failed without saying where: exit status ${timed}` };
+    return parsed;
+  } catch (error) { return { findings: [], couldNotCheck: `asciidoctor could not be executed: ${String(error)}` }; }
+  finally { await rm(output, { recursive: true, force: true }); }
+}
+
+async function checkDocumentationInner(input: { root: string; declaration: DocumentationDeclaration | null; changeSet: string[] | null; render?: () => Promise<DocumentationRender> }): Promise<DocumentationCheck> {
+  if (input.declaration?.impact === "none") return { verdict: "NOT_APPLICABLE", findings: [], checked: [] };
+  const corpus = await scanDocumentation(input.root); const findings: DocumentationCheck["findings"] = [...corpus]; const checked = (await documents(resolve(input.root))).map(d => d.path); let definite = corpus.length > 0;
+  if (input.declaration) { const declarationFindings = declarationViolations(input.declaration, input.changeSet ?? undefined); findings.push(...declarationFindings); definite ||= declarationFindings.length > 0; checked.push("<declaration>"); if (input.declaration.impact === "change") for (const artifact of input.declaration.artifacts ?? []) if (["create", "modify"].includes(artifact.action ?? "") && artifact.path && !existsSync(join(input.root, artifact.path))) { findings.push(violation("planner.docs.artifact-path-shape", artifact.path, 1, `declared artifact ${JSON.stringify(artifact.path)} (action: ${artifact.action}) is not in the tree, so it was never examined; a declared document that was never written has not discharged the obligation.`)); definite = true; } } else findings.push({ rule_id: null, where: "<declaration>", message: "core supplied no documentation declaration, so no declaration-dependent rule could be evaluated. This is COULD_NOT_CHECK and it BLOCKS." });
+  if (input.declaration && input.changeSet === null) findings.push({ rule_id: null, where: "<change_set>", message: "core supplied no change set, so whether this diff touches docs/ without declaring it could not be established. This is COULD_NOT_CHECK and it BLOCKS." });
+  const rendered = await (input.render ?? (() => renderDocumentation(input.root)))(); findings.push(...rendered.findings); definite ||= rendered.findings.length > 0; if (rendered.couldNotCheck) findings.push({ rule_id: "planner.docs.reference-integrity", file: "docs/", line: 1, col: 1, evidence: rendered.couldNotCheck, source_line: "" }); else checked.push("<render:asciidoctor>");
+  return { verdict: definite ? "FAIL" : input.declaration === null || input.changeSet === null || Boolean(rendered.couldNotCheck) ? "COULD_NOT_CHECK" : "PASS", findings, checked };
+}
+
+/** A capability crash is never interpreted as a clean documentation result. */
+export async function checkDocumentation(input: { root: string; declaration: DocumentationDeclaration | null; changeSet: string[] | null; render?: () => Promise<DocumentationRender> }): Promise<DocumentationCheck> {
+  try { return await checkDocumentationInner(input); }
+  catch (error) { return { verdict: "FAIL", findings: [{ rule_id: null, where: input.root, message: `the documentation capability raised ${error instanceof Error ? error.name : "Error"}: ${String(error)}. A capability that crashes has not discharged the obligation.` }], checked: [] }; }
+}

package/src/enforce.ts

@@ -0,0 +1,103 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+export type Profile = "traceability" | "docs" | "planner" | "coder" | "tester" | "security" | "architecture" | "metrics" | "runtime" | "interlocking" | "htmx" | "all";
+
+export type Violation = {
+  rule_id: string;
+  file: string;
+  line: number;
+  col: number;
+  evidence: string;
+  source_line: string;
+};
+
+export type EnforcementConfig = {
+  root?: string;
+  scanRoots?: string[];
+  excludes?: string[];
+  profiles?: Profile[];
+};
+
+const profiles: Record<Exclude<Profile, "all">, string[]> = {
+  traceability: ["atdd_traceability_closure"],
+  docs: ["planner_docs_capability"],
+  planner: ["planner_plan_integrity", "planner_schema_validation", "planner_static_validators"],
+  coder: ["bun_green_traceability_detector", "bun_clean_architecture_detector", "bun_ts_metrics_detector", "bun_fullstack_detector"],
+  tester: ["bun_tester_discipline_detector"],
+  security: ["bun_security_hygiene_detector"],
+  architecture: ["bun_clean_architecture_detector"],
+  metrics: ["bun_ts_metrics_detector"],
+  runtime: ["bun_fullstack_detector"],
+  interlocking: ["bun_interlocking_binding", "bun_interlocking_coverage", "bun_interlocking_infrastructure"],
+  htmx: ["htmx_hypermedia_detector", "htmx_tester_detector"],
+};
+
+/** Profile names accepted by the CLI and public integrations. */
+export const profileNames = [...Object.keys(profiles), "all"] as Profile[];
+
+const packageRoot = resolve(import.meta.dir, "..");
+const detectorRoot = join(packageRoot, "detectors");
+
+export function implementationsFor(requested: Profile[] = ["all"]): string[] {
+  const selected = new Set<string>();
+  for (const profile of requested) {
+    if (profile === "all") {
+      for (const ids of Object.values(profiles)) ids.forEach((id) => selected.add(id));
+      continue;
+    }
+    const ids = profiles[profile];
+    if (!ids) throw new Error(`unknown enforcement profile: ${profile}`);
+    ids.forEach((id) => selected.add(id));
+  }
+  return [...selected].sort();
+}
+
+export async function runImplementation(
+  implementation: string,
+  config: Required<Pick<EnforcementConfig, "scanRoots" | "excludes">>,
+): Promise<Violation[]> {
+  const detector = join(detectorRoot, implementation, "detect.mjs");
+  const scratch = await mkdtemp(join(tmpdir(), "atdd-bun-"));
+  const report = join(scratch, "violations.json");
+  try {
+    const bun = Bun.which("bun") ?? process.execPath;
+    const child = Bun.spawn({
+      cmd: [bun, detector],
+      cwd: config.scanRoots[0] ?? process.cwd(),
+      stdout: "pipe",
+      stderr: "pipe",
+      env: {
+        ...process.env,
+        ATDD_SCAN_ROOTS: JSON.stringify(config.scanRoots),
+        ATDD_SCAN_EXCLUDES: JSON.stringify(config.excludes),
+        ATDD_VIOLATIONS_REPORT: report,
+      },
+    });
+    const exitCode = await child.exited;
+    if (exitCode !== 0) {
+      const stderr = await new Response(child.stderr).text();
+      throw new Error(`${implementation} failed to run (exit ${exitCode}): ${stderr.trim()}`);
+    }
+    const raw = JSON.parse(await readFile(report, "utf8"));
+    if (!raw || !Array.isArray(raw.violations)) {
+      throw new Error(`${implementation} emitted no structured violation report`);
+    }
+    return raw.violations as Violation[];
+  } finally {
+    await rm(scratch, { recursive: true, force: true });
+  }
+}
+
+export async function enforce(config: EnforcementConfig = {}): Promise<Violation[]> {
+  const root = resolve(config.root ?? process.cwd());
+  const scanRoots = (config.scanRoots?.length ? config.scanRoots : [root]).map((path) => resolve(root, path));
+  const excludes = ["node_modules", ".git", ".atdd", ...(config.excludes ?? [])];
+  const results = await Promise.all(
+    implementationsFor(config.profiles).map((implementation) => runImplementation(implementation, { scanRoots, excludes })),
+  );
+  return results.flat().sort((left, right) =>
+    left.rule_id.localeCompare(right.rule_id) || left.file.localeCompare(right.file) || left.line - right.line,
+  );
+}

package/src/hooks.ts

@@ -0,0 +1,48 @@
+import { chmod, mkdir, readdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { enforce } from "./enforce";
+
+export type WorktreePolicy = { enabled: boolean; root: string; primary_directory: string; primary_branch: string; require_linked_worktree: boolean };
+export type HookPolicy = { max_staged_files: number; max_staged_changed_lines: number; max_uncommitted_files: number; max_commits_per_push: number; protected_branches: string[]; require_plan_reference: boolean; require_traceability: boolean; worktrees: WorktreePolicy };
+export const defaultWorktreePolicy: WorktreePolicy = { enabled: false, root: "../worktrees", primary_directory: "main", primary_branch: "main", require_linked_worktree: true };
+export const defaultHookPolicy: HookPolicy = { max_staged_files: 20, max_staged_changed_lines: 350, max_uncommitted_files: 10, max_commits_per_push: 10, protected_branches: ["main", "master"], require_plan_reference: true, require_traceability: true, worktrees: defaultWorktreePolicy };
+export const hookEvents = ["pre-commit", "commit-msg", "pre-push", "pre-merge-commit", "post-commit", "post-merge"] as const;
+export type HookEvent = typeof hookEvents[number];
+const git = async (root: string, args: string[], input?: string) => { const child = Bun.spawn({ cmd: ["git", ...args], cwd: root, stdin: input ? new Blob([input]) : undefined, stdout: "pipe", stderr: "pipe" }); return { code: await child.exited, out: (await new Response(child.stdout).text()).trim(), err: (await new Response(child.stderr).text()).trim() }; };
+const bad = (message: string) => ({ ok: false, message });
+const files = async (root: string, args: string[]) => (await git(root, args)).out.split("\n").filter(Boolean);
+
+export async function policy(root: string): Promise<HookPolicy> { const file = join(root, "atdd-bun.yaml"); if (!existsSync(file)) return defaultHookPolicy; const data = Bun.YAML.parse(await readFile(file, "utf8")) as Record<string, unknown>; const configuredWorktrees = data?.worktrees && typeof data.worktrees === "object" && !Array.isArray(data.worktrees) ? data.worktrees as Record<string, unknown> : {}; return { ...defaultHookPolicy, ...Object.fromEntries(Object.entries(data ?? {}).filter(([key, value]) => key in defaultHookPolicy && key !== "worktrees" && typeof value === typeof (defaultHookPolicy as any)[key])), protected_branches: Array.isArray(data?.protected_branches) ? data.protected_branches.filter((x): x is string => typeof x === "string") : defaultHookPolicy.protected_branches, worktrees: { ...defaultWorktreePolicy, ...Object.fromEntries(Object.entries(configuredWorktrees).filter(([key, value]) => key in defaultWorktreePolicy && typeof value === typeof (defaultWorktreePolicy as any)[key])) } }; }
+async function validation(root: string, changed: string[], full: boolean) { const profiles: any[] = []; if (changed.some(path => path.startsWith("plan/"))) profiles.push("planner", "traceability"); if (changed.some(path => /\.(?:[cm]?[jt]sx?|html)$/.test(path))) profiles.push("coder", "tester"); if (!profiles.length) return { ok: true, message: "no affected area" }; try { const findings = await enforce({ root, profiles: full ? ["all"] : [...new Set(profiles)] }); return findings.length ? bad(findings.map(f => `${f.rule_id}: ${f.file}`).join("\n")) : { ok: true, message: "validation clean" }; } catch (error) { return bad(`Bun enforcer resolution failed: ${String(error)}`); } }
+
+const inside = (parent: string, child: string) => { const path = relative(parent, child); return path === "" || (path !== ".." && !path.startsWith("../") && !path.startsWith("..\\")); };
+async function primaryRoot(root: string): Promise<string | null> { const result = await git(root, ["rev-parse", "--git-common-dir"]); if (result.code) return null; return dirname(resolve(root, result.out)); }
+export type WorktreeLayout = { primary: string; worktreeRoot: string; current: string; branch: string };
+async function layout(root: string, cfg: WorktreePolicy): Promise<WorktreeLayout | { error: string }> { const current = await realpath(resolve(root)), commonRoot = await primaryRoot(current); if (!commonRoot) return { error: "not inside a Git worktree" }; const primary = await realpath(commonRoot), expectedPrimary = join(dirname(primary), cfg.primary_directory); if (primary !== expectedPrimary) return { error: `primary checkout must be ${expectedPrimary}, not ${primary}` }; const branch = (await git(primary, ["symbolic-ref", "--quiet", "--short", "HEAD"])).out; if (branch !== cfg.primary_branch) return { error: `primary checkout ${primary} must be on ${cfg.primary_branch}, not ${branch || "a detached HEAD"}` }; return { primary, worktreeRoot: resolve(primary, cfg.root), current, branch: (await git(current, ["symbolic-ref", "--quiet", "--short", "HEAD"])).out }; }
+async function worktreeCommitPolicy(root: string, cfg: WorktreePolicy): Promise<string | null> { if (!cfg.enabled || !cfg.require_linked_worktree) return null; const state = await layout(root, cfg); if ("error" in state) return state.error; if (state.current === state.primary) return `commits must use a linked worktree beneath ${state.worktreeRoot}; run: atdd-bun worktree start <branch>`; if (!inside(state.worktreeRoot, state.current)) return `linked worktree ${state.current} is outside required root ${state.worktreeRoot}`; if (!state.branch) return "commits require a named branch, not a detached HEAD"; return null; }
+
+export async function runHook(event: HookEvent, root = process.cwd(), args: string[] = [], stdin = "") {
+  const cfg = await policy(root), branch = (await git(root, ["symbolic-ref", "--quiet", "--short", "HEAD"])).out;
+  if (["pre-commit", "pre-merge-commit"].includes(event) && cfg.protected_branches.includes(branch)) return bad(`protected branch ${branch} is blocked`);
+  if (["pre-commit", "pre-merge-commit"].includes(event)) { const violation = await worktreeCommitPolicy(root, cfg.worktrees); if (violation) return bad(violation); }
+  if (event === "pre-commit") { const staged = await files(root, ["diff", "--cached", "--name-only"]), dirty = await files(root, ["status", "--porcelain"]), lines = (await git(root, ["diff", "--cached", "--numstat"])).out.split("\n").reduce((n, row) => n + (Number(row.split("\t")[0]) || 0) + (Number(row.split("\t")[1]) || 0), 0); if (staged.length > cfg.max_staged_files) return bad(`staged files ${staged.length} exceed ${cfg.max_staged_files}`); if (dirty.length > cfg.max_uncommitted_files) return bad(`uncommitted files ${dirty.length} exceed ${cfg.max_uncommitted_files}`); if (lines > cfg.max_staged_changed_lines) return bad(`staged changed lines ${lines} exceed ${cfg.max_staged_changed_lines}`); return cfg.require_traceability ? validation(root, staged, false) : { ok: true, message: "ok" }; }
+  if (event === "commit-msg") { const deleted = (await files(root, ["diff", "--cached", "--name-only", "--diff-filter=D"])).length, lines = (await git(root, ["diff", "--cached", "--numstat"])).out.split("\n").reduce((n, row) => n + (Number(row.split("\t")[1]) || 0), 0), message = args[0] && existsSync(args[0]) ? await readFile(args[0], "utf8") : ""; return (deleted > 50 || lines > 10_000) && !message.includes("[mass-delete-approved]") ? bad("mass delete requires [mass-delete-approved]") : { ok: true, message: "ok" }; }
+  if (event === "pre-push") { for (const row of stdin.split("\n").filter(Boolean).map(row => row.split(/\s+/))) { const [,,remote, remoteSha] = row, target = remote?.replace("refs/heads/", ""); if (target && cfg.protected_branches.includes(target)) return bad(`protected branch ${target} is blocked`); const local = row[1]; if (local && !/^0+$/.test(local)) { const range = !remoteSha || /^0+$/.test(remoteSha) ? `${local}^..${local}` : `${remoteSha}..${local}`, count = Number((await git(root, ["rev-list", "--count", range])).out); if (count > cfg.max_commits_per_push) return bad(`commits per push ${count} exceed ${cfg.max_commits_per_push}`); } } return validation(root, await files(root, ["diff", "--name-only", "HEAD~1..HEAD"]), true); }
+  if (event === "post-commit") { const result = await validation(root, await files(root, ["show", "--pretty=format:", "--name-only", "HEAD"]), false); return { ok: true, message: result.ok ? result.message : `advisory: ${result.message}` }; }
+  return { ok: true, message: "ok" };
+}
+
+const dispatcher = (event: HookEvent, entry: string) => `#!/bin/sh\nexec bun ${JSON.stringify(entry)} hook ${event} "$@"\n`;
+export async function installHooks(root = process.cwd(), replace = false) { const current = (await git(root, ["config", "--worktree", "--get", "core.hooksPath"])).out || (await git(root, ["config", "--get", "core.hooksPath"])).out; if (current && current !== ".githooks" && !replace) return bad(`core.hooksPath is ${current}; use --replace`); await git(root, ["config", "extensions.worktreeConfig", "true"]); await mkdir(join(root, ".githooks"), { recursive: true }); const entry = resolve(import.meta.dir, "cli.ts"); for (const event of hookEvents) { const file = join(root, ".githooks", event); await writeFile(file, dispatcher(event, entry)); await chmod(file, 0o755); } const result = await git(root, ["config", "--worktree", "core.hooksPath", ".githooks"]); return result.code ? bad(result.err) : { ok: true, message: "hooks installed" }; }
+export async function uninstallHooks(root = process.cwd()) { if ((await git(root, ["config", "--worktree", "--get", "core.hooksPath"])).out === ".githooks") await git(root, ["config", "--worktree", "--unset", "core.hooksPath"]); for (const event of hookEvents) await rm(join(root, ".githooks", event), { force: true }); return { ok: true, message: "hooks uninstalled" }; }
+export async function hooksStatus(root = process.cwd()) { const path = (await git(root, ["config", "--worktree", "--get", "core.hooksPath"])).out; return { ok: path === ".githooks" && hookEvents.every(event => existsSync(join(root, ".githooks", event))), message: path || "not installed" }; }
+
+const branchPath = (branch: string) => branch.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+export async function startWorktree(root = process.cwd(), branch = "") { const cfg = await policy(root); if (!cfg.worktrees.enabled) return bad("worktree policy is disabled; set worktrees.enabled: true in atdd-bun.yaml"); const state = await layout(root, cfg.worktrees); if ("error" in state) return bad(state.error); if (state.current !== state.primary) return bad(`start must run from the primary checkout ${state.primary}`); if (!branch) return bad("branch is required: atdd-bun worktree start <branch>"); if ((await git(root, ["check-ref-format", "--branch", branch])).code) return bad(`invalid branch name ${JSON.stringify(branch)}`); if (cfg.protected_branches.includes(branch)) return bad(`cannot create a worktree for protected branch ${branch}`); const leaf = branchPath(branch); if (!leaf) return bad(`branch ${JSON.stringify(branch)} cannot form a safe worktree directory`); const target = join(state.worktreeRoot, leaf); if (existsSync(target)) return bad(`worktree path already exists: ${target}`); await mkdir(state.worktreeRoot, { recursive: true }); const created = await git(state.primary, ["worktree", "add", target, "-b", branch]); if (created.code) return bad(created.err || created.out); const hooks = await installHooks(target); if (!hooks.ok) return bad(`created ${target}, but could not install hooks: ${hooks.message}`); return { ok: true, message: `created linked worktree ${target} on ${branch}` }; }
+
+export async function worktreeStatus(root = process.cwd()) { const cfg = await policy(root); if (!cfg.worktrees.enabled) return bad("worktree policy is disabled"); const state = await layout(root, cfg.worktrees); if ("error" in state) return bad(state.error); const result = await git(state.primary, ["worktree", "list", "--porcelain"]); return result.code ? bad(result.err) : { ok: true, message: result.out }; }
+
+async function generatedHooksOnly(root: string): Promise<boolean> { const directory = join(root, ".githooks"); if (!existsSync(directory)) return false; const names = (await readdir(directory)).sort(); if (names.join("\n") !== [...hookEvents].sort().join("\n")) return false; const entry = resolve(import.meta.dir, "cli.ts"); return (await Promise.all(hookEvents.map(async event => (await readFile(join(directory, event), "utf8")) === dispatcher(event, entry)))).every(Boolean); }
+
+export async function finishWorktree(root = process.cwd(), deleteBranch = false) { const cfg = await policy(root); if (!cfg.worktrees.enabled) return bad("worktree policy is disabled"); const state = await layout(root, cfg.worktrees); if ("error" in state) return bad(state.error); if (state.current === state.primary || !inside(state.worktreeRoot, state.current)) return bad(`finish must run from a linked worktree beneath ${state.worktreeRoot}`); if (!state.branch || cfg.protected_branches.includes(state.branch)) return bad("finish requires a non-protected named branch"); const status = (await git(state.current, ["status", "--porcelain"])).out, generatedHooks = await generatedHooksOnly(state.current), onlyGeneratedHooks = Boolean(status) && status.split("\n").every(line => line.endsWith(" .githooks/") || line.endsWith(" .githooks")); if (status && !onlyGeneratedHooks) return bad("worktree is dirty; commit, stash, or discard changes before finish"); if ((await git(state.primary, ["merge-base", "--is-ancestor", state.branch, cfg.worktrees.primary_branch])).code) return bad(`branch ${state.branch} is not merged into ${cfg.worktrees.primary_branch} in the primary checkout`); const removed = await git(state.primary, ["worktree", "remove", ...(onlyGeneratedHooks && generatedHooks ? ["--force"] : []), state.current]); if (removed.code) return bad(removed.err || removed.out); if (deleteBranch) { const deleted = await git(state.primary, ["branch", "-d", state.branch]); if (deleted.code) return bad(`worktree removed, but branch deletion failed: ${deleted.err || deleted.out}`); } return { ok: true, message: `removed merged worktree ${state.current}${deleteBranch ? ` and branch ${state.branch}` : ""}` }; }

package/src/index.ts

@@ -0,0 +1,13 @@
+export { enforce, implementationsFor, profileNames, runImplementation } from "./enforce";
+export type { EnforcementConfig, Profile, Violation } from "./enforce";
+export { checkDocumentation, declarationViolations, DOC_RULE_IDS, parseAsciidoctorDiagnostics, parseAttributes, renderDocumentation, scanDocumentation } from "./docs-capability";
+export type { DocumentationCheck, DocumentationDeclaration, DocumentationRender, DocumentationRuleId, DocumentationViolation } from "./docs-capability";
+export { loadPlan, traceabilityPlan, validatePlan } from "./planner-kernel";
+export type { PlanArtifact, PlanFinding, PlanGraph, PlanKind } from "./planner-kernel";
+export { validateStaticPlannerConventions } from "./planner-validators";
+export { PLANNER_SCHEMA_RULE_ID, validatePlannerSchemas } from "./planner-schema-validator";
+export { defaultHookPolicy, hookEvents, hooksStatus, installHooks, runHook, uninstallHooks } from "./hooks";
+export type { HookEvent, HookPolicy } from "./hooks";
+export { ciInit, ciStatus } from "./ci";
+export { initializeRepository } from "./setup";
+export { releaseCheck } from "./release";