@printpractical/cruze 0.0.6 → 0.0.8

package/skills/roles/verifier.md

@@ -4,23 +4,24 @@ You check that a change actually works when someone uses it. The tests passing i
 
 ## Inputs
 
-- The change's `change.md`, and its `feature.md` when it belongs to a feature. The scenarios it delivers are listed under `Delivers` in its scope, and written out in the spec delta.
+- The change's `change.md`, for its test plan, and the output of `cruze show <ref>`: the scenarios it delivers, written out, and the flows and elements it builds.
 - The project's commands, from `commands:` in `.cruze/config.yaml`, and from `README.md` when they aren't there.
 - The mechanical checks' results, with the commit they ran at.
-- The flows in `docs/architecture.md` that serve those scenarios.
 
 ## Work
 
 1. **Build.** Build the system with the project's build command, and record whether it passed. The test suite already ran at the commit in your inputs, and CI runs it again before the merge, so don't run it. Run a single test only when it is how a scenario reaches its real front door, such as a UI test that drives the app.
 2. **Trace.** Run `cruze trace --change <ref>` and record its result.
-3. **Run each scenario.** For every scenario the change delivers:
+3. **Run each scenario that has a front door.** A scenario whose test plan row names an inbound adapter, a screen or a real adapter as its seam is one a user meets, so run it:
    - Set up its GIVEN with real things where you can: configuration files, directories, a local test server, a pseudo-terminal. Put them in a temporary directory outside the project.
    - Perform its WHEN through the real inbound adapter, such as the CLI binary or an HTTP request, the way a user or client would.
    - Compare what you observe with its THEN, word for word where the scenario quotes output.
-4. **Probe one step further.** For each scenario, try the nearest thing a user would plausibly do next or get wrong, such as the same command twice, a typo in the input, or an interrupt. Report surprises; they are not failures of the scenario.
+
+   A scenario whose row runs through a use case with fakes is proved by its behaviour test, which passed at the checks commit: give the test's file and name as `Ran:` and the commit as `Observed:`, and don't drive it. Driving every scenario cost one app project 31 minutes a change, for one defect in 28 runs.
+4. **Probe one step further.** For each scenario you ran, try the nearest thing a user would plausibly do next or get wrong, such as the same command twice, a typo in the input, or an interrupt. Report surprises; they are not failures of the scenario.
 5. **Clean up** everything you created outside the project.
 
-When a scenario needs something you don't have, such as real hardware or a remote host, don't fake it. Mark it `could not run`, and say exactly what it needs, so a person can run it by hand.
+When a scenario needs something you don't have, such as real hardware or a remote host, don't fake it. Mark it `could not run`, and say exactly what it needs, so a person can run it by hand. The same holds for time: don't idle through a timer, a scheduled notification or a device settling. Drive time through the project's seam for it when there is one; otherwise a wait over 30 seconds is `could not run`, with the wait a person needs.
 
 ## Report
 

package/skills/triage/SKILL.md

@@ -33,3 +33,5 @@ Triage starts from a symptom and ends with a fix, or with the right step to fix
 - Code defect fixed: `land`, which lands bug fixes too.
 - Spec gap: `architect "<tweak>"`.
 - Design flaw: `rethink`.
+
+Start it in a new session, so its context starts empty.

package/skills/verify/SKILL.md

@@ -16,7 +16,7 @@ Verify answers one question: does this change work when someone uses it? Green t
    - When one fails, fix the code in a commit and run them again. When a fix needs design, stop and offer `rethink`.
 3. **Check the dependencies.** Follow "Checking" in `.agents/skills/cruze-dependency-approval/SKILL.md` against the base commit. An unrecorded dependency is a blocker.
 4. **Run the verifier.** Run the verifier role from `.agents/skills/cruze-roles/SKILL.md` for the change, with the mechanical checks' results and the commit they ran at. It must be able to build and run the system. When it runs through `cruze review`, check that `review.command` in `.cruze/config.yaml` allows the project's build and run commands, and add them with the user's agreement. Done when you have its report, with a result for every delivered scenario.
-5. **Review the code.** Run the review in the roles skill with the code reviewer, `review=code`, `--item <ref>` and the base commit. Fix each finding whose disposition is `fixed` in a commit, running the tests each fix touches, and `test` when `commands:` has a `test_full`. Then check the fixes in round 2.
+5. **Review the code.** Run the review in the roles skill with the code reviewer, `review=code`, `--item <ref>` and the base commit. Fix each finding whose disposition is `fixed` in a commit, running the tests each fix touches, and `test` when `commands:` has a `test_full`. Then check the fixes yourself, as round 2 in the roles skill says.
 6. **Write the manual test script** as `manual-test.md` in the change folder, following [manual-test.md](manual-test.md). Commit it.
 7. **Check the fixes once.** When code changed since the last `checks` entry, run the format, lint and build commands and the full suite once more, and record them as in step 2. Done when the last `checks` entry is at a commit with no code changes since.
 8. **Report.** Show the user four things:
@@ -41,3 +41,5 @@ Done when the decision is recorded.
 
 - Accepted: `land`.
 - Sent back: `build` for reopened tasks, or `rethink` for design.
+
+Start it in a new session, so its context starts empty.

package/src/adapters/inbound/cli/commands/journal.ts

@@ -15,7 +15,7 @@ export async function runJournal(context: CliContext, args: string[], options: O
     return { json: entry, human: `Recorded ${entry.event}.` };
   }
   if (args[0] === "list") {
-    const entries = await listEvents(context, options.event, options.item);
+    const entries = await listEvents(context, options.event, options.item, options.all);
     return { json: entries, human: entries.map((e) => `${e.at} ${e.event} ${JSON.stringify({ ...e, at: undefined, event: undefined, by: undefined })}`).join("\n") || "No entries." };
   }
   throw new UsageError(`cruze journal takes add or list, not "${args[0]}"`);

package/src/adapters/inbound/cli/commands/show.ts

@@ -0,0 +1,27 @@
+import { showScope, type ScopeReport } from "../../../../app/use_cases/show_scope.ts";
+import type { ShownElement } from "../../../../domain/project/scope_view.ts";
+import { requireArgs, type CliContext, type CommandResult } from "../cli_context.ts";
+
+export async function runShow(context: CliContext, args: string[]): Promise<CommandResult> {
+  requireArgs(args, ["ref"]);
+  const report = await showScope(context, args[0] ?? "");
+  return { json: report, human: render(report) };
+}
+
+/** The scope as a document an agent reads in place of the living docs. */
+function render(report: ScopeReport): string {
+  const lines = [`# ${report.ref}${report.feature === undefined ? "" : ` (feature ${report.feature})`}`, ""];
+  lines.push("## Elements", "", ...blocks(report.elements), "## Scenarios", "", ...blocks(report.scenarios));
+  lines.push("## Cited, not shown", "");
+  lines.push(...(report.cited.length === 0 ? ["None."] : report.cited.map((c) => `- ${c.id}: ${c.title} (${c.source})`)), "");
+  lines.push("## Settled decisions", "", ...(report.decisions.length === 0 ? ["None."] : report.decisions), "");
+  lines.push("## Dispositions", "");
+  lines.push(...(report.dispositions.length === 0 ? ["None."] : report.dispositions.map((d) => `- [${d.disposition}, ${d.review}] ${d.finding}: ${d.reason}`)), "");
+  if (report.missing.length > 0) lines.push("## Missing", "", ...report.missing.map((id) => `- ${id} is defined nowhere`), "");
+  return lines.join("\n").trimEnd();
+}
+
+function blocks(elements: ShownElement[]): string[] {
+  if (elements.length === 0) return ["None.", ""];
+  return elements.flatMap((element) => [`<!-- ${element.source} -->`, ...element.body.join("\n").trimEnd().split("\n"), ""]);
+}

package/src/adapters/inbound/cli/commands/status.ts

@@ -32,9 +32,25 @@ export async function runStatus(context: CliContext, _args: string[], options: O
     }
   }
   for (const change of report.standalone) lines.push(`${describe(`change ${change.ref}`, change.approval)}, tasks ${change.tasksDone}/${change.tasksTotal}`);
-  return { json: report, human: lines.join("\n") };
+  const json = {
+    ...report,
+    documents: report.documents.map(compact),
+    features: report.features.map((f) => ({ ...f, approval: compact(f.approval), changes: f.changes.map((c) => ({ ...c, approval: compact(c.approval) })) })),
+    standalone: report.standalone.map((c) => ({ ...c, approval: compact(c.approval) })),
+  };
+  return { json, human: lines.join("\n") };
 }
 
+/** The state without the record's hashes: an agent reads status often, and the hashes were a third of each read. */
+function compact(status: ApprovalStatus): Omit<ApprovalStatus, "record"> & { approvedAt?: string; by?: string; basis?: string } {
+  const { record, ...rest } = status;
+  if (record === undefined) return rest;
+  return { ...rest, approvedAt: record.approvedAt, by: record.by, ...(record.basis === undefined ? {} : { basis: record.basis }) };
+}
+
+/** Every step starts a new session: one session that ran plan, build, verify and land reached 745k tokens of context. */
+const FRESH_SESSION = "Run it in a new session, so its context starts empty.";
+
 const BASIS: Record<string, string> = { "plan-review": " (by the agent, after its plan review)", rethink: " (re-stamped by the agent after a rethink)" };
 
 function describe(label: string, status: ApprovalStatus): string {
@@ -46,6 +62,6 @@ function describe(label: string, status: ApprovalStatus): string {
 export async function runNext(context: CliContext): Promise<CommandResult> {
   const report = await suggestNext(context);
   const describe = (s: { step: string; target?: string; reason: string }): string => `${s.step}${s.target === undefined ? "" : ` ${s.target}`}: ${s.reason}`;
-  const lines = [`Next: ${describe(report.next)}`, ...report.also.map((s) => `Also: ${describe(s)}`)];
-  return { json: report, human: lines.join("\n") };
+  const lines = [`Next: ${describe(report.next)}`, ...report.also.map((s) => `Also: ${describe(s)}`), FRESH_SESSION];
+  return { json: { ...report, session: FRESH_SESSION }, human: lines.join("\n") };
 }

package/src/adapters/inbound/cli/commands.ts

@@ -7,6 +7,7 @@ import { runRealign } from "./commands/realign.ts";
 import { runFeedback, runJournal } from "./commands/journal.ts";
 import { runAbandon, runFeatures, runRoadmap, runTask } from "./commands/progress.ts";
 import { runReviewCommand } from "./commands/review.ts";
+import { runShow } from "./commands/show.ts";
 import { runNext, runStatus } from "./commands/status.ts";
 
 /** A command, and the options it takes: one list, or one per subcommand for a command that has them. */
@@ -22,6 +23,7 @@ export const COMMANDS: Record<string, Command> = {
   validate: { handler: runValidate, options: [], usage: "validate                                          check every document against the formats" },
   status: { handler: runStatus, options: ["gate", "override", "overlap", "change"], usage: "status [--gate build [--override <reason>]] [--overlap [--change <ref>]]" },
   next: { handler: runNext, options: [], usage: "next                                              the step to run next on this branch, and why" },
+  show: { handler: runShow, options: [], usage: "show <ref>                                        the design a change builds, or a feature's delta, with what it cites and its settled ledger" },
   approve: {
     handler: runApprove,
     options: ["replan", "rebase", "by-agent", "restamp-unchanged"],
@@ -35,7 +37,7 @@ export const COMMANDS: Record<string, Command> = {
   task: { handler: runTask, options: { done: ["change", "commit"], deviation: ["change"], reopen: ["change"] }, usage: "task <done|deviation|reopen> <T#> [text] [--change <ref>] [--commit <sha>]" },
   features: { handler: runFeatures, options: { add: ["summary", "goals"], update: ["summary"], drop: ["reason"] }, usage: "features <add|update|drop> <slug> [--summary <text>] [--goals <ids>] [--reason <text>]" },
   roadmap: { handler: runRoadmap, options: { prune: [] }, usage: "roadmap prune                                     clear landed items from the roadmap status when a release closes" },
-  journal: { handler: runJournal, options: { add: ["set", "item"], list: ["event", "item"] }, usage: "journal <add <event> --set key=value... [--item <ref>]|list [--event <event>] [--item <ref>]>" },
+  journal: { handler: runJournal, options: { add: ["set", "item"], list: ["event", "item", "all"] }, usage: "journal <add <event> --set key=value... [--item <ref>]|list [--event <event>] [--item <ref>] [--all]>" },
   review: { handler: runReviewCommand, options: ["item", "round", "blockers", "base"], usage: "review <role> [--item <ref>] [--round 1|2 --blockers <file>] [--base <commit>]   run a role in a fresh agent context" },
   feedback: { handler: runFeedback, options: { export: ["out", "no-redact"] }, usage: "feedback export [--out <file>] [--no-redact]" },
   trace: { handler: runTrace, options: ["all", "change"], usage: "trace [--all] [--change <ref>]                    link scenarios to the tests that prove them" },

package/src/app/use_cases/approve_artifact.ts

@@ -15,6 +15,8 @@ import { isPlanned, readChangesTable } 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 { featureOf } from "../../domain/project/work_items.ts";
+import type { Problem } from "../../domain/validation/problem.ts";
+import { SIZE_RULES } from "../../domain/validation/size_rules.ts";
 import { validateProject } from "../../domain/validation/validate_project.ts";
 import { appendJournal, loadView, withFiles, type ProjectDeps } from "../project_context.ts";
 
@@ -87,11 +89,13 @@ export async function approveArtifact(deps: ProjectDeps, ref: string, options: A
   if (text !== view.snapshot.get(path)) edits.set(path, text);
   view = withFiles(view, edits);
 
-  const errors = validateProject(view).filter((p) => p.path === path && p.severity === "error");
+  const problems = validateProject(view).filter((p) => p.path === path);
+  const errors = problems.filter((p) => p.severity === "error");
   if (errors.length > 0) {
     const listing = errors.map((p) => `  ${p.path}:${p.line ?? ""} ${p.message}`).join("\n");
     throw new CruzeError("invalid", `${path} has ${errors.length} problem(s) to fix before approval:\n${listing}`);
   }
+  requireSizesAccepted(problems, path);
 
   const { hash, upstream } = fingerprint(view, path, parseMarkdown(text));
   const folder = approvalFolder(view, path);
@@ -154,6 +158,20 @@ function requireRebased(view: ProjectView, deltaIds: Set<string>, previous: Appr
   }
 }
 
+/**
+ * A size warning stands until the work is split or the user accepts it under `changes.exceptions`.
+ * A 28-task change approved over its warning went on to 26 deviations, so approval waits for one or the other.
+ */
+function requireSizesAccepted(problems: Problem[], path: string): void {
+  const standing = problems.filter((p) => SIZE_RULES.includes(p.rule));
+  if (standing.length === 0) return;
+  const listing = standing.map((p) => `  ${p.message} [${p.rule}]`).join("\n");
+  throw new CruzeError(
+    "size-unaccepted",
+    `${path} has ${standing.length} size warning(s). Split the work through rethink, or record the user's acceptance under changes.exceptions in .cruze/config.yaml, as the item's ref and their reason:\n${listing}`,
+  );
+}
+
 function notWork(path: string): never {
   throw new CruzeError("needs-user", `${path} is a project document, so the user approves it`);
 }

package/src/app/use_cases/check_code.ts

@@ -6,6 +6,7 @@ import { FIRST_RELEASE, isPending } from "../../domain/versions/rule_versions.ts
 import type { CruzeConfig } from "../../domain/config.ts";
 import type { ProjectView } from "../../domain/project/project_view.ts";
 import { resolveChange } from "../../domain/project/artifact_ref.ts";
+import { readDelta } from "../../domain/project/deltas.ts";
 import { activeChange } from "../../domain/status/work_status.ts";
 import { traceScenarios, type TraceReport } from "../../domain/trace.ts";
 import { loadView, type ProjectDeps } from "../project_context.ts";
@@ -88,8 +89,14 @@ function globBase(glob: string): string {
   return fixed.join("/");
 }
 
+/**
+ * Every module's Path: the living docs' modules, and the modules that work in progress adds or
+ * changes in its architecture delta, since their files are written before land merges them.
+ */
 function modulePaths(view: ProjectView): string[] {
-  return [...view.living.elements.values()]
-    .filter((e) => e.id.startsWith("MOD-"))
-    .flatMap((e) => (factsOf(e.doc, e.element).get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? "")));
+  const living = [...view.living.elements.values()].filter((e) => e.id.startsWith("MOD-")).map((e) => ({ doc: e.doc, element: e.element }));
+  const inFlight = view.items
+    .filter((item) => item.kind !== "change" && !item.archived)
+    .flatMap((item) => readDelta(item.doc).entries.filter((entry) => entry.element.id.startsWith("MOD-") && entry.element.op !== "REMOVED").map((entry) => ({ doc: item.doc, element: entry.element })));
+  return [...living, ...inFlight].flatMap(({ doc, element }) => (factsOf(doc, element).get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? "")));
 }

package/src/app/use_cases/journal_events.ts

@@ -18,16 +18,19 @@ export async function recordEvent(deps: ProjectDeps, event: string, fields: Reco
   return appendJournal(deps, folder, event, { ...recorded, cruze: deps.bundle.version });
 }
 
-/** The journal, or one feature's or change's part of it: its own journal, and a feature's changes' too. */
-export async function listEvents(deps: ProjectDeps, event?: string, item?: string): Promise<JournalEntry[]> {
+/**
+ * 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 entries = view.journal;
+  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`);
-    const parts = [resolved, ...view.items.filter((i) => resolved.kind === "feature" && i.featureRef === resolved.ref)];
-    entries = parts.flatMap((part) => parseJournal(view.snapshot.get(journalPath(part.folder))).entries).sort((a, b) => a.at.localeCompare(b.at));
+    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);
 }
 

package/src/app/use_cases/run_review.ts

@@ -4,7 +4,7 @@ import { featureOf } from "../../domain/project/work_items.ts";
 import type { AgentRunner } from "../ports/agent_runner.ts";
 import { loadView, type ProjectDeps } from "../project_context.ts";
 
-export const ROLES = ["design-reviewer", "code-reviewer", "verifier", "researcher", "auditor"] as const;
+export const ROLES = ["design-reviewer", "code-reviewer", "verifier", "researcher", "auditor", "surveyor"] as const;
 export type Role = (typeof ROLES)[number];
 
 export interface ReviewRequest {

package/src/app/use_cases/show_scope.ts

@@ -0,0 +1,35 @@
+import { CruzeError } from "../../domain/cruze_error.ts";
+import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
+import { scopeView, type ScopeView } from "../../domain/project/scope_view.ts";
+import { loadView, type ProjectDeps } from "../project_context.ts";
+import { listEvents } from "./journal_events.ts";
+
+export interface Disposition {
+  finding: string;
+  disposition: string;
+  reason: string;
+  review: string;
+}
+
+export interface ScopeReport extends ScopeView {
+  /** The settled ledger of the item: the feature's dispositions and its changes', or a standalone change's. */
+  dispositions: Disposition[];
+}
+
+/**
+ * The design a change builds, or a feature's whole delta, with the elements it cites and the
+ * item's settled ledger: what plan, build and the reviewers read instead of the whole living docs.
+ */
+export async function showScope(deps: ProjectDeps, ref: string): Promise<ScopeReport> {
+  const view = await loadView(deps.files);
+  const { item } = resolveArtifact(view, ref);
+  if (item === undefined) throw new CruzeError("not-work", `"${ref}" is not a feature or change; show takes a feature or change ID`);
+  const scope = scopeView(view, item);
+  const dispositions = (await listEvents(deps, "disposition", scope.feature ?? item.ref, true)).map((entry) => ({
+    finding: String(entry["finding"] ?? ""),
+    disposition: String(entry["disposition"] ?? ""),
+    reason: String(entry["reason"] ?? ""),
+    review: String(entry["review"] ?? ""),
+  }));
+  return { ...scope, dispositions };
+}

package/src/domain/check/budget_text.ts

@@ -0,0 +1,24 @@
+/**
+ * The part of a source file its budgets measure. Budgets apply to source, not tests, so a Rust
+ * file's `#[cfg(test)]` modules are left out: rustfmt closes a top-level module with `}` in column 0.
+ */
+export function budgetedText(path: string, text: string): string {
+  if (!path.endsWith(".rs")) return text;
+  const lines = text.split("\n");
+  const kept: string[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const item = lines[i + 1] ?? "";
+    if (lines[i]?.trim() !== "#[cfg(test)]" || !/^(?:pub(?:\([^)]*\))?\s+)?mod\s+\w+\s*[{;]/.test(item)) {
+      kept.push(lines[i] ?? "");
+      continue;
+    }
+    if (item.trimEnd().endsWith(";")) {
+      i += 1;
+      continue;
+    }
+    let end = i + 2;
+    while (end < lines.length && lines[end] !== "}") end++;
+    i = end;
+  }
+  return kept.join("\n");
+}

package/src/domain/check/check_source.ts

@@ -1,5 +1,6 @@
 import type { CruzeConfig, Layer } from "../config.ts";
 import { matchesAny } from "../glob.ts";
+import { budgetedText } from "./budget_text.ts";
 import { importsOf, resolveImport } from "./imports.ts";
 import { countTypes } from "./type_count.ts";
 
@@ -50,11 +51,13 @@ export function checkSource(input: CheckInput): CheckFinding[] {
       }
     }
     const excepted = config.check.exceptions.some((exception) => exception.path === path);
-    const lines = text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+    const budgeted = budgetedText(path, text);
+    const lines = budgeted.split("\n").length - (budgeted.endsWith("\n") ? 1 : 0);
     if (!excepted && lines > config.check.maxLines) {
-      findings.push({ path, rule: "max-lines", severity: "warning", message: `${lines} lines, over the budget of ${config.check.maxLines}; split it by responsibility` });
+      const measured = budgeted === text ? "" : ", not counting its inline tests";
+      findings.push({ path, rule: "max-lines", severity: "warning", message: `${lines} lines${measured}, over the budget of ${config.check.maxLines}; split it by responsibility` });
     }
-    const types = countTypes(path, text);
+    const types = countTypes(path, budgeted);
     if (!excepted && types !== null && types > config.check.maxTypes) {
       findings.push({ path, rule: "max-types", severity: "warning", message: `${types} top-level types, over the budget of ${config.check.maxTypes}` });
     }

package/src/domain/config.ts

@@ -38,9 +38,11 @@ export interface ChangeLimits {
   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 };
+export const DEFAULT_CHANGE_LIMITS: ChangeLimits = { minBuilds: 3, maxScenarios: 30, maxTasks: 25, exceptions: [] };
 
 export interface Layer {
   name: string;
@@ -120,6 +122,14 @@ export function parseConfig(text: string): ConfigResult {
     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 config: CruzeConfig = {

package/src/domain/journal.ts

@@ -26,14 +26,14 @@ const OPTIONAL_FIELDS: Record<string, string[]> = {
 };
 
 /** The workflow steps and checks that find or miss a problem, so a retro can count them. */
-export const STEPS = ["envision", "architect", "research", "design-review", "walkthrough", "plan", "plan-review", "build", "code-review", "verify", "land", "realign", "validate", "check", "user"];
+export const STEPS = ["envision", "architect", "research", "design-review", "walkthrough", "plan", "plan-review", "build", "code-review", "verify", "land", "realign", "improve", "validate", "check", "user"];
 
 export const FIELD_VALUES: Record<string, string[]> = {
   level: ["task", "change", "feature", "architecture", "vision"],
   kind: ["defect", "discovery"],
   disposition: ["fixed", "waived", "deferred", "rejected"],
   decided: ["agent", "user"],
-  review: ["design", "plan", "code", "realign"],
+  review: ["design", "plan", "code", "realign", "improve"],
   result: ["accepted", "sent-back"],
   checked_by: ["agent", "reviewer"],
   found_by: STEPS,

package/src/domain/project/scope_view.ts

@@ -0,0 +1,118 @@
+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, then of the change. */
+  decisions: 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 = 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 = feature === undefined ? decisionLines(item.doc) : [...decisionLines(feature.doc), ...decisionLines(item.doc)];
+  const result: ScopeView = { ref: item.ref, kind: item.kind, elements, scenarios, cited, decisions, missing };
+  if (feature !== undefined) result.feature = feature.ref;
+  return result;
+}
+
+/** 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/status/work_status.ts

@@ -1,7 +1,7 @@
 import { evaluateApproval, type ApprovalStatus } from "../approvals/evaluate.ts";
 import { PATHS } from "../project/layout.ts";
 import { readDelta } from "../project/deltas.ts";
-import { readScope } from "../project/plan_parts.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";
@@ -80,12 +80,23 @@ export function buildGateReasons(view: ProjectView, branch: string | null): stri
   const feature = featureOf(view.items, change);
   if (feature !== undefined) required.push(feature.path);
   if (view.snapshot.has(PATHS.architecture)) required.push(PATHS.architecture);
-  return required.flatMap((path) => {
+  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}`];
   });
+  return [...approvals, ...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. */

package/src/domain/validation/element_rules.ts

@@ -18,7 +18,7 @@ const REQUIRED_FACTS: Partial<Record<Kind, string[]>> = {
 const ALLOWED_VALUES: Record<string, { kinds: Kind[]; values: string[] }> = {
   Kind: { kinds: ["ENT"], values: ["aggregate", "entity", "value", "service", "policy", "event"] },
   Direction: { kinds: ["PORT"], values: ["driven", "driving"] },
-  Layer: { kinds: ["MOD"], values: ["domain", "application", "adapter", "composition"] },
+  Layer: { kinds: ["MOD"], values: ["core", "domain", "application", "adapter", "composition"] },
 };
 
 export function elementProblems(path: string, doc: MarkdownDoc, element: Element): Problem[] {
@@ -41,6 +41,11 @@ export function elementProblems(path: string, doc: MarkdownDoc, element: Element
       problems.push(error(path, element.start, "fact-value", `${element.id} ${key} must be one of ${rule.values.join(", ")}`));
     }
   }
+  if (element.kind === "MOD") {
+    for (const glob of (facts.get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? "")).filter((p) => /[*?[{]/.test(p))) {
+      problems.push(error(path, element.start, "module-path-glob", `${element.id} Path \`${glob}\` is a glob, which matches no file; name a directory ending in / or a single file, one per Path value`));
+    }
+  }
   const module = facts.get("Module")?.[0];
   if (module !== undefined && !findIds(module).some((id) => id.startsWith("MOD-"))) {
     problems.push(error(path, element.start, "fact-value", `${element.id} Module must name a MOD element`));

package/src/domain/validation/size_rules.ts

@@ -12,17 +12,25 @@ export function changeLimits(view: ProjectView): ChangeLimits {
   return view.config?.config?.changes ?? DEFAULT_CHANGE_LIMITS;
 }
 
+/** The rules a size warning comes from. An item stays outside the band only with the user's recorded acceptance. */
+export const SIZE_RULES = ["feature-size", "change-too-small", "change-too-large", "plan-too-large"];
+
+/** Whether the user accepted this feature or change outside the band, under `changes.exceptions`. */
+export function sizeAccepted(view: ProjectView, ref: string): boolean {
+  return changeLimits(view).exceptions.some((exception) => exception.item === ref);
+}
+
 /** A feature's changes not yet landed that fall outside the size band. A feature of one change has nothing to merge into. */
-export function changeRowSizeProblems(view: ProjectView, path: string, rows: ChangeRow[], landed: Set<string>): Problem[] {
+export function changeRowSizeProblems(view: ProjectView, feature: { path: string; ref: string }, rows: ChangeRow[], landed: Set<string>): Problem[] {
   const limits = changeLimits(view);
   const problems: Problem[] = [];
-  for (const row of rows.filter((r) => !landed.has(r.change))) {
+  for (const row of rows.filter((r) => !landed.has(r.change) && !sizeAccepted(view, `${feature.ref}/${r.change}`))) {
     if (rows.length > 1 && row.builds.length < limits.minBuilds) {
-      problems.push(warning(path, row.line, "change-too-small", `${row.change} builds ${row.builds.length} element(s), under ${limits.minBuilds}; merge it into the change it continues, since each change pays for its own plan, review and verify`));
+      problems.push(warning(feature.path, row.line, "change-too-small", `${row.change} builds ${row.builds.length} element(s), under ${limits.minBuilds}; merge it into the change it continues, since each change pays for its own plan, review and verify`));
     }
     const scenarios = row.delivers.filter((id) => kindOf(id) === "SCN").length;
     if (scenarios > limits.maxScenarios) {
-      problems.push(warning(path, row.line, "change-too-large", `${row.change} delivers ${scenarios} scenarios, over ${limits.maxScenarios}; split it, since one verifier run has to go through them all`));
+      problems.push(warning(feature.path, row.line, "change-too-large", `${row.change} delivers ${scenarios} scenarios, over ${limits.maxScenarios}; split it, since one verifier run has to go through them all`));
     }
   }
   return problems;
@@ -31,6 +39,7 @@ export function changeRowSizeProblems(view: ProjectView, path: string, rows: Cha
 /** A plan with more tasks than one code review and one verify can hold. */
 export function planSizeProblems(view: ProjectView, path: string, tasks: number): Problem[] {
   const { maxTasks } = changeLimits(view);
-  if (tasks <= maxTasks) return [];
+  const ref = view.items.find((item) => item.path === path)?.ref ?? path;
+  if (tasks <= maxTasks || sizeAccepted(view, ref)) return [];
   return [warning(path, undefined, "plan-too-large", `the plan has ${tasks} tasks, over ${maxTasks}; split the change through rethink at feature level`)];
 }