mirror-mind 0.0.1 → 0.32.1

package/ts/src/builder/artifacts/artifactWriter.ts

@@ -0,0 +1,113 @@
+// CR079: no Ariad command replaces content it did not write.
+//
+// Every file the Builder writes goes through here, under one of two policies.
+//
+// A SCAFFOLD (`create-only`) is written once, when absent, and never again: the
+// Plan packages, Expand's story indexes, the method templates. From its first
+// write on, it belongs to the Driver.
+//
+// A RECORD (`sealed-record`) may be rewritten, because a checkpoint recorded as
+// pending and later accepted runs its command again, and the file has to follow.
+// These are the closure artifacts: `validation.md`, `review.md`, `coherence.md`
+// and `done.md`, at story and Delivery Story level. A record is rewritten only
+// while the runtime can prove that it wrote the file and nobody changed it
+// since. The proof is a seal on the record's last line: the SHA-256 of everything
+// above it, with line endings normalized, so that a CRLF checkout does not read
+// as an edit.
+//
+// Anything else is PRESERVED, byte for byte, and the caller reports that: an
+// authored file, an edited record, a record written before the seal existed, a
+// removed seal, or text after the seal. Before this, the closure writers
+// replaced whatever was there, and two stories lost authored validation evidence
+// to them.
+//
+// Both policies refuse a path outside the project before writing anything.
+// `builderWriteGuard.test.ts` fails if any other module under `ts/src/builder`
+// writes a file, so a new artifact cannot arrive without choosing a policy here.
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+
+export type ArtifactPolicy = "create-only" | "sealed-record";
+
+/** What the writer did, which is what a surface must report: never a pre-check. */
+export type ArtifactOutcome = "created" | "updated" | "existing" | "preserved";
+
+export class ArtifactOutsideProjectError extends Error {}
+
+const SEAL_TEXT =
+  "Ariad wrote this file and rewrites it only while this line matches the text above it. " +
+  "Edit the file and Ariad will leave it as it is.";
+
+/** The hash and a closing marker; the prose between them may change without orphaning old seals. */
+const SEAL_LINE = /^<!-- ariad-seal sha256:([0-9a-f]{64}) .*-->$/u;
+
+export function writeBuilderArtifact(options: {
+  readonly path: string;
+  readonly content: string;
+  readonly policy: ArtifactPolicy;
+  readonly projectRoot: string;
+}): ArtifactOutcome {
+  const target = confinedTo(options.projectRoot, options.path);
+  const sealed = options.policy === "sealed-record";
+  if (!existsSync(target)) {
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, sealed ? sealArtifact(options.content) : options.content, "utf8");
+    return "created";
+  }
+  if (!sealed) return "existing";
+  if (!isSealedByAriad(readFileSync(target, "utf8"))) return "preserved";
+  writeFileSync(target, sealArtifact(options.content), "utf8");
+  return "updated";
+}
+
+/**
+ * The project root a write must stay inside. A path that arrives without one is a
+ * caller bug: it is refused loudly rather than written unconfined.
+ */
+export function requireProjectRoot(projectRoot: string | null | undefined, path: string): string {
+  if (!projectRoot) {
+    throw new Error(`Error: ${path} was given without its project root; refusing to write it.`);
+  }
+  return projectRoot;
+}
+
+/** The content, then one line carrying the SHA-256 of that content. */
+export function sealArtifact(content: string): string {
+  const body = normalized(content.endsWith("\n") ? content : `${content}\n`);
+  return `${body}<!-- ariad-seal sha256:${sha256(body)} — ${SEAL_TEXT} -->\n`;
+}
+
+/** True only when the last line is a seal whose hash matches everything above it. */
+export function isSealedByAriad(text: string): boolean {
+  const lines = normalized(text).replace(/\n+$/u, "").split("\n");
+  const match = SEAL_LINE.exec(lines.pop() ?? "");
+  if (match === null) return false;
+  return match[1] === sha256(lines.length > 0 ? `${lines.join("\n")}\n` : "");
+}
+
+function normalized(text: string): string {
+  return text.replaceAll("\r\n", "\n");
+}
+
+function sha256(text: string): string {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+/**
+ * Both resolved against the working directory, as `writeFileSync` would resolve the
+ * path: a relative project path (the lifecycle corpus uses one) must not be read as
+ * relative to itself.
+ */
+function confinedTo(projectRoot: string, path: string): string {
+  const root = resolve(projectRoot);
+  const target = resolve(path);
+  const within = relative(root, target);
+  if (within === "" || within === ".." || within.startsWith(`..${sep}`) || isAbsolute(within)) {
+    throw new ArtifactOutsideProjectError(
+      `Error: refusing to write ${path}: it is outside the project at ${root}.`,
+    );
+  }
+  return target;
+}

package/ts/src/builder/artifacts/closureArtifacts.ts

@@ -0,0 +1,199 @@
+// CV22.DS7.US8 plateau 4 — the four files story closure writes.
+//
+// Port of `_render_validation_artifact`, `_render_review_artifact`,
+// `_render_coherence_artifact`, and `_render_done_artifact` from
+// `src/memory/builder/lifecycle.py`.
+//
+// These are RECORDS, not scaffolds: a checkpoint recorded pending and later
+// accepted runs its verb again, and the file has to follow. Python wrote them
+// unconditionally, and the port reproduced that until CR079 settled it, because a
+// guard added during the port would have hidden the CR. The overwrite destroyed a
+// 235-line authored `validation.md`, and a 146-line one a story later.
+// `writeClosureArtifact` now writes through the artifact writer as a sealed
+// record: rewritten only while its seal proves Ariad wrote the file and nobody
+// changed it, and preserved byte for byte otherwise. The corpus sequence
+// `closure_preserves_authored_artifacts` records the authored files surviving.
+//
+// Each body's `## ` headings are also the shape a human reassembles by hand after an
+// overwrite, so they are graded as bytes rather than as structure.
+
+import {
+  type ArtifactOutcome,
+  requireProjectRoot,
+  writeBuilderArtifact,
+} from "./artifactWriter.ts";
+import { markdownList } from "./planArtifacts.ts";
+
+/** Python `_render_validation_artifact`. */
+export function renderValidationArtifact(report: {
+  activeItem: string;
+  automatedChecks: readonly string[];
+  checksStatus: string;
+  e2eDecision: string;
+  e2eEvidence: string | null;
+  navigatorValidationRoute: string;
+  navigatorAccepted: boolean;
+  expectedObservation: string;
+  passCondition: string;
+  failCondition: string;
+  missingEvidence: readonly string[];
+}): string {
+  return `# Validation — ${report.activeItem}
+
+## Status
+
+${report.missingEvidence.length > 0 ? "Blocked" : "Passed"}
+
+## Automated Checks
+
+${markdownList(
+  report.automatedChecks.length > 0 ? report.automatedChecks : ["No automated checks declared."],
+)}
+
+Checks status: ${report.checksStatus}
+
+## E2E
+
+Decision: ${report.e2eDecision}
+
+Evidence: ${report.e2eEvidence || "none"}
+
+## Navigator Validation
+
+Route: ${report.navigatorValidationRoute}
+
+Navigator accepted: ${report.navigatorAccepted ? "yes" : "no"}
+
+Expected observation: ${report.expectedObservation}
+
+Pass condition: ${report.passCondition}
+
+Fail condition: ${report.failCondition}
+
+## Missing Evidence
+
+${markdownList(report.missingEvidence.length > 0 ? report.missingEvidence : ["none"])}
+`;
+}
+
+/** Python `_render_review_artifact`. */
+export function renderReviewArtifact(report: {
+  activeItem: string;
+  debtFindings: readonly string[];
+  debtDecision: string;
+  deferReason: string | null;
+  revisitTrigger: string | null;
+  missingDecision: readonly string[];
+}): string {
+  return `# Review — ${report.activeItem}
+
+## Status
+
+${report.missingDecision.length > 0 ? "Pending debt decision" : "Reviewed"}
+
+## Debt Findings
+
+${markdownList(
+  report.debtFindings.length > 0 ? report.debtFindings : ["No debt findings declared."],
+)}
+
+## Debt Decision
+
+${report.debtDecision}
+
+## Defer Reason
+
+${report.deferReason || "none"}
+
+## Revisit Trigger
+
+${report.revisitTrigger || "none"}
+
+## Missing Decision
+
+${markdownList(report.missingDecision.length > 0 ? report.missingDecision : ["none"])}
+`;
+}
+
+/** Python `_render_coherence_artifact`. */
+export function renderCoherenceArtifact(report: {
+  activeItem: string;
+  processAlignment: string;
+  projectAlignment: string;
+  productAlignment: string;
+  localDifferences: readonly string[];
+  missingCoherence: readonly string[];
+}): string {
+  return `# Coherence — ${report.activeItem}
+
+## Status
+
+${report.missingCoherence.length > 0 ? "Pending coherence" : "Coherent"}
+
+## Process Alignment
+
+${report.processAlignment}
+
+## Project Alignment
+
+${report.projectAlignment}
+
+## Product Alignment
+
+${report.productAlignment}
+
+## Local Guide Differences
+
+${markdownList(report.localDifferences.length > 0 ? report.localDifferences : ["none"])}
+
+## Missing Coherence
+
+${markdownList(report.missingCoherence.length > 0 ? report.missingCoherence : ["none"])}
+`;
+}
+
+/** Python `_render_done_artifact`. */
+export function renderDoneArtifact(report: {
+  activeItem: string;
+  historyAction: string;
+  roadmapUpdate: string;
+  nextRecommendation: string;
+  missingDone: readonly string[];
+}): string {
+  return `# Done — ${report.activeItem}
+
+## Status
+
+${report.missingDone.length > 0 ? "Pending Done" : "Done"}
+
+## History Action
+
+${report.historyAction}
+
+## Roadmap Update
+
+${report.roadmapUpdate}
+
+## Next Recommendation
+
+${report.nextRecommendation}
+
+## Missing Done
+
+${markdownList(report.missingDone.length > 0 ? report.missingDone : ["none"])}
+`;
+}
+
+/** A closure record: created sealed, rewritten while its seal holds, otherwise preserved. */
+export function writeClosureArtifact(
+  path: string,
+  content: string,
+  projectRoot: string | null | undefined,
+): ArtifactOutcome {
+  return writeBuilderArtifact({
+    path,
+    content,
+    policy: "sealed-record",
+    projectRoot: requireProjectRoot(projectRoot, path),
+  });
+}

package/ts/src/builder/artifacts/deliveryStoryArtifacts.ts

@@ -0,0 +1,316 @@
+// CV22.DS7.US8 plateau 5 — the Delivery Story package and the closure artifacts.
+//
+// Port of `_write_delivery_story_package` / `_render_*_artifact` in
+// `delivery_story_plan.py` and `_write_artifact` / `_render_artifact` in
+// `delivery_story_closure.py`.
+//
+// Two OPPOSITE file rules live here, and the difference is deliberate in Python:
+//
+//   * the Plan package preserves — `index.md`, `plan.md`, and `test-guide.md` are
+//     written only when absent, so Expand-generated or hand-authored content
+//     survives Plan and approval alike;
+//   * the closure artifacts OVERWRITE — `validation.md`, `review.md`,
+//     `coherence.md`, and `done.md` are rewritten on every call. That is CR079, the
+//     same defect story closure carries, and it is reproduced rather than repaired:
+//     adding the "obvious" existence guard here fails the corpus on purpose.
+//
+// The manifest each writer returns reports the REAL disk action, which is what the
+// artifact writer says it did, because the ARTIFACTS_MATERIALIZED surface must match
+// what happened rather than what was intended (CR079). The package is a scaffold,
+// written only where absent; the closure artifact is a sealed record.
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pySplitLines, pyStrip } from "#util/pythonText.ts";
+import {
+  existingArtifact,
+  type MaterializedArtifact,
+  materializedArtifact,
+} from "./artifactSurfaces.ts";
+import {
+  type ArtifactOutcome,
+  requireProjectRoot,
+  writeBuilderArtifact,
+} from "./artifactWriter.ts";
+
+/** What the renderers need from a Delivery Story Plan report. */
+export interface DeliveryStoryArtifactInput {
+  readonly journey: string;
+  readonly method: string;
+  readonly deliveryStory: string;
+  readonly deliveryStoryTitle: string | null;
+  readonly childWorkItems: readonly string[];
+  readonly objective: string;
+}
+
+const FLOW_UNIT_DELIVERY_STORY = "delivery_story";
+
+/** Python's `"\n".join(f"- {item}" for item in items) or "- none"`. */
+function childList(items: readonly string[]): string {
+  return items.map((item) => `- ${item}`).join("\n") || "- none";
+}
+
+/** Python `_PLAN_CONTRACT_SECTIONS`, with the guidance text that becomes the placeholder. */
+const PLAN_CONTRACT_SECTIONS: readonly (readonly [string, string])[] = [
+  ["Scope", "name what this Delivery Story delivers across its child work packages."],
+  ["Non-Goals", "name what is explicitly out of scope for this Delivery Story."],
+  [
+    "Acceptance Behavior",
+    "describe the aggregate observable outcome, using Given/When/Then when practical.",
+  ],
+  [
+    "Validation Route",
+    "describe how the aggregate delivery is validated, including whether E2E is required.",
+  ],
+  [
+    "Implementation Contract",
+    "record the constraints for child work: TDD for behavior changes, changes scoped to " +
+      "this Delivery Story's children, and no silent scope absorption.",
+  ],
+];
+
+/** Python `_placeholder_line`. */
+export function placeholderLine(guidance: string): string {
+  return `Pending — ${guidance}`;
+}
+
+/**
+ * Python `_unfilled_plan_sections_for` in `delivery_story_plan.py`.
+ *
+ * NOT the story-level rule (`planSectionsToAuthor` in `scaffoldState.ts`), and the
+ * difference is an authority boundary rather than a detail. The Delivery Story check carries two
+ * conditions the story-level one does not:
+ *
+ *   * the section body CONTAINS this section's exact scaffold line
+ *     (`Pending — <guidance>`) anywhere, not only at the start of a line;
+ *   * the casefolded body contains `placeholder` ANYWHERE, where the story-level
+ *     rule only matches it at the start of a line.
+ *
+ * So the DS rule is strictly broader, and reusing the story helper would consume a
+ * preauthorization receipt against a Plan Python still calls unfilled — authority
+ * granted where Python refuses it. Graded by
+ * `delivery_story_preauthorization_refuses_prose_placeholder`.
+ */
+export function unfilledDeliveryStoryPlanSections(planPath: string | null): string[] {
+  const headers = PLAN_CONTRACT_SECTIONS.map(([header]) => header);
+  if (planPath === null || !existsSync(planPath)) return headers;
+  const sections = levelTwoSections(readFileSync(planPath, "utf8"));
+  const throwaway = new Set(["todo", "tbd", "...", "n/a", "none"]);
+  const unfilled: string[] = [];
+  for (const [header, guidance] of PLAN_CONTRACT_SECTIONS) {
+    const body = pyStrip(sections.get(header) ?? "");
+    const normalized = body.toLowerCase();
+    const lines = pySplitLines(body)
+      .map((line) => pyStrip(line).toLowerCase())
+      .filter((line) => line !== "");
+    if (
+      !body ||
+      body.includes(placeholderLine(guidance)) ||
+      lines.some((line) => line.startsWith("pending")) ||
+      lines.some((line) => throwaway.has(line)) ||
+      normalized.includes("placeholder")
+    ) {
+      unfilled.push(header);
+    }
+  }
+  return unfilled;
+}
+
+/**
+ * Python `_level_two_sections` — the DS copy.
+ *
+ * `setdefault` semantics: a repeated `## Scope` appends to the first section.
+ */
+function levelTwoSections(planText: string): Map<string, string> {
+  const sections = new Map<string, string[]>();
+  let current: string | null = null;
+  for (const line of planText.split("\n")) {
+    if (line.startsWith("## ")) {
+      current = pyStrip(line.slice(3));
+      if (!sections.has(current)) sections.set(current, []);
+    } else if (current !== null) {
+      sections.get(current)?.push(line);
+    }
+  }
+  return new Map([...sections].map(([header, lines]) => [header, lines.join("\n")]));
+}
+
+/** Python `_render_plan_artifact`. */
+export function renderDeliveryStoryPlanArtifact(report: DeliveryStoryArtifactInput): string {
+  const contractSections = PLAN_CONTRACT_SECTIONS.map(
+    ([header, guidance]) => `## ${header}\n\n${placeholderLine(guidance)}`,
+  ).join("\n\n");
+  return `# Delivery Story Plan — ${report.deliveryStory}
+
+**Journey:** ${report.journey}
+**Method:** ${report.method}
+**Navigator Flow Unit:** ${FLOW_UNIT_DELIVERY_STORY}
+
+## Delivery Story
+
+${report.deliveryStoryTitle || "Untitled Delivery Story"}
+
+## Objective
+
+${report.objective}
+
+## Child Work Packages
+
+${childList(report.childWorkItems)}
+
+${contractSections}
+
+---
+
+_Approval and lifecycle state are tracked by the Builder runtime, not duplicated in this plan._
+`;
+}
+
+/** Python `_render_index_artifact`. */
+export function renderDeliveryStoryIndexArtifact(report: DeliveryStoryArtifactInput): string {
+  const title = report.deliveryStoryTitle || report.deliveryStory;
+  return `[< Parent](../index.md)
+
+# ${report.deliveryStory} — ${title}
+
+**Status:** 🟡 Planned
+**Type:** Delivery Story
+
+---
+
+## Outcome
+
+${report.objective}
+
+## Child Work Packages
+
+${childList(report.childWorkItems)}
+
+## Done Condition
+
+The Delivery Story is done when its child work packages produce a coherent delivery outcome.
+
+---
+
+## Artifacts
+
+- [Plan](plan.md)
+- [Test Guide](test-guide.md)
+`;
+}
+
+/** Python `_render_test_guide_artifact`. */
+export function renderDeliveryStoryTestGuideArtifact(report: DeliveryStoryArtifactInput): string {
+  return `[< Story](index.md)
+
+# Test Guide — ${report.deliveryStory}
+
+## Aggregate Validation
+
+Pending aggregate Delivery Story validation across child work packages.
+
+## Child Work Packages
+
+${childList(report.childWorkItems)}
+
+## Navigator Validation
+
+Provide the Navigator-visible route with expected observation, pass condition, and fail condition before the Delivery Story can pass aggregate Validation.
+
+## Validation Evidence
+
+Pending implementation and validation.
+`;
+}
+
+/**
+ * Python `_write_delivery_story_package`.
+ *
+ * Insert-if-absent for all three files, and the manifest order is
+ * `index → plan → test guide` regardless of which one was created.
+ */
+export function writeDeliveryStoryPackage(
+  planPath: string,
+  report: DeliveryStoryArtifactInput,
+  projectRoot: string | null | undefined,
+): readonly MaterializedArtifact[] {
+  const parent = dirname(planPath);
+  const root = requireProjectRoot(projectRoot, planPath);
+  const write = (kind: string, path: string, content: string): MaterializedArtifact =>
+    writeBuilderArtifact({ path, content, policy: "create-only", projectRoot: root }) === "existing"
+      ? existingArtifact(kind, path)
+      : materializedArtifact(kind, path, { existedBefore: false });
+  // Written plan first, as before: the plan is the artifact the other two describe.
+  const plan = write("plan", planPath, renderDeliveryStoryPlanArtifact(report));
+  const index = write(
+    "story index",
+    join(parent, "index.md"),
+    renderDeliveryStoryIndexArtifact(report),
+  );
+  const testGuide = write(
+    "test guide",
+    join(parent, "test-guide.md"),
+    renderDeliveryStoryTestGuideArtifact(report),
+  );
+  return [index, plan, testGuide];
+}
+
+/** What the closure artifact renderer needs from a DS closure report. */
+export interface DeliveryStoryClosureArtifactInput {
+  readonly deliveryStory: string;
+  readonly childWorkItems: readonly string[];
+  readonly checkpoint: string;
+  readonly status: string;
+  readonly summary: string;
+  readonly boundary: string;
+}
+
+/** Python `_render_artifact` in `delivery_story_closure.py`. */
+export function renderDeliveryStoryClosureArtifact(
+  report: DeliveryStoryClosureArtifactInput,
+): string {
+  // Python's `str.title()` over a `_`-to-space checkpoint name: `debt_review`
+  // becomes `Debt Review`.
+  const title = report.checkpoint
+    .replaceAll("_", " ")
+    .replace(
+      /[A-Za-z]+('[A-Za-z]*)?/g,
+      (word) => word[0].toUpperCase() + word.slice(1).toLowerCase(),
+    );
+  return `# ${title} — ${report.deliveryStory}
+
+## Status
+
+${report.status}
+
+## Summary
+
+${report.summary}
+
+## Child Work Packages
+
+${report.childWorkItems.map((item) => `- ${item}`).join("\n") || "- none"}
+
+## Boundary
+
+${report.boundary}
+`;
+}
+
+/**
+ * A Delivery Story closure record: created sealed, rewritten while its seal holds,
+ * and otherwise preserved (CR079). Null when the story has no package to write to.
+ */
+export function writeDeliveryStoryClosureArtifact(
+  path: string | null,
+  report: DeliveryStoryClosureArtifactInput,
+  projectRoot: string | null | undefined,
+): ArtifactOutcome | null {
+  if (path === null) return null;
+  return writeBuilderArtifact({
+    path,
+    content: renderDeliveryStoryClosureArtifact(report),
+    policy: "sealed-record",
+    projectRoot: requireProjectRoot(projectRoot, path),
+  });
+}