ahead-pi 0.1.1 → 0.2.1

package/src/index.ts

@@ -7,6 +7,20 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { AheadEngine, AheadEngineError } from "./engine.js";
+import {
+  buildArtifactTemplate,
+  buildWidgetLines,
+  nextAction,
+  phaseGuide,
+  phasePosition,
+} from "./guidance.js";
+import {
+  findReference,
+  loadReferenceIndex,
+  readReference,
+  relevantReferences,
+} from "./reference.js";
+import { showReferenceViewer } from "./reference-viewer.js";
 import { humanActor, projectRoot, RunStore } from "./storage.js";
 import type { Actor, Capability, EventAction, Run, RunState } from "./types.js";
 
@@ -31,38 +45,34 @@ const RecordArtifactParams = Type.Object({
   kind: Type.String({ description: "Artifact kind permitted for AI in the active phase" }),
   content: Type.String({ description: "Complete Markdown artifact content", maxLength: 100_000 }),
 });
+const ReferenceParams = Type.Object({
+  topic: Type.Optional(Type.String({ description: "Reference id, path, or title; omit to list phase-relevant references" })),
+});
 
 export default function aheadExtension(pi: ExtensionAPI): void {
+  pi.registerCommand("ahead", {
+    description: "Enter or continue the guided AHEAD mode",
+    handler: async (args, ctx) => command(ctx, async () => {
+      await openAheadMode(pi, args, ctx);
+    }),
+  });
+
+  pi.registerCommand("ahead-guide", {
+    description: "Read the AHEAD framework guidance relevant to the active phase",
+    handler: async (args, ctx) => command(ctx, async () => {
+      await showAheadGuide(ctx, args);
+    }),
+  });
+
   pi.registerCommand("ahead-start", {
-    description: "Start a Product Change workflow owned by the current human",
+    description: "Advanced: start a Product Change run directly",
     handler: async (args, ctx) => command(ctx, async () => {
-      const engine = await enginePromise;
-      const store = storeFor(ctx);
-      const current = await store.loadCurrent();
-      if (current && !engine.deriveState(current).closed) {
-        throw new AheadEngineError(
-          "active_run_exists",
-          `run ${current.id} is still active; close it before starting another`,
-        );
-      }
-      const title = args.trim() || (ctx.hasUI ? await ctx.ui.input("AHEAD Product Change", "Run title") : undefined);
-      if (!title?.trim()) return;
-      const owner = humanActor(store.projectRoot);
-      const run = engine.createRun({
-        id: store.newRunId(),
-        title: title.trim(),
-        owner,
-        timestamp: new Date().toISOString(),
-        workflow_id: "product-change",
-      });
-      await store.save(run);
-      await refreshUi(ctx, run);
-      ctx.ui.notify(`Started AHEAD run ${run.id}. Record the human-owned problem with /ahead-record problem.`, "info");
+      await startRun(ctx, args);
     }),
   });
 
   pi.registerCommand("ahead-status", {
-    description: "Show the active AHEAD phase, evidence, gate, and blockers",
+    description: "Advanced: show the raw active AHEAD phase contract",
     handler: async (_args, ctx) => command(ctx, async () => {
       const run = await requireRun(ctx);
       const state = (await enginePromise).deriveState(run);
@@ -72,50 +82,14 @@ export default function aheadExtension(pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("ahead-record", {
-    description: "Write and record a human-owned artifact for the active phase",
+    description: "Advanced: record a human-owned artifact directly",
     handler: async (args, ctx) => command(ctx, async () => {
-      if (!ctx.hasUI) throw new Error("/ahead-record requires interactive or RPC UI support");
-      const engine = await enginePromise;
-      const store = storeFor(ctx);
-      const run = await requireRun(ctx);
-      const state = engine.deriveState(run);
-      const allowed = state.artifacts.filter((artifact) => artifact.actor !== "ai");
-      let kind = args.trim();
-      if (!kind) {
-        kind = (await ctx.ui.select(
-          `Record human artifact · ${state.phase.title}`,
-          allowed.map((artifact) => artifact.kind),
-        )) ?? "";
-      }
-      const artifact = allowed.find((candidate) => candidate.kind === kind);
-      if (!artifact) {
-        throw new AheadEngineError(
-          "artifact_not_human_owned",
-          `human cannot record ${kind || "that artifact"} in phase ${state.phase.id}; choose: ${allowed.map((item) => item.kind).join(", ")}`,
-        );
-      }
-      const content = await ctx.ui.editor(
-        `AHEAD · ${artifact.title}`,
-        artifactTemplate(run, state, artifact.kind, artifact.title),
-      );
-      if (!content?.trim()) return;
-      const path = store.artifactPath(run, state.phase.id, artifact.kind);
-      const action: EventAction = {
-        type: "artifact_recorded",
-        phase: state.phase.id,
-        kind: artifact.kind,
-        path: path.relative,
-      };
-      const updated = engine.applyEvent(run, humanActor(store.projectRoot), action);
-      await store.writeArtifact(path.absolute, content);
-      await store.save(updated);
-      await refreshUi(ctx, updated);
-      ctx.ui.notify(`Recorded ${artifact.kind} as ${path.relative}`, "info");
+      await recordHumanArtifact(ctx, args.trim());
     }),
   });
 
   pi.registerCommand("ahead-accept", {
-    description: "Human acceptance of the active phase gate",
+    description: "Advanced: accept the active gate without advancing",
     handler: async (_args, ctx) => command(ctx, async () => {
       if (!ctx.hasUI) throw new Error("/ahead-accept requires interactive or RPC UI support");
       const engine = await enginePromise;
@@ -139,7 +113,7 @@ export default function aheadExtension(pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("ahead-advance", {
-    description: "Human transition to the next phase, or close the final phase",
+    description: "Advanced: advance an already accepted gate",
     handler: async (_args, ctx) => command(ctx, async () => {
       if (!ctx.hasUI) throw new Error("/ahead-advance requires interactive or RPC UI support");
       const engine = await enginePromise;
@@ -168,57 +142,26 @@ export default function aheadExtension(pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("ahead-return", {
-    description: "Human return to an allowed earlier phase with a recorded reason",
+    description: "Advanced: return to an earlier phase with a reason",
     handler: async (args, ctx) => command(ctx, async () => {
-      if (!ctx.hasUI) throw new Error("/ahead-return requires interactive or RPC UI support");
-      const engine = await enginePromise;
-      const store = storeFor(ctx);
-      const run = await requireRun(ctx);
-      const state = engine.deriveState(run);
-      if (!state.return_targets.length) {
-        throw new AheadEngineError("no_return_target", `phase ${state.phase.id} has no return transition`);
-      }
-      let target = args.trim();
-      if (!target) target = (await ctx.ui.select("Return to which phase?", state.return_targets)) ?? "";
-      if (!state.return_targets.includes(target)) {
-        throw new AheadEngineError(
-          "invalid_return",
-          `phase ${state.phase.id} can return only to: ${state.return_targets.join(", ")}`,
-        );
-      }
-      const reason = await ctx.ui.editor(`Why return to ${target}?`);
-      if (!reason?.trim()) return;
-      const confirmed = await ctx.ui.confirm(
-        `Return to ${target}?`,
-        "This creates a new phase visit. Earlier artifacts remain in history but will not satisfy the reopened gate.",
-      );
-      if (!confirmed) return;
-      const updated = engine.applyEvent(run, humanActor(store.projectRoot), {
-        type: "phase_transitioned",
-        from: state.phase.id,
-        to: target,
-        direction: "return",
-        reason: reason.trim(),
-      });
-      await store.save(updated);
-      await refreshUi(ctx, updated);
-      ctx.ui.notify(`Returned to ${target}. New evidence and human gate acceptance are required.`, "warning");
+      await returnToEarlierPhase(ctx, args);
     }),
   });
 
   pi.registerCommand("ahead-help", {
-    description: "Show AHEAD Pi commands and the human/AI boundary",
+    description: "Explain guided AHEAD mode and its authority boundary",
     handler: async (_args, ctx) => {
       ctx.ui.notify(
         [
-          "/ahead-start [title] — start a human-owned Product Change run",
-          "/ahead-status — show phase, evidence, gate, and blockers",
-          "/ahead-record [kind] — human writes an artifact",
-          "/ahead-accept — human accepts the current gate",
-          "/ahead-advance — human advances or closes",
-          "/ahead-return [phase] — human reopens an allowed earlier phase",
+          "/ahead [title] — enter, resume, or act in guided AHEAD mode",
+          "/ahead-guide [topic] — read the applicable AHEAD framework Markdown",
+          "",
+          "Once started, the repository run remains in AHEAD mode until an accountable human closes the outcome.",
+          "Use normal conversation to think and work with AI. Run /ahead whenever you want the next valid action.",
+          "The persistent guide explains what you own, what AI may do, required evidence, and what happens next.",
           "",
-          "AI can inspect context and record only AI-permitted artifacts. It cannot accept gates or transition the run.",
+          "Advanced fallback commands: /ahead-status, /ahead-record, /ahead-accept, /ahead-advance, /ahead-return.",
+          "AI can record only AI/shared artifacts allowed in the active phase. It cannot accept gates, transition, approve, deploy, or close the run.",
         ].join("\n"),
         "info",
       );
@@ -240,6 +183,34 @@ export default function aheadExtension(pi: ExtensionAPI): void {
     },
   });
 
+  pi.registerTool({
+    name: "ahead_get_reference",
+    label: "AHEAD framework reference",
+    description: "List or read packaged AHEAD Constitution, philosophy, acceptable-use, engineering-practice, workflow, and evidence Markdown.",
+    promptSnippet: "Retrieve relevant AHEAD framework guidance when the phase or policy is unclear.",
+    parameters: ReferenceParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      return toolResult(async () => {
+        const run = await storeFor(ctx).loadCurrent();
+        const phase = run && !(await enginePromise).deriveState(run).closed
+          ? (await enginePromise).deriveState(run).phase.id
+          : undefined;
+        if (!params.topic?.trim()) {
+          const index = await loadReferenceIndex();
+          return {
+            phase: phase ?? null,
+            recommended: await relevantReferences(phase),
+            available: index.references.map(({ id, title, path }) => ({ id, title, path })),
+            instruction: "Request one reference by id, path, or title. Load only what is relevant.",
+          };
+        }
+        const entry = await findReference(params.topic);
+        if (!entry) throw new Error(`No packaged AHEAD reference matches ${params.topic}`);
+        return { reference: entry, content: await readReference(entry) };
+      });
+    },
+  });
+
   pi.registerTool({
     name: "ahead_record_artifact",
     label: "Record AHEAD artifact",
@@ -290,7 +261,7 @@ export default function aheadExtension(pi: ExtensionAPI): void {
           requested: true,
           transitioned: false,
           message: state.can_advance
-            ? `The gate is accepted. Ask the human to use /ahead-advance to ${state.phase.next ?? "close the run"}.`
+            ? `The gate is accepted. Ask the human to use /ahead to ${state.phase.next ?? "close the run"}.`
             : "The phase cannot advance. The human must resolve the blockers and accept the gate.",
           blockers: state.blockers,
         };
@@ -311,6 +282,14 @@ export default function aheadExtension(pi: ExtensionAPI): void {
   pi.on("session_start", async (_event, ctx) => {
     try {
       await refreshUi(ctx);
+      const run = await storeFor(ctx).loadCurrent();
+      if (run && !(await enginePromise).deriveState(run).closed && ctx.hasUI) {
+        const state = (await enginePromise).deriveState(run);
+        ctx.ui.notify(
+          `AHEAD mode resumed · ${state.phase.title}. Human leads, AI assists. Run /ahead for the next guided action.`,
+          "info",
+        );
+      }
     } catch (error) {
       ctx.ui.setStatus("ahead", "AHEAD · invalid state");
       ctx.ui.notify(errorMessage(error), "error");
@@ -320,7 +299,12 @@ export default function aheadExtension(pi: ExtensionAPI): void {
   pi.on("before_agent_start", async (event, ctx) => {
     const run = await storeFor(ctx).loadCurrent();
     if (!run) return;
-    const state = (await enginePromise).deriveState(run);
+    const engine = await enginePromise;
+    const state = engine.deriveState(run);
+    if (state.closed) return;
+    const workflow = engine.getWorkflow(run.workflow_id);
+    const guidance = phaseGuide(state.phase.id);
+    const action = nextAction(state, workflow);
     const phaseInstructions = await loadInstructions(state.phase.id);
     const liveContext = [
       "# Live AHEAD run",
@@ -329,6 +313,18 @@ export default function aheadExtension(pi: ExtensionAPI): void {
       `- Gate accepted: ${state.gate.accepted}`,
       `- Current blockers: ${state.blockers.length ? state.blockers.join("; ") : "none"}`,
       `- Allowed AI capabilities: ${state.allowed_ai_capabilities.length ? state.allowed_ai_capabilities.join(", ") : "none"}`,
+      `- Human responsibility: ${guidance.human}`,
+      `- AI role: ${guidance.ai}`,
+      `- Next guided action (${action.actor}): ${action.label}`,
+      "",
+      "## AHEAD interaction behavior",
+      "- AHEAD is an active working mode, not a command checklist. Help the human understand and complete the active phase through normal conversation.",
+      "- When asked what to do, explain the current expectation in plain language; do not merely repeat artifact identifiers or slash commands.",
+      "- Never author a human-owned artifact, make a human decision, accept a gate, transition the run, approve a change, or claim accountability.",
+      "- When required AI-owned work is ready, record it with ahead_record_artifact and explain what the human must validate or decide.",
+      "- Treat AI review findings as hypotheses. Independent human review remains required for lasting engineering changes.",
+      "- Humans may ask questions at any phase. During implementation, help them understand or solve the problem without taking over; if their first attempt or current model is missing, ask for it.",
+      "- When AHEAD policy or rationale is unclear, use ahead_get_reference to retrieve only the applicable packaged Markdown.",
     ].join("\n");
     return { systemPrompt: `${event.systemPrompt}\n\n${phaseInstructions}\n\n${liveContext}\n` };
   });
@@ -337,6 +333,7 @@ export default function aheadExtension(pi: ExtensionAPI): void {
     if (event.toolName.startsWith("ahead_")) return;
     const run = await storeFor(ctx).loadCurrent();
     if (!run) return;
+    if ((await enginePromise).deriveState(run).closed) return;
     const capability = toolCapabilities[event.toolName];
     if (!capability) {
       return {
@@ -353,13 +350,437 @@ export default function aheadExtension(pi: ExtensionAPI): void {
   });
 }
 
+interface GuidedAction {
+  label: string;
+  run: () => Promise<void>;
+}
+
+async function openAheadMode(pi: ExtensionAPI, args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const engine = await enginePromise;
+  const store = storeFor(ctx);
+  let run = await store.loadCurrent();
+
+  if (run && engine.deriveState(run).closed) {
+    if (!ctx.hasUI) {
+      ctx.ui.notify("The current AHEAD run is complete. Start new work in an interactive Pi session.", "info");
+      return;
+    }
+    const choice = await ctx.ui.select("AHEAD work is complete", [
+      "Start a new Product Change",
+      "View the completed run",
+    ]);
+    if (choice === "View the completed run") {
+      ctx.ui.notify(formatState(engine.deriveState(run)), "info");
+      return;
+    }
+    if (choice !== "Start a new Product Change") return;
+    run = undefined;
+  }
+
+  if (!run) {
+    run = await startRun(ctx, args);
+    if (!run) return;
+  }
+
+  await refreshUi(ctx, run);
+  if (!ctx.hasUI) {
+    ctx.ui.notify(formatState(engine.deriveState(run)), "info");
+    return;
+  }
+
+  const state = engine.deriveState(run);
+  const workflow = engine.getWorkflow(run.workflow_id);
+  const guidance = phaseGuide(state.phase.id);
+  const action = nextAction(state, workflow);
+  const actions: GuidedAction[] = [];
+  const missingRequired = state.artifacts.filter((artifact) => artifact.required && !artifact.present);
+  if (action.artifactKind) {
+    actions.push({
+      label: action.label,
+      run: action.actor === "ai"
+        ? async () => requestAiAssistance(pi, state, action.artifactKind)
+        : async () => recordHumanArtifact(ctx, action.artifactKind ?? ""),
+    });
+  }
+
+  if (action.optional) {
+    const nextHumanArtifact = missingRequired.find((artifact) => artifact.actor === "human");
+    if (nextHumanArtifact) {
+      actions.push({
+        label: `Continue without optional AI challenge · Write ${nextHumanArtifact.title}`,
+        run: async () => recordHumanArtifact(ctx, nextHumanArtifact.kind),
+      });
+    }
+  }
+
+  if (missingRequired.length === 0 && !action.artifactKind) {
+    actions.push({
+      label: state.gate.accepted
+        ? action.label
+        : `Accept and continue · ${state.gate.title}`,
+      run: async () => acceptAndContinue(ctx),
+    });
+  }
+
+  if (
+    state.allowed_ai_capabilities.length > 0
+    && action.actor !== "ai"
+    && !missingRequired.some((artifact) => artifact.actor === "ai")
+    && state.phase.id !== "implement"
+  ) {
+    actions.push({
+      label: `Ask AI to assist · ${state.phase.title}`,
+      run: async () => requestAiAssistance(pi, state),
+    });
+  }
+
+  if (state.phase.id === "implement") {
+    actions.push({
+      label: "Ask AI for help understanding or solving a problem",
+      run: async () => askImplementationQuestion(pi, ctx, state),
+    });
+  }
+
+  if (state.return_targets.length > 0) {
+    actions.push({
+      label: "Return to an earlier phase",
+      run: async () => returnToEarlierPhase(ctx, ""),
+    });
+  }
+
+  actions.push({
+    label: "Read AHEAD framework guidance for this phase",
+    run: async () => showAheadGuide(ctx, ""),
+  });
+
+  actions.push({
+    label: "Explain this phase and its expectations",
+    run: async () => {
+      ctx.ui.notify(
+        [
+          `${state.phase.title} · Human leads, AI assists`,
+          `Goal: ${guidance.objective}`,
+          `You: ${guidance.human}`,
+          `AI: ${guidance.ai}`,
+          `Gate: ${state.gate.title}`,
+        ].join("\n"),
+        "info",
+      );
+    },
+  });
+
+  const selected = await ctx.ui.select(
+    `AHEAD mode · ${state.phase.title}\nNext (${action.actor === "human" ? "you" : "AI"}): ${action.label}`,
+    actions.map((candidate) => candidate.label),
+  );
+  const chosen = actions.find((candidate) => candidate.label === selected);
+  if (chosen) await chosen.run();
+}
+
+async function askImplementationQuestion(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  state: RunState,
+): Promise<void> {
+  if (!ctx.hasUI) throw new Error("Implementation coaching requires interactive or RPC UI support");
+  const question = await ctx.ui.editor(
+    "AHEAD implementation help · human first",
+    [
+      "## What are you trying to understand or solve?",
+      "",
+      "",
+      "## What do you currently think is happening or should happen?",
+      "",
+      "",
+      "## What have you tried or inspected so far?",
+      "",
+      "",
+      "## What kind of help would be useful?",
+      "",
+      "<!-- Ask for explanation, a hint, competing approaches, debugging help, or a bounded suggestion. -->",
+      "",
+    ].join("\n"),
+  );
+  if (!question?.trim()) return;
+  pi.sendUserMessage([
+    `AHEAD mode: help me with this ${state.phase.title} question while I remain the implementer.`,
+    "Use my current model and first attempt below. Help me understand or solve the problem with questions, explanation, evidence, hints, and bounded next steps.",
+    "Do not convert this question into autonomous implementation or author my human-owned records. If I later request a bounded mechanical edit, explain it so I can inspect and own it.",
+    "",
+    question.trim(),
+  ].join("\n"));
+}
+
+async function showAheadGuide(ctx: ExtensionCommandContext, requestedTopic: string): Promise<void> {
+  if (!ctx.hasUI) throw new Error("Reading AHEAD framework guidance requires interactive or RPC UI support");
+  const run = await storeFor(ctx).loadCurrent();
+  const phase = run && !(await enginePromise).deriveState(run).closed
+    ? (await enginePromise).deriveState(run).phase.id
+    : undefined;
+  const index = await loadReferenceIndex();
+  let entry = requestedTopic.trim() && requestedTopic.trim().toLowerCase() !== "all"
+    ? await findReference(requestedTopic)
+    : undefined;
+
+  if (requestedTopic.trim() && requestedTopic.trim().toLowerCase() !== "all" && !entry) {
+    throw new Error(`No packaged AHEAD reference matches ${requestedTopic.trim()}`);
+  }
+
+  if (!entry) {
+    const recommended = requestedTopic.trim().toLowerCase() === "all"
+      ? index.references
+      : await relevantReferences(phase);
+    const browseAll = "Browse all packaged AHEAD Markdown";
+    const selected = await ctx.ui.select(
+      phase ? `AHEAD guidance · ${phase}` : "AHEAD framework guidance",
+      [...recommended.map((candidate) => candidate.title), ...(recommended.length < index.references.length ? [browseAll] : [])],
+    );
+    if (!selected) return;
+    if (selected === browseAll) return showAheadGuide(ctx, "all");
+    entry = recommended.find((candidate) => candidate.title === selected);
+  }
+  if (!entry) return;
+
+  await showReferenceViewer(ctx, `AHEAD reference · ${entry.title}`, await readReference(entry));
+}
+
+async function startRun(ctx: ExtensionCommandContext, requestedTitle: string): Promise<Run | undefined> {
+  const engine = await enginePromise;
+  const store = storeFor(ctx);
+  const current = await store.loadCurrent();
+  if (current && !engine.deriveState(current).closed) {
+    throw new AheadEngineError(
+      "active_run_exists",
+      `run ${current.id} is still active; use /ahead to continue it`,
+    );
+  }
+
+  const title = requestedTitle.trim()
+    || (ctx.hasUI ? await ctx.ui.input("Enter AHEAD mode · Product Change", "What work are you doing?") : undefined);
+  if (!title?.trim()) return undefined;
+
+  const owner = humanActor(store.projectRoot);
+  const run = engine.createRun({
+    id: store.newRunId(),
+    title: title.trim(),
+    owner,
+    timestamp: new Date().toISOString(),
+    workflow_id: "product-change",
+  });
+  await store.save(run);
+  await refreshUi(ctx, run);
+  ctx.ui.notify(
+    [
+      `AHEAD mode started · ${run.title}`,
+      "Human leads · AI assists",
+      "This run remains active in the repository until an accountable human closes the outcome.",
+      "Use /ahead for the next guided action; use normal conversation to think and work with AI.",
+    ].join("\n"),
+    "info",
+  );
+  return run;
+}
+
+async function recordHumanArtifact(ctx: ExtensionCommandContext, requestedKind: string): Promise<void> {
+  if (!ctx.hasUI) throw new Error("Recording a human artifact requires interactive or RPC UI support");
+  const engine = await enginePromise;
+  const store = storeFor(ctx);
+  const run = await requireRun(ctx);
+  const state = engine.deriveState(run);
+  const allowed = state.artifacts.filter((artifact) => artifact.actor !== "ai" && !artifact.present);
+  let kind = requestedKind.trim();
+  if (!kind) {
+    kind = (await ctx.ui.select(
+      `AHEAD mode · Write for ${state.phase.title}`,
+      allowed.map((artifact) => artifact.title),
+    )) ?? "";
+    kind = allowed.find((artifact) => artifact.title === kind)?.kind ?? kind;
+  }
+  const artifact = allowed.find((candidate) => candidate.kind === kind);
+  if (!artifact) {
+    throw new AheadEngineError(
+      "artifact_not_human_owned",
+      `there is no unrecorded human artifact named ${kind || "that"} in ${state.phase.title}`,
+    );
+  }
+
+  const content = await ctx.ui.editor(
+    `AHEAD mode · ${artifact.title} · write in your own words`,
+    buildArtifactTemplate(run, state, artifact.kind, artifact.title),
+  );
+  if (!content?.trim()) return;
+  const path = store.artifactPath(run, state.phase.id, artifact.kind);
+  const action: EventAction = {
+    type: "artifact_recorded",
+    phase: state.phase.id,
+    kind: artifact.kind,
+    path: path.relative,
+  };
+  const updated = engine.applyEvent(run, humanActor(store.projectRoot), action);
+  await store.writeArtifact(path.absolute, content);
+  await store.save(updated);
+  await refreshUi(ctx, updated);
+  ctx.ui.notify(
+    `Saved ${artifact.title}. AHEAD mode remains active; continue the conversation or run /ahead for the next guided action.`,
+    "info",
+  );
+}
+
+function requestAiAssistance(pi: ExtensionAPI, state: RunState, requiredKind?: string): void {
+  const guidance = phaseGuide(state.phase.id);
+  const artifact = requiredKind
+    ? state.artifacts.find((candidate) => candidate.kind === requiredKind)
+    : undefined;
+  const request = artifact
+    ? [
+        `AHEAD mode: perform the ${artifact.required ? "required" : "recommended"} ${state.phase.title} work for the exact current evidence and changeset.`,
+        `Produce ${artifact.title}.`,
+        `Follow the active human/AI boundary: ${guidance.ai}`,
+        `Use ahead_get_context first, then record the completed artifact as ${artifact.kind} with ahead_record_artifact.`,
+        "Treat findings as hypotheses for human disposition. Do not accept the gate or transition the run.",
+      ].join("\n")
+    : [
+        `AHEAD mode: assist with the active ${state.phase.title} phase.`,
+        guidance.ai,
+        "Use ahead_get_context before acting. Stay within the allowed capabilities and never author a human-owned artifact or decision.",
+        "Explain what you found and what the human must understand or decide next.",
+      ].join("\n");
+  pi.sendUserMessage(request);
+}
+
+async function acceptAndContinue(ctx: ExtensionCommandContext): Promise<void> {
+  if (!ctx.hasUI) throw new Error("Accepting an AHEAD gate requires interactive or RPC UI support");
+  const engine = await enginePromise;
+  const store = storeFor(ctx);
+  const run = await requireRun(ctx);
+  let state = engine.deriveState(run);
+  const missing = state.artifacts.filter((artifact) => artifact.required && !artifact.present);
+  if (missing.length > 0) {
+    throw new AheadEngineError(
+      "required_artifact_missing",
+      `complete first: ${missing.map((artifact) => artifact.title).join(", ")}`,
+    );
+  }
+
+  const destination = state.phase.next
+    ? engine.getWorkflow(run.workflow_id).phases.find((phase) => phase.id === state.phase.next)?.title ?? state.phase.next
+    : "close this AHEAD run";
+  const confirmed = await ctx.ui.confirm(
+    `Accept and continue from ${state.phase.title}?`,
+    [
+      state.gate.title,
+      "",
+      `Next: ${destination}`,
+      `Accountable human: ${humanActor(store.projectRoot).identity}`,
+      "",
+      "This records human acceptance. AI cannot perform this action.",
+    ].join("\n"),
+  );
+  if (!confirmed) return;
+
+  const actor = humanActor(store.projectRoot);
+  let updated = run;
+  if (!state.gate.accepted) {
+    updated = engine.applyEvent(updated, actor, {
+      type: "gate_accepted",
+      phase: state.phase.id,
+      gate: state.gate.id,
+    });
+    state = engine.deriveState(updated);
+  }
+  if (!state.can_advance) {
+    throw new AheadEngineError("cannot_advance", state.blockers.join("; ") || "the phase cannot advance");
+  }
+
+  const action: EventAction = state.phase.next
+    ? {
+        type: "phase_transitioned",
+        from: state.phase.id,
+        to: state.phase.next,
+        direction: "advance",
+      }
+    : { type: "run_closed", phase: state.phase.id };
+  updated = engine.applyEvent(updated, actor, action);
+  await store.save(updated);
+  await refreshUi(ctx, updated);
+
+  const nextState = engine.deriveState(updated);
+  if (nextState.closed) {
+    ctx.ui.notify("AHEAD work complete. The accountable human accepted the outcome and closed the run.", "info");
+  } else if (nextState.phase.id === "human-review") {
+    ctx.ui.notify(
+      [
+        "READY FOR INDEPENDENT HUMAN REVIEW",
+        "The AI review is recorded and its material findings were disposed by a human.",
+        "A draft branch may already exist, but a human must now request review or mark the PR ready.",
+        "The independent reviewer opens this repository, runs /ahead, and records the review.",
+      ].join("\n"),
+      "info",
+    );
+  } else {
+    ctx.ui.notify(
+      `Continued to ${nextState.phase.title}. AHEAD mode remains active; run /ahead for the next guided action.`,
+      "info",
+    );
+  }
+}
+
+async function returnToEarlierPhase(ctx: ExtensionCommandContext, requestedTarget: string): Promise<void> {
+  if (!ctx.hasUI) throw new Error("Returning an AHEAD phase requires interactive or RPC UI support");
+  const engine = await enginePromise;
+  const store = storeFor(ctx);
+  const run = await requireRun(ctx);
+  const state = engine.deriveState(run);
+  if (!state.return_targets.length) {
+    throw new AheadEngineError("no_return_target", `phase ${state.phase.id} has no return transition`);
+  }
+  const workflow = engine.getWorkflow(run.workflow_id);
+  const targetOptions = state.return_targets.map((target) => ({
+    id: target,
+    title: workflow.phases.find((phase) => phase.id === target)?.title ?? target,
+  }));
+  let target = requestedTarget.trim();
+  if (!target) {
+    const selected = await ctx.ui.select(
+      "Return to which phase?",
+      targetOptions.map((candidate) => candidate.title),
+    );
+    target = targetOptions.find((candidate) => candidate.title === selected)?.id ?? "";
+  }
+  if (!state.return_targets.includes(target)) {
+    throw new AheadEngineError(
+      "invalid_return",
+      `phase ${state.phase.id} can return only to: ${state.return_targets.join(", ")}`,
+    );
+  }
+  const reason = await ctx.ui.editor(
+    `Why return to ${workflow.phases.find((phase) => phase.id === target)?.title ?? target}?`,
+  );
+  if (!reason?.trim()) return;
+  const confirmed = await ctx.ui.confirm(
+    `Return to ${target}?`,
+    "This opens a new phase visit. Earlier artifacts remain as history but cannot satisfy the reopened gate.",
+  );
+  if (!confirmed) return;
+  const updated = engine.applyEvent(run, humanActor(store.projectRoot), {
+    type: "phase_transitioned",
+    from: state.phase.id,
+    to: target,
+    direction: "return",
+    reason: reason.trim(),
+  });
+  await store.save(updated);
+  await refreshUi(ctx, updated);
+  ctx.ui.notify(`Returned to ${target}. AHEAD mode remains active with fresh evidence and gate requirements.`, "warning");
+}
+
 function storeFor(ctx: ExtensionContext): RunStore {
   return new RunStore(projectRoot(ctx.cwd));
 }
 
 async function requireRun(ctx: ExtensionContext): Promise<Run> {
   const run = await storeFor(ctx).loadCurrent();
-  if (!run) throw new AheadEngineError("no_active_run", "no active AHEAD run; use /ahead-start [title]");
+  if (!run) throw new AheadEngineError("no_active_run", "no active AHEAD run; use /ahead [title]");
   return run;
 }
 
@@ -378,26 +799,20 @@ async function refreshUi(ctx: ExtensionContext, supplied?: Run): Promise<void> {
     ctx.ui.setWidget("ahead", undefined);
     return;
   }
-  const state = (await enginePromise).deriveState(run);
+  const engine = await enginePromise;
+  const state = engine.deriveState(run);
+  const workflow = engine.getWorkflow(run.workflow_id);
+  const position = phasePosition(state, workflow);
+  const action = nextAction(state, workflow);
   ctx.ui.setStatus(
     "ahead",
     state.closed
-      ? `AHEAD · ${state.workflow_id} · closed`
-      : `AHEAD · ${state.phase.id}#${state.phase.visit} · ${state.blockers.length} blocker${state.blockers.length === 1 ? "" : "s"}`,
+      ? `AHEAD · complete · ${state.workflow_id}`
+      : `AHEAD · ${position.current}/${position.total} · ${state.phase.id} · ${action.actor} action`,
   );
   ctx.ui.setWidget(
     "ahead",
-    [
-      `AHEAD · ${run.title}`,
-      state.closed
-        ? "Closed"
-        : `${state.phase.title} · visit ${state.phase.visit} · gate ${state.gate.accepted ? "accepted" : "open"}`,
-      state.blockers.length
-        ? `Next: ${state.blockers[0]}`
-        : state.phase.next
-          ? "Next: /ahead-advance"
-          : "Next: /ahead-advance (closes run)",
-    ],
+    buildWidgetLines(run, state, workflow),
     { placement: "aboveEditor" },
   );
 }
@@ -426,19 +841,6 @@ function formatState(state: RunState): string {
   ].join("\n");
 }
 
-function artifactTemplate(run: Run, state: RunState, kind: string, title: string): string {
-  return [
-    `# ${title}`,
-    "",
-    `AHEAD run: ${run.id}`,
-    `Phase: ${state.phase.id} (visit ${state.phase.visit})`,
-    `Artifact: ${kind}`,
-    "",
-    "<!-- Replace this comment with the human-authored record. Preserve evidence, uncertainty, and rationale. -->",
-    "",
-  ].join("\n");
-}
-
 async function command(ctx: ExtensionCommandContext, action: () => Promise<void>): Promise<void> {
   try {
     await action();