@printpractical/cruze 0.0.13 → 0.0.14

package/src/app/use_cases/journal_events.ts

@@ -1,64 +0,0 @@
-import { CruzeError } from "../../domain/cruze_error.ts";
-import { knownPitfalls } from "../../domain/edits/agents_file.ts";
-import { journalPath, parseJournal, recordedEventProblems, recordedFields, type JournalEntry } from "../../domain/journal.ts";
-import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
-import { appendJournal, loadView, type ProjectDeps } from "../project_context.ts";
-
-/** Records an event a skill observed: a rethink, a review round, a disposition, an override or a bug. */
-export async function recordEvent(deps: ProjectDeps, event: string, fields: Record<string, string>, item?: string): Promise<JournalEntry> {
-  const problems = recordedEventProblems(event, fields);
-  if (problems.length > 0) throw new CruzeError("invalid-event", problems.join("; "));
-  let folder = ".cruze";
-  let recorded = recordedFields(fields);
-  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;
-    recorded = { ...recorded, item: resolved.ref };
-  }
-  return appendJournal(deps, folder, event, { ...recorded, cruze: deps.bundle.version });
-}
-
-/**
- * The journal of the work in flight and the project, or of one feature or change (a feature's changes' too).
- * Landed work's entries are history, listed only with `all`, since every entry ever recorded is too much to read.
- */
-export async function listEvents(deps: ProjectDeps, event?: string, item?: string, all = false): Promise<JournalEntry[]> {
-  const view = await loadView(deps.files);
-  let folders = [".cruze", ...view.items.filter((i) => all || !i.archived).map((i) => i.folder)];
-  if (item !== undefined) {
-    const resolved = resolveArtifact(view, item).item;
-    if (resolved === undefined) throw new CruzeError("not-found", `"${item}" is not a feature or change`);
-    folders = [resolved, ...view.items.filter((i) => resolved.kind === "feature" && i.featureRef === resolved.ref)].map((part) => part.folder);
-  }
-  const entries = folders.flatMap((folder) => parseJournal(view.snapshot.get(journalPath(folder))).entries).sort((a, b) => a.at.localeCompare(b.at));
-  return event === undefined ? entries : entries.filter((entry) => entry.event === event);
-}
-
-export interface FeedbackExport {
-  format: "cruze-feedback/1";
-  cruze: string;
-  exported_at: string;
-  redacted: boolean;
-  entries: JournalEntry[];
-  /** The lines under `## Known pitfalls` in `AGENTS.md`: lessons that may belong in Cruze rather than the project. */
-  pitfalls: string[];
-}
-
-/**
- * Bundles the journal, and the project's known pitfalls, for the framework feedback loop. By default the project name and
- * the approver's identity are redacted, since the bundle may leave the project.
- */
-export async function exportFeedback(deps: ProjectDeps, redact: boolean): Promise<FeedbackExport> {
-  const view = await loadView(deps.files);
-  const project = view.config?.config?.project ?? "";
-  const scrub = (value: unknown): unknown => {
-    if (typeof value === "string") return project === "" ? value : value.split(project).join("<project>");
-    if (Array.isArray(value)) return value.map(scrub);
-    if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, scrub(v)]));
-    return value;
-  };
-  const entries = redact ? view.journal.map((entry) => ({ ...(scrub(entry) as JournalEntry), by: "<redacted>" })) : view.journal;
-  const pitfalls = knownPitfalls((await deps.files.readText("AGENTS.md")) ?? "").map((line) => (redact ? (scrub(line) as string) : line));
-  return { format: "cruze-feedback/1", cruze: deps.bundle.version, exported_at: deps.clock.now().toISOString(), redacted: redact, entries, pitfalls };
-}

package/src/app/use_cases/land_change.ts

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

package/src/app/use_cases/new_project_doc.ts

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

package/src/app/use_cases/new_work_item.ts

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

package/src/app/use_cases/realign_done.ts

@@ -1,45 +0,0 @@
-import { CruzeError } from "../../domain/cruze_error.ts";
-import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
-import { PATHS } from "../../domain/project/layout.ts";
-import { withVersionLine } from "../../domain/versions/cruze_version.ts";
-import { withScheduledExceptions } from "../../domain/versions/scheduled_exceptions.ts";
-import { appendJournal, loadView, type ProjectDeps } from "../project_context.ts";
-import { realignStatus } from "./realign_status.ts";
-
-export interface RealignDone {
-  from: string;
-  to: string;
-  /** The change that fixes what is still open, when anything is. */
-  scheduled?: string;
-  /** Files listed under `check.exceptions` until that change lands. */
-  excepted: string[];
-}
-
-/**
- * Moves `standards:` up to the installed Cruze once every mechanical finding is fixed, waived,
- * or scheduled in a change. A scheduled `check` finding becomes an exception naming that change,
- * so CI stays green until it lands, and landing it removes the exception.
- */
-export async function realignDone(deps: ProjectDeps, options: { change?: string }): Promise<RealignDone> {
-  const status = await realignStatus(deps, { full: false });
-  if (status.standards === status.target) return { from: status.standards, to: status.target, excepted: [] };
-  const open = status.notes.flatMap((note) => note.findings.filter((f) => !f.waived).map((f) => ({ note, finding: f })));
-  let scheduled: string | undefined;
-  if (open.length > 0) {
-    if (options.change === undefined) {
-      const list = open.map(({ note, finding }) => `${note.id}: ${finding.path}${finding.line === undefined ? "" : `:${finding.line}`}`);
-      throw new CruzeError("realign-open", `fix, waive or schedule these first, then pass --change <ref> for the change that fixes the rest:\n  ${list.join("\n  ")}`);
-    }
-    const item = resolveArtifact(await loadView(deps.files), options.change).item;
-    if (item === undefined) throw new CruzeError("not-found", `"${options.change}" is not a feature or change; create the prefactor change first`);
-    scheduled = item.ref;
-  }
-
-  const excepted = open.filter(({ note }) => note.detect?.startsWith("check:") === true).map(({ note, finding }) => ({ path: finding.path, note: note.id }));
-  const config = (await deps.files.readText(PATHS.config)) ?? "";
-  const withExceptions = scheduled === undefined ? config : withScheduledExceptions(config, status.target, scheduled, excepted);
-  await deps.files.writeText(PATHS.config, withVersionLine(withExceptions, "standards", status.target));
-  const paths = [...new Set(excepted.map((e) => e.path))];
-  await appendJournal(deps, ".cruze", "realign", { from: status.standards, to: status.target, ...(scheduled === undefined ? {} : { scheduled }), excepted: paths });
-  return { from: status.standards, to: status.target, ...(scheduled === undefined ? {} : { scheduled }), excepted: paths };
-}

package/src/app/use_cases/realign_status.ts

@@ -1,106 +0,0 @@
-import { CruzeError } from "../../domain/cruze_error.ts";
-import type { CruzeConfig } from "../../domain/config.ts";
-import { PATHS } from "../../domain/project/layout.ts";
-import type { ProjectView } from "../../domain/project/project_view.ts";
-import { validateProject } from "../../domain/validation/validate_project.ts";
-import { notesBetween, parseRealignNotes, type RealignNote } from "../../domain/versions/realign_notes.ts";
-import { FIRST_RELEASE } from "../../domain/versions/rule_versions.ts";
-import type { Bundle } from "../ports/bundle.ts";
-import { loadView, type ProjectDeps } from "../project_context.ts";
-import { checkCode } from "./check_code.ts";
-
-export const REALIGN_SKILL = "realign";
-
-export interface RealignFinding {
-  path: string;
-  line?: number;
-  message: string;
-  /** Waived by an earlier realign, so never raised again. */
-  waived: boolean;
-}
-
-export interface RealignNoteReport extends RealignNote {
-  /** What the note's CLI rule reports now, for a note with `Detect`. */
-  findings: RealignFinding[];
-}
-
-export interface RealignStatus {
-  /** The version the code meets now, and the one the installed skills expect. */
-  standards: string;
-  target: string;
-  full: boolean;
-  /** Notes for existing code: those with findings to fix, waive or schedule, and those an auditor answers. */
-  notes: RealignNoteReport[];
-  /** Notes that change only new work, so nothing existing has to move. */
-  newWorkOnly: string[];
-  /** Mechanical findings not yet waived. */
-  open: number;
-}
-
-/**
- * What realigning the project to its installed Cruze involves: the notes of every release
- * since `standards:`, or of all releases with `full`, and what their CLI rules find now.
- */
-export async function realignStatus(deps: ProjectDeps, options: { full: boolean }): Promise<RealignStatus> {
-  const view = await loadView(deps.files);
-  const config = requireInstalled(view, deps.bundle.version);
-  const standards = config.standards ?? FIRST_RELEASE;
-  const target = deps.bundle.version;
-  const notes = notesBetween(await bundledNotes(deps.bundle), options.full ? "0.0.0" : standards, target);
-  const waived = waivedFindings(view);
-  const check = (await checkCode(deps, { ci: false })).findings;
-  const problems = validateProject(view);
-  const report = notes.filter((n) => n.appliesTo === "existing").map((note): RealignNoteReport => {
-    const [command, rule] = (note.detect ?? ":").split(":");
-    const found = command === "check" ? check.filter((f) => f.rule === rule) : command === "validate" ? problems.filter((p) => p.rule === rule) : [];
-    const findings = found.map((f) => ({
-      path: f.path,
-      ...(f.line === undefined ? {} : { line: f.line }),
-      message: f.message,
-      // A check finding is waived by listing the file under check.exceptions, which also keeps CI green.
-      waived: command === "validate" && waived.has(findingKey(note.id, f.path)),
-    }));
-    return { ...note, findings };
-  });
-  return {
-    standards,
-    target,
-    full: options.full,
-    notes: report,
-    newWorkOnly: notes.filter((n) => n.appliesTo === "new").map((n) => n.id),
-    open: report.flatMap((n) => n.findings).filter((f) => !f.waived).length,
-  };
-}
-
-/** The key a realign disposition records for a mechanical finding, so a waiver can be matched later. */
-export function findingKey(note: string, path: string): string {
-  return `${note}: ${path}`;
-}
-
-/** The project's config, once its skills come from this CLI; realign works from the installed notes. */
-export function requireInstalled(view: ProjectView, version: string): CruzeConfig {
-  const config = view.config?.config;
-  if (config === null || config === undefined) throw new CruzeError("config", `fix ${PATHS.config} first; run cruze validate for details`);
-  if (config.cruze !== version) {
-    throw new CruzeError("install-first", `the project's skills are from Cruze ${config.cruze ?? "an unrecorded version"}, and this CLI is ${version}; run cruze install first`);
-  }
-  return config;
-}
-
-async function bundledNotes(bundle: Bundle): Promise<RealignNote[]> {
-  const skill = (await bundle.skills()).find((s) => s.folder === REALIGN_SKILL);
-  return (skill?.files ?? [])
-    .flatMap((file) => {
-      const version = /^notes\/(\d+\.\d+\.\d+)\.md$/.exec(file.path)?.[1];
-      return version === undefined ? [] : parseRealignNotes(version, file.text).notes;
-    });
-}
-
-/** Findings earlier realigns waived, by key. */
-function waivedFindings(view: ProjectView): Set<string> {
-  return new Set(
-    view.journal
-      .filter((e) => e.event === "disposition" && e["review"] === "realign" && e["disposition"] === "waived")
-      .map((e) => String(e["finding"])),
-  );
-}

package/src/app/use_cases/record_progress.ts

@@ -1,118 +0,0 @@
-import { CruzeError } from "../../domain/cruze_error.ts";
-import { readRows, removeRow, upsertRow } from "../../domain/edits/managed_tables.ts";
-import { updateProgress } from "../../domain/edits/progress_block.ts";
-import { resolveChange } from "../../domain/project/artifact_ref.ts";
-import { PATHS } from "../../domain/project/layout.ts";
-import { readTasks } from "../../domain/project/plan_parts.ts";
-import { requireSlug } from "../../domain/project/new_items.ts";
-import { activeChange } from "../../domain/status/work_status.ts";
-import type { WorkItem } from "../../domain/project/work_items.ts";
-import { appendJournal, loadView, type ProjectDeps } from "../project_context.ts";
-
-/** Commands that write the CLI-owned progress records: task ticks, deviations and the feature map. */
-
-export interface TaskReport {
-  change: string;
-  task: string;
-  done: number;
-  total: number;
-}
-
-/** Marks a task done, recording the commit that completed it (HEAD by default). */
-export async function completeTask(deps: ProjectDeps, task: string, options: { change?: string; commit?: string }): Promise<TaskReport> {
-  const change = await changeFor(deps, options.change);
-  requireTask(change, task);
-  const commit = options.commit ?? (await deps.repository.headCommit()) ?? "";
-  const text = updateProgress(change.doc.lines.join("\n"), (progress) => progress.tasks.set(task, commit));
-  await deps.files.writeText(change.path, text);
-  const ticks = [...text.matchAll(/^- \[([ x])\] T\d+/gm)];
-  return { change: change.ref, task, done: ticks.filter((m) => m[1] === "x").length, total: ticks.length };
-}
-
-/** Reopens a done task whose design a rethink changed, so build does it again. */
-export async function reopenTask(deps: ProjectDeps, task: string, reason: string, options: { change?: string }): Promise<{ change: string; task: string }> {
-  const change = await changeFor(deps, options.change);
-  requireTask(change, task);
-  if (reason.trim() === "") throw new CruzeError("missing-reason", "say why the task reopens");
-  await deps.files.writeText(change.path, updateProgress(change.doc.lines.join("\n"), (progress) => progress.tasks.set(task, null)));
-  await appendJournal(deps, change.folder, "reopen", { change: change.ref, task, reason: reason.trim() });
-  return { change: change.ref, task };
-}
-
-/** Records a task-level choice the agent made on its own. Anything larger is a rethink. */
-export async function recordDeviation(deps: ProjectDeps, task: string, text: string, options: { change?: string }): Promise<{ change: string; task: string }> {
-  const change = await changeFor(deps, options.change);
-  requireTask(change, task);
-  if (text.trim() === "") throw new CruzeError("missing-text", "describe the deviation");
-  await deps.files.writeText(change.path, updateProgress(change.doc.lines.join("\n"), (progress) => progress.deviations.push(`${task}: ${text.trim()}`)));
-  await appendJournal(deps, change.folder, "deviation", { change: change.ref, task, text: text.trim() });
-  return { change: change.ref, task };
-}
-
-/** Adds a feature to the future list of the feature map, or replaces its entry. */
-export async function addFutureFeature(deps: ProjectDeps, slug: string, summary: string, goals: string[]): Promise<{ feature: string }> {
-  requireSlug(slug);
-  const vision = await requireVision(deps);
-  await deps.files.writeText(PATHS.vision, upsertRow(vision, "Future", [slug, summary, goals.join(", ")]));
-  await appendJournal(deps, ".cruze", "feature-map", { action: "add", feature: slug, summary, goals });
-  return { feature: slug };
-}
-
-/**
- * Replaces a feature's summary on the feature map, in the future list or the implemented list,
- * when a decision changed what the feature delivers. Its goals or release stay as they are.
- */
-export async function updateFeatureSummary(deps: ProjectDeps, slug: string, summary: string): Promise<{ feature: string; list: "Future" | "Implemented" }> {
-  if (summary.trim() === "") throw new CruzeError("missing-summary", "a feature needs a summary");
-  const vision = await requireVision(deps);
-  const future = readRows(vision, "Future").find((row) => row[0] === slug);
-  const implemented = readRows(vision, "Implemented").find((row) => row[0] === slug);
-  if (future === undefined && implemented === undefined) throw new CruzeError("not-found", `${slug} is not on the feature map`);
-  const list = future !== undefined ? "Future" : "Implemented";
-  const cells = future !== undefined ? [slug, summary.trim(), future[2] ?? ""] : [slug, implemented?.[1] ?? "", summary.trim()];
-  await deps.files.writeText(PATHS.vision, upsertRow(vision, list, cells));
-  await appendJournal(deps, ".cruze", "feature-map", { action: "update", feature: slug, summary: summary.trim() });
-  return { feature: slug, list };
-}
-
-export async function dropFutureFeature(deps: ProjectDeps, slug: string, reason: string): Promise<{ feature: string }> {
-  const vision = await requireVision(deps);
-  const { text, removed } = removeRow(vision, "Future", slug);
-  if (removed === null) throw new CruzeError("not-found", `${slug} is not on the future list`);
-  if (reason.trim() === "") throw new CruzeError("missing-reason", "dropping a feature needs a reason");
-  await deps.files.writeText(PATHS.vision, text);
-  await appendJournal(deps, ".cruze", "feature-map", { action: "drop", feature: slug, reason });
-  return { feature: slug };
-}
-
-/** Clears the landed rows from the roadmap's Status table, when a release closes. */
-export async function pruneRoadmap(deps: ProjectDeps): Promise<{ removed: string[] }> {
-  const roadmap = await deps.files.readText(PATHS.roadmap);
-  if (roadmap === undefined) throw new CruzeError("not-found", `${PATHS.roadmap} does not exist yet`);
-  const landed = readRows(roadmap, "Status").filter((row) => row[2] === "landed").map((row) => row[0] ?? "");
-  let text = roadmap;
-  for (const item of landed) text = removeRow(text, "Status", item).text;
-  if (landed.length > 0) {
-    await deps.files.writeText(PATHS.roadmap, text);
-    await appendJournal(deps, ".cruze", "roadmap-prune", { items: landed });
-  }
-  return { removed: landed };
-}
-
-async function changeFor(deps: ProjectDeps, ref: string | undefined): Promise<WorkItem> {
-  const view = await loadView(deps.files);
-  if (ref !== undefined) return resolveChange(view, ref);
-  const 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");
-  return change;
-}
-
-function requireTask(change: WorkItem, task: string): void {
-  if (!readTasks(change.doc).tasks.some((t) => t.number === task)) throw new CruzeError("unknown-task", `${change.ref} has no task ${task}`);
-}
-
-async function requireVision(deps: ProjectDeps): Promise<string> {
-  const vision = await deps.files.readText(PATHS.vision);
-  if (vision === undefined) throw new CruzeError("not-found", `${PATHS.vision} does not exist yet`);
-  return vision;
-}

package/src/app/use_cases/show_elements.ts

@@ -1,18 +0,0 @@
-import { CruzeError } from "../../domain/cruze_error.ts";
-import { elementIndex, lookupElements, type ElementIndex } from "../../domain/project/element_lookup.ts";
-import type { ShownElement } from "../../domain/project/scope_view.ts";
-import { loadView, type ProjectDeps } from "../project_context.ts";
-
-/** The bodies of the named elements, living and in each in-flight delta that changes them. */
-export async function showElements(deps: ProjectDeps, ids: string[]): Promise<{ elements: ShownElement[] }> {
-  const { elements, missing } = lookupElements(await loadView(deps.files), ids);
-  if (missing.length > 0) throw new CruzeError("unknown-id", `${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} defined nowhere in the living docs or the work in flight; cruze show --index lists every element`);
-  return { elements };
-}
-
-/** One line per element of the living architecture and specs, with what work in flight adds or changes. */
-export async function showIndex(deps: ProjectDeps, scope?: string): Promise<ElementIndex & { scope?: string }> {
-  const index = elementIndex(await loadView(deps.files), scope);
-  if (scope !== undefined && index.entries.length === 0) throw new CruzeError("unknown-scope", `no element belongs to "${scope}"; name a context or capability, such as the part of an ID before its dot`);
-  return scope === undefined ? index : { ...index, scope };
-}

package/src/app/use_cases/show_notes.ts

@@ -1,11 +0,0 @@
-import { notesFor, readNotes, type Note, type NotesFor } from "../../domain/project/notes.ts";
-import { loadView, type ProjectDeps } from "../project_context.ts";
-
-/**
- * Every note with what it is about and the hand-off it holds, or, given a target such as
- * `project`, `architect` or a feature slug, the notes and hand-off rows for it.
- */
-export async function showNotes(deps: ProjectDeps, target?: string): Promise<{ notes: Note[] } | (NotesFor & { target: string })> {
-  const notes = readNotes((await loadView(deps.files)).snapshot);
-  return target === undefined ? { notes } : { target, ...notesFor(notes, [target]) };
-}