@printpractical/cruze 0.0.4 → 0.0.6

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

@@ -35,8 +35,11 @@ export async function runStatus(context: CliContext, _args: string[], options: O
   return { json: report, human: lines.join("\n") };
 }
 
+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 {
-  const detail = status.changed.length > 0 ? ` (${status.changed.join(", ")})` : status.unjournaled === true ? " (no journal entry)" : "";
+  const byAgent = status.state === "approved" ? BASIS[status.record?.basis ?? ""] ?? "" : "";
+  const detail = status.changed.length > 0 ? ` (${status.changed.join(", ")})` : status.unjournaled === true ? " (no journal entry)" : byAgent;
   return `${label}: ${status.state}${detail}`;
 }
 

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

@@ -22,7 +22,11 @@ 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" },
-  approve: { handler: runApprove, options: ["replan", "rebase"], usage: "approve <vision|architecture|roadmap|ref|path> [--replan <ID>...] [--rebase <ID>...]   record your approval of a document" },
+  approve: {
+    handler: runApprove,
+    options: ["replan", "rebase", "by-agent", "restamp-unchanged"],
+    usage: "approve <vision|architecture|roadmap|ref|path> [--replan <ID>...] [--rebase <ID>...] [--by-agent|--restamp-unchanged]   record an approval of a document",
+  },
   new: {
     handler: runNew,
     options: { vision: [], glossary: [], architecture: [], roadmap: [], feature: ["title", "roadmap"], change: ["title", "feature", "roadmap"], adr: ["title"], note: ["title"] },

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

@@ -52,6 +52,8 @@ export function parseCommand(argv: string[]): ParsedCommand {
         rebase: { type: "string", multiple: true, default: [] },
         base: { type: "string" },
         blockers: { type: "string" },
+        "by-agent": { type: "boolean", default: false },
+        "restamp-unchanged": { type: "boolean", default: false },
       },
     });
   } catch (error) {
@@ -74,6 +76,8 @@ export function parseCommand(argv: string[]): ParsedCommand {
     full: values.full,
     replan: values.replan,
     rebase: values.rebase,
+    byAgent: values["by-agent"],
+    restampUnchanged: values["restamp-unchanged"],
     ...optional("name", values.name),
     ...optional("title", values.title),
     ...optional("feature", values.feature),

package/src/app/use_cases/approve_artifact.ts

@@ -1,3 +1,4 @@
+import { requirePlanReviewClosed, requireUnchangedSinceApproval, type AgentBasis } from "../../domain/approvals/agent_approval.ts";
 import { evaluateApproval } from "../../domain/approvals/evaluate.ts";
 import { fingerprint, isApprovable } from "../../domain/approvals/fingerprint.ts";
 import { latestApproval, serializeApprovals, withApproval, type ApprovalRecord } from "../../domain/approvals/records.ts";
@@ -29,6 +30,10 @@ export interface ApproveReport {
   replanned: string[];
   /** Elements whose current living text this feature accepted after a land conflict. */
   rebased: string[];
+  /** Why the agent gave this approval for the user, when it did. */
+  basis?: AgentBasis;
+  /** For a re-stamp: the upstream IDs or documents that had changed. */
+  restamped?: string[];
 }
 
 export interface ApproveOptions {
@@ -36,6 +41,8 @@ export interface ApproveOptions {
   replan?: string[];
   /** Elements this work's delta changes whose living text changed since its last approval; the approval accepts the current text. */
   rebase?: string[];
+  /** Approve for the user: a change whose plan review closed, or work a rethink left unchanged. */
+  agent?: AgentBasis;
 }
 
 /**
@@ -53,6 +60,9 @@ export async function approveArtifact(deps: ProjectDeps, ref: string, options: A
   if (item !== undefined && item.kind !== "feature" && !isPlanned(item.doc)) {
     throw new CruzeError("not-planned", `${path} has no test plan or tasks yet; plan it before approving`);
   }
+  const before = evaluateApproval(view, path);
+  if (options.agent === "plan-review") requirePlanReviewClosed(view.journal, item ?? notWork(path));
+  if (options.agent === "rethink") requireUnchangedSinceApproval(view.journal, item, path, before);
 
   const edits = new Map<string, string>();
   let text = view.snapshot.get(path) ?? "";
@@ -103,12 +113,23 @@ export async function approveArtifact(deps: ProjectDeps, ref: string, options: A
     upstream,
     approvedAt: deps.clock.now().toISOString(),
     by: (await deps.repository.userName()) ?? "unknown",
+    ...(options.agent === undefined ? {} : { basis: options.agent }),
   });
   for (const [changed, content] of edits) await deps.files.writeText(changed, content);
   await deps.files.writeText(approvalsPath(folder), serializeApprovals(approvals));
-  await appendJournal(deps, folder, "approve", { artifact: path, hash, ...(replanned.length > 0 ? { replanned } : {}), ...(rebased.length > 0 ? { rebased } : {}) });
+  const restamped = options.agent === "rethink" ? before.changed : undefined;
+  await appendJournal(deps, folder, "approve", {
+    artifact: path,
+    hash,
+    ...(replanned.length > 0 ? { replanned } : {}),
+    ...(rebased.length > 0 ? { rebased } : {}),
+    ...(options.agent === undefined ? {} : { basis: options.agent }),
+    ...(restamped === undefined ? {} : { restamped }),
+  });
   const report: ApproveReport = { artifact: path, hash, upstream: Object.keys(upstream), stamped, replanned, rebased };
   if (bound !== undefined) report.bound = bound;
+  if (options.agent !== undefined) report.basis = options.agent;
+  if (restamped !== undefined) report.restamped = restamped;
   return report;
 }
 
@@ -133,6 +154,10 @@ function requireRebased(view: ProjectView, deltaIds: Set<string>, previous: Appr
   }
 }
 
+function notWork(path: string): never {
+  throw new CruzeError("needs-user", `${path} is a project document, so the user approves it`);
+}
+
 /** A change needs its feature approved; a feature or standalone change needs the architecture approved. */
 function requireUpstreamApproved(view: ProjectView, path: string): void {
   const item = view.items.find((i) => i.path === path);

package/src/app/use_cases/new_work_item.ts

@@ -28,7 +28,7 @@ export interface NewReport {
 export async function createWorkItem(deps: ProjectDeps, request: NewRequest): Promise<NewReport> {
   const view = await loadView(deps.files);
   const date = deps.clock.today();
-  const values = { id: "", title: request.title, date, project_name: "" };
+  const values = { id: "", title: request.title, title_quoted: JSON.stringify(request.title), date, project_name: "" };
   if (request.title.trim() === "") throw new CruzeError("missing-title", "a title is required");
 
   if (request.kind === "adr") {

package/src/domain/approvals/agent_approval.ts

@@ -0,0 +1,68 @@
+import { CruzeError } from "../cruze_error.ts";
+import type { JournalEntry } from "../journal.ts";
+import type { WorkItem } from "../project/work_items.ts";
+import type { ApprovalStatus } from "./evaluate.ts";
+
+/**
+ * Why an approval was given without the user: a plan whose review closed, or work that a
+ * rethink left unchanged while something it cites moved. The user can still object, and
+ * editing the document makes the approval stale as usual.
+ */
+export type AgentBasis = "plan-review" | "rethink";
+
+const byTime = (a: JournalEntry, b: JournalEntry): number => a.at.localeCompare(b.at);
+
+/**
+ * A feature's change may be approved by the agent once its plan review has closed: a review
+ * recorded since the change was last approved, no blocker left open in its last round, and a
+ * disposition for every finding of its first round. The feature's design, and a standalone
+ * change's, stay the user's to approve.
+ */
+export function requirePlanReviewClosed(journal: JournalEntry[], item: WorkItem): void {
+  if (item.kind !== "change") {
+    throw new CruzeError("needs-user", `${item.ref} carries design, so the user approves it; only a feature's change can be approved after its plan review`);
+  }
+  const entries = journal.filter((e) => e["item"] === item.ref || e["artifact"] === item.path).sort(byTime);
+  const lastApproval = entries.filter((e) => e.event === "approve").at(-1);
+  const reviews = entries.filter((e) => e.event === "review" && e["review"] === "plan" && (lastApproval === undefined || e.at > lastApproval.at));
+  const last = reviews.at(-1);
+  if (last === undefined) {
+    const since = lastApproval === undefined ? "" : " since the change was last approved";
+    throw new CruzeError("plan-review-open", `no plan review is recorded for ${item.ref}${since}; run the plan review first`);
+  }
+  const blockers = Number(last["blockers"] ?? 0);
+  if (blockers > 0 && Number(last["round"]) === 1) {
+    throw new CruzeError("plan-review-open", `the plan review's round 1 found ${blockers} blocker(s); check their fixes in round 2`);
+  }
+  if (blockers > 0) {
+    throw new CruzeError("plan-review-open", `round 2 left ${blockers} blocker(s) open; the user decides them and approves the plan`);
+  }
+  const first = reviews.filter((e) => Number(e["round"]) === 1).at(-1) ?? last;
+  const findings = Number(first["blockers"] ?? 0) + Number(first["concerns"] ?? 0);
+  const decided = entries.filter((e) => e.event === "disposition" && e["review"] === "plan" && e.at > first.at).length;
+  if (decided < findings) {
+    throw new CruzeError("plan-review-open", `the plan review raised ${findings} finding(s) but ${decided} have a disposition; record one for each`);
+  }
+}
+
+/**
+ * A rethink may re-approve, for the user, a feature or change it didn't edit: one whose own
+ * design is unchanged and that is stale only because something it cites changed. A change
+ * with a task reopened since its approval goes back to the user.
+ */
+export function requireUnchangedSinceApproval(journal: JournalEntry[], item: WorkItem | undefined, path: string, status: ApprovalStatus): void {
+  if (item === undefined) {
+    throw new CruzeError("needs-user", `${path} is a project document, so the user re-approves it; a rethink re-stamps only features and changes`);
+  }
+  if (status.state === "edited") {
+    throw new CruzeError("needs-user", `${item.ref} itself changed since its approval, so the user re-approves it`);
+  }
+  if (status.state !== "upstream-changed") {
+    throw new CruzeError("not-stale", `${item.ref} is ${status.state}; only work whose upstream changed can be re-stamped`);
+  }
+  const approvedAt = journal.filter((e) => e.event === "approve" && e["artifact"] === path).sort(byTime).at(-1)?.at ?? "";
+  const reopened = journal.filter((e) => e.event === "reopen" && e["change"] === item.ref && e.at > approvedAt).map((e) => String(e["task"]));
+  if (reopened.length > 0) {
+    throw new CruzeError("needs-user", `${item.ref} had ${reopened.join(", ")} reopened since its approval, so the user re-approves it`);
+  }
+}

package/src/domain/config.ts

@@ -23,9 +23,25 @@ export interface CruzeConfig {
    * 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[] };
+  review: { command?: string[]; decide: ReviewDecide };
+  /** The size band of a change, so each one is worth its own plan, review and verify. */
+  changes: ChangeLimits;
 }
 
+/** 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;
+}
+
+export const DEFAULT_CHANGE_LIMITS: ChangeLimits = { minBuilds: 3, maxScenarios: 30, maxTasks: 25 };
+
 export interface Layer {
   name: string;
   paths: string[];
@@ -97,6 +113,14 @@ export function parseConfig(text: string): ConfigResult {
   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,
+  };
 
   const config: CruzeConfig = {
     version: 1,
@@ -109,7 +133,11 @@ export function parseConfig(text: string): ConfigResult {
     check: { maxLines: maxLines ?? 250, maxTypes: maxTypes ?? 5, exceptions },
     layers,
     commands,
-    review: reviewCommand === undefined || reviewCommand.length === 0 ? {} : { command: reviewCommand },
+    review: {
+      ...(reviewCommand === undefined || reviewCommand.length === 0 ? {} : { command: reviewCommand }),
+      decide: decide === "all" ? "all" : "exceptions",
+    },
+    changes,
   };
   return { config, problems };
 }

package/src/domain/journal.ts

@@ -15,12 +15,14 @@ export const RECORDED_EVENTS: Record<string, string[]> = {
   override: ["gate", "reason"],
   bug: ["summary", "cause"],
   verification: ["result", "summary"],
+  checks: ["commit"],
 };
 
 /** Fields an event may carry beyond its required ones, checked when present. A defect rethink must say which step missed it. */
 const OPTIONAL_FIELDS: Record<string, string[]> = {
   rethink: ["missed_by"],
-  review: ["nits"],
+  review: ["nits", "checked_by"],
+  disposition: ["decided"],
 };
 
 /** The workflow steps and checks that find or miss a problem, so a retro can count them. */
@@ -30,8 +32,10 @@ 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"],
   result: ["accepted", "sent-back"],
+  checked_by: ["agent", "reviewer"],
   found_by: STEPS,
   missed_by: STEPS,
 };
@@ -77,6 +81,12 @@ export function recordedEventProblems(event: string, fields: Record<string, stri
     if (allowed !== undefined && !allowed.includes(value)) problems.push(`${field} must be one of ${allowed.join(", ")}`);
     if (COUNT_FIELDS.includes(field) && !/^\d+$/.test(value)) problems.push(`${field} must be a whole number`);
   }
+  if (event === "checks" && fields["commit"] !== undefined && !/^[0-9a-f]{7,40}$/.test(fields["commit"])) {
+    problems.push("commit must be a commit hash, such as the output of git rev-parse --short HEAD");
+  }
+  if (event === "disposition" && fields["decided"] === "agent" && fields["disposition"] !== "fixed") {
+    problems.push("the agent decides only fixes; the user waives, defers or rejects a finding (decided=user)");
+  }
   return problems;
 }
 

package/src/domain/status/next_step.ts

@@ -66,7 +66,7 @@ function projectStep(view: ProjectView): NextStep | null {
     {
       path: PATHS.architecture,
       missing: { step: "architect", reason: "the project has no architecture yet" },
-      unapproved: { step: "architect", reason: "finish the architecture, walk through it and approve it" },
+      unapproved: { step: "architect", reason: "finish the architecture, review it and approve it" },
       changed: { step: "rethink", target: "architecture", reason: "the architecture changed since its approval" },
     },
     {
@@ -89,7 +89,7 @@ function itemSteps(view: ProjectView, item: WorkItem, branch: string | null): Ne
   if (item.kind === "standalone") return [changeStep(view, item, branch)];
   const state = evaluateApproval(view, item.path);
   if (readChangesTable(item.doc).length === 0) return [{ step: "architect", target: item.ref, reason: "the feature has no design or changes yet" }];
-  if (state.state === "unapproved") return [{ step: "architect", target: item.ref, reason: "review the feature's design, walk through it and approve it" }];
+  if (state.state === "unapproved") return [{ step: "architect", target: item.ref, reason: "review the feature's design and approve it" }];
   if (state.state !== "approved") return [{ step: "rethink", target: item.ref, reason: `the feature changed since its approval${state.changed.length > 0 ? ` (${state.changed.join(", ")})` : ""}` }];
   const changes = changesOf(view.items, item);
   const landed = new Set(changes.filter((c) => readProgress(c.doc).landed !== undefined).map((c) => c.folderName));

package/src/domain/status/verification.ts

@@ -4,13 +4,14 @@ import type { WorkItem } from "../project/work_items.ts";
 /**
  * Whether the user accepted a change at verify. The latest verification recorded for the change
  * counts. A later approval keeps it only when the change's own design is unchanged, as when it is
- * re-approved because something upstream moved; a changed plan means verifying again.
+ * re-approved because something upstream moved; a changed plan means verifying again. Land's
+ * re-stamps don't count, since they follow the merge; an approval the agent gave does.
  */
 export function isVerified(journal: JournalEntry[], change: WorkItem): boolean {
   const byTime = (a: JournalEntry, b: JournalEntry): number => a.at.localeCompare(b.at);
   const verification = journal.filter((e) => e.event === "verification" && e["item"] === change.ref).sort(byTime).at(-1);
   if (verification?.["result"] !== "accepted") return false;
-  const approvals = journal.filter((e) => e.event === "approve" && e["artifact"] === change.path && e["basis"] === undefined).sort(byTime);
+  const approvals = journal.filter((e) => e.event === "approve" && e["artifact"] === change.path && !String(e["basis"] ?? "").startsWith("land ")).sort(byTime);
   const verifiedHash = approvals.filter((e) => e.at < verification.at).at(-1)?.["hash"];
   return approvals.filter((e) => e.at > verification.at).every((e) => e["hash"] === verifiedHash);
 }

package/src/domain/validation/plan_rules.ts

@@ -7,6 +7,7 @@ import type { Delta } from "../project/deltas.ts";
 import { isPlanned, readScope, readTasks, readTestPlan, type Scope, type Task } from "../project/plan_parts.ts";
 import type { ProjectView } from "../project/project_view.ts";
 import { error, warning, type Problem } from "./problem.ts";
+import { planSizeProblems } from "./size_rules.ts";
 
 const TEST_KINDS = ["behaviour", "contract", "domain", "smoke"];
 
@@ -31,6 +32,7 @@ export function changePlanProblems(
     problems.push(error(path, line, "task-format", "task lines read: - T<n>: `<owner>` in `<path>`[, `<path>`], proves <ID>[, <ID>]"));
   }
   if (tasks.length === 0 && malformed.length === 0) problems.push(error(path, undefined, "missing-tasks", "the change has no tasks"));
+  problems.push(...planSizeProblems(view, path, tasks.length));
 
   const proved = new Set(tasks.flatMap((task) => task.proves));
   const taskPaths = tasks.flatMap((task) => task.paths);

package/src/domain/validation/size_rules.ts

@@ -0,0 +1,36 @@
+import { DEFAULT_CHANGE_LIMITS, type ChangeLimits } from "../config.ts";
+import { kindOf } from "../ids.ts";
+import type { ChangeRow } from "../project/plan_parts.ts";
+import type { ProjectView } from "../project/project_view.ts";
+import { warning, type Problem } from "./problem.ts";
+
+/**
+ * Every change pays for its own plan review, code review, verifier run and land, so a change
+ * should carry enough work to be worth them, and no more than one review and one run can hold.
+ */
+export function changeLimits(view: ProjectView): ChangeLimits {
+  return view.config?.config?.changes ?? DEFAULT_CHANGE_LIMITS;
+}
+
+/** 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[] {
+  const limits = changeLimits(view);
+  const problems: Problem[] = [];
+  for (const row of rows.filter((r) => !landed.has(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`));
+    }
+    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`));
+    }
+  }
+  return problems;
+}
+
+/** 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 [];
+  return [warning(path, undefined, "plan-too-large", `the plan has ${tasks} tasks, over ${maxTasks}; split the change through rethink at feature level`)];
+}

package/src/domain/validation/work_item_rules.ts

@@ -11,6 +11,7 @@ import { deltaProblems } from "./delta_rules.ts";
 import { malformedIdHeadings, lineOf } from "./living_rules.ts";
 import { changePlanProblems } from "./plan_rules.ts";
 import { error, warning, type Problem } from "./problem.ts";
+import { changeRowSizeProblems } from "./size_rules.ts";
 
 const REQUIRED_SECTIONS: Record<WorkItem["kind"], string[]> = {
   feature: ["Intent", "Spec delta", "Architecture delta", "Changes"],
@@ -71,6 +72,7 @@ function featureScopeProblems(view: ProjectView, feature: WorkItem, delta: Delta
   if (extra !== undefined) {
     problems.push(warning(feature.path, extra.line, "feature-size", `the feature has ${rows.length} changes, over ${MAX_CHANGES}; split it into features a single design review can hold`));
   }
+  problems.push(...changeRowSizeProblems(view, feature.path, rows, landedChanges));
   for (const row of rows) {
     if (!/^\d\d-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(row.change)) problems.push(error(feature.path, row.line, "change-name", `change "${row.change}" must be named NN-slug`));
     if (names.indexOf(row.change) !== names.lastIndexOf(row.change)) problems.push(error(feature.path, row.line, "change-name", `change ${row.change} is listed twice`));

package/src/domain/versions/rule_versions.ts

@@ -13,6 +13,9 @@ export const RULE_SINCE: Record<string, string> = {
   "validate:outside-module-map": "0.0.2",
   "validate:readme-overview": "0.0.2",
   "validate:feature-size": "0.0.2",
+  "validate:change-too-small": "0.0.5",
+  "validate:change-too-large": "0.0.5",
+  "validate:plan-too-large": "0.0.5",
 };
 
 /** Whether a rule arrived after the version the project's code meets, so it waits for `realign`. */