@printpractical/cruze 0.0.13 → 0.0.14

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

package/src/app/use_cases/project_status.ts

@@ -1,82 +1,58 @@
-import { CruzeError } from "../../domain/cruze_error.ts";
+import { approvalState, type ApprovalState } from "../../domain/approvals.ts";
 import { PATHS } from "../../domain/project/layout.ts";
-import { readProgress } from "../../domain/project/progress.ts";
-import { buildProjectView } from "../../domain/project/project_view.ts";
-import { findWorkItem, type WorkItem } from "../../domain/project/work_items.ts";
-import { nextSteps, type NextReport } from "../../domain/status/next_step.ts";
-import { activeChange, buildGateReasons, projectStatus, touchedIds, type ProjectStatus } from "../../domain/status/work_status.ts";
-import { appendJournal, loadView, type ProjectDeps } from "../project_context.ts";
+import type { MarkdownDoc } from "../../domain/markdown.ts";
+import { nextStep, type NextStep } from "../../domain/next_step.ts";
+import type { FeatureStatus } from "../../domain/project/features.ts";
+import { loadDocs, type ProjectDeps } from "../project_context.ts";
 
-export interface StatusReport extends ProjectStatus {
-  branch: string | null;
+export interface DocumentStatus {
+  path: string;
+  state: ApprovalState | "missing";
 }
 
-export async function showStatus(deps: ProjectDeps): Promise<StatusReport> {
-  const branch = await deps.repository.currentBranch();
-  return { branch, ...projectStatus(await loadView(deps.files), branch) };
-}
-
-/** The step to run next on this branch, and other work that could proceed. */
-export async function suggestNext(deps: ProjectDeps): Promise<NextReport & { branch: string | null }> {
-  const branch = await deps.repository.currentBranch();
-  return { branch, ...nextSteps(await loadView(deps.files), branch) };
-}
-
-export interface GateReport {
-  gate: "build";
-  passed: boolean;
-  reasons: string[];
-  overridden: boolean;
+export interface FeatureReport {
+  slug: string;
+  path?: string;
+  /** Missing when the release lists it but nobody has shaped it yet. */
+  status: FeatureStatus | "not-shaped" | "unknown";
+  approval: ApprovalState | "missing";
+  inRelease: boolean;
+  needs: string[];
+  scenarios: number;
 }
 
-/**
- * The build gate: the change bound to this branch, its feature and the architecture are
- * all approved and current. An override passes the gate and is journaled with its reason.
- */
-export async function checkBuildGate(deps: ProjectDeps, override?: string): Promise<GateReport> {
-  const view = await loadView(deps.files);
-  const branch = await deps.repository.currentBranch();
-  const reasons = buildGateReasons(view, branch);
-  if (reasons.length === 0) return { gate: "build", passed: true, reasons, overridden: false };
-  if (override === undefined) return { gate: "build", passed: false, reasons, overridden: false };
-  if (override.trim() === "") throw new CruzeError("override-reason", "an override needs a reason");
-  const folder = activeChange(view, branch)?.folder ?? ".cruze";
-  await appendJournal(deps, folder, "override", { gate: "build", reason: override, blocked_by: reasons });
-  return { gate: "build", passed: true, reasons, overridden: true };
+export interface StatusReport {
+  documents: DocumentStatus[];
+  features: FeatureReport[];
+  next: NextStep;
 }
 
-export interface Overlap {
-  branch: string;
-  item: string;
-  shared: string[];
-}
-
-/** In-flight work on other branches that touches the same elements as this branch's change. */
-export async function findOverlaps(deps: ProjectDeps, ref?: string): Promise<{ change: string; overlaps: Overlap[] }> {
-  const view = await loadView(deps.files);
-  const branch = await deps.repository.currentBranch();
-  const change = ref === undefined ? activeChange(view, branch) : view.items.find((item) => item.ref === ref);
-  if (change === undefined) throw new CruzeError("no-active-change", "no change is bound to this branch; name one with --change");
-  const mine = touchedIds(view, change);
-  const overlaps: Overlap[] = [];
-  for (const other of await deps.repository.otherBranches()) {
-    // Landed work is archived, so a branch's work in flight is under features/ and changes/ only.
-    const inFlight = [...(await deps.repository.filesOnBranch(other, PATHS.featuresDir)), ...(await deps.repository.filesOnBranch(other, PATHS.changesDir))];
-    const theirs = buildProjectView(new Map([...view.snapshot].filter(([p]) => p.startsWith("docs/")).concat(inFlight)));
-    // Work in flight on a branch is the change bound to it that hasn't landed, there or here.
-    const boundThere = theirs.items.filter((i) => {
-      const bound = readProgress(i.doc).branch;
-      const here = findWorkItem(view.items, i.ref);
-      return !landed(i) && (here === undefined || !landed(here)) && i.ref !== change.ref && bound !== undefined && (other === bound || other.endsWith(`/${bound}`));
-    });
-    for (const item of boundThere) {
-      const shared = [...touchedIds(theirs, item)].filter((id) => mine.has(id));
-      if (shared.length > 0) overlaps.push({ branch: other, item: item.ref, shared: shared.sort() });
-    }
-  }
-  return { change: change.ref, overlaps };
-}
-
-function landed(item: WorkItem): boolean {
-  return item.archived || readProgress(item.doc).landed !== undefined;
+/** Each document's approval, and each feature's progress, in release order. */
+export async function showStatus(deps: ProjectDeps): Promise<StatusReport> {
+  const docs = await loadDocs(deps.files);
+  const state = (path: string, doc: MarkdownDoc | undefined): ApprovalState | "missing" => (doc === undefined ? "missing" : approvalState(docs.approvals, path, doc));
+  const documents = [
+    { path: PATHS.vision, state: state(PATHS.vision, docs.vision) },
+    { path: PATHS.architecture, state: state(PATHS.architecture, docs.architecture) },
+  ];
+  const slugs = [...docs.release.map((r) => r.slug), ...docs.features.map((f) => f.slug).filter((s) => !docs.release.some((r) => r.slug === s))];
+  const features = slugs.map((slug): FeatureReport => {
+    const feature = docs.features.find((f) => f.slug === slug);
+    const row = docs.release.find((r) => r.slug === slug);
+    return {
+      slug,
+      ...(feature === undefined ? {} : { path: feature.path }),
+      status: feature === undefined ? "not-shaped" : (feature.status ?? "unknown"),
+      approval: feature === undefined ? "missing" : approvalState(docs.approvals, feature.path, feature.doc),
+      inRelease: row !== undefined,
+      needs: row?.needs ?? [],
+      scenarios: feature?.scenarios.length ?? 0,
+    };
+  });
+  return { documents, features, next: nextStep(docs) };
+}
+
+/** The step to run next, and why. */
+export async function suggestNext(deps: ProjectDeps): Promise<NextStep> {
+  return nextStep(await loadDocs(deps.files));
 }

package/src/app/use_cases/run_review.ts

@@ -1,20 +1,14 @@
 import { CruzeError } from "../../domain/cruze_error.ts";
-import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
-import { isPlanned } from "../../domain/project/plan_parts.ts";
-import { featureOf, type WorkItem } from "../../domain/project/work_items.ts";
 import type { AgentRunner } from "../ports/agent_runner.ts";
-import { loadView, type ProjectDeps } from "../project_context.ts";
+import { loadDocs, type ProjectDeps } from "../project_context.ts";
 
-export const ROLES = ["design-reviewer", "code-reviewer", "verifier", "researcher", "auditor", "surveyor"] as const;
+export const ROLES = ["code-reviewer", "researcher"] as const;
 export type Role = (typeof ROLES)[number];
 
 export interface ReviewRequest {
   role: string;
-  /** The feature or change under review; omitted for project-scope documents. */
+  /** The feature under review, by slug. */
   item?: string;
-  round?: number;
-  /** The round-1 blockers, for round 2. */
-  blockers?: string;
   /** The commit the diff under review starts from. */
   base?: string;
 }
@@ -30,37 +24,31 @@ export type ReviewReport = { role: Role; item?: string; command?: string[] } & (
 
 /**
  * Runs a Cruze role in a fresh agent context: the role's prompt, what it reviews, and nothing
- * from the conversation that produced the work. Returns the role's report as written, or the
- * prompt to run in a helper when the configured agent isn't installed.
+ * from the conversation that produced the work.
  */
 export async function runReview(deps: ProjectDeps & { runner: AgentRunner }, request: ReviewRequest): Promise<ReviewReport> {
   if (!(ROLES as readonly string[]).includes(request.role)) throw new CruzeError("unknown-role", `the roles are ${ROLES.join(", ")}`);
   const role = request.role as Role;
-  const view = await loadView(deps.files);
+  const docs = await loadDocs(deps.files);
   const roleText = (await deps.files.readText(`.agents/skills/cruze-roles/${role}.md`)) ?? (await bundledRole(deps, role));
 
-  const context = [`Round: ${request.round ?? 1}`];
+  const context: string[] = [];
   if (request.item !== undefined) {
-    const { path, item } = resolveArtifact(view, request.item);
-    context.push(`Under review: ${item?.ref ?? path} (\`${path}\`)`);
-    const feature = item === undefined ? undefined : featureOf(view.items, item);
-    if (feature !== undefined) context.push(`Its feature: \`${feature.path}\``);
-    if (role === "design-reviewer" && item !== undefined) context.push(rubricLine(item));
-  } else {
-    context.push("Under review: the project documents the role lists for project scope");
+    const feature = docs.features.find((f) => f.slug === request.item);
+    if (feature === undefined) throw new CruzeError("not-found", `no feature ${request.item} in docs/features/`);
+    context.push(`Under review: the feature in \`${feature.path}\``);
   }
   if (request.base !== undefined) context.push(`The changes under review: run \`git diff ${request.base}\`.`);
-  if (request.blockers !== undefined) context.push(`Round-1 blockers to check:\n\n${request.blockers}`);
 
   const prompt = [
     roleText.trim(),
     "## This run",
     "You are running the role above in a fresh context, in the project's repository. Read every input it lists from the files, and run the commands it names. Edit no files. End with the report the role describes.",
-    context.map((line) => `- ${line}`).join("\n"),
+    ...(context.length === 0 ? [] : [context.map((line) => `- ${line}`).join("\n")]),
   ].join("\n\n");
 
   const subject = { role, ...(request.item === undefined ? {} : { item: request.item }) };
-  const command = view.config?.config?.review.command;
+  const command = docs.config?.config?.review.command;
   if (command === undefined) return { ...subject, status: "run-in-helper", instruction: helperInstruction(undefined), prompt };
   const run = await deps.runner.run(command, prompt);
   if (run.kind === "missing") return { ...subject, command, status: "run-in-helper", instruction: helperInstruction(command[0]), prompt };
@@ -84,10 +72,3 @@ async function bundledRole(deps: ProjectDeps, role: Role): Promise<string> {
   if (file === undefined) throw new CruzeError("role-missing", `the ${role} role is not installed; run cruze install`);
   return file.text;
 }
-
-/** A design reviewer reads one rubric: the plan rubric for a planned change, the design rubric otherwise. */
-function rubricLine(item: WorkItem): string {
-  return item.kind !== "feature" && isPlanned(item.doc)
-    ? "This is a change's plan: review it against `.agents/skills/cruze-roles/plan-rubric.md`."
-    : "This is a design: review it against `.agents/skills/cruze-roles/design-rubric.md`.";
-}

package/src/app/use_cases/validate_project.ts

@@ -3,8 +3,8 @@ import { warning, type Problem } from "../../domain/validation/problem.ts";
 import { PATHS } from "../../domain/project/layout.ts";
 import { versionSkew } from "../../domain/versions/cruze_version.ts";
 import type { Bundle } from "../ports/bundle.ts";
-import { loadView } from "../project_context.ts";
 import type { ProjectFiles } from "../ports/project_files.ts";
+import { loadDocs } from "../project_context.ts";
 
 export interface ValidateReport {
   valid: boolean;
@@ -15,10 +15,10 @@ export interface ValidateReport {
 
 /** Checks every document in the project against the cruze-formats rules, and that its skills match this CLI. */
 export async function validate(deps: { files: ProjectFiles; bundle: Bundle }): Promise<ValidateReport> {
-  const view = await loadView(deps.files);
-  const config = view.config?.config;
+  const docs = await loadDocs(deps.files);
+  const config = docs.config?.config;
   const skew = config === null || config === undefined ? undefined : versionSkew(deps.bundle.version, config.cruze);
-  const problems = [...validateProject(view), ...(skew === undefined ? [] : [warning(PATHS.config, undefined, "cruze-version", skew.message)])];
+  const problems = [...validateProject(docs), ...(skew === undefined ? [] : [warning(PATHS.config, undefined, "cruze-version", skew.message)])];
   return {
     valid: !hasErrors(problems),
     errors: problems.filter((p) => p.severity === "error").length,

package/src/domain/approvals.ts

@@ -0,0 +1,51 @@
+import { designHash } from "./hashing.ts";
+import type { MarkdownDoc } from "./markdown.ts";
+import { slugOfFeaturePath } from "./project/layout.ts";
+
+/** One approval of one document: the hash of its design content when the user approved it. */
+export interface ApprovalRecord {
+  path: string;
+  hash: string;
+  approvedAt: string;
+  by: string;
+}
+
+export type ApprovalState = "approved" | "edited" | "unapproved";
+
+/** Reads `.cruze/approvals.json`; anything unreadable counts as no approvals, and validate reports it. */
+export function parseApprovals(text: string | undefined): ApprovalRecord[] {
+  if (text === undefined) return [];
+  try {
+    const parsed: unknown = JSON.parse(text);
+    const list = (parsed as { approvals?: unknown }).approvals;
+    if (!Array.isArray(list)) return [];
+    return list.filter((r): r is ApprovalRecord => typeof r?.path === "string" && typeof r?.hash === "string" && typeof r?.approvedAt === "string" && typeof r?.by === "string");
+  } catch {
+    return [];
+  }
+}
+
+export function serializeApprovals(records: ApprovalRecord[]): string {
+  const sorted = [...records].sort((a, b) => a.path.localeCompare(b.path));
+  return `${JSON.stringify({ version: 2, approvals: sorted }, null, 2)}\n`;
+}
+
+/** The records with this one replacing any earlier approval of the same document. */
+export function withApproval(records: ApprovalRecord[], record: ApprovalRecord): ApprovalRecord[] {
+  return [...records.filter((r) => r.path !== record.path), record];
+}
+
+/**
+ * The hash an approval records. A feature's `## Decisions` is the agent's record of what it chose,
+ * which build and review add to, so it stays out: the user's approval covers the rest.
+ */
+export function approvalHash(path: string, doc: MarkdownDoc): string {
+  return designHash(doc, slugOfFeaturePath(path) === undefined ? [] : ["Decisions"]);
+}
+
+/** Whether the document still reads as it did when it was approved. */
+export function approvalState(records: readonly ApprovalRecord[], path: string, doc: MarkdownDoc): ApprovalState {
+  const record = records.find((r) => r.path === path);
+  if (record === undefined) return "unapproved";
+  return record.hash === approvalHash(path, doc) ? "approved" : "edited";
+}