@printpractical/cruze 0.0.1

package/src/domain/validation/plan_rules.ts

@@ -0,0 +1,105 @@
+import { factsOf, isUnbuilt } from "../elements.ts";
+import { findIds, kindOf } from "../ids.ts";
+import type { MarkdownDoc } from "../markdown.ts";
+import type { Delta } from "../project/deltas.ts";
+import { isPlanned, readScope, readTasks, readTestPlan, type Scope } from "../project/plan_parts.ts";
+import type { ProjectView } from "../project/project_view.ts";
+import { error, warning, type Problem } from "./problem.ts";
+
+const TEST_KINDS = ["behaviour", "contract", "domain", "smoke"];
+
+/**
+ * Rules for one buildable change: its scope names only things that can be built. Once it is
+ * planned, every scope ID is proved by a task, every delivered scenario has a behaviour test,
+ * and every port a built adapter implements has a contract test.
+ */
+export function changePlanProblems(
+  view: ProjectView,
+  path: string,
+  doc: MarkdownDoc,
+  delta: { delta: Delta; doc: MarkdownDoc },
+  available: Set<string>,
+): Problem[] {
+  const scope = readScope(doc);
+  if (scope === null) return [error(path, undefined, "missing-section", 'the change needs a "## Scope" section')];
+  const problems: Problem[] = [...scopeTargetProblems(view, path, scope, delta.delta)];
+  if (!isPlanned(doc)) return [...problems, warning(path, undefined, "not-planned", "the change has no test plan or tasks yet; plan fills them")];
+  const { tasks, malformed } = readTasks(doc);
+  for (const line of malformed) {
+    problems.push(error(path, line, "task-format", "task lines read: - T<n>: `<owner>` in `<path>`[, `<path>`], proves <ID>[, <ID>]"));
+  }
+  if (tasks.length === 0 && malformed.length === 0) problems.push(error(path, undefined, "missing-tasks", "the change has no tasks"));
+
+  const proved = new Set(tasks.flatMap((task) => task.proves));
+  const taskPaths = tasks.flatMap((task) => task.paths);
+  for (const task of tasks) {
+    for (const id of task.proves.filter((id) => !available.has(id))) {
+      problems.push(error(path, task.line, "unknown-id", `${task.number} proves ${id}, which is not defined`));
+    }
+  }
+  for (const id of [...scope.delivers, ...scope.builds]) {
+    if (kindOf(id) === "MOD") {
+      const modulePaths = modulePathsOf(view, delta.doc, delta.delta, id);
+      if (!taskPaths.some((p) => modulePaths.some((m) => p.startsWith(m)))) {
+        problems.push(error(path, scope.line, "unproved-scope", `${id} is in scope but no task writes inside ${modulePaths.join(" or ") || "its path"}`));
+      }
+    } else if (kindOf(id) === "REQ") {
+      const scenarios = delta.delta.entries.find((e) => e.element.id === id)?.scenarios.map((s) => s.id) ?? [];
+      if (!proved.has(id) && !scenarios.some((s) => proved.has(s))) problems.push(error(path, scope.line, "unproved-scope", `no task proves ${id} or its scenarios`));
+    } else if (!proved.has(id)) {
+      problems.push(error(path, scope.line, "unproved-scope", `${id} is in scope but no task proves it`));
+    }
+  }
+
+  const rows = readTestPlan(doc);
+  for (const row of rows) {
+    if (!TEST_KINDS.includes(row.kind)) problems.push(error(path, row.line, "test-kind", `test kind must be one of ${TEST_KINDS.join(", ")}`));
+    const subject = findIds(row.subject)[0];
+    if (subject === undefined || !available.has(subject)) problems.push(error(path, row.line, "unknown-id", `test subject "${row.subject}" is not a defined ID`));
+    if (row.file === "") problems.push(error(path, row.line, "test-file", "every test plan row names its test file"));
+  }
+  for (const id of scope.delivers.filter((id) => kindOf(id) === "SCN")) {
+    if (!rows.some((row) => findIds(row.subject)[0] === id && row.kind === "behaviour")) {
+      problems.push(error(path, scope.line, "missing-behaviour-test", `${id} is delivered but has no behaviour row in the test plan`));
+    }
+  }
+  for (const adapter of scope.builds.filter((id) => kindOf(id) === "ADP")) {
+    const ports = (factsOfScoped(view, delta.doc, delta.delta, adapter).get("Implements") ?? []).flatMap(findIds).filter((id) => kindOf(id) === "PORT");
+    for (const port of ports.filter((p) => !rows.some((row) => findIds(row.subject)[0] === p && row.kind === "contract"))) {
+      problems.push(error(path, scope.line, "missing-contract-test", `${adapter} implements ${port} but the test plan has no contract row for ${port}`));
+    }
+  }
+  return problems;
+}
+
+/** Scope IDs must come from the item's deltas or be planned in the living docs. */
+function scopeTargetProblems(view: ProjectView, path: string, scope: Scope, delta: Delta): Problem[] {
+  const problems: Problem[] = [];
+  for (const id of [...scope.delivers, ...scope.builds]) {
+    if (delta.ids.has(id)) continue;
+    const living = view.living.elements.get(id);
+    if (living === undefined) problems.push(error(path, scope.line, "unknown-id", `${id} is in scope but defined nowhere`));
+    else if (!isUnbuilt(living.doc, living.element)) {
+      problems.push(error(path, scope.line, "scope-not-planned", `${id} is already built; change it through a MODIFIED operation in the delta`));
+    }
+  }
+  for (const id of scope.removes) {
+    const removal = delta.entries.find((e) => e.element.id === id && e.element.op === "REMOVED");
+    if (removal === undefined) problems.push(error(path, scope.line, "scope-removes", `${id} is in Removes but the delta has no REMOVED operation for it`));
+  }
+  if (scope.delivers.length + scope.builds.length + scope.removes.length === 0) {
+    problems.push(warning(path, scope.line, "empty-scope", "the scope delivers and builds nothing"));
+  }
+  return problems;
+}
+
+/** An element's facts as this item will build it: from its delta when it has one, else from the living docs. */
+function factsOfScoped(view: ProjectView, doc: MarkdownDoc, delta: Delta, id: string): Map<string, string[]> {
+  const fromDelta = delta.entries.find((e) => e.element.id === id);
+  const living = view.living.elements.get(id);
+  return fromDelta !== undefined ? factsOf(doc, fromDelta.element) : living !== undefined ? factsOf(living.doc, living.element) : new Map<string, string[]>();
+}
+
+function modulePathsOf(view: ProjectView, doc: MarkdownDoc, delta: Delta, id: string): string[] {
+  return (factsOfScoped(view, doc, delta, id).get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? "")).filter((p) => p !== "");
+}

package/src/domain/validation/problem.ts

@@ -0,0 +1,21 @@
+/** One way a document breaks the cruze-formats rules. */
+export interface Problem {
+  path: string;
+  /** 1-based line number, when the problem has a location. */
+  line?: number;
+  rule: string;
+  message: string;
+  severity: "error" | "warning";
+}
+
+export function error(path: string, line: number | undefined, rule: string, message: string): Problem {
+  return line === undefined ? { path, rule, message, severity: "error" } : { path, line: line + 1, rule, message, severity: "error" };
+}
+
+export function warning(path: string, line: number | undefined, rule: string, message: string): Problem {
+  return { ...error(path, line, rule, message), severity: "warning" };
+}
+
+export function sortProblems(problems: Problem[]): Problem[] {
+  return [...problems].sort((a, b) => a.path.localeCompare(b.path) || (a.line ?? 0) - (b.line ?? 0) || a.rule.localeCompare(b.rule));
+}

package/src/domain/validation/project_rules.ts

@@ -0,0 +1,99 @@
+import { factsOf } from "../elements.ts";
+import { matchesAny } from "../glob.ts";
+import { findIds } from "../ids.ts";
+import { parseMarkdown, type MarkdownDoc } from "../markdown.ts";
+import { PATHS } from "../project/layout.ts";
+import { readRoadmapItems } from "../project/roadmap.ts";
+import type { ProjectView } from "../project/project_view.ts";
+import { error, warning, type Problem } from "./problem.ts";
+
+/** Rules that span the project: leftover template guides, the roadmap and the config. */
+
+const GUIDE = /(?<!`)<(?!!--|\/|https?:|br\b)[A-Za-z][^<>\n]*>(?!`)/;
+const PLACEHOLDER = /\{\{[a-z_]+\}\}/;
+
+/**
+ * Unfilled `<guides>` and `{{placeholders}}` outside code, in living docs and active work.
+ * Managed blocks are skipped: the CLI writes them, and they may quote text such as `<COMMAND>`.
+ */
+export function templateLeftovers(view: ProjectView): Problem[] {
+  const paths = [...view.living.docs.keys(), PATHS.roadmap, PATHS.glossary, ...view.items.filter((i) => !i.archived).map((i) => i.path)];
+  return paths.flatMap((path) => {
+    const text = view.snapshot.get(path);
+    if (text === undefined) return [];
+    const doc = parseMarkdown(text);
+    return doc.lines.flatMap((line, i) => {
+      if (doc.inFence[i] || doc.inManaged[i]) return [];
+      const withoutCode = line.replace(/`[^`]*`/g, "");
+      if (GUIDE.test(withoutCode) || PLACEHOLDER.test(withoutCode)) {
+        return [error(path, i, "template-leftover", "replace the template guide or placeholder on this line")];
+      }
+      return [];
+    });
+  });
+}
+
+export function roadmapProblems(view: ProjectView): Problem[] {
+  const text = view.snapshot.get(PATHS.roadmap);
+  if (text === undefined) return [];
+  const doc = parseMarkdown(text);
+  const problems: Problem[] = [];
+  const items = new Map<string, { blockedBy: string[]; line: number }>();
+  for (const { slug: item, kind, blockedBy, line } of readRoadmapItems(text)) {
+    if (items.has(item)) problems.push(error(PATHS.roadmap, line, "roadmap-item", `item ${item} appears twice`));
+    if (!["feature", "change"].includes(kind)) problems.push(error(PATHS.roadmap, line, "roadmap-item", `item ${item} kind must be feature or change`));
+    items.set(item, { blockedBy, line });
+  }
+  for (const [item, { blockedBy, line }] of items) {
+    for (const blocker of blockedBy.filter((b) => !items.has(b))) problems.push(error(PATHS.roadmap, line, "roadmap-blocker", `${item} is blocked by unknown item ${blocker}`));
+  }
+  const cycle = findCycle(items);
+  if (cycle !== null) problems.push(error(PATHS.roadmap, undefined, "roadmap-cycle", `blocking cycle: ${cycle.join(" -> ")}`));
+  const coverage = doc.lines.join("\n").split(/^## Coverage$/m)[1] ?? "";
+  for (const goal of [...view.living.elements.keys()].filter((id) => id.startsWith("GOAL-"))) {
+    if (!findIds(coverage).includes(goal)) problems.push(warning(PATHS.roadmap, undefined, "goal-uncovered", `${goal} has no items in the coverage table`));
+  }
+  return problems;
+}
+
+function findCycle(items: Map<string, { blockedBy: string[] }>): string[] | null {
+  const state = new Map<string, "visiting" | "done">();
+  const visit = (item: string, path: string[]): string[] | null => {
+    if (state.get(item) === "done") return null;
+    if (state.get(item) === "visiting") return [...path.slice(path.indexOf(item)), item];
+    state.set(item, "visiting");
+    for (const next of items.get(item)?.blockedBy ?? []) {
+      const found = visit(next, [...path, item]);
+      if (found !== null) return found;
+    }
+    state.set(item, "done");
+    return null;
+  };
+  for (const item of items.keys()) {
+    const found = visit(item, []);
+    if (found !== null) return found;
+  }
+  return null;
+}
+
+export function configProblems(view: ProjectView): Problem[] {
+  if (view.config === null) return [error(PATHS.config, undefined, "config-missing", "the project has no .cruze/config.yaml; run cruze init")];
+  const problems = view.config.problems.map((message) => error(PATHS.config, undefined, "config", message));
+  const config = view.config.config;
+  const architecture = view.living.docs.get(PATHS.architecture);
+  if (config === null || architecture === undefined || config.layers.length === 0) return problems;
+  for (const { element } of [...view.living.elements.values()].filter((e) => e.id.startsWith("MOD-"))) {
+    for (const path of modulePaths(architecture, element)) {
+      const probe = path.endsWith("/") ? `${path}probe.file` : path;
+      const layers = config.layers.filter((layer) => matchesAny(probe, layer.paths));
+      if (layers.length !== 1) {
+        problems.push(warning(PATHS.config, undefined, "module-layer", `${element.id} path ${path} falls in ${layers.length} layers; it should fall in exactly one`));
+      }
+    }
+  }
+  return problems;
+}
+
+function modulePaths(doc: MarkdownDoc, element: Parameters<typeof factsOf>[1]): string[] {
+  return (factsOf(doc, element).get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? ""));
+}

package/src/domain/validation/validate_project.ts

@@ -0,0 +1,31 @@
+import type { ProjectView } from "../project/project_view.ts";
+import { livingProblems } from "./living_rules.ts";
+import { error, sortProblems, type Problem } from "./problem.ts";
+import { configProblems, roadmapProblems, templateLeftovers } from "./project_rules.ts";
+import { workItemProblems } from "./work_item_rules.ts";
+
+/** Every rule in the cruze-formats skill, applied to the whole project. */
+export function validateProject(view: ProjectView): Problem[] {
+  const approvalProblems = [...view.approvalProblems].map(([path, message]) => error(path, undefined, "approvals-file", message));
+  const journalProblems = [...view.journalProblems].flatMap(([path, lines]) =>
+    lines.map((line) => error(path, line - 1, "journal-line", "this journal line is not a valid entry")),
+  );
+  return sortProblems([
+    ...configProblems(view),
+    ...livingProblems(view),
+    ...roadmapProblems(view),
+    ...workItemProblems(view),
+    ...templateLeftovers(view),
+    ...approvalProblems,
+    ...journalProblems,
+  ]);
+}
+
+/** Problems that concern one document. */
+export function problemsFor(problems: Problem[], path: string): Problem[] {
+  return problems.filter((problem) => problem.path === path);
+}
+
+export function hasErrors(problems: Problem[]): boolean {
+  return problems.some((problem) => problem.severity === "error");
+}

package/src/domain/validation/work_item_rules.ts

@@ -0,0 +1,144 @@
+import { isUnbuilt } from "../elements.ts";
+import { findIds, kindOf } from "../ids.ts";
+import { elementHash } from "../hashing.ts";
+import { findSection, type MarkdownDoc } from "../markdown.ts";
+import { readDelta, type Delta } from "../project/deltas.ts";
+import { readChangesTable, readScope } from "../project/plan_parts.ts";
+import { readProgress } from "../project/progress.ts";
+import type { ProjectView } from "../project/project_view.ts";
+import { changesOf, featureOf, type WorkItem } from "../project/work_items.ts";
+import { deltaProblems } from "./delta_rules.ts";
+import { malformedIdHeadings, lineOf } from "./living_rules.ts";
+import { changePlanProblems } from "./plan_rules.ts";
+import { error, warning, type Problem } from "./problem.ts";
+
+const REQUIRED_SECTIONS: Record<WorkItem["kind"], string[]> = {
+  feature: ["Intent", "Spec delta", "Architecture delta", "Changes"],
+  change: ["Scope", "Test plan", "Tasks"],
+  standalone: ["Intent", "Spec delta", "Architecture delta", "Scope", "Test plan", "Tasks"],
+};
+
+/** Rules for every active feature and change. Archived work is history and is not checked. */
+export function workItemProblems(view: ProjectView): Problem[] {
+  return view.items.filter((item) => !item.archived).flatMap((item) => itemProblems(view, item));
+}
+
+function itemProblems(view: ProjectView, item: WorkItem): Problem[] {
+  const { path, doc } = item;
+  const problems: Problem[] = [...malformedIdHeadings(path, doc)];
+  const id = doc.frontmatter?.["id"];
+  if (id !== item.folderName) problems.push(error(path, 0, "frontmatter", `frontmatter id must be "${item.folderName}", the folder name`));
+  const title = doc.frontmatter?.["title"];
+  if (typeof title !== "string" || title.trim() === "") problems.push(error(path, 0, "frontmatter", "frontmatter needs a title"));
+  for (const section of REQUIRED_SECTIONS[item.kind]) {
+    if (findSection(doc, section) === null) problems.push(error(path, undefined, "missing-section", `missing "## ${section}"`));
+  }
+
+  const feature = item.kind === "change" ? featureOf(view.items, item) : undefined;
+  if (item.kind === "change" && feature === undefined) problems.push(error(path, undefined, "orphan-change", "the change's feature.md is missing"));
+  const deltaSource = item.kind === "change" ? feature : item;
+  const delta = deltaSource === undefined ? readDelta(doc) : readDelta(deltaSource.doc);
+  const available = new Set([...view.living.elements.keys(), ...delta.ids]);
+
+  const text = doc.lines.join("\n");
+  for (const cited of findIds(text).filter((cited) => !available.has(cited))) {
+    problems.push(error(path, lineOf(text, cited), "unknown-id", `${cited} is cited but defined neither in the living docs nor in this work's deltas`));
+  }
+  if (item.kind !== "change") problems.push(...deltaProblems(view, item));
+  if (item.kind === "feature") problems.push(...featureScopeProblems(view, item, delta));
+  // A landed change is history: its scope named what it built, which is now built.
+  const landed = item.kind !== "feature" && readProgress(doc).landed !== undefined;
+  if (item.kind !== "feature" && deltaSource !== undefined && !landed) {
+    problems.push(...changePlanProblems(view, path, doc, { delta, doc: deltaSource.doc }, available));
+  }
+  if (item.kind === "standalone") problems.push(...coverageProblems(view, path, delta, doc, [{ name: "this change", ids: scopeIds(item) }]));
+  return problems;
+}
+
+/** A feature's Changes table covers its deltas, and each change folder agrees with its row. */
+function featureScopeProblems(view: ProjectView, feature: WorkItem, delta: Delta): Problem[] {
+  const rows = readChangesTable(feature.doc);
+  if (rows.length === 0) return [warning(feature.path, undefined, "not-designed", "the feature has no changes yet; architect designs and splits it")];
+  const problems: Problem[] = [];
+  const landedChanges = new Set(
+    [...readProgress(feature.doc).changes].filter(([, state]) => state === "landed").map(([change]) => change),
+  );
+  const names = rows.map((row) => row.change);
+  for (const row of rows) {
+    if (!/^\d\d-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(row.change)) problems.push(error(feature.path, row.line, "change-name", `change "${row.change}" must be named NN-slug`));
+    if (names.indexOf(row.change) !== names.lastIndexOf(row.change)) problems.push(error(feature.path, row.line, "change-name", `change ${row.change} is listed twice`));
+    for (const dependency of row.dependsOn) {
+      const at = names.indexOf(dependency);
+      if (at === -1 || at >= names.indexOf(row.change)) problems.push(error(feature.path, row.line, "change-order", `${row.change} depends on ${dependency}, which must be an earlier change`));
+    }
+    for (const id of landedChanges.has(row.change) ? [] : [...row.delivers, ...row.builds]) {
+      const living = view.living.elements.get(id);
+      const planned = living !== undefined && isUnbuilt(living.doc, living.element);
+      if (!delta.ids.has(id) && !planned) problems.push(error(feature.path, row.line, "scope-not-planned", `${id} must come from this feature's deltas or be planned in the living docs`));
+    }
+  }
+  problems.push(...coverageProblems(view, feature.path, delta, feature.doc, rows.map((row) => ({ name: row.change, ids: [...row.delivers, ...row.builds, ...row.removes], landed: landedChanges.has(row.change) }))));
+
+  for (const change of changesOf(view.items, feature)) {
+    const row = rows.find((r) => r.change === change.folderName);
+    if (row === undefined) {
+      problems.push(error(change.path, undefined, "change-not-listed", `${change.folderName} is not in the feature's Changes table`));
+      continue;
+    }
+    const expected = new Set([...row.delivers, ...row.builds, ...row.removes]);
+    const actual = new Set(scopeIds(change));
+    const differ = [...expected].filter((id) => !actual.has(id)).concat([...actual].filter((id) => !expected.has(id)));
+    if (differ.length > 0) problems.push(error(change.path, readScope(change.doc)?.line, "scope-mismatch", `Scope differs from the feature's Changes row: ${differ.join(", ")}`));
+  }
+  return problems;
+}
+
+/**
+ * Every delta ID lands exactly once. A requirement is covered by its own ID or one of its
+ * scenarios. A scenario must be covered when it is new or its text changed; an unchanged
+ * scenario kept by a MODIFIED requirement may be left out.
+ */
+function coverageProblems(
+  view: ProjectView,
+  path: string,
+  delta: Delta,
+  deltaDoc: MarkdownDoc,
+  groups: Array<{ name: string; ids: string[]; landed?: boolean }>,
+): Problem[] {
+  const coveredBy = new Map<string, string[]>();
+  const pendingBy = new Map<string, string[]>();
+  for (const group of groups) {
+    for (const id of group.ids) {
+      coveredBy.set(id, [...(coveredBy.get(id) ?? []), group.name]);
+      if (group.landed !== true) pendingBy.set(id, [...(pendingBy.get(id) ?? []), group.name]);
+    }
+  }
+  const problems: Problem[] = [];
+  // A change that already landed may be followed by one that rebuilds the same element after a rethink.
+  const once = (id: string, line: number, required: boolean): void => {
+    const pending = pendingBy.get(id) ?? [];
+    if (required && (coveredBy.get(id) ?? []).length === 0) problems.push(error(path, line, "uncovered", `${id} is not in any change's scope`));
+    if (pending.length > 1) problems.push(error(path, line, "covered-twice", `${id} is in the scope of ${pending.join(" and ")}; it must land exactly once`));
+  };
+  for (const { element, scenarios } of delta.entries) {
+    if (kindOf(element.id) !== "REQ") {
+      once(element.id, element.start, true);
+      continue;
+    }
+    once(element.id, element.start, false);
+    if (![element.id, ...scenarios.map((s) => s.id)].some((id) => coveredBy.has(id))) {
+      problems.push(error(path, element.start, "uncovered", `${element.id} is not delivered by any change`));
+    }
+    for (const scenario of scenarios) {
+      const living = view.living.elements.get(scenario.id);
+      const changed = living === undefined || elementHash(living.doc, living.element) !== elementHash(deltaDoc, scenario);
+      once(scenario.id, scenario.start, element.op !== "REMOVED" && changed);
+    }
+  }
+  return problems;
+}
+
+function scopeIds(item: WorkItem): string[] {
+  const scope = readScope(item.doc);
+  return scope === null ? [] : [...scope.delivers, ...scope.builds, ...scope.removes];
+}

package/src/main.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// Composition root: the only place that constructs adapters.
+import { basename } from "node:path";
+import { runCli } from "./adapters/inbound/cli/run_cli.ts";
+import { GitRepository } from "./adapters/outbound/git_repository.ts";
+import { NodeProjectFiles } from "./adapters/outbound/node_project_files.ts";
+import { PackageBundle } from "./adapters/outbound/package_bundle.ts";
+import { ProcessAgentRunner } from "./adapters/outbound/process_agent_runner.ts";
+import { SystemClock } from "./adapters/outbound/system_clock.ts";
+import { DefaultAnswerPrompter, TerminalPrompter } from "./adapters/outbound/terminal_prompter.ts";
+
+const cwd = process.cwd();
+const exitCode = await runCli(
+  process.argv.slice(2),
+  {
+    files: new NodeProjectFiles(cwd),
+    bundle: await PackageBundle.locate(),
+    clock: new SystemClock(),
+    repository: new GitRepository(cwd),
+    interactivePrompter: new TerminalPrompter(),
+    unattendedPrompter: new DefaultAnswerPrompter(),
+    runner: new ProcessAgentRunner(cwd),
+    interactive: process.stdin.isTTY === true,
+    directoryName: basename(cwd),
+  },
+  {
+    stdout: (text) => process.stdout.write(`${text}\n`),
+    stderr: (text) => process.stderr.write(`${text}\n`),
+    stdoutIsTerminal: process.stdout.isTTY === true,
+  },
+);
+process.exitCode = exitCode;

package/templates/init/AGENTS.md

@@ -0,0 +1,28 @@
+# {{project_name}}
+
+Instructions for coding agents working in this repository. Cruze keeps the managed sections current as changes land; edit everything else freely.
+
+## Workflow
+
+This project uses [Cruze](https://github.com/PrintPractical/cruze) for spec-driven development. Durable documents live in `docs/`: vision, glossary, architecture, ADRs, specs and roadmap. Work in progress lives in `.cruze/`. Read `docs/architecture.md` before changing code, once it exists. The Cruze skills run the `cruze` command; when it is missing, install it as https://github.com/PrintPractical/cruze#quick-start describes.
+
+## Commands
+
+<!-- cruze:managed -->
+No build or test commands yet. `cruze land` fills this in when the walking-skeleton change lands.
+<!-- /cruze:managed -->
+
+## Layout
+
+<!-- cruze:managed -->
+Not defined yet. `cruze land` fills this in from the module map in `docs/architecture.md`.
+<!-- /cruze:managed -->
+
+## Conventions
+
+- Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/).
+- Record notable changes under `[Unreleased]` in `CHANGELOG.md`.
+
+## Known pitfalls
+
+None recorded yet. `land` adds a line here when the same review finding or defect happens twice.

package/templates/init/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]

package/templates/init/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/init/README.md

@@ -0,0 +1 @@
+# {{project_name}}

package/templates/init/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+      # The walking-skeleton change adds the language's format, lint, build and
+      # test steps here, from `commands:` in .cruze/config.yaml.
+      - name: Documents match the Cruze formats
+        run: npx --yes --package={{cruze_package}} cruze validate
+      - name: Layer rules and file budgets
+        run: npx --yes --package={{cruze_package}} cruze check --ci
+      - name: Every built scenario has a test
+        run: npx --yes --package={{cruze_package}} cruze trace --all

package/templates/init/config.yaml

@@ -0,0 +1,33 @@
+# Cruze project configuration, created by cruze {{cruze_version}}.
+# The format is described in .agents/skills/cruze-formats/reference/config.md.
+version: 1
+project: {{project_name_quoted}}
+
+# Where work items are tracked. V1 supports markdown in the repository only.
+tracker: markdown
+
+# Source files `cruze check` inspects, and files `cruze trace` searches for
+# scenario IDs. Project-scope architecture design sets these.
+source: []
+tests: []
+
+# Budgets enforced by `cruze check`. List a file under exceptions, with a
+# reason, to allow it past a budget.
+check:
+  max_lines: 250
+  max_types: 5
+  exceptions: []
+
+# Layer rules, written by project-scope architecture design from the module map.
+layers: []
+
+# The project's commands, by name, such as `test: cargo test`. The
+# walking-skeleton change fills them in; `cruze land` copies them into AGENTS.md.
+commands: {}
+
+# How `cruze review` starts an agent in a fresh context to run a role, with the
+# prompt on standard input. The default lets Claude Code read the project and run
+# git and cruze. The verifier runs the system, so add the project's build and run
+# commands, such as "Bash(cargo:*)". For Codex, use ["codex", "exec", "-"].
+review:
+  command: ["claude", "-p", "--allowedTools", "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git show:*) Bash(cruze:*)"]

package/templates/init/gitattributes

@@ -0,0 +1,2 @@
+# Cruze journals are append-only, so parallel branches merge them by keeping every line.
+**/journal.jsonl merge=union