@printpractical/cruze 0.0.1 → 0.0.3

package/skills/realign/notes.md

@@ -0,0 +1,30 @@
+# Realign notes
+
+Each release that changes what Cruze expects of a project ships a notes file, `notes/<version>.md`. `cruze realign status` reads the notes between the project's `standards:` and the installed version.
+
+## Releases
+
+- [0.0.2](notes/0.0.2.md)
+- [0.0.3](notes/0.0.3.md)
+
+## Format
+
+A note is a `###` heading with an ID and a title, then facts:
+
+```markdown
+### test-placement: Rust tests live in tests/
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-hexagonal-design/languages/rust.md`, "Dependencies and tooling"
+- Detect: check:test-placement
+- Migrate: move `src/<module>/tests.rs` to `tests/<module>.rs`
+```
+
+| Fact | Holds |
+| --- | --- |
+| `Applies to` | `existing code`, when work that met the last release must change; `new work only`, when only future work follows it |
+| `Rule` | The skill file and heading that state the rule |
+| `Detect` | The CLI rule that finds it, as `check:<rule>` or `validate:<rule>` |
+| `Ask` | The question the auditor answers when no CLI rule can |
+| `Migrate` | How existing work changes to meet it |
+
+A note for existing code has `Migrate`, and `Detect` or `Ask`.

package/skills/research/SKILL.md

@@ -17,8 +17,9 @@ Run these steps for each component in a design that isn't domain logic. Domain l
 4. Recommend one. Adopt a library, or build with a concrete reason: the behaviour is specific to this product, no candidate meets a stated constraint, every candidate brings disproportionate risk or complexity, or the capability is the product itself. Avoiding a dependency is not a reason on its own.
 5. Record the result as a row in the `## Adopt or build` table of the feature or standalone change, as Component, Decision, Choice and Reason. At project scope, record it as the adapter's `Adopts` fact, and put rows for anything no adapter owns in the walking-skeleton change's `## Adopt or build`. When the evidence runs longer than the reason, write it to `.cruze/notes/<date>-<slug>.md` and cite that note in the reason.
 6. Take the recommendation to the user. Adopting means a new dependency, which follows `.agents/skills/cruze-dependency-approval/SKILL.md`. Building commodity functionality is the user's call as well.
+7. Verify what the design will rely on. List each claim the design makes about an adopted library or tool: the features or flags it needs, and each command the design spells out, such as a CI step. Once the user has approved the dependency, check each claim by running it: build a scratch project outside the repository with exactly the declared features, and run each command there or with `--help`. When a claim can't be run, check it in that version's source. Write the features into the `Adopts` fact or the row's Choice.
 
-Done when every non-domain component in the design has a row with a decision and a reason.
+Done when every non-domain component in the design has a row with a decision and a reason, and every claim the design relies on is verified, with how.
 
 ## Answering a question
 

package/skills/rethink/SKILL.md

@@ -24,10 +24,12 @@ Finding a design flaw mid-build is information, not failure. Rethink amends the
    ```sh
    cruze journal add rethink --set level=<task|change|feature|architecture|vision> --set kind=<defect|discovery> \
      --set summary="<what changed>" --set wrong="<document and element, and what was wrong>" \
-     --set caught_by="<for a defect, the step that should have caught it; for a discovery, the step that found it>" \
+     --set found_by=<step> [--set missed_by=<step>] \
      --set agent="<the agent you run in>" [--item <ref>]
    ```
 
+   `found_by` is the step that found it. A defect also needs `missed_by`, the earliest step whose job was to catch it. Both take one of `envision`, `architect`, `research`, `design-review`, `walkthrough`, `plan`, `plan-review`, `build`, `code-review`, `verify`, `land`, `validate`, `check` or `user`.
+
 Done when `cruze status` shows every document approved and current, or names only work the user chose to leave for later.
 
 ## Levels

package/skills/rethink/levels.md

@@ -30,7 +30,7 @@
 
 ## Vision
 
-1. Edit `docs/vision.md` with the user: goals, non-goals or constraints. The feature map changes only through `cruze features add` and `cruze features drop`.
+1. Edit `docs/vision.md` with the user: goals, non-goals or constraints. The feature map changes only through `cruze features add` and `cruze features drop`. When the problem, users or goals changed, update the overview under the title of `README.md` to match.
 2. Update `docs/roadmap.md` to match, following `.agents/skills/cruze-roadmap/SKILL.md`.
 3. For each feature in progress that served a dropped goal, the user decides: keep it, or stop it with `cruze abandon <ref> --reason "<why>"`. Abandoning archives the folder and puts the feature back on the future list; changes that already landed stay.
 4. Re-approve with `cruze approve vision`, then `cruze approve roadmap`.

package/skills/roles/SKILL.md

@@ -13,12 +13,13 @@ A role is a prompt with fixed inputs and a report as its only output. It runs in
 | Code reviewer | [code-reviewer.md](code-reviewer.md) | verify, for the code review |
 | Verifier | [verifier.md](verifier.md) | verify, to run the system |
 | Researcher | [researcher.md](researcher.md) | architect, for adopt-or-build decisions |
+| Auditor | [auditor.md](auditor.md) | realign, to compare existing code with what a release now expects |
 
 ## Running a role
 
 1. Read the role file and gather exactly the inputs it lists. Done when you have every input path, plus any command output the role asks for.
 2. Start a fresh context: a helper agent with no conversation history, where the agent can start one. Give it the role file's full text and the inputs the role lists, including draft documents it names, and nothing else. Your own opinions, the conversation and your reasons for the design stay out.
-3. If the agent can't start a helper, run `cruze review <role> --item <ref>`, where the role is `design-reviewer`, `code-reviewer`, `verifier` or `researcher`. Add `--base <commit>` for the code under review. It starts the agent configured under `review:` in `.cruze/config.yaml` in a fresh context and prints the role's report. If that can't run either, the reviewers and the verifier must still run fresh: tell the user, and have them run the role in a new session. The researcher may run in your own context, since its evidence is checkable; say that you did.
+3. If the agent can't start a helper, run `cruze review <role> --item <ref>`, where the role is `design-reviewer`, `code-reviewer`, `verifier`, `researcher` or `auditor`. Add `--base <commit>` for the code under review. It starts the agent configured under `review:` in `.cruze/config.yaml` in a fresh context and prints the role's report. When no agent is configured, or it isn't installed, it reports `status: run-in-helper` with the role's full prompt instead: start a helper, such as a subagent, and give it exactly that prompt. If no fresh context can run, the reviewers, the verifier and the auditor must still run fresh: tell the user, and have them run the role in a new session. The researcher may run in your own context, since its evidence is checkable; say that you did.
 4. Take the report as it comes back. Check its evidence against the files before you act on any finding.
 
 ## Running a review
@@ -28,12 +29,14 @@ A review has at most two rounds. Only blockers can force the second one.
 ### Round 1
 
 1. Commit the documents under review (`docs: <artifact> for design review`), so the fixes in round 2 have a diff. Then run the reviewer on the complete artifact.
-2. Record the round: `cruze journal add review --set review=<design|plan|code> --set round=1 --set blockers=<n> --set concerns=<n>`, adding `--item <ref>` for a feature or change.
+2. Record the round: `cruze journal add review --set review=<design|plan|code> --set round=1 --set blockers=<n> --set concerns=<n> --set nits=<n>`, with the counts from the report's last line, adding `--item <ref>` for a feature or change.
 3. Present every finding to the user with your recommended disposition and why:
    - `fixed`: you will change the design as the finding proposes.
    - `waived`: the finding is right, but the user accepts the risk.
    - `deferred`: it belongs to later work. When it is future scope, add it with `cruze features add <slug> --summary <text> --goals <ids>`.
    - `rejected`: the finding is wrong, with the reason.
+
+   A finding whose fix would change an approved element, such as one marked `Needs design change`, is never `deferred` or `waived`. Recommend `rethink` at that element's level now. Once the rethink is done and the code follows it, record the finding as `fixed`.
 4. The user decides each one. Record each decision: `cruze journal add disposition --set finding="<rubric item>: <summary>" --set disposition=<fixed|waived|deferred|rejected> --set reason="<reason>" --set review=<design|plan|code>`, with the same `--item`. A recorded disposition is never raised again.
 5. Apply every `fixed` change, then run `cruze validate`. Done when it reports no errors.
 6. When a finding could be caught by a tool, such as a layering, naming or size rule, tell the user which `cruze check` rule or linter setting would catch it next time.

package/skills/roles/auditor.md

@@ -0,0 +1,35 @@
+# Auditor
+
+You compare a project's existing code and documents with what the installed Cruze now expects, and report every place they differ. You report findings, and you edit nothing.
+
+## Inputs
+
+- The notes to audit, from `cruze realign status`: each note's ID, `Rule`, `Ask` and `Migrate`.
+- In a full audit, the standards instead of notes: `.agents/skills/cruze-hexagonal-design/SKILL.md` and its language file, `.agents/skills/cruze-behavioural-testing/SKILL.md`, and `.agents/skills/cruze-formats/reference/architecture.md`. You audit one module, named with its `Path`.
+- `docs/architecture.md`, for the module map and the elements the code implements.
+- The files in scope: every source and test file under the project's `source` and `tests` globs in `.cruze/config.yaml`, or under the module's `Path`.
+- The settled ledger, as `.agents/skills/cruze-roles/SKILL.md` defines it, and the earlier realign dispositions from `cruze journal list --event disposition`. Never raise a finding they waived.
+
+## Work
+
+1. For each note, answer its `Ask` for every file in scope, not a sample. Work module by module.
+2. For each difference, find the smallest fix the note's `Migrate` allows, and whether it changes the text of an element in `docs/architecture.md`.
+3. Done when every note has findings, or evidence that the code already meets it.
+
+## Findings
+
+Group findings by note, in this shape:
+
+```markdown
+### <n>. <note ID>: <one-line summary>
+- Evidence: <path:line, quoting the code>
+- Standard: <the rule text it departs from>
+- Fix: <the specific change>
+- Design change: <the element in docs/architecture.md whose text must change, or `no`>
+```
+
+List every finding. When one pattern repeats more than 5 times, list 5 and give the count and the paths of the rest in one line.
+
+## Report
+
+End with one line: `Findings: <n> across <m> notes.` For each note with no findings, give the evidence that the code meets it.

package/skills/roles/code-reviewer.md

@@ -20,7 +20,7 @@ Review against these items and nothing else. Each finding names one.
 
 1. **Scenarios.** Every scenario the change delivers is implemented, and has a test that carries its ID, drives the seam the test plan names, and takes its expected values from the scenario.
 2. **Failures.** Each failure scenario produces the error it specifies and leaves the state it specifies.
-3. **Scope.** The code adds no behaviour the change's scope doesn't deliver. Unrequested behaviour is a finding, even when it looks useful.
+3. **Scope.** The code adds no behaviour the change's scope doesn't deliver, and no public item, variant or operation that only a later change uses. Unrequested or early code is a finding, even when it looks useful or the next change needs it.
 4. **Protected tests.** No behaviour, contract or smoke test for an approved scenario, port or flow was weakened, skipped or deleted without a delta that changes its subject.
 
 ### Architecture lane
@@ -28,7 +28,7 @@ Review against these items and nothing else. Each finding names one.
 5. **Placement.** Every file the diff adds or changes is where the architecture puts its owner, and matches the task's file targets or a recorded deviation.
 6. **Direction.** Dependencies point inward. No technology type crosses a port. Inbound adapters hold no domain rules or workflow.
 7. **Size.** No file holds two responsibilities or passes its budget without a recorded exception.
-8. **Idiom.** The code is idiomatic for the language, uses its standard tooling, and follows the language file's rules.
+8. **Idiom.** The code is idiomatic for the language, uses its standard tooling, and follows the language file's rules, including where tests live. Tests reuse the fixtures and harnesses in the test support module rather than redefining them.
 9. **Libraries.** Nothing hand-writes what a mature library does without a recorded `build` decision, and every new dependency has a recorded approval.
 10. **Contracts.** Each adapter honours its port's `Operations`, and each fake passes the same contract tests as the real adapter.
 
@@ -42,9 +42,10 @@ Each finding has this shape:
 - Evidence: <path:line, quoting the code>
 - Failure scenario: <what goes wrong, concretely, when this runs>
 - Proposed fix: <the specific change>
+- Needs design change: <the approved element whose text the fix must change, such as a port's `Operations`, or `no`>
 ```
 
-- A **blocker** means a scenario fails or is untested, a protected test was weakened, a layering rule is broken, or an unapproved dependency was added. Everything else is a **concern**.
+- A **blocker** means a scenario fails or is untested, a protected test was weakened, a layering rule is broken, an unapproved dependency was added, or an adapter can't honour its port's `Operations`. A finding that needs a design change is a blocker. Everything else is a **concern**.
 - List every blocker. List at most 5 concerns, the most important first. Count the rest as nits without listing them.
 - Drop any finding that contradicts the settled ledger. The only exception is a blocker with new evidence, which you mark `New evidence:` and explain.
 - When a finding could be caught mechanically, add `Check: <the cruze check rule or linter setting that would catch it>`.

package/skills/roles/design-reviewer.md

@@ -20,13 +20,16 @@ Review against these items and nothing else. Each finding names one.
 
 1. **Behaviour.** Every requirement has at least one scenario. Every scenario has concrete values, one WHEN, and a THEN a person could check. Failure behaviour the user will meet has its own scenario.
 2. **Seams.** Every scenario can be driven through a use case, or through an inbound adapter when the outcome is what that adapter shows. Every driven port the use case needs can be faked.
-3. **Placement.** Every new or changed element with code has a `Module` whose `Layer` fits its role and a `File` with a real path. No generic modules, and no file is likely to hold two responsibilities.
+3. **Placement.** Every new or changed element with code has a `Module` whose `Layer` fits its role and a `File` with a real path. No generic modules, and no file is likely to hold two responsibilities. Every element, fact and value serves a requirement in scope or a `Future` fact the feature map calls for. Anything reserved for a need nobody stated is a finding.
 4. **Direction.** Every dependency points inward and is allowed by the `RULE` elements and the `layers:` in `.cruze/config.yaml`.
-5. **Adopt or build.** Every component that isn't domain logic has an adopt-or-build decision with a reason, and every new dependency is named.
+5. **Adopt or build.** Every component that isn't domain logic has an adopt-or-build decision with a reason, and every new dependency is named with the features the design uses. Every command the design spells out, such as a CI step, is spelled as that version's `--help` or source shows it. A claim the design relies on that the research left unverified is a blocker.
 6. **Contracts.** Every new or changed port's `Operations` state what each operation guarantees, how it fails, and who owns cleanup.
 7. **Flows.** The key scenarios have a `FLOW` whose participants are all in its `Elements`, including the failure paths the scenarios need.
-8. **Consistency.** The design agrees with `docs/architecture.md` and the accepted ADRs, or changes them explicitly through a `MODIFIED` operation or a new ADR.
-9. **Slicing.** Each change is a vertical slice that delivers scenarios end to end and can land on its own. The order respects `Depends on`, and the first change is the thinnest useful tracer bullet. At project scope, the roadmap starts with the walking skeleton, and every goal in the release is covered.
+8. **Consistency.** The design agrees with `docs/architecture.md`, the accepted ADRs and what earlier changes landed, or changes them explicitly through a `MODIFIED` operation or a new ADR. Its own elements agree with each other. Check every pair, not a sample:
+   - each use case's `Output` and `Errors` against the `FLOW`s that serve it and the `XC` rules that apply to it;
+   - each adapter's duties against the port it implements and the `XC` rules it follows;
+   - each guarantee, such as "always fits" or "never returns", against the limits and failures that bound it.
+9. **Slicing.** Each change is a vertical slice that delivers scenarios end to end and can land on its own. The order respects `Depends on`, and the first change is the thinnest useful tracer bullet. A change `Builds` an element only when its delivered scenarios prove the whole body; an element whose duties arrive in several changes is split into elements that each arrive whole. `Depends on` names every earlier change that builds something this change's scenarios need. At project scope, the roadmap starts with the walking skeleton, and every goal in the release is covered.
 10. **Ambiguity.** Name each point where a fresh implementer could reasonably build something different from what the user expects.
 
 ## Plan rubric
@@ -34,7 +37,7 @@ Review against these items and nothing else. Each finding names one.
 When the artifact is a change's plan, review against these items instead.
 
 1. **Test plan.** Every delivered scenario has a `behaviour` row at a real seam, with its test file. Every port that a built adapter implements has a `contract` row. Seams need fakes of driven ports only, never mocks of internal code.
-2. **Tasks.** Every task names one owner and file paths the architecture assigns to that owner. Every scope ID is proved by a task. Each task is small enough to build red to green and commit on its own.
+2. **Tasks.** Every task names one owner and file paths the architecture assigns to that owner. Every scope ID is proved by a task. Each task is small enough to build red to green and commit on its own. A task that changes a signature, default or setting lists every file whose callers it breaks, including tests that start the real binary.
 3. **Order.** Tasks run from the inside out, domain before ports, use cases and adapters, so each task's test can fail first and then pass. The last tasks wire the composition root.
 4. **No design.** Nothing in the plan changes the architecture or the specs. A plan that needs a new element, operation or scenario goes back to `architect` or `rethink`.
 5. **Risks and overlap.** The riskiest task is named, with how it is checked. Overlap with work on other branches is resolved or accepted.
@@ -52,7 +55,7 @@ Each finding has this shape:
 - Proposed fix: <the specific edit>
 ```
 
-- A **blocker** means building from the design as written would produce wrong behaviour, a layering violation or an untestable scenario. Everything else is a **concern**.
+- A **blocker** means building from the design as written would produce wrong behaviour, a layering violation or an untestable scenario. Two elements that contradict each other are always a blocker, because an implementer has to pick one. Everything else is a **concern**.
 - List every blocker. List at most 5 concerns, the most important first. Count the rest as nits without listing them.
 - Drop any finding that contradicts the settled ledger. The only exception is a blocker with new evidence, which you mark `New evidence:` and explain.
 - When a finding could be caught mechanically, add `Check: <the cruze check rule or linter setting that would catch it>`.

package/skills/roles/researcher.md

@@ -26,6 +26,7 @@ For components, report one block each:
 
 Evidence: <the evaluation table for the serious candidates, with sources and the date checked>
 New dependency: yes or no
+Claims to verify: <each feature, flag or command the design would rely on, with where the source shows it>
 ```
 
 For a question, report the answer, its evidence (version or commit, and file and line or URL) and what you couldn't verify.

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

@@ -48,6 +48,7 @@ export interface Options {
   gate?: string;
   override?: string;
   overlap: boolean;
+  full: boolean;
   replan: string[];
   rebase: string[];
   round?: string;

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

@@ -5,7 +5,7 @@ import type { CliContext, CommandResult, Options } from "../cli_context.ts";
 export async function runCheck(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
   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: CliContext, args: string[], options: Opti
   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/src/adapters/inbound/cli/commands/install.ts

@@ -11,5 +11,9 @@ export function describeSkillInstall(report: InstallSkillsReport): string[] {
   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/src/adapters/inbound/cli/commands/realign.ts

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

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

@@ -14,5 +14,5 @@ export async function runReviewCommand(context: CliContext, args: string[], 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/src/adapters/inbound/cli/commands.ts

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

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

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

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

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

package/src/adapters/outbound/node_project_files.ts

@@ -78,7 +78,8 @@ export class NodeProjectFiles implements ProjectFiles {
     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/src/adapters/outbound/process_agent_runner.ts

@@ -11,15 +11,20 @@ export class ProcessAgentRunner implements AgentRunner {
 
   run(command: string[], prompt: string): Promise<AgentRun> {
     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: Buffer) => (output += chunk.toString("utf8")));
       child.stderr.on("data", (chunk: Buffer) => (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: NodeJS.ErrnoException) =>
+        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/src/app/ports/agent_runner.ts

@@ -1,11 +1,10 @@
 /** Starts a coding agent in a fresh context, non-interactively, and collects what it reports. */
 export interface AgentRunner {
-  /** Runs `command` in the project root with `prompt` on standard input. */
+  /**
+   * Runs `command` in the project root with `prompt` on standard input. Reports `missing`,
+   * without running anything, when the command's program isn't installed.
+   */
   run(command: string[], prompt: string): Promise<AgentRun>;
 }
 
-export interface AgentRun {
-  exitCode: number;
-  output: string;
-  error: string;
-}
+export type AgentRun = { kind: "finished"; exitCode: number; output: string; error: string } | { kind: "missing" };

package/src/app/project_context.ts

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

package/src/app/use_cases/check_code.ts

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

package/src/app/use_cases/init_project.ts

@@ -1,5 +1,7 @@
+import { CruzeError } from "../../domain/cruze_error.ts";
+import { agentSkillHome } from "../../domain/agent_skill_homes.ts";
 import { parseProjectName } from "../../domain/project_name.ts";
-import { INIT_SCAFFOLD, renderTemplate } from "../../domain/scaffold.ts";
+import { CLAUDE_INSTRUCTIONS, INIT_AGENTS, INIT_SCAFFOLD, type InitAgent, renderTemplate, reviewSettingTemplate } from "../../domain/scaffold.ts";
 import type { Bundle } from "../ports/bundle.ts";
 import type { ProjectFiles } from "../ports/project_files.ts";
 import type { Prompter } from "../ports/prompter.ts";
@@ -10,6 +12,7 @@ export interface InitProjectRequest {
   name?: string;
   /** Offered as the default answer when asking for the name. */
   defaultName: string;
+  /** From `--agent`: `claude`, `other`, or agents to link skills for. Asked for when it names neither. */
   agents: string[];
   /**
    * How CI runs this version of Cruze through npx, such as `github:PrintPractical/cruze#v0.0.1`
@@ -20,6 +23,7 @@ export interface InitProjectRequest {
 
 export interface InitProjectReport {
   project: string;
+  agent: InitAgent;
   created: string[];
   /** Files that already existed and were left untouched. */
   skipped: string[];
@@ -36,11 +40,13 @@ export async function initProject(
 ): Promise<InitProjectReport> {
   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: string[] = [];
@@ -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: ProjectFiles, prompter: Prompter, requested: string[]): Promise<InitAgent> {
+  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/src/app/use_cases/install_skills.ts

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