@printpractical/cruze 0.0.13 → 0.0.14

package/dist/app/use_cases/run_review.js

@@ -1,20 +1,14 @@
 import { CruzeError } from "../../domain/cruze_error.js";
-import { resolveArtifact } from "../../domain/project/artifact_ref.js";
-import { isPlanned } from "../../domain/project/plan_parts.js";
-import { featureOf,               } from "../../domain/project/work_items.js";
                                                             
-import { loadView,                  } from "../project_context.js";
+import { loadDocs,                  } from "../project_context.js";
 
-export const ROLES = ["design-reviewer", "code-reviewer", "verifier", "researcher", "auditor", "surveyor"]         ;
+export const ROLES = ["code-reviewer", "researcher"]         ;
                                           
 
                                 
                
-                                                                                 
-                
-                 
                                            
-                    
+                
                                                       
                 
  
@@ -30,37 +24,31 @@ export const ROLES = ["design-reviewer", "code-reviewer", "verifier", "researche
 
 /**
  * Runs a Cruze role in a fresh agent context: the role's prompt, what it reviews, and nothing
- * from the conversation that produced the work. Returns the role's report as written, or the
- * prompt to run in a helper when the configured agent isn't installed.
+ * from the conversation that produced the work.
  */
 export async function runReview(deps                                       , request               )                        {
   if (!(ROLES                     ).includes(request.role)) throw new CruzeError("unknown-role", `the roles are ${ROLES.join(", ")}`);
   const role = request.role        ;
-  const view = await loadView(deps.files);
+  const docs = await loadDocs(deps.files);
   const roleText = (await deps.files.readText(`.agents/skills/cruze-roles/${role}.md`)) ?? (await bundledRole(deps, role));
 
-  const context = [`Round: ${request.round ?? 1}`];
+  const context           = [];
   if (request.item !== undefined) {
-    const { path, item } = resolveArtifact(view, request.item);
-    context.push(`Under review: ${item?.ref ?? path} (\`${path}\`)`);
-    const feature = item === undefined ? undefined : featureOf(view.items, item);
-    if (feature !== undefined) context.push(`Its feature: \`${feature.path}\``);
-    if (role === "design-reviewer" && item !== undefined) context.push(rubricLine(item));
-  } else {
-    context.push("Under review: the project documents the role lists for project scope");
+    const feature = docs.features.find((f) => f.slug === request.item);
+    if (feature === undefined) throw new CruzeError("not-found", `no feature ${request.item} in docs/features/`);
+    context.push(`Under review: the feature in \`${feature.path}\``);
   }
   if (request.base !== undefined) context.push(`The changes under review: run \`git diff ${request.base}\`.`);
-  if (request.blockers !== undefined) context.push(`Round-1 blockers to check:\n\n${request.blockers}`);
 
   const prompt = [
     roleText.trim(),
     "## This run",
     "You are running the role above in a fresh context, in the project's repository. Read every input it lists from the files, and run the commands it names. Edit no files. End with the report the role describes.",
-    context.map((line) => `- ${line}`).join("\n"),
+    ...(context.length === 0 ? [] : [context.map((line) => `- ${line}`).join("\n")]),
   ].join("\n\n");
 
   const subject = { role, ...(request.item === undefined ? {} : { item: request.item }) };
-  const command = view.config?.config?.review.command;
+  const command = docs.config?.config?.review.command;
   if (command === undefined) return { ...subject, status: "run-in-helper", instruction: helperInstruction(undefined), prompt };
   const run = await deps.runner.run(command, prompt);
   if (run.kind === "missing") return { ...subject, command, status: "run-in-helper", instruction: helperInstruction(command[0]), prompt };
@@ -84,10 +72,3 @@ async function bundledRole(deps             , role      )                  {
   if (file === undefined) throw new CruzeError("role-missing", `the ${role} role is not installed; run cruze install`);
   return file.text;
 }
-
-/** A design reviewer reads one rubric: the plan rubric for a planned change, the design rubric otherwise. */
-function rubricLine(item          )         {
-  return item.kind !== "feature" && isPlanned(item.doc)
-    ? "This is a change's plan: review it against `.agents/skills/cruze-roles/plan-rubric.md`."
-    : "This is a design: review it against `.agents/skills/cruze-roles/design-rubric.md`.";
-}

package/dist/app/use_cases/validate_project.js

@@ -3,8 +3,8 @@ import { warning,              } from "../../domain/validation/problem.js";
 import { PATHS } from "../../domain/project/layout.js";
 import { versionSkew } from "../../domain/versions/cruze_version.js";
                                                  
-import { loadView } from "../project_context.js";
                                                               
+import { loadDocs } from "../project_context.js";
 
                                  
                  
@@ -15,10 +15,10 @@ import { loadView } from "../project_context.js";
 
 /** Checks every document in the project against the cruze-formats rules, and that its skills match this CLI. */
 export async function validate(deps                                         )                          {
-  const view = await loadView(deps.files);
-  const config = view.config?.config;
+  const docs = await loadDocs(deps.files);
+  const config = docs.config?.config;
   const skew = config === null || config === undefined ? undefined : versionSkew(deps.bundle.version, config.cruze);
-  const problems = [...validateProject(view), ...(skew === undefined ? [] : [warning(PATHS.config, undefined, "cruze-version", skew.message)])];
+  const problems = [...validateProject(docs), ...(skew === undefined ? [] : [warning(PATHS.config, undefined, "cruze-version", skew.message)])];
   return {
     valid: !hasErrors(problems),
     errors: problems.filter((p) => p.severity === "error").length,

package/dist/domain/approvals.js

@@ -0,0 +1,51 @@
+import { designHash } from "./hashing.js";
+                                                 
+import { slugOfFeaturePath } from "./project/layout.js";
+
+/** One approval of one document: the hash of its design content when the user approved it. */
+                                 
+               
+               
+                     
+             
+ 
+
+                                                                 
+
+/** Reads `.cruze/approvals.json`; anything unreadable counts as no approvals, and validate reports it. */
+export function parseApprovals(text                    )                   {
+  if (text === undefined) return [];
+  try {
+    const parsed          = JSON.parse(text);
+    const list = (parsed                           ).approvals;
+    if (!Array.isArray(list)) return [];
+    return list.filter((r)                      => typeof r?.path === "string" && typeof r?.hash === "string" && typeof r?.approvedAt === "string" && typeof r?.by === "string");
+  } catch {
+    return [];
+  }
+}
+
+export function serializeApprovals(records                  )         {
+  const sorted = [...records].sort((a, b) => a.path.localeCompare(b.path));
+  return `${JSON.stringify({ version: 2, approvals: sorted }, null, 2)}\n`;
+}
+
+/** The records with this one replacing any earlier approval of the same document. */
+export function withApproval(records                  , record                )                   {
+  return [...records.filter((r) => r.path !== record.path), record];
+}
+
+/**
+ * The hash an approval records. A feature's `## Decisions` is the agent's record of what it chose,
+ * which build and review add to, so it stays out: the user's approval covers the rest.
+ */
+export function approvalHash(path        , doc             )         {
+  return designHash(doc, slugOfFeaturePath(path) === undefined ? [] : ["Decisions"]);
+}
+
+/** Whether the document still reads as it did when it was approved. */
+export function approvalState(records                           , path        , doc             )                {
+  const record = records.find((r) => r.path === path);
+  if (record === undefined) return "unapproved";
+  return record.hash === approvalHash(path, doc) ? "approved" : "edited";
+}

package/dist/domain/check/check_source.js

@@ -1,36 +1,29 @@
                                                        
 import { matchesAny } from "../glob.js";
 import { budgetedText } from "./budget_text.js";
-import { decisionCitationsInComments } from "./decision_comments.js";
 import { importsOf, resolveImport } from "./imports.js";
 import { countTypes } from "./type_count.js";
 
                                
                
                 
-                                                                                                                         
+                                                                            
                   
                                                                            
                                 
-                                                                                                                              
-                 
  
 
                              
                       
                                                              
                                        
-                                                                                              
-                        
-                                                                                    
-                                      
                                                                                         
                   
  
 
 /** Enforces the architecture's layer rules and the file budgets on source code. */
 export function checkSource(input            )                 {
-  const { config, sources, modulePaths } = input;
+  const { config, sources } = input;
   const all = [...sources.keys()];
   const targets = input.only ?? all;
   const layerOf = (path        )                    => config.layers.find((layer) => matchesAny(path, layer.paths));
@@ -67,32 +60,10 @@ export function checkSource(input            )                 {
     if (!excepted && isRustTestFileInSource(path)) {
       findings.push({ path, rule: "test-placement", severity: "warning", message: "Rust tests that leave their inline module go in the crate's tests/ directory, not under src/" });
     }
-    if (modulePaths.length > 0 && !insideModuleMap(path, modulePaths)) {
-      findings.push({ path, rule: "outside-module-map", severity: "warning", message: "the file is outside every module in the architecture's module map" });
-    }
-    findings.push(...decisionFindings(path, text));
-  }
-  for (const [path, text] of input.tests ?? []) {
-    if (!sources.has(path) && (input.only === undefined || input.only.includes(path))) findings.push(...decisionFindings(path, text));
   }
   return findings;
 }
 
-function decisionFindings(path        , text        )                 {
-  return decisionCitationsInComments(path, text).map((citation) => ({
-    path,
-    line: citation.line + 1,
-    rule: "decision-citation",
-    severity: "warning",
-    message: `the comment cites ${citation.text}, a decision number a reader of the code can't follow; say what was decided, or cite the element or ADR that holds it`,
-  }));
-}
-
-/** Whether a module's Path covers the file: a directory path ending in `/` covers everything under it, any other names one file. */
-export function insideModuleMap(path        , modulePaths          )          {
-  return modulePaths.some((module) => (module.endsWith("/") ? path.startsWith(module) : path === module));
-}
-
 /** A Rust file of tests split out of a module: `tests.rs`, `*_tests.rs`, or anything under a `tests/` folder inside `src/`. */
 function isRustTestFileInSource(path        )          {
   if (!path.endsWith(".rs")) return false;

package/dist/domain/config.js

@@ -5,10 +5,7 @@ import { parse as parseYaml } from "yaml";
              
                                                                                            
                  
-                                                                                         
-                     
                   
-                      
                    
                   
           
@@ -17,34 +14,12 @@ import { parse as parseYaml } from "yaml";
                                                         
     
                   
-                                                                                
-                                   
      
                                                                                           
                                                                                   
      
-                                                       
-                                                                                         
-                        
-                                                                                                                     
-                                                   
+                                 
  
-
-/** Which review findings the user decides: only the exceptions, or every one. */
-                                                
-
-                               
-                                                                                      
-                    
-                                                             
-                       
-                                                 
-                   
-                                                                                               
-                                                      
- 
-
-export const DEFAULT_CHANGE_LIMITS               = { minBuilds: 3, maxScenarios: 30, maxTasks: 25, exceptions: [] };
 
                         
                
@@ -62,17 +37,14 @@ export function parseConfig(text        )               {
   } catch (error) {
     return { config: null, problems: [`not valid YAML: ${error instanceof Error ? error.message : String(error)}`] };
   }
-  const problems           = [];
   const root = asRecord(raw);
   if (root === null) return { config: null, problems: ["the file must be a YAML mapping"] };
-
-  if (root["version"] !== 1) problems.push("version must be 1");
+  if (root["version"] === 1) return { config: null, problems: ["this config was created by an older Cruze, whose documents this release doesn't read; start the project's Cruze documents again with cruze init in a fresh checkout"] };
+  const problems           = [];
+  if (root["version"] !== 2) problems.push("version must be 2");
   const cruze = root["cruze"];
-  if (cruze !== undefined && (typeof cruze !== "string" || cruze.trim() === "")) problems.push("cruze must be a version string, such as \"0.0.2\"");
-  const standards = root["standards"];
-  if (standards !== undefined && (typeof standards !== "string" || standards.trim() === "")) problems.push("standards must be a version string, such as \"0.0.2\"");
+  if (cruze !== undefined && (typeof cruze !== "string" || cruze.trim() === "")) problems.push("cruze must be a version string, such as \"0.0.14\"");
   if (typeof root["project"] !== "string" || root["project"] === "") problems.push("project must be a non-empty string");
-  if (root["tracker"] !== "markdown") problems.push("tracker must be markdown");
   const source = stringList(root["source"], "source", problems);
   const tests = stringList(root["tests"], "tests", problems);
 
@@ -104,71 +76,23 @@ export function parseConfig(text        )               {
     }
   }
 
-  const commands                         = {};
-  const rawCommands = root["commands"];
-  if (rawCommands !== undefined && rawCommands !== null) {
-    const record = asRecord(rawCommands);
-    if (record === null) problems.push("commands must be a mapping of names to commands");
-    for (const [name, command] of Object.entries(record ?? {})) {
-      if (typeof command === "string" && command.trim() !== "") commands[name] = command;
-      else problems.push(`commands.${name} must be a command string`);
-    }
-  }
   const review = asRecord(root["review"]) ?? {};
   const reviewCommand = review["command"] === undefined ? undefined : stringList(review["command"], "review.command", problems);
   if (reviewCommand?.length === 0) problems.push("review.command needs at least the program to run");
-  const decide = review["decide"] ?? "exceptions";
-  if (decide !== "exceptions" && decide !== "all") problems.push("review.decide must be exceptions or all");
-  const limits = asRecord(root["changes"]) ?? {};
-  const changes               = {
-    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 references = (Array.isArray(root["references"]) ? root["references"] : root["references"] === undefined ? [] : [null]).flatMap((entry         , i        ) => {
-    const record = asRecord(entry);
-    if (typeof record?.["path"] !== "string" || record["path"].trim() === "" || typeof record["use"] !== "string" || record["use"].trim() === "") {
-      problems.push(`references[${i}] needs a path and a non-empty use`);
-      return [];
-    }
-    return [{ path: record["path"], use: record["use"] }];
-  });
 
   const config              = {
-    version: 1,
+    version: 2,
     ...(typeof cruze === "string" && cruze.trim() !== "" ? { cruze } : {}),
-    ...(typeof standards === "string" && standards.trim() !== "" ? { standards } : {}),
     project: typeof root["project"] === "string" ? root["project"] : "",
-    tracker: "markdown",
     source,
     tests,
-    check: { maxLines: maxLines ?? 250, maxTypes: maxTypes ?? 5, exceptions },
+    check: { maxLines: maxLines ?? 600, maxTypes: maxTypes ?? 12, exceptions },
     layers,
-    commands,
-    review: {
-      ...(reviewCommand === undefined || reviewCommand.length === 0 ? {} : { command: reviewCommand }),
-      decide: decide === "all" ? "all" : "exceptions",
-    },
-    changes,
-    references,
+    review: reviewCommand === undefined || reviewCommand.length === 0 ? {} : { command: reviewCommand },
   };
   return { config, problems };
 }
 
-/** The first layer whose paths match the file, as the formats define. */
-export function layerOf(config             , path        , matches                                            )                    {
-  return config.layers.find((layer) => matches(path, layer.paths));
-}
-
 function asRecord(value         )                                 {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? (value                           ) : null;
 }

package/dist/domain/hashing.js

@@ -1,43 +1,29 @@
 import { createHash } from "node:crypto";
-import { elementLines, isStatusLine,              } from "./elements.js";
-                                                 
+import { findSection,                  } from "./markdown.js";
 
 /**
- * Hashes cover design content only. Managed blocks and status lines are
- * excluded, so bookkeeping by the CLI never makes a design look edited.
+ * Hashes cover design content only. A feature's `- Status:` line is bookkeeping, so marking a
+ * feature built never makes its approved design look edited.
  */
 
-export function sha256(text        )         {
-  return `sha256:${createHash("sha256").update(text).digest("hex")}`;
-}
+const STATUS_LINE = /^- Status: \S+\s*$/;
 
-/** Hash of a whole document's design content. */
-export function designHash(doc             )         {
-  const kept = doc.lines.filter((line, i) => !doc.inManaged[i] && (doc.inFence[i] || !isStatusLine(line)));
-  return sha256(normalize(kept));
+export function isStatusLine(line        )          {
+  return STATUS_LINE.test(line);
 }
 
-/**
- * Hash of one element, independent of where it sits: heading levels are made
- * relative to the element and a delta operation prefix is dropped, so an element
- * hashes the same in a delta and after it is merged into a living document.
- */
-export function elementHash(doc             , element         )         {
-  if (element.form === "row") return sha256(normalize(elementLines(doc, element)));
-  const kept           = [];
-  for (let i = element.start; i < element.end; i++) {
-    const line = doc.lines[i] ?? "";
-    if (doc.inManaged[i] || (!doc.inFence[i] && isStatusLine(line))) continue;
-    kept.push(doc.inFence[i] ? line : relativeHeading(line, element.level, i === element.start));
-  }
-  return sha256(normalize(kept));
+export function sha256(text        )         {
+  return `sha256:${createHash("sha256").update(text).digest("hex")}`;
 }
 
-function relativeHeading(line        , baseLevel        , isOwnHeading         )         {
-  const match = /^(#{1,6}) (.*)$/.exec(line);
-  if (match?.[1] === undefined || match[2] === undefined) return line;
-  const text = isOwnHeading ? match[2].replace(/^(ADDED|MODIFIED|REMOVED) /, "") : match[2];
-  return `${"#".repeat(match[1].length - baseLevel + 1)} ${text}`;
+/** Hash of a document's design content, leaving out the `##` sections named. */
+export function designHash(doc             , leftOut                    = [])         {
+  const skipped = leftOut.flatMap((title) => {
+    const section = findSection(doc, title);
+    return section === null ? [] : [[section.heading.line, section.end]         ];
+  });
+  const kept = doc.lines.filter((line, i) => !skipped.some(([start, end]) => i >= start && i < end) && (doc.inFence[i] || !isStatusLine(line)));
+  return sha256(normalize(kept));
 }
 
 function normalize(lines          )         {

package/dist/domain/ids.js

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

package/dist/domain/next_step.js

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

package/dist/domain/project/features.js

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