@printpractical/cruze 0.0.1 → 0.0.2

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"]         ;
                                           
 
                                 

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. */
                               
              
+                                                                                           
+                 
+                                                                                         
+                     
                   
                       
                    
@@ -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);
@@ -92,6 +100,8 @@ export function parseConfig(text        )               {
 
   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,

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/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,
   ]);

package/dist/domain/validation/work_item_rules.js

@@ -56,6 +56,9 @@ function itemProblems(view             , item          )            {
 }
 
 /** A feature's Changes table covers its deltas, and each change folder agrees with its row. */
+/** More changes than this, and one design review can't hold the whole feature: contradictions slip through to plan. */
+const MAX_CHANGES = 6;
+
 function featureScopeProblems(view             , feature          , delta       )            {
   const rows = readChangesTable(feature.doc);
   if (rows.length === 0) return [warning(feature.path, undefined, "not-designed", "the feature has no changes yet; architect designs and splits it")];
@@ -64,6 +67,10 @@ function featureScopeProblems(view             , feature          , delta
     [...readProgress(feature.doc).changes].filter(([, state]) => state === "landed").map(([change]) => change),
   );
   const names = rows.map((row) => row.change);
+  const extra = rows[MAX_CHANGES];
+  if (extra !== undefined) {
+    problems.push(warning(feature.path, extra.line, "feature-size", `the feature has ${rows.length} changes, over ${MAX_CHANGES}; split it into features a single design review can hold`));
+  }
   for (const row of rows) {
     if (!/^\d\d-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(row.change)) problems.push(error(feature.path, row.line, "change-name", `change "${row.change}" must be named NN-slug`));
     if (names.indexOf(row.change) !== names.lastIndexOf(row.change)) problems.push(error(feature.path, row.line, "change-name", `change ${row.change} is listed twice`));

package/dist/domain/versions/ci_pin.js

@@ -0,0 +1,40 @@
+/** The Cruze package CI runs through `npx --package=<spec>`, kept at the version the project installed. */
+
+                        
+               
+                                                                              
+                     
+                                                                                                   
+                         
+ 
+
+const FORMS                                                          = [
+  // The npm package: @printpractical/cruze@0.0.1
+  (spec, version) => (/^@printpractical\/cruze@[^/\s]+$/.test(spec) ? `@printpractical/cruze@${version}` : null),
+  // The release tarball: .../releases/download/v0.0.1/printpractical-cruze-0.0.1.tgz
+  (spec, version) => {
+    const m = /^(.*\/releases\/download\/)v[^/]+\/printpractical-cruze-[^/]+\.tgz$/.exec(spec);
+    return m === null ? null : `${m[1]}v${version}/printpractical-cruze-${version}.tgz`;
+  },
+  // The git repository at a release tag: github:PrintPractical/cruze#v0.0.1
+  (spec, version) => {
+    const m = /^(.*cruze(?:\.git)?)#v\d[^\s]*$/.exec(spec);
+    return m === null ? null : `${m[1]}#v${version}`;
+  },
+];
+
+/** Moves every `--package=<spec>` that runs Cruze in a CI workflow to the version. */
+export function repinCruze(ciText        , version        )        {
+  const repinned           = [];
+  const unrecognised           = [];
+  const text = ciText.replace(/--package=(\S+)(?=\s+cruze\b)/g, (whole, spec        ) => {
+    const moved = FORMS.map((form) => form(spec, version)).find((result) => result !== null);
+    if (moved === undefined || moved === null) {
+      if (!unrecognised.includes(spec)) unrecognised.push(spec);
+      return whole;
+    }
+    if (!repinned.includes(moved)) repinned.push(moved);
+    return `--package=${moved}`;
+  });
+  return { text, repinned, unrecognised };
+}

package/dist/domain/versions/cruze_version.js

@@ -0,0 +1,51 @@
+/** Which Cruze a project runs: recorded in `.cruze/config.yaml` by `cruze install`, compared with the CLI. */
+
+/** Orders two versions such as `0.0.1` and `0.1.0` by their numeric parts; a pre-release tag is ignored. */
+export function compareVersions(a        , b        )         {
+  const parts = (v        )           => (v.split("-")[0] ?? "").split(".").map((p) => Number.parseInt(p, 10) || 0);
+  const [x, y] = [parts(a), parts(b)];
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    const diff = (x[i] ?? 0) - (y[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+                         
+                                           
+                                                               
+                                                             
+
+/** How the project's recorded Cruze differs from the CLI running now, or undefined when they match. */
+export function versionSkew(cli        , recorded                    )                          {
+  if (recorded === undefined) {
+    return { kind: "unrecorded", message: `the project doesn't record which Cruze its skills came from; run \`cruze install\` to install the skills of this CLI (${cli}) and record it` };
+  }
+  const order = compareVersions(recorded, cli);
+  if (order < 0) {
+    return { kind: "skills-older", recorded, message: `the project's skills are from Cruze ${recorded}, older than this CLI (${cli}); run \`cruze install\` to update them and the CI pin` };
+  }
+  if (order > 0) {
+    return { kind: "cli-older", recorded, message: `the project uses Cruze ${recorded}, newer than this CLI (${cli}); upgrade the CLI as the README's "Upgrading" section says` };
+  }
+  return undefined;
+}
+
+/**
+ * The config text with `cruze:` set to the version. The line is replaced in place, or added
+ * after `version:`, so the file's comments and layout survive.
+ */
+export function withRecordedVersion(configText        , version        )         {
+  return withVersionLine(configText, "cruze", version);
+}
+
+/** The config text with a top-level version key, such as `cruze:` or `standards:`, set in place. */
+export function withVersionLine(configText        , key                       , version        )         {
+  const line = `${key}: ${JSON.stringify(version)}`;
+  const existing = new RegExp(`^${key}:.*$`, "m");
+  if (existing.test(configText)) return configText.replace(existing, line);
+  const anchor = key === "standards" ? /^cruze:.*$/m.exec(configText) ?? /^version:.*$/m.exec(configText) : /^version:.*$/m.exec(configText);
+  if (anchor === null) return `${line}\n${configText}`;
+  const end = anchor.index + anchor[0].length;
+  return `${configText.slice(0, end)}\n${line}${configText.slice(end)}`;
+}

package/dist/domain/versions/realign_notes.js

@@ -0,0 +1,72 @@
+import { compareVersions } from "./cruze_version.js";
+
+/**
+ * A realign note: one change in what Cruze expects of a project, shipped in
+ * `skills/realign/notes/<version>.md` so `realign` can bring existing code up to it.
+ */
+                              
+             
+                
+                  
+                                                                                      
+                                
+                                                                    
+               
+                                                                      
+                  
+                                                              
+               
+                   
+ 
+
+                              
+                       
+                     
+ 
+
+const APPLIES                                           = { "existing code": "existing", "new work only": "new" };
+
+/** Parses one version's notes file. Each note is a `### <id>: <title>` heading with facts under it. */
+export function parseRealignNotes(version        , text        )              {
+  const notes                = [];
+  const problems           = [];
+  const sections = text.split(/^### /m).slice(1);
+  for (const section of sections) {
+    const [heading = "", ...body] = section.split("\n");
+    const match = /^([a-z0-9]+(?:-[a-z0-9]+)*): (.+)$/.exec(heading.trim());
+    if (match === null) {
+      problems.push(`${version}: "### ${heading.trim()}" must read "### <id>: <title>"`);
+      continue;
+    }
+    const [, id = "", title = ""] = match;
+    const fact = (key        )                     => body.map((line) => new RegExp(`^- ${key}: (.+)$`).exec(line)?.[1]?.trim()).find((v) => v !== undefined);
+    const applies = APPLIES[fact("Applies to") ?? ""];
+    const rule = fact("Rule");
+    const detect = fact("Detect")?.replace(/`/g, "");
+    const ask = fact("Ask");
+    const migrate = fact("Migrate");
+    if (applies === undefined) problems.push(`${version} ${id}: "- Applies to:" must be "existing code" or "new work only"`);
+    if (rule === undefined) problems.push(`${version} ${id}: needs "- Rule:"`);
+    if (detect !== undefined && !/^(check|validate):[a-z-]+$/.test(detect)) problems.push(`${version} ${id}: "- Detect:" names a rule as check:<rule> or validate:<rule>`);
+    if (applies === "existing" && detect === undefined && ask === undefined) problems.push(`${version} ${id}: a note for existing code needs "- Detect:" or "- Ask:"`);
+    if (applies === "existing" && migrate === undefined) problems.push(`${version} ${id}: a note for existing code needs "- Migrate:"`);
+    notes.push({
+      id,
+      title,
+      version,
+      appliesTo: applies ?? "new",
+      rule: rule ?? "",
+      ...(detect === undefined ? {} : { detect }),
+      ...(ask === undefined ? {} : { ask }),
+      ...(migrate === undefined ? {} : { migrate }),
+    });
+  }
+  const ids = notes.map((n) => n.id);
+  ids.filter((id, i) => ids.indexOf(id) !== i).forEach((id) => problems.push(`${version}: note ${id} appears twice`));
+  return { notes, problems };
+}
+
+/** Notes after the version the code meets, up to and including the version installed. */
+export function notesBetween(notes               , standards        , target        )                {
+  return notes.filter((n) => compareVersions(n.version, standards) > 0 && compareVersions(n.version, target) <= 0);
+}

package/dist/domain/versions/rule_versions.js

@@ -0,0 +1,22 @@
+import { compareVersions } from "./cruze_version.js";
+
+/** The first release of Cruze. A project that records no `standards:` meets its expectations. */
+export const FIRST_RELEASE = "0.0.1";
+
+/**
+ * The release that introduced each rule reporting on existing code, keyed as `<command>:<rule>`.
+ * A rule newer than the project's `standards:` still reports, but can't fail CI until the project realigns.
+ * Every entry needs a realign note in `skills/realign/notes/<version>.md`; the bundle lint checks it.
+ */
+export const RULE_SINCE                         = {
+  "check:test-placement": "0.0.2",
+  "validate:outside-module-map": "0.0.2",
+  "validate:readme-overview": "0.0.2",
+  "validate:feature-size": "0.0.2",
+};
+
+/** Whether a rule arrived after the version the project's code meets, so it waits for `realign`. */
+export function isPending(command                      , rule        , standards        )          {
+  const since = RULE_SINCE[`${command}:${rule}`];
+  return since !== undefined && compareVersions(since, standards) > 0;
+}

package/dist/domain/versions/scheduled_exceptions.js

@@ -0,0 +1,41 @@
+import { parseDocument,               } from "yaml";
+
+/**
+ * `check.exceptions` entries that `realign` adds for findings a prefactor change will fix,
+ * and that landing that change removes. Edited through the YAML document, so comments survive.
+ */
+
+                            
+               
+               
+ 
+
+const scheduledReason = (version        , note        , ref        )         => `realign ${version} (${note}): scheduled in ${ref}`;
+
+/** The config text with an exception for each finding, naming the change that will fix it. */
+export function withScheduledExceptions(configText        , version        , ref        , findings             )         {
+  if (findings.length === 0) return configText;
+  const doc = parseDocument(configText);
+  const listed = new Set(((doc.getIn(["check", "exceptions"])                                                      )?.toJSON() ?? []).map((e) => e.path));
+  for (const finding of findings.filter((f, i) => !listed.has(f.path) && findings.findIndex((o) => o.path === f.path) === i)) {
+    doc.addIn(["check", "exceptions"], doc.createNode({ path: finding.path, reason: scheduledReason(version, finding.note, ref) }));
+  }
+  return render(doc);
+}
+
+/** The config text without the exceptions scheduled in a change, once it lands; unchanged when it had none. */
+export function withoutScheduledExceptions(configText        , ref        )                                      {
+  const doc = parseDocument(configText);
+  const exceptions = doc.getIn(["check", "exceptions"])                                                                                  ;
+  if (exceptions === undefined || !Array.isArray(exceptions.items)) return { text: configText, removed: [] };
+  const suffix = `: scheduled in ${ref}`;
+  const removed = exceptions.items.map((item) => item.toJSON()).filter((e) => e.reason?.endsWith(suffix)).map((e) => e.path ?? "");
+  if (removed.length === 0) return { text: configText, removed: [] };
+  exceptions.items = exceptions.items.filter((item) => !(item.toJSON().reason ?? "").endsWith(suffix));
+  return { text: render(doc), removed };
+}
+
+/** Renders without wrapping long lines or padding flow lists, so an edit changes only what it touches. */
+function render(doc          )         {
+  return doc.toString({ lineWidth: 0, flowCollectionPadding: false });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@printpractical/cruze",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Spec-driven development for coding agents: one living model of the system, small deltas, convergent review.",
   "license": "Apache-2.0",
   "author": "Chris Buchter",