@printpractical/cruze 0.0.13 → 0.0.15

package/src/domain/project/scope_view.ts

@@ -1,134 +0,0 @@
-import { elementLines, type DeltaOp, type Element } from "../elements.ts";
-import { findIds } from "../ids.ts";
-import { findSection, type MarkdownDoc } from "../markdown.ts";
-import { readDelta } from "./deltas.ts";
-import { readScope } from "./plan_parts.ts";
-import type { ProjectView } from "./project_view.ts";
-import { featureOf, type WorkItem, type WorkItemKind } from "./work_items.ts";
-
-/**
- * The design a piece of work builds, cut out of the documents that hold it, so a step reads
- * the elements in its scope instead of the whole architecture and the whole feature.
- */
-
-export interface ShownElement {
-  id: string;
-  title: string;
-  op?: DeltaOp;
-  /** Where the body comes from, as `<path>:<line>`. */
-  source: string;
-  body: string[];
-}
-
-export interface CitedElement {
-  id: string;
-  title: string;
-  source: string;
-}
-
-export interface ScopeView {
-  ref: string;
-  kind: WorkItemKind;
-  feature?: string;
-  /** The architecture elements the work builds or removes; for a feature, its whole architecture delta. */
-  elements: ShownElement[];
-  /** The scenarios and requirements the work delivers; for a feature, its whole spec delta. */
-  scenarios: ShownElement[];
-  /** Elements the shown bodies cite but don't include, with where to read them. */
-  cited: CitedElement[];
-  /** The settled decisions of the feature, or of a standalone change. */
-  decisions: string[];
-  /** A feature's change's own settled decisions, numbered apart from the feature's. */
-  changeDecisions: string[];
-  /** Scope IDs defined nowhere: the delta, the living docs or the archive. */
-  missing: string[];
-}
-
-interface Located {
-  doc: MarkdownDoc;
-  path: string;
-  element: Element;
-}
-
-export function scopeView(view: ProjectView, item: WorkItem): ScopeView {
-  const feature = featureOf(view.items, item);
-  const deltaItem = feature ?? item;
-  const locate = locator(view, deltaItem);
-  const wanted = item.kind === "change" || item.kind === "standalone" ? changeIds(item) : featureIds(deltaItem);
-  const missing: string[] = [];
-  const show = (ids: string[]): ShownElement[] =>
-    ids.flatMap((id) => {
-      const found = locate(id);
-      if (found === undefined) {
-        missing.push(id);
-        return [];
-      }
-      const shown: ShownElement = { id, title: found.element.title, source: `${found.path}:${found.element.start + 1}`, body: elementLines(found.doc, found.element) };
-      if (found.element.op !== undefined) shown.op = found.element.op;
-      return [shown];
-    });
-  const elements = show(wanted.elements);
-  const scenarios = withoutRepeatedScenarios(show(wanted.scenarios));
-  const shownIds = new Set([...elements, ...scenarios].map((e) => e.id));
-  const cited = [...new Set([...elements, ...scenarios].flatMap((e) => findIds(e.body.join("\n"))))]
-    .filter((id) => !shownIds.has(id))
-    .flatMap((id) => {
-      const found = locate(id);
-      return found === undefined ? [] : [{ id, title: found.element.title, source: `${found.path}:${found.element.start + 1}` }];
-    });
-  const decisions = decisionLines((feature ?? item).doc);
-  const changeDecisions = feature === undefined ? [] : decisionLines(item.doc);
-  const result: ScopeView = { ref: item.ref, kind: item.kind, elements, scenarios, cited, decisions, changeDecisions, missing };
-  if (feature !== undefined) result.feature = feature.ref;
-  return result;
-}
-
-/**
- * A requirement shown beside its own scenarios keeps only its own text: its body would repeat
- * each of them, which made up a third of one change's output.
- */
-function withoutRepeatedScenarios(shown: ShownElement[]): ShownElement[] {
-  const ids = new Set(shown.map((e) => e.id));
-  return shown.map((element) => {
-    if (!element.id.startsWith("REQ-")) return element;
-    const first = element.body.findIndex((line, i) => i > 0 && /^#{2,6} /.test(line) && findIds(line).some((id) => ids.has(id)));
-    return first === -1 ? element : { ...element, body: element.body.slice(0, first) };
-  });
-}
-
-/** A change shows what its scope builds, removes and delivers. */
-function changeIds(change: WorkItem): { elements: string[]; scenarios: string[] } {
-  const scope = readScope(change.doc);
-  return { elements: [...(scope?.builds ?? []), ...(scope?.removes ?? [])], scenarios: scope?.delivers ?? [] };
-}
-
-/** A feature shows its whole delta: every operation, with a requirement's scenarios inside its body. */
-function featureIds(feature: WorkItem): { elements: string[]; scenarios: string[] } {
-  const entries = readDelta(feature.doc).entries;
-  return {
-    elements: entries.filter((e) => e.section === "architecture").map((e) => e.element.id),
-    scenarios: entries.filter((e) => e.section === "spec").map((e) => e.element.id),
-  };
-}
-
-/** Finds an element's body in the work's own delta first, since that is the text the work builds, then in the living docs. */
-function locator(view: ProjectView, deltaItem: WorkItem): (id: string) => Located | undefined {
-  const delta = readDelta(deltaItem.doc);
-  const inDelta = new Map<string, Element>();
-  for (const entry of delta.entries) {
-    inDelta.set(entry.element.id, entry.element);
-    for (const scenario of entry.scenarios) inDelta.set(scenario.id, scenario);
-  }
-  return (id) => {
-    const own = inDelta.get(id);
-    if (own !== undefined) return { doc: deltaItem.doc, path: deltaItem.path, element: own };
-    const living = view.living.elements.get(id);
-    return living === undefined ? undefined : { doc: living.doc, path: living.path, element: living.element };
-  };
-}
-
-function decisionLines(doc: MarkdownDoc): string[] {
-  const section = findSection(doc, "Settled decisions");
-  if (section === null) return [];
-  return doc.lines.slice(section.start, section.end).filter((line) => line.startsWith("- "));
-}

package/src/domain/project/work_items.ts

@@ -1,68 +0,0 @@
-import { parseMarkdown, type MarkdownDoc } from "../markdown.ts";
-import { PATHS, filesUnder, type Snapshot } from "./layout.ts";
-
-export type WorkItemKind = "feature" | "change" | "standalone";
-
-/** A feature, a change inside a feature, or a standalone change. */
-export interface WorkItem {
-  kind: WorkItemKind;
-  /** `<feature id>`, `<feature id>/<change>` or `<standalone id>`. */
-  ref: string;
-  /** The ID its frontmatter must carry: the folder name. */
-  folderName: string;
-  folder: string;
-  path: string;
-  doc: MarkdownDoc;
-  archived: boolean;
-  /** For a change inside a feature: the feature's ref. */
-  featureRef?: string;
-}
-
-const FEATURE = /^\.cruze\/(features|archive)\/([^/]+)\/feature\.md$/;
-const FEATURE_CHANGE = /^\.cruze\/(features|archive)\/([^/]+)\/changes\/([^/]+)\/change\.md$/;
-const STANDALONE = /^\.cruze\/(changes|archive)\/([^/]+)\/change\.md$/;
-
-export function listWorkItems(snapshot: Snapshot): WorkItem[] {
-  const paths = [...filesUnder(snapshot, PATHS.featuresDir), ...filesUnder(snapshot, PATHS.changesDir), ...filesUnder(snapshot, PATHS.archiveDir)];
-  return paths.flatMap((path) => {
-    const item = classify(path);
-    return item === null ? [] : [{ ...item, path, doc: parseMarkdown(snapshot.get(path) ?? "") }];
-  });
-}
-
-export function findWorkItem(items: WorkItem[], ref: string): WorkItem | undefined {
-  return items.find((item) => item.ref === ref || item.path === ref || item.folder === ref);
-}
-
-/** The feature a change belongs to. */
-export function featureOf(items: WorkItem[], change: WorkItem): WorkItem | undefined {
-  return change.featureRef === undefined ? undefined : items.find((item) => item.kind === "feature" && item.ref === change.featureRef);
-}
-
-export function changesOf(items: WorkItem[], feature: WorkItem): WorkItem[] {
-  return items.filter((item) => item.featureRef === feature.ref).sort((a, b) => a.ref.localeCompare(b.ref));
-}
-
-function classify(path: string): Omit<WorkItem, "path" | "doc"> | null {
-  const folder = path.slice(0, path.lastIndexOf("/"));
-  let match = FEATURE.exec(path);
-  if (match?.[2] !== undefined) {
-    return { kind: "feature", ref: match[2], folderName: match[2], folder, archived: match[1] === "archive" };
-  }
-  match = FEATURE_CHANGE.exec(path);
-  if (match?.[2] !== undefined && match[3] !== undefined) {
-    return {
-      kind: "change",
-      ref: `${match[2]}/${match[3]}`,
-      folderName: match[3],
-      folder,
-      archived: match[1] === "archive",
-      featureRef: match[2],
-    };
-  }
-  match = STANDALONE.exec(path);
-  if (match?.[2] !== undefined) {
-    return { kind: "standalone", ref: match[2], folderName: match[2], folder, archived: match[1] === "archive" };
-  }
-  return null;
-}

package/src/domain/status/next_step.ts

@@ -1,181 +0,0 @@
-import { evaluateApproval, type ApprovalStatus } from "../approvals/evaluate.ts";
-import { rebaseNeeded } from "../approvals/rebase.ts";
-import { PATHS } from "../project/layout.ts";
-import { isPlanned, readChangesTable } from "../project/plan_parts.ts";
-import { readProgress } from "../project/progress.ts";
-import type { ProjectView } from "../project/project_view.ts";
-import { readRoadmapItems, readRoadmapStatus } from "../project/roadmap.ts";
-import { changesOf, featureOf, type WorkItem } from "../project/work_items.ts";
-import { compareVersions } from "../versions/cruze_version.ts";
-import { FIRST_RELEASE } from "../versions/rule_versions.ts";
-import { pendingReason, pendingRethinks } from "./pending_rethink.ts";
-import { awaitsRethink, isVerified } from "./verification.ts";
-import { activeChange } from "./work_status.ts";
-
-/** The Cruze step to run next, computed from the project's state and the current branch. */
-
-export type Step = "envision" | "architect" | "roadmap" | "plan" | "build" | "verify" | "land" | "rethink" | "realign" | "switch-branch";
-
-export interface NextStep {
-  step: Step;
-  /** What the step works on: a feature or change ref, a roadmap slug, or a branch. */
-  target?: string;
-  reason: string;
-}
-
-export interface NextReport {
-  next: NextStep;
-  /** Other work that could proceed, such as changes waiting on their own branches. */
-  also: NextStep[];
-}
-
-export function nextSteps(view: ProjectView, branch: string | null): NextReport {
-  const project = projectStep(view);
-  if (project !== null) return { next: project, also: [] };
-  const active = activeChange(view, branch);
-  const inFlight = inRoadmapOrder(view, view.items.filter((item) => !item.archived && item.kind !== "change")).flatMap((item) => itemSteps(view, item, branch));
-  const roadmap = roadmapStep(view);
-  const realign = realignStep(view);
-  const candidates = [
-    ...(active === undefined ? [] : [changeStep(view, active, branch)]),
-    ...inFlight,
-    ...(roadmap === null ? [] : [roadmap]),
-    ...(realign === null ? [] : [realign]),
-  ];
-  const unique = candidates.filter((c, i) => candidates.findIndex((o) => o.step === c.step && o.target === c.target) === i);
-  const [next, ...also] = unique;
-  return { next: next ?? { step: "roadmap", reason: "every item on the roadmap has landed; close the release and plan the next" }, also };
-}
-
-/**
- * Work in flight in the roadmap's order, with items whose roadmap blockers haven't all landed
- * last: a feature designed early still waits for the prefactors the user put before it.
- */
-function inRoadmapOrder(view: ProjectView, items: WorkItem[]): WorkItem[] {
-  const text = view.snapshot.get(PATHS.roadmap);
-  if (text === undefined) return items;
-  const rows = readRoadmapStatus(text);
-  const state = new Map(rows.map((row) => [row.slug, row.state]));
-  const slugOf = new Map(rows.map((row) => [row.id, row.slug]));
-  const roadmap = readRoadmapItems(text);
-  const rank = (item: WorkItem): [number, number] => {
-    const at = roadmap.findIndex((r) => r.slug === slugOf.get(item.ref));
-    const blocked = at !== -1 && (roadmap[at]?.blockedBy ?? []).some((b) => state.get(b) !== "landed");
-    return [blocked ? 1 : 0, at === -1 ? roadmap.length : at];
-  };
-  return items
-    .map((item, i) => ({ item, key: [...rank(item), i] }))
-    .sort((a, b) => (a.key[0] ?? 0) - (b.key[0] ?? 0) || (a.key[1] ?? 0) - (b.key[1] ?? 0) || (a.key[2] ?? 0) - (b.key[2] ?? 0))
-    .map(({ item }) => item);
-}
-
-/** Realign comes when nothing else is due: the installed skills expect more than the code meets. */
-function realignStep(view: ProjectView): NextStep | null {
-  const config = view.config?.config;
-  if (config?.cruze === undefined) return null;
-  const standards = config.standards ?? FIRST_RELEASE;
-  if (compareVersions(standards, config.cruze) >= 0) return null;
-  return { step: "realign", target: config.cruze, reason: `the code meets Cruze ${standards}'s expectations, and the installed skills are ${config.cruze}` };
-}
-
-/** The project documents come first: nothing else can proceed without them. */
-function projectStep(view: ProjectView): NextStep | null {
-  const docs: Array<{ path: string; missing: NextStep; unapproved: NextStep; changed: NextStep }> = [
-    {
-      path: PATHS.vision,
-      missing: { step: "envision", reason: "the project has no vision yet" },
-      unapproved: { step: "envision", reason: "finish the vision and approve it" },
-      changed: { step: "envision", reason: "the vision changed since its approval; review the change and approve it again" },
-    },
-    {
-      path: PATHS.architecture,
-      missing: { step: "architect", reason: "the project has no architecture yet" },
-      unapproved: { step: "architect", reason: "finish the architecture, review it and approve it" },
-      changed: { step: "rethink", target: "architecture", reason: "the architecture changed since its approval" },
-    },
-    {
-      path: PATHS.roadmap,
-      missing: { step: "architect", reason: "the project has no roadmap yet" },
-      unapproved: { step: "roadmap", reason: "approve the release ordering" },
-      changed: { step: "roadmap", reason: "the roadmap changed since its approval; approve the new ordering" },
-    },
-  ];
-  for (const doc of docs) {
-    if (!view.snapshot.has(doc.path)) return doc.missing;
-    const state = evaluateApproval(view, doc.path).state;
-    if (state === "unapproved") return doc.unapproved;
-    if (state !== "approved") return doc.changed;
-  }
-  return null;
-}
-
-function itemSteps(view: ProjectView, item: WorkItem, branch: string | null): NextStep[] {
-  if (item.kind === "standalone") return [changeStep(view, item, branch)];
-  const state = evaluateApproval(view, item.path);
-  if (readChangesTable(item.doc).length === 0) return [{ step: "architect", target: item.ref, reason: "the feature has no design or changes yet" }];
-  if (state.state === "unapproved") return [{ step: "architect", target: item.ref, reason: "review the feature's design and approve it" }];
-  if (state.state !== "approved") return [{ step: "rethink", target: item.ref, reason: staleReason(view, item, "the feature", state) }];
-  const pending = pendingRethinks(view.journal, item);
-  if (pending.length > 0) return [{ step: "rethink", target: item.ref, reason: pendingReason(item, pending) }];
-  const changes = changesOf(view.items, item);
-  const landed = new Set(changes.filter((c) => readProgress(c.doc).landed !== undefined).map((c) => c.folderName));
-  const steps: NextStep[] = [];
-  for (const row of readChangesTable(item.doc)) {
-    const change = changes.find((c) => c.folderName === row.change);
-    if (change !== undefined) {
-      if (!landed.has(row.change)) steps.push(changeStep(view, change, branch));
-    } else if (row.dependsOn.every((d) => landed.has(d))) {
-      steps.push({ step: "plan", target: `${item.ref}/${row.change}`, reason: "the next change of an approved feature, with its dependencies landed" });
-    }
-  }
-  return steps;
-}
-
-function changeStep(view: ProjectView, change: WorkItem, branch: string | null): NextStep {
-  const feature = featureOf(view.items, change);
-  const featureState = feature === undefined ? undefined : evaluateApproval(view, feature.path);
-  if (feature !== undefined && featureState !== undefined && featureState.state !== "approved") {
-    return { step: "rethink", target: feature.ref, reason: staleReason(view, feature, `the feature of ${change.ref}`, featureState) };
-  }
-  for (const part of [feature, change]) {
-    const pending = part === undefined ? [] : pendingRethinks(view.journal, part);
-    if (part !== undefined && pending.length > 0) return { step: "rethink", target: part.ref, reason: pendingReason(part, pending) };
-  }
-  const bound = readProgress(change.doc).branch;
-  const state = evaluateApproval(view, change.path);
-  if (!isPlanned(change.doc)) return { step: "plan", target: change.ref, reason: "the change is designed but has no test plan or tasks yet" };
-  if (state.state === "unapproved") return { step: "plan", target: change.ref, reason: "review the plan and approve it on the branch that will build it" };
-  if (state.state !== "approved") return { step: "rethink", target: change.ref, reason: staleReason(view, change, "the change", state) };
-  if (awaitsRethink(view.journal, change, feature)) return { step: "rethink", target: feature?.ref ?? change.ref, reason: `verify sent ${change.ref} back for a design change` };
-  if (bound !== undefined && bound !== branch) return { step: "switch-branch", target: bound, reason: `${change.ref} is built on branch ${bound}` };
-  const progress = readProgress(change.doc);
-  if ([...progress.tasks.values()].some((commit) => commit === null)) return { step: "build", target: change.ref, reason: "the change has open tasks" };
-  if (!isVerified(view.journal, change)) return { step: "verify", target: change.ref, reason: "every task is done; verify the change" };
-  return { step: "land", target: change.ref, reason: "the change is verified and accepted" };
-}
-
-/**
- * Why work went stale, and what the rethink will take: a rebase when its delta still changes an
- * element whose living text moved, or only a check of the diff and a re-stamp when nothing it cites
- * asks anything of its own text. One project expected a re-stamp and met rebase-required.
- */
-function staleReason(view: ProjectView, item: WorkItem, label: string, state: ApprovalStatus): string {
-  if (state.state === "edited") return `${label} changed since its approval`;
-  const changed = state.changed.join(", ");
-  const rebase = rebaseNeeded(view, item);
-  const then = rebase.length > 0
-    ? `its delta changes ${rebase.join(", ")}, so rebase it, as cruze diff ${item.ref} shows`
-    : `read cruze diff ${item.ref}, and re-stamp it when the work still holds`;
-  return `something ${label} cites changed since its approval (${changed}); ${then}`;
-}
-
-/** The first roadmap item that hasn't started and whose blockers have all landed. */
-function roadmapStep(view: ProjectView): NextStep | null {
-  const text = view.snapshot.get(PATHS.roadmap);
-  if (text === undefined) return null;
-  const status = new Map(readRoadmapStatus(text).map((row) => [row.slug, row.state]));
-  const item = readRoadmapItems(text).find((i) => !status.has(i.slug) && i.blockedBy.every((b) => status.get(b) === "landed"));
-  if (item === undefined) return null;
-  if (item.kind === "feature") return { step: "envision", target: item.slug, reason: "the next roadmap feature; skip to architect when its requirements are settled" };
-  return { step: "architect", target: item.slug, reason: "the next roadmap change; design it as a tweak" };
-}

package/src/domain/status/pending_rethink.ts

@@ -1,22 +0,0 @@
-import type { JournalEntry } from "../journal.ts";
-import type { WorkItem } from "../project/work_items.ts";
-
-/**
- * Findings decided `rethink` for a feature or change that no rethink of it has followed yet.
- * One project's realign recorded seven design findings on a feature as fixed "by a rethink before
- * its next change is planned"; nothing showed them, and they surfaced only in a commit message.
- */
-export function pendingRethinks(journal: JournalEntry[], item: WorkItem): JournalEntry[] {
-  const lastRethink = journal
-    .filter((e) => e.event === "rethink" && e["item"] === item.ref)
-    .map((e) => e.at)
-    .sort()
-    .at(-1);
-  return journal.filter((e) => e.event === "disposition" && e["disposition"] === "rethink" && e["item"] === item.ref && (lastRethink === undefined || e.at > lastRethink));
-}
-
-/** Why work waits on a rethink, naming the first finding. */
-export function pendingReason(item: WorkItem, pending: JournalEntry[]): string {
-  const more = pending.length > 1 ? ` and ${pending.length - 1} more` : "";
-  return `${pending.length} finding(s) on ${item.ref} were decided for a rethink that hasn't happened yet: ${String(pending[0]?.["finding"] ?? "")}${more}`;
-}

package/src/domain/status/verification.ts

@@ -1,29 +0,0 @@
-import type { JournalEntry } from "../journal.ts";
-import type { WorkItem } from "../project/work_items.ts";
-
-/**
- * Whether the user accepted a change at verify. The latest verification recorded for the change
- * counts. A later approval keeps it only when the change's own design is unchanged, as when it is
- * re-approved because something upstream moved; a changed plan means verifying again. Land's
- * re-stamps don't count, since they follow the merge; an approval the agent gave does.
- */
-export function isVerified(journal: JournalEntry[], change: WorkItem): boolean {
-  const byTime = (a: JournalEntry, b: JournalEntry): number => a.at.localeCompare(b.at);
-  const verification = journal.filter((e) => e.event === "verification" && e["item"] === change.ref).sort(byTime).at(-1);
-  if (verification?.["result"] !== "accepted") return false;
-  const approvals = journal.filter((e) => e.event === "approve" && e["artifact"] === change.path && !String(e["basis"] ?? "").startsWith("land ")).sort(byTime);
-  const verifiedHash = approvals.filter((e) => e.at < verification.at).at(-1)?.["hash"];
-  return approvals.filter((e) => e.at > verification.at).every((e) => e["hash"] === verifiedHash);
-}
-
-/**
- * Whether verify sent the change back for a rethink that hasn't been recorded yet. Tasks the
- * agent reopens at verify would otherwise make the change look ready to build again.
- */
-export function awaitsRethink(journal: JournalEntry[], change: WorkItem, feature: WorkItem | undefined): boolean {
-  const verification = journal.filter((e) => e.event === "verification" && e["item"] === change.ref).sort((a, b) => a.at.localeCompare(b.at)).at(-1);
-  if (verification?.["result"] !== "sent-back" || verification["back_to"] !== "rethink") return false;
-  // An architecture-level rethink records no item, and counts too.
-  const refs = new Set([change.ref, feature?.ref, undefined]);
-  return !journal.some((e) => e.event === "rethink" && e.at > verification.at && refs.has(e["item"] as string | undefined));
-}

package/src/domain/status/work_status.ts

@@ -1,125 +0,0 @@
-import { evaluateApproval, type ApprovalStatus } from "../approvals/evaluate.ts";
-import { PATHS } from "../project/layout.ts";
-import { readDelta } from "../project/deltas.ts";
-import { readChangesTable, readScope } from "../project/plan_parts.ts";
-import { readProgress } from "../project/progress.ts";
-import type { ProjectView } from "../project/project_view.ts";
-import { changesOf, featureOf, type WorkItem } from "../project/work_items.ts";
-import { pendingReason, pendingRethinks } from "./pending_rethink.ts";
-
-export interface ChangeStatus {
-  ref: string;
-  path: string;
-  approval: ApprovalStatus;
-  branch?: string;
-  tasksDone: number;
-  tasksTotal: number;
-  /** When and in which commit the change landed, once it has. */
-  landed?: string;
-  /** Findings decided for a rethink of this change that hasn't happened yet. */
-  rethinkPending?: string[];
-}
-
-export interface FeatureStatus {
-  ref: string;
-  path: string;
-  approval: ApprovalStatus;
-  changes: ChangeStatus[];
-  /** Findings decided for a rethink of this feature that hasn't happened yet. */
-  rethinkPending?: string[];
-}
-
-export interface ProjectStatus {
-  documents: ApprovalStatus[];
-  features: FeatureStatus[];
-  standalone: ChangeStatus[];
-  /** The change bound to the current branch, if any. */
-  active?: string;
-}
-
-export function projectStatus(view: ProjectView, branch: string | null): ProjectStatus {
-  const documents = [PATHS.vision, PATHS.architecture, PATHS.roadmap].filter((p) => view.snapshot.has(p)).map((p) => evaluateApproval(view, p));
-  const active = view.items.filter((item) => !item.archived);
-  const features = active
-    .filter((item) => item.kind === "feature")
-    .map((feature) => ({
-      ref: feature.ref,
-      path: feature.path,
-      approval: evaluateApproval(view, feature.path),
-      changes: changesOf(view.items, feature).map((change) => changeStatus(view, change)),
-      ...withPending(view, feature),
-    }));
-  const standalone = active.filter((item) => item.kind === "standalone").map((change) => changeStatus(view, change));
-  const status: ProjectStatus = { documents, features, standalone };
-  const bound = activeChange(view, branch);
-  if (bound !== undefined) status.active = bound.ref;
-  return status;
-}
-
-export function activeChange(view: ProjectView, branch: string | null): WorkItem | undefined {
-  if (branch === null) return undefined;
-  return view.items.find((item) => {
-    const progress = readProgress(item.doc);
-    return !item.archived && item.kind !== "feature" && progress.landed === undefined && progress.branch === branch;
-  });
-}
-
-function changeStatus(view: ProjectView, change: WorkItem): ChangeStatus {
-  const progress = readProgress(change.doc);
-  const status: ChangeStatus = {
-    ref: change.ref,
-    path: change.path,
-    approval: evaluateApproval(view, change.path),
-    tasksDone: [...progress.tasks.values()].filter((commit) => commit !== null).length,
-    tasksTotal: progress.tasks.size,
-  };
-  if (progress.branch !== undefined) status.branch = progress.branch;
-  if (progress.landed !== undefined) status.landed = progress.landed;
-  return { ...status, ...withPending(view, change) };
-}
-
-function withPending(view: ProjectView, item: WorkItem): { rethinkPending?: string[] } {
-  const pending = pendingRethinks(view.journal, item);
-  return pending.length === 0 ? {} : { rethinkPending: pending.map((e) => String(e["finding"] ?? "")) };
-}
-
-/** Why building may not start on this branch; empty when the build gate passes. */
-export function buildGateReasons(view: ProjectView, branch: string | null): string[] {
-  const change = activeChange(view, branch);
-  if (change === undefined) return [`no change is bound to branch ${branch ?? "(none)"}; approve a planned change on this branch first`];
-  const required = [change.path];
-  const feature = featureOf(view.items, change);
-  if (feature !== undefined) required.push(feature.path);
-  if (view.snapshot.has(PATHS.architecture)) required.push(PATHS.architecture);
-  const approvals = required.flatMap((path) => {
-    const status = evaluateApproval(view, path);
-    if (status.state === "approved") return [];
-    const detail = status.changed.length > 0 ? `: ${status.changed.join(", ")} changed` : status.unjournaled === true ? ": the approval has no journal entry" : "";
-    return [`${path} is ${status.state}${detail}`];
-  });
-  const rethinks = [feature, change].flatMap((part) => {
-    const pending = part === undefined ? [] : pendingRethinks(view.journal, part);
-    return part === undefined || pending.length === 0 ? [] : [`${pendingReason(part, pending)}; run rethink`];
-  });
-  return [...approvals, ...rethinks, ...unlandedDependencies(view, change, feature)];
-}
-
-/** The changes this change's row in its feature's Changes table depends on that haven't landed on this branch. */
-function unlandedDependencies(view: ProjectView, change: WorkItem, feature: WorkItem | undefined): string[] {
-  if (feature === undefined) return [];
-  const row = readChangesTable(feature.doc).find((r) => r.change === change.folderName);
-  const landed = new Set(changesOf(view.items, feature).filter((c) => readProgress(c.doc).landed !== undefined).map((c) => c.folderName));
-  return (row?.dependsOn ?? [])
-    .filter((dependency) => !landed.has(dependency))
-    .map((dependency) => `${change.ref} depends on ${dependency}, which hasn't landed here; land it, then merge main into this branch`);
-}
-
-/** The elements a change touches: its scope and its delta, not the elements it only cites, such as a test seam. */
-export function touchedIds(view: ProjectView, change: WorkItem): Set<string> {
-  const feature = featureOf(view.items, change);
-  const scope = readScope(change.doc);
-  const ids = new Set([...(scope?.delivers ?? []), ...(scope?.builds ?? []), ...(scope?.removes ?? [])]);
-  const deltaDoc = feature?.doc ?? change.doc;
-  for (const id of readDelta(deltaDoc).ids) ids.add(id);
-  return new Set([...ids].filter((id) => !id.startsWith("RULE-")));
-}

package/src/domain/validation/decision_rules.ts

@@ -1,76 +0,0 @@
-import { definedDecisions, findDecisionCitations, workItemSlugs, type DecisionCitation } from "../decision_citations.ts";
-import type { Element } from "../elements.ts";
-import { findSection, type MarkdownDoc } from "../markdown.ts";
-import { readDelta } from "../project/deltas.ts";
-import { PATHS } from "../project/layout.ts";
-import type { ProjectView } from "../project/project_view.ts";
-import type { WorkItem } from "../project/work_items.ts";
-import { warning, type Problem } from "./problem.ts";
-
-const INSTEAD = "write what it decided into this text, or cite the ADR that records it";
-
-/**
- * The architecture cites only the decisions its own `## Decisions` defines. The other living docs
- * cite none by number, and no living doc cites a feature's or change's, which is archived when it finishes.
- */
-export function livingDecisionProblems(view: ProjectView): Problem[] {
-  const slugs = slugsOf(view);
-  const project = projectDecisions(view);
-  const problems: Problem[] = [];
-  for (const [path, doc] of view.living.docs) {
-    for (const citation of citationsIn(doc, slugs)) {
-      if (citation.qualifier !== undefined) {
-        problems.push(warning(path, citation.line, "decision-citation", `cites ${citation.text}, a decision of ${citation.qualifier}, which the living docs don't hold; ${INSTEAD}`));
-      } else if (path !== PATHS.architecture) {
-        problems.push(warning(path, citation.line, "decision-citation", `cites ${citation.text}, but only the architecture cites decisions by number, its own; ${INSTEAD}`));
-      } else {
-        const unknown = citation.numbers.filter((n) => !project.has(n));
-        if (unknown.length > 0) {
-          problems.push(warning(path, citation.line, "decision-citation", `cites ${unknown.map((n) => `D${n}`).join(", ")}, which "## Decisions" doesn't define; ${INSTEAD}`));
-        }
-      }
-    }
-  }
-  return problems;
-}
-
-/**
- * A delta's elements merge into the living docs, where the work's own decisions don't follow them.
- * They may cite a project decision the work doesn't renumber, or one the living element already cites.
- */
-export function deltaDecisionProblems(view: ProjectView, item: WorkItem): Problem[] {
-  const slugs = slugsOf(view);
-  const project = projectDecisions(view);
-  const local = definedDecisions(sectionLines(item.doc, "Settled decisions"));
-  const problems: Problem[] = [];
-  for (const { element } of readDelta(item.doc).entries) {
-    const living = view.living.elements.get(element.id);
-    const carried = new Set(living === undefined ? [] : citationsIn(living.doc, slugs, living.element).flatMap((c) => (c.qualifier === undefined ? c.numbers : [])));
-    const allowed = (n: number): boolean => project.has(n) && (!local.has(n) || carried.has(n));
-    for (const citation of citationsIn(item.doc, slugs, element)) {
-      if (citation.qualifier === undefined && citation.numbers.every(allowed)) continue;
-      problems.push(warning(item.path, citation.line, "decision-citation", `${element.id} cites ${citation.text}, which won't mean the same in the living docs once this delta merges; ${INSTEAD}`));
-    }
-  }
-  return problems;
-}
-
-function citationsIn(doc: MarkdownDoc, slugs: Set<string>, element?: Element): DecisionCitation[] {
-  const from = element === undefined ? doc.bodyStart : element.start + 1;
-  const to = element === undefined ? doc.lines.length : element.end;
-  return findDecisionCitations(doc.lines, slugs, (line) => line < from || line >= to || doc.inFence[line] === true || doc.inManaged[line] === true);
-}
-
-function projectDecisions(view: ProjectView): Set<number> {
-  const architecture = view.living.docs.get(PATHS.architecture);
-  return architecture === undefined ? new Set() : definedDecisions(sectionLines(architecture, "Decisions"));
-}
-
-function sectionLines(doc: MarkdownDoc, title: string): string[] {
-  const range = findSection(doc, title);
-  return range === null ? [] : doc.lines.slice(range.start, range.end);
-}
-
-function slugsOf(view: ProjectView): Set<string> {
-  return workItemSlugs(view.items.map((item) => item.folderName));
-}