mirror-mind 0.0.1 → 0.32.1

package/ts/src/builder/refinementField.ts

@@ -0,0 +1,93 @@
+// The Refinement field snapshot.
+//
+// Port of `find_canonical_refinement_index`, `inspect_refinement_field`, and
+// `_refinement_snapshot` from `src/memory/builder/home_surface.py`.
+//
+// CV22.DS7.US8 landed the filesystem half here and the Workbench read beside
+// it, because `build load` rendered the `🧰 Refinement field` out of SQLite
+// whenever a project had no `docs/project/refinement/index.md`.
+// CV22.DS10.TS4 retired that Workbench, and with it the second authority: a
+// project either HAS the canonical index or has not created it yet. There is
+// no other place to look, so this module no longer takes a database read of
+// any kind.
+//
+// The port reproduced one inherited oddity rather than clean it mid-port: a
+// seed-CR count read from a HARD-CODED path into Mirror Mind's own roadmap,
+// inside the USER's project -- any other project simply reported zero. It was
+// carried as debt D-024 and removed from both engines by CV22.DS10.TS5, which
+// left the field with a single conditional: the canonical index, or not yet.
+
+import { statSync } from "node:fs";
+import { join } from "node:path";
+
+/** Python `CANONICAL_REFINEMENT_INDEX`. */
+export const CANONICAL_REFINEMENT_INDEX = "docs/project/refinement/index.md";
+
+/**
+ * Python `RefinementFieldSnapshot`.
+ *
+ * `activeRefinementStory` and `activeChangeRequest` are retained as always-null
+ * fields because the surfaces still read them; the three Workbench COUNTS went
+ * with the Workbench, since a permanently-zero count invites a reader to
+ * believe something counts it.
+ */
+export interface RefinementFieldSnapshot {
+  readonly activeRefinementStory: string | null;
+  readonly activeChangeRequest: string | null;
+  readonly storageState: string;
+  readonly nextMove: string;
+  readonly canonicalIndex: string | null;
+}
+
+function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Python `find_canonical_refinement_index`: the project-relative path when the
+ * canonical index exists as a FILE. A directory at that path is not an index —
+ * Python's `is_file()`, not `exists()`.
+ */
+export function findCanonicalRefinementIndex(projectPath: string | null): string | null {
+  if (projectPath === null) return null;
+  return isFile(join(projectPath, CANONICAL_REFINEMENT_INDEX)) ? CANONICAL_REFINEMENT_INDEX : null;
+}
+
+/**
+ * Python `inspect_refinement_field`.
+ *
+ * The canonical index reports `storage_state="project files"`; without it the
+ * answer is the same authority in its unstarted state.
+ */
+export function inspectRefinementField(projectPath: string | null): RefinementFieldSnapshot {
+  const canonicalIndex = findCanonicalRefinementIndex(projectPath);
+  if (canonicalIndex !== null) {
+    return {
+      activeRefinementStory: null,
+      activeChangeRequest: null,
+      storageState: "project files",
+      nextMove: "inspect canonical Refinement index",
+      canonicalIndex,
+    };
+  }
+
+  return buildRefinementSnapshot();
+}
+
+/**
+ * Python `_refinement_snapshot`: the field for a project with no canonical
+ * index. One state, and the next move is to create the file.
+ */
+export function buildRefinementSnapshot(): RefinementFieldSnapshot {
+  return {
+    activeRefinementStory: null,
+    activeChangeRequest: null,
+    storageState: "project files (not started)",
+    nextMove: `create ${CANONICAL_REFINEMENT_INDEX}`,
+    canonicalIndex: null,
+  };
+}

package/ts/src/builder/releaseIntent.ts

@@ -0,0 +1,173 @@
+// CV22.DS7.US8 plateau 6 — Delivery Story release intent.
+//
+// Port of `src/memory/builder/release_intent.py`.
+//
+// Release intent is the only Builder state that belongs to an ANCESTOR rather than
+// to the active item: it is stored as a pair — the intent and the Delivery Story
+// code it was recorded against — so moving to a story under a different Delivery
+// Story makes the inspect face report `not_recorded` instead of inheriting the
+// previous decision. Two cursor fields, one meaning.
+//
+// The boundary itself is derived from the active item's CODE by
+// `deliveryStoryCodeForItem` (already ported for the cursor), so a story whose code
+// carries no `DS<n>` segment has nothing to record against and is refused.
+//
+// `not_recorded` is a RENDERED value, never a stored one: the cursor holds `null`,
+// and the surface distinguishes "nothing was decided" from the explicit decision
+// `none`. Collapsing the two would erase the difference between an open question
+// and an answered one, which is the whole point of the `undecided` value existing
+// beside them.
+
+import type { Database, WritableDatabase } from "#db/database.ts";
+import { pyStrip } from "#util/pythonText.ts";
+import { cardText, cardWrapped } from "./card.ts";
+import { deliveryStoryCodeForItem } from "./cursorTransitions.ts";
+import {
+  type BuilderDeliveryCursor,
+  type CursorWriteDeps,
+  getDeliveryCursor,
+  setDeliveryCursor,
+} from "./deliveryCursor.ts";
+import { wrapAriadSurface } from "./surfaceProtocol.ts";
+
+/** Python `RELEASE_INTENTS`. */
+export const RELEASE_INTENTS = ["planned", "none", "undecided"] as const;
+
+export interface ReleaseIntentReport {
+  readonly journey: string;
+  readonly method: string;
+  readonly deliveryStory: string;
+  readonly intent: string;
+  readonly cursor: BuilderDeliveryCursor;
+  /** False when the pair already said this, which the surface renders as `inspected`. */
+  readonly changed: boolean;
+}
+
+/** Python `_active_delivery_story`: cursor, method match, then the DS ancestor. */
+function activeDeliveryStory(
+  db: Database,
+  journey: string,
+  method: string,
+): { cursor: BuilderDeliveryCursor; deliveryStory: string } {
+  const cursor = getDeliveryCursor(db, journey);
+  if (cursor === null) {
+    throw new Error("delivery cursor is required before release intent");
+  }
+  if (cursor.method !== method) {
+    throw new Error("active Builder method does not match release intent method");
+  }
+  const deliveryStory = deliveryStoryCodeForItem(cursor.activeItem);
+  if (deliveryStory === null) {
+    throw new Error("active Delivery Story boundary is required for release intent");
+  }
+  return { cursor, deliveryStory };
+}
+
+/** Python `set_release_intent`. */
+export function setReleaseIntent(
+  db: WritableDatabase,
+  options: { journey: string; method: string; intent: string },
+  deps: CursorWriteDeps,
+): ReleaseIntentReport {
+  const normalized = pyStrip(options.intent).toLowerCase();
+  if (!(RELEASE_INTENTS as readonly string[]).includes(normalized)) {
+    throw new Error("release intent must be planned, none, or undecided");
+  }
+  // Value first, then the cursor: an unknown intent is refused even with no cursor.
+  const { cursor, deliveryStory } = activeDeliveryStory(db, options.journey, options.method);
+  const changed = !(
+    cursor.releaseIntentDeliveryStory === deliveryStory && cursor.releaseIntent === normalized
+  );
+  const updated = setDeliveryCursor(
+    db,
+    {
+      journey: cursor.journey,
+      method: cursor.method,
+      activeItem: cursor.activeItem,
+      activeItemTitle: cursor.activeItemTitle,
+      activeItemLevel: cursor.activeItemLevel,
+      activeCheckpoint: cursor.activeCheckpoint,
+      pendingConfirmation: cursor.pendingConfirmation,
+      lastDeliveryEvent: cursor.lastDeliveryEvent,
+      cadenceProfile: cursor.cadenceProfile,
+      cadenceLimits: cursor.cadenceLimits,
+      granularityDecision: cursor.granularityDecision,
+      navigatorFlowUnit: cursor.navigatorFlowUnit,
+      childWorkItems: cursor.childWorkItems,
+      aggregateCheckpointStatus: cursor.aggregateCheckpointStatus,
+      cursorGeneration: cursor.cursorGeneration,
+      releaseIntentDeliveryStory: { kind: "set", value: deliveryStory },
+      releaseIntent: { kind: "set", value: normalized },
+    },
+    deps,
+  );
+  return {
+    journey: options.journey,
+    method: options.method,
+    deliveryStory,
+    intent: normalized,
+    cursor: updated,
+    changed,
+  };
+}
+
+/** Python `inspect_release_intent`. */
+export function inspectReleaseIntent(
+  db: Database,
+  options: { journey: string; method: string },
+): ReleaseIntentReport {
+  const { cursor, deliveryStory } = activeDeliveryStory(db, options.journey, options.method);
+  const recorded =
+    cursor.releaseIntentDeliveryStory === deliveryStory && cursor.releaseIntent
+      ? cursor.releaseIntent
+      : "not_recorded";
+  return {
+    journey: options.journey,
+    method: options.method,
+    deliveryStory,
+    intent: recorded,
+    cursor,
+    changed: false,
+  };
+}
+
+const MEANING: Record<string, string> = {
+  planned: "This Delivery Story is expected to create a release boundary if completed coherently.",
+  none: "This Delivery Story is not expected to create a release boundary.",
+  undecided: "Release intent is intentionally unresolved and may be revisited later.",
+  not_recorded: "No release intent has been recorded for this Delivery Story.",
+};
+
+/** Python `render_release_intent_report`. */
+export function renderReleaseIntentReport(report: ReleaseIntentReport): string {
+  const meaning = MEANING[report.intent];
+  if (meaning === undefined) {
+    // Python indexes the dict directly, so an unknown intent is a KeyError there.
+    throw new Error(`unknown release intent: ${report.intent}`);
+  }
+  const body = [
+    "Delivery",
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    "│        🚦  DELIVERY STORY RELEASE INTENT               │",
+    "│                                                        │",
+    cardText("Delivery Story"),
+    ...cardWrapped(report.deliveryStory),
+    "│                                                        │",
+    cardText("Intent"),
+    ...cardWrapped(report.intent),
+    "│                                                        │",
+    cardText("Meaning"),
+    ...cardWrapped(meaning),
+    "│                                                        │",
+    cardText("Action"),
+    ...cardWrapped(report.changed ? "recorded" : "inspected"),
+    "│                                                        │",
+    cardText("Authority boundary"),
+    ...cardWrapped(
+      "Release intent does not authorize commit, push, tag creation, stable promotion, release publication, or remote mutation.",
+    ),
+    "╰────────────────────────────────────────────────────────╯",
+  ];
+  return wrapAriadSurface("release_intent", `${body.join("\n")}\n`);
+}

package/ts/src/builder/resumeState.ts

@@ -0,0 +1,84 @@
+// CV22.DS7.US8 plateau 2 — the DB-backed Builder resume state.
+//
+// Port of `read_builder_resume_state` from `src/memory/builder/resume_state.py`,
+// deferred from plateau 1 because it needs both the adoption row and the delivery
+// cursor, and the cursor's reader ships with its writer.
+//
+// Three states, in Python's order of precedence, each with its own reason:
+//
+//   no adopted method -> `adoption_required`
+//   no cursor         -> `cursor_sync_required`
+//   otherwise         -> resumable
+//
+// CR114: the actions come from `allowedNextActions` in `cursorPosition.ts`, the list
+// `build show` prints too, except for a journey that adopted no method, which `build
+// show` refuses. Python chose them here, from two facts and never the cursor's last
+// event, so it offered Prepare at every position with nothing pending.
+//
+// CV22.DS10.TS4 removed the Workbench read that used to happen here, and with
+// it an asymmetry both engines carried: Python read the Workbench unguarded
+// here while the Home path wrapped the same call, so a database predating
+// CV20.DS6 degraded there and RAISED on this one. Resume state is Delivery
+// state now; the absent-tables case is graded in the golden.
+
+import type { Database } from "#db/database.ts";
+import { allowedNextActions, NOT_ADOPTED_ACTIONS } from "./cursorPosition.ts";
+import { getDeliveryCursor } from "./deliveryCursor.ts";
+import { getAdoptedMethod } from "./methodAdoption.ts";
+import type { BuilderResumeState, ResumeCursorView } from "./resumeSurface.ts";
+
+/** Python `_normalize_journey`. */
+function normalizeJourney(journey: string): string {
+  const normalized = typeof journey === "string" ? journey.trim() : "";
+  if (!normalized) throw new Error("journey must not be empty");
+  return normalized;
+}
+
+/** Python `read_builder_resume_state`. */
+export function readBuilderResumeState(db: Database, journey: string): BuilderResumeState {
+  const normalizedJourney = normalizeJourney(journey);
+
+  const adoptedMethod = getAdoptedMethod(db, normalizedJourney);
+  if (!adoptedMethod) {
+    return {
+      journey: normalizedJourney,
+      adoptedMethod: null,
+      cursor: null,
+      resumable: false,
+      reason: "adoption_required",
+      allowedNextActions: [...NOT_ADOPTED_ACTIONS],
+    };
+  }
+
+  const cursor = getDeliveryCursor(db, normalizedJourney);
+  if (cursor === null) {
+    return {
+      journey: normalizedJourney,
+      adoptedMethod,
+      cursor: null,
+      resumable: false,
+      reason: "cursor_sync_required",
+      allowedNextActions: [...allowedNextActions(null)],
+    };
+  }
+
+  const view: ResumeCursorView = {
+    activeItem: cursor.activeItem,
+    activeItemLevel: cursor.activeItemLevel,
+    activeCheckpoint: cursor.activeCheckpoint,
+    pendingConfirmation: cursor.pendingConfirmation,
+    lastDeliveryEvent: cursor.lastDeliveryEvent,
+    releaseIntent: cursor.releaseIntent,
+    releaseIntentDeliveryStory: cursor.releaseIntentDeliveryStory,
+    cadenceProfile: cursor.cadenceProfile,
+    cadenceLimits: cursor.cadenceLimits,
+  };
+  return {
+    journey: normalizedJourney,
+    adoptedMethod,
+    cursor: view,
+    resumable: true,
+    reason: null,
+    allowedNextActions: [...allowedNextActions(view)],
+  };
+}

package/ts/src/builder/resumeSurface.ts

@@ -0,0 +1,149 @@
+// CV22.DS7.US8 plateau 1 — the `■ BUILDER RESUME` surface.
+//
+// Port of `src/memory/builder/resume_surface.py`. Python's three allowed-next-action
+// tuples and the rule that picked between them lived here too. CR114 replaced them:
+// the rule never read the cursor's last event, so it offered Prepare at every
+// position with nothing pending. The list is chosen in `cursorPosition.ts` now, and
+// this module only prints it.
+//
+// Three conditional shapes a port merges by accident:
+//
+//   * the `reason` block renders only when a reason exists;
+//   * `release intent` needs BOTH `release_intent` AND
+//     `release_intent_delivery_story` — `and`, not `or`, so a cursor carrying one
+//     of them shows neither;
+//   * `_last_refinement_event` reports `"none"` whenever there is no active
+//     Refinement Story, EVEN WHEN an event is recorded. Reading the field
+//     directly is the obvious port and it is wrong.
+//
+// `_resume_phase` exists in Python and is never called by anything. It is not
+// ported: dead code that the surface does not reach is not parity surface, and
+// carrying it forward would import a maintenance obligation with no observable
+// behavior. Recorded in the story's debt list instead.
+
+import { type CadenceView, cadenceCardLines } from "./cadence.ts";
+import { cardPrefixed, cardText, cardWrapped } from "./card.ts";
+import { CANONICAL_REFINEMENT_INDEX } from "./refinementField.ts";
+import type { RoadmapScope } from "./roadmapScope.ts";
+import { roadmapPositionLines } from "./scopePhrases.ts";
+import { wrapAriadSurface } from "./surfaceProtocol.ts";
+
+const FRAME_TOP = "╭────────────────────────────────────────────────────────╮";
+const FRAME_BOTTOM = "╰────────────────────────────────────────────────────────╯";
+const FRAME_BLANK = "│                                                        │";
+
+/** The cursor fields the resume surface reads, and its next actions are chosen from. */
+export interface ResumeCursorView extends CadenceView {
+  readonly activeItem: string | null;
+  readonly activeItemLevel: string | null;
+  readonly activeCheckpoint: string | null;
+  readonly pendingConfirmation: string | null;
+  readonly lastDeliveryEvent: string | null;
+  readonly releaseIntent: string | null;
+  readonly releaseIntentDeliveryStory: string | null;
+}
+
+/** Python `BuilderResumeState`. */
+export interface BuilderResumeState {
+  readonly journey: string;
+  readonly adoptedMethod: string | null;
+  readonly cursor: ResumeCursorView | null;
+  readonly resumable: boolean;
+  readonly reason: string | null;
+  readonly allowedNextActions: readonly string[];
+}
+
+/** Python `_release_intent_lines`: both fields, or no block at all. */
+function releaseIntentLines(cursor: ResumeCursorView | null): string[] {
+  const intent = cursor?.releaseIntent ?? null;
+  const deliveryStory = cursor?.releaseIntentDeliveryStory ?? null;
+  if (!intent || !deliveryStory) return [];
+  return [
+    FRAME_BLANK,
+    cardText("release intent"),
+    ...cardWrapped(`${deliveryStory}: ${intent}`),
+    ...cardWrapped("intent is not release authorization"),
+  ];
+}
+
+/** Python `_refinement_field_lines`. Two shapes since CV22.DS10.TS4. */
+function refinementFieldLines(canonicalRefinementIndex: string | null): string[] {
+  if (canonicalRefinementIndex) {
+    return [
+      cardText("authority: project files"),
+      ...cardWrapped(`index: ${canonicalRefinementIndex}`),
+    ];
+  }
+  return [
+    cardText("authority: project files (not started)"),
+    ...cardWrapped(`create: ${CANONICAL_REFINEMENT_INDEX}`),
+  ];
+}
+
+/**
+ * Python `render_builder_resume_surface`, except for the `roadmap position` row.
+ *
+ * Python filled that row with the first roadmap file whose status contained
+ * "Active", whichever journey asked. Since CR002 it states the journey's own
+ * scope, which the caller resolves from the same cursor `state` carries. The
+ * scope is required so that no caller can fall back to a guess by omission.
+ */
+export function renderBuilderResumeSurface(
+  state: BuilderResumeState,
+  options: {
+    scope: RoadmapScope;
+    canonicalRefinementIndex?: string | null;
+  },
+): string {
+  const canonicalRefinementIndex = options.canonicalRefinementIndex ?? null;
+  const cursor = state.cursor;
+  const lines: string[] = [
+    "Delivery",
+    "",
+    FRAME_TOP,
+    "│        ■  BUILDER RESUME                               │",
+    FRAME_BLANK,
+    cardText("journey"),
+    cardText(state.journey),
+    FRAME_BLANK,
+    cardText("adopted method"),
+    cardText(state.adoptedMethod || "none"),
+    FRAME_BLANK,
+    cardText("resumable"),
+    cardText(state.resumable ? "yes" : "no"),
+  ];
+  if (state.reason) {
+    lines.push(FRAME_BLANK, cardText("reason"), ...cardWrapped(state.reason));
+  }
+  lines.push(
+    FRAME_BLANK,
+    cardText("roadmap position"),
+    ...roadmapPositionLines(options.scope).flatMap(cardWrapped),
+    FRAME_BLANK,
+    cardText("active item"),
+    cardText(cursor?.activeItem || "none"),
+    FRAME_BLANK,
+    cardText("active checkpoint"),
+    cardText(cursor?.activeCheckpoint || "none"),
+    FRAME_BLANK,
+    cardText("pending confirmation"),
+    cardText(cursor?.pendingConfirmation || "none"),
+    FRAME_BLANK,
+    cardText("last delivery event"),
+    cardText(cursor?.lastDeliveryEvent || "none"),
+    FRAME_BLANK,
+    ...cadenceCardLines(cursor),
+    ...releaseIntentLines(cursor),
+    FRAME_BLANK,
+    cardText("🧰 Refinement field"),
+    ...refinementFieldLines(canonicalRefinementIndex),
+    FRAME_BLANK,
+    cardText("allowed next actions"),
+    ...cardPrefixed(state.allowedNextActions, "-"),
+    FRAME_BLANK,
+    cardText("boundary"),
+    ...cardWrapped("Builder resumes context only; no story lifecycle work was executed."),
+    FRAME_BOTTOM,
+  );
+  return wrapAriadSurface("builder_resume", `${lines.join("\n")}\n`);
+}