@getpipher/armory-fleet 0.2.0 → 0.4.0

package/src/index.ts

@@ -21,7 +21,15 @@ import { createDescribeImageTool } from "./vision/describe-image-tool.ts";
 import type { MemoryHydratePort } from "./memory-hydrate/port.ts";
 import type { VisionPort } from "./vision/port.ts";
 import type { ChildSessionFactory, ChildSession } from "./engine/spawnSubagent.ts";
+import { BackendRegistry, PI_HOOK_PARITY, CLAUDE_HOOK_PARITY, type Backend } from "./backend/port.ts";
+import { ResumeStore } from "./backend/resume-store.ts";
+import { detectClaude } from "./backend/claude-detector.ts";
+import { createClaudeChildFactory } from "./backend/claude-factory.ts";
 import { join } from "node:path";
+import { discoverLifecycles } from "./lifecycle/registry.ts";
+import { DEFAULT_LIFECYCLE, builtinLifecyclesDir } from "./lifecycle/default.ts";
+import type { LifecycleDef } from "./lifecycle/lifecycle-types.ts";
+import type { LifecycleRunDeps } from "./lifecycle/run-lifecycle.ts";
 
 /** The package builtin agents/ dir, resolved relative to this module. */
 function builtinAgentsDir(): string {
@@ -30,7 +38,44 @@ function builtinAgentsDir(): string {
 
 /** Build the real (SDK-backed) child-session factory. memoryPort is shared (cwd-agnostic);
  *  the vision adapter is constructed per-spawn (needs the child cwd). */
-function createChildSessionFactory(modelRuntime: ModelRuntime, memoryPort: MemoryHydratePort): ChildSessionFactory {
+/** SPEC-3: wrap a pi SDK session so it emits session_init on subscribe + forwards the rest. */
+function wrapPiSession(inner: ChildSession, backendSessionId: string): ChildSession {
+  return {
+    prompt: (t) => inner.prompt(t),
+    abort: () => inner.abort(),
+    dispose: () => inner.dispose(),
+    subscribe: (handler) => {
+      handler({ type: "session_init", backendSessionId });
+      return inner.subscribe(handler);
+    },
+  };
+}
+
+/** SPEC-3: build the BackendRegistry — pi always; claude registered with availability reflecting detectClaude(). */
+async function buildDefaultBackendRegistry(modelRuntime: ModelRuntime): Promise<BackendRegistry> {
+  const resumeStore = new ResumeStore();
+  const claudeInfo = await detectClaude();
+  const reg = new BackendRegistry();
+  const pi: Backend = {
+    id: "pi",
+    factory: createChildSessionFactory(modelRuntime, new ArmoryMemoryAdapter(), resumeStore),
+    available: () => true,
+    versionInfo: () => null,
+    hookParity: PI_HOOK_PARITY,
+  };
+  reg.register(pi);
+  // claude is registered regardless of availability so the Backends view can show it; available reflects detection.
+  reg.register({
+    id: "claude",
+    factory: createClaudeChildFactory(claudeInfo, resumeStore),
+    available: () => claudeInfo?.schemaOk === true,
+    versionInfo: () => claudeInfo,
+    hookParity: CLAUDE_HOOK_PARITY,
+  });
+  return reg;
+}
+
+export function createChildSessionFactory(modelRuntime: ModelRuntime, memoryPort: MemoryHydratePort, resumeStore: ResumeStore): ChildSessionFactory {
   return {
     async create(opts) {
       let model: Model<any> | undefined;
@@ -52,7 +97,10 @@ function createChildSessionFactory(modelRuntime: ModelRuntime, memoryPort: Memor
         agentDir: getAgentDir(),
       });
       const injectVision = opts.agent.vision && !visionPort.isMultimodal(model);
-      const { session } = await createAgentSession({
+      // SPEC-3 §3.1: file-backed SessionManager so resume works. Resume a prior session when the store has a path.
+      const resumePath = resumeStore.get("pi", opts.agent.sessionKey);
+      const sessionManager = resumePath ? SessionManager.open(resumePath) : SessionManager.create(opts.cwd);
+      const { session: piSession } = await createAgentSession({
         cwd: opts.cwd,
         model,
         thinkingLevel: opts.thinkingLevel,
@@ -60,10 +108,14 @@ function createChildSessionFactory(modelRuntime: ModelRuntime, memoryPort: Memor
         excludeTools: ["todo"],                       // SPEC-2 §9.1 hardened single-writer guard
         customTools: injectVision ? [createDescribeImageTool(visionPort) as never] : [],
         resourceLoader: loader,
-        sessionManager: SessionManager.inMemory(),
+        sessionManager,
         modelRuntime,
       });
-      return { session: session as unknown as ChildSession, model: opts.model ?? "" };
+      // SPEC-3 §4.3: wrap + emit session_init + persist the session file path for resume.
+      const backendSessionId = piSession.sessionFile ?? piSession.sessionId;
+      if (piSession.sessionFile) resumeStore.set("pi", opts.agent.sessionKey, piSession.sessionFile);
+      const session: ChildSession = wrapPiSession(piSession as unknown as ChildSession, backendSessionId);
+      return { session, model: opts.model ?? "" };
     },
   };
 }
@@ -75,10 +127,29 @@ export default async function (pi: ExtensionAPI): Promise<void> {
     runRegistry: new RunRegistry(),
     lock: createSingleSlotLock(),
     todoSync: new ArmoryTodoAdapter(),
-    childFactory: createChildSessionFactory(modelRuntime, new ArmoryMemoryAdapter()),
+    backendRegistry: await buildDefaultBackendRegistry(modelRuntime),
     parentModel: { provider: "", id: "" },
     parentCwd: "",
+    lifecycleRegistry: new Map<string, LifecycleDef>(),
+    lifecycleRuns: new Map<string, import("./lifecycle/lifecycle-types.ts").LifecycleRunRecord>(),
+    lifecycleDeps: {
+      registry: new Map(),          // wired to the real agent registry in refreshLifecycles (Task 12)
+      agentRegistry: new Map(),     // ditto
+      todoPort: new ArmoryTodoAdapter(),
+      resolveBackend: (phaseBackend, lifecycleBackend) => {
+        const id = phaseBackend ?? lifecycleBackend;
+        if (id === "claude" && !deps.backendRegistry.get("claude")?.available()) {
+          throw new Error("phase requests backend 'claude' but claude is not installed; run 'claude' to set up, or change the phase backend in the lifecycle file");
+        }
+        return id;
+      },
+      genRunId: () => "fl-" + Date.now().toString(36) + "-" + Math.random().toString(36).slice(2, 8),
+    },
   };
+  // Seed the builtin `default` lifecycle + wire lifecycleDeps to the live registries.
+  deps.lifecycleRegistry.set(DEFAULT_LIFECYCLE.name, DEFAULT_LIFECYCLE);
+  deps.lifecycleDeps.registry = deps.lifecycleRegistry;
+  deps.lifecycleDeps.agentRegistry = deps.registry;
 
   const refresh = (ctx: { cwd: string; ui: { notify: (m: string, t?: "info" | "warning" | "error") => void } }): void => {
     const r = discoverAgents({
@@ -88,18 +159,35 @@ export default async function (pi: ExtensionAPI): Promise<void> {
     });
     for (const e of r.errors) ctx.ui.notify(e, "error");
     for (const w of r.warnings) ctx.ui.notify(w, "warning");
-    deps.registry = r.agents;
+    // Mutate in place (not replace the reference) so lifecycleDeps.agentRegistry — which is bound
+    // to this same Map once at init — stays live across refreshes (SPEC-4 fix).
+    deps.registry.clear();
+    for (const [k, v] of r.agents) deps.registry.set(k, v);
+  };
+
+  const refreshLifecycles = (ctx: { cwd: string; ui: { notify: (m: string, t?: "info" | "warning" | "error") => void } }): void => {
+    const r = discoverLifecycles({
+      projectDir: join(ctx.cwd, ".pi", "lifecycles"),
+      globalDir: join(process.env.HOME ?? "", ".pi", "agent", "lifecycles"),
+      builtinDir: builtinLifecyclesDir(),
+    });
+    for (const e of r.errors) ctx.ui.notify(e, "error");
+    for (const w of r.warnings) ctx.ui.notify(w, "warning");
+    deps.lifecycleRegistry.clear();
+    deps.lifecycleRegistry.set(DEFAULT_LIFECYCLE.name, DEFAULT_LIFECYCLE);
+    for (const [name, def] of r.lifecycles) deps.lifecycleRegistry.set(name, def);
   };
 
   pi.on("session_start", (_event, ctx) => {
     refresh(ctx);
+    refreshLifecycles(ctx);
     const m = ctx.model;
     deps.parentModel = m ? { provider: m.provider, id: m.id } : { provider: "", id: "" };
     deps.parentCwd = ctx.cwd;
   });
 
   pi.on("resources_discover", (event, ctx) => {
-    if (event.reason === "reload") refresh(ctx);
+    if (event.reason === "reload") { refresh(ctx); refreshLifecycles(ctx); }
     return undefined;
   });
 
@@ -115,4 +203,50 @@ export default async function (pi: ExtensionAPI): Promise<void> {
       openFleetPanel(deps, ctx as never);
     },
   });
+
+  // SPEC-4: /fleet-implement <task> [--lifecycle <name>] [--auto] — the done-bar slash.
+  const parseImplementArgs = (args: string): { task: string; lifecycle?: string; auto?: boolean } => {
+    const parts = String(args ?? "").trim().split(/\s+/);
+    let lifecycle: string | undefined; let auto = false; const taskParts: string[] = [];
+    for (let i = 0; i < parts.length; i++) {
+      if (parts[i] === "--lifecycle") { lifecycle = parts[++i]; continue; }
+      if (parts[i] === "--auto") { auto = true; continue; }
+      taskParts.push(parts[i]!);
+    }
+    return { task: taskParts.join(" ").trim(), lifecycle, auto };
+  };
+
+  pi.registerCommand("fleet-implement", {
+    description: "Run a task through the superpowers lifecycle (default). Flags: --lifecycle <name>, --auto.",
+    handler: async (args, ctx) => {
+      const parsed = parseImplementArgs(args);
+      const lcName = parsed.lifecycle ?? "default";
+      if (!parsed.task) { ctx.ui.notify("usage: /fleet-implement <task> [--lifecycle <name>] [--auto]", "warning"); return; }
+      if (!deps.lifecycleRegistry.has(lcName)) {
+        ctx.ui.notify(`lifecycle '${lcName}' not found; available: ${[...deps.lifecycleRegistry.keys()].sort().join(", ")}`, "error");
+        return;
+      }
+      const { runLifecycle } = await import("./lifecycle/run-lifecycle.ts");
+      const { spawnSubagent } = await import("./engine/spawnSubagent.ts");
+      const onCheckpoint: import("./lifecycle/run-lifecycle.ts").CheckpointFn = parsed.auto
+        ? async (_phase) => ({ action: "continue" })
+        : async (phase) => {
+            // Non-TUI / non-auto: can't prompt interactively → auto-continue + notify (open /fleet for interactive).
+            ctx.ui.notify(`lifecycle checkpoint at '${phase.name}' — open /fleet Lifecycle view to Continue/Revise/Abort (auto-continuing)`, "info");
+            return { action: "continue" };
+          };
+      const lifecycleFullDeps: import("./lifecycle/run-lifecycle.ts").LifecycleRunDeps = {
+        ...deps.lifecycleDeps,
+        spawn: async (o) => spawnSubagent({
+          agent: o.agent, task: o.task, lifecycleTodoId: o.lifecycleTodoId, model: o.model,
+            skillsOverride: o.skills, backendOverride: o.backend,
+          registry: deps.registry, todoSync: deps.todoSync, runRegistry: deps.runRegistry, lock: deps.lock,
+          backendRegistry: deps.backendRegistry, parentModel: deps.parentModel, parentCwd: deps.parentCwd,
+        }),
+      };
+      const res = await runLifecycle(parsed.task, lcName, { deps: lifecycleFullDeps, mode: parsed.auto ? "auto" : "checkpointed", onCheckpoint });
+      deps.lifecycleRuns.set(res.runId, res);
+      ctx.ui.notify(`lifecycle ${res.status}: ${res.runId}${res.error ? " — " + res.error : ""}`, res.status === "completed" ? "info" : "warning");
+    },
+  });
 }

package/src/lifecycle/artifacts-parser.ts

@@ -0,0 +1,57 @@
+// src/lifecycle/artifacts-parser.ts
+import { parse as parseYaml } from "yaml";
+
+export const MAX_REVISE = 3;
+
+export interface ArtifactsOk { summary: string; paths: string[] }
+export interface ArtifactsErr { error: string }
+export type ArtifactsResult = ArtifactsOk | ArtifactsErr;
+
+/** Parse the trailing `Artifacts:` YAML block from a child's finalText.
+ *  Returns {summary, paths} on success, or {error} on failure.
+ *  terminal=true exempts a missing block (the finish phase may have no file artifact). */
+export function parseArtifacts(finalText: string, opts: { terminal?: boolean } = {}): ArtifactsResult {
+  // Strip a trailing prompt-echo trailer (e.g. CIPHER's "📌 YOUR PROMPT: ..." bordered by `---`),
+  // which the child may inherit from the base system prompt. The echo can contain the literal
+  // "Artifacts:" (quoting the phase instruction) and would fool lastIndexOf below.
+  let text = finalText;
+  const echoIdx = text.lastIndexOf("📌 YOUR PROMPT:");
+  if (echoIdx >= 0) {
+    text = text.slice(0, echoIdx).replace(/\n---\s*$/, "");
+  }
+  const marker = "Artifacts:";
+  const idx = text.lastIndexOf(marker);
+  if (idx < 0) {
+    if (opts.terminal) return { summary: text.trim(), paths: [] };
+    return { error: "missing Artifacts block (child did not list produced file paths)" };
+  }
+  const summary = text.slice(0, idx).trim();
+  let block = text.slice(idx + marker.length);
+  // Robustness: models often wrap the YAML in a fenced code block (the `Artifacts:` marker sits
+  // inside the fence) and/or trail a prompt-echo / signature. Strip a leading opening fence line
+  // (```yaml) if present, then truncate at the FIRST closing fence (```) or markdown thematic
+  // break (`\n---\n`) — whichever comes first — so trailing content can't break the YAML parse.
+  block = block.replace(/^\s*```[a-zA-Z]*\s*\n/, "");
+  const fenceClose = block.indexOf("```");
+  const brk = block.search(/\n---\s*\n/);
+  let cut = block.length;
+  if (fenceClose >= 0) cut = Math.min(cut, fenceClose);
+  if (brk >= 0) cut = Math.min(cut, brk);
+  block = block.slice(0, cut);
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(block) ?? [];
+  } catch (e) {
+    return { error: `malformed Artifacts block: ${(e as Error).message}` };
+  }
+  if (!Array.isArray(parsed)) return { error: "Artifacts block must be a list of {path, kind}" };
+  const entries = parsed as Array<Record<string, unknown>>;
+  const paths: string[] = [];
+  for (const e of entries) {
+    if (typeof e.path === "string" && e.path.trim()) paths.push(e.path.trim());
+  }
+  if (paths.length === 0 && !opts.terminal) {
+    return { error: "Artifacts block has no paths (non-terminal phase must produce at least one file)" };
+  }
+  return { summary, paths };
+}

package/src/lifecycle/default.ts

@@ -0,0 +1,74 @@
+// src/lifecycle/default.ts
+import { join } from "node:path";
+import { parseLifecycleFile } from "./registry.ts";
+import type { LifecycleDef } from "./lifecycle-types.ts";
+
+/** The package builtin lifecycles/ dir, resolved relative to this module. */
+export function builtinLifecyclesDir(): string {
+  return join(new URL(".", import.meta.url).pathname, "..", "..", "lifecycles");
+}
+
+/** The shipped `default` lifecycle as a markdown string (frontmatter + ## phase templates).
+ *  This is the single source of truth — it is both written to lifecycles/default.md
+ *  (for human reading) AND parsed here at runtime so the builtin is always in sync. */
+export const DEFAULT_LIFECYCLE_SOURCE = `---
+name: default
+description: The superpowers-native 5-phase lifecycle (brainstorm→plan→implement→review→finish).
+backend: pi
+phases:
+  - name: brainstorm
+    skills: [brainstorming]
+    agent: general-purpose
+    checkpoint: true
+  - name: plan
+    skills: [writing-plans]
+    agent: general-purpose
+    checkpoint: true
+  - name: implement
+    skills: [executing-plans, test-driven-development, verification-before-completion]
+    agent: general-purpose
+    checkpoint: false
+  - name: review
+    skills: [requesting-code-review, receiving-code-review]
+    agent: general-purpose
+    checkpoint: true
+  - name: finish
+    skills: [finishing-a-development-branch]
+    agent: general-purpose
+---
+
+## brainstorm
+You are the **brainstorm** phase of a superpowers lifecycle. Use the brainstorming skill.
+Task: {{task}}
+{% if prev %}Previous phase ({{prev.name}}) produced: {{prev.summary}}
+Artifacts to read: {{prev.paths}}{% endif %}
+Explore the task, produce a design doc per the brainstorming skill. End your response with an
+\`Artifacts:\` block (YAML) listing the produced file paths + a kind.
+
+## plan
+You are the **plan** phase. Use writing-plans. Read the brainstorm phase's design artifact.
+{% if prev %}Previous phase: {{prev.summary}} | Artifacts: {{prev.paths}}{% endif %}
+{% if feedback %}Human feedback on a prior attempt: {{feedback}}{% endif %}
+Write the implementation plan per writing-plans. End with an \`Artifacts:\` block.
+
+## implement
+You are the **implement** phase. Use executing-plans + test-driven-development + verification-before-completion.
+Read the plan artifact. Implement it, run tests, verify before claiming done.
+End with an \`Artifacts:\` block (files changed).
+
+## review
+You are the **review** phase. Use requesting-code-review + receiving-code-review.
+Review the implementation against the plan + design. Produce review findings.
+End with an \`Artifacts:\` block (review notes path).
+
+## finish
+You are the **finish** phase. Use finishing-a-development-branch.
+Decide merge/PR/cleanup per the skill and execute it. End with an \`Artifacts:\` block
+(or omit on a merge/PR with no further file artifact — terminal-phase exemption).
+`;
+
+export const DEFAULT_LIFECYCLE: LifecycleDef = parseLifecycleFile(
+  DEFAULT_LIFECYCLE_SOURCE,
+  "<builtin:default>",
+  "builtin",
+);

package/src/lifecycle/lifecycle-todo.ts

@@ -0,0 +1,84 @@
+// src/lifecycle/lifecycle-todo.ts
+import type { BackendId, LifecycleMode } from "./lifecycle-types.ts";
+
+/** Minimal port shape the lifecycle-todo helpers need (so unit tests can pass a fake
+ *  without depending on the full TodoSyncPort). */
+export interface LifecycleTodoPort {
+  linkOrCreateRunTodo(run: { runId: string; agent: string; task: string; todoId?: string; track: boolean }): Promise<{ todoId: string | null; priorStatus?: string }>;
+  markRunTodoDone(todoId: string | null, priorStatus: string | undefined, result: string): Promise<void>;
+  markRunTodoReverted(todoId: string | null, priorStatus: string | undefined, reason: string): Promise<void>;
+  updateLifecycleProgress(todoId: string, progressBlock: string): Promise<void>;
+}
+
+/** Test fake helper type (re-exported so tests don't hand-roll the shape). */
+export interface FakeTodoPort extends LifecycleTodoPort {
+  _state: Map<string, { id: string; notes: string; status: string }>;
+}
+
+export interface LifecycleTodoMeta {
+  runId: string; task: string; lifecycle: string; backend: BackendId; mode: LifecycleMode;
+  phases: string[];
+}
+
+export interface ProgressPhase {
+  name: string;
+  done: boolean;
+  revising?: boolean;
+  attempt?: number;
+}
+
+export function buildProgressBlock(opts: {
+  lifecycle: string; task: string; backend: BackendId; mode: LifecycleMode;
+  phases: ProgressPhase[]; last: string;
+}): string {
+  const marks = opts.phases.map((p) => {
+    if (p.done) return `[x] ${p.name}`;
+    if (p.revising) return `[~] ${p.name} (revising, attempt ${p.attempt ?? 1}/3)`;
+    return `[ ] ${p.name}`;
+  }).join("  ");
+  return [
+    `Lifecycle: ${opts.lifecycle} · task: "${opts.task}"`,
+    `Backend: ${opts.backend} · Mode: ${opts.mode}`,
+    `Phases: ${marks}`,
+    `Last: ${opts.last}`,
+  ].join("\n");
+}
+
+export async function createLifecycleTodo(port: LifecycleTodoPort, meta: LifecycleTodoMeta): Promise<string> {
+  const link = await port.linkOrCreateRunTodo({
+    runId: meta.runId, agent: meta.lifecycle, task: meta.task, track: true,
+  });
+  if (!link.todoId) throw new Error("lifecycle TODO link-or-create returned null (armory-todo port error)");
+  await port.updateLifecycleProgress(link.todoId, buildProgressBlock({
+    lifecycle: meta.lifecycle, task: meta.task, backend: meta.backend, mode: meta.mode,
+    phases: meta.phases.map((n) => ({ name: n, done: false })), last: "started",
+  }));
+  return link.todoId;
+}
+
+export async function updateProgress(
+  port: LifecycleTodoPort, todoId: string,
+  upd: { phase: string; done: boolean; last: string; revising: boolean; attempt: number },
+  ctx: { lifecycle: string; task: string; backend: BackendId; mode: LifecycleMode; phases: ProgressPhase[] },
+): Promise<void> {
+  // Mutate the shared progressPhases in place so completion accumulates across phases
+  // (a new array here would discard prior phases' [x] state — the block is the single source of truth).
+  for (const ph of ctx.phases) {
+    if (ph.name === upd.phase) {
+      ph.done = upd.done;
+      ph.revising = upd.revising;
+      ph.attempt = upd.attempt;
+    }
+  }
+  await port.updateLifecycleProgress(todoId, buildProgressBlock({
+    lifecycle: ctx.lifecycle, task: ctx.task, backend: ctx.backend, mode: ctx.mode, phases: ctx.phases, last: upd.last,
+  }));
+}
+
+export async function completeLifecycleTodo(port: LifecycleTodoPort, todoId: string, result: string): Promise<void> {
+  await port.markRunTodoDone(todoId, undefined, result);
+}
+
+export async function revertLifecycleTodo(port: LifecycleTodoPort, todoId: string, reason: string): Promise<void> {
+  await port.markRunTodoReverted(todoId, undefined, reason);
+}

package/src/lifecycle/lifecycle-types.ts

@@ -0,0 +1,66 @@
+// src/lifecycle/lifecycle-types.ts
+import type { FleetRunStatus } from "../todo-sync/port.ts";
+import type { AgentSource } from "../registry/frontmatter.ts";
+
+/** Backend id (mirrors SPEC-3 AgentDef.backend). */
+export type BackendId = "pi" | "claude";
+
+/** Lifecycle-wide status (richer than FleetRunStatus: adds checkpoint + revising). */
+export type LifecycleStatus = "running" | "checkpoint" | "completed" | "failed" | "aborted";
+
+export type LifecycleMode = "checkpointed" | "auto";
+
+/** A phase definition (parsed from a lifecycle file's frontmatter). */
+export interface PhaseDef {
+  name: string;
+  skills: string[];
+  /** Per-phase default agent pin; absent → general-purpose. */
+  agent?: string;
+  /** Per-phase backend override (Q4=C); absent → lifecycle.backend. */
+  backend?: BackendId;
+  /** Pause for human review after this phase; default true. Terminal phase omits (no checkpoint). */
+  checkpoint?: boolean;
+  /** The phase prompt template (parsed from the `## <name>` body section). */
+  promptTemplate: string;
+}
+
+export interface LifecycleDef {
+  name: string;
+  description: string;
+  /** Lifecycle-wide default backend; absent → "pi". */
+  backend: BackendId;
+  phases: PhaseDef[];
+  source: AgentSource;
+  filePath: string;
+}
+
+/** The record of one phase's execution (stored on the LifecycleRunRecord). */
+export interface PhaseRecord {
+  name: string;
+  summary: string;
+  paths: string[];
+  status: FleetRunStatus;
+  reviseCount: number;
+}
+
+export interface LifecycleRunRecord {
+  runId: string;
+  lifecycleName: string;
+  task: string;
+  backend: BackendId;
+  mode: LifecycleMode;
+  status: LifecycleStatus;
+  phases: PhaseRecord[];
+  startedAt: number;
+  /** Set when the lifecycle reaches a terminal status (completed/failed/aborted). */
+  endedAt?: number;
+  todoId: string | null;
+}
+
+/** Human (or auto) decision at a checkpoint. */
+export type CheckpointAction = "continue" | "revise" | "abort";
+export interface CheckpointDecision {
+  action: CheckpointAction;
+  /** Present only when action === "revise". */
+  feedback?: string;
+}

package/src/lifecycle/port.ts

@@ -0,0 +1,7 @@
+// src/lifecycle/port.ts
+export { parseLifecycleFile, discoverLifecycles, LifecycleParseError } from "./registry.ts";
+export type { LifecycleDiscoverOpts, LifecycleDiscoverResult } from "./registry.ts";
+export type {
+  LifecycleStatus, LifecycleMode, BackendId, PhaseDef, LifecycleDef, PhaseRecord,
+  LifecycleRunRecord, CheckpointAction, CheckpointDecision,
+} from "./lifecycle-types.ts";

package/src/lifecycle/prompt-template.ts

@@ -0,0 +1,40 @@
+// src/lifecycle/prompt-template.ts
+import type { PhaseRecord } from "./lifecycle-types.ts";
+
+export interface PromptVars {
+  task: string;
+  lifecycle: string;
+  phase: string;
+  /** Previous phase record (absent on phase 1). */
+  prev?: { name: string; summary: string; paths: string[] };
+  /** On Revise only: human feedback + prior-attempt digest. */
+  feedback?: string;
+}
+
+/** Render a phase prompt template. Supports {{task}}, {{lifecycle}}, {{phase}},
+ *  {{prev.name}}, {{prev.summary}}, {{prev.paths}}, {{feedback}}, and
+ *  {% if prev %}…{% endif %} / {% if feedback %}…{% endif %} conditional blocks. */
+export function renderPhasePrompt(template: string, vars: PromptVars): string {
+  let out = template;
+
+  // {% if prev %}…{% endif %}
+  out = out.replace(/{%\s*if\s*prev\s*%}([\s\S]*?){%\s*endif\s*%}/g,
+    vars.prev ? "$1" : "");
+  // {% if feedback %}…{% endif %}
+  out = out.replace(/{%\s*if\s*feedback\s*%}([\s\S]*?){%\s*endif\s*%}/g,
+    vars.feedback ? "$1" : "");
+
+  // {{prev.paths}} → newline-separated "- path" list (or empty)
+  const pathsStr = vars.prev ? vars.prev.paths.map((p) => `- ${p}`).join("\n") : "";
+
+  out = out
+    .replace(/{{\s*task\s*}}/g, vars.task)
+    .replace(/{{\s*lifecycle\s*}}/g, vars.lifecycle)
+    .replace(/{{\s*phase\s*}}/g, vars.phase)
+    .replace(/{{\s*prev\.name\s*}}/g, vars.prev?.name ?? "")
+    .replace(/{{\s*prev\.summary\s*}}/g, vars.prev?.summary ?? "")
+    .replace(/{{\s*prev\.paths\s*}}/g, pathsStr)
+    .replace(/{{\s*feedback\s*}}/g, vars.feedback ?? "");
+
+  return out;
+}