// CV22.DS7.US8 plateau 1 — `build inspect-method` and `build pull-candidates`, // end to end. // // Port of `cmd_inspect_method`, `cmd_pull_candidates`, and the shared guards // `_reject_unknown_method`, `_resolve_builder_journey`, `_require_adopted_method` // from `src/memory/cli/build.py`. // // Nothing is routed here. These return a `CommandResult` rather than writing to // the process, so plateau 8's front door wires them and the tests can grade // stdout, stderr, and the exit code without a subprocess. // // `build check-implementation` is deliberately absent: it calls // `assert_implementation_allowed`, which reads the delivery cursor, so it belongs // with the cursor in plateau 2 rather than being half-ported here. // // The refusal taxonomy measured at plateau 1 applies directly (D3.17). Everything // in this module is CLASS B: a domain refusal at exit 1 whose `Error: …` text is a // byte-exact parity obligation. Class A — argparse's own exit 2 with usage text — // happens before any of this runs and is the front door's business. // // One ordering detail no surface reveals but every refusal depends on: the guards // run method-first, then journey resolution, then journey existence, then // adoption. So `pull-candidates --method bogus` with no journey reports the // METHOD error, and the same command with a valid method but no resolvable // journey reports the JOURNEY error. A port that resolves the journey first // reports the wrong one. import { existsSync } from "node:fs"; import { dirname, join } from "node:path"; import type { Database, WritableDatabase } from "#db/database.ts"; import { getIdentityContent } from "#identity/identityRead.ts"; import { getProjectPath } from "#journey/journeyStatus.ts"; import { getRuntimeSession, resolveNamedRuntimeSessionId } from "#mirror/runtimeSession.ts"; import { getSessionOperatingMode } from "#mode/operatingMode.ts"; import { PROGRAM } from "#util/program.ts"; import { pyRStrip } from "#util/pythonText.ts"; import { shellWord } from "#util/shellWord.ts"; import { CLOSURE_RECORDS, renderActiveCheckpoint } from "./activeCheckpoint.ts"; import { approvePlanCheckpoint, renderPlanApproval } from "./approve.ts"; import { getAriadMethod } from "./ariadMethod.ts"; import { type MaterializedArtifact, renderArtifactsMaterializedSurface, } from "./artifacts/artifactSurfaces.ts"; import type { ArtifactOutcome } from "./artifacts/artifactWriter.ts"; import { planPackageArtifacts } from "./artifacts/planArtifacts.ts"; import { judgeStoryFiles } from "./artifacts/storyFiles.ts"; import { effectiveCadenceProfile } from "./cadence.ts"; import { CARD_WIDTH, cardText, wrapPlainText } from "./card.ts"; import { renderCheckpointRefused } from "./checkpointRefused.ts"; import { coherenceLifecycleItem, doneLifecycleItem, renderCoherenceCheckpoint, renderDoneCheckpoint, renderReviewCheckpoint, renderValidationCheckpoint, reviewLifecycleItem, validateLifecycleItem, } from "./closure.ts"; import { type BuilderDeliveryCursor, type CursorWriteDeps, getDeliveryCursor, renderDeliveryCursorSyncReport, setDeliveryCursor, } from "./deliveryCursor.ts"; import { closureArtifactManifest, coherenceDeliveryStory, type DeliveryStoryClosureReport, doneDeliveryStory, renderDeliveryStoryClosureReport, reviewDeliveryStory, validateDeliveryStory, } from "./deliveryStoryClosure.ts"; import { approveDeliveryStoryPlan, cancelDeliveryStoryPlanPreauthorization, planDeliveryStoryCheckpoint, renderDeliveryStoryImplementationStarted, renderDeliveryStoryPlanReport, renderPlanPreauthorizationMismatch, renderPlanPreauthorizationRecorded, } from "./deliveryStoryPlan.ts"; import { renderDeliveryStoryReadyReport } from "./deliveryStoryReady.ts"; import { inspectAuthoredClosure } from "./deliveryStoryRoadmapClosure.ts"; import { ExpandBlockedError, expandDeliveryStory, renderExpandBlocked } from "./expand.ts"; import { inspectNavigatorFlowUnit, renderFlowUnitScopeConfirmationReport, renderNavigatorFlowUnitReport, setNavigatorFlowUnit, } from "./flowUnit.ts"; import { assertImplementationAllowed, ImplementationBlockedError, renderImplementationGuardAllowed, renderImplementationGuardBlocked, } from "./implementationGuard.ts"; import { LifecycleRefusal } from "./lifecycleRefusal.ts"; import { renderLifecycleRibbon } from "./lifecycleRibbon.ts"; import { getAdoptedMethod, setAdoptedMethod } from "./methodAdoption.ts"; import { AVAILABLE_METHODS, renderAvailableMethod, renderJourneyMethodState, renderMethodAdoptionReport, renderNoJourneyNamed, } from "./methodInspection.ts"; import { planLifecycleItem, renderPlanCheckpoint } from "./plan.ts"; import { PlanPreauthorizationMismatch } from "./planPreauthorization.ts"; import { prepareLifecycleItem, projectContractRules, renderPrepareReport } from "./prepare.ts"; import { displayPath } from "./projectPaths.ts"; import { placementCvTitle, pullLifecycleItem, pullPlacement, renderPullReport } from "./pull.ts"; import { inspectPullCandidates, inspectRoadmapSnapshot } from "./pullCandidates.ts"; import { renderProjectPositionReport, renderPullCandidatesReport, renderRoadmapSnapshotReport, } from "./pullCandidatesRender.ts"; import { inspectReleaseIntent, renderReleaseIntentReport, setReleaseIntent, } from "./releaseIntent.ts"; import { resolveRoadmapScope, type ScopedPullCandidates, scopePullCandidates, siblingsOf, } from "./roadmapScope.ts"; import { createStoryDirectory, resolveStoryDirectory, StoryPackageAmbiguityError, } from "./storyPaths.ts"; import { approveStoryPlanWithPreauthorization, cancelStoryPlanPreauthorization, renderStoryImplementationStarted, renderStoryPlanPreauthorizationMismatch, renderStoryPlanPreauthorizationRecorded, renderStoryPreauthorizationAlreadyConsumed, } from "./storyPlanPreauthorization.ts"; import { wrapAriadSurface } from "./surfaceProtocol.ts"; import { prepareMethodTemplates, renderTemplatePreparationReport } from "./templateGeneration.ts"; /** What a `build` leaf produced, without touching the process. */ export interface CommandResult { readonly stdout: string; readonly stderr: string; readonly exitCode: number; } /** * Python `print(text)` — the value PLUS the newline `print` adds. * * Every renderer here already ends in `\n`, so each surface leaves a blank line * behind it and the stream ends with TWO newlines. That is not a quirk worth * smoothing: it is the byte a shell sees, and reproducing the expression Python * passes to `print` while forgetting `print` itself is one byte short on every * invocation. Measured against the real CLI in a subprocess, not reasoned about. */ function printed(text: string): string { return `${text}\n`; } const IDENTITY_JOURNEY_LAYER = "journey"; export interface BuilderCommandContext { readonly db: Database; /** `MIRROR_SESSION_ID`, passed in rather than read, as every TS route does. */ readonly environmentSessionId?: string | null; } /** The context the writing leaves need: a writable handle and a clock. */ export interface BuilderWriteContext { readonly db: WritableDatabase; readonly environmentSessionId?: string | null; readonly deps: CursorWriteDeps; } /** Python's `print(message, file=sys.stderr); sys.exit(1)` pair. */ function refuse(message: string): CommandResult { return { stdout: "", stderr: printed(message), exitCode: 1 }; } /** Python `_reject_unknown_method`. */ function rejectUnknownMethod(method: string): CommandResult | null { if (method === "ariad") return null; return refuse( `Error: Builder method '${method}' not found. Available methods: ${AVAILABLE_METHODS.join(", ")}`, ); } /** * The Builder journey of the session the caller NAMED (`--session-id` or * `MIRROR_SESSION_ID`), or null. * * Never a guessed session and never the global mode row (CR008): either can hold * another window's journey, and binding to it wrote that journey's cursor and * materialized files into its project. A named session that has ended, or that * is in another mode, names no journey. * * Decision C (CR008): when no session is named, `build load` still stamps a * GUESSED session, so each window's footer shows its own mode. A named session's * stamp may therefore have been written by another window's load. Since * CV9.DS8.US5 runtimes name their sessions (Pi sets `MIRROR_SESSION_ID`; the * Claude-family readers came with US4), so option B holds here: a stamp binds * only when it records that it was written under the name * (`OperatingModeState.namedSession`). A guessed stamp on a named session is * the footer's business, not a journey. */ function namedSessionBuilderJourney( context: BuilderCommandContext, sessionId: string | null, ): string | null { const named = resolveNamedRuntimeSessionId(sessionId, context.environmentSessionId ?? null); if (!named || !getRuntimeSession(context.db, named)?.active) return null; const state = getSessionOperatingMode(context.db, named); return state?.mode === "Builder Mode" && state.journey && state.namedSession === true ? state.journey : null; } /** * The journey a Builder leaf acts on: the explicit `--journey`, else the Builder * journey of a named session. Nothing else. With neither, the leaf refuses * before it reads a cursor or writes a file. * * This departs from Python's `_resolve_builder_journey` on purpose (CR008). * Python fell back to the most recently touched session and then the global * mode row, and an agent shell names no session, so every lifecycle command * without `--journey` was bound by a guess. */ function resolveBuilderJourney( context: BuilderCommandContext, options: { journey: string | null; sessionId: string | null; action: string }, ): { journey: string } | CommandResult { if (options.journey) return { journey: options.journey }; const journey = namedSessionBuilderJourney(context, options.sessionId); if (journey) return { journey }; return refuse( `Error: Builder method ${options.action} requires a journey. ` + "Pass --journey , or name a session in Builder Mode with --session-id or MIRROR_SESSION_ID.", ); } function isCommandResult(value: unknown): value is CommandResult { return typeof value === "object" && value !== null && "exitCode" in value; } /** Python's `mem.get_identity("journey", slug)` existence guard. */ function requireJourney(db: Database, journey: string): CommandResult | null { const content = getIdentityContent(db, IDENTITY_JOURNEY_LAYER, journey); if (content) return null; return refuse(`Error: journey '${journey}' not found.`); } /** Python `_require_adopted_method`. */ function requireAdoptedMethod(db: Database, journey: string, method: string): CommandResult | null { if (getAdoptedMethod(db, journey) === method) return null; return refuse( `Error: journey '${journey}' has not adopted Ariad yet. ` + `Run: ${PROGRAM} build adopt --journey ${shellWord(journey)} --method ariad`, ); } /** * Python `cmd_inspect_method`. * * Three shapes, and the order of the branches is the behavior: * * * `--journey X` given -> that journey's state, after an existence check. The * positional method is IGNORED in this branch, so `inspect-method ariad * --journey j` renders the journey state rather than the method definition. * * no positional method -> the Builder journey of a NAMED session if there is * one, else the no-journey card. Never an error, and never a guess (CR008). * * a positional method -> the built-in definition, or a Class B refusal. */ export function runInspectMethod( context: BuilderCommandContext, options: { method?: string | null; journey?: string | null; sessionId?: string | null } = {}, ): CommandResult { const method = options.method ?? null; const journey = options.journey ?? null; if (journey) { const missing = requireJourney(context.db, journey); if (missing) return missing; return { stdout: printed(renderJourneyMethodState(journey, getAdoptedMethod(context.db, journey))), stderr: "", exitCode: 0, }; } if (method === null) { const named = namedSessionBuilderJourney(context, options.sessionId ?? null); if (named) { return { stdout: printed(renderJourneyMethodState(named, getAdoptedMethod(context.db, named))), stderr: "", exitCode: 0, }; } return { stdout: printed(renderNoJourneyNamed()), stderr: "", exitCode: 0 }; } const unknown = rejectUnknownMethod(method); if (unknown) return unknown; return { stdout: printed(renderAvailableMethod(getAriadMethod())), stderr: "", exitCode: 0 }; } /** Python `_surfaces_for_trigger`: the surfaces a DSL route declares for a trigger. */ export function surfacesForTrigger(trigger: string): readonly string[] { for (const route of getAriadMethod().surfaceRoutes) { if (route.trigger === trigger) return route.surfaces; } return []; } /** * Python `cmd_pull_candidates`. * * Which surfaces appear is decided by the DSL, not by the command: the * `show_roadmap` surface route names them, so removing `roadmap_snapshot` from * `ariadMethod.ts` would drop that block from this output. That indirection is * the method DSL doing its job and is preserved. * * The join is Python's exactly: each part is `rstrip()`ed, joined with a single * newline, and ONE trailing newline is added — so two surfaces are separated by * the newline that ends the first one, with no blank line between them. */ export function runPullCandidates( context: BuilderCommandContext, options: { method: string; journey?: string | null; sessionId?: string | null }, ): CommandResult { const unknown = rejectUnknownMethod(options.method); if (unknown) return unknown; const resolved = resolveBuilderJourney(context, { journey: options.journey ?? null, sessionId: options.sessionId ?? null, action: "pull candidates inspection", }); if (isCommandResult(resolved)) return resolved; const journey = resolved.journey; const missing = requireJourney(context.db, journey); if (missing) return missing; const notAdopted = requireAdoptedMethod(context.db, journey, options.method); if (notAdopted) return notAdopted; const projectPath = getProjectPath(context.db, journey); const root = projectPath || null; const surfaces = surfacesForTrigger("show_roadmap"); const rendered: string[] = []; const view = journeyCandidateView(context.db, journey, root, options.method); if (surfaces.includes("roadmap_snapshot")) { rendered.push( renderRoadmapSnapshotReport( inspectRoadmapSnapshot(root, { journey, method: options.method }), { view }, ), ); } if (surfaces.includes("pull_candidates")) { rendered.push(renderPullCandidatesReport(view)); } return { stdout: printed(`${rendered.map((part) => pyRStrip(part)).join("\n")}\n`), stderr: "", exitCode: 0, }; } /** * Python `cmd_adopt_method`. * * `already_adopted` is computed BEFORE the write, so re-adopting Ariad reports * "was already adopted" while a first adoption reports "is now adopted" — and * switching from another method reports "is now", because the comparison is * against the method being adopted rather than against any adoption at all. */ export function runAdoptMethod( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null }, ): CommandResult { const unknown = rejectUnknownMethod(options.method); if (unknown) return unknown; const resolved = resolveBuilderJourney(context, { journey: options.journey ?? null, sessionId: options.sessionId ?? null, action: "adoption", }); if (isCommandResult(resolved)) return resolved; const journey = resolved.journey; const missing = requireJourney(context.db, journey); if (missing) return missing; const alreadyAdopted = getAdoptedMethod(context.db, journey) === options.method; const adoption = setAdoptedMethod(context.db, journey, options.method, context.deps.nowIso); return { stdout: printed( renderMethodAdoptionReport(adoption.journey, adoption.method, { alreadyAdopted }), ), stderr: "", exitCode: 0, }; } /** * Python `cmd_prepare_templates`. * * The only leaf in this plateau that writes into the user's repository, and the * only one with a fifth guard: a journey with no `project_path` is refused rather * than defaulted, because there is nowhere safe to write. */ export function runPrepareTemplates( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null }, ): CommandResult { const unknown = rejectUnknownMethod(options.method); if (unknown) return unknown; const resolved = resolveBuilderJourney(context, { journey: options.journey ?? null, sessionId: options.sessionId ?? null, action: "template preparation", }); if (isCommandResult(resolved)) return resolved; const journey = resolved.journey; const missing = requireJourney(context.db, journey); if (missing) return missing; const notAdopted = requireAdoptedMethod(context.db, journey, options.method); if (notAdopted) return notAdopted; const projectPath = getProjectPath(context.db, journey); if (!projectPath) { return refuse( `Error: journey '${journey}' has no project_path configured. ` + "Set a project path before preparing Ariad templates.", ); } const report = prepareMethodTemplates(projectPath, { journey, method: getAriadMethod() }); return { stdout: printed(renderTemplatePreparationReport(report)), stderr: "", exitCode: 0 }; } /** * Python `cmd_sync_cursor`. * * The written cursor is fixed, not derived: `last_delivery_event` is always * `template_preparation` and `cadence_profile` always `stepwise`, and no active * item is inferred. Running it on a journey that already has a cursor therefore * RESETS those two fields while carrying the generation forward — which is the * cursor's own carry-forward rule, not something this command decides. */ export function runSyncCursor( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null }, ): CommandResult { const unknown = rejectUnknownMethod(options.method); if (unknown) return unknown; const resolved = resolveBuilderJourney(context, { journey: options.journey ?? null, sessionId: options.sessionId ?? null, action: "cursor sync", }); if (isCommandResult(resolved)) return resolved; const journey = resolved.journey; const missing = requireJourney(context.db, journey); if (missing) return missing; const notAdopted = requireAdoptedMethod(context.db, journey, options.method); if (notAdopted) return notAdopted; const cursor = setDeliveryCursor( context.db, { journey, method: options.method, lastDeliveryEvent: "template_preparation", cadenceProfile: "stepwise", }, context.deps, ); return { stdout: printed(renderDeliveryCursorSyncReport(cursor)), stderr: "", exitCode: 0 }; } /** * Python `cmd_check_implementation`. * * The only leaf whose REFUSAL prints a surface on stdout rather than a message on * stderr: a blocked guard renders `IMPLEMENTATION_GUARD` to stdout and still exits * 1. A port that routes the block through the ordinary `refuse` helper loses the * surface the transport protocol requires to be rendered verbatim. */ export function runCheckImplementation( context: BuilderCommandContext, options: { method: string; journey?: string | null; sessionId?: string | null }, ): CommandResult { const unknown = rejectUnknownMethod(options.method); if (unknown) return unknown; const resolved = resolveBuilderJourney(context, { journey: options.journey ?? null, sessionId: options.sessionId ?? null, action: "implementation check", }); if (isCommandResult(resolved)) return resolved; const journey = resolved.journey; const missing = requireJourney(context.db, journey); if (missing) return missing; const notAdopted = requireAdoptedMethod(context.db, journey, options.method); if (notAdopted) return notAdopted; try { const cursor = assertImplementationAllowed(context.db, journey); return { stdout: printed(renderImplementationGuardAllowed(cursor)), stderr: "", exitCode: 0, }; } catch (error) { if (!(error instanceof ImplementationBlockedError)) throw error; return { stdout: printed( renderImplementationGuardBlocked( error.message, getDeliveryCursor(context.db, journey)?.activeItemLevel ?? null, ), ), stderr: "", exitCode: 1, }; } } /** * CR067 with CR020: the journey's active checkpoint, shown again. Read-only by * construction: it takes the read context, and the front door runs it on a read-only * database handle like every leaf in `READ_ONLY_BUILDER_SUBCOMMANDS`. */ export function runShowCheckpoint( context: BuilderCommandContext, options: { method: string; journey?: string | null; sessionId?: string | null }, ): CommandResult { const unknown = rejectUnknownMethod(options.method); if (unknown) return unknown; const resolved = resolveBuilderJourney(context, { journey: options.journey ?? null, sessionId: options.sessionId ?? null, action: "checkpoint display", }); if (isCommandResult(resolved)) return resolved; const journey = resolved.journey; const missing = requireJourney(context.db, journey); if (missing) return missing; const notAdopted = requireAdoptedMethod(context.db, journey, options.method); if (notAdopted) return notAdopted; const cursor = getDeliveryCursor(context.db, journey); const projectPath = getProjectPath(context.db, journey); const plan = cursor?.activeItem ? closureArtifactPath(projectPath, cursor, "plan.md") : null; const records = plan === null ? null : { folder: displayPath(dirname(plan), projectPath), artifacts: judgeStoryFiles(dirname(plan)), present: new Set(CLOSURE_RECORDS.filter((name) => existsSync(join(dirname(plan), name)))), }; return { stdout: printed(renderActiveCheckpoint({ journey, cursor, records })), stderr: "", exitCode: 0, }; } // --- plateau 3: the story-lifecycle leaves --------------------------------- // // Port of `cmd_pull_item`, `cmd_prepare_item`, `cmd_plan_item`, `cmd_approve_plan`, // and `cmd_cancel_story_plan_preauthorization`. // // These are the first leaves whose guard chain has a FIFTH link: after method, // journey resolution, journey existence, and adoption comes // `_require_delivery_cursor`. Its position matters — two refusals that look like // they belong to the lifecycle (`active item is required before prepare`, the // Delivery Story project-path error) sit BEHIND it, so a port that checks the // cursor last reports the wrong refusal for a journey that never ran `sync-cursor`. // // `pull-item` is also the only leaf here that composes: it runs Pull, then Prepare // unconditionally, then for a Delivery Story it runs Expand and renders the // composite `DELIVERY_STORY_READY` surface INSTEAD of the Pull and Prepare // surfaces. Emitting all three is a duplicate-surface defect no renderer-level test // can see. /** * The journey's scoped candidate view (CR002), from its persisted cursor. After a * Done write the closure verbs carry the active item forward, so the scope is the * CV of the item that just closed and "what looks next" stays inside it. */ function journeyCandidateView( db: Database, journey: string, projectPath: string | null, method: string, ): ScopedPullCandidates { const scope = resolveRoadmapScope(projectPath || null, getDeliveryCursor(db, journey)); return scopePullCandidates(inspectPullCandidates(projectPath, { journey, method }), scope); } /** Python `_require_delivery_cursor`. */ function requireDeliveryCursor(db: Database, journey: string): CommandResult | null { if (getDeliveryCursor(db, journey) !== null) return null; return refuse( `Error: journey '${journey}' has no Builder delivery cursor. ` + `Run: ${PROGRAM} build sync-cursor --journey ${shellWord(journey)} --method ariad`, ); } /** The four guards every lifecycle leaf runs, in Python's order. */ function lifecycleGuards( context: BuilderCommandContext, options: { method: string; journey?: string | null; sessionId?: string | null; action: string; requireCursor: boolean; }, ): { journey: string } | CommandResult { const unknown = rejectUnknownMethod(options.method); if (unknown) return unknown; const resolved = resolveBuilderJourney(context, { journey: options.journey ?? null, sessionId: options.sessionId ?? null, action: options.action, }); if (isCommandResult(resolved)) return resolved; const journey = resolved.journey; const missing = requireJourney(context.db, journey); if (missing) return missing; const notAdopted = requireAdoptedMethod(context.db, journey, options.method); if (notAdopted) return notAdopted; if (options.requireCursor) { const noCursor = requireDeliveryCursor(context.db, journey); if (noCursor) return noCursor; } return { journey }; } /** * Python's `except ValueError as exc: print(f"Error: {exc}", file=sys.stderr)`. * * The two roadmap errors pass through: Pull renders both as `EXPAND_BLOCKED`, and * anywhere else the dispatcher answers a double claim with its own `Error:` line * (CR018). */ function refuseValueError(error: unknown): CommandResult { if (error instanceof StoryPackageAmbiguityError || error instanceof ExpandBlockedError) throw error; return refuse(`Error: ${(error as Error).message}`); } /** Python `_canonical_package_path`: resolve the authored package, else create it. */ function canonicalPackagePath( projectPath: string | null, cursor: { activeItem: string | null; activeItemTitle: string | null } | null, ): string | null { const activeItem = cursor?.activeItem ?? null; if (!projectPath || !activeItem) return null; const resolved = resolveStoryDirectory(projectPath, activeItem); if (resolved !== null) return resolved; return createStoryDirectory(projectPath, activeItem, cursor?.activeItemTitle || activeItem); } /** Python `_artifact_existence`: sampled BEFORE the write, or preservation is invisible. */ function artifactExistence(planPath: string | null): Map { const existence = new Map(); if (planPath === null) return existence; const directory = dirname(planPath); for (const path of [join(directory, "index.md"), planPath, join(directory, "test-guide.md")]) { existence.set(path, existsSync(path)); } return existence; } /** The surface's last word on a closure record, true to what the writer did (CR079). */ function closureBoundary(label: string, outcome: ArtifactOutcome | null | undefined): string { return outcome === "preserved" ? `${label} artifact was preserved as it is: Ariad did not write it, or it was edited since. ` + "This checkpoint's fields are above, not in the file." : `${label} artifact was materialized.`; } /** Python `_print_artifacts_materialized`: no artifacts means NO surface, not an empty one. */ function artifactsSurface(options: { context: string; artifacts: readonly MaterializedArtifact[]; projectPath: string | null; journey: string; boundary: string; }): string { if (options.artifacts.length === 0) return ""; return printed( renderArtifactsMaterializedSurface({ context: options.context, artifacts: options.artifacts, projectPath: options.projectPath, journey: options.journey, boundary: options.boundary, }), ); } /** * Python `_roadmap_plan_context`, reduced to the two facts only the roadmap holds * (CR111 D3): the active candidate's whole title (CR018), and its SIBLINGS' titles, * which Plan names as Non-Goals. Siblings are the other children of the same parent, * never an ancestor or a cousin (CR019). The sentences are the scaffold model's, filled * by `planLifecycleItem`; without a roadmap title it takes the title Pull recorded (D5). */ function roadmapPlanFacts( projectPath: string | null, cursor: { activeItem: string | null } | null, ): { title: string | null; siblings: string[] } { const activeItem = cursor?.activeItem ?? null; if (!projectPath || !activeItem) return { title: null, siblings: [] }; const candidates = inspectPullCandidates(projectPath, { journey: "", method: "ariad", }).candidates; const active = candidates.find((candidate) => candidate.code === activeItem); if (!active) return { title: null, siblings: [] }; return { title: active.title || null, siblings: siblingsOf(candidates, activeItem).map((candidate) => candidate.title), }; } /** Python `cmd_pull_item`. */ export function runPullItem( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null; itemCode: string; itemTitle: string; itemLevel: string; whyNow: string; }, ): CommandResult { const guarded = lifecycleGuards(context, { ...options, action: "pull", requireCursor: true }); if (isCommandResult(guarded)) return guarded; const journey = guarded.journey; let pullReport: ReturnType; try { pullReport = pullLifecycleItem( context.db, { journey, method: options.method, item: { code: options.itemCode, title: options.itemTitle, level: options.itemLevel, whyNow: options.whyNow, }, }, context.deps, ); } catch (error) { return refuseValueError(error); } const projectPath = getProjectPath(context.db, journey); // Prepare runs unconditionally, and OUTSIDE the try above: Python lets a Prepare // failure raise rather than reporting it as a Pull refusal. const prepareReport = prepareLifecycleItem( context.db, { journey, method: options.method, projectPath }, context.deps, ); if (options.itemLevel === "delivery_story") { if (!projectPath) { return refuse("Error: Delivery Story expansion requires project_path."); } let expandReport: ReturnType; try { expandReport = expandDeliveryStory( context.db, { journey, method: options.method, projectPath }, context.deps, ); } catch (error) { if (error instanceof ExpandBlockedError || error instanceof StoryPackageAmbiguityError) { // The refusal renders a SURFACE on stdout and still exits 1. return { stdout: printed(renderExpandBlocked(options.itemCode, error.message)), stderr: "", exitCode: 1, }; } return refuseValueError(error); } const stdout = printed( renderDeliveryStoryReadyReport({ pull: pullReport, prepare: prepareReport, expand: expandReport, cvTitle: placementCvTitle(projectPath, pullReport.cursor), }), ) + artifactsSurface({ context: `Expand — ${expandReport.deliveryStory}`, artifacts: expandReport.materializedArtifacts, projectPath, journey, boundary: "Files were materialized only. No Plan or implementation was executed.", }); return { stdout, stderr: "", exitCode: 0 }; } return { stdout: printed(renderPullReport(pullReport, pullPlacement(projectPath, pullReport.cursor))) + printed(renderPrepareReport(prepareReport)), stderr: "", exitCode: 0, }; } /** Python `cmd_prepare_item`. */ export function runPrepareItem( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null }, ): CommandResult { const guarded = lifecycleGuards(context, { ...options, action: "prepare", requireCursor: true }); if (isCommandResult(guarded)) return guarded; const journey = guarded.journey; const projectPath = getProjectPath(context.db, journey); try { const report = prepareLifecycleItem( context.db, { journey, method: options.method, projectPath }, context.deps, ); return { stdout: printed(renderPrepareReport(report)), stderr: "", exitCode: 0 }; } catch (error) { // CR114 (D3): a Prepare past its place is refused where the cursor stands. if (error instanceof LifecycleRefusal) { return refusedSurface(context.db, journey, "prepare-item", error); } return refuseValueError(error); } } /** Python `cmd_plan_item`. */ export function runPlanItem( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null; objective?: string | null; preauthorizeApproval?: boolean; stopAfter?: string; }, ): CommandResult { const guarded = lifecycleGuards(context, { ...options, action: "plan", requireCursor: true }); if (isCommandResult(guarded)) return guarded; const journey = guarded.journey; const projectPath = getProjectPath(context.db, journey); const cursor = getDeliveryCursor(context.db, journey); const planPath = canonicalPackagePath(projectPath, cursor); const planArtifactPath = planPath === null ? null : join(planPath, "plan.md"); const existedBefore = artifactExistence(planArtifactPath); const roadmap = roadmapPlanFacts(projectPath, cursor); try { const report = planLifecycleItem( context.db, { journey, method: getAriadMethod(), objective: options.objective || null, title: roadmap.title, siblings: roadmap.siblings, localRules: projectContractRules(projectPath), planArtifactPath, projectRoot: projectPath, preauthorize: options.preauthorizeApproval ?? false, stopBoundary: options.stopAfter ?? "navigator_validation", }, context.deps, ); const authority = report.preauthorizationRecorded ? printed(renderStoryPlanPreauthorizationRecorded(report.cursor)) : ""; const stdout = printed(renderPlanCheckpoint(report)) + authority + artifactsSurface({ context: `Plan — ${report.activeItem}`, artifacts: planPackageArtifacts(report.planArtifactPath, existedBefore), projectPath, journey, boundary: "Plan artifacts were materialized. Implementation remains blocked until approval.", }); return { stdout, stderr: "", exitCode: 0 }; } catch (error) { if (error instanceof LifecycleRefusal) { return refusedSurface(context.db, journey, "plan-item", error); } return refuseValueError(error); } } /** * Python `cmd_approve_plan`. * * Note the guard chain: approval does NOT require a delivery cursor up front — the * lifecycle call reports that itself — so a journey with no cursor reports * `delivery cursor is required before plan approval`, not the `sync-cursor` hint. */ export function runApprovePlan( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null; usePreauthorization?: boolean; }, ): CommandResult { const guarded = lifecycleGuards(context, { ...options, action: "plan approval", requireCursor: false, }); if (isCommandResult(guarded)) return guarded; const journey = guarded.journey; try { if (options.usePreauthorization === true) { const cursor = getDeliveryCursor(context.db, journey); const projectPath = getProjectPath(context.db, journey); const packagePath = canonicalPackagePath(projectPath, cursor); const report = approveStoryPlanWithPreauthorization( context.db, { journey, method: options.method, planArtifactPath: packagePath === null ? null : join(packagePath, "plan.md"), }, context.deps, ); if (report.status === "already_approved") { return { stdout: printed(renderStoryPreauthorizationAlreadyConsumed(report.cursor)), stderr: "", exitCode: 0, }; } return { stdout: printed(renderPlanApproval(report.cursor)) + printed(renderStoryImplementationStarted(report.cursor)), stderr: "", exitCode: 0, }; } const projectPath = getProjectPath(context.db, journey); const cursor = approvePlanCheckpoint( context.db, { journey, method: options.method, planArtifactPath: closureArtifactPath( projectPath, getDeliveryCursor(context.db, journey), "plan.md", ), projectRoot: projectPath, }, context.deps, ); return { stdout: printed(renderPlanApproval(cursor)), stderr: "", exitCode: 0 }; } catch (error) { if (error instanceof PlanPreauthorizationMismatch) { // Exit 0, not 1: a mismatch is a bounded fallback to ordinary approval, and // the surface says so. Treating it as a failure would tell the Navigator the // command broke. const cursor = getDeliveryCursor(context.db, journey); return { stdout: printed( renderStoryPlanPreauthorizationMismatch({ activeItem: cursor?.activeItem ?? null, reason: error.reason, toAuthor: error.sections, }), ), stderr: "", exitCode: 0, }; } if (error instanceof LifecycleRefusal) { return refusedSurface(context.db, journey, "approve-plan", error); } return refuseValueError(error); } } /** * Python `cmd_cancel_story_plan_preauthorization`. * * The one leaf that skips the journey-existence check: Python's version never calls * `get_identity`, so a nonexistent journey reaches the adoption guard instead. */ export function runCancelPlanPreauthorization( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null }, ): CommandResult { const unknown = rejectUnknownMethod(options.method); if (unknown) return unknown; const resolved = resolveBuilderJourney(context, { journey: options.journey ?? null, sessionId: options.sessionId ?? null, action: "story Plan preauthorization cancellation", }); if (isCommandResult(resolved)) return resolved; const journey = resolved.journey; const notAdopted = requireAdoptedMethod(context.db, journey, options.method); if (notAdopted) return notAdopted; try { const cursor = cancelStoryPlanPreauthorization( context.db, { journey, method: options.method }, context.deps, ); return { stdout: printed( renderStoryPlanPreauthorizationMismatch({ activeItem: cursor.activeItem, reason: "navigator_cancelled", }), ), stderr: "", exitCode: 0, }; } catch (error) { return refuseValueError(error); } } // --- plateau 4: the closure leaves ----------------------------------------- // // Port of `cmd_validate_item`, `cmd_review_item`, `cmd_coherence_item`, and // `cmd_done_item`. // // Their refusal shape differs from every other lifecycle leaf: a blocked lifecycle // call renders IMPLEMENTATION_GUARD on STDOUT and exits 1, rather than printing // `Error: …` to stderr. Routing these through `refuse` would lose a surface the // transport protocol requires to be rendered verbatim — the same trap // `check-implementation` set at plateau 2. // // Two of them emit a SECOND, CLI-only surface on the complete path: // `debt_review_started` after a passed Validation, and `done_closure_confirmation` // after a `no_action` Debt Review with nothing missing. Those two exist only here, not // in `lifecycle.py`, so the module-level corpus cannot see them. // // `done-item` additionally prints the project position after its checkpoint, which is // the Navigator's "where are we now" view and reads the roadmap a second time. /** Python `_mini_card_text`. */ function miniCardText(text: string): string { return cardText(text); } /** * Python `_mini_card_wrapped`. * * The NON-chunking wrapper: an over-long word overflows its row instead of being * split, unlike `cardWrapped`. Python keeps two `_wrap_plain_text` behaviors across * ten modules and this is one of the non-chunking ones, so the flag is explicit. */ function miniCardWrapped(text: string): string[] { return wrapPlainText(text, { width: CARD_WIDTH, chunkLongWords: false }).map(cardText); } /** Python `_render_debt_review_handoff`: a CLI-only surface with its own ribbon literal. */ // --- cadence, release intent, continuation (plateau 6) ---------------------- /** Python `cmd_set_cadence`'s allowed set, checked in the CLI rather than the DSL. */ const CADENCE_PROFILES = ["stepwise", "checkpoint", "accelerated", "autonomous"]; /** * Python `cmd_set_cadence`. * * No module: the whole leaf is the CLI function, and its guard ORDER is unlike * every other leaf here — method, then the PROFILE, then the autonomous-limits * rule, and only then journey resolution and adoption. So an unknown profile * against a journey that cannot be resolved reports the profile, not the journey. * The corpus pins that with `set_cadence_profile_guard_precedes_journey`. * * It also writes the cursor directly rather than through a lifecycle verb, which * is why it carries every other field forward by hand: cadence is a Navigator * preference, not a lifecycle transition. */ export function runSetCadence( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null; profile?: string | null; limits?: readonly string[]; }, ): CommandResult { const unknown = rejectUnknownMethod(options.method); if (unknown) return unknown; const profile = options.profile ?? ""; const limits = options.limits ?? []; if (!CADENCE_PROFILES.includes(profile)) { return refuse( "Error: cadence profile must be one of stepwise, checkpoint, accelerated, autonomous", ); } if (profile === "autonomous" && limits.length === 0) { return refuse("Error: autonomous cadence requires at least one --limit"); } const resolved = resolveBuilderJourney(context, { journey: options.journey ?? null, sessionId: options.sessionId ?? null, action: "cadence profile update", }); if (isCommandResult(resolved)) return resolved; const journey = resolved.journey; const notAdopted = requireAdoptedMethod(context.db, journey, options.method); if (notAdopted) return notAdopted; const cursor = getDeliveryCursor(context.db, journey); if (cursor === null) { // Its own message, not `_require_delivery_cursor`'s. return refuse(`Error: journey '${journey}' has no Builder delivery cursor.`); } const updated = setDeliveryCursor( context.db, { journey, method: options.method, activeItem: cursor.activeItem, activeItemTitle: cursor.activeItemTitle, activeItemLevel: cursor.activeItemLevel, activeCheckpoint: cursor.activeCheckpoint, pendingConfirmation: cursor.pendingConfirmation, lastDeliveryEvent: cursor.lastDeliveryEvent, cadenceProfile: profile, cadenceLimits: limits, granularityDecision: cursor.granularityDecision, navigatorFlowUnit: cursor.navigatorFlowUnit, childWorkItems: cursor.childWorkItems, aggregateCheckpointStatus: cursor.aggregateCheckpointStatus, }, context.deps, ); return { stdout: printed(renderDeliveryCursorSyncReport(updated)), stderr: "", exitCode: 0 }; } /** Python `cmd_release_intent`: set with `--intent`, inspect without it. */ export function runReleaseIntent( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null; intent?: string | null; }, ): CommandResult { const guarded = lifecycleGuards(context, { ...options, action: "Delivery Story release intent", requireCursor: false, }); if (isCommandResult(guarded)) return guarded; const intent = options.intent ?? null; try { const report = intent === null ? inspectReleaseIntent(context.db, { journey: guarded.journey, method: options.method }) : setReleaseIntent( context.db, { journey: guarded.journey, method: options.method, intent }, context.deps, ); return { stdout: printed(renderReleaseIntentReport(report)), stderr: "", exitCode: 0 }; } catch (error) { return refuseValueError(error); } } /** * Python `cmd_continue_lifecycle`. * * Also CLI-only, and narrower than its name suggests: the ONLY continuation it can * perform is crossing Done from a completed Debt Review or Coherence. Everything * else is one of five refusals, each rendering IMPLEMENTATION_GUARD on stdout with * exit 1 rather than an `Error:` line on stderr. * * Two shapes reproduced deliberately. It accepts `--process`, `--project`, * `--product`, and `--difference` and IGNORES all four — it never runs Coherence, * despite taking Coherence's evidence. And unlike `done-item`, which prints the * roadmap snapshot after closing, it prints its checkpoint and stops. Both are * parity-bound; both have cases. */ export function runContinueLifecycle( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null; historyAction?: string | null; roadmapUpdate?: string | null; nextRecommendation?: string | null; }, ): CommandResult { const guarded = lifecycleGuards(context, { ...options, action: "lifecycle continuation", requireCursor: true, }); if (isCommandResult(guarded)) return guarded; const journey = guarded.journey; const cursor = getDeliveryCursor(context.db, journey); if (cursor === null) { return refuse("Error: delivery cursor is required before continuation"); } const blocked = (reason: string): CommandResult => ({ stdout: printed( renderCheckpointRefused({ request: "continue-lifecycle", reason, journey, cursor }), ), stderr: "", exitCode: 1, }); const profile = effectiveCadenceProfile(cursor); if (profile === "stepwise") { return blocked("Stepwise cadence does not continue automatically."); } if (profile === "autonomous" && cursor.cadenceLimits.length === 0) { return blocked("Autonomous cadence requires explicit limits."); } if (cursor.pendingConfirmation) { return blocked(`Continuation is blocked: pending confirmation ${cursor.pendingConfirmation}.`); } const projectPath = getProjectPath(context.db, journey); const planPath = closureArtifactPath(projectPath, cursor, "plan.md"); if (!["review_complete", "coherence_complete"].includes(cursor.lastDeliveryEvent ?? "")) { return blocked( `No bypassable continuation is available after ${cursor.lastDeliveryEvent || "none"}.`, ); } if (!(options.historyAction && options.roadmapUpdate && options.nextRecommendation)) { return blocked("Done requires history, roadmap, and next-step evidence."); } // The same Done as `done-item`, with the same record to read (CR112): a cadence that // continues on its own must not close a story `done-item` would refuse. try { const report = doneLifecycleItem( context.db, { journey, method: getAriadMethod(), historyAction: options.historyAction, roadmapUpdate: options.roadmapUpdate, nextRecommendation: options.nextRecommendation, doneArtifactPath: planPath === null ? null : join(dirname(planPath), "done.md"), indexArtifactPath: planPath === null ? null : join(dirname(planPath), "index.md"), projectRoot: projectPath, }, context.deps, ); return { stdout: printed(renderDoneCheckpoint(report)), stderr: "", exitCode: 0 }; } catch (error) { if (error instanceof LifecycleRefusal) return blocked(error.message); throw error; } } // --- Delivery Story leaves (plateau 5) -------------------------------------- // // The aggregate leaves differ from their story-level twins in three CLI-visible // ways, all reproduced here: // // * no CLI cursor guard — `lifecycleGuards` runs with `requireCursor: false`, // so a missing cursor surfaces the MODULE's message, not the CLI's; // * refusals are ordinary stderr lines (`Error: …`, exit 1), never the // IMPLEMENTATION_GUARD surface the story closure leaves print on stdout; // * `approve-delivery-story-plan` prints the mismatch surface and exits **0**, // because a refused authority is a normal Navigator-facing outcome rather than // a failure — the ordinary Plan gate is still there. /** Python `cmd_set_flow_unit`: inspect with no `--unit`, select with one. */ export function runSetFlowUnit( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null; unit?: string | null; }, ): CommandResult { const guarded = lifecycleGuards(context, { ...options, action: "navigator flow unit", requireCursor: false, }); if (isCommandResult(guarded)) return guarded; const unit = options.unit ?? null; try { if (unit === null) { const report = inspectNavigatorFlowUnit(context.db, { journey: guarded.journey, method: options.method, }); return { stdout: printed(renderNavigatorFlowUnitReport(report)), stderr: "", exitCode: 0 }; } const report = setNavigatorFlowUnit( context.db, { journey: guarded.journey, method: options.method, flowUnit: unit }, context.deps, ); return { stdout: printed(renderFlowUnitScopeConfirmationReport(report)), stderr: "", exitCode: 0, }; } catch (error) { return refuseValueError(error); } } /** Python `cmd_plan_delivery_story`. */ export function runPlanDeliveryStory( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null; objective?: string | null; children?: readonly string[]; preauthorizeApproval?: boolean; stopAfter?: string; }, ): CommandResult { const guarded = lifecycleGuards(context, { ...options, action: "Delivery Story Plan", requireCursor: false, }); if (isCommandResult(guarded)) return guarded; const journey = guarded.journey; const cursor = getDeliveryCursor(context.db, journey); const projectPath = getProjectPath(context.db, journey); const planPath = closureArtifactPath(projectPath, cursor, "plan.md"); try { const report = planDeliveryStoryCheckpoint( context.db, { journey, method: options.method, objective: options.objective ?? "", childWorkItems: options.children ?? [], planArtifactPath: planPath, projectRoot: projectPath, preauthorize: options.preauthorizeApproval ?? false, stopBoundary: options.stopAfter ?? "navigator_validation", }, context.deps, ); const receipt = options.preauthorizeApproval ? printed(renderPlanPreauthorizationRecorded(report)) : ""; return { stdout: printed(renderDeliveryStoryPlanReport(report)) + receipt + artifactsSurface({ context: `Delivery Story Plan — ${report.cursor.activeItem || "active item"}`, artifacts: report.materializedArtifacts, projectPath, journey, boundary: "Plan artifacts were materialized. Implementation remains blocked until approval.", }), stderr: "", exitCode: 0, }; } catch (error) { return refuseValueError(error); } } /** Python `cmd_approve_delivery_story_plan`. */ export function runApproveDeliveryStoryPlan( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null; usePreauthorization?: boolean; }, ): CommandResult { const guarded = lifecycleGuards(context, { ...options, action: "Delivery Story Plan approval", requireCursor: false, }); if (isCommandResult(guarded)) return guarded; const journey = guarded.journey; const cursor = getDeliveryCursor(context.db, journey); const projectPath = getProjectPath(context.db, journey); try { const report = approveDeliveryStoryPlan( context.db, { journey, method: options.method, planArtifactPath: closureArtifactPath(projectPath, cursor, "plan.md"), projectRoot: projectPath, usePreauthorization: options.usePreauthorization ?? false, }, context.deps, ); // A repeat consumption returns after the card: no artifacts, no handoff. if (report.status === "already_approved") { return { stdout: printed(renderDeliveryStoryPlanReport(report)), stderr: "", exitCode: 0 }; } const started = report.implementationStarted ? printed(renderDeliveryStoryImplementationStarted(report)) : ""; return { stdout: printed(renderDeliveryStoryPlanReport(report)) + artifactsSurface({ context: `Delivery Story Plan Approval — ${report.cursor.activeItem || "active item"}`, artifacts: report.materializedArtifacts, projectPath, journey, boundary: "Plan approval artifacts were materialized. Implementation may proceed under the approved plan.", }) + started, stderr: "", exitCode: 0, }; } catch (error) { if (error instanceof PlanPreauthorizationMismatch) { // Re-read: the mismatch path invalidated the receipt, so the card reports the // cursor as it stands now. const current = getDeliveryCursor(context.db, journey); return { stdout: printed( renderPlanPreauthorizationMismatch({ activeItem: current?.activeItem ?? null, reason: error.reason, }), ), stderr: "", exitCode: 0, }; } return refuseValueError(error); } } /** Python `cmd_cancel_delivery_story_plan_preauthorization`. */ export function runCancelDeliveryStoryPlanPreauthorization( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null }, ): CommandResult { const guarded = lifecycleGuards(context, { ...options, action: "Delivery Story Plan preauthorization cancellation", requireCursor: false, }); if (isCommandResult(guarded)) return guarded; try { const cursor = cancelDeliveryStoryPlanPreauthorization( context.db, { journey: guarded.journey, method: options.method }, context.deps, ); return { stdout: printed( renderPlanPreauthorizationMismatch({ activeItem: cursor.activeItem, reason: "navigator_cancelled", }), ), stderr: "", exitCode: 0, }; } catch (error) { return refuseValueError(error); } } /** The four aggregate closure leaves share everything but their call and artifact. */ function runDeliveryStoryClosure( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null }, spec: { action: string; kind: string; filename: string; label: string; run: ( journey: string, artifactPath: string | null, projectRoot: string | null, ) => DeliveryStoryClosureReport; preflight?: (journey: string, projectPath: string | null) => CommandResult | null; trailer?: (report: DeliveryStoryClosureReport, projectPath: string | null) => string; }, ): CommandResult { const guarded = lifecycleGuards(context, { ...options, action: spec.action, requireCursor: false, }); if (isCommandResult(guarded)) return guarded; const journey = guarded.journey; const projectPath = getProjectPath(context.db, journey); try { const refusal = spec.preflight?.(journey, projectPath) ?? null; if (refusal !== null) return refusal; const cursor = getDeliveryCursor(context.db, journey); const artifactPath = closureArtifactPath(projectPath, cursor, spec.filename); const report = spec.run(journey, artifactPath, projectPath); return { stdout: printed(renderDeliveryStoryClosureReport(report)) + artifactsSurface({ context: `Delivery Story ${spec.label} — ${report.cursor.activeItem || "active item"}`, artifacts: closureArtifactManifest(spec.kind, artifactPath, report.artifactOutcome), projectPath, journey, boundary: closureBoundary(spec.label, report.artifactOutcome), }) + (spec.trailer?.(report, projectPath) ?? ""), stderr: "", exitCode: 0, }; } catch (error) { return refuseValueError(error); } } /** Python `cmd_validate_delivery_story`. */ export function runValidateDeliveryStory( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null; summary?: string | null; navigatorAccepted?: boolean; }, ): CommandResult { return runDeliveryStoryClosure(context, options, { action: "Delivery Story validation", kind: "validation", filename: "validation.md", label: "Validation", run: (journey, artifactPath, projectRoot) => validateDeliveryStory( context.db, { journey, method: options.method, summary: options.summary ?? "", navigatorAccepted: options.navigatorAccepted ?? false, artifactPath, projectRoot, }, context.deps, ), // Same CLI-only mini-card the story-level Validate prints, on the same // condition: a passed validation offers Debt Review. trailer: (report) => report.status === "passed" ? printed(renderDebtReviewHandoff(report.cursor)) : "", }); } /** Python `cmd_review_delivery_story`. */ export function runReviewDeliveryStory( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null; decision?: string | null; summary?: string | null; }, ): CommandResult { return runDeliveryStoryClosure(context, options, { action: "Delivery Story debt review", kind: "review", filename: "review.md", label: "Review", run: (journey, artifactPath, projectRoot) => reviewDeliveryStory( context.db, { journey, method: options.method, decision: options.decision ?? "", summary: options.summary ?? "", artifactPath, projectRoot, }, context.deps, ), // Keyed off the REQUESTED decision, as Python is — not off the report. trailer: (report) => options.decision === "no_action" ? printed(renderDoneClosureConfirmation(report.cursor)) : "", }); } /** Python `cmd_coherence_delivery_story`. */ export function runCoherenceDeliveryStory( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null; summary?: string | null; }, ): CommandResult { return runDeliveryStoryClosure(context, options, { action: "Delivery Story coherence", kind: "coherence", filename: "coherence.md", label: "Coherence", run: (journey, artifactPath, projectRoot) => coherenceDeliveryStory( context.db, { journey, method: options.method, summary: options.summary ?? "", artifactPath, projectRoot, }, context.deps, ), }); } /** * Python `cmd_done_delivery_story`. * * The preflight runs BEFORE any artifact path is derived or any cursor is written, * so a refused Done leaves the project exactly as it was. Its message is the `; ` * join of the issues, which is why the preflight's ORDER is behavior. */ export function runDoneDeliveryStory( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null; summary?: string | null; }, ): CommandResult { return runDeliveryStoryClosure(context, options, { action: "Delivery Story Done", kind: "done", filename: "done.md", label: "Done", preflight: (journey, projectPath) => { if (!projectPath) { return refuse("Error: project path is required before Delivery Story Done"); } const cursor = getDeliveryCursor(context.db, journey); if (cursor === null || !cursor.activeItem) { return refuse("Error: active Delivery Story is required before Done"); } const authored = inspectAuthoredClosure(projectPath, { deliveryStory: cursor.activeItem, childWorkItems: cursor.childWorkItems, }); if (!authored.ready) { return refuse( `Error: authored roadmap is not ready for Delivery Story Done: ${authored.issues.join("; ")}`, ); } return null; }, run: (journey, artifactPath, projectRoot) => doneDeliveryStory( context.db, { journey, method: options.method, summary: options.summary ?? "", artifactPath, projectRoot, }, context.deps, ), // Python `_print_roadmap_snapshot_at_done_end`: the roadmap is read AGAIN, after // the write, so the position reflects the Delivery Story that just closed. trailer: (report, projectPath) => printed( renderProjectPositionReport( inspectRoadmapSnapshot(projectPath, { journey: report.journey, method: options.method }), { view: journeyCandidateView(context.db, report.journey, projectPath, options.method), justMoved: `🟩[${report.deliveryStory}] ${report.deliveryStoryTitle || "Delivery Story"} closed`, }, ), ), }); } /** * The handoff after an accepted validation. Its ribbon was a fixed string, so it drew a * story's Expand as done where every other surface now draws it not applicable (CR113). */ function renderDebtReviewHandoff(cursor: BuilderDeliveryCursor): string { const activeItem = cursor.activeItem; const body = `${[ "Delivery", renderLifecycleRibbon("debt_review", cursor.activeItemLevel), "", "╭────────────────────────────────────────────────────────╮", "│ 🔎 DEBT REVIEW STARTED │", "│ │", miniCardText("What changed?"), ...miniCardWrapped( "Validation was accepted. Before closure, review whether any relevant technical debt remains.", ), "│ │", miniCardText("Active item"), miniCardText(activeItem || "active item"), "│ │", miniCardText("Navigator check"), // "no action needed" is the runtime's own word for `no_action`. The oracle had a // Portuguese phrase here, in an English sentence (CR090). ...miniCardWrapped( "If there is no relevant debt to address now, I can record this as no action needed and continue toward closure.", ), "╰────────────────────────────────────────────────────────╯", ].join("\n")}\n`; return wrapAriadSurface("debt_review_started", body); } /** Python `_render_done_closure_confirmation`, its ribbon told the level (CR113). */ function renderDoneClosureConfirmation(cursor: BuilderDeliveryCursor): string { const activeItem = cursor.activeItem; const body = `${[ "Delivery", renderLifecycleRibbon("done", cursor.activeItemLevel), "", "╭────────────────────────────────────────────────────────╮", "│ 🧭 DONE CLOSURE CONFIRMATION │", "│ │", miniCardText("My understanding"), ...miniCardWrapped( "Debt review found no relevant action to take now. The story is ready to close.", ), "│ │", miniCardText("Active item"), miniCardText(activeItem || "active item"), "│ │", miniCardText("Before I close"), ...miniCardWrapped("Is there anything else to do in this story before Done?"), "╰────────────────────────────────────────────────────────╯", ].join("\n")}\n`; return wrapAriadSurface("done_closure_confirmation", body); } /** * A refused lifecycle request, rendered where the cursor stands (CR067). Only a * `LifecycleRefusal` qualifies: it is raised before any write, which is what the * surface's boundary promises. A failure after the cursor write, such as a record the * artifact writer refuses or cannot write, keeps the plain `Error:` line instead. */ function refusedSurface( db: Database, journey: string, request: string, refusal: LifecycleRefusal, ): CommandResult { const cursor = getDeliveryCursor(db, journey); const reason = refusal.message; return { stdout: printed(renderCheckpointRefused({ request, reason, journey, cursor })), stderr: "", exitCode: 1, }; } /** The closure leaves' shared artifact path: the Plan package's sibling file. */ function closureArtifactPath( projectPath: string | null, cursor: { activeItem: string | null; activeItemTitle: string | null } | null, filename: string, ): string | null { const packagePath = canonicalPackagePath(projectPath, cursor); return packagePath === null ? null : join(packagePath, filename); } /** Python `cmd_validate_item`. */ export function runValidateItem( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null; checks?: readonly string[]; checksStatus?: string; e2eDecision?: string; e2eEvidence?: string | null; navigatorRoute?: string | null; navigatorAccepted?: boolean; expectedObservation?: string | null; passCondition?: string | null; failCondition?: string | null; implementationComplete?: boolean; }, ): CommandResult { const guarded = lifecycleGuards(context, { ...options, action: "validation", requireCursor: true, }); if (isCommandResult(guarded)) return guarded; const journey = guarded.journey; const cursor = getDeliveryCursor(context.db, journey); const projectPath = getProjectPath(context.db, journey); try { const report = validateLifecycleItem( context.db, { journey, method: getAriadMethod(), automatedChecks: options.checks ?? [], checksStatus: options.checksStatus ?? "not_run", e2eDecision: options.e2eDecision ?? "not_required", e2eEvidence: options.e2eEvidence ?? null, navigatorValidationRoute: options.navigatorRoute ?? null, navigatorAccepted: options.navigatorAccepted ?? false, expectedObservation: options.expectedObservation ?? null, passCondition: options.passCondition ?? null, failCondition: options.failCondition ?? null, implementationComplete: options.implementationComplete ?? false, validationArtifactPath: closureArtifactPath(projectPath, cursor, "validation.md"), projectRoot: projectPath, }, context.deps, ); const handoff = report.missingEvidence.length === 0 ? printed(renderDebtReviewHandoff(report.cursor)) : ""; return { stdout: printed(renderValidationCheckpoint(report)) + handoff, stderr: "", exitCode: 0, }; } catch (error) { if (error instanceof LifecycleRefusal) { return refusedSurface(context.db, journey, "validate-item", error); } return refuseValueError(error); } } /** Python `cmd_review_item`. */ export function runReviewItem( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null; debtFindings?: readonly string[]; debtDecision?: string; deferReason?: string | null; revisitTrigger?: string | null; }, ): CommandResult { const guarded = lifecycleGuards(context, { ...options, action: "debt review", requireCursor: true, }); if (isCommandResult(guarded)) return guarded; const journey = guarded.journey; const cursor = getDeliveryCursor(context.db, journey); const projectPath = getProjectPath(context.db, journey); try { const report = reviewLifecycleItem( context.db, { journey, method: getAriadMethod(), debtFindings: options.debtFindings ?? [], debtDecision: options.debtDecision ?? "pending", deferReason: options.deferReason ?? null, revisitTrigger: options.revisitTrigger ?? null, reviewArtifactPath: closureArtifactPath(projectPath, cursor, "review.md"), projectRoot: projectPath, }, context.deps, ); // Only `no_action` WITH nothing missing offers closure. A completed `defer` does // not, which is the distinction the second surface carries. const confirmation = report.debtDecision === "no_action" && report.missingDecision.length === 0 ? printed(renderDoneClosureConfirmation(report.cursor)) : ""; return { stdout: printed(renderReviewCheckpoint(report)) + confirmation, stderr: "", exitCode: 0, }; } catch (error) { if (error instanceof LifecycleRefusal) { return refusedSurface(context.db, journey, "review-item", error); } return refuseValueError(error); } } /** Python `cmd_coherence_item`. */ export function runCoherenceItem( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null; processAlignment?: string | null; projectAlignment?: string | null; productAlignment?: string | null; localDifferences?: readonly string[]; }, ): CommandResult { const guarded = lifecycleGuards(context, { ...options, action: "coherence", requireCursor: true, }); if (isCommandResult(guarded)) return guarded; const journey = guarded.journey; const cursor = getDeliveryCursor(context.db, journey); const projectPath = getProjectPath(context.db, journey); try { const report = coherenceLifecycleItem( context.db, { journey, method: getAriadMethod(), processAlignment: options.processAlignment ?? null, projectAlignment: options.projectAlignment ?? null, productAlignment: options.productAlignment ?? null, localDifferences: options.localDifferences ?? [], coherenceArtifactPath: closureArtifactPath(projectPath, cursor, "coherence.md"), projectRoot: projectPath, }, context.deps, ); return { stdout: printed(renderCoherenceCheckpoint(report)), stderr: "", exitCode: 0 }; } catch (error) { if (error instanceof LifecycleRefusal) { return refusedSurface(context.db, journey, "coherence-item", error); } return refuseValueError(error); } } /** Python `cmd_done_item`, including the project position it prints afterwards. */ export function runDoneItem( context: BuilderWriteContext, options: { method: string; journey?: string | null; sessionId?: string | null; historyAction?: string | null; roadmapUpdate?: string | null; nextRecommendation?: string | null; }, ): CommandResult { const guarded = lifecycleGuards(context, { ...options, action: "done", requireCursor: true }); if (isCommandResult(guarded)) return guarded; const journey = guarded.journey; const cursor = getDeliveryCursor(context.db, journey); const projectPath = getProjectPath(context.db, journey); try { const report = doneLifecycleItem( context.db, { journey, method: getAriadMethod(), historyAction: options.historyAction ?? null, roadmapUpdate: options.roadmapUpdate ?? null, nextRecommendation: options.nextRecommendation ?? null, doneArtifactPath: closureArtifactPath(projectPath, cursor, "done.md"), indexArtifactPath: closureArtifactPath(projectPath, cursor, "index.md"), projectRoot: projectPath, }, context.deps, ); // Python `_print_roadmap_snapshot_at_done_end`: the roadmap is read again, after // the write, so the position reflects the story that just closed. const position = renderProjectPositionReport( inspectRoadmapSnapshot(projectPath, { journey, method: options.method }), { view: journeyCandidateView(context.db, journey, projectPath, options.method), justMoved: `🟩[${report.activeItem}] ${report.activeItemTitle || "Story"} closed`, }, ); return { stdout: printed(renderDoneCheckpoint(report)) + printed(position), stderr: "", exitCode: 0, }; } catch (error) { if (error instanceof LifecycleRefusal) { return refusedSurface(context.db, journey, "done-item", error); } return refuseValueError(error); } }