@printpractical/cruze 0.0.8 → 0.0.10

package/dist/domain/land/merge_plan.js

@@ -1,3 +1,4 @@
+import { settledIds } from "../approvals/rebase.js";
 import { sectionForKind } from "../architecture_sections.js";
 import { CruzeError } from "../cruze_error.js";
 import { setStatus } from "../edits/status_lines.js";
@@ -26,7 +27,8 @@ import { appendBlock, relevel, removeElement, replaceElement } from "./text_ops.
 /**
  * Merges a change's work into the living docs. The first change of a feature to land merges
  * the whole delta; elements it doesn't build arrive as planned, and later changes flip what
- * they build to built. Text is replaced only when nobody else changed it since this work merged it.
+ * they build to built. Text is replaced only when nobody else changed it since this work merged it,
+ * and an element merged and unchanged in the delta since keeps its living text, whoever edited it.
  */
 export function planMerge(view             , change          , source          )            {
   const scope = readScope(change.doc);
@@ -36,6 +38,7 @@ export function planMerge(view             , change          , source          )
   const files = new Map                ();
   const text = (path        )         => files.get(path) ?? view.snapshot.get(path) ?? "";
   const plan            = { files, merged, mergedIds: [], built: [], removed: [] };
+  const settled = settledIds(source.doc, merged);
 
   for (const op of delta.capabilities) {
     const key = capabilityKey(op.capability);
@@ -56,8 +59,10 @@ export function planMerge(view             , change          , source          )
       }
       continue;
     }
-    mergeEntry(view, source, entry, path, text, files, merged, plan);
+    const kept = settled.has(id) && view.living.elements.has(id);
+    if (!kept) mergeEntry(view, source, entry, path, text, files, merged, plan);
     for (const target of [entry.element, ...entry.scenarios].filter((e) => STATUS_KINDS.includes(e.kind))) {
+      if (kept && !inScope.has(target.id)) continue;
       files.set(path, setStatus(text(path), target.id, statusAfterMerge(view, source, target, inScope)));
       if (inScope.has(target.id)) plan.built.push(target.id);
     }

package/dist/domain/line_diff.js

@@ -0,0 +1,56 @@
+/**
+ * A line diff of two texts as unified-diff lines: "  " for a kept line, "- " removed, "+ " added.
+ * Only the changes and `context` kept lines around each are shown; "…" marks the lines left out.
+ */
+export function lineDiff(before          , after          , context = 2)           {
+  const ops = diffOps(before, after);
+  const near = new Set        ();
+  ops.forEach((op, i) => {
+    if (op.kind === " ") return;
+    for (let j = Math.max(0, i - context); j <= Math.min(ops.length - 1, i + context); j++) near.add(j);
+  });
+  const lines           = [];
+  let skipped = false;
+  ops.forEach((op, i) => {
+    if (!near.has(i)) {
+      skipped = true;
+      return;
+    }
+    if (skipped && lines.length > 0) lines.push("…");
+    skipped = false;
+    lines.push(`${op.kind} ${op.line}`);
+  });
+  if (skipped && lines.length > 0) lines.push("…");
+  return lines;
+}
+
+              
+                        
+               
+ 
+
+/** The edit script of a longest common subsequence: documents are small enough for the quadratic table. */
+function diffOps(a          , b          )       {
+  const width = b.length + 1;
+  const table = new Int32Array((a.length + 1) * width);
+  const at = (i        , j        )         => table[i * width + j] ?? 0;
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      table[i * width + j] = a[i] === b[j] ? at(i + 1, j + 1) + 1 : Math.max(at(i + 1, j), at(i, j + 1));
+    }
+  }
+  const ops       = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length || j < b.length) {
+    if (i < a.length && j < b.length && a[i] === b[j]) {
+      ops.push({ kind: " ", line: a[i++] ?? "" });
+      j++;
+    } else if (j >= b.length || (i < a.length && at(i + 1, j) >= at(i, j + 1))) {
+      ops.push({ kind: "-", line: a[i++] ?? "" });
+    } else {
+      ops.push({ kind: "+", line: b[j++] ?? "" });
+    }
+  }
+  return ops;
+}

package/dist/domain/project/element_lookup.js

@@ -0,0 +1,124 @@
+import { elementLines, factsOf, statusOf,                                         } from "../elements.js";
+import { findIds, kindOf, scopeOf,           } from "../ids.js";
+                                                  
+import { readDelta } from "./deltas.js";
+import { PATHS } from "./layout.js";
+                                                     
+                                                    
+                                                
+
+/**
+ * Elements one at a time, and an index of all of them, so a step that needs a few elements of a
+ * large architecture fetches those instead of reading the whole file. One project's architecture
+ * held 52k words, and a single architect run read all of it to find what it would extend.
+ */
+
+                             
+             
+                
+             
+                                                                          
+                 
+                  
+                                                                           
+                 
+                                                        
+                     
+                                                          
+                      
+                                                        
+                   
+ 
+
+                               
+                                                                                                        
+                                                 
+                        
+ 
+
+const DOCS_INDEXED = (path        )          => path === PATHS.architecture || path.startsWith(`${PATHS.specsDir}/`);
+
+/**
+ * Every element of the living architecture and specs, one entry each, with what in-flight work
+ * adds. Without a scope, scenarios are counted under their requirement; with a context or
+ * capability name, only its elements are listed, scenarios included.
+ */
+export function elementIndex(view             , scope         )               {
+  const inScope = (id        )          => scope === undefined || scopeOf(id) === scope || id === `CTX-${scope}`;
+  const entries               = [];
+  const byId = new Map                    ();
+  for (const living of view.living.elements.values()) {
+    if (!DOCS_INDEXED(living.path) || !inScope(living.id) || (scope === undefined && kindOf(living.id) === "SCN")) continue;
+    const entry = entryOf(living.id, living.element, living.doc, living.path);
+    if (kindOf(living.id) === "REQ") entry.scenarios = scenarioCount(view, living.id);
+    entries.push(entry);
+    byId.set(entry.id, entry);
+  }
+  for (const item of inFlight(view)) {
+    for (const element of deltaElements(item)) {
+      if (!inScope(element.element.id) || (scope === undefined && element.element.kind === "SCN")) continue;
+      const known = byId.get(element.element.id);
+      if (known !== undefined) {
+        known.changedBy.push(item.ref);
+        continue;
+      }
+      const added = { ...entryOf(element.element.id, element.element, item.doc, item.ref), addedBy: item.ref };
+      entries.push(added);
+      byId.set(added.id, added);
+    }
+  }
+  return { words: livingWords(view), entries };
+}
+
+/** The bodies of the named elements: the living one, then each in-flight delta that changes it. */
+export function lookupElements(view             , ids          )                                                  {
+  const elements                 = [];
+  const missing           = [];
+  for (const id of ids) {
+    const found                 = [];
+    const living = view.living.elements.get(id);
+    if (living !== undefined) found.push(shown(living.doc, living.element, living.path));
+    for (const item of inFlight(view)) {
+      const delta = deltaElements(item).find((d) => d.element.id === id);
+      if (delta !== undefined) found.push({ ...shown(item.doc, delta.element, item.path), ...(delta.op === undefined ? {} : { op: delta.op }) });
+    }
+    if (found.length === 0) missing.push(id);
+    elements.push(...found);
+  }
+  return { elements, missing };
+}
+
+function entryOf(id        , element         , doc             , source        )             {
+  const facts = factsOf(doc, element);
+  const place = (facts.get("Module") ?? []).flatMap(findIds)[0] ?? (facts.get("Path") ?? [])[0];
+  const status = statusOf(doc, element);
+  return { id, title: element.title, kind: kindOf(id), source, changedBy: [], ...(status === undefined ? {} : { status }), ...(place === undefined ? {} : { place }) };
+}
+
+function shown(doc             , element         , path        )               {
+  return { id: element.id, title: element.title, source: `${path}:${element.start + 1}`, body: elementLines(doc, element) };
+}
+
+function inFlight(view             )             {
+  return view.items.filter((item) => !item.archived && item.kind !== "change");
+}
+
+/** Each element a work item's delta defines or changes, scenarios under a requirement included. */
+function deltaElements(item          )                                            {
+  return readDelta(item.doc).entries.flatMap((entry) => [
+    { element: entry.element, ...(entry.element.op === undefined ? {} : { op: entry.element.op }) },
+    ...entry.scenarios.map((scenario) => ({ element: scenario })),
+  ]);
+}
+
+function scenarioCount(view             , requirement        )         {
+  const living = view.living.elements.get(requirement);
+  if (living === undefined) return 0;
+  return [...view.living.elements.values()].filter((e) => e.path === living.path && e.id.startsWith("SCN-") && e.element.start > living.element.start && e.element.start < living.element.end).length;
+}
+
+function livingWords(view             )                                          {
+  const words = (path        )         => (view.snapshot.get(path) ?? "").split(/\s+/).filter((w) => w !== "").length;
+  const specs = [...view.living.docs.keys()].filter((path) => path.startsWith(`${PATHS.specsDir}/`));
+  return { architecture: words(PATHS.architecture), specs: specs.reduce((sum, path) => sum + words(path), 0) };
+}

package/dist/domain/project/living_model.js

@@ -1,4 +1,5 @@
 import { headingElements, rowElements,              } from "../elements.js";
+import { VISION_KINDS } from "../ids.js";
 import { parseMarkdown,                  } from "../markdown.js";
 import { PATHS, childFiles,               } from "./layout.js";
 
@@ -49,6 +50,6 @@ function elementsOf(path        , doc             )            {
   if (path.startsWith(`${PATHS.adrDir}/`)) {
     return [{ id: adrId(path), kind: "ADR", title: doc.headings[0]?.text ?? "", form: "heading", level: 1, start: 0, end: doc.lines.length }];
   }
-  if (path === PATHS.vision) return rowElements(doc).filter((element) => element.kind === "GOAL");
+  if (path === PATHS.vision) return rowElements(doc).filter((element) => VISION_KINDS.includes(element.kind));
   return headingElements(doc);
 }

package/dist/domain/project/notes.js

@@ -0,0 +1,74 @@
+import { findSection, parseMarkdown } from "../markdown.js";
+import { tablesIn } from "../markdown_tables.js";
+import { PATHS } from "./layout.js";
+                                            
+
+/**
+ * Notes under `.cruze/notes/`: what the user brought, what explore captured, the evidence research
+ * gathered, and the hand-off envision wrote from them. Each says what it is about, so a step reads
+ * the notes for its work rather than guessing from file names: one project held 21 notes, and a
+ * 9,500-word seed whose design sections no step was told to read.
+ */
+
+export const NOTE_KINDS = ["input", "intake", "explore", "research"]         ;
+                                                   
+
+/** The step an intake row hands a part to, besides a feature on the map. */
+export const HANDOFF_STEPS = ["vision", "architect", "roadmap", "user"]         ;
+
+                             
+                                                                
+               
+                                                                                            
+                 
+                                                                                
+                 
+                                                                                                 
+                 
+ 
+
+                       
+               
+                
+                
+                                                                   
+                  
+                        
+ 
+
+export function readNotes(snapshot          )         {
+  return [...snapshot.keys()]
+    .filter((path) => path.startsWith(`${PATHS.notesDir}/`) && path.endsWith(".md"))
+    .sort()
+    .map((path) => readNote(path, snapshot.get(path) ?? ""));
+}
+
+function readNote(path        , text        )       {
+  const doc = parseMarkdown(text);
+  const title = doc.headings.find((h) => h.level === 1)?.text ?? path.slice(path.lastIndexOf("/") + 1, -".md".length);
+  const firstSection = doc.headings.find((h) => h.level === 2)?.line ?? doc.lines.length;
+  const fact = (key        )                     =>
+    doc.lines.slice(0, firstSection).map((line) => new RegExp(`^- ${key}: (.+)$`).exec(line)?.[1]?.trim()).find((v) => v !== undefined);
+  const about = (fact("About") ?? "").split(",").map((a) => a.trim()).filter((a) => a !== "");
+  const kind = fact("Kind");
+  const section = findSection(doc, "Hand-off");
+  const rows = section === null ? [] : (tablesIn(doc.lines, doc.inFence, section.start, section.end)[0]?.rows ?? []);
+  const handoff = rows.map(({ cells }) => ({ part: cells[0] ?? "", source: cells[1] ?? "", goesTo: (cells[2] ?? "").replace(/`/g, ""), status: cells[3] ?? "open" }));
+  return { path, title, about, handoff, ...(kind === undefined ? {} : { kind }) };
+}
+
+                           
+                                                                                        
+                
+                                                                                        
+                                                 
+ 
+
+/** The notes and hand-off rows for a piece of work, named by its targets: `project`, a step, a feature slug or a context. */
+export function notesFor(notes        , targets          )           {
+  const wanted = new Set(targets);
+  return {
+    notes: notes.filter((note) => note.about.some((a) => wanted.has(a))),
+    handoffs: notes.flatMap((note) => note.handoff.filter((row) => wanted.has(row.goesTo)).map((row) => ({ ...row, note: note.path }))),
+  };
+}

package/dist/domain/project/scope_view.js

@@ -36,8 +36,10 @@ import { featureOf,                                  } from "./work_items.js";
                             
                                                                                    
                         
-                                                                  
+                                                                         
                       
+                                                                                       
+                            
                                                                               
                     
  
@@ -66,7 +68,7 @@ export function scopeView(view             , item          )            {
       return [shown];
     });
   const elements = show(wanted.elements);
-  const scenarios = show(wanted.scenarios);
+  const scenarios = withoutRepeatedScenarios(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))
@@ -74,12 +76,26 @@ export function scopeView(view             , item          )            {
       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 };
+  const decisions = decisionLines((feature ?? item).doc);
+  const changeDecisions = feature === undefined ? [] : decisionLines(item.doc);
+  const result            = { ref: item.ref, kind: item.kind, elements, scenarios, cited, decisions, changeDecisions, missing };
   if (feature !== undefined) result.feature = feature.ref;
   return result;
 }
 
+/**
+ * A requirement shown beside its own scenarios keeps only its own text: its body would repeat
+ * each of them, which made up a third of one change's output.
+ */
+function withoutRepeatedScenarios(shown                )                 {
+  const ids = new Set(shown.map((e) => e.id));
+  return shown.map((element) => {
+    if (!element.id.startsWith("REQ-")) return element;
+    const first = element.body.findIndex((line, i) => i > 0 && /^#{2,6} /.test(line) && findIds(line).some((id) => ids.has(id)));
+    return first === -1 ? element : { ...element, body: element.body.slice(0, first) };
+  });
+}
+
 /** A change shows what its scope builds, removes and delivers. */
 function changeIds(change          )                                              {
   const scope = readScope(change.doc);

package/dist/domain/skill_budget.js

@@ -0,0 +1,36 @@
+                                                   
+
+/**
+ * The words one instruction file may hold. A longer file holds material only some runs need, so it
+ * splits by branch, as `docs/contributing/writing-skills.md` says, and each run reads only its part.
+ */
+export const MAX_FILE_WORDS = 2100;
+
+/**
+ * The words agents may read across the whole bundle. Every retro adds rules, and between 0.0.1 and
+ * 0.0.10 the skills grew by half while nothing was removed. Lower this when text is cut. Raising it
+ * is the maintainer's decision, with the reason in the commit that raises it.
+ */
+export const BUNDLE_WORD_BUDGET = 44500;
+
+/** Data the CLI reads or renders, rather than instructions an agent reads. */
+const NOT_INSTRUCTIONS = /(^|\/)(templates|notes)\//;
+
+export function wordCount(text        )         {
+  return text.split(/\s+/).filter((word) => word !== "").length;
+}
+
+/** Instruction files over their limit, and the bundle when it is over its budget. */
+export function budgetProblems(skills              )           {
+  const files = skills.flatMap((skill) =>
+    skill.files.filter((f) => f.path.endsWith(".md") && !NOT_INSTRUCTIONS.test(f.path)).map((f) => ({ path: `${skill.folder}/${f.path}`, words: wordCount(f.text) })),
+  );
+  const problems = files
+    .filter((f) => f.words > MAX_FILE_WORDS)
+    .map((f) => `${f.path}: ${f.words} words, over ${MAX_FILE_WORDS}; move what only some runs need into a sibling file`);
+  const total = files.reduce((sum, f) => sum + f.words, 0);
+  if (total > BUNDLE_WORD_BUDGET) {
+    problems.push(`the skills hold ${total} words, over the budget of ${BUNDLE_WORD_BUDGET}; cut or merge text to make room, or raise the budget with the reason in the commit`);
+  }
+  return problems;
+}

package/dist/domain/status/next_step.js

@@ -1,4 +1,5 @@
-import { evaluateApproval } from "../approvals/evaluate.js";
+import { evaluateApproval,                     } from "../approvals/evaluate.js";
+import { rebaseNeeded } from "../approvals/rebase.js";
 import { PATHS } from "../project/layout.js";
 import { isPlanned, readChangesTable } from "../project/plan_parts.js";
 import { readProgress } from "../project/progress.js";
@@ -7,7 +8,8 @@ import { readRoadmapItems, readRoadmapStatus } from "../project/roadmap.js";
 import { changesOf, featureOf,               } from "../project/work_items.js";
 import { compareVersions } from "../versions/cruze_version.js";
 import { FIRST_RELEASE } from "../versions/rule_versions.js";
-import { isVerified } from "./verification.js";
+import { pendingReason, pendingRethinks } from "./pending_rethink.js";
+import { awaitsRethink, isVerified } from "./verification.js";
 import { activeChange } from "./work_status.js";
 
 /** The Cruze step to run next, computed from the project's state and the current branch. */
@@ -31,7 +33,7 @@ export function nextSteps(view             , branch               )
   const project = projectStep(view);
   if (project !== null) return { next: project, also: [] };
   const active = activeChange(view, branch);
-  const inFlight = view.items.filter((item) => !item.archived && item.kind !== "change").flatMap((item) => itemSteps(view, item, branch));
+  const inFlight = inRoadmapOrder(view, view.items.filter((item) => !item.archived && item.kind !== "change")).flatMap((item) => itemSteps(view, item, branch));
   const roadmap = roadmapStep(view);
   const realign = realignStep(view);
   const candidates = [
@@ -45,6 +47,28 @@ export function nextSteps(view             , branch               )
   return { next: next ?? { step: "roadmap", reason: "every item on the roadmap has landed; close the release and plan the next" }, also };
 }
 
+/**
+ * Work in flight in the roadmap's order, with items whose roadmap blockers haven't all landed
+ * last: a feature designed early still waits for the prefactors the user put before it.
+ */
+function inRoadmapOrder(view             , items            )             {
+  const text = view.snapshot.get(PATHS.roadmap);
+  if (text === undefined) return items;
+  const rows = readRoadmapStatus(text);
+  const state = new Map(rows.map((row) => [row.slug, row.state]));
+  const slugOf = new Map(rows.map((row) => [row.id, row.slug]));
+  const roadmap = readRoadmapItems(text);
+  const rank = (item          )                   => {
+    const at = roadmap.findIndex((r) => r.slug === slugOf.get(item.ref));
+    const blocked = at !== -1 && (roadmap[at]?.blockedBy ?? []).some((b) => state.get(b) !== "landed");
+    return [blocked ? 1 : 0, at === -1 ? roadmap.length : at];
+  };
+  return items
+    .map((item, i) => ({ item, key: [...rank(item), i] }))
+    .sort((a, b) => (a.key[0] ?? 0) - (b.key[0] ?? 0) || (a.key[1] ?? 0) - (b.key[1] ?? 0) || (a.key[2] ?? 0) - (b.key[2] ?? 0))
+    .map(({ item }) => item);
+}
+
 /** Realign comes when nothing else is due: the installed skills expect more than the code meets. */
 function realignStep(view             )                  {
   const config = view.config?.config;
@@ -90,7 +114,9 @@ function itemSteps(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 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(", ")})` : ""}` }];
+  if (state.state !== "approved") return [{ step: "rethink", target: item.ref, reason: staleReason(view, item, "the feature", state) }];
+  const pending = pendingRethinks(view.journal, item);
+  if (pending.length > 0) return [{ step: "rethink", target: item.ref, reason: pendingReason(item, pending) }];
   const changes = changesOf(view.items, item);
   const landed = new Set(changes.filter((c) => readProgress(c.doc).landed !== undefined).map((c) => c.folderName));
   const steps             = [];
@@ -109,14 +135,18 @@ function changeStep(view             , change          , branch               )
   const feature = featureOf(view.items, change);
   const featureState = feature === undefined ? undefined : evaluateApproval(view, feature.path);
   if (feature !== undefined && featureState !== undefined && featureState.state !== "approved") {
-    const why = featureState.changed.length > 0 ? ` (${featureState.changed.join(", ")})` : "";
-    return { step: "rethink", target: feature.ref, reason: `the feature of ${change.ref} changed since its approval${why}` };
+    return { step: "rethink", target: feature.ref, reason: staleReason(view, feature, `the feature of ${change.ref}`, featureState) };
+  }
+  for (const part of [feature, change]) {
+    const pending = part === undefined ? [] : pendingRethinks(view.journal, part);
+    if (part !== undefined && pending.length > 0) return { step: "rethink", target: part.ref, reason: pendingReason(part, pending) };
   }
   const bound = readProgress(change.doc).branch;
   const state = evaluateApproval(view, change.path);
   if (!isPlanned(change.doc)) return { step: "plan", target: change.ref, reason: "the change is designed but has no test plan or tasks yet" };
   if (state.state === "unapproved") return { step: "plan", target: change.ref, reason: "review the plan and approve it on the branch that will build it" };
-  if (state.state !== "approved") return { step: "rethink", target: change.ref, reason: `the change or something it cites changed since its approval${state.changed.length > 0 ? ` (${state.changed.join(", ")})` : ""}` };
+  if (state.state !== "approved") return { step: "rethink", target: change.ref, reason: staleReason(view, change, "the change", state) };
+  if (awaitsRethink(view.journal, change, feature)) return { step: "rethink", target: feature?.ref ?? change.ref, reason: `verify sent ${change.ref} back for a design change` };
   if (bound !== undefined && bound !== branch) return { step: "switch-branch", target: bound, reason: `${change.ref} is built on branch ${bound}` };
   const progress = readProgress(change.doc);
   if ([...progress.tasks.values()].some((commit) => commit === null)) return { step: "build", target: change.ref, reason: "the change has open tasks" };
@@ -124,6 +154,21 @@ function changeStep(view             , change          , branch               )
   return { step: "land", target: change.ref, reason: "the change is verified and accepted" };
 }
 
+/**
+ * Why work went stale, and what the rethink will take: a rebase when its delta still changes an
+ * element whose living text moved, or only a check of the diff and a re-stamp when nothing it cites
+ * asks anything of its own text. One project expected a re-stamp and met rebase-required.
+ */
+function staleReason(view             , item          , label        , state                )         {
+  if (state.state === "edited") return `${label} changed since its approval`;
+  const changed = state.changed.join(", ");
+  const rebase = rebaseNeeded(view, item);
+  const then = rebase.length > 0
+    ? `its delta changes ${rebase.join(", ")}, so rebase it, as cruze diff ${item.ref} shows`
+    : `read cruze diff ${item.ref}, and re-stamp it when the work still holds`;
+  return `something ${label} cites changed since its approval (${changed}); ${then}`;
+}
+
 /** The first roadmap item that hasn't started and whose blockers have all landed. */
 function roadmapStep(view             )                  {
   const text = view.snapshot.get(PATHS.roadmap);

package/dist/domain/status/pending_rethink.js

@@ -0,0 +1,22 @@
+                                                  
+                                                         
+
+/**
+ * Findings decided `rethink` for a feature or change that no rethink of it has followed yet.
+ * One project's realign recorded seven design findings on a feature as fixed "by a rethink before
+ * its next change is planned"; nothing showed them, and they surfaced only in a commit message.
+ */
+export function pendingRethinks(journal                , item          )                 {
+  const lastRethink = journal
+    .filter((e) => e.event === "rethink" && e["item"] === item.ref)
+    .map((e) => e.at)
+    .sort()
+    .at(-1);
+  return journal.filter((e) => e.event === "disposition" && e["disposition"] === "rethink" && e["item"] === item.ref && (lastRethink === undefined || e.at > lastRethink));
+}
+
+/** Why work waits on a rethink, naming the first finding. */
+export function pendingReason(item          , pending                )         {
+  const more = pending.length > 1 ? ` and ${pending.length - 1} more` : "";
+  return `${pending.length} finding(s) on ${item.ref} were decided for a rethink that hasn't happened yet: ${String(pending[0]?.["finding"] ?? "")}${more}`;
+}

package/dist/domain/status/verification.js

@@ -15,3 +15,15 @@ export function isVerified(journal                , change          )          {
   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);
 }
+
+/**
+ * Whether verify sent the change back for a rethink that hasn't been recorded yet. Tasks the
+ * agent reopens at verify would otherwise make the change look ready to build again.
+ */
+export function awaitsRethink(journal                , change          , feature                      )          {
+  const verification = journal.filter((e) => e.event === "verification" && e["item"] === change.ref).sort((a, b) => a.at.localeCompare(b.at)).at(-1);
+  if (verification?.["result"] !== "sent-back" || verification["back_to"] !== "rethink") return false;
+  // An architecture-level rethink records no item, and counts too.
+  const refs = new Set([change.ref, feature?.ref, undefined]);
+  return !journal.some((e) => e.event === "rethink" && e.at > verification.at && refs.has(e["item"]                      ));
+}

package/dist/domain/status/work_status.js

@@ -5,6 +5,7 @@ import { readChangesTable, readScope } from "../project/plan_parts.js";
 import { readProgress } from "../project/progress.js";
                                                               
 import { changesOf, featureOf,               } from "../project/work_items.js";
+import { pendingReason, pendingRethinks } from "./pending_rethink.js";
 
                                
               
@@ -15,6 +16,8 @@ import { changesOf, featureOf,               } from "../project/work_items.js";
                      
                                                                  
                   
+                                                                                
+                            
  
 
                                 
@@ -22,6 +25,8 @@ import { changesOf, featureOf,               } from "../project/work_items.js";
                
                            
                           
+                                                                                 
+                            
  
 
                                 
@@ -42,6 +47,7 @@ export function projectStatus(view             , branch               )
       path: feature.path,
       approval: evaluateApproval(view, feature.path),
       changes: changesOf(view.items, feature).map((change) => changeStatus(view, change)),
+      ...withPending(view, feature),
     }));
   const standalone = active.filter((item) => item.kind === "standalone").map((change) => changeStatus(view, change));
   const status                = { documents, features, standalone };
@@ -69,7 +75,12 @@ function changeStatus(view             , change          )               {
   };
   if (progress.branch !== undefined) status.branch = progress.branch;
   if (progress.landed !== undefined) status.landed = progress.landed;
-  return status;
+  return { ...status, ...withPending(view, change) };
+}
+
+function withPending(view             , item          )                                {
+  const pending = pendingRethinks(view.journal, item);
+  return pending.length === 0 ? {} : { rethinkPending: pending.map((e) => String(e["finding"] ?? "")) };
 }
 
 /** Why building may not start on this branch; empty when the build gate passes. */
@@ -86,7 +97,11 @@ export function buildGateReasons(view             , branch               )
     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)];
+  const rethinks = [feature, change].flatMap((part) => {
+    const pending = part === undefined ? [] : pendingRethinks(view.journal, part);
+    return part === undefined || pending.length === 0 ? [] : [`${pendingReason(part, pending)}; run rethink`];
+  });
+  return [...approvals, ...rethinks, ...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. */