mirror-mind 0.0.1 → 0.33.0

package/ts/src/builder/artifacts/scaffoldState.ts

@@ -0,0 +1,227 @@
+// CR112 — reading a story-package artifact back and saying what it is.
+//
+// Plan and Expand write scaffolds where no file exists and never touch a file that
+// does (CR079). Until CR112 that was the whole story: `build show` said present or
+// missing, and no approval read a file, so a scaffold nobody had authored was
+// approvable on both story routes. This module answers the question the surfaces
+// and the approvals need: is this file still the scaffold, and which of its sections
+// are still waiting to be written?
+//
+// The verdict is structural, never a judgement of prose. A section is
+//
+//   * `missing`   -- the file, or the `## ` heading, is not there;
+//   * `unfilled`  -- empty, or holding a line that starts with `pending`, is a
+//                    throwaway token, or matches the placeholder pattern: the rule
+//                    Python's `unfilled_plan_sections_for` applied;
+//   * `scaffold`  -- every non-blank line is one the scaffold would write under this
+//                    heading, with the `{title}` slot wildcarded;
+//   * `authored`  -- anything else. One real line under a heading is authored.
+//
+// `unfilled` is judged before `scaffold`, so a section that holds a `TODO` beside the
+// template is unfilled, not scaffold, and either way not authored.
+//
+// Only `placeholder` sections decide the file's word. A `default` section is a rule
+// the Driver may keep verbatim. For `plan.md` every placeholder heading is required and
+// a missing one counts against the file, as the Plan contract has always required; for
+// `index.md` and `test-guide.md` a missing heading is the Driver's structure, not a
+// scaffold, and only sections that are present and still the scaffold's count.
+//
+// The file's word follows its judged sections: `authored` when nothing is left to
+// write, `partly authored` when some are authored, `scaffold` when none is and the file
+// still carries the scaffold's text, and `incomplete` when none is and none of it is
+// the scaffold's -- a file a person wrote without the sections the contract requires.
+// Calling that file a scaffold would say Ariad wrote what it did not.
+//
+// CR111 D4: for `plan.md` the LIST of sections still to write is what approval would
+// refuse: `PLAN_APPROVAL_SECTIONS`, which adds the two required `default` sections,
+// Non-Goals and the Implementation Contract, while they are missing or empty. Until
+// then `build show` could say `authored` over an approval that refused. The two
+// required defaults lengthen the list; they never decide the word, or an untouched
+// scaffold, whose defaults are filled, would read `partly authored`. Approval reads
+// the same list (`planSectionsToAuthor`), so no surface can disagree with it.
+
+import { existsSync, readFileSync } from "node:fs";
+import { pySplitLines, pyStrip } from "#util/pythonText.ts";
+import {
+  matchesTemplate,
+  PLAN_APPROVAL_SECTIONS,
+  PLAN_SECTIONS,
+  type SectionSpec,
+  STORY_INDEX_SECTIONS,
+  TEST_GUIDE_SECTIONS,
+} from "./scaffoldSections.ts";
+
+export type SectionState = "missing" | "unfilled" | "scaffold" | "authored";
+export type ArtifactState = "missing" | "scaffold" | "incomplete" | "partly_authored" | "authored";
+export type ArtifactName = "index.md" | "plan.md" | "test-guide.md";
+
+/** The state word a surface prints beside an artifact's name. */
+export function describeArtifactState(state: ArtifactState): string {
+  return state === "partly_authored" ? "partly authored" : state;
+}
+
+export interface SectionVerdict {
+  readonly header: string;
+  readonly state: SectionState;
+}
+
+export interface ArtifactVerdict {
+  readonly name: ArtifactName;
+  readonly state: ArtifactState;
+  /** Every placeholder section the reader judged, in the artifact's own order. */
+  readonly sections: readonly SectionVerdict[];
+  /**
+   * The sections still to be written, by their exact `## ` text, in the file's order:
+   * the placeholder sections not authored and, for `plan.md`, the required default
+   * sections missing or empty -- exactly what a Plan approval would refuse on.
+   */
+  readonly toAuthor: readonly string[];
+}
+
+/**
+ * Python `_PLACEHOLDER_LINE_RE`.
+ *
+ * `^(?:[-*]\s+)?(?:this (?:section )?is (?:a )?)?placeholder(?:\b|$)`, case
+ * insensitive. `\s` is Python's, which matches more than JavaScript's — but this
+ * pattern's `\s+` sits between an ASCII bullet and the word, where the two agree.
+ * The `\b` alternative is what keeps "placeholder story" a placeholder while
+ * "placeholders" is not; and the whole point is that it anchors at the START, so
+ * "Do not implement the sibling Payment placeholder story" is product vocabulary,
+ * not an unfilled section.
+ */
+export const PLACEHOLDER_LINE_RE =
+  /^(?:[-*]\s+)?(?:this (?:section )?is (?:a )?)?placeholder(?:\b|$)/i;
+
+const THROWAWAY = new Set(["todo", "tbd", "...", "n/a", "none"]);
+
+/**
+ * Python `_level_two_sections`.
+ *
+ * `setdefault` means a REPEATED `## Scope` heading appends to the first section
+ * rather than replacing it, so a Plan with two Scope headings is complete if either
+ * carries content.
+ */
+export function levelTwoSections(text: string): Map<string, string> {
+  const sections = new Map<string, string[]>();
+  let current: string | null = null;
+  for (const line of pySplitLines(text)) {
+    if (line.startsWith("## ")) {
+      current = pyStrip(line.slice(3));
+      if (!sections.has(current)) sections.set(current, []);
+    } else if (current !== null) {
+      sections.get(current)?.push(line);
+    }
+  }
+  const joined = new Map<string, string>();
+  for (const [header, lines] of sections) joined.set(header, lines.join("\n"));
+  return joined;
+}
+
+/** The unfilled rule, Python's `unfilled_plan_sections_for`, for one section's body. */
+export function isUnfilledBody(body: string): boolean {
+  const stripped = pyStrip(body);
+  if (!stripped) return true;
+  const lines = pySplitLines(stripped)
+    .map((line) => pyStrip(line).toLowerCase())
+    .filter((line) => line !== "");
+  return (
+    lines.some((line) => line.startsWith("pending")) ||
+    lines.some((line) => THROWAWAY.has(line)) ||
+    lines.some((line) => PLACEHOLDER_LINE_RE.test(line))
+  );
+}
+
+/** True when every non-blank line of `body` is a line the scaffold writes for `spec`. */
+export function isScaffoldBody(body: string, spec: SectionSpec): boolean {
+  const lines = pySplitLines(body)
+    .map((line) => pyStrip(line))
+    .filter((line) => line !== "");
+  if (lines.length === 0) return false;
+  return lines.every((line) => spec.lines.some((template) => matchesTemplate(line, template)));
+}
+
+/** The state of one section, given the file's sections. */
+export function sectionState(sections: Map<string, string>, spec: SectionSpec): SectionState {
+  const body = sections.get(spec.header);
+  if (body === undefined) return "missing";
+  if (isUnfilledBody(body)) return "unfilled";
+  if (isScaffoldBody(body, spec)) return "scaffold";
+  return "authored";
+}
+
+const SPECS: Readonly<Record<ArtifactName, readonly SectionSpec[]>> = {
+  "index.md": STORY_INDEX_SECTIONS,
+  "plan.md": PLAN_SECTIONS,
+  "test-guide.md": TEST_GUIDE_SECTIONS,
+};
+
+/**
+ * Which placeholder sections decide `name`. `plan.md` requires every one of its
+ * placeholder headings; the other two judge only the placeholder headings the file
+ * has, so a Driver's own structure is never called a scaffold.
+ */
+function judgedSections(name: ArtifactName, sections: Map<string, string>): SectionSpec[] {
+  const placeholders = SPECS[name].filter((spec) => spec.kind === "placeholder");
+  if (name === "plan.md") return placeholders;
+  return placeholders.filter((spec) => sections.has(spec.header));
+}
+
+/** The `PLAN_SECTIONS` entry for `header`; a heading the table lacks is a default. */
+function planSpec(header: string): SectionSpec {
+  return (
+    PLAN_SECTIONS.find((candidate) => candidate.header === header) ?? {
+      header,
+      kind: "default",
+      lines: [],
+    }
+  );
+}
+
+/** What approval would refuse on in a `plan.md` whose sections are `sections`. */
+function planToAuthor(sections: Map<string, string>): string[] {
+  return PLAN_APPROVAL_SECTIONS.filter(
+    (header) => sectionState(sections, planSpec(header)) !== "authored",
+  );
+}
+
+/** The verdict for artifact text already read; `null` text means the file is missing. */
+export function judgeArtifact(name: ArtifactName, text: string | null): ArtifactVerdict {
+  if (text === null) return { name, state: "missing", sections: [], toAuthor: [] };
+  const sections = levelTwoSections(text);
+  const verdicts = judgedSections(name, sections).map((spec) => ({
+    header: spec.header,
+    state: sectionState(sections, spec),
+  }));
+  const toAuthor =
+    name === "plan.md"
+      ? planToAuthor(sections)
+      : verdicts.filter((verdict) => verdict.state !== "authored").map((verdict) => verdict.header);
+  // The word comes from the placeholder sections alone (D4): the required defaults
+  // lengthen the list, never turn a scaffold into a partly authored file.
+  const state: ArtifactState =
+    toAuthor.length === 0
+      ? "authored"
+      : verdicts.some((verdict) => verdict.state === "authored")
+        ? "partly_authored"
+        : verdicts.some((verdict) => verdict.state === "scaffold")
+          ? "scaffold"
+          : "incomplete";
+  return { name, state, sections: verdicts, toAuthor };
+}
+
+/** The verdict for the artifact at `path`. */
+export function artifactState(name: ArtifactName, path: string): ArtifactVerdict {
+  if (!existsSync(path)) return judgeArtifact(name, null);
+  return judgeArtifact(name, readFileSync(path, "utf8"));
+}
+
+/**
+ * The sections of `plan.md` a Plan approval must see authored, on either route: the
+ * `toAuthor` list `build show` and the Plan checkpoint print for the same file (CR111
+ * D4). A missing file, or no file to read, leaves every one of them to write, which is
+ * what makes a receipt unusable before the Driver writes the Plan.
+ */
+export function planSectionsToAuthor(planPath: string | null): string[] {
+  if (planPath === null || !existsSync(planPath)) return [...PLAN_APPROVAL_SECTIONS];
+  return [...judgeArtifact("plan.md", readFileSync(planPath, "utf8")).toAuthor];
+}

package/ts/src/builder/artifacts/storyFiles.ts

@@ -0,0 +1,61 @@
+// CR111 — the Plan-stage story files, judged and rendered once for every surface that
+// names them.
+//
+// `build show` lists a story package's `index.md`, `plan.md`, and `test-guide.md`, each
+// with its state and, while it is not authored, the sections still to write (CR112).
+// The Plan checkpoint names the same three files the same way. Both import these lines
+// from here, so the two surfaces cannot say different things about one file: the card
+// does not reach into `build show`'s module, and neither keeps its own copy.
+//
+// The glyph carries only done or not; the word carries the state.
+
+import { join } from "node:path";
+import { CARD_WIDTH, cardText } from "../card.ts";
+import { type ArtifactVerdict, artifactState, describeArtifactState } from "./scaffoldState.ts";
+
+/** The artifacts Plan and Expand scaffold, in the order Plan writes them. */
+export const PLAN_STAGE_ARTIFACTS = ["index.md", "plan.md", "test-guide.md"] as const;
+
+/** The Plan-stage files of the package at `directory`, judged, in `PLAN_STAGE_ARTIFACTS` order. */
+export function judgeStoryFiles(directory: string): ArtifactVerdict[] {
+  return PLAN_STAGE_ARTIFACTS.map((name) => artifactState(name, join(directory, name)));
+}
+
+const TO_AUTHOR = "to author: ";
+const TO_AUTHOR_INDENT = "  ";
+
+/**
+ * The sections still to write, wrapped BETWEEN headings, never inside one, with every
+ * row after the first starting under the first heading. A heading cut in two reads as
+ * two items: the first render printed `Navigator` over `Validation` (CR112's handoff
+ * review). The headings are the scaffold tables' own, all far shorter than a row.
+ */
+export function toAuthorLines(headers: readonly string[]): string[] {
+  const width = CARD_WIDTH - TO_AUTHOR_INDENT.length - TO_AUTHOR.length;
+  const rows: string[] = [];
+  let row = "";
+  headers.forEach((header, index) => {
+    const item = index < headers.length - 1 ? `${header},` : header;
+    const joined = row === "" ? item : `${row} ${item}`;
+    if (row !== "" && joined.length > width) {
+      rows.push(row);
+      row = item;
+    } else {
+      row = joined;
+    }
+  });
+  if (row !== "") rows.push(row);
+  const hanging = " ".repeat(TO_AUTHOR.length);
+  return rows.map((text, index) =>
+    cardText(`${TO_AUTHOR_INDENT}${index === 0 ? TO_AUTHOR : hanging}${text}`),
+  );
+}
+
+/** One file's card rows: its glyph, name, and state, then the sections still to write. */
+export function storyFileLines(verdict: ArtifactVerdict): string[] {
+  const glyph = verdict.state === "authored" ? "✓" : "○";
+  return [
+    cardText(`${glyph} ${verdict.name} — ${describeArtifactState(verdict.state)}`),
+    ...toAuthorLines(verdict.toAuthor),
+  ];
+}

package/ts/src/builder/artifacts/storyIndex.ts

@@ -0,0 +1,166 @@
+// CV22.DS7.US8 plateau 3 — the story-package `index.md` scaffolds Expand writes.
+//
+// Port of the `_render_*_index` half of `src/memory/builder/lifecycle.py`.
+//
+// These bodies are written into the Navigator's repository and then read by
+// humans, by `resolve_story_directory` (which locates a package by the heading
+// these render), and by Expand's own candidate-table parser. So they are graded as
+// bytes, not as structure: a changed dash, a dropped blank line, or a `—` turned
+// into `--` moves a heading out of the grammar that finds it again.
+//
+// The Delivery Story scaffold is the one that closes the loop: it emits the
+// canonical five-column candidate table, which is exactly the shape
+// `parseCandidateStories` requires. A port that drifts here produces a package
+// whose own Expand refuses it.
+
+import { tableCell } from "../roadmapGrammar.ts";
+import { storyFolderName } from "../storyPaths.ts";
+import {
+  fill,
+  STORY_OUTCOME,
+  TECHNICAL_STORY_ACCEPTANCE,
+  TECHNICAL_STORY_STATEMENT,
+  USER_STORY_ACCEPTANCE,
+  USER_STORY_STATEMENT,
+} from "./scaffoldSections.ts";
+
+// Every sentence below is a template in `scaffoldSections.ts` (CR112): the reader
+// that tells a scaffold from an authored file matches against the same lines these
+// writers fill, so neither can drift from the other.
+
+function fillLines(lines: readonly string[], title: string): string {
+  return lines.map((line) => fill(line, { title })).join("\n");
+}
+
+/** Python `_user_story_statement`. */
+export function userStoryStatement(title: string): string {
+  return fillLines(USER_STORY_STATEMENT, title);
+}
+
+/** Python `_technical_story_statement`. */
+export function technicalStoryStatement(title: string): string {
+  return fillLines(TECHNICAL_STORY_STATEMENT, title);
+}
+
+/** Python `_user_story_outcome`. */
+export function userStoryOutcome(title: string): string {
+  return fill(STORY_OUTCOME, { title });
+}
+
+/** Python `_render_delivery_story_index`. */
+export function renderDeliveryStoryIndex(
+  code: string,
+  title: string,
+  recommendedCode: string,
+  recommendedTitle: string,
+): string {
+  const link = `${storyFolderName(recommendedCode, recommendedTitle)}/index.md`;
+  return `[< Parent](../index.md)
+
+# ${code} — ${title}
+
+**Status:** 🟡 Planned
+**Type:** Delivery Story
+
+---
+
+## Outcome
+
+${title}
+
+## Candidate Stories
+
+| Code | Story | Type | Outcome | Status |
+|------|-------|------|---------|--------|
+| [${recommendedCode}](${link}) | ${tableCell(recommendedTitle)} | User Story | ${tableCell(userStoryOutcome(recommendedTitle))} | 🟡 Planned |
+
+## Done Condition
+
+The Delivery Story is done when child User/Technical Stories produce a coherent delivery outcome.
+`;
+}
+
+/** Python `_render_technical_story_index`. */
+export function renderTechnicalStoryIndex(code: string, title: string): string {
+  return `[< Parent](../index.md)
+
+# ${code} — ${title}
+
+**Status:** 🟡 Planned
+**Type:** Technical Story
+
+---
+
+## Technical Story
+
+${technicalStoryStatement(title)}
+
+## Outcome
+
+${userStoryOutcome(title)}
+
+## Acceptance Behavior
+
+\`\`\`text
+${fillLines(TECHNICAL_STORY_ACCEPTANCE, title)}
+\`\`\`
+
+## Scope
+
+- ${title}
+
+## Out Of Scope
+
+- Sibling Delivery Story scope.
+
+## Validation
+
+Navigator-visible validation route plus automated checks.
+`;
+}
+
+/** Python `_render_user_story_index`. */
+export function renderUserStoryIndex(code: string, title: string): string {
+  return `[< Parent](../index.md)
+
+# ${code} — ${title}
+
+**Status:** 🟡 Planned
+**Type:** User Story
+
+---
+
+## User Story
+
+${userStoryStatement(title)}
+
+## Outcome
+
+${userStoryOutcome(title)}
+
+## Acceptance Behavior
+
+\`\`\`text
+${fillLines(USER_STORY_ACCEPTANCE, title)}
+\`\`\`
+
+## Scope
+
+- ${title}
+
+## Out Of Scope
+
+- Sibling Delivery Story scope.
+
+## Validation
+
+Navigator-visible validation route plus automated checks.
+`;
+}
+
+/** Python `_render_story_index`: the level chooses the scaffold. */
+export function renderStoryIndex(code: string, title: string, level: string): string {
+  return level === "technical_story"
+    ? renderTechnicalStoryIndex(code, title)
+    : renderUserStoryIndex(code, title);
+}

package/ts/src/builder/cadence.ts

@@ -0,0 +1,59 @@
+// CR115 — the cadence a journey runs at, and the rows that print it.
+//
+// A journey's cadence changes what Plan does: under `accelerated`, Plan records a story
+// preauthorization and the Driver continues into implementation without a Navigator
+// turn. The cursor stores the profile and, for `autonomous`, its limits, and only the
+// cursor sync report printed them, when the cadence was being changed. Every surface
+// that orients the Navigator now prints them, from this module: the Builder resume and
+// `build show` in their label-and-value pairs, the Builder orientation in its own rows.
+//
+// A cursor that stores no profile runs `stepwise`. The sync report and
+// `continue-lifecycle` each held that default before; they read it here now.
+//
+// This module reads two fields and declares them itself, so it imports nothing from the
+// cursor's persistence module, which imports it.
+
+import { cardText, cardWrapped } from "./card.ts";
+
+const FRAME_BLANK = cardText("");
+
+/** The cursor fields the cadence is read from. */
+export interface CadenceView {
+  readonly cadenceProfile: string | null;
+  readonly cadenceLimits: readonly string[];
+}
+
+/** The profile the runtime applies: a cursor that stores none runs `stepwise`. */
+export function effectiveCadenceProfile(cursor: CadenceView): string {
+  return cursor.cadenceProfile || "stepwise";
+}
+
+/**
+ * The limits as one line, or `none`. They bound continuation only under `autonomous`,
+ * so only that profile prints them: a limit stored beside another profile bounds
+ * nothing, and printing it would say it did.
+ */
+function limitsUnder(cursor: CadenceView): string | null {
+  if (effectiveCadenceProfile(cursor) !== "autonomous") return null;
+  return cursor.cadenceLimits.length > 0 ? cursor.cadenceLimits.join(", ") : "none";
+}
+
+/**
+ * The resume's and `build show`'s rows: `cadence profile` and the profile, and under
+ * `autonomous`, `cadence limits` and the limits. With no cursor there is no cadence.
+ */
+export function cadenceCardLines(cursor: CadenceView | null): string[] {
+  if (cursor === null) return [cardText("cadence profile"), cardText("none")];
+  const lines = [cardText("cadence profile"), cardText(effectiveCadenceProfile(cursor))];
+  const limits = limitsUnder(cursor);
+  if (limits !== null) lines.push(FRAME_BLANK, cardText("cadence limits"), ...cardWrapped(limits));
+  return lines;
+}
+
+/** The orientation's rows, in its `label: value` form, as it answers the Refinement question. */
+export function cadenceOrientationLines(cursor: CadenceView): string[] {
+  const lines = cardWrapped(`cadence profile: ${effectiveCadenceProfile(cursor)}`);
+  const limits = limitsUnder(cursor);
+  if (limits !== null) lines.push(...cardWrapped(`cadence limits: ${limits}`));
+  return lines;
+}