@printpractical/cruze 0.0.1 → 0.0.2

package/README.md

@@ -10,7 +10,7 @@ It works with any agent that supports the [Agent Skills](https://agentskills.io)
 
 ## Status
 
-Version 0.0.1 is the first preview. Early development. The CLI is complete for the V1 lifecycle. The document formats ship as the `cruze-formats` skill, the standards an agent designs and codes to ship as knowledge skills, and the whole workflow, from explore to land, ships as workflow skills. Claude Code is the agent tested so far.
+Version 0.0.2 is the second preview. It adds upgrading and `realign`, and the fixes from the first real project's retro. Early development. The CLI is complete for the V1 lifecycle. The document formats ship as the `cruze-formats` skill, the standards an agent designs and codes to ship as knowledge skills, and the whole workflow, from explore to land, ships as workflow skills. Claude Code is the agent tested so far.
 
 ## Why
 
@@ -35,7 +35,7 @@ The skills run `cruze` commands, so the agent needs `cruze` on its path. Install
 From a GitHub Release, without npm. Each release attaches the packed package:
 
 ```sh
-npm install -g https://github.com/PrintPractical/cruze/releases/download/v0.0.1/printpractical-cruze-0.0.1.tgz
+npm install -g https://github.com/PrintPractical/cruze/releases/download/v0.0.2/printpractical-cruze-0.0.2.tgz
 ```
 
 From npm, once a version is published there:
@@ -47,7 +47,7 @@ npm install -g @printpractical/cruze
 From the git repository, at a tag or `#main`. This needs git and access to the repository. npm 11 needs `--install-links` for a global git install, and the first `cruze` command builds the CLI, which takes a moment:
 
 ```sh
-npm install -g --install-links github:PrintPractical/cruze#v0.0.1
+npm install -g --install-links github:PrintPractical/cruze#v0.0.2
 ```
 
 ### 2. Set up a repository
@@ -61,7 +61,7 @@ cruze init
 When you didn't install from npm, tell `init` where Cruze came from, so the CI it writes runs the same source instead of the npm package:
 
 ```sh
-cruze init --package https://github.com/PrintPractical/cruze/releases/download/v0.0.1/printpractical-cruze-0.0.1.tgz
+cruze init --package https://github.com/PrintPractical/cruze/releases/download/v0.0.2/printpractical-cruze-0.0.2.tgz
 ```
 
 `init` asks for the project name, then creates:
@@ -72,24 +72,45 @@ cruze init --package https://github.com/PrintPractical/cruze/releases/download/v
 | `CHANGELOG.md` | In [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format |
 | `AGENTS.md` | Agent instructions; Cruze keeps its managed sections current |
 | `CLAUDE.md` | One line that imports `AGENTS.md`, for Claude Code |
-| `.cruze/config.yaml` | Project configuration |
+| `.cruze/config.yaml` | Project configuration, including the Cruze version whose skills the project uses |
 | `.github/workflows/ci.yml` | CI that runs `cruze validate`, `check` and `trace`; the walking-skeleton change adds the language's build and test steps |
 | `.gitattributes` | Merges Cruze's journals line by line, so parallel branches don't conflict on them |
 | `.agents/skills/cruze-*` | The Cruze skills, linked into `.claude/skills/` for Claude Code |
 
 Existing files are never overwritten, so it is safe to run in an existing repository.
 
-To upgrade, install the new version globally the same way, then update the skills in each repository:
+The CLI writes JSON to stdout when it isn't attached to a terminal, and a human summary to stderr. Pass `--json` to get JSON on a terminal too.
 
-```sh
-cruze install
-```
+## Upgrading
 
-Also update the version in `.github/workflows/ci.yml`.
+A repository runs three copies of Cruze: the CLI on your path, the skills in `.agents/skills/`, and the CLI that CI runs. `.cruze/config.yaml` records the version the skills came from, as `cruze: "0.0.2"`. When the CLI you run differs from it, every `cruze` command says so in a note on stderr, and `cruze validate` reports it as a `cruze-version` warning.
 
-`install` replaces the Cruze skills (those named `cruze-*`) and leaves your own skills alone. Pass `--agent claude` to link skills for Claude Code in a repository without `CLAUDE.md` or `.claude/`.
+It also records `standards:`, the version whose expectations the code meets. A release can expect more of existing code, such as where tests live. Its new rules report on your code right away, but they fail CI only once you realign to that release, so upgrading never turns CI red.
 
-The CLI writes JSON to stdout when it isn't attached to a terminal, and a human summary to stderr. Pass `--json` to get JSON on a terminal too.
+1. **Upgrade the CLI** the same way you installed it, naming the new version, then check it with `cruze --version`:
+
+   ```sh
+   npm install -g https://github.com/PrintPractical/cruze/releases/download/v<version>/printpractical-cruze-<version>.tgz
+   npm install -g @printpractical/cruze@<version>
+   npm install -g --install-links github:PrintPractical/cruze#v<version>
+   ```
+
+2. **Update each repository.** In its root, run:
+
+   ```sh
+   cruze install
+   ```
+
+   `install` does three things:
+   - It replaces the Cruze skills (those named `cruze-*`) and leaves your own skills alone. Pass `--agent claude` to link them for Claude Code in a repository without `CLAUDE.md` or `.claude/`.
+   - It records the new version in `.cruze/config.yaml`.
+   - It moves `.github/workflows/ci.yml` to the new version when CI runs the npm package, a release tarball or a release tag. It names any other source, such as a branch, for you to update by hand.
+
+3. **Commit** the skills, the config and the CI workflow together, with a message such as `chore: upgrade Cruze to <version>`, so CI runs the version the skills were written for.
+
+4. **Realign the code** when it suits you, with the `realign` skill. `cruze realign status` lists what each release since `standards:` expects of existing code: what its CLI rules find, and the questions a fresh-context auditor answers. You decide each finding: fix it in a prefactor change, waive it for good, or defer it. `cruze realign done` then moves `standards:` up. Findings still waiting for their prefactor are listed under `check.exceptions` until it lands, so CI stays green. Add `--full` to audit against every release, such as for a project that adopted Cruze partway. `cruze next` suggests realigning when nothing else is due.
+
+An older CLI refuses to install over a repository that already moved to a newer version, so a stale CLI on another machine can't roll it back. To go back on purpose, set `cruze:` in `.cruze/config.yaml` to the older version first, then run that version's `cruze install`.
 
 ## Commands
 
@@ -109,8 +130,10 @@ Skills call these at fixed points, and CI runs `check` and `trace` on every push
 | `cruze roadmap prune` | Clears landed items from the roadmap's status when a release closes |
 | `cruze trace` | Fails when a delivered scenario has no test carrying its ID; `--all` checks every built scenario |
 | `cruze check` | Enforces the layer rules and the file budgets; `--ci` also fails on budget warnings |
-| `cruze review <role>` | Runs a review role (design reviewer, code reviewer, verifier or researcher) in a fresh agent context, through the command in `.cruze/config.yaml` |
+| `cruze review <role>` | Runs a role (design reviewer, code reviewer, verifier, researcher or auditor) in a fresh agent context, through the command in `.cruze/config.yaml` |
 | `cruze land` | Merges a verified change into the living docs, re-stamps the approvals the merge would make stale, fills the Commands and Layout sections of `AGENTS.md`, and archives finished work |
+| `cruze realign status` | Lists what the installed Cruze expects of existing code since its `standards:` version, with what the CLI rules find now; `--full` covers every release |
+| `cruze realign done` | Moves `standards:` up once every finding is fixed, waived or scheduled in a change named with `--change` |
 | `cruze abandon <ref>` | Archives a feature or standalone change that stops for good, with its reason, and puts a feature back on the future list |
 | `cruze journal add <event>` | Records a rethink, review round, disposition, verification, override or bug; `cruze feedback export` bundles the journal for improving Cruze itself |
 
@@ -132,8 +155,9 @@ Stepping back is editing: change an upstream document and every approval that ci
 | `cruze-land` | Merges the change into the living docs and updates the changelog, README and `AGENTS.md`; also lands bug fixes |
 | `cruze-triage` | Reproduces a bug, finds its root cause against the living docs, and fixes it test-first or routes it to architect or rethink |
 | `cruze-rethink` | Steps back to the level a discovery touches, keeps completed work, re-approves what went stale and records why |
+| `cruze-realign` | Brings existing code up to what a new Cruze expects: audits it against each release's notes, decides every finding with you, and schedules the fixes as prefactor changes |
 | `cruze-next` | Says which step to run next and why |
-| `cruze-roles` | The fresh-context design reviewer, code reviewer, verifier and researcher, and how a review runs to a disposition for every finding |
+| `cruze-roles` | The fresh-context design reviewer, code reviewer, verifier, researcher and auditor, and how a review runs to a disposition for every finding |
 | `cruze-formats` | The format of every Cruze document, with templates |
 | `cruze-hexagonal-design` | Ports and adapters with domain-driven design: who owns each rule, dependency direction, many small modules, contracts, runtime ownership, and notes for Rust and C++ |
 | `cruze-behavioural-testing` | Which tests to write and at which seam, fakes instead of mocks, and protecting approved scenarios' tests |

package/dist/adapters/inbound/cli/cli_context.js

@@ -48,6 +48,7 @@
                 
                     
                    
+                
                    
                    
                  

package/dist/adapters/inbound/cli/commands/code.js

@@ -5,7 +5,7 @@ import { landChange } from "../../../../app/use_cases/land_change.js";
 export async function runCheck(context            , args          , options         )                         {
   const files = [...options.file, ...args];
   const report = await checkCode(context, { ci: options.ci, ...(files.length === 0 ? {} : { files }) });
-  const lines = report.findings.map((f) => `${f.severity} ${f.path}${f.line === undefined ? "" : `:${f.line}`} ${f.message} [${f.rule}]`);
+  const lines = report.findings.map((f) => `${f.severity} ${f.path}${f.line === undefined ? "" : `:${f.line}`} ${f.message} [${f.rule}]${f.pending === true ? " (pending realign)" : ""}`);
   lines.push(`Checked ${report.checked} file(s): ${report.passed ? "passed" : "failed"}.`);
   return { json: report, human: lines.join("\n"), failed: !report.passed };
 }
@@ -25,6 +25,7 @@ export async function runLand(context            , args          , options
   if (report.built.length > 0) lines.push(`Now built: ${report.built.join(", ")}`);
   if (report.removed.length > 0) lines.push(`Removed: ${report.removed.join(", ")}`);
   if (report.restamped.length > 0) lines.push(`Re-stamped approvals: ${report.restamped.join(", ")}`);
+  if (report.unexcepted.length > 0) lines.push(`CI checks these again, now that the change realign scheduled them in has landed: ${report.unexcepted.join(", ")}`);
   if (report.archivedTo !== undefined) lines.push(`Finished; archived to ${report.archivedTo}.`);
   return { json: report, human: lines.join("\n") };
 }

package/dist/adapters/inbound/cli/commands/install.js

@@ -11,5 +11,9 @@ export function describeSkillInstall(report                     )           {
   const lines = [`Installed ${count} Cruze skill${count === 1 ? "" : "s"} into .agents/skills/: ${report.installed.join(", ")}`];
   if (report.removed.length > 0) lines.push(`Removed skills no longer shipped: ${report.removed.join(", ")}`);
   for (const link of report.linked) lines.push(`Linked them for ${link.agent} in ${link.dir}/`);
+  const { from, to, ci } = report.recorded;
+  if (from !== to) lines.push(`Recorded Cruze ${to} in .cruze/config.yaml${from === undefined ? "" : `, up from ${from}`}`);
+  if (ci.repinned.length > 0) lines.push(`CI runs ${ci.repinned.join(", ")}`);
+  for (const spec of ci.unrecognised) lines.push(`CI runs ${spec}, which Cruze can't move to ${to}; update .github/workflows/ci.yml yourself`);
   return lines;
 }

package/dist/adapters/inbound/cli/commands/realign.js

@@ -0,0 +1,28 @@
+import { realignDone } from "../../../../app/use_cases/realign_done.js";
+import { realignStatus } from "../../../../app/use_cases/realign_status.js";
+import { UsageError, requireArgs,                                                   } from "../cli_context.js";
+
+export async function runRealign(context            , args          , options         )                         {
+  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/dist/adapters/inbound/cli/commands.js

@@ -3,6 +3,7 @@ import { runCheck, runLand, runTrace } from "./commands/code.js";
 import { runApprove, runNew, runValidate } from "./commands/documents.js";
 import { runInit } from "./commands/init.js";
 import { runInstall } from "./commands/install.js";
+import { runRealign } from "./commands/realign.js";
 import { runFeedback, runJournal } from "./commands/journal.js";
 import { runAbandon, runFeatures, runRoadmap, runTask } from "./commands/progress.js";
 import { runReviewCommand } from "./commands/review.js";
@@ -26,6 +27,7 @@ export const COMMANDS                                                      = {
   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/dist/adapters/inbound/cli/parse_command.js

@@ -41,6 +41,7 @@ export function parseCommand(argv          )                {
         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          )                {
     file: values.file,
     ci: values.ci,
     overlap: values.overlap,
+    full: values.full,
     replan: values.replan,
     rebase: values.rebase,
     ...optional("name", values.name),

package/dist/adapters/inbound/cli/run_cli.js

@@ -1,3 +1,4 @@
+import { versionNotice } from "../../../app/use_cases/record_version.js";
 import { CruzeError } from "../../../domain/cruze_error.js";
 import {                  UsageError } from "./cli_context.js";
 import { COMMANDS, USAGE } from "./commands.js";
@@ -10,12 +11,17 @@ import { parseCommand } from "./parse_command.js";
                             
  
 
+/** 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          , context            , terminal          )                  {
   let json = !terminal.stdoutIsTerminal || argv.includes("--json");
+  let notice                    ;
   try {
     const parsed = parseCommand(argv);
     json ||= parsed.options.json;
@@ -30,6 +36,7 @@ export async function runCli(argv          , context            , terminal
     }
     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          , context            , terminal
       return 1;
     }
     throw error;
+  } finally {
+    if (notice !== undefined) terminal.stderr(`cruze: note: ${notice}`);
   }
 }

package/dist/app/project_context.js

@@ -1,5 +1,5 @@
 import { buildProjectView,                  } from "../domain/project/project_view.js";
-import { SNAPSHOT_ROOTS } from "../domain/project/layout.js";
+import { PATHS, SNAPSHOT_ROOTS } from "../domain/project/layout.js";
 import { journalPath, serializeEntry,                   } from "../domain/journal.js";
                                                 
                                               
@@ -14,7 +14,7 @@ import { journalPath, serializeEntry,                   } from "../domain/journa
                  
  
 
-/** 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              )                       {
   const snapshot = new Map                ();
   for (const root of SNAPSHOT_ROOTS) {
@@ -23,6 +23,8 @@ export async function loadView(files              )                       {
       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/dist/app/use_cases/check_code.js

@@ -2,6 +2,7 @@ import { factsOf } from "../../domain/elements.js";
 import { checkSource,                   } from "../../domain/check/check_source.js";
 import { CruzeError } from "../../domain/cruze_error.js";
 import { matchesAny } from "../../domain/glob.js";
+import { FIRST_RELEASE, isPending } from "../../domain/versions/rule_versions.js";
                                                           
                                                                         
 import { resolveChange } from "../../domain/project/artifact_ref.js";
@@ -18,7 +19,8 @@ import { loadView,                  } from "../project_context.js";
 
 /**
  * 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             , options                                   )                       {
   const view = await loadView(deps.files);
@@ -32,8 +34,11 @@ export async function checkCode(deps             , options
     }
   }
   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          } : 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/dist/app/use_cases/install_skills.js

@@ -4,6 +4,7 @@ import { AGENT_SKILL_HOMES, SHARED_SKILLS_DIR, agentSkillHome, knownAgents } fro
 import { SKILL_FILE, installedSkillName, isInstalledSkillName, skillProblems } from "../../domain/skill.js";
                                                                
                                                               
+import { recordVersion, refuseDowngrade,                    } from "./record_version.js";
 
                                        
                                                                                      
@@ -15,12 +16,16 @@ import { SKILL_FILE, installedSkillName, isInstalledSkillName, skillProblems } f
                       
                     
                                                 
+                                                                                     
+                          
  
 
 /**
  * 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                                         ,
@@ -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                )       {

package/dist/app/use_cases/journal_events.js

@@ -1,5 +1,5 @@
 import { CruzeError } from "../../domain/cruze_error.js";
-import { recordedEventProblems,                   } from "../../domain/journal.js";
+import { recordedEventProblems, recordedFields,                   } from "../../domain/journal.js";
 import { resolveArtifact } from "../../domain/project/artifact_ref.js";
 import { appendJournal, loadView,                  } from "../project_context.js";
 
@@ -8,13 +8,14 @@ export async function recordEvent(deps             , event        , fields
   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             , event         )                          {

package/dist/app/use_cases/land_change.js

@@ -15,6 +15,7 @@ import { changesOf, featureOf,               } from "../../domain/project/work_i
 import { isVerified } from "../../domain/status/verification.js";
 import { activeChange } from "../../domain/status/work_status.js";
 import { validateProject } from "../../domain/validation/validate_project.js";
+import { withoutScheduledExceptions } from "../../domain/versions/scheduled_exceptions.js";
 import { appendJournal, loadView, withFiles,                  } from "../project_context.js";
 
 const AGENTS_FILE = "AGENTS.md";
@@ -26,6 +27,8 @@ const AGENTS_FILE = "AGENTS.md";
                     
                       
                     
+                                                                                                            
+                       
                       
  
 
@@ -54,7 +57,9 @@ export async function landChange(deps             , ref         , options
   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                       ();
   const by = (await deps.repository.userName()) ?? "unknown";
@@ -81,8 +86,9 @@ export async function landChange(deps             , ref         , options
     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             = { change: change.ref, merged: plan.mergedIds, built: plan.built, removed: plan.removed, restamped: restamp, finished: books.finished };
+  const report             = { 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             , change          , source          )
   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             , after             )       {
+/** 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             , after             , work          )       {
   const key = (p                                   )         => `${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        )          => 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             , refs          )                    {
+  let text = await deps.files.readText(PATHS.config);
+  if (text === undefined) return [];
+  const removed           = [];
+  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/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"])),
+  );
+}