@printpractical/cruze 0.0.6 → 0.0.8

package/README.md

@@ -10,7 +10,7 @@ It works with any agent that supports the [Agent Skills](https://agentskills.io)
 
 ## Status
 
-Version 0.0.6 is the sixth preview. It cuts the waiting per change: the full test suite runs once per commit, with an optional fast tier for the task loop, the design walkthrough is one overview followed by the documents to read in full, the agent checks a review's round 2 when the fixes follow the proposals, and research checks every claim the design relies on. Early development. The CLI is complete for the V1 lifecycle. The document formats ship as the `cruze-formats` skill, the standards an agent designs and codes to ship as knowledge skills, and the whole workflow, from explore to land, ships as workflow skills. Claude Code is the agent tested so far.
+Version 0.0.8 is the eighth preview. It cuts what each step reads and tightens the gates: every step runs in a new session, plan, build and the reviewers read a change's scope through `cruze show` instead of the living docs whole, round 2 of a review is checked by the agent, `cruze approve` refuses a size warning the user hasn't accepted, build waits for the changes it depends on and runs the same check as CI, and neither a file budget nor avoiding a dependency shapes code. Early development. The CLI is complete for the V1 lifecycle. The document formats ship as the `cruze-formats` skill, the standards an agent designs and codes to ship as knowledge skills, and the whole workflow, from explore to land, ships as workflow skills. Claude Code is the agent tested so far.
 
 ## Why
 
@@ -35,7 +35,7 @@ The skills run `cruze` commands, so the agent needs `cruze` on its path. Install
 From a GitHub Release, without npm. Each release attaches the packed package:
 
 ```sh
-npm install -g https://github.com/PrintPractical/cruze/releases/download/v0.0.6/printpractical-cruze-0.0.6.tgz
+npm install -g https://github.com/PrintPractical/cruze/releases/download/v0.0.8/printpractical-cruze-0.0.8.tgz
 ```
 
 From npm, once a version is published there:
@@ -47,7 +47,7 @@ npm install -g @printpractical/cruze
 From the git repository, at a tag or `#main`. This needs git and access to the repository. npm 11 needs `--install-links` for a global git install, and the first `cruze` command builds the CLI, which takes a moment:
 
 ```sh
-npm install -g --install-links github:PrintPractical/cruze#v0.0.6
+npm install -g --install-links github:PrintPractical/cruze#v0.0.8
 ```
 
 ### 2. Set up a repository
@@ -61,7 +61,7 @@ cruze init
 When you didn't install from npm, tell `init` where Cruze came from, so the CI it writes runs the same source instead of the npm package:
 
 ```sh
-cruze init --package https://github.com/PrintPractical/cruze/releases/download/v0.0.6/printpractical-cruze-0.0.6.tgz
+cruze init --package https://github.com/PrintPractical/cruze/releases/download/v0.0.8/printpractical-cruze-0.0.8.tgz
 ```
 
 `init` asks for the project name, and which coding agent you use: `claude` for Claude Code, or `other` for any agent that reads `AGENTS.md` and `.agents/skills/`, such as Codex or OpenCode. It doesn't ask when you pass `--agent claude` or `--agent other`, or when the repository already has `CLAUDE.md` or `.claude/`. With `--yes`, or without a terminal, it sets up Claude Code. Then it creates:
@@ -121,6 +121,7 @@ Skills call these at fixed points, and CI runs `check` and `trace` on every push
 | `cruze validate` | Checks every document against the formats: IDs, elements, deltas, scope rules, task lines, test plans, roadmap and config, and warns when a change falls outside the size band in `changes:` |
 | `cruze approve <doc>` | Records an approval as a fingerprint: the document's design hash plus the hash of every upstream element it cites. `--replan` sets built elements a rethink changed back to planned; `--rebase` accepts living text a feature must now build on. `--by-agent` approves a change for you once its plan review has closed, and `--restamp-unchanged` re-stamps work a rethink didn't change; both record that the agent gave the approval |
 | `cruze next` | Names the step to run next on this branch, and why, from computed status |
+| `cruze show <ref>` | Prints the design a change builds, or a feature's delta: each element's full body, the delivered scenarios, what they cite with where to find it, the settled decisions and the item's dispositions, so a step reads its scope instead of the whole architecture |
 | `cruze status` | Computes each document's state (approved, edited, upstream changed or unapproved) from content, never from stored state |
 | `cruze status --gate build` | Passes only when this branch's change, its feature and the architecture are approved and current |
 | `cruze status --overlap` | Lists changes on other branches that touch the same elements as this branch's change |
@@ -135,7 +136,7 @@ Skills call these at fixed points, and CI runs `check` and `trace` on every push
 | `cruze realign status` | Lists what the installed Cruze expects of existing code since its `standards:` version, with what the CLI rules find now; `--full` covers every release |
 | `cruze realign done` | Moves `standards:` up once every finding is fixed, waived or scheduled in a change named with `--change` |
 | `cruze abandon <ref>` | Archives a feature or standalone change that stops for good, with its reason, and puts a feature back on the future list |
-| `cruze journal add <event>` | Records a rethink, review round, disposition, verification, override or bug; `cruze feedback export` bundles the journal for improving Cruze itself |
+| `cruze journal add <event>` | Records a rethink, review round, disposition, verification, override or bug; `cruze journal list` reads the work in flight's entries, or landed work's too with `--all`; `cruze feedback export` bundles the journal for improving Cruze itself |
 
 Stepping back is editing: change an upstream document and every approval that cites a changed element shows as stale, with the element named. Re-approving is the rewind; there are no phases to reset.
 
@@ -156,10 +157,11 @@ Stepping back is editing: change an upstream document and every approval that ci
 | `cruze-triage` | Reproduces a bug, finds its root cause against the living docs, and fixes it test-first or routes it to architect or rethink |
 | `cruze-rethink` | Steps back to the level a discovery touches, keeps completed work, re-approves what went stale and records why |
 | `cruze-realign` | Brings existing code up to what a new Cruze expects: audits it against each release's notes, decides every finding with you, and schedules the fixes as prefactor changes |
+| `cruze-improve` | Restructures existing code to meet today's standards: surveys it for structure that departs from them or keeps causing friction, lets you pick any or all of the candidates, and schedules the moves as prefactor changes |
 | `cruze-next` | Says which step to run next and why |
-| `cruze-roles` | The fresh-context design reviewer, code reviewer, verifier, researcher and auditor, and how a review runs to a disposition for every finding |
+| `cruze-roles` | The fresh-context design reviewer, code reviewer, verifier, researcher, auditor and surveyor, and how a review runs to a disposition for every finding |
 | `cruze-formats` | The format of every Cruze document, with templates |
-| `cruze-hexagonal-design` | Ports and adapters with domain-driven design: who owns each rule, dependency direction, many small modules, contracts, runtime ownership, and notes for Rust and C++ |
+| `cruze-hexagonal-design` | Ports and adapters with domain-driven design: who owns each rule, dependency direction, many small modules, contracts, runtime ownership, layouts by kind of system, and notes for Rust, Swift and C++ |
 | `cruze-behavioural-testing` | Which tests to write and at which seam, fakes instead of mocks, and protecting approved scenarios' tests |
 | `cruze-grilling` | Interviewing the user in rounds until decisions settle, and challenging once before deferring |
 | `cruze-domain-language` | Building the glossary and using its words in documents, IDs and code |

package/dist/adapters/inbound/cli/commands/journal.js

@@ -15,7 +15,7 @@ export async function runJournal(context            , args          , options
     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/dist/adapters/inbound/cli/commands/show.js

@@ -0,0 +1,27 @@
+import { showScope,                  } from "../../../../app/use_cases/show_scope.js";
+                                                                             
+import { requireArgs,                                     } from "../cli_context.js";
+
+export async function runShow(context            , args          )                         {
+  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             )         {
+  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                )           {
+  if (elements.length === 0) return ["None.", ""];
+  return elements.flatMap((element) => [`<!-- ${element.source} -->`, ...element.body.join("\n").trimEnd().split("\n"), ""]);
+}

package/dist/adapters/inbound/cli/commands/status.js

@@ -32,9 +32,25 @@ export async function runStatus(context            , _args          , options
     }
   }
   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                )                                                                                        {
+  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                         = { "plan-review": " (by the agent, after its plan review)", rethink: " (re-stamped by the agent after a rethink)" };
 
 function describe(label        , status                )         {
@@ -46,6 +62,6 @@ function describe(label        , status                )         {
 export async function runNext(context            )                         {
   const report = await suggestNext(context);
   const describe = (s                                                   )         => `${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/dist/adapters/inbound/cli/commands.js

@@ -7,6 +7,7 @@ import { runRealign } from "./commands/realign.js";
 import { runFeedback, runJournal } from "./commands/journal.js";
 import { runAbandon, runFeatures, runRoadmap, runTask } from "./commands/progress.js";
 import { runReviewCommand } from "./commands/review.js";
+import { runShow } from "./commands/show.js";
 import { runNext, runStatus } from "./commands/status.js";
 
 /** 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                          = {
   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                          = {
   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/dist/app/use_cases/approve_artifact.js

@@ -15,6 +15,8 @@ import { isPlanned, readChangesTable } from "../../domain/project/plan_parts.js"
 import { readProgress } from "../../domain/project/progress.js";
 import { approvalFolder, approvalsPath,                  } from "../../domain/project/project_view.js";
 import { featureOf } from "../../domain/project/work_items.js";
+                                                                  
+import { SIZE_RULES } from "../../domain/validation/size_rules.js";
 import { validateProject } from "../../domain/validation/validate_project.js";
 import { appendJournal, loadView, withFiles,                  } from "../project_context.js";
 
@@ -87,11 +89,13 @@ export async function approveArtifact(deps             , ref        , options
   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             , deltaIds             , previous
   }
 }
 
+/**
+ * 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           , path        )       {
+  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        )        {
   throw new CruzeError("needs-user", `${path} is a project document, so the user approves it`);
 }

package/dist/app/use_cases/check_code.js

@@ -6,6 +6,7 @@ import { FIRST_RELEASE, isPending } from "../../domain/versions/rule_versions.js
                                                           
                                                                         
 import { resolveChange } from "../../domain/project/artifact_ref.js";
+import { readDelta } from "../../domain/project/deltas.js";
 import { activeChange } from "../../domain/status/work_status.js";
 import { traceScenarios,                  } from "../../domain/trace.js";
 import { loadView,                  } from "../project_context.js";
@@ -88,8 +89,14 @@ function globBase(glob        )         {
   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             )           {
-  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/dist/app/use_cases/journal_events.js

@@ -18,16 +18,19 @@ export async function recordEvent(deps             , event        , fields
   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             , event         , item         )                          {
+/**
+ * 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             , event         , item         , all = false)                          {
   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/dist/app/use_cases/run_review.js

@@ -4,7 +4,7 @@ import { featureOf } from "../../domain/project/work_items.js";
                                                             
 import { loadView,                  } from "../project_context.js";
 
-export const ROLES = ["design-reviewer", "code-reviewer", "verifier", "researcher", "auditor"]         ;
+export const ROLES = ["design-reviewer", "code-reviewer", "verifier", "researcher", "auditor", "surveyor"]         ;
                                           
 
                                 

package/dist/app/use_cases/show_scope.js

@@ -0,0 +1,35 @@
+import { CruzeError } from "../../domain/cruze_error.js";
+import { resolveArtifact } from "../../domain/project/artifact_ref.js";
+import { scopeView,                } from "../../domain/project/scope_view.js";
+import { loadView,                  } from "../project_context.js";
+import { listEvents } from "./journal_events.js";
+
+                              
+                  
+                      
+                 
+                 
+ 
+
+                                                
+                                                                                                               
+                              
+ 
+
+/**
+ * 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             , ref        )                       {
+  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/dist/domain/check/budget_text.js

@@ -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        , text        )         {
+  if (!path.endsWith(".rs")) return text;
+  const lines = text.split("\n");
+  const kept           = [];
+  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/dist/domain/check/check_source.js

@@ -1,5 +1,6 @@
                                                        
 import { matchesAny } from "../glob.js";
+import { budgetedText } from "./budget_text.js";
 import { importsOf, resolveImport } from "./imports.js";
 import { countTypes } from "./type_count.js";
 
@@ -50,11 +51,13 @@ export function checkSource(input            )                 {
       }
     }
     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/dist/domain/config.js

@@ -38,9 +38,11 @@ import { parse as parseYaml } from "yaml";
                        
                                                  
                    
+                                                                                               
+                                                      
  
 
-export const DEFAULT_CHANGE_LIMITS               = { minBuilds: 3, maxScenarios: 30, maxTasks: 25 };
+export const DEFAULT_CHANGE_LIMITS               = { minBuilds: 3, maxScenarios: 30, maxTasks: 25, exceptions: [] };
 
                         
                
@@ -120,6 +122,14 @@ export function parseConfig(text        )               {
     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         , i        ) => {
+      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              = {

package/dist/domain/journal.js

@@ -26,14 +26,14 @@ const OPTIONAL_FIELDS                           = {
 };
 
 /** 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                           = {
   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/dist/domain/project/scope_view.js

@@ -0,0 +1,118 @@
+import { elementLines,                            } from "../elements.js";
+import { findIds } from "../ids.js";
+import { findSection,                  } from "../markdown.js";
+import { readDelta } from "./deltas.js";
+import { readScope } from "./plan_parts.js";
+                                                     
+import { featureOf,                                  } from "./work_items.js";
+
+/**
+ * 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 function scopeView(view             , item          )            {
+  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           = [];
+  const show = (ids          )                 =>
+    ids.flatMap((id) => {
+      const found = locate(id);
+      if (found === undefined) {
+        missing.push(id);
+        return [];
+      }
+      const shown               = { 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            = { 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          )                                              {
+  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          )                                              {
+  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             , deltaItem          )                                      {
+  const delta = readDelta(deltaItem.doc);
+  const inDelta = new Map                 ();
+  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             )           {
+  const section = findSection(doc, "Settled decisions");
+  if (section === null) return [];
+  return doc.lines.slice(section.start, section.end).filter((line) => line.startsWith("- "));
+}

package/dist/domain/status/work_status.js

@@ -1,7 +1,7 @@
 import { evaluateApproval,                     } from "../approvals/evaluate.js";
 import { PATHS } from "../project/layout.js";
 import { readDelta } from "../project/deltas.js";
-import { readScope } from "../project/plan_parts.js";
+import { readChangesTable, readScope } from "../project/plan_parts.js";
 import { readProgress } from "../project/progress.js";
                                                               
 import { changesOf, featureOf,               } from "../project/work_items.js";
@@ -80,12 +80,23 @@ export function buildGateReasons(view             , branch               )
   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             , change          , feature                      )           {
+  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/dist/domain/validation/element_rules.js

@@ -18,7 +18,7 @@ const REQUIRED_FACTS                                  = {
 const ALLOWED_VALUES                                                      = {
   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        , doc             , element         )            {
@@ -41,6 +41,11 @@ export function elementProblems(path        , doc             , 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`));