@xzzpig/pi-openspec-x 0.1.0

package/src/objective.ts

@@ -0,0 +1,246 @@
+/**
+ * Objective assembler for the `/opsx:implement` execution base (design D10;
+ * openspec change add-pi-openspec-x, task 6.2).
+ *
+ * The implementation flow runs on top of a persistent pi-goal-x goal, and the
+ * goal's objective is where the opsx orchestration contract lives. This module
+ * turns the authoritative `tasks.md` into:
+ *
+ * - the objective text handed to goal-x's `create_goal`: a `Steps` section (the
+ *   task list), a `Boundaries`/`Don'ts` section (the read-only boundary and the
+ *   flow discipline), and the single `Verification contract:` line goal-x
+ *   extracts;
+ * - the flat task list handed to goal-x's `set_goal_tasks` (mirror of the same
+ *   tasks, ids preserved 1:1 so the bidirectional sync in task 6.3 can follow);
+ * - the task count gate: `set_goal_tasks` accepts at most 50 nodes, so a
+ *   larger tasks.md is refused with guidance instead of silently truncated.
+ *
+ * Flow discipline is written into the objective text on purpose (design D10:
+ * "策略调校同受流程隔离约束"). Global goal policy settings are never touched
+ * — a global switch would change every plain `/goal`, and the objective is the
+ * per-goal carrier that cannot leak.
+ *
+ * The assembler is pure: it reads the tasks.md string it is given and returns
+ * data. Callers own file reading and goal-tool invocation.
+ */
+import {
+  duplicateTaskIds,
+  parseTasksMarkdown,
+  type OpsxTask,
+} from "./tasks-md.ts";
+
+/** `set_goal_tasks` hard limit (goal-task-tools.ts MAX_TASKS). */
+export const MAX_GOAL_TASKS = 50;
+
+/**
+ * The objective's `Verification contract:` value. goal-x extracts this line
+ * into the goal's own verificationContract, and the completion audit reads it.
+ */
+export const OPSX_VERIFICATION_CONTRACT =
+  "Implementation completion requires the goal completion audit to APPROVE; a fully ticked tasks.md is not completion.";
+
+/** Which implementation mode the objective describes. */
+export type OpsxImplementationMode = "agent" | "direct";
+
+/** The read-only boundary the objective encodes, per implementation mode. */
+export interface OpsxBoundaries {
+  mode: OpsxImplementationMode;
+  /**
+   * Write allowlist globs for the agent sandbox (design D4). Ignored in
+   * direct mode, where the main session keeps normal permissions.
+   */
+  writable: string[];
+}
+
+export interface AssembleObjectiveInput {
+  /** The openspec change id the goal implements. */
+  changeId: string;
+  /** Raw tasks.md content; `undefined` when the file does not exist. */
+  tasksMarkdown: string | undefined;
+  boundaries: OpsxBoundaries;
+}
+
+/** One `set_goal_tasks` entry (flat, parent-linked shape; all roots here). */
+export interface FlatGoalTaskInput {
+  id: string;
+  title: string;
+  verification_contract?: string;
+}
+
+/** Why the assembler refused to build an objective. */
+export type ObjectiveAssemblyFailureCode =
+  | "no_tasks_file"
+  | "no_tasks"
+  | "too_many_tasks"
+  | "duplicate_ids";
+
+export type ObjectiveAssembly =
+  | {
+      ok: true;
+      objective: string;
+      tasks: OpsxTask[];
+      /** The flat task list to mirror through `set_goal_tasks`. */
+      goalTasks: FlatGoalTaskInput[];
+      verificationContract: string;
+      /**
+       * The `create_goal` invocation the main agent makes to start the flow:
+       * sisyphus in agent mode (patient ordered execution), a regular
+       * autoContinue goal in direct mode (task 6.4).
+       */
+      goalStart: { objective: string; mode: "regular" | "sisyphus" };
+    }
+  | {
+      ok: false;
+      code: ObjectiveAssemblyFailureCode;
+      message: string;
+      guidance: string;
+    };
+
+/**
+ * Build the flat goal task list from the parsed tasks. Ids are preserved
+ * verbatim (the sync key), and the per-task verification contract travels
+ * along so the goal completion gate can demand evidence.
+ */
+export function toFlatGoalTasks(
+  tasks: readonly OpsxTask[],
+): FlatGoalTaskInput[] {
+  return tasks.map((task) => ({
+    id: task.id,
+    title: task.title,
+    ...(task.verificationContract
+      ? { verification_contract: task.verificationContract }
+      : {}),
+  }));
+}
+
+import { STANDARD_WORKER_MUST_NOT_DO } from "./worker-dispatch.ts";
+
+function agentBoundaries(writable: readonly string[]): string[] {
+  const writableText = writable.length > 0 ? writable.join(", ") : "(none)";
+  return [
+    "Boundaries:",
+    `- Writable: ${writableText}. Nothing else is writable.`,
+    "- Everything else, including the source tree, is read-only.",
+    "- Source changes happen only through an opsx-worker dispatch; the main agent never edits a source file itself.",
+    "- openspec/ plan files (tasks.md, proposal.md, specs/, design.md) are read-only for opsx-worker; only the main agent ticks tasks.md, after review.",
+    "",
+    "Worker dispatch contract (task 8.2): every opsx-worker dispatch carries these six sections, in this order:",
+    "1. Task — the task id and title.",
+    "2. Expected output — the concrete files/behavior the dispatch must produce.",
+    "3. Tools — the tools the worker needs for this task.",
+    "4. Must do — the task-specific obligations.",
+    "5. Must not do — the task-specific prohibitions, plus:",
+    ...STANDARD_WORKER_MUST_NOT_DO.map((rule) => `   - ${rule}`),
+    "6. Context — the files/behavior/constraints the worker needs to know.",
+    "After the dispatch: review its full diff and its verification output, then call report_work with taskId, changedFiles and the verification command/result. Ticking a task before that report exists is blocked by the tick gate, and a report that claims files the dispatch did not change (or omits files it did) is held for reconciliation.",
+    "",
+    "Don'ts:",
+    "- Do not edit source files directly, not even for a one-line fix; dispatch opsx-worker.",
+    "- Do not tick a task in tasks.md before reviewing the worker's full diff and running its verification.",
+    "- Do not idle-wait between tasks; after a reviewed dispatch, immediately start the next pending task.",
+    "- Do not change global goal policy settings; the flow discipline lives in this objective.",
+  ];
+}
+
+function directBoundaries(): string[] {
+  return [
+    "Boundaries:",
+    "- The main session implements directly: no role switch and no sandbox restriction.",
+    "- tasks.md is the task authority and openspec/ is the plan contract.",
+    "- The completion audit still gates completion: every task being ticked is not completion.",
+    "",
+    "Don'ts:",
+    "- Do not skip a task's stated verification.",
+    "- Do not tick a task in tasks.md before its verification passes.",
+    "- Do not idle-wait between tasks; after finishing one, immediately start the next pending task.",
+    "- Do not change global goal policy settings; the flow discipline lives in this objective.",
+  ];
+}
+
+/**
+ * Assemble the objective text and goal task mirror for one implementation
+ * flow. Refuses (never truncates) when there is no usable task list:
+ *
+ * - no tasks.md → run `/opsx:plan` first (or point at the change's tasks.md);
+ * - no tracked task → the change has nothing to implement;
+ * - more than {@link MAX_GOAL_TASKS} tasks → split the change, because
+ *   `set_goal_tasks` cannot mirror a longer list;
+ * - duplicate ids → the mirror would silently drop or collide tasks.
+ */
+export function assembleOpsxObjective(
+  input: AssembleObjectiveInput,
+): ObjectiveAssembly {
+  if (input.tasksMarkdown === undefined) {
+    return {
+      ok: false,
+      code: "no_tasks_file",
+      message: `No tasks.md was found for change "${input.changeId}".`,
+      guidance:
+        "Run /opsx:plan to produce the change plan (proposal/specs/design/tasks) first, then retry /opsx:implement.",
+    };
+  }
+
+  const tasks = parseTasksMarkdown(input.tasksMarkdown);
+  if (tasks.length === 0) {
+    return {
+      ok: false,
+      code: "no_tasks",
+      message: `tasks.md for change "${input.changeId}" contains no tracked tasks.`,
+      guidance:
+        "tasks.md must list checkbox tasks (`- [ ] 1.1 ...`); add them (or re-run /opsx:plan) before implementing.",
+    };
+  }
+
+  const duplicates = duplicateTaskIds(tasks);
+  if (duplicates.length > 0) {
+    return {
+      ok: false,
+      code: "duplicate_ids",
+      message: `tasks.md for change "${input.changeId}" repeats task id(s): ${duplicates.join(", ")}.`,
+      guidance:
+        "Task ids must be unique because the goal task mirror is keyed by id; fix the duplicate ids in tasks.md and retry.",
+    };
+  }
+
+  if (tasks.length > MAX_GOAL_TASKS) {
+    return {
+      ok: false,
+      code: "too_many_tasks",
+      message: `tasks.md for change "${input.changeId}" has ${tasks.length} tasks; set_goal_tasks accepts at most ${MAX_GOAL_TASKS}.`,
+      guidance:
+        "Split the change into smaller changes (or merge trivial tasks) so tasks.md stays within the limit, then retry /opsx:implement.",
+    };
+  }
+
+  const lines: string[] = [
+    `Implement the OpenSpec change "${input.changeId}".`,
+    "",
+    "Steps:",
+  ];
+  tasks.forEach((task, index) => {
+    const contract = task.verificationContract
+      ? ` — verification: ${task.verificationContract}`
+      : "";
+    lines.push(`${index + 1}. [${task.id}] ${task.title}${contract}`);
+  });
+  lines.push("");
+  lines.push(
+    ...(input.boundaries.mode === "agent"
+      ? agentBoundaries(input.boundaries.writable)
+      : directBoundaries()),
+  );
+  lines.push("");
+  lines.push(`Verification contract: ${OPSX_VERIFICATION_CONTRACT}`);
+
+  return {
+    ok: true,
+    objective: lines.join("\n"),
+    tasks,
+    goalTasks: toFlatGoalTasks(tasks),
+    verificationContract: OPSX_VERIFICATION_CONTRACT,
+    goalStart: {
+      objective: lines.join("\n"),
+      mode: input.boundaries.mode === "agent" ? "sisyphus" : "regular",
+    },
+  };
+}

package/src/plan-command.ts

@@ -0,0 +1,285 @@
+/**
+ * `/opsx:plan` command and turn_end injection wiring (design D5; openspec
+ * change add-pi-openspec-x, task 7.1).
+ *
+ * Entering the plan mode appends one mode-contract message (never a system
+ * prompt rewrite), and each turn_end appends at most one new phase block
+ * through the BoundaryResult `entries` channel — the append-only discipline
+ * that keeps the prompt-prefix cache intact. Skill registration is untouched.
+ *
+ * All CLI access is injectable: the default fetchers run the real `openspec
+ * status` / `openspec instructions` commands, while tests supply data or
+ * failures. A CLI failure degrades to the built-in skeleton and a notice; it
+ * never stops the flow.
+ */
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+  ExtensionHandler,
+  TurnEndEvent,
+  TurnEndEventResult,
+} from "@earendil-works/pi-coding-agent";
+
+import {
+  getOpenspecArtifactInstructions,
+  runOpenspecJson,
+  type OpenspecArtifactInstructions,
+  type OpenspecCliOptions,
+} from "./cli.ts";
+import { describeError } from "./dependencies.ts";
+import { sendNotice, sessionKey } from "./command-util.ts";
+import { appendFlowEntry, OPSX_ENTRY_TYPES } from "./flow-entries.ts";
+import { publishLifecycle, type EventEmitterLike } from "./lifecycle.ts";
+import { enterOpsxMode } from "./mode.ts";
+import {
+  nextPlanPhase,
+  renderPlanModeContract,
+  renderPlanPhaseBlock,
+  type PlanStatus,
+} from "./plan-flow.ts";
+
+/** customType of the appended mode-contract message. */
+export const PLAN_MODE_CONTRACT_CUSTOM_TYPE =
+  "pi-openspec-x/plan-mode-contract";
+/** customType of an appended phase instruction block. */
+export const PLAN_PHASE_CUSTOM_TYPE = "pi-openspec-x/plan-phase";
+/** customType of a plan-flow notice. */
+export const PLAN_NOTICE_CUSTOM_TYPE = "pi-openspec-x/plan-notice";
+
+export interface PlanFlowDeps {
+  /** CLI options (env/cwd/spawn) forwarded to the default fetchers. */
+  cliOptions?: OpenspecCliOptions;
+  /** Injectable status fetcher; defaults to `openspec status --json`. */
+  fetchStatus?: (changeId: string) => PlanStatus;
+  /** Injectable instructions fetcher; defaults to `openspec instructions`. */
+  fetchInstructions?: (
+    artifact: string,
+    changeId: string,
+  ) => OpenspecArtifactInstructions | undefined;
+  /** Injectable restricted-mode entry; defaults to the planner sandbox mode. */
+  enterMode?: (
+    pi: Pick<ExtensionAPI, "appendEntry">,
+    ctx: ExtensionCommandContext,
+  ) => Promise<void>;
+  /** Lifecycle bus; defaults to `pi.events` at call time. */
+  events?: EventEmitterLike;
+}
+
+interface PlanSession {
+  changeId: string;
+  /** Artifacts whose block was already appended (once per phase). */
+  injected: Set<string>;
+  degradedNotified: boolean;
+  reviewNotified: boolean;
+}
+
+const planSessions = new Map<string, PlanSession>();
+
+/** Reset the per-session plan-flow state. Test-only. */
+export function resetPlanFlowStateForTests(): void {
+  planSessions.clear();
+}
+
+/** The active plan session for a session id (status snapshot wiring). */
+export function activePlanSession(
+  sessionId: string,
+): { changeId: string } | undefined {
+  const session = planSessions.get(sessionId);
+  return session ? { changeId: session.changeId } : undefined;
+}
+
+/**
+ * End the plan session because the implementation flow takes over. Returns
+ * the change id of the ended session, or undefined when none was active.
+ */
+export function endPlanFlow(sessionId: string): string | undefined {
+  const session = planSessions.get(sessionId);
+  if (!session) return undefined;
+  planSessions.delete(sessionId);
+  return session.changeId;
+}
+
+function defaultFetchStatus(
+  changeId: string,
+  options: OpenspecCliOptions,
+): PlanStatus {
+  return runOpenspecJson<PlanStatus>(
+    ["status", "--change", changeId, "--json"],
+    options,
+  );
+}
+
+function defaultFetchInstructions(
+  artifact: string,
+  changeId: string,
+  options: OpenspecCliOptions,
+): OpenspecArtifactInstructions | undefined {
+  try {
+    return getOpenspecArtifactInstructions(artifact, changeId, options);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Build the turn_end handler that appends the next phase block. Returns an
+ * empty result while the change is unchanged, the block once per artifact,
+ * and `continue: true` so the agent picks the block up in the same run.
+ */
+function createPlanTurnEndHandler(
+  pi: Pick<ExtensionAPI, "sendMessage" | "appendEntry" | "events">,
+  deps: Required<Pick<PlanFlowDeps, "fetchStatus" | "fetchInstructions">>,
+): ExtensionHandler<TurnEndEvent, TurnEndEventResult> {
+  return (
+    _event: TurnEndEvent,
+    ctx: ExtensionContext,
+  ): TurnEndEventResult | void => {
+    const session = planSessions.get(sessionKey(ctx));
+    if (!session) return;
+
+    let status: PlanStatus;
+    try {
+      status = deps.fetchStatus(session.changeId);
+    } catch (error) {
+      sendNotice(
+        pi,
+        PLAN_NOTICE_CUSTOM_TYPE,
+        `Could not read the change status for "${session.changeId}": ${describeError(error)}. Fix the CLI/change id, then continue the plan flow.`,
+      );
+      return;
+    }
+
+    const phase = nextPlanPhase(status);
+    if (phase.kind === "review") {
+      if (!session.reviewNotified) {
+        session.reviewNotified = true;
+        sendNotice(
+          pi,
+          PLAN_NOTICE_CUSTOM_TYPE,
+          `Every artifact for change "${session.changeId}" is done. Dispatch the read-only opsx-plan-review plan reviewer and record each verdict with the opsx_plan_verdict tool; it applies the review-loop policy and opens the user approval dialog on OKAY.`,
+        );
+      }
+      return;
+    }
+
+    if (session.injected.has(phase.artifact)) return;
+    const instructions = deps.fetchInstructions(
+      phase.artifact,
+      session.changeId,
+    );
+    const block = renderPlanPhaseBlock(phase.artifact, instructions);
+    session.injected.add(phase.artifact);
+    appendFlowEntry(pi, OPSX_ENTRY_TYPES.phaseChanged, {
+      changeId: session.changeId,
+      phase: phase.artifact,
+    });
+    publishLifecycle(pi.events, {
+      type: "phase_changed",
+      change: session.changeId,
+      mode: "plan",
+      phase: phase.artifact,
+    });
+    if (block.degraded && !session.degradedNotified) {
+      session.degradedNotified = true;
+      sendNotice(
+        pi,
+        PLAN_NOTICE_CUSTOM_TYPE,
+        `Live instructions for artifact "${phase.artifact}" were unavailable; the built-in skeleton was injected instead. Re-run \`openspec instructions ${phase.artifact} --change "${session.changeId}" --json\` when the CLI answers.`,
+      );
+    }
+    return {
+      entries: [
+        {
+          type: "custom_message",
+          customType: PLAN_PHASE_CUSTOM_TYPE,
+          content: block.content,
+          display: true,
+        },
+      ],
+      continue: true,
+    };
+  };
+}
+
+/**
+ * Register the `/opsx:plan` command and the turn_end injection handler. The
+ * command enters the restricted planner mode (fail-closed) before appending
+ * the mode contract.
+ */
+export function registerPlanFlow(
+  pi: ExtensionAPI,
+  deps: PlanFlowDeps = {},
+): void {
+  const cliOptions = deps.cliOptions ?? {};
+  const fetchStatus =
+    deps.fetchStatus ??
+    ((changeId: string) => defaultFetchStatus(changeId, cliOptions));
+  const fetchInstructions =
+    deps.fetchInstructions ??
+    ((artifact: string, changeId: string) =>
+      defaultFetchInstructions(artifact, changeId, cliOptions));
+  const enterMode =
+    deps.enterMode ??
+    ((
+      target: Pick<ExtensionAPI, "appendEntry">,
+      ctx: ExtensionCommandContext,
+    ) =>
+      enterOpsxMode(target as ExtensionAPI, "planner", {
+        sessionId: () => ctx.sessionManager.getSessionId(),
+      }).then(() => undefined));
+
+  pi.registerCommand("opsx:plan", {
+    description:
+      "Run the enhanced OpenSpec planning flow for a change (planner mode, gap-analysis / plan-review gates, user approval).",
+    async handler(args: string, ctx: ExtensionCommandContext): Promise<void> {
+      const changeId = args.trim();
+      if (!changeId) {
+        sendNotice(
+          pi,
+          PLAN_NOTICE_CUSTOM_TYPE,
+          "Usage: /opsx:plan <change-id>",
+        );
+        return;
+      }
+      try {
+        await enterMode(pi, ctx);
+      } catch (error) {
+        sendNotice(
+          pi,
+          PLAN_NOTICE_CUSTOM_TYPE,
+          `Cannot enter plan mode: ${describeError(error)}`,
+        );
+        return;
+      }
+      planSessions.set(sessionKey(ctx), {
+        changeId,
+        injected: new Set(),
+        degradedNotified: false,
+        reviewNotified: false,
+      });
+      pi.sendMessage(
+        {
+          customType: PLAN_MODE_CONTRACT_CUSTOM_TYPE,
+          content: renderPlanModeContract(changeId),
+          display: true,
+        },
+        { deliverAs: "steer" },
+      );
+      appendFlowEntry(pi, OPSX_ENTRY_TYPES.modeEntered, {
+        changeId,
+        mode: "plan",
+      });
+      publishLifecycle(deps.events ?? pi.events, {
+        type: "plan_started",
+        change: changeId,
+        mode: "plan",
+      });
+    },
+  });
+
+  pi.on(
+    "turn_end",
+    createPlanTurnEndHandler(pi, { fetchStatus, fetchInstructions }),
+  );
+}

package/src/plan-flow.ts

@@ -0,0 +1,133 @@
+/**
+ * `/opsx:plan` phase model and append-only injection blocks (design D5; openspec
+ * change add-pi-openspec-x, task 7.1).
+ *
+ * The plan flow never rewrites the system prompt and never adds or removes a
+ * skill mid-session (that would break the prompt-prefix cache): the mode
+ * contract is one appended message, and each phase appends exactly one
+ * instruction block, built live from
+ * `openspec instructions <artifact> --change <id> --json`. When the CLI cannot
+ * answer (no change yet, CLI error, malformed output) the block degrades to a
+ * built-in skeleton and the caller raises a notice — the flow never stops.
+ *
+ * This module is pure: phase selection and block rendering take data and
+ * return data. The command/turn_end wiring lives in ./plan-command.ts.
+ */
+import type { OpenspecArtifactInstructions } from "./cli.ts";
+
+/** The spec-driven artifact order, used only for the built-in skeleton text. */
+const PLAN_ARTIFACT_ORDER = ["proposal", "specs", "design", "tasks"] as const;
+
+type PlanArtifact = string;
+
+/** The validated slice of `openspec status --change <id> --json`. */
+export interface PlanStatusArtifact {
+  id: string;
+  status: string;
+  requires?: string[];
+}
+
+export interface PlanStatus {
+  artifacts?: PlanStatusArtifact[];
+}
+
+/** The next thing the plan flow must do. */
+export type PlanPhase =
+  | { kind: "artifact"; artifact: PlanArtifact }
+  | { kind: "review" };
+
+/**
+ * The first artifact that is neither done nor skipped, in the status output's
+ * own order (which is the schema's dependency order). Every artifact done
+ * means the plan is ready for the plan-review gate.
+ */
+export function nextPlanPhase(status: PlanStatus): PlanPhase {
+  const pending = (status.artifacts ?? []).find(
+    (artifact) => artifact.status !== "done" && artifact.status !== "skipped",
+  );
+  return pending
+    ? { kind: "artifact", artifact: pending.id }
+    : { kind: "review" };
+}
+
+/** The decision-complete slice every phase block carries. */
+const DECISION_COMPLETE_RULES = [
+  "Decision-complete rules for this artifact:",
+  '- Name exact file paths and symbols; never write "the relevant file".',
+  "- Reference every dependency exhaustively: what to read, what to change.",
+  "- State Must-NOT-Have explicitly: what is out of scope.",
+  '- Every acceptance criterion must be executable by an agent (a command, a file check, a test run); no "the user confirms".',
+  "- Leave the implementer zero judgment calls.",
+];
+
+const ARTIFACT_SKELETONS: Record<string, string> = {
+  proposal:
+    "Write proposal.md: Why, What Changes, Capabilities (New/Modified), Impact. Keep it to the change's intent and boundaries.",
+  specs:
+    "Write the spec deltas under specs/: ADDED/MODIFIED/REMOVED requirements with WHEN/THEN scenarios. Keep capability paths stable.",
+  design:
+    "Write design.md: Context, Goals/Non-Goals, Decisions (including rejected alternatives), Risks, Migration, Open Questions.",
+  tasks:
+    "Write tasks.md: `## N. Group` headings and `- [ ] X.Y ...` checkbox tasks; every task states how to verify completion.",
+};
+
+const GENERIC_SKELETON =
+  "Follow the schema's artifact requirements; the CLI instructions are authoritative whenever they are available.";
+
+/** The mode-contract message appended once when the plan mode is entered. */
+export function renderPlanModeContract(changeId: string): string {
+  return [
+    `[OPSX PLAN MODE change=${changeId}]`,
+    `You are now in the opsx planning flow for change "${changeId}". Your writes are restricted to openspec/ (the opsx-planner sandbox profile); everything else is read-only.`,
+    "Flow: write the change artifacts in dependency order, each following its live `openspec instructions <artifact> --change <id> --json` output. Dispatch the read-only opsx-gap-analysis gap analyst mid-way, absorb its findings into the artifacts, and record them with the `opsx_plan_gap_analysis` tool. When every artifact is done, dispatch the read-only opsx-plan-review plan reviewer, record each verdict with `opsx_plan_verdict`, and follow that tool's instruction: revise and re-review, hand over to the user when it escalates, or — only after OKAY — let it open the blocking user approval dialog.",
+    "Discipline: decision-complete writing (exact paths, exhaustive references, explicit Must-NOT-Have, agent-executable acceptance criteria). Do not implement code in this mode. Only the user's explicit approval unlocks implementation; an OKAY verdict is not approval.",
+  ].join("\n");
+}
+
+export interface PlanPhaseBlock {
+  artifact: PlanArtifact;
+  content: string;
+  /** True when the live CLI instructions were unavailable and the skeleton was used. */
+  degraded: boolean;
+}
+
+/**
+ * Render one phase's append-only instruction block. `instructions === undefined`
+ * is the explicit degradation path (no change yet, CLI error, malformed
+ * output): the block says so and falls back to the built-in skeleton.
+ */
+export function renderPlanPhaseBlock(
+  artifact: PlanArtifact,
+  instructions: OpenspecArtifactInstructions | undefined,
+): PlanPhaseBlock {
+  const skeleton = ARTIFACT_SKELETONS[artifact] ?? GENERIC_SKELETON;
+  if (!instructions) {
+    return {
+      artifact,
+      degraded: true,
+      content: [
+        `[OPSX PLAN PHASE: ${artifact}] (live CLI instructions unavailable — built-in skeleton)`,
+        "Re-run `openspec instructions " +
+          artifact +
+          ' --change "<change-id>" --json` once the CLI answers, and follow that output over this skeleton.',
+        "",
+        skeleton,
+        "",
+        ...DECISION_COMPLETE_RULES,
+      ].join("\n"),
+    };
+  }
+
+  const lines = [`[OPSX PLAN PHASE: ${artifact}]`, instructions.instruction];
+  if (instructions.resolvedOutputPath) {
+    lines.push("", `Write to: ${instructions.resolvedOutputPath}`);
+  }
+  if (instructions.template) {
+    lines.push("", "Template:", instructions.template);
+  }
+  if (instructions.rules && instructions.rules.length > 0) {
+    lines.push("", "Rules:", ...instructions.rules.map((rule) => `- ${rule}`));
+  }
+  lines.push("", ...DECISION_COMPLETE_RULES);
+  return { artifact, degraded: false, content: lines.join("\n") };
+}