@printpractical/cruze 0.0.1

package/src/adapters/outbound/git_repository.ts

@@ -0,0 +1,57 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { Repository } from "../../app/ports/repository.ts";
+
+const run = promisify(execFile);
+
+/** The git repository at a directory, driven through the git command. */
+export class GitRepository implements Repository {
+  private readonly root: string;
+
+  constructor(root: string) {
+    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");
+    if (name === null) return email;
+    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 files = new Map<string, string>();
+    const listing = await this.git("ls-tree", "-r", "--name-only", branch, "--", dir);
+    for (const path of (listing ?? "").split("\n").filter((p) => p !== "")) {
+      const text = await this.git("show", `${branch}:${path}`);
+      if (text !== null) files.set(path, text);
+    }
+    return files;
+  }
+
+  private async git(...args: string[]): Promise<string | null> {
+    try {
+      const { stdout } = await run("git", args, { cwd: this.root, maxBuffer: 64 * 1024 * 1024 });
+      return stdout.trimEnd();
+    } catch {
+      return null;
+    }
+  }
+}

package/src/adapters/outbound/node_project_files.ts

@@ -0,0 +1,101 @@
+import { appendFile, lstat, mkdir, readFile, readdir, rename, rm, symlink, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import type { ProjectFiles } from "../../app/ports/project_files.ts";
+
+/** Project files on the local disk, confined to one root directory. */
+export class NodeProjectFiles implements ProjectFiles {
+  private readonly root: string;
+
+  constructor(root: string) {
+    this.root = resolve(root);
+  }
+
+  async exists(path: string): Promise<boolean> {
+    try {
+      await lstat(this.resolve(path));
+      return true;
+    } catch (error) {
+      if (isNotFound(error)) return false;
+      throw error;
+    }
+  }
+
+  async readText(path: string): Promise<string | undefined> {
+    try {
+      return await readFile(this.resolve(path), "utf8");
+    } catch (error) {
+      if (isNotFound(error)) return undefined;
+      throw error;
+    }
+  }
+
+  async writeText(path: string, text: string): Promise<void> {
+    const target = this.resolve(path);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, text, "utf8");
+  }
+
+  async appendText(path: string, text: string): Promise<void> {
+    const target = this.resolve(path);
+    await mkdir(dirname(target), { recursive: true });
+    await appendFile(target, text, "utf8");
+  }
+
+  async listFiles(path: string): Promise<string[]> {
+    try {
+      const entries = await readdir(this.resolve(path), { withFileTypes: true, recursive: true });
+      return entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => relative(this.root, join(entry.parentPath, entry.name)).split(sep).join("/"))
+        .sort();
+    } catch (error) {
+      if (isNotFound(error)) return [];
+      throw error;
+    }
+  }
+
+  async move(from: string, to: string): Promise<void> {
+    const target = this.resolve(to);
+    await mkdir(dirname(target), { recursive: true });
+    await rename(this.resolve(from), target);
+  }
+
+  async listEntries(path: string): Promise<string[]> {
+    try {
+      return (await readdir(this.resolve(path))).sort();
+    } catch (error) {
+      if (isNotFound(error)) return [];
+      throw error;
+    }
+  }
+
+  async remove(path: string): Promise<void> {
+    await rm(this.resolve(path), { recursive: true, force: true });
+  }
+
+  async link(path: string, target: string): Promise<void> {
+    const linkPath = this.resolve(path);
+    this.assertInsideRoot(resolve(dirname(linkPath), target));
+    await mkdir(dirname(linkPath), { recursive: true });
+    await rm(linkPath, { recursive: true, force: true });
+    await symlink(target, linkPath, "dir");
+  }
+
+  /** Resolves a project-relative path, refusing anything outside the root. */
+  private resolve(path: string): string {
+    const absolute = resolve(this.root, path);
+    this.assertInsideRoot(absolute);
+    return absolute;
+  }
+
+  private assertInsideRoot(absolute: string): void {
+    const fromRoot = relative(this.root, absolute);
+    if (fromRoot.startsWith("..") || isAbsolute(fromRoot)) {
+      throw new Error(`Path escapes the project root: ${absolute}`);
+    }
+  }
+}
+
+function isNotFound(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}

package/src/adapters/outbound/package_bundle.ts

@@ -0,0 +1,56 @@
+import { existsSync } from "node:fs";
+import { readFile, readdir } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Bundle, BundledFile, BundledSkill } from "../../app/ports/bundle.ts";
+
+/** The skills and templates shipped in the installed Cruze package. */
+export class PackageBundle implements Bundle {
+  readonly version: string;
+  private readonly root: string;
+
+  private constructor(root: string, version: string) {
+    this.root = root;
+    this.version = version;
+  }
+
+  /** Finds the package root by walking up from this module to the nearest package.json. */
+  static async locate(fromUrl: string = import.meta.url): Promise<PackageBundle> {
+    let dir = dirname(fileURLToPath(fromUrl));
+    while (!existsSync(join(dir, "package.json"))) {
+      const parent = dirname(dir);
+      if (parent === dir) throw new Error("Cannot find the Cruze package root");
+      dir = parent;
+    }
+    const manifest = JSON.parse(await readFile(join(dir, "package.json"), "utf8")) as { version: string };
+    return new PackageBundle(dir, manifest.version);
+  }
+
+  async skills(): Promise<BundledSkill[]> {
+    const skillsDir = join(this.root, "skills");
+    const entries = await readdir(skillsDir, { withFileTypes: true });
+    const folders = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+    return Promise.all(
+      folders.map(async (folder) => ({ folder, files: await readTree(join(skillsDir, folder)) })),
+    );
+  }
+
+  async template(path: string): Promise<string> {
+    return readFile(join(this.root, "templates", path), "utf8");
+  }
+
+  async formatTemplate(name: string): Promise<string> {
+    return readFile(join(this.root, "skills", "formats", "templates", name), "utf8");
+  }
+}
+
+async function readTree(dir: string): Promise<BundledFile[]> {
+  const entries = await readdir(dir, { withFileTypes: true, recursive: true });
+  const files = entries.filter((entry) => entry.isFile()).map((entry) => join(entry.parentPath, entry.name));
+  return Promise.all(
+    files.sort().map(async (file) => ({
+      path: relative(dir, file).split(sep).join("/"),
+      text: await readFile(file, "utf8"),
+    })),
+  );
+}

package/src/adapters/outbound/process_agent_runner.ts

@@ -0,0 +1,26 @@
+import { spawn } from "node:child_process";
+import type { AgentRun, AgentRunner } from "../../app/ports/agent_runner.ts";
+
+/** Runs an agent's non-interactive mode, such as `claude -p`, as a child process. */
+export class ProcessAgentRunner implements AgentRunner {
+  private readonly cwd: string;
+
+  constructor(cwd: string) {
+    this.cwd = cwd;
+  }
+
+  run(command: string[], prompt: string): Promise<AgentRun> {
+    const [program, ...args] = command;
+    if (program === undefined) return Promise.resolve({ exitCode: 127, output: "", error: "no command configured" });
+    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 }));
+      child.stdin.end(prompt);
+    });
+  }
+}

package/src/adapters/outbound/system_clock.ts

@@ -0,0 +1,14 @@
+import type { Clock } from "../../app/ports/clock.ts";
+
+/** The machine's clock, with dates in its local time zone. */
+export class SystemClock implements Clock {
+  now(): Date {
+    return new Date();
+  }
+
+  today(): string {
+    const date = new Date();
+    const pad = (n: number): string => String(n).padStart(2, "0");
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+  }
+}

package/src/adapters/outbound/terminal_prompter.ts

@@ -0,0 +1,22 @@
+import { createInterface } from "node:readline/promises";
+import type { Prompter } from "../../app/ports/prompter.ts";
+
+/** Asks on the terminal. Questions go to stderr so stdout stays machine-readable. */
+export class TerminalPrompter implements Prompter {
+  async ask(question: string, fallback: string): Promise<string> {
+    const terminal = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+      const answer = await terminal.question(`${question} (${fallback}): `);
+      return answer.trim() === "" ? fallback : answer.trim();
+    } finally {
+      terminal.close();
+    }
+  }
+}
+
+/** Used when nobody can answer: without a terminal, or with --yes. */
+export class DefaultAnswerPrompter implements Prompter {
+  async ask(_question: string, fallback: string): Promise<string> {
+    return fallback;
+  }
+}

package/src/app/ports/agent_runner.ts

@@ -0,0 +1,11 @@
+/** 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. */
+  run(command: string[], prompt: string): Promise<AgentRun>;
+}
+
+export interface AgentRun {
+  exitCode: number;
+  output: string;
+  error: string;
+}

package/src/app/ports/bundle.ts

@@ -0,0 +1,22 @@
+/** The assets shipped inside the Cruze package: skills and templates. */
+
+export interface BundledFile {
+  /** Path relative to the skill folder, using forward slashes. */
+  path: string;
+  text: string;
+}
+
+export interface BundledSkill {
+  /** The skill's folder name in the bundle, such as `plan`. */
+  folder: string;
+  files: BundledFile[];
+}
+
+export interface Bundle {
+  readonly version: string;
+  skills(): Promise<BundledSkill[]>;
+  /** A template's text, by path relative to the templates directory. */
+  template(path: string): Promise<string>;
+  /** A document template from the cruze-formats skill, such as `feature.md`. */
+  formatTemplate(name: string): Promise<string>;
+}

package/src/app/ports/clock.ts

@@ -0,0 +1,6 @@
+/** The current time, so use cases stay deterministic under test. */
+export interface Clock {
+  now(): Date;
+  /** Today's date in the user's time zone, as `YYYY-MM-DD`, for dated IDs and records. */
+  today(): string;
+}

package/src/app/ports/project_files.ts

@@ -0,0 +1,20 @@
+/** The files of the project Cruze is working in. Paths are relative to the project root. */
+export interface ProjectFiles {
+  exists(path: string): Promise<boolean>;
+  /** A file's text, or undefined when it doesn't exist. */
+  readText(path: string): Promise<string | undefined>;
+  /** Writes a file, creating parent directories as needed. */
+  writeText(path: string, text: string): Promise<void>;
+  /** Appends to a file, creating it and its parent directories as needed. */
+  appendText(path: string, text: string): Promise<void>;
+  /** Names of the entries directly inside a directory; empty when it doesn't exist. */
+  listEntries(path: string): Promise<string[]>;
+  /** Every file under a directory, recursively, as project-relative paths; empty when it doesn't exist. */
+  listFiles(path: string): Promise<string[]>;
+  /** Moves a file or directory, creating the destination's parent directories. */
+  move(from: string, to: string): Promise<void>;
+  /** Removes a file, a directory tree or a link (never what a link points to). */
+  remove(path: string): Promise<void>;
+  /** Creates a symbolic link at `path` pointing to `target`, a path relative to the link's directory. */
+  link(path: string, target: string): Promise<void>;
+}

package/src/app/ports/prompter.ts

@@ -0,0 +1,5 @@
+/** Asks the person running Cruze a question. */
+export interface Prompter {
+  /** Returns the answer, or `fallback` when the answer is empty or nobody can be asked. */
+  ask(question: string, fallback: string): Promise<string>;
+}

package/src/app/ports/repository.ts

@@ -0,0 +1,13 @@
+/** 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>>;
+}

package/src/app/project_context.ts

@@ -0,0 +1,45 @@
+import { buildProjectView, type ProjectView } from "../domain/project/project_view.ts";
+import { 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";
+import type { ProjectFiles } from "./ports/project_files.ts";
+import type { Repository } from "./ports/repository.ts";
+
+/** What the project use cases work with. */
+export interface ProjectDeps {
+  files: ProjectFiles;
+  clock: Clock;
+  repository: Repository;
+  bundle: Bundle;
+}
+
+/** Reads every document under docs/ and .cruze/ into a view. */
+export async function loadView(files: ProjectFiles): Promise<ProjectView> {
+  const snapshot = new Map<string, string>();
+  for (const root of SNAPSHOT_ROOTS) {
+    for (const path of await files.listFiles(root)) {
+      const text = await files.readText(path);
+      if (text !== undefined) snapshot.set(path, text);
+    }
+  }
+  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]));
+}
+
+/** 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;
+}

package/src/app/use_cases/abandon_work.ts

@@ -0,0 +1,42 @@
+import { CruzeError } from "../../domain/cruze_error.ts";
+import { readRows, upsertRow } from "../../domain/edits/managed_tables.ts";
+import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
+import { PATHS } from "../../domain/project/layout.ts";
+import { appendJournal, loadView, type ProjectDeps } from "../project_context.ts";
+
+export interface AbandonReport {
+  ref: string;
+  archivedTo: string;
+  /** The feature-map slug it went back to, for a feature that may return. */
+  futureList?: string;
+}
+
+/**
+ * Stops a feature or standalone change for good: archives its folder with the reason, marks it
+ * abandoned on the roadmap, and puts a feature back on the future list. Changes that already
+ * landed stay in the living docs.
+ */
+export async function abandonWork(deps: ProjectDeps, ref: string, reason: string): Promise<AbandonReport> {
+  if (reason.trim() === "") throw new CruzeError("missing-reason", "abandoning work needs a reason");
+  const view = await loadView(deps.files);
+  const { item } = resolveArtifact(view, ref);
+  if (item === undefined || item.archived) throw new CruzeError("not-found", `"${ref}" is not an active feature or standalone change`);
+  if (item.kind === "change") throw new CruzeError("not-abandonable", `${item.ref} belongs to a feature; remove it from the feature's Changes table through rethink instead`);
+
+  const slug = typeof item.doc.frontmatter?.["roadmap"] === "string" ? item.doc.frontmatter["roadmap"] : undefined;
+  const roadmap = view.snapshot.get(PATHS.roadmap);
+  if (slug !== undefined && roadmap !== undefined && roadmap.includes("## Status")) {
+    await deps.files.writeText(PATHS.roadmap, upsertRow(roadmap, "Status", [slug, item.folderName, "abandoned"]));
+  }
+  const report: AbandonReport = { ref: item.ref, archivedTo: `${PATHS.archiveDir}/${item.folderName}` };
+  const vision = view.snapshot.get(PATHS.vision);
+  if (item.kind === "feature" && slug !== undefined && vision !== undefined && vision.includes("### Future")) {
+    if (!readRows(vision, "Future").some((row) => row[0] === slug)) {
+      await deps.files.writeText(PATHS.vision, upsertRow(vision, "Future", [slug, String(item.doc.frontmatter?.["title"] ?? slug), ""]));
+    }
+    report.futureList = slug;
+  }
+  await appendJournal(deps, item.folder, "abandon", { item: item.ref, reason: reason.trim() });
+  await deps.files.move(item.folder, report.archivedTo);
+  return report;
+}

package/src/app/use_cases/approve_artifact.ts

@@ -0,0 +1,146 @@
+import { evaluateApproval } from "../../domain/approvals/evaluate.ts";
+import { fingerprint, isApprovable } from "../../domain/approvals/fingerprint.ts";
+import { latestApproval, serializeApprovals, withApproval, type ApprovalRecord } from "../../domain/approvals/records.ts";
+import { CruzeError } from "../../domain/cruze_error.ts";
+import { updateProgress } from "../../domain/edits/progress_block.ts";
+import { setStatus, stampMissingStatuses } from "../../domain/edits/status_lines.ts";
+import { statusOf } from "../../domain/elements.ts";
+import { elementHash } from "../../domain/hashing.ts";
+import { parseMarkdown } from "../../domain/markdown.ts";
+import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
+import { readDelta } from "../../domain/project/deltas.ts";
+import { PATHS } from "../../domain/project/layout.ts";
+import { isPlanned, readChangesTable } from "../../domain/project/plan_parts.ts";
+import { readProgress } from "../../domain/project/progress.ts";
+import { approvalFolder, approvalsPath, type ProjectView } from "../../domain/project/project_view.ts";
+import { featureOf } from "../../domain/project/work_items.ts";
+import { validateProject } from "../../domain/validation/validate_project.ts";
+import { appendJournal, loadView, withFiles, type ProjectDeps } from "../project_context.ts";
+
+export interface ApproveReport {
+  artifact: string;
+  hash: string;
+  upstream: string[];
+  /** Elements that received a `planned` status. */
+  stamped: string[];
+  /** The branch a change was bound to, when this approval bound it. */
+  bound?: string;
+  /** Built elements this approval set back to planned, because a rethink changed them. */
+  replanned: string[];
+  /** Elements whose current living text this feature accepted after a land conflict. */
+  rebased: string[];
+}
+
+export interface ApproveOptions {
+  /** Architecture elements to set back to `planned`: their design changed and their code must follow. */
+  replan?: string[];
+  /** Elements this work's delta changes whose living text changed since its last approval; the approval accepts the current text. */
+  rebase?: string[];
+}
+
+/**
+ * Records a person's approval of a document: its design hash and the hashes of everything
+ * upstream it relies on. Refuses invalid documents and documents whose upstream isn't approved.
+ */
+export async function approveArtifact(deps: ProjectDeps, ref: string, options: ApproveOptions = {}): Promise<ApproveReport> {
+  let view = await loadView(deps.files);
+  const { path, item } = resolveArtifact(view, ref);
+  if (!isApprovable(view, path)) throw new CruzeError("not-approvable", `${path} is not something you approve; it changes through approved work`);
+  requireUpstreamApproved(view, path);
+  if (item?.kind === "feature" && readChangesTable(item.doc).length === 0) {
+    throw new CruzeError("not-designed", `${path} has no changes yet; architect designs and splits it before approval`);
+  }
+  if (item !== undefined && item.kind !== "feature" && !isPlanned(item.doc)) {
+    throw new CruzeError("not-planned", `${path} has no test plan or tasks yet; plan it before approving`);
+  }
+
+  const edits = new Map<string, string>();
+  let text = view.snapshot.get(path) ?? "";
+  let stamped: string[] = [];
+  if (path === PATHS.architecture) ({ text, stamped } = stampMissingStatuses(text));
+  const replanned = options.replan ?? [];
+  if (replanned.length > 0 && path !== PATHS.architecture) throw new CruzeError("replan-architecture-only", "--replan applies to the architecture");
+  for (const id of replanned) {
+    const element = view.living.elements.get(id);
+    if (element?.path !== PATHS.architecture || statusOf(element.doc, element.element) !== "built") {
+      throw new CruzeError("not-built", `${id} is not a built element of ${PATHS.architecture}`);
+    }
+    text = setStatus(text, id, "planned");
+  }
+  let bound: string | undefined;
+  if (item !== undefined && item.kind !== "feature" && readProgress(parseMarkdown(text)).branch === undefined) {
+    bound = (await deps.repository.currentBranch()) ?? undefined;
+    text = updateProgress(text, (progress) => {
+      if (bound !== undefined) progress.branch = bound;
+    });
+  }
+  if (text !== view.snapshot.get(path)) edits.set(path, text);
+  view = withFiles(view, edits);
+
+  const errors = validateProject(view).filter((p) => p.path === path && p.severity === "error");
+  if (errors.length > 0) {
+    const listing = errors.map((p) => `  ${p.path}:${p.line ?? ""} ${p.message}`).join("\n");
+    throw new CruzeError("invalid", `${path} has ${errors.length} problem(s) to fix before approval:\n${listing}`);
+  }
+
+  const { hash, upstream } = fingerprint(view, path, parseMarkdown(text));
+  const folder = approvalFolder(view, path);
+  const current = view.approvals.get(folder) ?? { version: 1, approvals: [], merged: {} };
+  const rebased = options.rebase ?? [];
+  const deltaIds = item === undefined || item.kind === "change" ? new Set<string>() : readDelta(item.doc).ids;
+  requireRebased(view, deltaIds, latestApproval(current, path), rebased);
+  const merged = { ...current.merged };
+  for (const id of rebased) {
+    const living = view.living.elements.get(id);
+    if (living === undefined || (merged[id] === undefined && !deltaIds.has(id))) {
+      throw new CruzeError("not-in-delta", `${id} is not a living element that ${item?.ref ?? path} changes or merged`);
+    }
+    if (merged[id] !== undefined) merged[id] = elementHash(living.doc, living.element);
+  }
+  const approvals = withApproval({ ...current, merged }, {
+    artifact: path,
+    hash,
+    upstream,
+    approvedAt: deps.clock.now().toISOString(),
+    by: (await deps.repository.userName()) ?? "unknown",
+  });
+  for (const [changed, content] of edits) await deps.files.writeText(changed, content);
+  await deps.files.writeText(approvalsPath(folder), serializeApprovals(approvals));
+  await appendJournal(deps, folder, "approve", { artifact: path, hash, ...(replanned.length > 0 ? { replanned } : {}), ...(rebased.length > 0 ? { rebased } : {}) });
+  const report: ApproveReport = { artifact: path, hash, upstream: Object.keys(upstream), stamped, replanned, rebased };
+  if (bound !== undefined) report.bound = bound;
+  return report;
+}
+
+/**
+ * A feature or standalone change whose delta changes an element must have been written against
+ * that element's current text. When the living element changed since the last approval, through
+ * a rethink or another land, the delta would overwrite that edit, so approval waits until the
+ * delta is reconciled and the element is named with --rebase.
+ */
+function requireRebased(view: ProjectView, deltaIds: Set<string>, previous: ApprovalRecord | undefined, rebased: string[]): void {
+  if (previous === undefined) return;
+  const moved = [...deltaIds].filter((id) => {
+    const living = view.living.elements.get(id);
+    const before = previous.upstream[id];
+    return living !== undefined && before !== undefined && before !== elementHash(living.doc, living.element) && !rebased.includes(id);
+  });
+  if (moved.length > 0) {
+    throw new CruzeError(
+      "rebase-required",
+      `the living text of ${moved.join(", ")} changed since the last approval, and this work's delta changes ${moved.length === 1 ? "it" : "them"}. Rewrite the delta to keep that change, then approve with ${moved.map((id) => `--rebase ${id}`).join(" ")}`,
+    );
+  }
+}
+
+/** A change needs its feature approved; a feature or standalone change needs the architecture approved. */
+function requireUpstreamApproved(view: ProjectView, path: string): void {
+  const item = view.items.find((i) => i.path === path);
+  if (item === undefined) return;
+  const upstream = item.kind === "change" ? featureOf(view.items, item)?.path : view.snapshot.has(PATHS.architecture) ? PATHS.architecture : undefined;
+  if (upstream === undefined) return;
+  const status = evaluateApproval(view, upstream);
+  if (status.state !== "approved") {
+    throw new CruzeError("upstream-not-approved", `approve ${upstream} first; it is ${status.state}${status.changed.length > 0 ? ` (${status.changed.join(", ")})` : ""}`);
+  }
+}