@printpractical/cruze 0.0.1 → 0.0.3

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.3 is the third preview. It sets projects up for agents other than Claude Code, and runs reviews in the agent's own helpers when no review agent is configured. 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.3/printpractical-cruze-0.0.3.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.3
 ```
 
 ### 2. Set up a repository
@@ -61,35 +61,56 @@ 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.3/printpractical-cruze-0.0.3.tgz
 ```
 
-`init` asks for the project name, then creates:
+`init` asks for the project name, and which coding agent you use: `claude` for Claude Code, or `other` for any agent that reads `AGENTS.md` and `.agents/skills/`, such as Codex or OpenCode. It doesn't ask when you pass `--agent claude` or `--agent other`, or when the repository already has `CLAUDE.md` or `.claude/`. With `--yes`, or without a terminal, it sets up Claude Code. Then it creates:
 
 | Path | Purpose |
 | --- | --- |
 | `README.md` | Titled with the project name |
 | `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 |
+| `CLAUDE.md` | For Claude Code only: a link to `AGENTS.md` |
+| `.cruze/config.yaml` | Project configuration, including the Cruze version whose skills the project uses, and for Claude Code the command `cruze review` runs |
 | `.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 |
+| `.agents/skills/cruze-*` | The Cruze skills, also 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`. When no command is set, or its program isn't installed, it prints the role's prompt for the agent to run in a helper of its own |
 | `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/review.js

@@ -14,5 +14,5 @@ export async function runReviewCommand(context            , args          , opti
     ...(blockers === undefined ? {} : { blockers }),
     ...(options.base === undefined ? {} : { base: options.base }),
   });
-  return { json: report, human: report.report };
+  return { json: report, human: report.status === "reported" ? report.report : `${report.instruction}\n\n${report.prompt}` };
 }

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

@@ -3,13 +3,14 @@ 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";
 import { runNext, runStatus } from "./commands/status.js";
 
 export const COMMANDS                                                      = {
-  init: { handler: runInit, usage: "init [--name <name>] [--yes] [--agent <agent>] [--package <npm spec>]   set up this repository and install the skills" },
+  init: { handler: runInit, usage: "init [--name <name>] [--yes] [--agent claude|other] [--package <npm spec>]   set up this repository and install the skills" },
   install: { handler: runInstall, usage: "install [--agent <agent>]                         install or update the Cruze skills" },
   validate: { handler: runValidate, usage: "validate                                          check every document against the formats" },
   status: { handler: runStatus, usage: "status [--gate build [--override <reason>]] [--overlap [--change <ref>]]" },
@@ -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/adapters/outbound/node_project_files.js

@@ -78,7 +78,8 @@ export class NodeProjectFiles                         {
     this.assertInsideRoot(resolve(dirname(linkPath), target));
     await mkdir(dirname(linkPath), { recursive: true });
     await rm(linkPath, { recursive: true, force: true });
-    await symlink(target, linkPath, "dir");
+    // No link type: on Windows, Node picks a file or directory link from what the target is.
+    await symlink(target, linkPath);
   }
 
   /** Resolves a project-relative path, refusing anything outside the root. */

package/dist/adapters/outbound/process_agent_runner.js

@@ -11,15 +11,20 @@ export class ProcessAgentRunner                        {
 
   run(command          , prompt        )                    {
     const [program, ...args] = command;
-    if (program === undefined) return Promise.resolve({ exitCode: 127, output: "", error: "no command configured" });
+    if (program === undefined) return Promise.resolve({ kind: "missing" });
     return new Promise((resolve) => {
       const child = spawn(program, args, { cwd: this.cwd, stdio: ["pipe", "pipe", "pipe"] });
       let output = "";
       let error = "";
       child.stdout.on("data", (chunk        ) => (output += chunk.toString("utf8")));
       child.stderr.on("data", (chunk        ) => (error += chunk.toString("utf8")));
-      child.on("error", (failure) => resolve({ exitCode: 127, output, error: `${error}${failure.message}` }));
-      child.on("close", (code) => resolve({ exitCode: code ?? 1, output, error }));
+      // Spawning reports ENOENT when the program isn't on the PATH.
+      child.on("error", (failure                       ) =>
+        resolve(failure.code === "ENOENT" ? { kind: "missing" } : { kind: "finished", exitCode: 127, output, error: `${error}${failure.message}` }),
+      );
+      child.on("close", (code) => resolve({ kind: "finished", exitCode: code ?? 1, output, error }));
+      // A program that never started closes stdin; ignore the write error, since the spawn error reports it.
+      child.stdin.on("error", () => {});
       child.stdin.end(prompt);
     });
   }

package/dist/app/ports/agent_runner.js

@@ -1,11 +1,10 @@
 /** Starts a coding agent in a fresh context, non-interactively, and collects what it reports. */
                               
-                                                                            
+     
+                                                                                           
+                                                                          
+     
                                                             
  
 
-                           
-                   
-                 
-                
- 
+                                                                                                                   

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/init_project.js

@@ -1,5 +1,7 @@
+import { CruzeError } from "../../domain/cruze_error.js";
+import { agentSkillHome } from "../../domain/agent_skill_homes.js";
 import { parseProjectName } from "../../domain/project_name.js";
-import { INIT_SCAFFOLD, renderTemplate } from "../../domain/scaffold.js";
+import { CLAUDE_INSTRUCTIONS, INIT_AGENTS, INIT_SCAFFOLD,                 renderTemplate, reviewSettingTemplate } from "../../domain/scaffold.js";
                                                  
                                                               
                                                      
@@ -10,6 +12,7 @@ import { installSkills,                          } from "./install_skills.js";
                 
                                                                 
                       
+                                                                                                          
                    
      
                                                                                                 
@@ -20,6 +23,7 @@ import { installSkills,                          } from "./install_skills.js";
 
                                     
                   
+                   
                     
                                                             
                     
@@ -36,11 +40,13 @@ export async function initProject(
 )                             {
   const { files, bundle, prompter } = deps;
   const project = parseProjectName(request.name ?? (await prompter.ask("Project name", request.defaultName)));
+  const agent = await chooseAgent(files, prompter, request.agents);
   const values = {
     project_name: project,
     project_name_quoted: JSON.stringify(project),
     cruze_version: bundle.version,
     cruze_package: request.package ?? `@printpractical/cruze@${bundle.version}`,
+    review_setting: (await bundle.template(reviewSettingTemplate(agent))).trimEnd(),
   };
 
   const created           = [];
@@ -53,7 +59,29 @@ export async function initProject(
     await files.writeText(entry.path, renderTemplate(await bundle.template(entry.template), values));
     created.push(entry.path);
   }
+  if (agent === "claude") {
+    if (await files.exists(CLAUDE_INSTRUCTIONS.path)) skipped.push(CLAUDE_INSTRUCTIONS.path);
+    else {
+      await files.link(CLAUDE_INSTRUCTIONS.path, CLAUDE_INSTRUCTIONS.target);
+      created.push(CLAUDE_INSTRUCTIONS.path);
+    }
+  }
 
-  const skills = await installSkills({ files, bundle }, { agents: request.agents });
-  return { project, created, skipped, skills };
+  const linkFor = new Set(request.agents.filter((a) => a !== "other"));
+  if (agent === "claude") linkFor.add("claude");
+  const skills = await installSkills({ files, bundle }, { agents: [...linkFor] });
+  return { project, agent, created, skipped, skills };
+}
+
+/** The agent named with `--agent`, or shown by the project's files, or else the answer to asking. */
+async function chooseAgent(files              , prompter          , requested          )                     {
+  if (requested.includes("claude")) return "claude";
+  if (requested.includes("other")) return "other";
+  for (const marker of agentSkillHome("claude")?.markers ?? []) {
+    if (await files.exists(marker)) return "claude";
+  }
+  const answer = (await prompter.ask(`Coding agent (${INIT_AGENTS.join(" or ")})`, "claude")).trim().toLowerCase();
+  const agent = INIT_AGENTS.find((a) => a === answer);
+  if (agent === undefined) throw new CruzeError("unknown-agent", `Unknown agent: ${answer}. Answer ${INIT_AGENTS.join(" or ")}, or pass --agent.`);
+  return agent;
 }

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;
+}