@printpractical/cruze 0.0.1

package/dist/domain/glob.js

@@ -0,0 +1,46 @@
+/**
+ * Glob matching for config paths: `**` matches any number of directories,
+ * `*` anything within one path segment, `?` one character, `{a,b}` either.
+ */
+
+const cache = new Map                ();
+
+export function matchesGlob(path        , glob        )          {
+  let regex = cache.get(glob);
+  if (regex === undefined) {
+    regex = new RegExp(`^${globToRegex(glob)}$`);
+    cache.set(glob, regex);
+  }
+  return regex.test(path);
+}
+
+export function matchesAny(path        , globs                   )          {
+  return globs.some((glob) => matchesGlob(path, glob));
+}
+
+function globToRegex(glob        )         {
+  let out = "";
+  for (let i = 0; i < glob.length; i++) {
+    const char = glob[i] ?? "";
+    if (char === "*" && glob[i + 1] === "*") {
+      const slashAfter = glob[i + 2] === "/";
+      out += slashAfter ? "(?:.*/)?" : ".*";
+      i += slashAfter ? 2 : 1;
+    } else if (char === "*") {
+      out += "[^/]*";
+    } else if (char === "?") {
+      out += "[^/]";
+    } else if (char === "{") {
+      const close = glob.indexOf("}", i);
+      if (close === -1) {
+        out += "\\{";
+        continue;
+      }
+      out += `(?:${glob.slice(i + 1, close).split(",").map(globToRegex).join("|")})`;
+      i = close;
+    } else {
+      out += char.replace(/[.+^$()|[\]\\]/g, "\\$&");
+    }
+  }
+  return out;
+}

package/dist/domain/hashing.js

@@ -0,0 +1,52 @@
+import { createHash } from "node:crypto";
+import { elementLines, isStatusLine,              } from "./elements.js";
+                                                 
+
+/**
+ * Hashes cover design content only. Managed blocks and status lines are
+ * excluded, so bookkeeping by the CLI never makes a design look edited.
+ */
+
+export function sha256(text        )         {
+  return `sha256:${createHash("sha256").update(text).digest("hex")}`;
+}
+
+/** Hash of a whole document's design content. */
+export function designHash(doc             )         {
+  const kept = doc.lines.filter((line, i) => !doc.inManaged[i] && (doc.inFence[i] || !isStatusLine(line)));
+  return sha256(normalize(kept));
+}
+
+/**
+ * Hash of one element, independent of where it sits: heading levels are made
+ * relative to the element and a delta operation prefix is dropped, so an element
+ * hashes the same in a delta and after it is merged into a living document.
+ */
+export function elementHash(doc             , element         )         {
+  if (element.form === "row") return sha256(normalize(elementLines(doc, element)));
+  const kept           = [];
+  for (let i = element.start; i < element.end; i++) {
+    const line = doc.lines[i] ?? "";
+    if (doc.inManaged[i] || (!doc.inFence[i] && isStatusLine(line))) continue;
+    kept.push(doc.inFence[i] ? line : relativeHeading(line, element.level, i === element.start));
+  }
+  return sha256(normalize(kept));
+}
+
+function relativeHeading(line        , baseLevel        , isOwnHeading         )         {
+  const match = /^(#{1,6}) (.*)$/.exec(line);
+  if (match?.[1] === undefined || match[2] === undefined) return line;
+  const text = isOwnHeading ? match[2].replace(/^(ADDED|MODIFIED|REMOVED) /, "") : match[2];
+  return `${"#".repeat(match[1].length - baseLevel + 1)} ${text}`;
+}
+
+function normalize(lines          )         {
+  const out           = [];
+  for (const raw of lines) {
+    const line = raw.trimEnd();
+    if (line === "" && (out.length === 0 || out[out.length - 1] === "")) continue;
+    out.push(line);
+  }
+  while (out.length > 0 && out[out.length - 1] === "") out.pop();
+  return out.join("\n");
+}

package/dist/domain/ids.js

@@ -0,0 +1,37 @@
+/** Element IDs: `<KIND>-<name>` or `<KIND>-<scope>.<name>`, named and never reused. */
+
+export const KINDS = ["GOAL", "CTX", "ENT", "UC", "PORT", "ADP", "FLOW", "MOD", "RULE", "VIEW", "XC", "REQ", "SCN", "ADR"]         ;
+                                          
+
+/** Kinds that describe code, and so carry a managed planned/built status. */
+export const CODE_KINDS                  = ["ENT", "UC", "PORT", "ADP", "FLOW", "MOD"];
+/** Kinds whose elements carry a managed status: code kinds and scenarios. */
+export const STATUS_KINDS                  = [...CODE_KINDS, "SCN"];
+/** Kinds that must name their context or capability as a scope. */
+export const SCOPED_KINDS                  = ["ENT", "UC", "PORT", "ADP", "FLOW", "REQ", "SCN"];
+
+const WORD = "[a-z0-9]+(?:-[a-z0-9]+)*";
+export const ID_PATTERN = `(?:${KINDS.join("|")})-${WORD}(?:\\.${WORD})?`;
+
+const EXACT = new RegExp(`^${ID_PATTERN}$`);
+const ANYWHERE = new RegExp(`(?<![A-Za-z0-9_-])${ID_PATTERN}(?![A-Za-z0-9_-])`, "g");
+
+export function isId(text        )          {
+  return EXACT.test(text);
+}
+
+export function kindOf(id        )       {
+  return id.slice(0, id.indexOf("-"))        ;
+}
+
+/** The context or capability an ID belongs to, if it has one. */
+export function scopeOf(id        )                     {
+  const rest = id.slice(id.indexOf("-") + 1);
+  const dot = rest.indexOf(".");
+  return dot === -1 ? undefined : rest.slice(0, dot);
+}
+
+/** Every ID mentioned in the text, once each, in order of first mention. */
+export function findIds(text        )           {
+  return [...new Set(text.match(ANYWHERE) ?? [])];
+}

package/dist/domain/journal.js

@@ -0,0 +1,62 @@
+/** The append-only journal: one JSON object per line, written only by the CLI. */
+
+                               
+             
+                
+             
+                           
+ 
+
+/** Events other tools and skills record, with the fields each requires. */
+export const RECORDED_EVENTS                           = {
+  rethink: ["level", "kind", "summary", "wrong", "caught_by"],
+  disposition: ["finding", "disposition", "reason", "review"],
+  review: ["review", "round", "blockers", "concerns"],
+  override: ["gate", "reason"],
+  bug: ["summary", "cause"],
+  verification: ["result", "summary"],
+};
+
+export const FIELD_VALUES                           = {
+  level: ["task", "change", "feature", "architecture", "vision"],
+  kind: ["defect", "discovery"],
+  disposition: ["fixed", "waived", "deferred", "rejected"],
+  review: ["design", "plan", "code"],
+  result: ["accepted", "sent-back"],
+};
+
+export function journalPath(folder        )         {
+  return `${folder}/journal.jsonl`;
+}
+
+export function parseJournal(text                    )                                                  {
+  const entries                 = [];
+  const badLines           = [];
+  (text ?? "").split("\n").forEach((line, index) => {
+    if (line.trim() === "") return;
+    try {
+      const entry = JSON.parse(line)                ;
+      if (typeof entry.event === "string" && typeof entry.at === "string") entries.push(entry);
+      else badLines.push(index + 1);
+    } catch {
+      badLines.push(index + 1);
+    }
+  });
+  return { entries, badLines };
+}
+
+export function serializeEntry(entry              )         {
+  return `${JSON.stringify(entry)}\n`;
+}
+
+/** Problems with an event a caller asks to record; empty when it can be recorded. */
+export function recordedEventProblems(event        , fields                        )           {
+  const required = RECORDED_EVENTS[event];
+  if (required === undefined) return [`unknown event "${event}"; recordable events: ${Object.keys(RECORDED_EVENTS).join(", ")}`];
+  const problems = required.filter((field) => (fields[field] ?? "").trim() === "").map((field) => `${event} needs ${field}`);
+  for (const [field, allowed] of Object.entries(FIELD_VALUES)) {
+    const value = fields[field];
+    if (value !== undefined && required.includes(field) && !allowed.includes(value)) problems.push(`${field} must be one of ${allowed.join(", ")}`);
+  }
+  return problems;
+}

package/dist/domain/land/bookkeeping.js

@@ -0,0 +1,54 @@
+import { removeRow, upsertRow } from "../edits/managed_tables.js";
+import { updateProgress } from "../edits/progress_block.js";
+import { parseMarkdown } from "../markdown.js";
+import { PATHS } from "../project/layout.js";
+import { readChangesTable } from "../project/plan_parts.js";
+import { readProgress } from "../project/progress.js";
+                                                              
+                                                         
+
+                              
+                                                                                              
+                    
+                                                           
+                                         
+                  
+ 
+
+/** Records the land in progress blocks, the roadmap status and, when a feature finishes, the feature map. */
+export function applyBookkeeping(view             , change          , source          , landed        , files                     )              {
+  const text = (path        )                     => files.get(path) ?? view.snapshot.get(path);
+  files.set(change.path, updateProgress(text(change.path) ?? "", (progress) => (progress.landed = landed)));
+
+  let finished = true;
+  if (source !== change) {
+    const featureText = updateProgress(text(source.path) ?? "", (progress) => progress.changes.set(change.folderName, "landed"));
+    files.set(source.path, featureText);
+    const states = readProgress(parseMarkdown(featureText)).changes;
+    finished = readChangesTable(source.doc).every((row) => states.get(row.change) === "landed");
+  }
+
+  const release = releaseName(text(PATHS.roadmap));
+  const slug = typeof source.doc.frontmatter?.["roadmap"] === "string" ? source.doc.frontmatter["roadmap"] : undefined;
+  const roadmap = text(PATHS.roadmap);
+  if (slug !== undefined && roadmap !== undefined && roadmap.includes("## Status")) {
+    files.set(PATHS.roadmap, upsertRow(roadmap, "Status", [slug, source.folderName, finished ? "landed" : "building"]));
+  }
+  const vision = text(PATHS.vision);
+  if (finished && source.kind === "feature" && slug !== undefined && vision !== undefined && vision.includes("### Implemented")) {
+    const { text: withoutFuture, removed } = removeRow(vision, "Future", slug);
+    const summary = removed?.[1] ?? String(source.doc.frontmatter?.["title"] ?? slug);
+    files.set(PATHS.vision, upsertRow(withoutFuture, "Implemented", [slug, release, summary]));
+  }
+
+  const result              = { finished, release };
+  if (finished) result.archive = { from: source.folder, to: `${PATHS.archiveDir}/${source.folderName}` };
+  return result;
+}
+
+/** The release in progress: the roadmap's `## Release` line up to its colon. */
+export function releaseName(roadmap                    )         {
+  if (roadmap === undefined) return "unreleased";
+  const line = roadmap.split("## Release")[1]?.split("\n").find((l) => l.trim() !== "");
+  return line?.split(":")[0]?.trim() || "unreleased";
+}

package/dist/domain/land/merge_plan.js

@@ -0,0 +1,132 @@
+import { sectionForKind } from "../architecture_sections.js";
+import { CruzeError } from "../cruze_error.js";
+import { setStatus } from "../edits/status_lines.js";
+import { headingElements, statusOf,              } from "../elements.js";
+import { elementHash } from "../hashing.js";
+import { STATUS_KINDS, kindOf, scopeOf } from "../ids.js";
+import { findSection, parseMarkdown } from "../markdown.js";
+import { readDelta,                 } from "../project/deltas.js";
+import { PATHS, specPath } from "../project/layout.js";
+import { readScope } from "../project/plan_parts.js";
+                                                              
+                                                         
+import { REMOVED_MARK, capabilityKey } from "../validation/delta_rules.js";
+import { appendBlock, relevel, removeElement, replaceElement } from "./text_ops.js";
+
+                            
+                                                             
+                             
+                                                                                
+                                 
+                      
+                  
+                    
+ 
+
+/**
+ * Merges a change's work into the living docs. The first change of a feature to land merges
+ * the whole delta; elements it doesn't build arrive as planned, and later changes flip what
+ * they build to built. Text is replaced only when nobody else changed it since this work merged it.
+ */
+export function planMerge(view             , change          , source          )            {
+  const scope = readScope(change.doc);
+  const inScope = new Set([...(scope?.delivers ?? []), ...(scope?.builds ?? [])]);
+  const delta = readDelta(source.doc);
+  const merged = { ...(view.approvals.get(source.folder)?.merged ?? {}) };
+  const files = new Map                ();
+  const text = (path        )         => files.get(path) ?? view.snapshot.get(path) ?? "";
+  const plan            = { files, merged, mergedIds: [], built: [], removed: [] };
+
+  for (const op of delta.capabilities) {
+    const key = capabilityKey(op.capability);
+    if (merged[key] !== undefined || view.snapshot.has(specPath(op.capability))) continue;
+    const body = source.doc.lines.slice(op.start + 1, op.end).join("\n").trim();
+    files.set(specPath(op.capability), `# ${op.title}\n\n${body}\n`);
+    merged[key] = "created";
+  }
+
+  for (const entry of delta.entries) {
+    const { id } = entry.element;
+    const path = entry.section === "spec" ? specPath(scopeOf(id) ?? "") : PATHS.architecture;
+    if (entry.element.op === "REMOVED") {
+      if (scope?.removes.includes(id) === true) {
+        files.set(path, removeElement(text(path), id));
+        merged[id] = REMOVED_MARK;
+        plan.removed.push(id);
+      }
+      continue;
+    }
+    mergeEntry(view, source, entry, path, text, files, merged, plan);
+    for (const target of [entry.element, ...entry.scenarios].filter((e) => STATUS_KINDS.includes(e.kind))) {
+      files.set(path, setStatus(text(path), target.id, statusAfterMerge(view, source, target, inScope)));
+      if (inScope.has(target.id)) plan.built.push(target.id);
+    }
+  }
+
+  for (const id of [...inScope].filter((id) => !delta.ids.has(id) && STATUS_KINDS.includes(kindOf(id)))) {
+    const living = view.living.elements.get(id);
+    if (living === undefined) continue;
+    files.set(living.path, setStatus(text(living.path), id, "built"));
+    plan.built.push(id);
+  }
+  verifyMerged(source, delta.entries, text, plan);
+  return plan;
+}
+
+function mergeEntry(
+  view             ,
+  source          ,
+  entry            ,
+  path        ,
+  text                          ,
+  files                     ,
+  merged                        ,
+  plan           ,
+)       {
+  const { id } = entry.element;
+  const block = relevel(source.doc, entry.element.start, entry.element.end, entry.section === "spec" ? 2 : 3);
+  const deltaHash = elementHash(source.doc, entry.element);
+  const doc = parseMarkdown(text(path));
+  const living = headingElements(doc).find((e) => e.id === id);
+  const previous = merged[id];
+  if (living !== undefined) {
+    const livingHash = elementHash(doc, living);
+    if (previous !== undefined && previous !== REMOVED_MARK && livingHash !== previous) {
+      throw new CruzeError("merge-conflict", `${id} in ${path} changed since ${source.ref} merged it; rethink before landing`);
+    }
+    if (livingHash !== deltaHash) {
+      files.set(path, replaceElement(text(path), id, block));
+      plan.mergedIds.push(id);
+    }
+  } else {
+    if (previous !== undefined && previous !== REMOVED_MARK) {
+      throw new CruzeError("merge-conflict", `${id} was removed from ${path} after ${source.ref} merged it; rethink before landing`);
+    }
+    const section = entry.section === "spec" ? undefined : sectionForKind(entry.element.kind);
+    if (section !== undefined && findSection(doc, section) === null) throw new CruzeError("merge-conflict", `${path} has no "## ${section}" section for ${id}`);
+    files.set(path, appendBlock(text(path), block, section));
+    plan.mergedIds.push(id);
+  }
+  merged[id] = deltaHash;
+  for (const scenario of entry.scenarios) merged[scenario.id] = elementHash(source.doc, scenario);
+}
+
+/** Built when this change builds it, or when it was built and its text is unchanged; planned otherwise. */
+function statusAfterMerge(view             , source          , target         , inScope             )                      {
+  if (inScope.has(target.id)) return "built";
+  const before = view.living.elements.get(target.id);
+  if (before === undefined || statusOf(before.doc, before.element) !== "built") return "planned";
+  return elementHash(before.doc, before.element) === elementHash(source.doc, target) ? "built" : "planned";
+}
+
+/** After merging, every merged element must hash exactly as it did in the delta. */
+function verifyMerged(source          , entries              , text                          , plan           )       {
+  for (const entry of entries.filter((e) => plan.mergedIds.includes(e.element.id))) {
+    const path = entry.section === "spec" ? specPath(scopeOf(entry.element.id) ?? "") : PATHS.architecture;
+    const doc = parseMarkdown(text(path));
+    const living = headingElements(doc).find((e) => e.id === entry.element.id);
+    if (living === undefined || elementHash(doc, living) !== elementHash(source.doc, entry.element)) {
+      throw new Error(`merge check failed: ${entry.element.id} in ${path} does not match the delta`);
+    }
+  }
+}

package/dist/domain/land/text_ops.js

@@ -0,0 +1,66 @@
+import { headingElements, isStatusLine } from "../elements.js";
+import { parseMarkdown,                  } from "../markdown.js";
+
+/** Line-level edits land makes to living documents. Every function takes and returns whole text. */
+
+/**
+ * A delta block ready for a living document: headings shifted so the element's own heading
+ * sits at `level`, the operation prefix dropped, status lines removed, trailing blanks trimmed.
+ */
+export function relevel(doc             , start        , end        , level        )           {
+  const own = /^(#{1,6}) /.exec(doc.lines[start] ?? "")?.[1]?.length ?? level;
+  const shift = level - own;
+  const out           = [];
+  for (let i = start; i < end; i++) {
+    let line = doc.lines[i] ?? "";
+    if (!doc.inFence[i]) {
+      if (isStatusLine(line)) continue;
+      const heading = /^(#{1,6}) (.*)$/.exec(line);
+      if (heading?.[1] !== undefined && heading[2] !== undefined) {
+        const text = i === start ? heading[2].replace(/^(ADDED|MODIFIED|REMOVED) /, "") : heading[2];
+        line = `${"#".repeat(heading[1].length + shift)} ${text}`;
+      }
+    }
+    out.push(line);
+  }
+  while (out.length > 0 && out[out.length - 1]?.trim() === "") out.pop();
+  return out;
+}
+
+/** Replaces an element's whole block, keeping one blank line before whatever follows. */
+export function replaceElement(text        , id        , block          )         {
+  const doc = parseMarkdown(text);
+  const element = headingElements(doc).find((e) => e.id === id);
+  if (element === undefined) throw new Error(`${id} is not in the document`);
+  const lines = [...doc.lines];
+  const follows = element.end < lines.length;
+  lines.splice(element.start, element.end - element.start, ...block, ...(follows ? [""] : []));
+  return lines.join("\n");
+}
+
+export function removeElement(text        , id        )         {
+  const doc = parseMarkdown(text);
+  const element = headingElements(doc).find((e) => e.id === id);
+  if (element === undefined) return text;
+  const lines = [...doc.lines];
+  lines.splice(element.start, element.end - element.start);
+  return lines.join("\n");
+}
+
+/** Appends a block at the end of a `##` section, or at the end of the document when none is named. */
+export function appendBlock(text        , block          , section         )         {
+  const doc = parseMarkdown(text);
+  const lines = [...doc.lines];
+  let at = lines.length;
+  if (section !== undefined) {
+    const heading = doc.headings.find((h) => h.level === 2 && h.text === section);
+    if (heading === undefined) throw new Error(`the document has no "## ${section}" section`);
+    at = doc.headings.find((h) => h.line > heading.line && h.level <= 2)?.line ?? lines.length;
+  }
+  let insertAt = at;
+  while (insertAt > 0 && lines[insertAt - 1]?.trim() === "") insertAt--;
+  const trailing = at < lines.length ? [""] : [];
+  lines.splice(insertAt, at - insertAt, "", ...block, ...trailing);
+  const joined = lines.join("\n");
+  return joined.endsWith("\n") ? joined : `${joined}\n`;
+}

package/dist/domain/markdown.js

@@ -0,0 +1,79 @@
+import { parse as parseYaml } from "yaml";
+
+/** A Markdown document split into lines, with the structure Cruze relies on. */
+                              
+                  
+                                              
+                                          
+                    
+                      
+                                                                    
+                     
+                                                                 
+                       
+ 
+
+                          
+                
+               
+               
+ 
+
+export const MANAGED_OPEN = "<!-- cruze:managed -->";
+export const MANAGED_CLOSE = "<!-- /cruze:managed -->";
+
+export function parseMarkdown(text        )              {
+  const lines = text.replace(/\r\n/g, "\n").split("\n");
+  const { frontmatter, bodyStart } = readFrontmatter(lines);
+  const inFence            = [];
+  const inManaged            = [];
+  const headings            = [];
+  let fence                = null;
+  let managed = false;
+
+  lines.forEach((line, index) => {
+    const fenceMatch = /^(```|~~~)/.exec(line.trimStart());
+    if (fence === null && fenceMatch?.[1] !== undefined && index >= bodyStart) {
+      fence = fenceMatch[1];
+      inFence.push(true);
+    } else if (fence !== null) {
+      inFence.push(true);
+      if (line.trimStart().startsWith(fence)) fence = null;
+    } else {
+      inFence.push(false);
+    }
+
+    const trimmed = line.trim();
+    if (!inFence[index] && trimmed === MANAGED_OPEN) managed = true;
+    inManaged.push(managed);
+    if (!inFence[index] && trimmed === MANAGED_CLOSE) managed = false;
+
+    const heading = /^(#{1,6}) (.+?)\s*$/.exec(line);
+    if (heading?.[1] !== undefined && heading[2] !== undefined && !inFence[index] && index >= bodyStart) {
+      headings.push({ level: heading[1].length, text: heading[2], line: index });
+    }
+  });
+  return { lines, frontmatter, bodyStart, headings, inFence, inManaged };
+}
+
+/** The line range [start, end) of a heading's section: up to the next heading at the same or a higher level. */
+export function sectionEnd(doc             , heading         )         {
+  const next = doc.headings.find((h) => h.line > heading.line && h.level <= heading.level);
+  return next === undefined ? doc.lines.length : next.line;
+}
+
+/** The body lines of the first `##` section with this title, or null when absent. */
+export function findSection(doc             , title        , level = 2)                                                          {
+  const heading = doc.headings.find((h) => h.level === level && h.text === title);
+  if (heading === undefined) return null;
+  return { heading, start: heading.line + 1, end: sectionEnd(doc, heading) };
+}
+
+function readFrontmatter(lines          )                                                                     {
+  if (lines[0] !== "---") return { frontmatter: null, bodyStart: 0 };
+  const end = lines.indexOf("---", 1);
+  if (end === -1) return { frontmatter: null, bodyStart: 0 };
+  const parsed          = parseYaml(lines.slice(1, end).join("\n"));
+  const frontmatter = parsed !== null && typeof parsed === "object" ? (parsed                           ) : {};
+  return { frontmatter, bodyStart: end + 1 };
+}

package/dist/domain/markdown_tables.js

@@ -0,0 +1,34 @@
+/** Pipe tables: header cells and body rows, each row with its line number. */
+                        
+                   
+                                                 
+ 
+
+/** Tables found in lines [from, to), skipping fenced code. */
+export function tablesIn(lines          , inFence           , from        , to        )          {
+  const tables          = [];
+  let current               = null;
+  for (let i = from; i < to; i++) {
+    const line = lines[i] ?? "";
+    const isRow = !inFence[i] && /^\s*\|.*\|\s*$/.test(line);
+    if (!isRow) {
+      current = null;
+      continue;
+    }
+    const cells = splitRow(line);
+    if (current === null) {
+      current = { header: cells, rows: [] };
+      tables.push(current);
+    } else if (cells.every((cell) => /^:?-{3,}:?$/.test(cell))) {
+      continue;
+    } else {
+      current.rows.push({ cells, line: i });
+    }
+  }
+  return tables;
+}
+
+export function splitRow(line        )           {
+  const inner = line.trim().replace(/^\|/, "").replace(/\|$/, "");
+  return inner.split("|").map((cell) => cell.trim());
+}

package/dist/domain/project/artifact_ref.js

@@ -0,0 +1,42 @@
+import { CruzeError } from "../cruze_error.js";
+import { PATHS } from "./layout.js";
+                                                     
+import { findWorkItem,               } from "./work_items.js";
+
+const NAMED                         = { vision: PATHS.vision, architecture: PATHS.architecture, roadmap: PATHS.roadmap };
+
+/**
+ * Resolves what a person or skill names on the command line: `vision`, `architecture`,
+ * `roadmap`, a work item ref such as `2026-09-25-open-console/01-local-serial`, the same ref
+ * without its date (`open-console/local-serial`) when that names one active item, or a path.
+ */
+export function resolveArtifact(view             , ref        )                                    {
+  const named = NAMED[ref];
+  if (named !== undefined) {
+    if (!view.snapshot.has(named)) throw new CruzeError("not-found", `${named} does not exist yet`);
+    return { path: named };
+  }
+  const item = findWorkItem(view.items, ref.replace(/\/$/, "")) ?? bySlug(view.items, ref.replace(/\/$/, ""));
+  if (item !== undefined) return { path: item.path, item };
+  if (view.snapshot.has(ref)) return { path: ref };
+  throw new CruzeError("not-found", `nothing called "${ref}"; use vision, architecture, roadmap, a feature or change ID, or a path`);
+}
+
+/** An active item named by its slug, without the date or the change number. */
+function bySlug(items            , ref        )                       {
+  const [head = "", change] = ref.split("/");
+  const undated = (name        )         => name.replace(/^\d{4}-\d{2}-\d{2}-/, "");
+  const matches = items.filter((i) => !i.archived && i.kind !== "change" && undated(i.folderName) === head);
+  if (matches.length > 1) throw new CruzeError("ambiguous", `"${head}" names ${matches.map((m) => m.ref).join(" and ")}; use the full ID`);
+  const base = matches[0];
+  if (base === undefined || change === undefined) return base;
+  return items.find((i) => i.featureRef === base.ref && (i.folderName === change || i.folderName.replace(/^\d\d-/, "") === change));
+}
+
+/** Resolves a change: a feature's change or a standalone change, never archived. */
+export function resolveChange(view             , ref        )           {
+  const { item } = resolveArtifact(view, ref);
+  if (item === undefined || item.kind === "feature") throw new CruzeError("not-a-change", `"${ref}" is not a change`);
+  if (item.archived) throw new CruzeError("archived", `${item.ref} has already landed`);
+  return item;
+}

package/dist/domain/project/deltas.js

@@ -0,0 +1,49 @@
+import { capabilityOps, headingElements,                                 } from "../elements.js";
+import { findSection,                  } from "../markdown.js";
+
+/** One delta operation on a living element, with its nested scenarios when it is a requirement. */
+                             
+                   
+                                   
+                                                                
+                       
+ 
+
+                        
+                        
+                               
+                                                                         
+                   
+ 
+
+export function readDelta(doc             )        {
+  const entries               = [];
+  const capabilities                 = [];
+  for (const [title, section] of [["Spec delta", "spec"], ["Architecture delta", "architecture"]]         ) {
+    const range = findSection(doc, title);
+    if (range === null) continue;
+    capabilities.push(...capabilityOps(doc, range.start, range.end));
+    const elements = headingElements(doc, range.start, range.end);
+    for (const element of elements.filter((e) => e.op !== undefined)) {
+      const scenarios = elements.filter((e) => e.op === undefined && e.start > element.start && e.start < element.end);
+      entries.push({ element, section, scenarios });
+    }
+  }
+  const ids = new Set(entries.flatMap((entry) => [entry.element.id, ...entry.scenarios.map((s) => s.id)]));
+  return { entries, capabilities, ids };
+}
+
+/** Scenario elements that sit under no requirement operation: always a format error. */
+export function orphanDeltaElements(doc             )            {
+  const orphans            = [];
+  for (const title of ["Spec delta", "Architecture delta"]) {
+    const range = findSection(doc, title);
+    if (range === null) continue;
+    const elements = headingElements(doc, range.start, range.end);
+    const ops = elements.filter((e) => e.op !== undefined);
+    for (const element of elements.filter((e) => e.op === undefined)) {
+      if (!ops.some((op) => element.start > op.start && element.start < op.end)) orphans.push(element);
+    }
+  }
+  return orphans;
+}