mirror-mind 0.0.1 → 0.33.0

package/ts/src/builder/aggregateStatus.ts

@@ -0,0 +1,34 @@
+// A Delivery Story's aggregate checkpoint status: its writer, and one of its readers.
+//
+// `aggregate_checkpoint_status` is an ordered list cell on the delivery cursor,
+// one `<checkpoint>:<status>` entry per Delivery Story checkpoint reached: the Plan
+// (`plan:pending`, `plan:approved`), then validation, the debt review, coherence,
+// and done. `replaceStatus` writes every entry, for the Plan and closure modules.
+// `hasDeliveryStoryPlan` is the flow unit's reader (CR105), kept beside the writer
+// so the two agree on the Plan's prefix. The other readers still test entries by
+// hand: `implementationGuard.ts` and the Plan approval test `plan:approved`, and
+// `deliveryStoryClosure.ts` tests the entry each closure step expects.
+
+/**
+ * Python `_replace_status`.
+ *
+ * Keep every entry whose prefix differs, then APPEND. Shared by
+ * `deliveryStoryPlan.ts` and `deliveryStoryClosure.ts`, which need the identical
+ * rule: the order is part of the serialized cell a compare-and-swap matches on.
+ */
+export function replaceStatus(
+  existing: readonly string[],
+  checkpoint: string,
+  status: string,
+): string[] {
+  const prefix = `${checkpoint}:`;
+  return [...existing.filter((item) => !item.startsWith(prefix)), `${checkpoint}:${status}`];
+}
+
+/**
+ * Whether the Delivery Story's Plan is recorded: pending approval, approved, or
+ * followed by any later checkpoint, since each of those is reached through it.
+ */
+export function hasDeliveryStoryPlan(statuses: readonly string[]): boolean {
+  return statuses.some((item) => item.startsWith("plan:"));
+}

package/ts/src/builder/approve.ts

@@ -0,0 +1,149 @@
+// CV22.DS7.US8 plateau 3 — ordinary Plan approval.
+//
+// Port of `approve_plan_checkpoint` and `render_plan_approval` from
+// `src/memory/builder/lifecycle.py`.
+//
+// The detail worth naming: an ordinary approval INVALIDATES a pending authority
+// receipt with `ordinary_approval_used`, rather than leaving it pending or dropping
+// it. Leaving it pending would let the same authority be consumed a second time
+// after the Navigator already approved by hand; dropping it silently would lose the
+// record of why it never applied.
+//
+// CR112: approval reads the plan. Until then an untouched scaffold was approvable,
+// because nothing opened `plan.md`. An approval now refuses, before any write, while
+// any section the approval requires is missing, empty, pending, or still the
+// scaffold's own sentences -- the same list the preauthorized route checks. The
+// precondition that the cursor holds a Plan awaiting approval is a refusal too, told
+// apart as already complete, waiting on another confirmation, or not reached (CR067).
+
+import { existsSync } from "node:fs";
+import type { WritableDatabase } from "#db/database.ts";
+import { planSectionsToAuthor } from "./artifacts/scaffoldState.ts";
+import { cardText, cardWrapped } from "./card.ts";
+import { normalizeRequired } from "./cursorTransitions.ts";
+import {
+  type BuilderDeliveryCursor,
+  type CursorWriteDeps,
+  getDeliveryCursor,
+  setDeliveryCursor,
+  setTo,
+} from "./deliveryCursor.ts";
+import { LifecycleRefusal, refuseIfAlreadyComplete } from "./lifecycleRefusal.ts";
+import { renderLifecycleRibbon } from "./lifecycleRibbon.ts";
+import { displayPath } from "./projectPaths.ts";
+import { wrapAriadSurface } from "./surfaceProtocol.ts";
+
+export interface ApprovePlanOptions {
+  readonly journey: string;
+  readonly method: string;
+  /**
+   * The story package's `plan.md`. `null` when the journey has no project, so there
+   * is no file to read and approval proceeds as it always did. Required, not optional:
+   * the rule lives in this argument, and a caller that could omit it could skip the
+   * rule without anyone deciding to (CR112's handoff review, finding 1).
+   */
+  readonly planArtifactPath: string | null;
+  /** The project the refusal prints the path relative to. */
+  readonly projectRoot?: string | null;
+}
+
+/**
+ * Refuse, before any write, a plan that is not yet a plan: any section in
+ * `PLAN_APPROVAL_SECTIONS` missing, empty, pending, or still the scaffold's -- the list
+ * `build show` prints for the same file (CR111 D4).
+ */
+function refuseUnauthoredPlan(planPath: string | null, projectRoot: string | null): void {
+  if (planPath === null) return;
+  const unauthored = planSectionsToAuthor(planPath);
+  if (unauthored.length === 0) return;
+  const shown = displayPath(planPath, projectRoot);
+  throw new LifecycleRefusal(
+    "plan_approval",
+    "missing_evidence",
+    existsSync(planPath)
+      ? `Plan approval needs an authored plan. Still to author in ${shown}: ${unauthored.join(", ")}.`
+      : `Plan approval needs an authored plan, and ${shown} does not exist.`,
+  );
+}
+
+/** Python `approve_plan_checkpoint`. */
+export function approvePlanCheckpoint(
+  db: WritableDatabase,
+  options: ApprovePlanOptions,
+  deps: CursorWriteDeps,
+): BuilderDeliveryCursor {
+  const journey = normalizeRequired(options.journey, "journey");
+  const method = normalizeRequired(options.method, "method");
+
+  const existing = getDeliveryCursor(db, journey);
+  if (existing === null) throw new Error("delivery cursor is required before plan approval");
+  refuseIfAlreadyComplete("plan_approval", existing);
+  if (
+    existing.activeCheckpoint !== "after_plan" ||
+    existing.pendingConfirmation !== "navigator_approval"
+  ) {
+    if (existing.pendingConfirmation && existing.pendingConfirmation !== "navigator_approval") {
+      throw new LifecycleRefusal(
+        "plan_approval",
+        "pending_confirmation",
+        `Plan approval is blocked: pending confirmation ${existing.pendingConfirmation}.`,
+      );
+    }
+    throw new LifecycleRefusal(
+      "plan_approval",
+      "not_reached",
+      "Plan approval requires a Plan awaiting approval: run plan-item first.",
+    );
+  }
+  refuseUnauthoredPlan(options.planArtifactPath, options.projectRoot ?? null);
+
+  let receipt = existing.planPreauthorization;
+  if (receipt !== null && receipt.status === "pending") {
+    receipt = { ...receipt, status: "invalidated", reason: "ordinary_approval_used" };
+  }
+
+  return setDeliveryCursor(
+    db,
+    {
+      journey,
+      method,
+      activeItem: existing.activeItem,
+      activeItemTitle: existing.activeItemTitle,
+      activeItemLevel: existing.activeItemLevel,
+      activeCheckpoint: null,
+      pendingConfirmation: null,
+      lastDeliveryEvent: "plan_approved",
+      cadenceProfile: existing.cadenceProfile,
+      cadenceLimits: existing.cadenceLimits,
+      granularityDecision: existing.granularityDecision,
+      navigatorFlowUnit: existing.navigatorFlowUnit,
+      childWorkItems: existing.childWorkItems,
+      aggregateCheckpointStatus: existing.aggregateCheckpointStatus,
+      cursorGeneration: existing.cursorGeneration,
+      planPreauthorization: setTo(receipt),
+    },
+    deps,
+  );
+}
+
+/** Python `render_plan_approval`. */
+export function renderPlanApproval(cursor: BuilderDeliveryCursor): string {
+  const body = `${[
+    "Delivery",
+    renderLifecycleRibbon("implement", cursor.activeItemLevel),
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    "│        🟩■  PLAN APPROVED                              │",
+    "│                                                        │",
+    cardText("active item"),
+    cardText(cursor.activeItem ?? "none"),
+    "│                                                        │",
+    cardText("last delivery event"),
+    cardText(cursor.lastDeliveryEvent ?? "none"),
+    "│                                                        │",
+    cardText("boundary"),
+    ...cardWrapped("Implementation may begin under the approved Plan contract."),
+    "╰────────────────────────────────────────────────────────╯",
+  ].join("\n")}\n`;
+  return wrapAriadSurface("plan_approved", body);
+}

package/ts/src/builder/argv.ts

@@ -0,0 +1,292 @@
+// CV22.DS7.US8 — validated Builder argv → ported command leaf.
+//
+// Plateau 8 promotes the mapping used by the command corpus and lifecycle smoke
+// into production. `frontDoor/buildRoute.ts` owns validation and argparse-class
+// exit-2 refusals; this module owns the single argv-to-command mapping used by
+// production, goldens, and smokes so those callers cannot drift.
+//
+// `--check`, `--debt`, and `--difference` are `action="append"` in `build.py`, so
+// every occurrence contributes; `--preauthorize-approval`, `--navigator-accepted`,
+// `--implementation-complete`, and `--use-preauthorization` are `store_true`, so
+// their PRESENCE is the value — reading either kind as a single option would
+// swallow the following token.
+
+import {
+  type CommandResult,
+  runAdoptMethod,
+  runApproveDeliveryStoryPlan,
+  runApprovePlan,
+  runCancelDeliveryStoryPlanPreauthorization,
+  runCancelPlanPreauthorization,
+  runCheckImplementation,
+  runCoherenceDeliveryStory,
+  runCoherenceItem,
+  runContinueLifecycle,
+  runDoneDeliveryStory,
+  runDoneItem,
+  runInspectMethod,
+  runPlanDeliveryStory,
+  runPlanItem,
+  runPrepareItem,
+  runPrepareTemplates,
+  runPullCandidates,
+  runPullItem,
+  runReleaseIntent,
+  runReviewDeliveryStory,
+  runReviewItem,
+  runSetCadence,
+  runSetFlowUnit,
+  runShowCheckpoint,
+  runSyncCursor,
+  runValidateDeliveryStory,
+  runValidateItem,
+} from "#builder/commands.ts";
+import { StoryPackageAmbiguityError } from "#builder/storyPaths.ts";
+import type { Database, WritableDatabase } from "#db/database.ts";
+
+export interface BuilderInvokeDeps {
+  /** The clock the cursor writes stamp with. A test pins it; the smoke does not. */
+  readonly nowIso: () => string;
+  /** `MIRROR_SESSION_ID`, passed in rather than read, as every TS route does. */
+  readonly environmentSessionId?: string | null;
+}
+
+/** Raised for an argv this mapping does not carry, so a gap cannot pass silently. */
+export class UnsupportedBuilderArgvError extends Error {}
+
+/** The Builder leaves that never write and therefore need no live backup. */
+export const READ_ONLY_BUILDER_SUBCOMMANDS = new Set([
+  "inspect-method",
+  "pull-candidates",
+  "check-implementation",
+  "show",
+]);
+
+/**
+ * Two packages claiming one code is a roadmap defect for the Navigator to settle,
+ * not a crash (CR018). Every leaf that resolves the active item's package does so
+ * before its first write, so the answer is one `Error:` line, which, like every
+ * `Error:` line, claims nothing about what changed. Pull answers the same defect
+ * with `EXPAND_BLOCKED` before it gets here.
+ */
+function refusingDoubleClaims(leaf: () => CommandResult): CommandResult {
+  try {
+    return leaf();
+  } catch (error) {
+    if (!(error instanceof StoryPackageAmbiguityError)) throw error;
+    return { stdout: "", stderr: `Error: ${error.message}\n`, exitCode: 1 };
+  }
+}
+
+export function invokeReadOnlyBuilderArgv(
+  db: Database,
+  argv: readonly string[],
+  environmentSessionId?: string | null,
+): CommandResult {
+  return refusingDoubleClaims(() => readOnlyBuilderLeaf(db, argv, environmentSessionId));
+}
+
+export function invokeBuilderArgv(
+  db: WritableDatabase,
+  argv: readonly string[],
+  invokeDeps: BuilderInvokeDeps,
+): CommandResult {
+  return refusingDoubleClaims(() => builderLeaf(db, argv, invokeDeps));
+}
+
+function readOnlyBuilderLeaf(
+  db: Database,
+  argv: readonly string[],
+  environmentSessionId?: string | null,
+): CommandResult {
+  const option = (name: string): string | null => {
+    const index = argv.lastIndexOf(name);
+    return index === -1 ? null : (argv[index + 1] ?? null);
+  };
+  const positionals = argv.filter(
+    (token, index) => index > 0 && !token.startsWith("--") && !argv[index - 1]?.startsWith("--"),
+  );
+  const shared = {
+    method: option("--method") ?? "",
+    journey: option("--journey"),
+    sessionId: option("--session-id"),
+  };
+  const context = { db, environmentSessionId: environmentSessionId ?? null };
+  if (argv[0] === "inspect-method") {
+    return runInspectMethod(context, {
+      method: positionals[0] ?? null,
+      journey: shared.journey,
+      sessionId: shared.sessionId,
+    });
+  }
+  if (argv[0] === "pull-candidates") return runPullCandidates(context, shared);
+  if (argv[0] === "check-implementation") return runCheckImplementation(context, shared);
+  if (argv[0] === "show") return runShowCheckpoint(context, shared);
+  throw new UnsupportedBuilderArgvError(`unsupported read-only argv: ${argv.join(" ")}`);
+}
+
+function builderLeaf(
+  db: WritableDatabase,
+  argv: readonly string[],
+  invokeDeps: BuilderInvokeDeps,
+): CommandResult {
+  const option = (name: string): string | null => {
+    const index = argv.lastIndexOf(name);
+    return index === -1 ? null : (argv[index + 1] ?? null);
+  };
+  const appended = (name: string): string[] =>
+    argv.flatMap((token, index) => (token === name ? [argv[index + 1] ?? ""] : []));
+  const positionals = argv.filter(
+    (token, index) => index > 0 && !token.startsWith("--") && !argv[index - 1]?.startsWith("--"),
+  );
+  const environmentSessionId = invokeDeps.environmentSessionId ?? null;
+  const context = { db, environmentSessionId };
+  const writeContext = {
+    db,
+    environmentSessionId,
+    deps: {
+      nowIso: invokeDeps.nowIso,
+    },
+  };
+  const shared = {
+    method: option("--method") ?? "",
+    journey: option("--journey"),
+    sessionId: option("--session-id"),
+  };
+  switch (argv[0]) {
+    case "inspect-method":
+      return runInspectMethod(context, {
+        method: positionals[0] ?? null,
+        journey: shared.journey,
+        sessionId: shared.sessionId,
+      });
+    case "pull-candidates":
+      return runPullCandidates(context, shared);
+    case "adopt":
+      return runAdoptMethod(writeContext, shared);
+    case "prepare-templates":
+      return runPrepareTemplates(writeContext, shared);
+    case "sync-cursor":
+      return runSyncCursor(writeContext, shared);
+    case "check-implementation":
+      return runCheckImplementation(context, shared);
+    case "show":
+      return runShowCheckpoint(context, shared);
+    case "pull-item":
+      return runPullItem(writeContext, {
+        ...shared,
+        itemCode: option("--item-code") ?? "",
+        itemTitle: option("--item-title") ?? "",
+        itemLevel: option("--item-level") ?? "",
+        whyNow: option("--why-now") ?? "",
+      });
+    case "prepare-item":
+      return runPrepareItem(writeContext, shared);
+    case "plan-item":
+      return runPlanItem(writeContext, {
+        ...shared,
+        objective: option("--objective"),
+        preauthorizeApproval: argv.includes("--preauthorize-approval"),
+        stopAfter: option("--stop-after") ?? "navigator_validation",
+      });
+    case "approve-plan":
+      return runApprovePlan(writeContext, {
+        ...shared,
+        usePreauthorization: argv.includes("--use-preauthorization"),
+      });
+    case "cancel-plan-preauthorization":
+      return runCancelPlanPreauthorization(writeContext, shared);
+    case "validate-item":
+      return runValidateItem(writeContext, {
+        ...shared,
+        checks: appended("--check"),
+        checksStatus: option("--checks-status") ?? "not_run",
+        e2eDecision: option("--e2e-decision") ?? "not_required",
+        e2eEvidence: option("--e2e-evidence"),
+        navigatorRoute: option("--navigator-route"),
+        navigatorAccepted: argv.includes("--navigator-accepted"),
+        expectedObservation: option("--expected-observation"),
+        passCondition: option("--pass-condition"),
+        failCondition: option("--fail-condition"),
+        implementationComplete: argv.includes("--implementation-complete"),
+      });
+    case "review-item":
+      return runReviewItem(writeContext, {
+        ...shared,
+        debtFindings: appended("--debt"),
+        debtDecision: option("--decision") ?? "pending",
+        deferReason: option("--defer-reason"),
+        revisitTrigger: option("--revisit-trigger"),
+      });
+    case "coherence-item":
+      return runCoherenceItem(writeContext, {
+        ...shared,
+        processAlignment: option("--process"),
+        projectAlignment: option("--project"),
+        productAlignment: option("--product"),
+        localDifferences: appended("--local-difference"),
+      });
+    case "done-item":
+      return runDoneItem(writeContext, {
+        ...shared,
+        historyAction: option("--history-action"),
+        roadmapUpdate: option("--roadmap-update"),
+        nextRecommendation: option("--next-recommendation"),
+      });
+    // -- the aggregate leaves (plateau 5) ----------------------------------
+    case "set-flow-unit":
+      // `--unit` ABSENT is the inspect face, so it stays `null` rather than "".
+      return runSetFlowUnit(writeContext, { ...shared, unit: option("--unit") });
+    case "plan-delivery-story":
+      return runPlanDeliveryStory(writeContext, {
+        ...shared,
+        objective: option("--objective"),
+        children: appended("--child"),
+        preauthorizeApproval: argv.includes("--preauthorize-approval"),
+        stopAfter: option("--stop-after") ?? "navigator_validation",
+      });
+    case "approve-delivery-story-plan":
+      return runApproveDeliveryStoryPlan(writeContext, {
+        ...shared,
+        usePreauthorization: argv.includes("--use-preauthorization"),
+      });
+    case "cancel-delivery-story-plan-preauthorization":
+      return runCancelDeliveryStoryPlanPreauthorization(writeContext, shared);
+    case "validate-delivery-story":
+      return runValidateDeliveryStory(writeContext, {
+        ...shared,
+        summary: option("--summary"),
+        navigatorAccepted: argv.includes("--navigator-accepted"),
+      });
+    case "review-delivery-story":
+      return runReviewDeliveryStory(writeContext, {
+        ...shared,
+        decision: option("--decision"),
+        summary: option("--summary"),
+      });
+    case "coherence-delivery-story":
+      return runCoherenceDeliveryStory(writeContext, { ...shared, summary: option("--summary") });
+    case "done-delivery-story":
+      return runDoneDeliveryStory(writeContext, { ...shared, summary: option("--summary") });
+    // -- cadence, release intent, continuation (plateau 6) ------------------
+    case "set-cadence":
+      return runSetCadence(writeContext, {
+        ...shared,
+        profile: option("--profile"),
+        // `action="append"`, like `--check` and `--debt`.
+        limits: appended("--limit"),
+      });
+    case "release-intent":
+      // Absent `--intent` is the inspect face, so it stays `null` rather than "".
+      return runReleaseIntent(writeContext, { ...shared, intent: option("--intent") });
+    case "continue-lifecycle":
+      return runContinueLifecycle(writeContext, {
+        ...shared,
+        historyAction: option("--history-action"),
+        roadmapUpdate: option("--roadmap-update"),
+        nextRecommendation: option("--next-recommendation"),
+      });
+    default:
+      throw new UnsupportedBuilderArgvError(`unsupported argv: ${argv.join(" ")}`);
+  }
+}