@printpractical/cruze 0.0.1 → 0.0.3

package/src/app/use_cases/journal_events.ts

@@ -1,5 +1,5 @@
 import { CruzeError } from "../../domain/cruze_error.ts";
-import { recordedEventProblems, type JournalEntry } from "../../domain/journal.ts";
+import { recordedEventProblems, recordedFields, type JournalEntry } from "../../domain/journal.ts";
 import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
 import { appendJournal, loadView, type ProjectDeps } from "../project_context.ts";
 
@@ -8,13 +8,14 @@ export async function recordEvent(deps: ProjectDeps, event: string, fields: Reco
   const problems = recordedEventProblems(event, fields);
   if (problems.length > 0) throw new CruzeError("invalid-event", problems.join("; "));
   let folder = ".cruze";
+  let recorded = recordedFields(fields);
   if (item !== undefined) {
     const resolved = resolveArtifact(await loadView(deps.files), item).item;
     if (resolved === undefined) throw new CruzeError("not-found", `"${item}" is not a feature or change`);
     folder = resolved.folder;
-    fields = { ...fields, item: resolved.ref };
+    recorded = { ...recorded, item: resolved.ref };
   }
-  return appendJournal(deps, folder, event, { ...fields, cruze: deps.bundle.version });
+  return appendJournal(deps, folder, event, { ...recorded, cruze: deps.bundle.version });
 }
 
 export async function listEvents(deps: ProjectDeps, event?: string): Promise<JournalEntry[]> {

package/src/app/use_cases/land_change.ts

@@ -15,6 +15,7 @@ import { changesOf, featureOf, type WorkItem } from "../../domain/project/work_i
 import { isVerified } from "../../domain/status/verification.ts";
 import { activeChange } from "../../domain/status/work_status.ts";
 import { validateProject } from "../../domain/validation/validate_project.ts";
+import { withoutScheduledExceptions } from "../../domain/versions/scheduled_exceptions.ts";
 import { appendJournal, loadView, withFiles, type ProjectDeps } from "../project_context.ts";
 
 const AGENTS_FILE = "AGENTS.md";
@@ -26,6 +27,8 @@ export interface LandReport {
   removed: string[];
   restamped: string[];
   finished: boolean;
+  /** Files whose `check.exceptions` entry `realign` scheduled in this change, removed now that it lands. */
+  unexcepted: string[];
   archivedTo?: string;
 }
 
@@ -54,7 +57,9 @@ export async function landChange(deps: ProjectDeps, ref?: string, options: { ove
   const landed = `${deps.clock.today()}${commit === null ? "" : ` (${commit})`}`;
   const books = applyBookkeeping(view, change, source, landed, plan.files);
   const merged = withFiles(view, plan.files);
-  requireStillValid(view, merged);
+  const recorded = { ...(merged.approvals.get(source.folder) ?? { version: 1, approvals: [], merged: {} }), merged: plan.merged };
+  const checked = withFiles(merged, new Map([[approvalsPath(source.folder), serializeApprovals(recorded)]]));
+  requireStillValid(view, checked, [source.path, ...changesOf(view.items, source).map((c) => c.path)]);
 
   const approvals = new Map<string, ApprovalsFile>();
   const by = (await deps.repository.userName()) ?? "unknown";
@@ -81,8 +86,9 @@ export async function landChange(deps: ProjectDeps, ref?: string, options: { ove
     const rendered = renderAgentsFile(agents, merged);
     if (rendered !== agents) await deps.files.writeText(AGENTS_FILE, rendered);
   }
+  const unexcepted = await clearScheduledExceptions(deps, [change.ref, source.ref]);
 
-  const report: LandReport = { change: change.ref, merged: plan.mergedIds, built: plan.built, removed: plan.removed, restamped: restamp, finished: books.finished };
+  const report: LandReport = { change: change.ref, merged: plan.mergedIds, built: plan.built, removed: plan.removed, restamped: restamp, finished: books.finished, unexcepted };
   if (books.archive !== undefined) report.archivedTo = books.archive.to;
   return report;
 }
@@ -102,12 +108,27 @@ function requireReady(view: ProjectView, change: WorkItem, source: WorkItem): vo
   if (reasons.length > 0) throw new CruzeError("not-ready", `${change.ref} cannot land yet:\n  ${reasons.join("\n  ")}`);
 }
 
-/** The merge may not introduce errors into the living docs. */
-function requireStillValid(before: ProjectView, after: ProjectView): void {
+/** The merge may not introduce errors into the living docs, or into the work it lands, such as a citation of an ID it removes. */
+function requireStillValid(before: ProjectView, after: ProjectView, work: string[]): void {
   const key = (p: { path: string; message: string }): string => `${p.path}|${p.message}`;
   const existing = new Set(validateProject(before).map(key));
-  const introduced = validateProject(after).filter((p) => p.severity === "error" && p.path.startsWith("docs/") && !existing.has(key(p)));
+  const watched = (path: string): boolean => path.startsWith("docs/") || work.includes(path);
+  const introduced = validateProject(after).filter((p) => p.severity === "error" && watched(p.path) && !existing.has(key(p)));
   if (introduced.length > 0) {
-    throw new CruzeError("merge-invalid", `landing would break the living docs; nothing was written:\n  ${introduced.map((p) => `${p.path}:${p.line ?? ""} ${p.message}`).join("\n  ")}`);
+    throw new CruzeError("merge-invalid", `landing would leave errors behind; nothing was written:\n  ${introduced.map((p) => `${p.path}:${p.line ?? ""} ${p.message}`).join("\n  ")}`);
   }
 }
+
+/** Removes the exceptions `realign` scheduled in the landed work, so CI checks those files again. */
+async function clearScheduledExceptions(deps: ProjectDeps, refs: string[]): Promise<string[]> {
+  let text = await deps.files.readText(PATHS.config);
+  if (text === undefined) return [];
+  const removed: string[] = [];
+  for (const ref of [...new Set(refs)]) {
+    const result = withoutScheduledExceptions(text, ref);
+    text = result.text;
+    removed.push(...result.removed);
+  }
+  if (removed.length > 0) await deps.files.writeText(PATHS.config, text);
+  return removed;
+}

package/src/app/use_cases/realign_done.ts

@@ -0,0 +1,45 @@
+import { CruzeError } from "../../domain/cruze_error.ts";
+import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
+import { PATHS } from "../../domain/project/layout.ts";
+import { withVersionLine } from "../../domain/versions/cruze_version.ts";
+import { withScheduledExceptions } from "../../domain/versions/scheduled_exceptions.ts";
+import { appendJournal, loadView, type ProjectDeps } from "../project_context.ts";
+import { realignStatus } from "./realign_status.ts";
+
+export interface RealignDone {
+  from: string;
+  to: string;
+  /** The change that fixes what is still open, when anything is. */
+  scheduled?: string;
+  /** Files listed under `check.exceptions` until that change lands. */
+  excepted: string[];
+}
+
+/**
+ * Moves `standards:` up to the installed Cruze once every mechanical finding is fixed, waived,
+ * or scheduled in a change. A scheduled `check` finding becomes an exception naming that change,
+ * so CI stays green until it lands, and landing it removes the exception.
+ */
+export async function realignDone(deps: ProjectDeps, options: { change?: string }): Promise<RealignDone> {
+  const status = await realignStatus(deps, { full: false });
+  if (status.standards === status.target) return { from: status.standards, to: status.target, excepted: [] };
+  const open = status.notes.flatMap((note) => note.findings.filter((f) => !f.waived).map((f) => ({ note, finding: f })));
+  let scheduled: string | undefined;
+  if (open.length > 0) {
+    if (options.change === undefined) {
+      const list = open.map(({ note, finding }) => `${note.id}: ${finding.path}${finding.line === undefined ? "" : `:${finding.line}`}`);
+      throw new CruzeError("realign-open", `fix, waive or schedule these first, then pass --change <ref> for the change that fixes the rest:\n  ${list.join("\n  ")}`);
+    }
+    const item = resolveArtifact(await loadView(deps.files), options.change).item;
+    if (item === undefined) throw new CruzeError("not-found", `"${options.change}" is not a feature or change; create the prefactor change first`);
+    scheduled = item.ref;
+  }
+
+  const excepted = open.filter(({ note }) => note.detect?.startsWith("check:") === true).map(({ note, finding }) => ({ path: finding.path, note: note.id }));
+  const config = (await deps.files.readText(PATHS.config)) ?? "";
+  const withExceptions = scheduled === undefined ? config : withScheduledExceptions(config, status.target, scheduled, excepted);
+  await deps.files.writeText(PATHS.config, withVersionLine(withExceptions, "standards", status.target));
+  const paths = [...new Set(excepted.map((e) => e.path))];
+  await appendJournal(deps, ".cruze", "realign", { from: status.standards, to: status.target, ...(scheduled === undefined ? {} : { scheduled }), excepted: paths });
+  return { from: status.standards, to: status.target, ...(scheduled === undefined ? {} : { scheduled }), excepted: paths };
+}

package/src/app/use_cases/realign_status.ts

@@ -0,0 +1,106 @@
+import { CruzeError } from "../../domain/cruze_error.ts";
+import type { CruzeConfig } from "../../domain/config.ts";
+import { PATHS } from "../../domain/project/layout.ts";
+import type { ProjectView } from "../../domain/project/project_view.ts";
+import { validateProject } from "../../domain/validation/validate_project.ts";
+import { notesBetween, parseRealignNotes, type RealignNote } from "../../domain/versions/realign_notes.ts";
+import { FIRST_RELEASE } from "../../domain/versions/rule_versions.ts";
+import type { Bundle } from "../ports/bundle.ts";
+import { loadView, type ProjectDeps } from "../project_context.ts";
+import { checkCode } from "./check_code.ts";
+
+export const REALIGN_SKILL = "realign";
+
+export interface RealignFinding {
+  path: string;
+  line?: number;
+  message: string;
+  /** Waived by an earlier realign, so never raised again. */
+  waived: boolean;
+}
+
+export interface RealignNoteReport extends RealignNote {
+  /** What the note's CLI rule reports now, for a note with `Detect`. */
+  findings: RealignFinding[];
+}
+
+export interface RealignStatus {
+  /** The version the code meets now, and the one the installed skills expect. */
+  standards: string;
+  target: string;
+  full: boolean;
+  /** Notes for existing code: those with findings to fix, waive or schedule, and those an auditor answers. */
+  notes: RealignNoteReport[];
+  /** Notes that change only new work, so nothing existing has to move. */
+  newWorkOnly: string[];
+  /** Mechanical findings not yet waived. */
+  open: number;
+}
+
+/**
+ * What realigning the project to its installed Cruze involves: the notes of every release
+ * since `standards:`, or of all releases with `full`, and what their CLI rules find now.
+ */
+export async function realignStatus(deps: ProjectDeps, options: { full: boolean }): Promise<RealignStatus> {
+  const view = await loadView(deps.files);
+  const config = requireInstalled(view, deps.bundle.version);
+  const standards = config.standards ?? FIRST_RELEASE;
+  const target = deps.bundle.version;
+  const notes = notesBetween(await bundledNotes(deps.bundle), options.full ? "0.0.0" : standards, target);
+  const waived = waivedFindings(view);
+  const check = (await checkCode(deps, { ci: false })).findings;
+  const problems = validateProject(view);
+  const report = notes.filter((n) => n.appliesTo === "existing").map((note): RealignNoteReport => {
+    const [command, rule] = (note.detect ?? ":").split(":");
+    const found = command === "check" ? check.filter((f) => f.rule === rule) : command === "validate" ? problems.filter((p) => p.rule === rule) : [];
+    const findings = found.map((f) => ({
+      path: f.path,
+      ...(f.line === undefined ? {} : { line: f.line }),
+      message: f.message,
+      // A check finding is waived by listing the file under check.exceptions, which also keeps CI green.
+      waived: command === "validate" && waived.has(findingKey(note.id, f.path)),
+    }));
+    return { ...note, findings };
+  });
+  return {
+    standards,
+    target,
+    full: options.full,
+    notes: report,
+    newWorkOnly: notes.filter((n) => n.appliesTo === "new").map((n) => n.id),
+    open: report.flatMap((n) => n.findings).filter((f) => !f.waived).length,
+  };
+}
+
+/** The key a realign disposition records for a mechanical finding, so a waiver can be matched later. */
+export function findingKey(note: string, path: string): string {
+  return `${note}: ${path}`;
+}
+
+/** The project's config, once its skills come from this CLI; realign works from the installed notes. */
+export function requireInstalled(view: ProjectView, version: string): CruzeConfig {
+  const config = view.config?.config;
+  if (config === null || config === undefined) throw new CruzeError("config", `fix ${PATHS.config} first; run cruze validate for details`);
+  if (config.cruze !== version) {
+    throw new CruzeError("install-first", `the project's skills are from Cruze ${config.cruze ?? "an unrecorded version"}, and this CLI is ${version}; run cruze install first`);
+  }
+  return config;
+}
+
+async function bundledNotes(bundle: Bundle): Promise<RealignNote[]> {
+  const skill = (await bundle.skills()).find((s) => s.folder === REALIGN_SKILL);
+  return (skill?.files ?? [])
+    .flatMap((file) => {
+      const version = /^notes\/(\d+\.\d+\.\d+)\.md$/.exec(file.path)?.[1];
+      return version === undefined ? [] : parseRealignNotes(version, file.text).notes;
+    });
+}
+
+/** Findings earlier realigns waived, by key. */
+function waivedFindings(view: ProjectView): Set<string> {
+  return new Set(
+    view.journal
+      .filter((e) => e.event === "disposition" && e["review"] === "realign" && e["disposition"] === "waived")
+      .map((e) => String(e["finding"])),
+  );
+}

package/src/app/use_cases/record_version.ts

@@ -0,0 +1,56 @@
+import { CruzeError } from "../../domain/cruze_error.ts";
+import { PATHS } from "../../domain/project/layout.ts";
+import { repinCruze } from "../../domain/versions/ci_pin.ts";
+import { compareVersions, versionSkew, withRecordedVersion } from "../../domain/versions/cruze_version.ts";
+import type { ProjectFiles } from "../ports/project_files.ts";
+
+export const CI_WORKFLOW = ".github/workflows/ci.yml";
+
+export interface VersionRecord {
+  /** The version the project recorded before, when it recorded one. */
+  from?: string;
+  to: string;
+  /** The CI workflow's Cruze specs after the edit, and those left for the user to move. */
+  ci: { repinned: string[]; unrecognised: string[] };
+}
+
+/** The version the project's config records, read without requiring the rest of the config to be valid. */
+export async function recordedVersion(files: ProjectFiles): Promise<string | undefined> {
+  const text = await files.readText(PATHS.config);
+  return text === undefined ? undefined : versionIn(text);
+}
+
+/** What to tell the user when a Cruze project's skills don't match this CLI; nothing outside a Cruze project. */
+export async function versionNotice(files: ProjectFiles, version: string): Promise<string | undefined> {
+  const text = await files.readText(PATHS.config);
+  return text === undefined ? undefined : versionSkew(version, versionIn(text))?.message;
+}
+
+function versionIn(configText: string): string | undefined {
+  return /^cruze:\s*["']?([^"'\s#]+)/m.exec(configText)?.[1];
+}
+
+/** Refuses to install older skills over a project that already moved to a newer Cruze. */
+export async function refuseDowngrade(files: ProjectFiles, version: string): Promise<void> {
+  const recorded = await recordedVersion(files);
+  if (recorded !== undefined && compareVersions(recorded, version) > 0) {
+    throw new CruzeError(
+      "older-cli",
+      `this project uses Cruze ${recorded}, and this CLI is ${version}; upgrade the CLI instead. To go back to ${version} on purpose, set cruze: in ${PATHS.config} first`,
+    );
+  }
+}
+
+/** Records the installed version in the config, and moves the CI workflow's Cruze to it. */
+export async function recordVersion(files: ProjectFiles, version: string): Promise<VersionRecord> {
+  const from = await recordedVersion(files);
+  const config = await files.readText(PATHS.config);
+  if (config !== undefined) {
+    const updated = withRecordedVersion(config, version);
+    if (updated !== config) await files.writeText(PATHS.config, updated);
+  }
+  const ci = await files.readText(CI_WORKFLOW);
+  const repin = ci === undefined ? { text: "", repinned: [], unrecognised: [] } : repinCruze(ci, version);
+  if (ci !== undefined && repin.text !== ci) await files.writeText(CI_WORKFLOW, repin.text);
+  return { ...(from === undefined ? {} : { from }), to: version, ci: { repinned: repin.repinned, unrecognised: repin.unrecognised } };
+}

package/src/app/use_cases/run_review.ts

@@ -4,7 +4,7 @@ import { featureOf } from "../../domain/project/work_items.ts";
 import type { AgentRunner } from "../ports/agent_runner.ts";
 import { loadView, type ProjectDeps } from "../project_context.ts";
 
-export const ROLES = ["design-reviewer", "code-reviewer", "verifier", "researcher"] as const;
+export const ROLES = ["design-reviewer", "code-reviewer", "verifier", "researcher", "auditor"] as const;
 export type Role = (typeof ROLES)[number];
 
 export interface ReviewRequest {
@@ -18,16 +18,19 @@ export interface ReviewRequest {
   base?: string;
 }
 
-export interface ReviewReport {
-  role: Role;
-  item?: string;
-  command: string[];
-  report: string;
-}
+/**
+ * The role's report, or, when the configured agent isn't installed, the prompt for the calling
+ * agent to run in a helper of its own.
+ */
+export type ReviewReport = { role: Role; item?: string; command?: string[] } & (
+  | { status: "reported"; report: string }
+  | { status: "run-in-helper"; instruction: string; prompt: string }
+);
 
 /**
  * Runs a Cruze role in a fresh agent context: the role's prompt, what it reviews, and nothing
- * from the conversation that produced the work. Returns the role's report as written.
+ * from the conversation that produced the work. Returns the role's report as written, or the
+ * prompt to run in a helper when the configured agent isn't installed.
  */
 export async function runReview(deps: ProjectDeps & { runner: AgentRunner }, request: ReviewRequest): Promise<ReviewReport> {
   if (!(ROLES as readonly string[]).includes(request.role)) throw new CruzeError("unknown-role", `the roles are ${ROLES.join(", ")}`);
@@ -55,12 +58,23 @@ export async function runReview(deps: ProjectDeps & { runner: AgentRunner }, req
     context.map((line) => `- ${line}`).join("\n"),
   ].join("\n\n");
 
-  const command = view.config?.config?.review.command ?? [];
+  const subject = { role, ...(request.item === undefined ? {} : { item: request.item }) };
+  const command = view.config?.config?.review.command;
+  if (command === undefined) return { ...subject, status: "run-in-helper", instruction: helperInstruction(undefined), prompt };
   const run = await deps.runner.run(command, prompt);
+  if (run.kind === "missing") return { ...subject, command, status: "run-in-helper", instruction: helperInstruction(command[0]), prompt };
   if (run.exitCode !== 0) throw new CruzeError("review-failed", `${command.join(" ")} exited with ${run.exitCode}: ${run.error.trim() || run.output.trim()}`);
-  const report: ReviewReport = { role, command, report: run.output.trim() };
-  if (request.item !== undefined) report.item = request.item;
-  return report;
+  return { ...subject, command, status: "reported", report: run.output.trim() };
+}
+
+/** Why cruze review can't start the fresh context itself, and how the calling agent does instead. */
+function helperInstruction(program: string | undefined): string {
+  return [
+    program === undefined ? "No review agent is configured under review.command." : `${program} is not installed, so cruze review can't start a fresh context.`,
+    "Start a helper agent with no conversation history, give it this prompt and nothing else, and take its report as the role's report.",
+    "If you can't start a helper, tell the user, and have them run the prompt in a new session.",
+    "To have cruze review start an agent itself, set review.command in .cruze/config.yaml.",
+  ].join(" ");
 }
 
 async function bundledRole(deps: ProjectDeps, role: Role): Promise<string> {

package/src/app/use_cases/validate_project.ts

@@ -1,5 +1,8 @@
 import { hasErrors, validateProject } from "../../domain/validation/validate_project.ts";
-import type { Problem } from "../../domain/validation/problem.ts";
+import { warning, type Problem } from "../../domain/validation/problem.ts";
+import { PATHS } from "../../domain/project/layout.ts";
+import { versionSkew } from "../../domain/versions/cruze_version.ts";
+import type { Bundle } from "../ports/bundle.ts";
 import { loadView } from "../project_context.ts";
 import type { ProjectFiles } from "../ports/project_files.ts";
 
@@ -10,9 +13,12 @@ export interface ValidateReport {
   problems: Problem[];
 }
 
-/** Checks every document in the project against the cruze-formats rules. */
-export async function validate(deps: { files: ProjectFiles }): Promise<ValidateReport> {
-  const problems = validateProject(await loadView(deps.files));
+/** Checks every document in the project against the cruze-formats rules, and that its skills match this CLI. */
+export async function validate(deps: { files: ProjectFiles; bundle: Bundle }): Promise<ValidateReport> {
+  const view = await loadView(deps.files);
+  const config = view.config?.config;
+  const skew = config === null || config === undefined ? undefined : versionSkew(deps.bundle.version, config.cruze);
+  const problems = [...validateProject(view), ...(skew === undefined ? [] : [warning(PATHS.config, undefined, "cruze-version", skew.message)])];
   return {
     valid: !hasErrors(problems),
     errors: problems.filter((p) => p.severity === "error").length,

package/src/domain/check/check_source.ts

@@ -6,10 +6,12 @@ import { countTypes } from "./type_count.ts";
 export interface CheckFinding {
   path: string;
   line?: number;
-  rule: "layer" | "max-lines" | "max-types" | "outside-module-map" | "no-layer";
+  rule: "layer" | "max-lines" | "max-types" | "outside-module-map" | "no-layer" | "test-placement";
   message: string;
   /** Layer violations always fail; the rest fail in CI unless excepted. */
   severity: "error" | "warning";
+  /** Set when the rule is newer than the project's `standards:`: it reports, but can't fail CI until the project realigns. */
+  pending?: true;
 }
 
 export interface CheckInput {
@@ -56,9 +58,28 @@ export function checkSource(input: CheckInput): CheckFinding[] {
     if (!excepted && types !== null && types > config.check.maxTypes) {
       findings.push({ path, rule: "max-types", severity: "warning", message: `${types} top-level types, over the budget of ${config.check.maxTypes}` });
     }
-    if (modulePaths.length > 0 && !modulePaths.some((module) => (module.endsWith("/") ? path.startsWith(module) : path === module))) {
+    if (!excepted && isRustTestFileInSource(path)) {
+      findings.push({ path, rule: "test-placement", severity: "warning", message: "Rust tests that leave their inline module go in the crate's tests/ directory, not under src/" });
+    }
+    if (modulePaths.length > 0 && !insideModuleMap(path, modulePaths)) {
       findings.push({ path, rule: "outside-module-map", severity: "warning", message: "the file is outside every module in the architecture's module map" });
     }
   }
   return findings;
 }
+
+/** Whether a module's Path covers the file: a directory path ending in `/` covers everything under it, any other names one file. */
+export function insideModuleMap(path: string, modulePaths: string[]): boolean {
+  return modulePaths.some((module) => (module.endsWith("/") ? path.startsWith(module) : path === module));
+}
+
+/** A Rust file of tests split out of a module: `tests.rs`, `*_tests.rs`, or anything under a `tests/` folder inside `src/`. */
+function isRustTestFileInSource(path: string): boolean {
+  if (!path.endsWith(".rs")) return false;
+  const segments = path.split("/");
+  const inSource = segments.lastIndexOf("src");
+  if (inSource === -1) return false;
+  const below = segments.slice(inSource + 1);
+  const file = below.at(-1) ?? "";
+  return file === "tests.rs" || file.endsWith("_tests.rs") || below.slice(0, -1).includes("tests");
+}

package/src/domain/config.ts

@@ -3,6 +3,10 @@ import { parse as parseYaml } from "yaml";
 /** `.cruze/config.yaml`, as described in the cruze-formats skill. */
 export interface CruzeConfig {
   version: 1;
+  /** The Cruze version whose skills the project installed, recorded by `cruze install`. */
+  cruze?: string;
+  /** The Cruze version whose expectations the code meets, moved forward by `realign`. */
+  standards?: string;
   project: string;
   tracker: "markdown";
   source: string[];
@@ -15,13 +19,13 @@ export interface CruzeConfig {
   layers: Layer[];
   /** Named project commands, such as `test: cargo test`, shown in AGENTS.md. */
   commands: Record<string, string>;
-  /** How `cruze review` starts an agent in a fresh context: the program and its arguments. */
-  review: { command: string[] };
+  /**
+   * How `cruze review` starts an agent in a fresh context: the program and its arguments.
+   * Without one, the calling agent runs the role's prompt in a helper of its own.
+   */
+  review: { command?: string[] };
 }
 
-/** Claude Code in print mode, allowed to read the project, its history and run `cruze`, but not to edit. */
-export const DEFAULT_REVIEW_COMMAND = ["claude", "-p", "--allowedTools", "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git show:*) Bash(cruze:*)"];
-
 export interface Layer {
   name: string;
   paths: string[];
@@ -43,6 +47,10 @@ export function parseConfig(text: string): ConfigResult {
   if (root === null) return { config: null, problems: ["the file must be a YAML mapping"] };
 
   if (root["version"] !== 1) problems.push("version must be 1");
+  const cruze = root["cruze"];
+  if (cruze !== undefined && (typeof cruze !== "string" || cruze.trim() === "")) problems.push("cruze must be a version string, such as \"0.0.2\"");
+  const standards = root["standards"];
+  if (standards !== undefined && (typeof standards !== "string" || standards.trim() === "")) problems.push("standards must be a version string, such as \"0.0.2\"");
   if (typeof root["project"] !== "string" || root["project"] === "") problems.push("project must be a non-empty string");
   if (root["tracker"] !== "markdown") problems.push("tracker must be markdown");
   const source = stringList(root["source"], "source", problems);
@@ -87,11 +95,13 @@ export function parseConfig(text: string): ConfigResult {
     }
   }
   const review = asRecord(root["review"]) ?? {};
-  const reviewCommand = review["command"] === undefined ? DEFAULT_REVIEW_COMMAND : stringList(review["command"], "review.command", problems);
-  if (reviewCommand.length === 0) problems.push("review.command needs at least the program to run");
+  const reviewCommand = review["command"] === undefined ? undefined : stringList(review["command"], "review.command", problems);
+  if (reviewCommand?.length === 0) problems.push("review.command needs at least the program to run");
 
   const config: CruzeConfig = {
     version: 1,
+    ...(typeof cruze === "string" && cruze.trim() !== "" ? { cruze } : {}),
+    ...(typeof standards === "string" && standards.trim() !== "" ? { standards } : {}),
     project: typeof root["project"] === "string" ? root["project"] : "",
     tracker: "markdown",
     source,
@@ -99,7 +109,7 @@ export function parseConfig(text: string): ConfigResult {
     check: { maxLines: maxLines ?? 250, maxTypes: maxTypes ?? 5, exceptions },
     layers,
     commands,
-    review: { command: reviewCommand.length === 0 ? DEFAULT_REVIEW_COMMAND : reviewCommand },
+    review: reviewCommand === undefined || reviewCommand.length === 0 ? {} : { command: reviewCommand },
   };
   return { config, problems };
 }

package/src/domain/journal.ts

@@ -9,7 +9,7 @@ export interface JournalEntry {
 
 /** Events other tools and skills record, with the fields each requires. */
 export const RECORDED_EVENTS: Record<string, string[]> = {
-  rethink: ["level", "kind", "summary", "wrong", "caught_by"],
+  rethink: ["level", "kind", "summary", "wrong", "found_by"],
   disposition: ["finding", "disposition", "reason", "review"],
   review: ["review", "round", "blockers", "concerns"],
   override: ["gate", "reason"],
@@ -17,14 +17,28 @@ export const RECORDED_EVENTS: Record<string, string[]> = {
   verification: ["result", "summary"],
 };
 
+/** Fields an event may carry beyond its required ones, checked when present. A defect rethink must say which step missed it. */
+const OPTIONAL_FIELDS: Record<string, string[]> = {
+  rethink: ["missed_by"],
+  review: ["nits"],
+};
+
+/** The workflow steps and checks that find or miss a problem, so a retro can count them. */
+export const STEPS = ["envision", "architect", "research", "design-review", "walkthrough", "plan", "plan-review", "build", "code-review", "verify", "land", "realign", "validate", "check", "user"];
+
 export const FIELD_VALUES: Record<string, string[]> = {
   level: ["task", "change", "feature", "architecture", "vision"],
   kind: ["defect", "discovery"],
   disposition: ["fixed", "waived", "deferred", "rejected"],
-  review: ["design", "plan", "code"],
+  review: ["design", "plan", "code", "realign"],
   result: ["accepted", "sent-back"],
+  found_by: STEPS,
+  missed_by: STEPS,
 };
 
+/** Fields recorded as numbers rather than text. */
+const COUNT_FIELDS = ["round", "blockers", "concerns", "nits"];
+
 export function journalPath(folder: string): string {
   return `${folder}/journal.jsonl`;
 }
@@ -53,10 +67,20 @@ export function serializeEntry(entry: JournalEntry): string {
 export function recordedEventProblems(event: string, fields: Record<string, string>): string[] {
   const required = RECORDED_EVENTS[event];
   if (required === undefined) return [`unknown event "${event}"; recordable events: ${Object.keys(RECORDED_EVENTS).join(", ")}`];
-  const problems = required.filter((field) => (fields[field] ?? "").trim() === "").map((field) => `${event} needs ${field}`);
-  for (const [field, allowed] of Object.entries(FIELD_VALUES)) {
+  const needed = event === "rethink" && fields["kind"] === "defect" ? [...required, "missed_by"] : required;
+  const problems = needed.filter((field) => (fields[field] ?? "").trim() === "").map((field) => `${event} needs ${field}${field === "missed_by" ? " for a defect" : ""}`);
+  const known = [...required, ...(OPTIONAL_FIELDS[event] ?? [])];
+  for (const field of known) {
     const value = fields[field];
-    if (value !== undefined && required.includes(field) && !allowed.includes(value)) problems.push(`${field} must be one of ${allowed.join(", ")}`);
+    if (value === undefined) continue;
+    const allowed = FIELD_VALUES[field];
+    if (allowed !== undefined && !allowed.includes(value)) problems.push(`${field} must be one of ${allowed.join(", ")}`);
+    if (COUNT_FIELDS.includes(field) && !/^\d+$/.test(value)) problems.push(`${field} must be a whole number`);
   }
   return problems;
 }
+
+/** The fields as the journal stores them: counts become numbers. */
+export function recordedFields(fields: Record<string, string>): Record<string, string | number> {
+  return Object.fromEntries(Object.entries(fields).map(([key, value]) => [key, COUNT_FIELDS.includes(key) ? Number(value) : value]));
+}

package/src/domain/project/layout.ts

@@ -4,6 +4,7 @@
 export type Snapshot = ReadonlyMap<string, string>;
 
 export const PATHS = {
+  readme: "README.md",
   vision: "docs/vision.md",
   glossary: "docs/glossary.md",
   architecture: "docs/architecture.md",

package/src/domain/scaffold.ts

@@ -11,12 +11,26 @@ export const INIT_SCAFFOLD: readonly ScaffoldEntry[] = [
   { path: "README.md", template: "init/README.md" },
   { path: "CHANGELOG.md", template: "init/CHANGELOG.md" },
   { path: "AGENTS.md", template: "init/AGENTS.md" },
-  { path: "CLAUDE.md", template: "init/CLAUDE.md" },
   { path: ".cruze/config.yaml", template: "init/config.yaml" },
   { path: ".github/workflows/ci.yml", template: "init/ci.yml" },
   { path: ".gitattributes", template: "init/gitattributes" },
 ];
 
+/**
+ * The agents `cruze init` sets a project up for: Claude Code, which gets `CLAUDE.md`, linked skills
+ * and a review command, or any other agent, which reads `AGENTS.md` and `.agents/skills/`.
+ */
+export const INIT_AGENTS = ["claude", "other"] as const;
+export type InitAgent = (typeof INIT_AGENTS)[number];
+
+/** Claude Code reads `CLAUDE.md`, so init links it to `AGENTS.md` rather than keeping a second copy. */
+export const CLAUDE_INSTRUCTIONS = { path: "CLAUDE.md", target: "AGENTS.md" };
+
+/** The template for the config's `review:` setting, which only Claude Code gets filled in. */
+export function reviewSettingTemplate(agent: InitAgent): string {
+  return `init/review/${agent}.yaml`;
+}
+
 /** Replaces every `{{key}}` with its value; an unknown key is a template bug. */
 export function renderTemplate(template: string, values: Record<string, string>): string {
   return template.replace(/\{\{([a-z_]+)\}\}/g, (placeholder, key: string) => {