@printpractical/cruze 0.0.1 → 0.0.3

package/dist/app/use_cases/realign_done.js

@@ -0,0 +1,45 @@
+import { CruzeError } from "../../domain/cruze_error.js";
+import { resolveArtifact } from "../../domain/project/artifact_ref.js";
+import { PATHS } from "../../domain/project/layout.js";
+import { withVersionLine } from "../../domain/versions/cruze_version.js";
+import { withScheduledExceptions } from "../../domain/versions/scheduled_exceptions.js";
+import { appendJournal, loadView,                  } from "../project_context.js";
+import { realignStatus } from "./realign_status.js";
+
+                              
+               
+             
+                                                                    
+                     
+                                                                       
+                     
+ 
+
+/**
+ * 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             , options                     )                       {
+  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                    ;
+  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/dist/app/use_cases/realign_status.js

@@ -0,0 +1,106 @@
+import { CruzeError } from "../../domain/cruze_error.js";
+                                                          
+import { PATHS } from "../../domain/project/layout.js";
+                                                                        
+import { validateProject } from "../../domain/validation/validate_project.js";
+import { notesBetween, parseRealignNotes,                  } from "../../domain/versions/realign_notes.js";
+import { FIRST_RELEASE } from "../../domain/versions/rule_versions.js";
+                                                 
+import { loadView,                  } from "../project_context.js";
+import { checkCode } from "./check_code.js";
+
+export const REALIGN_SKILL = "realign";
+
+                                 
+               
+                
+                  
+                                                             
+                  
+ 
+
+                                                        
+                                                                        
+                             
+ 
+
+                                
+                                                                                 
+                    
+                 
+                
+                                                                                                              
+                             
+                                                                          
+                        
+                                            
+               
+ 
+
+/**
+ * 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             , options                   )                         {
+  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)                    => {
+    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        , path        )         {
+  return `${note}: ${path}`;
+}
+
+/** The project's config, once its skills come from this CLI; realign works from the installed notes. */
+export function requireInstalled(view             , version        )              {
+  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        )                         {
+  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             )              {
+  return new Set(
+    view.journal
+      .filter((e) => e.event === "disposition" && e["review"] === "realign" && e["disposition"] === "waived")
+      .map((e) => String(e["finding"])),
+  );
+}

package/dist/app/use_cases/record_version.js

@@ -0,0 +1,56 @@
+import { CruzeError } from "../../domain/cruze_error.js";
+import { PATHS } from "../../domain/project/layout.js";
+import { repinCruze } from "../../domain/versions/ci_pin.js";
+import { compareVersions, versionSkew, withRecordedVersion } from "../../domain/versions/cruze_version.js";
+                                                              
+
+export const CI_WORKFLOW = ".github/workflows/ci.yml";
+
+                                
+                                                                       
+                
+             
+                                                                                           
+                                                     
+ 
+
+/** The version the project's config records, read without requiring the rest of the config to be valid. */
+export async function recordedVersion(files              )                              {
+  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              , version        )                              {
+  const text = await files.readText(PATHS.config);
+  return text === undefined ? undefined : versionSkew(version, versionIn(text))?.message;
+}
+
+function versionIn(configText        )                     {
+  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              , version        )                {
+  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              , version        )                         {
+  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/dist/app/use_cases/run_review.js

@@ -4,7 +4,7 @@ import { featureOf } from "../../domain/project/work_items.js";
                                                             
 import { loadView,                  } from "../project_context.js";
 
-export const ROLES = ["design-reviewer", "code-reviewer", "verifier", "researcher"]         ;
+export const ROLES = ["design-reviewer", "code-reviewer", "verifier", "researcher", "auditor"]         ;
                                           
 
                                 
@@ -18,16 +18,19 @@ export const ROLES = ["design-reviewer", "code-reviewer", "verifier", "researche
                 
  
 
-                               
-             
-                
-                    
-                 
- 
+/**
+ * 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.
+ */
+                                                                                
+                                          
+                                                                    
+  
 
 /**
  * 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                                       , request               )                        {
   if (!(ROLES                     ).includes(request.role)) throw new CruzeError("unknown-role", `the roles are ${ROLES.join(", ")}`);
@@ -55,12 +58,23 @@ export async function runReview(deps                                       , 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               = { 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                    )         {
+  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             , role      )                  {

package/dist/app/use_cases/validate_project.js

@@ -1,5 +1,8 @@
 import { hasErrors, validateProject } from "../../domain/validation/validate_project.js";
-                                                                  
+import { warning,              } from "../../domain/validation/problem.js";
+import { PATHS } from "../../domain/project/layout.js";
+import { versionSkew } from "../../domain/versions/cruze_version.js";
+                                                 
 import { loadView } from "../project_context.js";
                                                               
 
@@ -10,9 +13,12 @@ import { loadView } from "../project_context.js";
                       
  
 
-/** Checks every document in the project against the cruze-formats rules. */
-export async function validate(deps                         )                          {
-  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                                         )                          {
+  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/dist/domain/check/check_source.js

@@ -6,10 +6,12 @@ import { countTypes } from "./type_count.js";
                                
                
                 
-                                                                                
+                                                                                                   
                   
                                                                            
                                 
+                                                                                                                              
+                 
  
 
                              
@@ -56,9 +58,28 @@ export function checkSource(input            )                 {
     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        , modulePaths          )          {
+  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        )          {
+  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/dist/domain/config.js

@@ -3,6 +3,10 @@ import { parse as parseYaml } from "yaml";
 /** `.cruze/config.yaml`, as described in the cruze-formats skill. */
                               
              
+                                                                                           
+                 
+                                                                                         
+                     
                   
                       
                    
@@ -15,13 +19,13 @@ import { parse as parseYaml } from "yaml";
                   
                                                                                 
                                    
-                                                                                              
-                                
+     
+                                                                                          
+                                                                                  
+     
+                                 
  
 
-/** 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:*)"];
-
                         
                
                   
@@ -43,6 +47,10 @@ export function parseConfig(text        )               {
   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        )               {
     }
   }
   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              = {
     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        )               {
     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/dist/domain/journal.js

@@ -9,7 +9,7 @@
 
 /** Events other tools and skills record, with the fields each requires. */
 export const RECORDED_EVENTS                           = {
-  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                           = {
   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                           = {
+  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                           = {
   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        )         {
   return `${folder}/journal.jsonl`;
 }
@@ -53,10 +67,20 @@ export function serializeEntry(entry              )         {
 export function recordedEventProblems(event        , fields                        )           {
   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                        )                                  {
+  return Object.fromEntries(Object.entries(fields).map(([key, value]) => [key, COUNT_FIELDS.includes(key) ? Number(value) : value]));
+}

package/dist/domain/project/layout.js

@@ -4,6 +4,7 @@
                                                    
 
 export const PATHS = {
+  readme: "README.md",
   vision: "docs/vision.md",
   glossary: "docs/glossary.md",
   architecture: "docs/architecture.md",

package/dist/domain/scaffold.js

@@ -11,12 +11,26 @@ export const INIT_SCAFFOLD                           = [
   { 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"]         ;
+                                                     
+
+/** 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           )         {
+  return `init/review/${agent}.yaml`;
+}
+
 /** Replaces every `{{key}}` with its value; an unknown key is a template bug. */
 export function renderTemplate(template        , values                        )         {
   return template.replace(/\{\{([a-z_]+)\}\}/g, (placeholder, key        ) => {

package/dist/domain/status/next_step.js

@@ -5,12 +5,14 @@ import { readProgress } from "../project/progress.js";
                                                               
 import { readRoadmapItems, readRoadmapStatus } from "../project/roadmap.js";
 import { changesOf, featureOf,               } from "../project/work_items.js";
+import { compareVersions } from "../versions/cruze_version.js";
+import { FIRST_RELEASE } from "../versions/rule_versions.js";
 import { isVerified } from "./verification.js";
 import { activeChange } from "./work_status.js";
 
 /** The Cruze step to run next, computed from the project's state and the current branch. */
 
-                                                                                                                             
+                                                                                                                                         
 
                            
              
@@ -31,12 +33,27 @@ export function nextSteps(view             , branch               )
   const active = activeChange(view, branch);
   const inFlight = view.items.filter((item) => !item.archived && item.kind !== "change").flatMap((item) => itemSteps(view, item, branch));
   const roadmap = roadmapStep(view);
-  const candidates = [...(active === undefined ? [] : [changeStep(view, active, branch)]), ...inFlight, ...(roadmap === null ? [] : [roadmap])];
+  const realign = realignStep(view);
+  const candidates = [
+    ...(active === undefined ? [] : [changeStep(view, active, branch)]),
+    ...inFlight,
+    ...(roadmap === null ? [] : [roadmap]),
+    ...(realign === null ? [] : [realign]),
+  ];
   const unique = candidates.filter((c, i) => candidates.findIndex((o) => o.step === c.step && o.target === c.target) === i);
   const [next, ...also] = unique;
   return { next: next ?? { step: "roadmap", reason: "every item on the roadmap has landed; close the release and plan the next" }, also };
 }
 
+/** Realign comes when nothing else is due: the installed skills expect more than the code meets. */
+function realignStep(view             )                  {
+  const config = view.config?.config;
+  if (config?.cruze === undefined) return null;
+  const standards = config.standards ?? FIRST_RELEASE;
+  if (compareVersions(standards, config.cruze) >= 0) return null;
+  return { step: "realign", target: config.cruze, reason: `the code meets Cruze ${standards}'s expectations, and the installed skills are ${config.cruze}` };
+}
+
 /** The project documents come first: nothing else can proceed without them. */
 function projectStep(view             )                  {
   const docs                                                                                      = [

package/dist/domain/validation/plan_rules.js

@@ -1,8 +1,10 @@
+import { insideModuleMap } from "../check/check_source.js";
 import { factsOf, isUnbuilt } from "../elements.js";
+import { matchesAny } from "../glob.js";
 import { findIds, kindOf } from "../ids.js";
                                                   
                                                   
-import { isPlanned, readScope, readTasks, readTestPlan,            } from "../project/plan_parts.js";
+import { isPlanned, readScope, readTasks, readTestPlan,                       } from "../project/plan_parts.js";
                                                               
 import { error, warning,              } from "./problem.js";
 
@@ -37,6 +39,7 @@ export function changePlanProblems(
       problems.push(error(path, task.line, "unknown-id", `${task.number} proves ${id}, which is not defined`));
     }
   }
+  problems.push(...outsideModuleMap(view, path, tasks, delta));
   for (const id of [...scope.delivers, ...scope.builds]) {
     if (kindOf(id) === "MOD") {
       const modulePaths = modulePathsOf(view, delta.doc, delta.delta, id);
@@ -103,3 +106,17 @@ function factsOfScoped(view             , doc             , delta       , id
 function modulePathsOf(view             , doc             , delta       , id        )           {
   return (factsOfScoped(view, doc, delta, id).get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? "")).filter((p) => p !== "");
 }
+
+/** Task paths that `cruze check` would report as outside every module, caught while the plan can still fix the module map. */
+function outsideModuleMap(view             , path        , tasks        , delta                                    )            {
+  const source = view.config?.config?.source ?? [];
+  const removed = new Set(delta.delta.entries.filter((e) => e.element.op === "REMOVED").map((e) => e.element.id));
+  const modules = new Set([...view.living.elements.keys(), ...delta.delta.entries.map((e) => e.element.id)].filter((id) => kindOf(id) === "MOD" && !removed.has(id)));
+  const modulePaths = [...modules].flatMap((id) => modulePathsOf(view, delta.doc, delta.delta, id));
+  if (modulePaths.length === 0) return [];
+  return tasks.flatMap((task) =>
+    task.paths
+      .filter((file) => matchesAny(file, source) && !insideModuleMap(file, modulePaths))
+      .map((file) => warning(path, task.line, "outside-module-map", `${task.number} writes ${file}, which no module's Path covers; add it to a module's Path or move the file`)),
+  );
+}

package/dist/domain/validation/project_rules.js

@@ -7,7 +7,7 @@ import { readRoadmapItems } from "../project/roadmap.js";
                                                               
 import { error, warning,              } from "./problem.js";
 
-/** Rules that span the project: leftover template guides, the roadmap and the config. */
+/** Rules that span the project: leftover template guides, the roadmap, the config and the README. */
 
 const GUIDE = /(?<!`)<(?!!--|\/|https?:|br\b)[A-Za-z][^<>\n]*>(?!`)/;
 const PLACEHOLDER = /\{\{[a-z_]+\}\}/;
@@ -97,3 +97,19 @@ export function configProblems(view             )            {
 function modulePaths(doc             , element                               )           {
   return (factsOf(doc, element).get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? ""));
 }
+
+/**
+ * Once the vision is approved, the README says what the project is under its title.
+ * Images, badges and HTML lines don't count as that overview.
+ */
+export function readmeProblems(view             )            {
+  const text = view.snapshot.get(PATHS.readme);
+  const visionApproved = [...view.approvals.values()].some((file) => file.approvals.some((record) => record.artifact === PATHS.vision));
+  if (text === undefined || !visionApproved) return [];
+  const doc = parseMarkdown(text);
+  const title = doc.lines.findIndex((line) => /^# /.test(line));
+  const next = doc.lines.findIndex((line, i) => i > title && /^#{1,6} /.test(line));
+  const intro = doc.lines.slice(title + 1, next === -1 ? undefined : next);
+  const overview = intro.some((line, i) => !doc.inFence[title + 1 + i] && line.trim() !== "" && !/^\s*(!\[|\[!\[|<)/.test(line));
+  return overview ? [] : [warning(PATHS.readme, Math.max(title, 0), "readme-overview", "add a paragraph under the title saying what the project is, who it is for and why, from docs/vision.md")];
+}

package/dist/domain/validation/validate_project.js

@@ -1,7 +1,7 @@
                                                               
 import { livingProblems } from "./living_rules.js";
 import { error, sortProblems,              } from "./problem.js";
-import { configProblems, roadmapProblems, templateLeftovers } from "./project_rules.js";
+import { configProblems, readmeProblems, roadmapProblems, templateLeftovers } from "./project_rules.js";
 import { workItemProblems } from "./work_item_rules.js";
 
 /** Every rule in the cruze-formats skill, applied to the whole project. */
@@ -16,6 +16,7 @@ export function validateProject(view             )            {
     ...roadmapProblems(view),
     ...workItemProblems(view),
     ...templateLeftovers(view),
+    ...readmeProblems(view),
     ...approvalProblems,
     ...journalProblems,
   ]);