@printpractical/cruze 0.0.1

package/src/app/use_cases/check_code.ts

@@ -0,0 +1,90 @@
+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 type { CruzeConfig } from "../../domain/config.ts";
+import type { ProjectView } from "../../domain/project/project_view.ts";
+import { resolveChange } from "../../domain/project/artifact_ref.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 type { ProjectFiles } from "../ports/project_files.ts";
+
+export interface CheckReport {
+  passed: boolean;
+  checked: number;
+  findings: CheckFinding[];
+}
+
+/**
+ * Enforces layer rules and file budgets. Layer violations always fail; budget and
+ * module-map 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 sources = await readMatching(deps.files, config.source);
+  for (const file of options.files ?? []) {
+    if (!sources.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);
+    }
+  }
+  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);
+  return { passed: failing.length === 0, checked: only?.length ?? sources.size, findings };
+}
+
+export interface TraceResult extends TraceReport {
+  passed: boolean;
+  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");
+  }
+  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;
+}
+
+/** Files matching any glob, read from the smallest directories that can contain them. */
+async function readMatching(files: ProjectFiles, globs: string[]): Promise<Map<string, string>> {
+  const result = new Map<string, string>();
+  const bases = [...new Set(globs.map(globBase))];
+  for (const base of bases) {
+    const listed = await files.listFiles(base === "" ? "." : base);
+    for (const path of listed) {
+      if (result.has(path) || !matchesAny(path, globs)) continue;
+      const text = await files.readText(path);
+      if (text !== undefined) result.set(path, text);
+    }
+  }
+  return result;
+}
+
+/** The directory part of a glob before its first wildcard. */
+function globBase(glob: string): string {
+  const segments = glob.split("/");
+  const fixed = segments.slice(0, segments.findIndex((s) => /[*?{]/.test(s)));
+  return fixed.join("/");
+}
+
+function modulePaths(view: ProjectView): string[] {
+  return [...view.living.elements.values()]
+    .filter((e) => e.id.startsWith("MOD-"))
+    .flatMap((e) => (factsOf(e.doc, e.element).get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? "")));
+}

package/src/app/use_cases/init_project.ts

@@ -0,0 +1,59 @@
+import { parseProjectName } from "../../domain/project_name.ts";
+import { INIT_SCAFFOLD, renderTemplate } 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";
+import { installSkills, type InstallSkillsReport } from "./install_skills.ts";
+
+export interface InitProjectRequest {
+  /** The project name; asked for when absent. */
+  name?: string;
+  /** Offered as the default answer when asking for the name. */
+  defaultName: string;
+  agents: string[];
+  /**
+   * How CI runs this version of Cruze through npx, such as `github:PrintPractical/cruze#v0.0.1`
+   * for a git install. Defaults to the published npm package at this version.
+   */
+  package?: string;
+}
+
+export interface InitProjectReport {
+  project: string;
+  created: string[];
+  /** Files that already existed and were left untouched. */
+  skipped: string[];
+  skills: InstallSkillsReport;
+}
+
+/**
+ * Gives a repository the Cruze starting files and installs the skills. Existing
+ * files are never overwritten, so running it in a brownfield repo is safe.
+ */
+export async function initProject(
+  deps: { files: ProjectFiles; bundle: Bundle; prompter: Prompter },
+  request: InitProjectRequest,
+): Promise<InitProjectReport> {
+  const { files, bundle, prompter } = deps;
+  const project = parseProjectName(request.name ?? (await prompter.ask("Project name", request.defaultName)));
+  const values = {
+    project_name: project,
+    project_name_quoted: JSON.stringify(project),
+    cruze_version: bundle.version,
+    cruze_package: request.package ?? `@printpractical/cruze@${bundle.version}`,
+  };
+
+  const created: string[] = [];
+  const skipped: string[] = [];
+  for (const entry of INIT_SCAFFOLD) {
+    if (await files.exists(entry.path)) {
+      skipped.push(entry.path);
+      continue;
+    }
+    await files.writeText(entry.path, renderTemplate(await bundle.template(entry.template), values));
+    created.push(entry.path);
+  }
+
+  const skills = await installSkills({ files, bundle }, { agents: request.agents });
+  return { project, created, skipped, skills };
+}

package/src/app/use_cases/install_skills.ts

@@ -0,0 +1,93 @@
+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 { 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";
+
+export interface InstallSkillsRequest {
+  /** Agents to link skills for even when the project shows no sign of using them. */
+  agents: string[];
+}
+
+export interface InstallSkillsReport {
+  version: string;
+  installed: string[];
+  removed: string[];
+  linked: Array<{ agent: string; dir: string }>;
+}
+
+/**
+ * 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.
+ */
+export async function installSkills(
+  deps: { files: ProjectFiles; bundle: Bundle },
+  request: InstallSkillsRequest,
+): Promise<InstallSkillsReport> {
+  const { files, bundle } = deps;
+  const skills = await bundle.skills();
+  assertValid(skills);
+
+  const names = skills.map((skill) => installedSkillName(skill.folder));
+  const removed = await removeStaleSkills(files, SHARED_SKILLS_DIR, names);
+  for (const skill of skills) {
+    await writeSkill(files, skill);
+  }
+
+  const linked: InstallSkillsReport["linked"] = [];
+  for (const agent of await agentsToLink(files, request.agents)) {
+    const home = agentSkillHome(agent);
+    if (home === undefined) continue;
+    await removeStaleSkills(files, home.skillsDir, []);
+    for (const name of names) {
+      const linkPath = posix.join(home.skillsDir, name);
+      await files.link(linkPath, posix.relative(home.skillsDir, posix.join(SHARED_SKILLS_DIR, name)));
+    }
+    linked.push({ agent, dir: home.skillsDir });
+  }
+
+  return { version: bundle.version, installed: names, removed, linked };
+}
+
+function assertValid(skills: BundledSkill[]): void {
+  const problems = skills.flatMap((skill) => {
+    const skillFile = skill.files.find((file) => file.path === SKILL_FILE);
+    return skillFile === undefined ? [`${skill.folder}: ${SKILL_FILE} is missing`] : skillProblems(skill.folder, skillFile.text);
+  });
+  if (problems.length > 0) {
+    throw new CruzeError("invalid-bundle", `The bundled skills are invalid:\n${problems.join("\n")}`);
+  }
+}
+
+async function writeSkill(files: ProjectFiles, skill: BundledSkill): Promise<void> {
+  const dir = posix.join(SHARED_SKILLS_DIR, installedSkillName(skill.folder));
+  await files.remove(dir);
+  for (const file of skill.files) {
+    await files.writeText(posix.join(dir, file.path), file.text);
+  }
+}
+
+/** Removes Cruze skills in `dir` that are not in `keep`, returning their names. */
+async function removeStaleSkills(files: ProjectFiles, dir: string, keep: string[]): Promise<string[]> {
+  const stale = (await files.listEntries(dir)).filter((name) => isInstalledSkillName(name) && !keep.includes(name));
+  for (const name of stale) {
+    await files.remove(posix.join(dir, name));
+  }
+  return stale;
+}
+
+async function agentsToLink(files: ProjectFiles, requested: string[]): Promise<string[]> {
+  const unknown = requested.filter((agent) => agentSkillHome(agent) === undefined);
+  if (unknown.length > 0) {
+    throw new CruzeError("unknown-agent", `Unknown agent: ${unknown.join(", ")}. Known agents: ${knownAgents().join(", ")}.`);
+  }
+  const agents = new Set(requested);
+  for (const home of AGENT_SKILL_HOMES) {
+    for (const marker of home.markers) {
+      if (await files.exists(marker)) agents.add(home.agent);
+    }
+  }
+  return [...agents];
+}

package/src/app/use_cases/journal_events.ts

@@ -0,0 +1,48 @@
+import { CruzeError } from "../../domain/cruze_error.ts";
+import { recordedEventProblems, type JournalEntry } from "../../domain/journal.ts";
+import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
+import { appendJournal, loadView, type ProjectDeps } from "../project_context.ts";
+
+/** Records an event a skill observed: a rethink, a review round, a disposition, an override or a bug. */
+export async function recordEvent(deps: ProjectDeps, event: string, fields: Record<string, string>, item?: string): Promise<JournalEntry> {
+  const problems = recordedEventProblems(event, fields);
+  if (problems.length > 0) throw new CruzeError("invalid-event", problems.join("; "));
+  let folder = ".cruze";
+  if (item !== undefined) {
+    const resolved = resolveArtifact(await loadView(deps.files), item).item;
+    if (resolved === undefined) throw new CruzeError("not-found", `"${item}" is not a feature or change`);
+    folder = resolved.folder;
+    fields = { ...fields, item: resolved.ref };
+  }
+  return appendJournal(deps, folder, event, { ...fields, cruze: deps.bundle.version });
+}
+
+export async function listEvents(deps: ProjectDeps, event?: string): Promise<JournalEntry[]> {
+  const { journal } = await loadView(deps.files);
+  return event === undefined ? journal : journal.filter((entry) => entry.event === event);
+}
+
+export interface FeedbackExport {
+  format: "cruze-feedback/1";
+  cruze: string;
+  exported_at: string;
+  redacted: boolean;
+  entries: JournalEntry[];
+}
+
+/**
+ * Bundles the journal for the framework feedback loop. By default the project name and
+ * the approver's identity are redacted, since the bundle may leave the project.
+ */
+export async function exportFeedback(deps: ProjectDeps, redact: boolean): Promise<FeedbackExport> {
+  const view = await loadView(deps.files);
+  const project = view.config?.config?.project ?? "";
+  const scrub = (value: unknown): unknown => {
+    if (typeof value === "string") return project === "" ? value : value.split(project).join("<project>");
+    if (Array.isArray(value)) return value.map(scrub);
+    if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, scrub(v)]));
+    return value;
+  };
+  const entries = redact ? view.journal.map((entry) => ({ ...(scrub(entry) as JournalEntry), by: "<redacted>" })) : view.journal;
+  return { format: "cruze-feedback/1", cruze: deps.bundle.version, exported_at: deps.clock.now().toISOString(), redacted: redact, entries };
+}

package/src/app/use_cases/land_change.ts

@@ -0,0 +1,113 @@
+import { evaluateApproval } from "../../domain/approvals/evaluate.ts";
+import { fingerprint } from "../../domain/approvals/fingerprint.ts";
+import { serializeApprovals, withApproval, type ApprovalsFile } from "../../domain/approvals/records.ts";
+import { CruzeError } from "../../domain/cruze_error.ts";
+import { renderAgentsFile } from "../../domain/edits/agents_file.ts";
+import { applyBookkeeping } from "../../domain/land/bookkeeping.ts";
+import { planMerge } from "../../domain/land/merge_plan.ts";
+import { parseMarkdown } from "../../domain/markdown.ts";
+import { resolveChange } from "../../domain/project/artifact_ref.ts";
+import { PATHS } from "../../domain/project/layout.ts";
+import { readTasks } 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 { changesOf, featureOf, type WorkItem } from "../../domain/project/work_items.ts";
+import { isVerified } from "../../domain/status/verification.ts";
+import { activeChange } from "../../domain/status/work_status.ts";
+import { validateProject } from "../../domain/validation/validate_project.ts";
+import { appendJournal, loadView, withFiles, type ProjectDeps } from "../project_context.ts";
+
+const AGENTS_FILE = "AGENTS.md";
+
+export interface LandReport {
+  change: string;
+  merged: string[];
+  built: string[];
+  removed: string[];
+  restamped: string[];
+  finished: boolean;
+  archivedTo?: string;
+}
+
+/**
+ * Lands a finished change: merges its work into the living docs, re-stamps the approvals the
+ * merge would otherwise make stale, records the land, and archives the work once it is finished.
+ * Nothing is written unless the merged docs still validate.
+ */
+export async function landChange(deps: ProjectDeps, ref?: string, options: { override?: string } = {}): Promise<LandReport> {
+  const view = await loadView(deps.files);
+  const change = ref !== undefined ? resolveChange(view, ref) : activeChange(view, await deps.repository.currentBranch());
+  if (change === undefined) throw new CruzeError("no-active-change", "no change is bound to this branch; name one to land");
+  const source = change.kind === "change" ? featureOf(view.items, change) : change;
+  if (source === undefined) throw new CruzeError("orphan-change", `${change.ref} has no feature.md`);
+  requireReady(view, change, source);
+  const verified = isVerified(view.journal, change);
+  if (!verified && (options.override ?? "").trim() === "") {
+    throw new CruzeError("not-verified", `${change.ref} has no accepted verification; run verify, or land with --override <reason>`);
+  }
+
+  const restamp = [PATHS.architecture, source.path, ...(source === change ? [] : changesOf(view.items, source).map((c) => c.path))]
+    .filter((path, i, all) => all.indexOf(path) === i && view.snapshot.has(path) && evaluateApproval(view, path).state === "approved");
+
+  const plan = planMerge(view, change, source);
+  const commit = await deps.repository.headCommit();
+  const landed = `${deps.clock.today()}${commit === null ? "" : ` (${commit})`}`;
+  const books = applyBookkeeping(view, change, source, landed, plan.files);
+  const merged = withFiles(view, plan.files);
+  requireStillValid(view, merged);
+
+  const approvals = new Map<string, ApprovalsFile>();
+  const by = (await deps.repository.userName()) ?? "unknown";
+  for (const path of restamp) {
+    const folder = approvalFolder(merged, path);
+    const { hash, upstream } = fingerprint(merged, path, parseMarkdown(merged.snapshot.get(path) ?? ""));
+    const file = approvals.get(folder) ?? merged.approvals.get(folder) ?? { version: 1, approvals: [], merged: {} };
+    approvals.set(folder, withApproval(file, { artifact: path, hash, upstream, approvedAt: deps.clock.now().toISOString(), by, basis: `land ${change.ref}` }));
+  }
+  const sourceApprovals = approvals.get(source.folder) ?? merged.approvals.get(source.folder) ?? { version: 1, approvals: [], merged: {} };
+  approvals.set(source.folder, { ...sourceApprovals, merged: plan.merged });
+
+  for (const [path, text] of plan.files) await deps.files.writeText(path, text);
+  for (const [folder, file] of approvals) await deps.files.writeText(approvalsPath(folder), serializeApprovals(file));
+  for (const path of restamp) {
+    const record = approvals.get(approvalFolder(merged, path))?.approvals.find((r) => r.artifact === path);
+    await appendJournal(deps, approvalFolder(merged, path), "approve", { artifact: path, hash: record?.hash, basis: `land ${change.ref}` });
+  }
+  if (!verified) await appendJournal(deps, source.folder, "override", { gate: "land", reason: options.override, item: change.ref });
+  await appendJournal(deps, source.folder, "land", { change: change.ref, merged: plan.mergedIds, built: plan.built, removed: plan.removed, release: books.release, commit });
+  if (books.archive !== undefined) await deps.files.move(books.archive.from, books.archive.to);
+  const agents = await deps.files.readText(AGENTS_FILE);
+  if (agents !== undefined) {
+    const rendered = renderAgentsFile(agents, merged);
+    if (rendered !== agents) await deps.files.writeText(AGENTS_FILE, rendered);
+  }
+
+  const report: LandReport = { change: change.ref, merged: plan.mergedIds, built: plan.built, removed: plan.removed, restamped: restamp, finished: books.finished };
+  if (books.archive !== undefined) report.archivedTo = books.archive.to;
+  return report;
+}
+
+/** The change, its feature and the architecture are approved and current, valid, and every task is done. */
+function requireReady(view: ProjectView, change: WorkItem, source: WorkItem): void {
+  const reasons: string[] = [];
+  for (const path of [change.path, source.path, PATHS.architecture].filter((p, i, all) => all.indexOf(p) === i && view.snapshot.has(p))) {
+    const status = evaluateApproval(view, path);
+    if (status.state !== "approved") reasons.push(`${path} is ${status.state}${status.changed.length > 0 ? ` (${status.changed.join(", ")})` : ""}`);
+  }
+  const errors = validateProject(view).filter((p) => p.severity === "error" && (p.path === change.path || p.path === source.path));
+  reasons.push(...errors.map((p) => `${p.path}:${p.line ?? ""} ${p.message}`));
+  const progress = readProgress(change.doc);
+  const open = readTasks(change.doc).tasks.filter((task) => (progress.tasks.get(task.number) ?? null) === null).map((task) => task.number);
+  if (open.length > 0) reasons.push(`tasks not done: ${open.join(", ")}`);
+  if (reasons.length > 0) throw new CruzeError("not-ready", `${change.ref} cannot land yet:\n  ${reasons.join("\n  ")}`);
+}
+
+/** The merge may not introduce errors into the living docs. */
+function requireStillValid(before: ProjectView, after: ProjectView): void {
+  const key = (p: { path: string; message: string }): string => `${p.path}|${p.message}`;
+  const existing = new Set(validateProject(before).map(key));
+  const introduced = validateProject(after).filter((p) => p.severity === "error" && p.path.startsWith("docs/") && !existing.has(key(p)));
+  if (introduced.length > 0) {
+    throw new CruzeError("merge-invalid", `landing would break the living docs; nothing was written:\n  ${introduced.map((p) => `${p.path}:${p.line ?? ""} ${p.message}`).join("\n  ")}`);
+  }
+}

package/src/app/use_cases/new_project_doc.ts

@@ -0,0 +1,40 @@
+import { CruzeError } from "../../domain/cruze_error.ts";
+import { PATHS } from "../../domain/project/layout.ts";
+import { requireSlug } from "../../domain/project/new_items.ts";
+import { renderTemplate } from "../../domain/scaffold.ts";
+import { appendJournal, loadView, type ProjectDeps } from "../project_context.ts";
+
+export type ProjectDocKind = "vision" | "glossary" | "architecture" | "roadmap";
+
+export const PROJECT_DOC_KINDS: readonly ProjectDocKind[] = ["vision", "glossary", "architecture", "roadmap"];
+
+export interface NewDocReport {
+  kind: ProjectDocKind | "note";
+  path: string;
+}
+
+/** Creates one of the project's living documents from its template, named for the project. */
+export async function createProjectDoc(deps: ProjectDeps, kind: ProjectDocKind): Promise<NewDocReport> {
+  const view = await loadView(deps.files);
+  const path = PATHS[kind];
+  if (view.snapshot.has(path)) throw new CruzeError("exists", `${path} already exists`);
+  const project = view.config?.config?.project ?? "";
+  if (project === "") throw new CruzeError("no-config", `${PATHS.config} is missing or has no project name; run cruze init first`);
+  const values = { project_name: project, id: "", title: "", date: deps.clock.today() };
+  await deps.files.writeText(path, renderTemplate(await deps.bundle.formatTemplate(`${kind}.md`), values));
+  await appendJournal(deps, ".cruze", "new", { kind, ref: path });
+  return { kind, path };
+}
+
+/** Creates a dated note in `.cruze/notes/`, such as a captured explore session or research evidence. */
+export async function createNote(deps: ProjectDeps, slug: string, title: string): Promise<NewDocReport> {
+  requireSlug(slug);
+  if (title.trim() === "") throw new CruzeError("missing-title", "a title is required");
+  const view = await loadView(deps.files);
+  const date = deps.clock.today();
+  const base = `${PATHS.notesDir}/${date}-${slug}`;
+  let path = `${base}.md`;
+  for (let n = 2; view.snapshot.has(path); n++) path = `${base}-${n}.md`;
+  await deps.files.writeText(path, `# ${title}\n\n- Date: ${date}\n\n`);
+  return { kind: "note", path };
+}

package/src/app/use_cases/new_work_item.ts

@@ -0,0 +1,75 @@
+import { CruzeError } from "../../domain/cruze_error.ts";
+import { upsertRow } from "../../domain/edits/managed_tables.ts";
+import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
+import { PATHS } from "../../domain/project/layout.ts";
+import { allocateId, changeRow, fillTemplate, requireSlug } from "../../domain/project/new_items.ts";
+import { renderTemplate } from "../../domain/scaffold.ts";
+import { appendJournal, loadView, type ProjectDeps } from "../project_context.ts";
+
+export type NewKind = "feature" | "change" | "adr";
+
+export interface NewRequest {
+  kind: NewKind;
+  slug: string;
+  title: string;
+  /** For a change: the feature it belongs to. Without one, the change is standalone. */
+  feature?: string;
+  /** The roadmap item this feature or standalone change delivers; defaults to the slug. */
+  roadmap?: string;
+}
+
+export interface NewReport {
+  kind: "feature" | "change" | "standalone" | "adr";
+  ref: string;
+  path: string;
+}
+
+/** Creates a feature, change or ADR from its template, with a fresh ID. */
+export async function createWorkItem(deps: ProjectDeps, request: NewRequest): Promise<NewReport> {
+  const view = await loadView(deps.files);
+  const date = deps.clock.today();
+  const values = { id: "", title: request.title, date, project_name: "" };
+  if (request.title.trim() === "") throw new CruzeError("missing-title", "a title is required");
+
+  if (request.kind === "adr") {
+    requireSlug(request.slug);
+    const path = `${PATHS.adrDir}/${date}-${request.slug}.md`;
+    if (view.snapshot.has(path)) throw new CruzeError("exists", `${path} already exists`);
+    const text = renderTemplate(await deps.bundle.formatTemplate("adr.md"), values).replace(/^# .*$/m, `# ${request.title}`);
+    await deps.files.writeText(path, text);
+    await appendJournal(deps, ".cruze", "new", { kind: "adr", ref: path });
+    return { kind: "adr", ref: `ADR-${date}-${request.slug}`, path };
+  }
+
+  if (request.kind === "change" && request.feature !== undefined) {
+    const { item: feature } = resolveArtifact(view, request.feature);
+    if (feature === undefined || feature.kind !== "feature" || feature.archived) throw new CruzeError("not-a-feature", `"${request.feature}" is not an active feature`);
+    const row = changeRow(view, feature, request.slug);
+    const folder = `${feature.folder}/changes/${row.change}`;
+    const template = renderTemplate(await deps.bundle.formatTemplate("change.md"), { ...values, id: row.change });
+    await deps.files.writeText(`${folder}/change.md`, fillTemplate(template, { delivers: row.delivers, builds: [...row.builds, ...row.removes] }));
+    await appendJournal(deps, feature.folder, "new", { kind: "change", ref: `${feature.ref}/${row.change}` });
+    return { kind: "change", ref: `${feature.ref}/${row.change}`, path: `${folder}/change.md` };
+  }
+
+  const kind = request.kind === "feature" ? "feature" : "standalone";
+  const id = allocateId(view, date, request.slug);
+  const folder = `${kind === "feature" ? PATHS.featuresDir : PATHS.changesDir}/${id}`;
+  const roadmap = request.roadmap ?? (roadmapHasItem(view.snapshot.get(PATHS.roadmap), request.slug) ? request.slug : undefined);
+  const template = renderTemplate(await deps.bundle.formatTemplate(kind === "feature" ? "feature.md" : "standalone-change.md"), { ...values, id });
+  const path = `${folder}/${kind === "feature" ? "feature.md" : "change.md"}`;
+  await deps.files.writeText(path, fillTemplate(template, roadmap === undefined ? {} : { roadmap }));
+  const roadmapText = view.snapshot.get(PATHS.roadmap);
+  if (roadmap !== undefined && roadmapText !== undefined) {
+    await deps.files.writeText(PATHS.roadmap, upsertRow(roadmapText, "Status", [roadmap, id, "designing"]));
+  }
+  await appendJournal(deps, folder, "new", { kind, ref: id });
+  return { kind, ref: id, path };
+}
+
+/** Whether a roadmap phase lists this slug as an item. */
+function roadmapHasItem(roadmap: string | undefined, slug: string): boolean {
+  if (roadmap === undefined) return false;
+  const phases = roadmap.split(/^## /m).find((section) => section.startsWith("Phases")) ?? "";
+  return phases.split("\n").some((line) => line.startsWith(`| ${slug} |`));
+}

package/src/app/use_cases/project_status.ts

@@ -0,0 +1,73 @@
+import { CruzeError } from "../../domain/cruze_error.ts";
+import { readProgress } from "../../domain/project/progress.ts";
+import { buildProjectView } from "../../domain/project/project_view.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";
+
+export interface StatusReport extends ProjectStatus {
+  branch: string | null;
+}
+
+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;
+}
+
+/**
+ * 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 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()) {
+    const theirs = buildProjectView(new Map([...view.snapshot].filter(([p]) => p.startsWith("docs/")).concat([...(await deps.repository.filesOnBranch(other, ".cruze"))])));
+    // Work in flight on a branch is the change bound to it.
+    const boundThere = theirs.items.filter((i) => {
+      const bound = readProgress(i.doc).branch;
+      return !i.archived && 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 };
+}