@printpractical/cruze 0.0.1 → 0.0.2

package/src/adapters/inbound/cli/commands/realign.ts

@@ -0,0 +1,28 @@
+import { realignDone } from "../../../../app/use_cases/realign_done.ts";
+import { realignStatus } from "../../../../app/use_cases/realign_status.ts";
+import { UsageError, requireArgs, type CliContext, type CommandResult, type Options } from "../cli_context.ts";
+
+export async function runRealign(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
+  requireArgs(args, ["status|done"]);
+  if (args[0] === "status") {
+    const report = await realignStatus(context, { full: options.full });
+    const lines = [`Code meets Cruze ${report.standards}; the installed skills are ${report.target}${report.full ? " (full audit)" : ""}.`];
+    for (const note of report.notes) {
+      const open = note.findings.filter((f) => !f.waived);
+      const how = note.detect !== undefined ? `${open.length} open finding(s) from ${note.detect}` : `for the auditor: ${note.ask ?? ""}`;
+      lines.push(`${note.version} ${note.id}: ${note.title} (${how})`);
+      for (const f of open) lines.push(`  ${f.path}${f.line === undefined ? "" : `:${f.line}`} ${f.message}`);
+    }
+    if (report.newWorkOnly.length > 0) lines.push(`New work only, nothing to move: ${report.newWorkOnly.join(", ")}`);
+    if (report.notes.length === 0) lines.push("Nothing to realign.");
+    return { json: report, human: lines.join("\n") };
+  }
+  if (args[0] === "done") {
+    const report = await realignDone(context, options.change === undefined ? {} : { change: options.change });
+    const lines = [report.from === report.to ? `The code already meets Cruze ${report.to}.` : `The code now meets Cruze ${report.to}, up from ${report.from}.`];
+    if (report.scheduled !== undefined) lines.push(`${report.scheduled} fixes the rest.`);
+    if (report.excepted.length > 0) lines.push(`Listed under check.exceptions until it lands: ${report.excepted.join(", ")}`);
+    return { json: report, human: lines.join("\n") };
+  }
+  throw new UsageError(`cruze realign takes status or done, not "${args[0]}"`);
+}

package/src/adapters/inbound/cli/commands.ts

@@ -3,6 +3,7 @@ import { runCheck, runLand, runTrace } from "./commands/code.ts";
 import { runApprove, runNew, runValidate } from "./commands/documents.ts";
 import { runInit } from "./commands/init.ts";
 import { runInstall } from "./commands/install.ts";
+import { runRealign } from "./commands/realign.ts";
 import { runFeedback, runJournal } from "./commands/journal.ts";
 import { runAbandon, runFeatures, runRoadmap, runTask } from "./commands/progress.ts";
 import { runReviewCommand } from "./commands/review.ts";
@@ -26,6 +27,7 @@ export const COMMANDS: Record<string, { handler: Handler; usage: string }> = {
   check: { handler: runCheck, usage: "check [<file>...] [--ci]                          enforce layer rules and file budgets" },
   abandon: { handler: runAbandon, usage: "abandon <ref> --reason <text>                     archive a feature or standalone change that stops for good" },
   land: { handler: runLand, usage: "land [<ref>] [--override <reason>]                merge a verified change into the living docs" },
+  realign: { handler: runRealign, usage: "realign <status [--full]|done [--change <ref>]>    what the installed Cruze expects of existing code, and recording that the code meets it" },
 };
 
 export const USAGE = `Usage: cruze <command> [options]

package/src/adapters/inbound/cli/parse_command.ts

@@ -41,6 +41,7 @@ export function parseCommand(argv: string[]): ParsedCommand {
         gate: { type: "string" },
         override: { type: "string" },
         overlap: { type: "boolean", default: false },
+        full: { type: "boolean", default: false },
         round: { type: "string" },
         package: { type: "string" },
         replan: { type: "string", multiple: true, default: [] },
@@ -65,6 +66,7 @@ export function parseCommand(argv: string[]): ParsedCommand {
     file: values.file,
     ci: values.ci,
     overlap: values.overlap,
+    full: values.full,
     replan: values.replan,
     rebase: values.rebase,
     ...optional("name", values.name),

package/src/adapters/inbound/cli/run_cli.ts

@@ -1,3 +1,4 @@
+import { versionNotice } from "../../../app/use_cases/record_version.ts";
 import { CruzeError } from "../../../domain/cruze_error.ts";
 import { type CliContext, UsageError } from "./cli_context.ts";
 import { COMMANDS, USAGE } from "./commands.ts";
@@ -10,12 +11,17 @@ export interface Terminal {
   stdoutIsTerminal: boolean;
 }
 
+/** Commands that set the version themselves, or report the skew as a problem of their own. */
+const NO_VERSION_NOTICE = new Set(["init", "install", "validate"]);
+
 /**
  * Runs one CLI invocation and returns the exit code: 0 on success, 1 when a check fails or
  * an expected error occurs, 2 for usage errors. Agents get JSON on stdout; people get a summary on stderr.
+ * When the project's skills don't match this CLI, a note on stderr says so, even when the command fails.
  */
 export async function runCli(argv: string[], context: CliContext, terminal: Terminal): Promise<number> {
   let json = !terminal.stdoutIsTerminal || argv.includes("--json");
+  let notice: string | undefined;
   try {
     const parsed = parseCommand(argv);
     json ||= parsed.options.json;
@@ -30,6 +36,7 @@ export async function runCli(argv: string[], context: CliContext, terminal: Term
     }
     const command = COMMANDS[name];
     if (command === undefined) throw new UsageError(`Unknown command: ${name}`);
+    if (!NO_VERSION_NOTICE.has(name)) notice = await versionNotice(context.files, context.bundle.version);
     const result = await command.handler(context, args, parsed.options);
     terminal.stderr(result.human);
     if (json) terminal.stdout(JSON.stringify(result.json, null, 2));
@@ -46,5 +53,7 @@ export async function runCli(argv: string[], context: CliContext, terminal: Term
       return 1;
     }
     throw error;
+  } finally {
+    if (notice !== undefined) terminal.stderr(`cruze: note: ${notice}`);
   }
 }

package/src/app/project_context.ts

@@ -1,5 +1,5 @@
 import { buildProjectView, type ProjectView } from "../domain/project/project_view.ts";
-import { SNAPSHOT_ROOTS } from "../domain/project/layout.ts";
+import { PATHS, SNAPSHOT_ROOTS } from "../domain/project/layout.ts";
 import { journalPath, serializeEntry, type JournalEntry } from "../domain/journal.ts";
 import type { Bundle } from "./ports/bundle.ts";
 import type { Clock } from "./ports/clock.ts";
@@ -14,7 +14,7 @@ export interface ProjectDeps {
   bundle: Bundle;
 }
 
-/** Reads every document under docs/ and .cruze/ into a view. */
+/** Reads every document under docs/ and .cruze/, and the README, into a view. */
 export async function loadView(files: ProjectFiles): Promise<ProjectView> {
   const snapshot = new Map<string, string>();
   for (const root of SNAPSHOT_ROOTS) {
@@ -23,6 +23,8 @@ export async function loadView(files: ProjectFiles): Promise<ProjectView> {
       if (text !== undefined) snapshot.set(path, text);
     }
   }
+  const readme = await files.readText(PATHS.readme);
+  if (readme !== undefined) snapshot.set(PATHS.readme, readme);
   return buildProjectView(snapshot);
 }
 

package/src/app/use_cases/check_code.ts

@@ -2,6 +2,7 @@ import { factsOf } from "../../domain/elements.ts";
 import { checkSource, type CheckFinding } from "../../domain/check/check_source.ts";
 import { CruzeError } from "../../domain/cruze_error.ts";
 import { matchesAny } from "../../domain/glob.ts";
+import { FIRST_RELEASE, isPending } from "../../domain/versions/rule_versions.ts";
 import type { CruzeConfig } from "../../domain/config.ts";
 import type { ProjectView } from "../../domain/project/project_view.ts";
 import { resolveChange } from "../../domain/project/artifact_ref.ts";
@@ -18,7 +19,8 @@ export interface CheckReport {
 
 /**
  * Enforces layer rules and file budgets. Layer violations always fail; budget and
- * module-map warnings fail only with `ci`.
+ * module-map warnings fail only with `ci`. A rule newer than the project's `standards:`
+ * is pending: it reports, but fails nothing until the project realigns.
  */
 export async function checkCode(deps: ProjectDeps, options: { files?: string[]; ci: boolean }): Promise<CheckReport> {
   const view = await loadView(deps.files);
@@ -32,8 +34,11 @@ export async function checkCode(deps: ProjectDeps, options: { files?: string[];
     }
   }
   const only = options.files?.filter((file) => sources.has(file));
-  const findings = checkSource({ config, sources, modulePaths: modulePaths(view), ...(only === undefined ? {} : { only }) });
-  const failing = findings.filter((f) => f.severity === "error" || options.ci);
+  const standards = config.standards ?? FIRST_RELEASE;
+  const findings = checkSource({ config, sources, modulePaths: modulePaths(view), ...(only === undefined ? {} : { only }) }).map((f) =>
+    isPending("check", f.rule, standards) ? { ...f, pending: true as const } : f,
+  );
+  const failing = findings.filter((f) => f.pending !== true && (f.severity === "error" || options.ci));
   return { passed: failing.length === 0, checked: only?.length ?? sources.size, findings };
 }
 

package/src/app/use_cases/install_skills.ts

@@ -4,6 +4,7 @@ import { AGENT_SKILL_HOMES, SHARED_SKILLS_DIR, agentSkillHome, knownAgents } fro
 import { SKILL_FILE, installedSkillName, isInstalledSkillName, skillProblems } from "../../domain/skill.ts";
 import type { Bundle, BundledSkill } from "../ports/bundle.ts";
 import type { ProjectFiles } from "../ports/project_files.ts";
+import { recordVersion, refuseDowngrade, type VersionRecord } from "./record_version.ts";
 
 export interface InstallSkillsRequest {
   /** Agents to link skills for even when the project shows no sign of using them. */
@@ -15,12 +16,16 @@ export interface InstallSkillsReport {
   installed: string[];
   removed: string[];
   linked: Array<{ agent: string; dir: string }>;
+  /** The version recorded in .cruze/config.yaml, and the CI workflow's Cruze pin. */
+  recorded: VersionRecord;
 }
 
 /**
  * Replaces the project's Cruze skills with the bundled set. Skills are written to
  * the shared Agent Skills directory, and linked for every agent the project uses.
  * Skills without the Cruze prefix belong to the user and are never touched.
+ * The project then records this version, and its CI runs it too. An older CLI
+ * never replaces the skills of a project that moved to a newer one.
  */
 export async function installSkills(
   deps: { files: ProjectFiles; bundle: Bundle },
@@ -29,6 +34,7 @@ export async function installSkills(
   const { files, bundle } = deps;
   const skills = await bundle.skills();
   assertValid(skills);
+  await refuseDowngrade(files, bundle.version);
 
   const names = skills.map((skill) => installedSkillName(skill.folder));
   const removed = await removeStaleSkills(files, SHARED_SKILLS_DIR, names);
@@ -48,7 +54,8 @@ export async function installSkills(
     linked.push({ agent, dir: home.skillsDir });
   }
 
-  return { version: bundle.version, installed: names, removed, linked };
+  const recorded = await recordVersion(files, bundle.version);
+  return { version: bundle.version, installed: names, removed, linked, recorded };
 }
 
 function assertValid(skills: BundledSkill[]): void {

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 {

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[];
@@ -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);
@@ -92,6 +100,8 @@ export function parseConfig(text: string): ConfigResult {
 
   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,