mirror-mind 0.0.1 → 0.33.0

package/ts/src/builder/artifacts/planArtifacts.ts

@@ -0,0 +1,242 @@
+// CV22.DS7.US8 plateau 3 — the three files Plan materializes.
+//
+// Port of `_write_story_package` and its renderers from
+// `src/memory/builder/lifecycle.py`.
+//
+// `writeStoryPackage` is the preservation rule in code: `if not path.exists()`, per
+// FILE, so a package where a Driver authored `plan.md` but not `test-guide.md` gets
+// the guide created and the plan left alone. A port that writes unconditionally
+// destroys authored work silently, in someone else's git history — the worst defect
+// available in this story, and the subject of CR004/CR015/CR079.
+//
+// The generated `plan.md` is also read back by `planSectionsToAuthor`
+// (`scaffoldState.ts`), the rule both approval routes apply, so its `## ` headings
+// are a contract with the approval rule, not decoration: rename one and a freshly
+// scaffolded Plan reads as incomplete forever.
+
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { ContractDefinition } from "../methodDefinition.ts";
+import {
+  existingArtifact,
+  type MaterializedArtifact,
+  materializedArtifact,
+} from "./artifactSurfaces.ts";
+import { requireProjectRoot, writeBuilderArtifact } from "./artifactWriter.ts";
+import { type ArtifactName, artifactState, describeArtifactState } from "./scaffoldState.ts";
+
+/** Python `_markdown_list`: an empty list renders the literal fallback line. */
+export function markdownList(items: readonly string[]): string {
+  return items.length > 0 ? items.map((item) => `- ${item}`).join("\n") : "- None declared.";
+}
+
+import { NAVIGATOR_VALIDATION_GUIDANCE, VALIDATION_EVIDENCE_PENDING } from "./scaffoldSections.ts";
+/** Python `_user_story_statement` / `_technical_story_statement`, shared with Expand. */
+import { technicalStoryStatement, userStoryStatement } from "./storyIndex.ts";
+
+/** The subset of the Plan report these renderers read. */
+export interface PlanArtifactInput {
+  readonly activeItem: string;
+  readonly activeItemTitle: string | null;
+  readonly activeItemLevel: string | null;
+  readonly objective: string;
+  readonly scope: readonly string[];
+  readonly nonGoals: readonly string[];
+  readonly acceptanceBehavior: readonly string[];
+  readonly validationRoute: readonly string[];
+  readonly e2eDecision: string;
+  readonly localRules: readonly string[];
+  readonly implementContract: ContractDefinition;
+  readonly activeCheckpoint: string | null;
+  readonly pendingConfirmation: string | null;
+}
+
+/** Python `_render_story_index_artifact`. */
+export function renderStoryIndexArtifact(report: PlanArtifactInput): string {
+  // `"technical_story".replace("_", " ").title()` -> `Technical Story`; a null level
+  // becomes the literal `Story`.
+  const storyType = (report.activeItemLevel ?? "story")
+    .replaceAll("_", " ")
+    .replace(/\p{L}+/gu, (word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase());
+  const title = report.activeItemTitle ?? report.activeItem;
+  const statement =
+    report.activeItemLevel === "technical_story"
+      ? technicalStoryStatement(title)
+      : userStoryStatement(title);
+  return `[< Parent](../index.md)
+
+# ${report.activeItem} — ${title}
+
+**Status:** 🟡 Planned
+**Type:** ${storyType}
+
+---
+
+## Outcome
+
+${report.objective}
+
+## Story Statement
+
+${statement}
+
+## Acceptance Behavior
+
+\`\`\`text
+${report.acceptanceBehavior.join("\n")}
+\`\`\`
+
+## Scope
+
+${markdownList(report.scope)}
+
+## Out Of Scope
+
+${markdownList(report.nonGoals)}
+
+## Validation
+
+${markdownList(report.validationRoute)}
+
+---
+
+## Artifacts
+
+- [Plan](plan.md)
+- [Test Guide](test-guide.md)
+`;
+}
+
+/**
+ * Ariad's own rule for staging, a method line in every Plan: the card and the
+ * scaffold both print it from here (CR019).
+ */
+export const STORY_SCOPED_COMMIT_RULE = "Do not use git add .; commit only story-scoped files.";
+
+/** Python `_render_plan_artifact`. */
+export function renderPlanArtifact(report: PlanArtifactInput): string {
+  // The project's own rules follow the method lines; none is an honest empty (CR019).
+  const contract = [
+    "- Use TDD or characterization tests for behavior changes when testable.",
+    `- Keep changes scoped to \`${report.activeItem}\`.`,
+    `- ${STORY_SCOPED_COMMIT_RULE}`,
+    ...report.localRules.map((rule) => `- ${rule}`),
+  ].join("\n");
+  const stopConditions = report.implementContract.stopConditions
+    .map((condition) => `- ${condition}`)
+    .join("\n");
+  return `# Plan — ${report.activeItem}
+
+## Objective
+
+${report.objective}
+
+## Scope
+
+${markdownList(report.scope)}
+
+## Non-Goals
+
+${markdownList(report.nonGoals)}
+
+## Acceptance Behavior
+
+\`\`\`text
+${report.acceptanceBehavior.join("\n")}
+\`\`\`
+
+## Validation Route
+
+${markdownList(report.validationRoute)}
+
+E2E decision: ${report.e2eDecision}
+
+## Implementation Contract
+
+${contract}
+
+## Stop Conditions
+
+${stopConditions}
+
+## Approval Gate
+
+- active checkpoint: \`${report.activeCheckpoint}\`
+- pending confirmation: \`${report.pendingConfirmation}\`
+- implementation remains blocked until Navigator approval.
+`;
+}
+
+/** Python `_render_test_guide_artifact`. */
+export function renderTestGuideArtifact(report: PlanArtifactInput): string {
+  return `[< Story](index.md)
+
+# Test Guide — ${report.activeItem}
+
+## Automated Validation
+
+${markdownList(report.validationRoute)}
+
+## E2E Decision
+
+${report.e2eDecision}
+
+## Navigator Validation
+
+${NAVIGATOR_VALIDATION_GUIDANCE}
+
+## Validation Evidence
+
+${VALIDATION_EVIDENCE_PENDING}
+`;
+}
+
+/**
+ * Python `_plan_package_artifacts`: what Plan did to each file of the package.
+ *
+ * A file that existed before Plan is left alone (CR079) and named with what it is
+ * (CR112): a scaffold nobody authored, an incomplete file, or an authored one, so the
+ * reader of the artifacts card can tell which. The command and the recorded corpus
+ * both call this, so the card they print cannot differ.
+ */
+export function planPackageArtifacts(
+  planPath: string | null,
+  existedBefore: ReadonlyMap<string, boolean>,
+): MaterializedArtifact[] {
+  if (planPath === null) return [];
+  const directory = dirname(planPath);
+  const triple: [string, string, ArtifactName][] = [
+    ["story index", join(directory, "index.md"), "index.md"],
+    ["plan", planPath, "plan.md"],
+    ["test guide", join(directory, "test-guide.md"), "test-guide.md"],
+  ];
+  return triple.map(([kind, path, name]) =>
+    existedBefore.get(path) === true
+      ? existingArtifact(kind, path, describeArtifactState(artifactState(name, path).state))
+      : materializedArtifact(kind, path, { existedBefore: false }),
+  );
+}
+
+/**
+ * Python `_write_story_package`.
+ *
+ * The directory is created unconditionally, the FILES conditionally. Both halves
+ * matter: a missing directory would make the whole package fail, while an existing
+ * file must survive untouched.
+ */
+export function writeStoryPackage(
+  directory: string,
+  projectRoot: string | null | undefined,
+  report: PlanArtifactInput,
+): void {
+  const root = requireProjectRoot(projectRoot, directory);
+  mkdirSync(directory, { recursive: true });
+  const artifacts: [string, string][] = [
+    [join(directory, "index.md"), renderStoryIndexArtifact(report)],
+    [join(directory, "plan.md"), renderPlanArtifact(report)],
+    [join(directory, "test-guide.md"), renderTestGuideArtifact(report)],
+  ];
+  for (const [path, content] of artifacts) {
+    writeBuilderArtifact({ path, content, policy: "create-only", projectRoot: root });
+  }
+}

package/ts/src/builder/artifacts/scaffoldSections.ts

@@ -0,0 +1,273 @@
+// CR112 — the one home of every sentence a story scaffold carries.
+//
+// Expand writes a child story's `index.md`; Plan writes `index.md`, `plan.md`, and
+// `test-guide.md`. Until CR112 the sentences those files carry lived where each
+// writer happened to compose them: the statement and outcome in `storyIndex.ts`,
+// the Plan context in `commands.ts`, and a second set of Plan defaults in `plan.ts`,
+// reached only when a caller passed no sections. Nothing could read a file back and
+// say whether it was still the scaffold, because nothing held the scaffold's lines in
+// a form a reader could compare against.
+//
+// This module holds them as TEMPLATES: fixed text with a `{title}` slot.
+// The writers fill them (`fill`) and produce the same bytes they always did; the
+// reader (`scaffoldState.ts`) matches a file's lines against them with the slots
+// wildcarded (`matchesTemplate`), so the check reads nothing but the file and this
+// module -- not the cursor's title, which a re-pull can change, and not the roadmap.
+//
+// Every section also carries a KIND. A `placeholder` section is where the scaffold
+// stands in for content the Driver must write. A `default` section is a rule or a
+// default that may legitimately stand as written: keeping "Do not use git add ."
+// verbatim leaves no placeholder behind; keeping "Deliver X as an observable slice"
+// does.
+//
+// One Plan vocabulary, `PRODUCT_PLAN`, which `planLifecycleItem` fills for every
+// caller. CR112 recorded a second one, the defaults Python's `plan_lifecycle_item`
+// wrote when a caller passed no sections; no product path wrote it, only the recorded
+// corpus and the tests, so the corpus graded a scaffold no user received. CR111 (D3)
+// retired it.
+
+export type SectionKind = "placeholder" | "default";
+
+/** A `## ` section of a scaffold: its heading, its kind, and the template lines it may hold. */
+export interface SectionSpec {
+  readonly header: string;
+  readonly kind: SectionKind;
+  /** Template lines a scaffold writes under this heading; empty for a `default` section. */
+  readonly lines: readonly string[];
+}
+
+/** The slot a template may carry: the item's title, the one thing a scaffold varies by. */
+export interface SlotValues {
+  readonly title?: string;
+}
+
+const SLOT_RE = /\{(title)\}/g;
+
+/** Fill a template's slots. A slot with no value is left as written. */
+export function fill(template: string, values: SlotValues): string {
+  return template.replace(SLOT_RE, (whole) => values.title ?? whole);
+}
+
+/**
+ * True when `line` is `template` with anything in its slots: the fixed text before,
+ * between, and after the slots must appear in order, at the ends where the template
+ * has them. A template with no slot matches only itself.
+ */
+export function matchesTemplate(line: string, template: string): boolean {
+  const parts = template.split(SLOT_RE).filter((_, index) => index % 2 === 0);
+  if (parts.length === 1) return line === template;
+  const first = parts[0] as string;
+  const last = parts[parts.length - 1] as string;
+  if (!line.startsWith(first) || !line.endsWith(last)) return false;
+  if (line.length < first.length + last.length) return false;
+  let cursor = first.length;
+  const end = line.length - last.length;
+  for (const part of parts.slice(1, -1)) {
+    const at = line.indexOf(part, cursor);
+    if (at === -1 || at + part.length > end) return false;
+    cursor = at + part.length;
+  }
+  return true;
+}
+
+// --- the statement and outcome templates (Expand's `index.md`, and Plan's) ---
+
+/** Python `_user_story_statement`, as a template. */
+export const USER_STORY_STATEMENT: readonly string[] = [
+  "As a user,",
+  "I want to {title},",
+  "So that I can receive the value of this story.",
+];
+
+/** Python `_technical_story_statement`, as a template. */
+export const TECHNICAL_STORY_STATEMENT: readonly string[] = [
+  "In order to support the delivery capability,",
+  "As an engineering team/system component,",
+  "I want to {title},",
+  "So that the expected technical outcome is available.",
+];
+
+/** Python `_user_story_outcome`, as a template. */
+export const STORY_OUTCOME = "Navigator can validate {title} as an observable behavior.";
+
+/** The acceptance block Expand writes for a User Story. */
+export const USER_STORY_ACCEPTANCE: readonly string[] = [
+  "Given the user is ready for {title}",
+  "When the user performs the planned action",
+  "Then the expected observable behavior is visible",
+  "And unrelated Delivery Story scope remains untouched",
+];
+
+/** The acceptance block Expand writes for a Technical Story. */
+export const TECHNICAL_STORY_ACCEPTANCE: readonly string[] = [
+  "Given the system is ready for {title}",
+  "When the planned technical change is applied",
+  "Then the expected technical outcome is observable",
+  "And unrelated Delivery Story scope remains untouched",
+];
+
+// --- the Plan vocabularies ---
+
+/** The sentences a Plan scaffold carries, before its slots are filled. */
+export interface PlanVocabulary {
+  readonly objective: string;
+  readonly scope: readonly string[];
+  readonly nonGoals: readonly string[];
+  readonly acceptanceBehavior: readonly string[];
+  readonly validationRoute: readonly string[];
+  readonly e2eDecision: string;
+}
+
+/** The Plan scaffold's sentences: Python `cmd_plan_item`'s roadmap context. */
+export const PRODUCT_PLAN: PlanVocabulary = {
+  objective: "Plan the smallest coherent, testable slice for {title}.",
+  scope: [
+    "Deliver {title} as an observable slice.",
+    "Keep the implementation narrow enough to validate at the Plan-defined checkpoint.",
+  ],
+  nonGoals: ["Do not silently absorb adjacent roadmap work."],
+  acceptanceBehavior: [
+    "Given the starting state needed for {title}",
+    "When the Navigator exercises {title}",
+    "Then the planned observable behavior is visible",
+    "And out-of-scope sibling roadmap items remain untouched",
+  ],
+  validationRoute: [
+    "Run automated tests that cover the planned behavior.",
+    "Provide a Navigator-visible route with expected observation, pass condition, and fail condition.",
+  ],
+  e2eDecision:
+    "required unless Navigator explicitly accepts a narrower fixture-level validation route",
+};
+
+/** The Non-Goals line the front door writes for each sibling roadmap item. */
+export const SIBLING_NON_GOAL = "Do not implement sibling roadmap item: {title}.";
+
+/** A vocabulary with its slots filled for one item. */
+export function fillPlanVocabulary(vocabulary: PlanVocabulary, values: SlotValues): PlanVocabulary {
+  const fillAll = (lines: readonly string[]): string[] => lines.map((line) => fill(line, values));
+  return {
+    objective: fill(vocabulary.objective, values),
+    scope: fillAll(vocabulary.scope),
+    nonGoals: fillAll(vocabulary.nonGoals),
+    acceptanceBehavior: fillAll(vocabulary.acceptanceBehavior),
+    validationRoute: fillAll(vocabulary.validationRoute),
+    e2eDecision: fill(vocabulary.e2eDecision, values),
+  };
+}
+
+/** The sentence a test guide's Navigator Validation section holds until it is authored. */
+export const NAVIGATOR_VALIDATION_GUIDANCE =
+  "Provide the Navigator-visible route with expected observation, pass condition, and fail condition before the story can pass Validation.";
+
+/** The sentence a test guide's Validation Evidence section holds until validation. */
+export const VALIDATION_EVIDENCE_PENDING = "Pending implementation and validation.";
+
+// --- the section tables, one per artifact ---
+
+const FENCE_OPEN = "```text";
+const FENCE_CLOSE = "```";
+
+function bullets(lines: readonly string[]): string[] {
+  return lines.map((line) => `- ${line}`);
+}
+
+/** The sections of `plan.md`, in the order Plan writes them. */
+export const PLAN_SECTIONS: readonly SectionSpec[] = [
+  { header: "Objective", kind: "placeholder", lines: [PRODUCT_PLAN.objective] },
+  { header: "Scope", kind: "placeholder", lines: bullets(PRODUCT_PLAN.scope) },
+  { header: "Non-Goals", kind: "default", lines: [] },
+  {
+    header: "Acceptance Behavior",
+    kind: "placeholder",
+    lines: [FENCE_OPEN, ...PRODUCT_PLAN.acceptanceBehavior, FENCE_CLOSE],
+  },
+  {
+    header: "Validation Route",
+    kind: "placeholder",
+    lines: [...bullets(PRODUCT_PLAN.validationRoute), `E2E decision: ${PRODUCT_PLAN.e2eDecision}`],
+  },
+  { header: "Implementation Contract", kind: "default", lines: [] },
+  { header: "Stop Conditions", kind: "default", lines: [] },
+  { header: "Approval Gate", kind: "default", lines: [] },
+];
+
+/** Python `STORY_PLAN_REQUIRED_SECTIONS`, in declaration order: the Plan contract's headings. */
+export const STORY_PLAN_REQUIRED_SECTIONS = [
+  "Scope",
+  "Non-Goals",
+  "Acceptance Behavior",
+  "Validation Route",
+  "Implementation Contract",
+] as const;
+
+/**
+ * The sections a Plan approval requires authored, on either route (CR112): every
+ * placeholder section of the story scaffold and every section the Plan contract
+ * requires, in the order the plan file has them, so a refusal lists them as the reader
+ * will find them. A placeholder section counts until it is authored; a required
+ * `default` section counts until it is not empty or pending.
+ *
+ * One list for every surface that says what a `plan.md` still needs: both approval
+ * routes, `build show`, and the Plan checkpoint read it through `scaffoldState.ts`
+ * (CR111 D4). It lives here, with the sections it names, so the reader below the
+ * approval layer can use it without depending on that layer.
+ */
+export const PLAN_APPROVAL_SECTIONS: readonly string[] = [
+  ...PLAN_SECTIONS.filter(
+    (section) =>
+      section.kind === "placeholder" ||
+      (STORY_PLAN_REQUIRED_SECTIONS as readonly string[]).includes(section.header),
+  ).map((section) => section.header),
+  ...STORY_PLAN_REQUIRED_SECTIONS.filter(
+    (header) => !PLAN_SECTIONS.some((section) => section.header === header),
+  ),
+];
+
+/**
+ * The sections of a story `index.md`. Expand's scaffold heads the statement
+ * `## User Story` or `## Technical Story`; Plan's heads it `## Story Statement` and
+ * puts the objective under `## Outcome`. A file carries one of the three statement
+ * headings; the reader judges whichever it finds.
+ */
+export const STORY_INDEX_SECTIONS: readonly SectionSpec[] = [
+  { header: "User Story", kind: "placeholder", lines: USER_STORY_STATEMENT },
+  { header: "Technical Story", kind: "placeholder", lines: TECHNICAL_STORY_STATEMENT },
+  {
+    header: "Story Statement",
+    kind: "placeholder",
+    lines: [...USER_STORY_STATEMENT, ...TECHNICAL_STORY_STATEMENT],
+  },
+  {
+    header: "Outcome",
+    kind: "placeholder",
+    lines: [STORY_OUTCOME, PRODUCT_PLAN.objective],
+  },
+  {
+    header: "Acceptance Behavior",
+    kind: "placeholder",
+    lines: [
+      FENCE_OPEN,
+      ...USER_STORY_ACCEPTANCE,
+      ...TECHNICAL_STORY_ACCEPTANCE,
+      ...PRODUCT_PLAN.acceptanceBehavior,
+      FENCE_CLOSE,
+    ],
+  },
+  { header: "Scope", kind: "default", lines: [] },
+  { header: "Out Of Scope", kind: "default", lines: [] },
+  { header: "Validation", kind: "default", lines: [] },
+  { header: "Artifacts", kind: "default", lines: [] },
+];
+
+/** The sections of `test-guide.md`, in the order Plan writes them. */
+export const TEST_GUIDE_SECTIONS: readonly SectionSpec[] = [
+  {
+    header: "Automated Validation",
+    kind: "placeholder",
+    lines: bullets(PRODUCT_PLAN.validationRoute),
+  },
+  { header: "E2E Decision", kind: "default", lines: [] },
+  { header: "Navigator Validation", kind: "placeholder", lines: [NAVIGATOR_VALIDATION_GUIDANCE] },
+  { header: "Validation Evidence", kind: "default", lines: [] },
+];