@printpractical/cruze 0.0.13 → 0.0.14

package/src/domain/check/check_source.ts

@@ -1,36 +1,29 @@
 import type { CruzeConfig, Layer } from "../config.ts";
 import { matchesAny } from "../glob.ts";
 import { budgetedText } from "./budget_text.ts";
-import { decisionCitationsInComments } from "./decision_comments.ts";
 import { importsOf, resolveImport } from "./imports.ts";
 import { countTypes } from "./type_count.ts";
 
 export interface CheckFinding {
   path: string;
   line?: number;
-  rule: "layer" | "max-lines" | "max-types" | "outside-module-map" | "no-layer" | "test-placement" | "decision-citation";
+  rule: "layer" | "max-lines" | "max-types" | "no-layer" | "test-placement";
   message: string;
   /** Layer violations always fail; the rest fail in CI unless excepted. */
   severity: "error" | "warning";
-  /** Set when the rule is newer than the project's `standards:`: it reports, but can't fail CI until the project realigns. */
-  pending?: true;
 }
 
 export interface CheckInput {
   config: CruzeConfig;
   /** Every source file matched by config.source, by path. */
   sources: ReadonlyMap<string, string>;
-  /** Paths of the MOD elements in the architecture; files outside all of them are flagged. */
-  modulePaths: string[];
-  /** Test files outside config.source, by path: only their comments are checked. */
-  tests?: ReadonlyMap<string, string>;
   /** Check only these files, when given; imports still resolve against every source. */
   only?: string[];
 }
 
 /** Enforces the architecture's layer rules and the file budgets on source code. */
 export function checkSource(input: CheckInput): CheckFinding[] {
-  const { config, sources, modulePaths } = input;
+  const { config, sources } = input;
   const all = [...sources.keys()];
   const targets = input.only ?? all;
   const layerOf = (path: string): Layer | undefined => config.layers.find((layer) => matchesAny(path, layer.paths));
@@ -67,32 +60,10 @@ export function checkSource(input: CheckInput): CheckFinding[] {
     if (!excepted && isRustTestFileInSource(path)) {
       findings.push({ path, rule: "test-placement", severity: "warning", message: "Rust tests that leave their inline module go in the crate's tests/ directory, not under src/" });
     }
-    if (modulePaths.length > 0 && !insideModuleMap(path, modulePaths)) {
-      findings.push({ path, rule: "outside-module-map", severity: "warning", message: "the file is outside every module in the architecture's module map" });
-    }
-    findings.push(...decisionFindings(path, text));
-  }
-  for (const [path, text] of input.tests ?? []) {
-    if (!sources.has(path) && (input.only === undefined || input.only.includes(path))) findings.push(...decisionFindings(path, text));
   }
   return findings;
 }
 
-function decisionFindings(path: string, text: string): CheckFinding[] {
-  return decisionCitationsInComments(path, text).map((citation) => ({
-    path,
-    line: citation.line + 1,
-    rule: "decision-citation",
-    severity: "warning",
-    message: `the comment cites ${citation.text}, a decision number a reader of the code can't follow; say what was decided, or cite the element or ADR that holds it`,
-  }));
-}
-
-/** Whether a module's Path covers the file: a directory path ending in `/` covers everything under it, any other names one file. */
-export function insideModuleMap(path: string, modulePaths: string[]): boolean {
-  return modulePaths.some((module) => (module.endsWith("/") ? path.startsWith(module) : path === module));
-}
-
 /** A Rust file of tests split out of a module: `tests.rs`, `*_tests.rs`, or anything under a `tests/` folder inside `src/`. */
 function isRustTestFileInSource(path: string): boolean {
   if (!path.endsWith(".rs")) return false;

package/src/domain/config.ts

@@ -2,13 +2,10 @@ import { parse as parseYaml } from "yaml";
 
 /** `.cruze/config.yaml`, as described in the cruze-formats skill. */
 export interface CruzeConfig {
-  version: 1;
+  version: 2;
   /** The Cruze version whose skills the project installed, recorded by `cruze install`. */
   cruze?: string;
-  /** The Cruze version whose expectations the code meets, moved forward by `realign`. */
-  standards?: string;
   project: string;
-  tracker: "markdown";
   source: string[];
   tests: string[];
   check: {
@@ -17,35 +14,13 @@ export interface CruzeConfig {
     exceptions: Array<{ path: string; reason: string }>;
   };
   layers: Layer[];
-  /** Named project commands, such as `test: cargo test`, shown in AGENTS.md. */
-  commands: Record<string, string>;
   /**
    * How `cruze review` starts an agent in a fresh context: the program and its arguments.
    * Without one, the calling agent runs the role's prompt in a helper of its own.
    */
-  review: { command?: string[]; decide: ReviewDecide };
-  /** The size band of a change, so each one is worth its own plan, review and verify. */
-  changes: ChangeLimits;
-  /** External documents the design must comply with, such as a protocol specification, each with what it governs. */
-  references: Array<{ path: string; use: string }>;
+  review: { command?: string[] };
 }
 
-/** Which review findings the user decides: only the exceptions, or every one. */
-export type ReviewDecide = "exceptions" | "all";
-
-export interface ChangeLimits {
-  /** A feature's change building fewer elements than this merges into a neighbour. */
-  minBuilds: number;
-  /** A change delivering more scenarios than this splits. */
-  maxScenarios: number;
-  /** A plan with more tasks than this splits. */
-  maxTasks: number;
-  /** Features and changes the user accepted outside the band, by ref, each with the reason. */
-  exceptions: Array<{ item: string; reason: string }>;
-}
-
-export const DEFAULT_CHANGE_LIMITS: ChangeLimits = { minBuilds: 3, maxScenarios: 30, maxTasks: 25, exceptions: [] };
-
 export interface Layer {
   name: string;
   paths: string[];
@@ -62,17 +37,14 @@ export function parseConfig(text: string): ConfigResult {
   } catch (error) {
     return { config: null, problems: [`not valid YAML: ${error instanceof Error ? error.message : String(error)}`] };
   }
-  const problems: string[] = [];
   const root = asRecord(raw);
   if (root === null) return { config: null, problems: ["the file must be a YAML mapping"] };
-
-  if (root["version"] !== 1) problems.push("version must be 1");
+  if (root["version"] === 1) return { config: null, problems: ["this config was created by an older Cruze, whose documents this release doesn't read; start the project's Cruze documents again with cruze init in a fresh checkout"] };
+  const problems: string[] = [];
+  if (root["version"] !== 2) problems.push("version must be 2");
   const cruze = root["cruze"];
-  if (cruze !== undefined && (typeof cruze !== "string" || cruze.trim() === "")) problems.push("cruze must be a version string, such as \"0.0.2\"");
-  const standards = root["standards"];
-  if (standards !== undefined && (typeof standards !== "string" || standards.trim() === "")) problems.push("standards must be a version string, such as \"0.0.2\"");
+  if (cruze !== undefined && (typeof cruze !== "string" || cruze.trim() === "")) problems.push("cruze must be a version string, such as \"0.0.14\"");
   if (typeof root["project"] !== "string" || root["project"] === "") problems.push("project must be a non-empty string");
-  if (root["tracker"] !== "markdown") problems.push("tracker must be markdown");
   const source = stringList(root["source"], "source", problems);
   const tests = stringList(root["tests"], "tests", problems);
 
@@ -104,71 +76,23 @@ export function parseConfig(text: string): ConfigResult {
     }
   }
 
-  const commands: Record<string, string> = {};
-  const rawCommands = root["commands"];
-  if (rawCommands !== undefined && rawCommands !== null) {
-    const record = asRecord(rawCommands);
-    if (record === null) problems.push("commands must be a mapping of names to commands");
-    for (const [name, command] of Object.entries(record ?? {})) {
-      if (typeof command === "string" && command.trim() !== "") commands[name] = command;
-      else problems.push(`commands.${name} must be a command string`);
-    }
-  }
   const review = asRecord(root["review"]) ?? {};
   const reviewCommand = review["command"] === undefined ? undefined : stringList(review["command"], "review.command", problems);
   if (reviewCommand?.length === 0) problems.push("review.command needs at least the program to run");
-  const decide = review["decide"] ?? "exceptions";
-  if (decide !== "exceptions" && decide !== "all") problems.push("review.decide must be exceptions or all");
-  const limits = asRecord(root["changes"]) ?? {};
-  const changes: ChangeLimits = {
-    minBuilds: positiveInt(limits["min_builds"], "changes.min_builds", problems) ?? DEFAULT_CHANGE_LIMITS.minBuilds,
-    maxScenarios: positiveInt(limits["max_scenarios"], "changes.max_scenarios", problems) ?? DEFAULT_CHANGE_LIMITS.maxScenarios,
-    maxTasks: positiveInt(limits["max_tasks"], "changes.max_tasks", problems) ?? DEFAULT_CHANGE_LIMITS.maxTasks,
-    exceptions: (Array.isArray(limits["exceptions"]) ? limits["exceptions"] : []).flatMap((entry: unknown, i: number) => {
-      const record = asRecord(entry);
-      if (typeof record?.["item"] !== "string" || typeof record["reason"] !== "string" || record["reason"].trim() === "") {
-        problems.push(`changes.exceptions[${i}] needs an item and a non-empty reason`);
-        return [];
-      }
-      return [{ item: record["item"], reason: record["reason"] }];
-    }),
-  };
-
-  const references = (Array.isArray(root["references"]) ? root["references"] : root["references"] === undefined ? [] : [null]).flatMap((entry: unknown, i: number) => {
-    const record = asRecord(entry);
-    if (typeof record?.["path"] !== "string" || record["path"].trim() === "" || typeof record["use"] !== "string" || record["use"].trim() === "") {
-      problems.push(`references[${i}] needs a path and a non-empty use`);
-      return [];
-    }
-    return [{ path: record["path"], use: record["use"] }];
-  });
 
   const config: CruzeConfig = {
-    version: 1,
+    version: 2,
     ...(typeof cruze === "string" && cruze.trim() !== "" ? { cruze } : {}),
-    ...(typeof standards === "string" && standards.trim() !== "" ? { standards } : {}),
     project: typeof root["project"] === "string" ? root["project"] : "",
-    tracker: "markdown",
     source,
     tests,
-    check: { maxLines: maxLines ?? 250, maxTypes: maxTypes ?? 5, exceptions },
+    check: { maxLines: maxLines ?? 600, maxTypes: maxTypes ?? 12, exceptions },
     layers,
-    commands,
-    review: {
-      ...(reviewCommand === undefined || reviewCommand.length === 0 ? {} : { command: reviewCommand }),
-      decide: decide === "all" ? "all" : "exceptions",
-    },
-    changes,
-    references,
+    review: reviewCommand === undefined || reviewCommand.length === 0 ? {} : { command: reviewCommand },
   };
   return { config, problems };
 }
 
-/** The first layer whose paths match the file, as the formats define. */
-export function layerOf(config: CruzeConfig, path: string, matches: (path: string, globs: string[]) => boolean): Layer | undefined {
-  return config.layers.find((layer) => matches(path, layer.paths));
-}
-
 function asRecord(value: unknown): Record<string, unknown> | null {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
 }

package/src/domain/hashing.ts

@@ -1,43 +1,29 @@
 import { createHash } from "node:crypto";
-import { elementLines, isStatusLine, type Element } from "./elements.ts";
-import type { MarkdownDoc } from "./markdown.ts";
+import { findSection, type MarkdownDoc } from "./markdown.ts";
 
 /**
- * Hashes cover design content only. Managed blocks and status lines are
- * excluded, so bookkeeping by the CLI never makes a design look edited.
+ * Hashes cover design content only. A feature's `- Status:` line is bookkeeping, so marking a
+ * feature built never makes its approved design look edited.
  */
 
-export function sha256(text: string): string {
-  return `sha256:${createHash("sha256").update(text).digest("hex")}`;
-}
+const STATUS_LINE = /^- Status: \S+\s*$/;
 
-/** Hash of a whole document's design content. */
-export function designHash(doc: MarkdownDoc): string {
-  const kept = doc.lines.filter((line, i) => !doc.inManaged[i] && (doc.inFence[i] || !isStatusLine(line)));
-  return sha256(normalize(kept));
+export function isStatusLine(line: string): boolean {
+  return STATUS_LINE.test(line);
 }
 
-/**
- * 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: MarkdownDoc, element: Element): string {
-  if (element.form === "row") return sha256(normalize(elementLines(doc, element)));
-  const kept: string[] = [];
-  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));
+export function sha256(text: string): string {
+  return `sha256:${createHash("sha256").update(text).digest("hex")}`;
 }
 
-function relativeHeading(line: string, baseLevel: number, isOwnHeading: boolean): string {
-  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}`;
+/** Hash of a document's design content, leaving out the `##` sections named. */
+export function designHash(doc: MarkdownDoc, leftOut: readonly string[] = []): string {
+  const skipped = leftOut.flatMap((title) => {
+    const section = findSection(doc, title);
+    return section === null ? [] : [[section.heading.line, section.end] as const];
+  });
+  const kept = doc.lines.filter((line, i) => !skipped.some(([start, end]) => i >= start && i < end) && (doc.inFence[i] || !isStatusLine(line)));
+  return sha256(normalize(kept));
 }
 
 function normalize(lines: string[]): string {

package/src/domain/ids.ts

@@ -1,39 +1,25 @@
-/** Element IDs: `<KIND>-<name>` or `<KIND>-<scope>.<name>`, named and never reused. */
-
-export const KINDS = ["GOAL", "PRINCIPLE", "LATER", "CTX", "ENT", "UC", "PORT", "ADP", "FLOW", "MOD", "RULE", "VIEW", "XC", "REQ", "SCN", "ADR"] as const;
-export type Kind = (typeof KINDS)[number];
-
-/** Kinds of the vision's row elements: goals, the principles every design follows, and what must stay possible later. */
-export const VISION_KINDS: readonly Kind[] = ["GOAL", "PRINCIPLE", "LATER"];
-/** Kinds that describe code, and so carry a managed planned/built status. */
-export const CODE_KINDS: readonly Kind[] = ["ENT", "UC", "PORT", "ADP", "FLOW", "MOD"];
-/** Kinds whose elements carry a managed status: code kinds and scenarios. */
-export const STATUS_KINDS: readonly Kind[] = [...CODE_KINDS, "SCN"];
-/** Kinds that must name their context or capability as a scope. */
-export const SCOPED_KINDS: readonly Kind[] = ["ENT", "UC", "PORT", "ADP", "FLOW", "REQ", "SCN"];
+/** Scenario IDs: `SCN-<feature>.<name>`, lowercase words joined by single hyphens, named and never reused. */
 
 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 const SLUG = new RegExp(`^${WORD}$`);
+const SCENARIO = `SCN-${WORD}\\.${WORD}`;
+const EXACT = new RegExp(`^${SCENARIO}$`);
+const ANYWHERE = new RegExp(`(?<![A-Za-z0-9_-])${SCENARIO}(?![A-Za-z0-9_.-])`, "g");
 
-export function isId(text: string): boolean {
+export function isScenarioId(text: string): boolean {
   return EXACT.test(text);
 }
 
-export function kindOf(id: string): Kind {
-  return id.slice(0, id.indexOf("-")) as Kind;
+export function isSlug(text: string): boolean {
+  return SLUG.test(text);
 }
 
-/** The context or capability an ID belongs to, if it has one. */
-export function scopeOf(id: string): string | undefined {
-  const rest = id.slice(id.indexOf("-") + 1);
-  const dot = rest.indexOf(".");
-  return dot === -1 ? undefined : rest.slice(0, dot);
+/** The feature a scenario belongs to. */
+export function featureOfScenario(id: string): string {
+  return id.slice(4, id.indexOf("."));
 }
 
-/** Every ID mentioned in the text, once each, in order of first mention. */
-export function findIds(text: string): string[] {
+/** Every scenario ID mentioned in the text, once each, in order of first mention. */
+export function findScenarioIds(text: string): string[] {
   return [...new Set(text.match(ANYWHERE) ?? [])];
 }

package/src/domain/next_step.ts

@@ -0,0 +1,41 @@
+import { approvalState } from "./approvals.ts";
+import { PATHS } from "./project/layout.ts";
+import type { ProjectDocs } from "./project/project_docs.ts";
+
+export type Step = "init" | "envision" | "shape" | "build";
+
+export interface NextStep {
+  step: Step;
+  /** The feature the step works on, for shape and build. */
+  target?: string;
+  reason: string;
+}
+
+/**
+ * The step to run next, from the documents alone. Work in progress comes first, in release order,
+ * then the first release feature not yet shaped whose needs are all built.
+ */
+export function nextStep(docs: ProjectDocs): NextStep {
+  if (docs.config === undefined) return { step: "init", reason: `${PATHS.config} is missing` };
+  if (docs.vision === undefined) return { step: "envision", reason: "the project has no vision yet" };
+  if (approvalState(docs.approvals, PATHS.vision, docs.vision) !== "approved") return { step: "envision", reason: "the vision isn't approved as it stands" };
+  if (docs.architecture === undefined) return { step: "envision", reason: "the project has no architecture map yet" };
+  if (approvalState(docs.approvals, PATHS.architecture, docs.architecture) !== "approved") return { step: "envision", reason: "the architecture map isn't approved as it stands" };
+
+  const order = [...docs.release.map((r) => r.slug), ...docs.features.map((f) => f.slug).filter((slug) => !docs.release.some((r) => r.slug === slug))];
+  for (const slug of order) {
+    const feature = docs.features.find((f) => f.slug === slug);
+    if (feature === undefined || feature.status === "built") continue;
+    const state = approvalState(docs.approvals, feature.path, feature.doc);
+    if (state === "unapproved") return { step: "shape", target: slug, reason: `${slug} is shaped but not approved` };
+    if (state === "edited") return { step: "shape", target: slug, reason: `${slug} changed since its approval; show the user what changed and approve it again` };
+    return { step: "build", target: slug, reason: `${slug} is approved and not built` };
+  }
+
+  const built = new Set(docs.features.filter((f) => f.status === "built").map((f) => f.slug));
+  const pending = docs.release.filter((r) => !built.has(r.slug));
+  const ready = pending.find((r) => !docs.features.some((f) => f.slug === r.slug) && r.needs.every((need) => built.has(need)));
+  if (ready !== undefined) return { step: "shape", target: ready.slug, reason: ready.needs.length === 0 ? `${ready.slug} is next in the release` : `${ready.slug} is next in the release, and everything it needs is built` };
+  if (pending.length > 0) return { step: "envision", reason: `no remaining release feature has all its needs built (${pending.map((r) => r.slug).join(", ")}); fix the Needs column` };
+  return { step: "envision", reason: docs.release.length === 0 ? "the vision's Release table lists no features" : "every release feature is built; plan the next release" };
+}

package/src/domain/project/features.ts

@@ -0,0 +1,71 @@
+import { isStatusLine } from "../hashing.ts";
+import { findScenarioIds, isScenarioId } from "../ids.ts";
+import { findSection, parseMarkdown, type MarkdownDoc } from "../markdown.ts";
+import { featurePath } from "./layout.ts";
+
+/** A feature document, docs/features/<slug>.md: one slice of behaviour, its public API and its stack sketch. */
+export interface Feature {
+  slug: string;
+  path: string;
+  text: string;
+  doc: MarkdownDoc;
+  /** `shaped` until build finishes it, then `built`; undefined when the line is missing or unknown. */
+  status: FeatureStatus | undefined;
+  /** The scenarios under `## Behaviour`, by heading `### SCN-<slug>.<name>: <title>`. */
+  scenarios: Scenario[];
+}
+
+export type FeatureStatus = "shaped" | "built";
+export const FEATURE_STATUSES: readonly FeatureStatus[] = ["shaped", "built"];
+
+export interface Scenario {
+  id: string;
+  title: string;
+  /** 0-based line of its heading. */
+  line: number;
+}
+
+export const FEATURE_SECTIONS = ["Intent", "Behaviour", "Public API", "Stack sketch", "Decisions"] as const;
+
+export function readFeature(slug: string, text: string): Feature {
+  const doc = parseMarkdown(text);
+  return { slug, path: featurePath(slug), text, doc, status: statusOf(doc), scenarios: scenariosOf(doc) };
+}
+
+/** The feature's `- Status:` line, the first one outside code. */
+export function statusLine(doc: MarkdownDoc): { line: number; value: string } | undefined {
+  const index = doc.lines.findIndex((line, i) => !doc.inFence[i] && isStatusLine(line));
+  if (index === -1) return undefined;
+  return { line: index, value: (doc.lines[index] ?? "").replace("- Status:", "").trim() };
+}
+
+function statusOf(doc: MarkdownDoc): FeatureStatus | undefined {
+  const value = statusLine(doc)?.value;
+  return (FEATURE_STATUSES as readonly string[]).includes(value ?? "") ? (value as FeatureStatus) : undefined;
+}
+
+/** Scenario headings under `## Behaviour`: any heading whose text starts with a scenario ID and a colon. */
+function scenariosOf(doc: MarkdownDoc): Scenario[] {
+  const section = findSection(doc, "Behaviour");
+  if (section === null) return [];
+  return doc.headings
+    .filter((h) => h.line >= section.start && h.line < section.end)
+    .flatMap((h) => {
+      const match = /^(\S+): (.+)$/.exec(h.text);
+      if (match?.[1] === undefined || match[2] === undefined || !isScenarioId(match[1])) return [];
+      return [{ id: match[1], title: match[2], line: h.line }];
+    });
+}
+
+/** Scenario-like IDs under `## Behaviour` that aren't a proper scenario heading, for validate to report. */
+export function strayScenarioIds(feature: Feature): Array<{ id: string; line: number }> {
+  const section = findSection(feature.doc, "Behaviour");
+  if (section === null) return [];
+  const headed = new Set(feature.scenarios.map((s) => s.line));
+  const stray: Array<{ id: string; line: number }> = [];
+  for (let i = section.start; i < section.end; i++) {
+    if (headed.has(i) || feature.doc.inFence[i] || !/^#{1,6} /.test(feature.doc.lines[i] ?? "")) continue;
+    for (const id of findScenarioIds(feature.doc.lines[i] ?? "")) stray.push({ id, line: i });
+  }
+  return stray;
+}

package/src/domain/project/layout.ts

@@ -1,4 +1,4 @@
-/** Where Cruze documents live in a project, and the snapshot of them the domain works on. */
+/** Where Cruze documents live in a project. */
 
 /** Project files by path, relative to the project root, with forward slashes. */
 export type Snapshot = ReadonlyMap<string, string>;
@@ -6,36 +6,20 @@ export type Snapshot = ReadonlyMap<string, string>;
 export const PATHS = {
   readme: "README.md",
   vision: "docs/vision.md",
-  glossary: "docs/glossary.md",
   architecture: "docs/architecture.md",
-  roadmap: "docs/roadmap.md",
-  adrDir: "docs/adr",
-  specsDir: "docs/specs",
+  featuresDir: "docs/features",
   config: ".cruze/config.yaml",
-  featuresDir: ".cruze/features",
-  changesDir: ".cruze/changes",
-  archiveDir: ".cruze/archive",
-  notesDir: ".cruze/notes",
-  projectApprovals: ".cruze/approvals.json",
-  projectJournal: ".cruze/journal.jsonl",
+  approvals: ".cruze/approvals.json",
 } as const;
 
-/** Directories whose files make up the snapshot. */
-export const SNAPSHOT_ROOTS = ["docs", ".cruze"] as const;
-
-export function specPath(capability: string): string {
-  return `${PATHS.specsDir}/${capability}.md`;
-}
-
-export function filesUnder(snapshot: Snapshot, dir: string): string[] {
-  const prefix = `${dir}/`;
-  return [...snapshot.keys()].filter((path) => path.startsWith(prefix)).sort();
+export function featurePath(slug: string): string {
+  return `${PATHS.featuresDir}/${slug}.md`;
 }
 
-/** Paths directly matching `<dir>/<name><suffix>`, one level deep. */
-export function childFiles(snapshot: Snapshot, dir: string, suffix: string): string[] {
-  return filesUnder(snapshot, dir).filter((path) => {
-    const rest = path.slice(dir.length + 1);
-    return !rest.includes("/") && rest.endsWith(suffix);
-  });
+/** The feature slug of a path directly under docs/features/, or undefined. */
+export function slugOfFeaturePath(path: string): string | undefined {
+  const prefix = `${PATHS.featuresDir}/`;
+  if (!path.startsWith(prefix) || !path.endsWith(".md")) return undefined;
+  const rest = path.slice(prefix.length, -3);
+  return rest.includes("/") ? undefined : rest;
 }

package/src/domain/project/project_docs.ts

@@ -0,0 +1,48 @@
+import { parseApprovals, type ApprovalRecord } from "../approvals.ts";
+import { parseConfig, type ConfigResult } from "../config.ts";
+import { parseMarkdown, type MarkdownDoc } from "../markdown.ts";
+import { readFeature, type Feature } from "./features.ts";
+import { PATHS, slugOfFeaturePath, type Snapshot } from "./layout.ts";
+import { readRelease, type ReleaseFeature } from "./release.ts";
+
+/** Every Cruze document of a project, parsed: what the use cases work on. */
+export interface ProjectDocs {
+  snapshot: Snapshot;
+  config: ConfigResult | undefined;
+  vision: MarkdownDoc | undefined;
+  architecture: MarkdownDoc | undefined;
+  release: ReleaseFeature[];
+  /** Feature documents, by slug, in slug order. */
+  features: Feature[];
+  approvals: ApprovalRecord[];
+}
+
+export function buildProjectDocs(snapshot: Snapshot): ProjectDocs {
+  const read = (path: string): MarkdownDoc | undefined => {
+    const text = snapshot.get(path);
+    return text === undefined ? undefined : parseMarkdown(text);
+  };
+  const configText = snapshot.get(PATHS.config);
+  const vision = read(PATHS.vision);
+  const features = [...snapshot.keys()]
+    .flatMap((path) => {
+      const slug = slugOfFeaturePath(path);
+      return slug === undefined ? [] : [readFeature(slug, snapshot.get(path) ?? "")];
+    })
+    .sort((a, b) => a.slug.localeCompare(b.slug));
+  return {
+    snapshot,
+    config: configText === undefined ? undefined : parseConfig(configText),
+    vision,
+    architecture: read(PATHS.architecture),
+    release: vision === undefined ? [] : readRelease(vision),
+    features,
+    approvals: parseApprovals(snapshot.get(PATHS.approvals)),
+  };
+}
+
+/** The document a reference names: `vision`, `architecture`, a feature slug, or a path. */
+export function resolveDocument(docs: ProjectDocs, ref: string): string | undefined {
+  const path = ref === "vision" ? PATHS.vision : ref === "architecture" ? PATHS.architecture : (docs.features.find((f) => f.slug === ref)?.path ?? ref);
+  return docs.snapshot.has(path) ? path : undefined;
+}

package/src/domain/project/release.ts

@@ -0,0 +1,30 @@
+import { findSection, type MarkdownDoc } from "../markdown.ts";
+import { tablesIn } from "../markdown_tables.ts";
+
+/** One row of the vision's `## Release` table: a feature of the release, in build order, and the features it needs. */
+export interface ReleaseFeature {
+  slug: string;
+  summary: string;
+  needs: string[];
+  /** 0-based line of its row. */
+  line: number;
+}
+
+/** The release's features, from the first table under `## Release` with Feature and Needs columns. */
+export function readRelease(vision: MarkdownDoc): ReleaseFeature[] {
+  const section = findSection(vision, "Release");
+  if (section === null) return [];
+  const table = tablesIn(vision.lines, vision.inFence, section.start, section.end).find((t) => t.header.includes("Feature") && t.header.includes("Needs"));
+  if (table === undefined) return [];
+  const at = (name: string): number => table.header.indexOf(name);
+  return table.rows.map(({ cells, line }) => ({
+    slug: unquote(cells[at("Feature")] ?? ""),
+    summary: at("Summary") === -1 ? "" : (cells[at("Summary")] ?? ""),
+    needs: (cells[at("Needs")] ?? "").split(",").map(unquote).filter((need) => need !== "" && !/^[-—–]+$/.test(need)),
+    line,
+  }));
+}
+
+function unquote(cell: string): string {
+  return cell.trim().replace(/^`(.*)`$/, "$1").trim();
+}

package/src/domain/scaffold.ts

@@ -13,7 +13,6 @@ export const INIT_SCAFFOLD: readonly ScaffoldEntry[] = [
   { path: "AGENTS.md", template: "init/AGENTS.md" },
   { path: ".cruze/config.yaml", template: "init/config.yaml" },
   { path: ".github/workflows/ci.yml", template: "init/ci.yml" },
-  { path: ".gitattributes", template: "init/gitattributes" },
 ];
 
 /**

package/src/domain/skill_budget.ts

@@ -7,11 +7,11 @@ import type { SkillFiles } from "./skill_links.ts";
 export const MAX_FILE_WORDS = 2100;
 
 /**
- * The words agents may read across the whole bundle. Every retro adds rules, and between 0.0.1 and
- * 0.0.10 the skills grew by half while nothing was removed. Lower this when text is cut. Raising it
- * is the maintainer's decision, with the reason in the commit that raises it.
+ * The words agents may read across the whole bundle. By 0.0.13 the skills had grown to 45,800 words
+ * as every fix added rules and nothing was removed; 0.0.14 cut them to this. Lower it when text is
+ * cut. Raising it is the maintainer's decision, with the reason in the commit that raises it.
  */
-export const BUNDLE_WORD_BUDGET = 45800;
+export const BUNDLE_WORD_BUDGET = 17605;
 
 /** Data the CLI reads or renders, rather than instructions an agent reads. */
 const NOT_INSTRUCTIONS = /(^|\/)(templates|notes)\//;