@printpractical/cruze 0.0.1

package/dist/app/ports/repository.js

@@ -0,0 +1,13 @@
+/** The version-control repository the project lives in. Every operation tolerates a project outside git. */
+                             
+                                                                      
+                                          
+                                                           
+                                       
+                                                                       
+                                     
+                                                                       
+                                     
+                                                                                         
+                                                                           
+ 

package/dist/app/project_context.js

@@ -0,0 +1,45 @@
+import { buildProjectView,                  } from "../domain/project/project_view.js";
+import { SNAPSHOT_ROOTS } from "../domain/project/layout.js";
+import { journalPath, serializeEntry,                   } from "../domain/journal.js";
+                                                
+                                              
+                                                             
+                                                        
+
+/** What the project use cases work with. */
+                              
+                      
+               
+                         
+                 
+ 
+
+/** Reads every document under docs/ and .cruze/ into a view. */
+export async function loadView(files              )                       {
+  const snapshot = new Map                ();
+  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             , changes                     )              {
+  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             , folder        , event        , fields                         )                        {
+  const entry               = {
+    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/dist/app/use_cases/abandon_work.js

@@ -0,0 +1,42 @@
+import { CruzeError } from "../../domain/cruze_error.js";
+import { readRows, upsertRow } from "../../domain/edits/managed_tables.js";
+import { resolveArtifact } from "../../domain/project/artifact_ref.js";
+import { PATHS } from "../../domain/project/layout.js";
+import { appendJournal, loadView,                  } from "../project_context.js";
+
+                                
+              
+                     
+                                                                             
+                      
+ 
+
+/**
+ * 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             , ref        , reason        )                         {
+  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                = { 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/dist/app/use_cases/approve_artifact.js

@@ -0,0 +1,146 @@
+import { evaluateApproval } from "../../domain/approvals/evaluate.js";
+import { fingerprint, isApprovable } from "../../domain/approvals/fingerprint.js";
+import { latestApproval, serializeApprovals, withApproval,                     } from "../../domain/approvals/records.js";
+import { CruzeError } from "../../domain/cruze_error.js";
+import { updateProgress } from "../../domain/edits/progress_block.js";
+import { setStatus, stampMissingStatuses } from "../../domain/edits/status_lines.js";
+import { statusOf } from "../../domain/elements.js";
+import { elementHash } from "../../domain/hashing.js";
+import { parseMarkdown } from "../../domain/markdown.js";
+import { resolveArtifact } from "../../domain/project/artifact_ref.js";
+import { readDelta } from "../../domain/project/deltas.js";
+import { PATHS } from "../../domain/project/layout.js";
+import { isPlanned, readChangesTable } from "../../domain/project/plan_parts.js";
+import { readProgress } from "../../domain/project/progress.js";
+import { approvalFolder, approvalsPath,                  } from "../../domain/project/project_view.js";
+import { featureOf } from "../../domain/project/work_items.js";
+import { validateProject } from "../../domain/validation/validate_project.js";
+import { appendJournal, loadView, withFiles,                  } from "../project_context.js";
+
+                                
+                   
+               
+                     
+                                                   
+                    
+                                                                       
+                 
+                                                                                          
+                      
+                                                                                        
+                    
+ 
+
+                                 
+                                                                                                         
+                    
+                                                                                                                                     
+                    
+ 
+
+/**
+ * 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             , ref        , options                 = {})                         {
+  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                ();
+  let text = view.snapshot.get(path) ?? "";
+  let stamped           = [];
+  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                    ;
+  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        () : 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                = { 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             , deltaIds             , previous                            , rebased          )       {
+  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             , path        )       {
+  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(", ")})` : ""}`);
+  }
+}

package/dist/app/use_cases/check_code.js

@@ -0,0 +1,90 @@
+import { factsOf } from "../../domain/elements.js";
+import { checkSource,                   } from "../../domain/check/check_source.js";
+import { CruzeError } from "../../domain/cruze_error.js";
+import { matchesAny } from "../../domain/glob.js";
+                                                          
+                                                                        
+import { resolveChange } from "../../domain/project/artifact_ref.js";
+import { activeChange } from "../../domain/status/work_status.js";
+import { traceScenarios,                  } from "../../domain/trace.js";
+import { loadView,                  } from "../project_context.js";
+                                                              
+
+                              
+                  
+                  
+                           
+ 
+
+/**
+ * Enforces layer rules and file budgets. Layer violations always fail; budget and
+ * module-map warnings fail only with `ci`.
+ */
+export async function checkCode(deps             , options                                   )                       {
+  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 };
+}
+
+                                                  
+                  
+                
+ 
+
+/** Scenario-to-test traceability for this branch's change, or for every built scenario with `all`. */
+export async function traceTests(deps             , options                                   )                       {
+  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             )              {
+  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              , globs          )                               {
+  const result = new Map                ();
+  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        )         {
+  const segments = glob.split("/");
+  const fixed = segments.slice(0, segments.findIndex((s) => /[*?{]/.test(s)));
+  return fixed.join("/");
+}
+
+function modulePaths(view             )           {
+  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/dist/app/use_cases/init_project.js

@@ -0,0 +1,59 @@
+import { parseProjectName } from "../../domain/project_name.js";
+import { INIT_SCAFFOLD, renderTemplate } from "../../domain/scaffold.js";
+                                                 
+                                                              
+                                                     
+import { installSkills,                          } from "./install_skills.js";
+
+                                     
+                                                 
+                
+                                                                
+                      
+                   
+     
+                                                                                                
+                                                                              
+     
+                   
+ 
+
+                                    
+                  
+                    
+                                                            
+                    
+                              
+ 
+
+/**
+ * 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                                                             ,
+  request                    ,
+)                             {
+  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           = [];
+  const skipped           = [];
+  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/dist/app/use_cases/install_skills.js

@@ -0,0 +1,93 @@
+import { posix } from "node:path";
+import { CruzeError } from "../../domain/cruze_error.js";
+import { AGENT_SKILL_HOMES, SHARED_SKILLS_DIR, agentSkillHome, knownAgents } from "../../domain/agent_skill_homes.js";
+import { SKILL_FILE, installedSkillName, isInstalledSkillName, skillProblems } from "../../domain/skill.js";
+                                                               
+                                                              
+
+                                       
+                                                                                     
+                   
+ 
+
+                                      
+                  
+                      
+                    
+                                                
+ 
+
+/**
+ * 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                                         ,
+  request                      ,
+)                               {
+  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                                = [];
+  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                )       {
+  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              , skill              )                {
+  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              , dir        , keep          )                    {
+  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              , requested          )                    {
+  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/dist/app/use_cases/journal_events.js

@@ -0,0 +1,48 @@
+import { CruzeError } from "../../domain/cruze_error.js";
+import { recordedEventProblems,                   } from "../../domain/journal.js";
+import { resolveArtifact } from "../../domain/project/artifact_ref.js";
+import { appendJournal, loadView,                  } from "../project_context.js";
+
+/** Records an event a skill observed: a rethink, a review round, a disposition, an override or a bug. */
+export async function recordEvent(deps             , event        , fields                        , item         )                        {
+  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             , event         )                          {
+  const { journal } = await loadView(deps.files);
+  return event === undefined ? journal : journal.filter((entry) => entry.event === event);
+}
+
+                                 
+                             
+                
+                      
+                    
+                          
+ 
+
+/**
+ * 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             , redact         )                          {
+  const view = await loadView(deps.files);
+  const project = view.config?.config?.project ?? "";
+  const scrub = (value         )          => {
+    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)                ), by: "<redacted>" })) : view.journal;
+  return { format: "cruze-feedback/1", cruze: deps.bundle.version, exported_at: deps.clock.now().toISOString(), redacted: redact, entries };
+}

package/dist/app/use_cases/land_change.js

@@ -0,0 +1,113 @@
+import { evaluateApproval } from "../../domain/approvals/evaluate.js";
+import { fingerprint } from "../../domain/approvals/fingerprint.js";
+import { serializeApprovals, withApproval,                    } from "../../domain/approvals/records.js";
+import { CruzeError } from "../../domain/cruze_error.js";
+import { renderAgentsFile } from "../../domain/edits/agents_file.js";
+import { applyBookkeeping } from "../../domain/land/bookkeeping.js";
+import { planMerge } from "../../domain/land/merge_plan.js";
+import { parseMarkdown } from "../../domain/markdown.js";
+import { resolveChange } from "../../domain/project/artifact_ref.js";
+import { PATHS } from "../../domain/project/layout.js";
+import { readTasks } from "../../domain/project/plan_parts.js";
+import { readProgress } from "../../domain/project/progress.js";
+import { approvalFolder, approvalsPath,                  } from "../../domain/project/project_view.js";
+import { changesOf, featureOf,               } from "../../domain/project/work_items.js";
+import { isVerified } from "../../domain/status/verification.js";
+import { activeChange } from "../../domain/status/work_status.js";
+import { validateProject } from "../../domain/validation/validate_project.js";
+import { appendJournal, loadView, withFiles,                  } from "../project_context.js";
+
+const AGENTS_FILE = "AGENTS.md";
+
+                             
+                 
+                   
+                  
+                    
+                      
+                    
+                      
+ 
+
+/**
+ * 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             , ref         , options                        = {})                      {
+  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                       ();
+  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             = { 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             , change          , source          )       {
+  const reasons           = [];
+  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             , after             )       {
+  const key = (p                                   )         => `${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  ")}`);
+  }
+}