@printpractical/cruze 0.0.13 → 0.0.15

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

@@ -1,14 +1,9 @@
 import type { Handler } from "./cli_context.ts";
-import { runCheck, runLand, runTrace } from "./commands/code.ts";
-import { runDiff } from "./commands/diff.ts";
+import { runCheck, 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 { runShow } from "./commands/show.ts";
 import { runNext, runStatus } from "./commands/status.ts";
 
 /** A command, and the options it takes: one list, or one per subcommand for a command that has them. */
@@ -20,37 +15,15 @@ export interface Command {
 
 export const COMMANDS: Record<string, Command> = {
   init: { handler: runInit, options: ["name", "yes", "agent", "package"], usage: "init [--name <name>] [--yes] [--agent claude|other] [--package <npm spec>]   set up this repository and install the skills" },
-  install: { handler: runInstall, options: ["agent"], usage: "install [--agent <agent>]                         install or update the Cruze skills" },
-  validate: { handler: runValidate, options: [], usage: "validate                                          check every document against the formats" },
-  status: { handler: runStatus, options: ["gate", "override", "overlap", "change"], usage: "status [--gate build [--override <reason>]] [--overlap [--change <ref>]]" },
-  next: { handler: runNext, options: [], usage: "next                                              the step to run next on this branch, and why" },
-  diff: { handler: runDiff, options: [], usage: "diff <ref>                                        what changed upstream of a document since its approval, and whether its delta needs a rebase" },
-  show: {
-    handler: runShow,
-    options: ["index", "notes"],
-    usage: "show <ref> | show <ID>... | show --index [<context>] | show --notes [<target>]   a change's design, chosen elements, one line per element, or the notes and hand-offs for a target",
-  },
-  approve: {
-    handler: runApprove,
-    options: ["replan", "rebase", "by-agent", "restamp-unchanged"],
-    usage: "approve <vision|architecture|roadmap|ref|path> [--replan <ID>...] [--rebase <ID>...] [--by-agent|--restamp-unchanged]   record an approval of a document",
-  },
-  new: {
-    handler: runNew,
-    options: { vision: [], glossary: [], architecture: [], roadmap: [], feature: ["title", "roadmap"], change: ["title", "feature", "roadmap"], adr: ["title"], note: ["title", "kind", "about"] },
-    usage: "new <vision|glossary|architecture|roadmap> | new <feature|change|adr> <slug> --title <title> [--feature <ref>] [--roadmap <slug>] | new note <slug> --title <title> --kind <input|intake|explore|research> --about <subjects>",
-  },
-  task: { handler: runTask, options: { done: ["change", "commit"], deviation: ["change"], reopen: ["change"] }, usage: "task <done|deviation|reopen> <T#> [text] [--change <ref>] [--commit <sha>]" },
-  features: { handler: runFeatures, options: { add: ["summary", "goals"], update: ["summary"], drop: ["reason"] }, usage: "features <add|update|drop> <slug> [--summary <text>] [--goals <ids>] [--reason <text>]" },
-  roadmap: { handler: runRoadmap, options: { prune: [] }, usage: "roadmap prune                                     clear landed items from the roadmap status when a release closes" },
-  journal: { handler: runJournal, options: { add: ["set", "item"], list: ["event", "item", "all"] }, usage: "journal <add <event> --set key=value... [--item <ref>]|list [--event <event>] [--item <ref>] [--all]>" },
-  review: { handler: runReviewCommand, options: ["item", "round", "blockers", "base"], usage: "review <role> [--item <ref>] [--round 1|2 --blockers <file>] [--base <commit>]   run a role in a fresh agent context" },
-  feedback: { handler: runFeedback, options: { export: ["out", "no-redact"] }, usage: "feedback export [--out <file>] [--no-redact]" },
-  trace: { handler: runTrace, options: ["all", "change"], usage: "trace [--all] [--change <ref>]                    link scenarios to the tests that prove them" },
-  check: { handler: runCheck, options: ["file", "ci"], usage: "check [<file>...] [--ci]                          enforce layer rules and file budgets" },
-  abandon: { handler: runAbandon, options: ["reason"], usage: "abandon <ref> --reason <text>                     archive a feature or standalone change that stops for good" },
-  land: { handler: runLand, options: ["override"], usage: "land [<ref>] [--override <reason>]                merge a verified change into the living docs" },
-  realign: { handler: runRealign, options: { status: ["full"], done: ["change"] }, usage: "realign <status [--full]|done [--change <ref>]>    what the installed Cruze expects of existing code, and recording that the code meets it" },
+  install: { handler: runInstall, options: ["agent"], usage: "install [--agent <agent>]                 install or update the Cruze skills" },
+  new: { handler: runNew, options: { vision: [], architecture: [], feature: ["title"] }, usage: "new vision | new architecture | new feature <slug> [--title <title>]   start a document from its template" },
+  validate: { handler: runValidate, options: [], usage: "validate                                  check every document against the formats" },
+  approve: { handler: runApprove, options: [], usage: "approve <vision|architecture|feature slug>   record that the user approved a document as it reads now" },
+  status: { handler: runStatus, options: [], usage: "status                                    each document's approval, each feature's progress, and the next step" },
+  next: { handler: runNext, options: [], usage: "next                                      the step to run next, and why" },
+  trace: { handler: runTrace, options: [], usage: "trace [<feature slug>]                    link scenarios to the tests that carry their IDs" },
+  check: { handler: runCheck, options: ["ci"], usage: "check [<file>...] [--ci]                  enforce layer rules and file budgets" },
+  review: { handler: runReviewCommand, options: ["feature", "base"], usage: "review <code-reviewer|researcher> [--feature <slug>] [--base <commit>]   run a role in a fresh agent context" },
 };
 
 export const USAGE = `Usage: cruze <command> [options]

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

@@ -28,36 +28,9 @@ export function parseCommand(argv: string[]): ParsedCommand {
         help: { type: "boolean", short: "h", default: false },
         title: { type: "string" },
         feature: { type: "string" },
-        roadmap: { type: "string" },
-        change: { type: "string" },
-        commit: { type: "string" },
-        summary: { type: "string" },
-        goals: { type: "string" },
-        reason: { type: "string" },
-        set: { type: "string", multiple: true, default: [] },
-        item: { type: "string" },
-        event: { type: "string" },
-        out: { type: "string" },
-        "no-redact": { type: "boolean", default: false },
-        all: { type: "boolean", default: false },
-        file: { type: "string", multiple: true, default: [] },
         ci: { type: "boolean", default: false },
-        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: [] },
-        rebase: { type: "string", multiple: true, default: [] },
         base: { type: "string" },
-        blockers: { type: "string" },
-        "by-agent": { type: "boolean", default: false },
-        "restamp-unchanged": { type: "boolean", default: false },
-        index: { type: "boolean", default: false },
-        notes: { type: "boolean", default: false },
-        kind: { type: "string" },
-        about: { type: "string" },
       },
     });
   } catch (error) {
@@ -71,39 +44,12 @@ export function parseCommand(argv: string[]): ParsedCommand {
     agent: values.agent,
     json: values.json,
     text: values.text,
-    set: values.set,
-    redact: !values["no-redact"],
-    all: values.all,
-    file: values.file,
     ci: values.ci,
-    overlap: values.overlap,
-    full: values.full,
-    replan: values.replan,
-    rebase: values.rebase,
-    byAgent: values["by-agent"],
-    restampUnchanged: values["restamp-unchanged"],
-    index: values.index,
-    notes: values.notes,
     ...optional("name", values.name),
     ...optional("title", values.title),
     ...optional("feature", values.feature),
-    ...optional("roadmap", values.roadmap),
-    ...optional("change", values.change),
-    ...optional("commit", values.commit),
-    ...optional("summary", values.summary),
-    ...optional("goals", values.goals),
-    ...optional("reason", values.reason),
-    ...optional("item", values.item),
-    ...optional("event", values.event),
-    ...optional("out", values.out),
-    ...optional("gate", values.gate),
-    ...optional("override", values.override),
-    ...optional("round", values.round),
     ...optional("package", values.package),
     ...optional("base", values.base),
-    ...optional("blockers", values.blockers),
-    ...optional("kind", values.kind),
-    ...optional("about", values.about),
   };
   const given = [...new Set(tokens.flatMap((token) => (token.kind === "option" ? [token.name] : [])))];
   return { words: positionals, options, given, help: values.help, version: values.version };

package/src/adapters/outbound/git_repository.ts

@@ -1,4 +1,4 @@
-import { execFile, spawn } from "node:child_process";
+import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import type { Repository } from "../../app/ports/repository.ts";
 
@@ -12,15 +12,6 @@ export class GitRepository implements Repository {
     this.root = root;
   }
 
-  async currentBranch(): Promise<string | null> {
-    const branch = await this.git("rev-parse", "--abbrev-ref", "HEAD");
-    return branch === null || branch === "HEAD" ? null : branch;
-  }
-
-  async headCommit(): Promise<string | null> {
-    return this.git("rev-parse", "--short", "HEAD");
-  }
-
   async userName(): Promise<string | null> {
     const name = await this.git("config", "user.name");
     const email = await this.git("config", "user.email");
@@ -28,72 +19,12 @@ export class GitRepository implements Repository {
     return email === null ? name : `${name} <${email}>`;
   }
 
-  async otherBranches(): Promise<string[]> {
-    const current = await this.currentBranch();
-    const listing = await this.git("for-each-ref", "--format=%(refname:short)", "refs/heads", "refs/remotes");
-    return (listing ?? "")
-      .split("\n")
-      .filter((ref) => ref !== "" && ref !== current && !ref.endsWith("/HEAD") && ref !== `origin/${current}`);
-  }
-
-  async filesOnBranch(branch: string, dir: string): Promise<Map<string, string>> {
-    const listing = await this.git("ls-tree", "-r", "--name-only", branch, "--", dir);
-    const paths = (listing ?? "").split("\n").filter((p) => p !== "");
-    if (paths.length === 0) return new Map();
-    // One git process for every file: a process per file took up to two minutes on a project with 26 branches.
-    const blobs = await this.catFiles(paths.map((path) => `${branch}:${path}`));
-    return new Map(paths.flatMap((path, i) => (blobs[i] === undefined ? [] : [[path, blobs[i]] as [string, string]])));
-  }
-
-  async firstCommitAdding(path: string, text: string): Promise<string | null> {
-    const commits = await this.git("log", "--reverse", "--format=%H", `-S${text}`, "--", path);
-    return commits?.split("\n").find((c) => c !== "") ?? null;
-  }
-
-  async fileAt(commit: string, path: string): Promise<string | null> {
-    return (await this.catFiles([`${commit}:${path}`]))[0] ?? null;
-  }
-
-  /** The contents of each object, in order, through one `git cat-file --batch`; undefined for one that is missing. */
-  private catFiles(objects: string[]): Promise<Array<string | undefined>> {
-    return new Promise((resolve) => {
-      const child = spawn("git", ["cat-file", "--batch"], { cwd: this.root, stdio: ["pipe", "pipe", "ignore"] });
-      const chunks: Buffer[] = [];
-      child.stdout.on("data", (chunk: Buffer) => chunks.push(chunk));
-      child.on("error", () => resolve(objects.map(() => undefined)));
-      child.on("close", () => resolve(parseBatch(Buffer.concat(chunks), objects.length)));
-      child.stdin.end(`${objects.join("\n")}\n`);
-    });
-  }
-
   private async git(...args: string[]): Promise<string | null> {
     try {
-      const { stdout } = await run("git", args, { cwd: this.root, maxBuffer: 64 * 1024 * 1024 });
+      const { stdout } = await run("git", args, { cwd: this.root });
       return stdout.trimEnd();
     } catch {
       return null;
     }
   }
 }
-
-/** Splits `git cat-file --batch` output: a `<sha> <type> <size>` header, the bytes and a newline, or `<name> missing`. */
-function parseBatch(output: Buffer, count: number): Array<string | undefined> {
-  const results: Array<string | undefined> = [];
-  let at = 0;
-  while (results.length < count && at < output.length) {
-    const headerEnd = output.indexOf(10, at);
-    if (headerEnd === -1) break;
-    const header = output.subarray(at, headerEnd).toString("utf8");
-    const size = /^[0-9a-f]+ \w+ (\d+)$/.exec(header)?.[1];
-    if (size === undefined) {
-      results.push(undefined);
-      at = headerEnd + 1;
-      continue;
-    }
-    const start = headerEnd + 1;
-    results.push(output.subarray(start, start + Number(size)).toString("utf8"));
-    at = start + Number(size) + 1;
-  }
-  while (results.length < count) results.push(undefined);
-  return results;
-}

package/src/app/ports/repository.ts

@@ -1,17 +1,5 @@
 /** The version-control repository the project lives in. Every operation tolerates a project outside git. */
 export interface Repository {
-  /** The checked-out branch, or null when detached or outside git. */
-  currentBranch(): Promise<string | null>;
-  /** The short hash of the checked-out commit, or null. */
-  headCommit(): Promise<string | null>;
   /** Who is approving: the configured user name and email, or null. */
   userName(): Promise<string | null>;
-  /** Local and remote-tracking branches other than the current one. */
-  otherBranches(): Promise<string[]>;
-  /** Files under a directory as they are on another branch, by project-relative path. */
-  filesOnBranch(branch: string, dir: string): Promise<Map<string, string>>;
-  /** The oldest commit whose change to a file added the text, or null. */
-  firstCommitAdding(path: string, text: string): Promise<string | null>;
-  /** A file's contents at a commit, or null when it didn't exist there. */
-  fileAt(commit: string, path: string): Promise<string | null>;
 }

package/src/app/project_context.ts

@@ -1,6 +1,6 @@
-import { buildProjectView, type ProjectView } from "../domain/project/project_view.ts";
-import { PATHS, SNAPSHOT_ROOTS } from "../domain/project/layout.ts";
-import { journalPath, serializeEntry, type JournalEntry } from "../domain/journal.ts";
+import { buildProjectDocs, type ProjectDocs } from "../domain/project/project_docs.ts";
+import { CruzeError } from "../domain/cruze_error.ts";
+import type { CruzeConfig } from "../domain/config.ts";
 import type { Bundle } from "./ports/bundle.ts";
 import type { Clock } from "./ports/clock.ts";
 import type { ProjectFiles } from "./ports/project_files.ts";
@@ -14,34 +14,24 @@ export interface ProjectDeps {
   bundle: Bundle;
 }
 
-/** Reads every document under docs/ and .cruze/, and the README, into a view. */
-export async function loadView(files: ProjectFiles): Promise<ProjectView> {
+/** Directories whose files make up the project's documents. */
+const DOC_ROOTS = ["docs", ".cruze"] as const;
+
+/** Reads every document under docs/ and .cruze/. */
+export async function loadDocs(files: ProjectFiles): Promise<ProjectDocs> {
   const snapshot = new Map<string, string>();
-  for (const root of SNAPSHOT_ROOTS) {
+  for (const root of DOC_ROOTS) {
     for (const path of await files.listFiles(root)) {
       const text = await files.readText(path);
       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);
-}
-
-/** A new view with some files replaced, for checking edits before writing them. */
-export function withFiles(view: ProjectView, changes: Map<string, string>): ProjectView {
-  return buildProjectView(new Map([...view.snapshot, ...changes]));
+  return buildProjectDocs(snapshot);
 }
 
-/** Appends an entry to the journal in `folder`, stamped with the time and the approver. */
-export async function appendJournal(deps: ProjectDeps, folder: string, event: string, fields: Record<string, unknown>): Promise<JournalEntry> {
-  const entry: JournalEntry = {
-    at: deps.clock.now().toISOString(),
-    event,
-    by: (await deps.repository.userName()) ?? "unknown",
-    cruze: deps.bundle.version,
-    ...fields,
-  };
-  await deps.files.appendText(journalPath(folder), serializeEntry(entry));
-  return entry;
+/** The project's config, or an error telling the user to fix it first. */
+export function requireConfig(docs: ProjectDocs): CruzeConfig {
+  const config = docs.config?.config;
+  if (config === null || config === undefined) throw new CruzeError("config", "fix .cruze/config.yaml first; run cruze validate for details");
+  return config;
 }

package/src/app/use_cases/approve_document.ts

@@ -0,0 +1,29 @@
+import { approvalHash, serializeApprovals, withApproval, type ApprovalRecord } from "../../domain/approvals.ts";
+import { CruzeError } from "../../domain/cruze_error.ts";
+import { parseMarkdown } from "../../domain/markdown.ts";
+import { PATHS } from "../../domain/project/layout.ts";
+import { resolveDocument } from "../../domain/project/project_docs.ts";
+import { validateProject } from "../../domain/validation/validate_project.ts";
+import { loadDocs, type ProjectDeps } from "../project_context.ts";
+
+/**
+ * Records that the user approved a document as it reads now: the vision, the architecture map or a
+ * feature. Any later edit to its design content shows it as edited until it is approved again.
+ */
+export async function approveDocument(deps: ProjectDeps, ref: string): Promise<ApprovalRecord> {
+  const docs = await loadDocs(deps.files);
+  const path = resolveDocument(docs, ref);
+  if (path === undefined) throw new CruzeError("not-found", `no document matches "${ref}"; name vision, architecture, a feature slug or a path`);
+  const errors = validateProject(docs).filter((p) => p.path === path && p.severity === "error");
+  if (errors.length > 0) {
+    throw new CruzeError("invalid", `${path} has ${errors.length} problem(s) to fix first: ${errors.map((p) => `${p.line === undefined ? "" : `line ${p.line}: `}${p.message}`).join("; ")}`);
+  }
+  const record: ApprovalRecord = {
+    path,
+    hash: approvalHash(path, parseMarkdown(docs.snapshot.get(path) ?? "")),
+    approvedAt: deps.clock.now().toISOString(),
+    by: (await deps.repository.userName()) ?? "unknown",
+  };
+  await deps.files.writeText(PATHS.approvals, serializeApprovals(withApproval(docs.approvals, record)));
+  return record;
+}

package/src/app/use_cases/check_code.ts

@@ -1,15 +1,8 @@
-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";
-import { readDelta } from "../../domain/project/deltas.ts";
-import { activeChange } from "../../domain/status/work_status.ts";
 import { traceScenarios, type TraceReport } from "../../domain/trace.ts";
-import { loadView, type ProjectDeps } from "../project_context.ts";
+import { loadDocs, requireConfig, type ProjectDeps } from "../project_context.ts";
 import type { ProjectFiles } from "../ports/project_files.ts";
 
 export interface CheckReport {
@@ -18,30 +11,19 @@ export interface CheckReport {
   findings: CheckFinding[];
 }
 
-/**
- * Enforces layer rules and file budgets. Layer violations always fail; budget and
- * 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.
- */
+/** Enforces layer rules and file budgets. Layer violations always fail; budget warnings fail only with `ci`. */
 export async function checkCode(deps: ProjectDeps, options: { files?: string[]; ci: boolean }): Promise<CheckReport> {
-  const view = await loadView(deps.files);
-  const config = requireConfig(view);
+  const config = requireConfig(await loadDocs(deps.files));
   const sources = await readMatching(deps.files, config.source);
-  const tests = await readMatching(deps.files, config.tests);
   for (const file of options.files ?? []) {
-    if (!sources.has(file) && !tests.has(file)) {
-      const text = await deps.files.readText(file);
-      if (text === undefined) throw new CruzeError("not-found", `${file} does not exist`);
-      if (matchesAny(file, config.source)) sources.set(file, text);
-      else if (matchesAny(file, config.tests)) tests.set(file, text);
-    }
+    if (sources.has(file) || !matchesAny(file, config.source)) continue;
+    const text = await deps.files.readText(file);
+    if (text === undefined) throw new CruzeError("not-found", `${file} does not exist`);
+    sources.set(file, text);
   }
-  const only = options.files?.filter((file) => sources.has(file) || tests.has(file));
-  const standards = config.standards ?? FIRST_RELEASE;
-  const findings = checkSource({ config, sources, tests, 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));
+  const only = options.files?.filter((file) => sources.has(file));
+  const findings = checkSource({ config, sources, ...(only === undefined ? {} : { only }) });
+  const failing = findings.filter((f) => f.severity === "error" || options.ci);
   return { passed: failing.length === 0, checked: only?.length ?? sources.size, findings };
 }
 
@@ -50,23 +32,18 @@ export interface TraceResult extends TraceReport {
   scope: string;
 }
 
-/** Scenario-to-test traceability for this branch's change, or for every built scenario with `all`. */
-export async function traceTests(deps: ProjectDeps, options: { all: boolean; change?: string }): Promise<TraceResult> {
-  const view = await loadView(deps.files);
-  const config = requireConfig(view);
-  let change;
-  if (!options.all) {
-    change = options.change !== undefined ? resolveChange(view, options.change) : activeChange(view, await deps.repository.currentBranch());
-    if (change === undefined) throw new CruzeError("no-active-change", "no change is bound to this branch; name one with --change, or use --all");
+/** Scenario-to-test traceability for one feature, or for every built feature. */
+export async function traceTests(deps: ProjectDeps, slug?: string): Promise<TraceResult> {
+  const docs = await loadDocs(deps.files);
+  const config = requireConfig(docs);
+  let required = docs.features.filter((f) => f.status === "built");
+  if (slug !== undefined) {
+    const feature = docs.features.find((f) => f.slug === slug);
+    if (feature === undefined) throw new CruzeError("not-found", `no feature ${slug} in docs/features/`);
+    required = [feature];
   }
-  const report = traceScenarios(view, await readMatching(deps.files, config.tests), change);
-  return { ...report, passed: report.missing.length === 0 && report.unknown.length === 0, scope: change?.ref ?? "all built scenarios" };
-}
-
-function requireConfig(view: ProjectView): CruzeConfig {
-  const config = view.config?.config;
-  if (config === null || config === undefined) throw new CruzeError("config", "fix .cruze/config.yaml first; run cruze validate for details");
-  return config;
+  const report = traceScenarios(docs.features, required, await readMatching(deps.files, config.tests));
+  return { ...report, passed: report.missing.length === 0 && report.unknown.length === 0, scope: slug ?? "every built feature" };
 }
 
 /** Files matching any glob, read from the smallest directories that can contain them. */
@@ -90,15 +67,3 @@ function globBase(glob: string): string {
   const fixed = segments.slice(0, segments.findIndex((s) => /[*?{]/.test(s)));
   return fixed.join("/");
 }
-
-/**
- * Every module's Path: the living docs' modules, and the modules that work in progress adds or
- * changes in its architecture delta, since their files are written before land merges them.
- */
-function modulePaths(view: ProjectView): string[] {
-  const living = [...view.living.elements.values()].filter((e) => e.id.startsWith("MOD-")).map((e) => ({ doc: e.doc, element: e.element }));
-  const inFlight = view.items
-    .filter((item) => item.kind !== "change" && !item.archived)
-    .flatMap((item) => readDelta(item.doc).entries.filter((entry) => entry.element.id.startsWith("MOD-") && entry.element.op !== "REMOVED").map((entry) => ({ doc: item.doc, element: entry.element })));
-  return [...living, ...inFlight].flatMap(({ doc, element }) => (factsOf(doc, element).get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? "")));
-}

package/src/app/use_cases/install_skills.ts

@@ -1,9 +1,12 @@
 import { posix } from "node:path";
 import { CruzeError } from "../../domain/cruze_error.ts";
 import { AGENT_SKILL_HOMES, SHARED_SKILLS_DIR, agentSkillHome, knownAgents } from "../../domain/agent_skill_homes.ts";
+import { reviewSettingTemplate } from "../../domain/scaffold.ts";
 import { SKILL_FILE, installedSkillName, isInstalledSkillName, skillProblems } from "../../domain/skill.ts";
+import { reviewCommandProblems } from "../../domain/validation/review_rules.ts";
 import type { Bundle, BundledSkill } from "../ports/bundle.ts";
 import type { ProjectFiles } from "../ports/project_files.ts";
+import { loadDocs } from "../project_context.ts";
 import { recordVersion, refuseDowngrade, type VersionRecord } from "./record_version.ts";
 
 export interface InstallSkillsRequest {
@@ -18,6 +21,8 @@ export interface InstallSkillsReport {
   linked: Array<{ agent: string; dir: string }>;
   /** The version recorded in .cruze/config.yaml, and the CI workflow's Cruze pin. */
   recorded: VersionRecord;
+  /** What the project still has to change by hand, such as letting the reviewer run its tests. */
+  notes: string[];
 }
 
 /**
@@ -55,7 +60,8 @@ export async function installSkills(
   }
 
   const recorded = await recordVersion(files, bundle.version);
-  return { version: bundle.version, installed: names, removed, linked, recorded };
+  const notes = reviewCommandProblems(await loadDocs(files), await bundle.template(reviewSettingTemplate("claude"))).map((problem) => problem.message);
+  return { version: bundle.version, installed: names, removed, linked, recorded, notes };
 }
 
 function assertValid(skills: BundledSkill[]): void {

package/src/app/use_cases/new_document.ts

@@ -0,0 +1,25 @@
+import { CruzeError } from "../../domain/cruze_error.ts";
+import { isSlug } from "../../domain/ids.ts";
+import { PATHS, featurePath } from "../../domain/project/layout.ts";
+import { renderTemplate } from "../../domain/scaffold.ts";
+import { loadDocs, requireConfig, type ProjectDeps } from "../project_context.ts";
+
+export const DOCUMENT_KINDS = ["vision", "architecture", "feature"] as const;
+export type DocumentKind = (typeof DOCUMENT_KINDS)[number];
+
+export interface NewDocReport {
+  kind: DocumentKind;
+  path: string;
+}
+
+/** Creates the vision, the architecture map or a feature from its template. A feature needs a slug, and a title defaults to it. */
+export async function createDocument(deps: ProjectDeps, kind: DocumentKind, slug?: string, title?: string): Promise<NewDocReport> {
+  const docs = await loadDocs(deps.files);
+  const project = requireConfig(docs).project;
+  if (kind === "feature" && (slug === undefined || !isSlug(slug))) throw new CruzeError("invalid-slug", `a feature needs a slug of lowercase words joined by single hyphens, such as "sign-in"`);
+  const path = kind === "feature" ? featurePath(slug ?? "") : PATHS[kind];
+  if (docs.snapshot.has(path)) throw new CruzeError("exists", `${path} already exists`);
+  const values = { project_name: project, slug: slug ?? "", title: title ?? slug ?? "" };
+  await deps.files.writeText(path, renderTemplate(await deps.bundle.formatTemplate(`${kind}.md`), values));
+  return { kind, path };
+}