ahead-pi 0.1.1 → 0.2.0

package/README.md

@@ -1,14 +1,14 @@
 # AHEAD for Pi
 
-Status: dogfood v0.1
+Status: guided-mode dogfood v0.2
 
-The Pi integration runs the Rust AHEAD state machine as WebAssembly, injects generated phase instructions into any Pi model, persists the event/evidence chain, and exposes human gates through explicit slash commands.
+The Pi integration runs the Rust AHEAD state machine as WebAssembly, injects generated phase instructions into any Pi model, persists the event/evidence chain, and presents AHEAD as a guided mode with human-owned gates.
 
 It does not own model authentication. Use whichever provider Pi already supports and your organization permits, including an existing GitHub Copilot configuration. AHEAD never receives the model credential.
 
 ## Install from npm
 
-After the first public release, install the current version globally in Pi:
+Install the current version globally in Pi:
 
 ```sh
 pi install npm:ahead-pi
@@ -17,7 +17,7 @@ pi install npm:ahead-pi
 Pin an exact version for a team or project:
 
 ```sh
-pi install -l npm:ahead-pi@0.1.0
+pi install -l npm:ahead-pi@0.2.0
 ```
 
 Or try it for one session without changing settings:
@@ -51,31 +51,41 @@ pi
 
 Pi may ask you to trust the project-local extension. Review it before accepting; project trust is not a sandbox.
 
-## Dogfood loop
+## Guided mode
 
 1. Start Pi in the repository where the engineering work will occur.
-2. Run `/ahead-start <short title>`.
-3. Run `/ahead-status` to see the active phase contract.
-4. Use `/ahead-record [kind]` for human-owned artifacts.
-5. Ask the model for only the assistance allowed in the active phase. It can call `ahead_get_context` and, where allowed, `ahead_record_artifact`.
-6. Run `/ahead-accept` only after examining the evidence and owning the gate decision.
-7. Run `/ahead-advance`, or `/ahead-return [phase]` with a reason when the work must reopen.
-8. Commit appropriate `.ahead` records with the work so review and later adapters can validate them.
+2. Run `/ahead <short title>` once to enter AHEAD mode and start a Product Change run.
+3. Work through normal conversation. The persistent widget shows the current goal, what the human owns, what AI may do, required evidence, and the next valid action.
+4. Run `/ahead` again whenever you want the contextual action menu. It opens the right guided editor, requests the right AI contribution, accepts and advances a human gate, or returns to an earlier phase.
+5. Keep the `.ahead` records with the work so another session or independent reviewer resumes the same authoritative run.
+
+AHEAD remains active across Pi sessions until an accountable human completes the outcome phase and closes the run. Restarting Pi does not leave the mode or reset the workflow.
+
+The normal implementation handoff is:
+
+```text
+HUMAN IMPLEMENTS AND SELF-CHECKS
+              ↓
+AI REVIEWS THE EXACT CURRENT CHANGESET
+              ↓
+HUMAN DISPOSES MATERIAL AI FINDINGS
+              ↓
+READY FOR INDEPENDENT HUMAN REVIEW
+              ↓
+INDEPENDENT HUMAN REVIEWS AND ACCEPTS
+```
 
-The footer and editor widget show the current phase, visit, gate, and first blocker.
+A draft branch or draft PR may exist earlier. The handoff gate is requesting human review or marking the PR ready, not ordinary draft pushes.
 
 ## Human commands
 
 | Command | Effect |
 |---|---|
-| `/ahead-start [title]` | Human starts and owns a Product Change run |
-| `/ahead-status` | Show phase, artifacts, capabilities, gate, and blockers |
-| `/ahead-record [kind]` | Human writes and records a permitted artifact |
-| `/ahead-accept` | Human accepts the current gate after required evidence exists |
-| `/ahead-advance` | Human advances, or closes the accepted final phase |
-| `/ahead-return [phase]` | Human reopens an allowed earlier phase with a reason |
+| `/ahead [title]` | Enter, resume, or perform the next guided AHEAD action |
 | `/ahead-help` | Show commands and authority boundaries |
 
+`/ahead-start`, `/ahead-status`, `/ahead-record`, `/ahead-accept`, `/ahead-advance`, and `/ahead-return` remain available as advanced recovery and inspection commands. Normal use should not require memorizing them.
+
 ## AI tools
 
 - `ahead_get_context` reads authoritative state.
@@ -101,11 +111,11 @@ Human identity is resolved from `AHEAD_HUMAN_IDENTITY`, Git `user.email`, Git `u
 AHEAD_HUMAN_IDENTITY=reviewer@example.com pi -e ./integrations/pi/src/index.ts
 ```
 
-This is local self-attestation, not cryptographic identity. The initial version is single-writer, implements only Product Change, and has no GitHub/CI workflow enforcement yet. See [Executable AHEAD workflows](https://github.com/Kade-Powell/ahead/blob/main/docs/design/executable-workflows.md) for the architecture and trust boundaries.
+This is local self-attestation, not cryptographic identity. The initial version is single-writer, implements only Product Change, and has no GitHub/CI workflow enforcement yet. Review records ask for the exact commit or diff, but v0.2 does not yet cryptographically bind that changeset to the review; a changed changeset must be returned and reviewed again by the humans involved. See [Executable AHEAD workflows](https://github.com/Kade-Powell/ahead/blob/main/docs/design/executable-workflows.md) for the architecture and trust boundaries.
 
 ## Package and release verification
 
-`npm test` builds the Rust core for `wasm32-unknown-unknown`, regenerates instructions, runs Rust/WASM-facing tests, creates the exact npm tarball, verifies its allowlisted contents, loads the extracted package through the real Pi binary, and confirms that `/ahead-start` persists a valid run.
+`npm test` builds the Rust core for `wasm32-unknown-unknown`, regenerates instructions, runs Rust/WASM-facing and guided-mode tests, creates the exact npm tarball, verifies its allowlisted contents, loads the extracted package through the real Pi binary, and confirms that the packaged extension persists a valid run.
 
 The npm package contains only its README, package metadata, TypeScript runtime, generated phase instructions, and compiled WASM engine. Build scripts, tests, source specs, development dependencies, and repository files are excluded.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ahead-pi",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "AHEAD workflow enforcement and context for Pi",
   "license": "MIT",
   "type": "module",

package/src/guidance.ts

@@ -0,0 +1,358 @@
+import type { ArtifactState, Run, RunState, WorkflowDefinition } from "./types.js";
+
+export interface PhaseGuide {
+  objective: string;
+  human: string;
+  ai: string;
+  artifactPrompts: Record<string, string[]>;
+  handoff?: string;
+}
+
+const guides: Record<string, PhaseGuide> = {
+  define: {
+    objective: "Agree on the problem and the observable outcome before solution work begins.",
+    human: "Describe the users, current problem, desired outcome, scope, constraints, and success signals.",
+    ai: "Explain the prompts. After your first statement, clarify ambiguity and expose assumptions without redefining the problem.",
+    artifactPrompts: {
+      problem: [
+        "Who experiences the problem, and what happens today?",
+        "What outcome should change, for whom, and why now?",
+        "What is in scope, out of scope, or constrained?",
+        "What observable signals would demonstrate success or failure?",
+        "Which assumptions or uncertainties should remain visible?",
+      ],
+    },
+  },
+  research: {
+    objective: "Build enough evidence to understand the problem before choosing a solution.",
+    human: "Set the research boundary, judge source relevance, and identify what evidence is material.",
+    ai: "Inspect authorized sources, organize evidence, surface contradictions, and state confidence and gaps.",
+    artifactPrompts: {
+      research: [
+        "What sources, code, behavior, history, or measurements were examined?",
+        "What findings are supported, contradicted, or still uncertain?",
+        "How directly does each finding apply to this work?",
+        "What important evidence is still missing?",
+      ],
+    },
+  },
+  questions: {
+    objective: "Dispose the unknowns that could materially change the decision or plan.",
+    human: "Decide which unknowns must be answered and which uncertainty can be accepted explicitly.",
+    ai: "Challenge gaps, perform authorized follow-up research, and distinguish evidence from inference.",
+    artifactPrompts: {
+      unknowns: [
+        "Which questions could materially change the work?",
+        "What answer or evidence resolved each question?",
+        "Which unknowns remain, and why is proceeding still acceptable?",
+      ],
+      "question-research": [
+        "What follow-up question was investigated?",
+        "What evidence was found, and what remains uncertain?",
+      ],
+    },
+  },
+  options: {
+    objective: "Understand viable approaches and tradeoffs before committing to one.",
+    human: "Produce the first option, then evaluate alternatives and tradeoffs in the system's real context.",
+    ai: "After the human first pass, challenge assumptions and add materially different alternatives.",
+    artifactPrompts: {
+      "human-option": [
+        "What is your first workable approach?",
+        "Why might it fit the problem and constraints?",
+        "What risks, costs, and uncertainties do you already see?",
+      ],
+      "ai-challenge": [
+        "Which assumptions or failure modes does the first option overlook?",
+        "What materially different alternatives deserve consideration?",
+      ],
+      options: [
+        "Which options were considered?",
+        "What are their tradeoffs, failure modes, reversibility, and operational consequences?",
+        "Which options were rejected, and why?",
+      ],
+    },
+  },
+  decision: {
+    objective: "Make an accountable and explainable choice.",
+    human: "Choose the approach and own its rationale, tradeoffs, remaining uncertainty, and reversibility.",
+    ai: "Test the recorded decision for contradictions, weak evidence, and hidden consequences.",
+    artifactPrompts: {
+      decision: [
+        "What was decided?",
+        "Why does it best fit the evidence and constraints?",
+        "What tradeoffs and risks are accepted?",
+        "What remains unknown, and how reversible is the decision?",
+      ],
+    },
+  },
+  plan: {
+    objective: "Create an implementable plan with verification, rollout, and recovery.",
+    human: "Write the first-pass sequence and approve the final plan after challenges are resolved.",
+    ai: "After the human first pass, identify missing dependencies, tests, edge cases, rollout evidence, recovery, and decision points.",
+    artifactPrompts: {
+      "first-pass-plan": [
+        "What sequence of changes do you currently expect?",
+        "Which systems, boundaries, and dependencies are involved?",
+        "How will you test, release, observe, and recover?",
+      ],
+      "ai-plan-review": [
+        "What is missing, risky, ambiguous, or ordered incorrectly?",
+        "Which tests, edge cases, rollout checks, and recovery steps should be added?",
+      ],
+      plan: [
+        "What is the final ordered implementation sequence?",
+        "What tests and observable evidence are required?",
+        "How will rollout and recovery work?",
+        "Which deviations require returning to decision or plan?",
+      ],
+    },
+  },
+  implement: {
+    objective: "Produce a change the engineer understands and can defend.",
+    human: "Own the implementation, understand every lasting change, run the planned checks, and record deviations.",
+    ai: "Assist within the approved plan, explain changes, run authorized checks, and surface reasons to revisit earlier phases.",
+    artifactPrompts: {
+      changeset: [
+        "What exact commit, branch, pull request, or diff identifies the current change?",
+        "Can you explain the important behavior and design choices?",
+      ],
+      tests: [
+        "Which planned and additional checks ran?",
+        "What passed, failed, or was not run?",
+        "What evidence covers boundaries, failures, and regressions?",
+      ],
+      "plan-deviations": [
+        "Where did implementation differ from the approved plan?",
+        "Why was each deviation acceptable, or state explicitly that there were none?",
+      ],
+    },
+  },
+  "ai-review": {
+    objective: "Add an AI review of the exact current changeset before independent human review.",
+    human: "Validate and dispose every material finding. Return to implementation when a change is required.",
+    ai: "Review without modifying: correctness, security, tests, architecture, plan compliance, operations, and maintainability.",
+    artifactPrompts: {
+      "ai-review": [
+        "What exact commit or diff was reviewed?",
+        "What findings were identified, with evidence and severity?",
+        "What disposition is proposed for each finding?",
+        "What could not be assessed?",
+      ],
+    },
+  },
+  "human-review": {
+    objective: "Obtain independent final engineering judgment on the current change.",
+    human: "A reviewer other than the implementer examines the exact change and material evidence, then accepts or returns it.",
+    ai: "Retrieve evidence and answer targeted questions. It cannot approve the change or replace reviewer judgment.",
+    handoff: "READY FOR INDEPENDENT HUMAN REVIEW",
+    artifactPrompts: {
+      "human-review": [
+        "Who reviewed the change, and what exact commit or diff was reviewed?",
+        "What code, tests, evidence, risks, and operational consequences were examined?",
+        "Which findings must be addressed or explicitly accepted?",
+        "Does the reviewer understand and accept the current change?",
+      ],
+    },
+  },
+  deploy: {
+    objective: "Authorize and record deployment or explicitly establish that it is not applicable.",
+    human: "Own the release decision and production risk. Record the exact version, target, actor, time, authorization, and result.",
+    ai: "Analyze readiness evidence. It cannot authorize deployment or claim a version is live.",
+    artifactPrompts: {
+      deployment: [
+        "What exact version was released to which target?",
+        "Who authorized and performed it, and when?",
+        "What did the deployment system report?",
+        "If deployment is not applicable, why?",
+      ],
+    },
+  },
+  verify: {
+    objective: "Demonstrate the intended outcome using observed evidence, not just test or deployment status.",
+    human: "Select adequate checks and decide whether the original success signals are demonstrated.",
+    ai: "Suggest checks and analyze authorized observations while separating code, deployment, and observed behavior.",
+    artifactPrompts: {
+      verification: [
+        "What pre-change and post-change behavior was compared?",
+        "Which tests, deployment facts, runtime observations, and user-visible signals were checked?",
+        "Did the original success and failure signals occur?",
+        "What remains uncertain or needs continued observation?",
+      ],
+    },
+  },
+  "ai-audit": {
+    objective: "Compare the result with the original intent and expose weak evidence or divergence.",
+    human: "Review and dispose material audit findings; reopen work when the evidence demands it.",
+    ai: "Audit the full chain from problem through observed outcome without changing or approving the work.",
+    artifactPrompts: {
+      "ai-audit": [
+        "Where did the result diverge from the problem, decision, plan, or reviews?",
+        "Which claims have weak or missing evidence?",
+        "Which findings require follow-up or reopening?",
+      ],
+    },
+  },
+  outcome: {
+    objective: "Make the accountable outcome decision and preserve learning.",
+    human: "Accept, roll back, follow up, abandon, or reopen the work, including remaining uncertainty.",
+    ai: "Organize evidence and summarize learning. It cannot choose or accept the outcome.",
+    artifactPrompts: {
+      outcome: [
+        "What outcome decision is being made?",
+        "Which evidence supports it?",
+        "What uncertainty, debt, monitoring, or follow-up remains?",
+        "What should the team or AHEAD process learn from this run?",
+      ],
+    },
+  },
+};
+
+const fallbackGuide: PhaseGuide = {
+  objective: "Complete the active phase using the recorded workflow contract.",
+  human: "Own the phase decision, required evidence, and gate.",
+  ai: "Assist only within the capabilities and artifact ownership allowed by the active phase.",
+  artifactPrompts: {},
+};
+
+export function phaseGuide(phaseId: string): PhaseGuide {
+  return guides[phaseId] ?? fallbackGuide;
+}
+
+export function promptsForArtifact(phaseId: string, kind: string): string[] {
+  return phaseGuide(phaseId).artifactPrompts[kind] ?? [
+    "What must another engineer understand from this record?",
+    "What evidence, uncertainty, and rationale should remain durable?",
+  ];
+}
+
+export function phasePosition(state: RunState, workflow: WorkflowDefinition): { current: number; total: number } {
+  const index = workflow.phases.findIndex((phase) => phase.id === state.phase.id);
+  return { current: index < 0 ? 0 : index + 1, total: workflow.phases.length };
+}
+
+export interface GuidedNextAction {
+  actor: "human" | "ai";
+  label: string;
+  artifactKind?: string;
+  optional?: boolean;
+}
+
+export function nextAction(state: RunState, workflow: WorkflowDefinition): GuidedNextAction {
+  if (state.closed) return { actor: "human", label: "Work complete; start another run only for new work" };
+
+  const orderedAssist = optionalAssistBeforeFinalHumanRecord(state);
+  if (orderedAssist) return orderedAssist;
+
+  const artifact = state.artifacts.find((candidate) => candidate.required && !candidate.present);
+  if (artifact) {
+    const actor = artifact.actor === "human"
+      ? "human"
+      : artifact.actor === "ai" || state.phase.id === "research"
+        ? "ai"
+        : "human";
+    if (actor === "human") {
+      const label = state.phase.id === "human-review"
+        ? "Independent reviewer records the current human review"
+        : `Write ${artifact.title}`;
+      return { actor, label, artifactKind: artifact.kind };
+    }
+
+    const label = state.phase.id === "ai-review"
+      ? "Run AI review of the exact current changeset"
+      : state.phase.id === "ai-audit"
+        ? "Run AI audit across intent, evidence, and outcome"
+        : `Ask AI to produce ${artifact.title}`;
+    return { actor, label, artifactKind: artifact.kind };
+  }
+
+  if (!state.gate.accepted) return { actor: "human", label: `Review evidence and accept: ${state.gate.title}` };
+
+  const nextPhase = workflow.phases.find((phase) => phase.id === state.phase.next);
+  return {
+    actor: "human",
+    label: nextPhase ? `Continue to ${nextPhase.title}` : "Accept the outcome and close this AHEAD run",
+  };
+}
+
+function optionalAssistBeforeFinalHumanRecord(state: RunState): GuidedNextAction | undefined {
+  const orderedAssist = state.phase.id === "options"
+    ? { prerequisite: "human-option", assist: "ai-challenge", final: "options" }
+    : state.phase.id === "plan"
+      ? { prerequisite: "first-pass-plan", assist: "ai-plan-review", final: "plan" }
+      : undefined;
+  if (!orderedAssist) return undefined;
+
+  const prerequisite = state.artifacts.find((artifact) => artifact.kind === orderedAssist.prerequisite);
+  const assist = state.artifacts.find((artifact) => artifact.kind === orderedAssist.assist);
+  const final = state.artifacts.find((artifact) => artifact.kind === orderedAssist.final);
+  if (!prerequisite?.present || assist?.present || final?.present) return undefined;
+
+  return {
+    actor: "ai",
+    artifactKind: assist?.kind,
+    label: state.phase.id === "options"
+      ? "Ask AI to challenge the human option and expand alternatives"
+      : "Ask AI to challenge the human first-pass plan",
+    optional: true,
+  };
+}
+
+export function buildWidgetLines(run: Run, state: RunState, workflow: WorkflowDefinition): string[] {
+  if (state.closed) {
+    return [
+      `AHEAD COMPLETE · ${run.title}`,
+      "The accountable human accepted the outcome and closed this run.",
+      "Run /ahead only when new work needs a new workflow.",
+    ];
+  }
+
+  const guide = phaseGuide(state.phase.id);
+  const position = phasePosition(state, workflow);
+  const required = state.artifacts.filter((artifact) => artifact.required);
+  const checklist = required.length
+    ? required.map(formatArtifactStatus).join(" · ")
+    : "No required artifact";
+  const action = nextAction(state, workflow);
+
+  return [
+    `AHEAD MODE · ${workflow.title.toUpperCase()} · ${position.current}/${position.total}`,
+    `${guide.handoff ?? state.phase.title.toUpperCase()} · HUMAN LEADS · AI ASSISTS`,
+    `Goal: ${guide.objective}`,
+    `You: ${guide.human}`,
+    `AI: ${guide.ai}`,
+    `Required: ${checklist}`,
+    `Next (${action.actor === "human" ? "you" : "AI"}): ${action.label}`,
+    "Run /ahead for the guided action.",
+  ];
+}
+
+export function buildArtifactTemplate(
+  run: Run,
+  state: RunState,
+  kind: string,
+  title: string,
+): string {
+  const prompts = promptsForArtifact(state.phase.id, kind);
+  return [
+    `# ${title}`,
+    "",
+    `AHEAD run: ${run.id}`,
+    `Phase: ${state.phase.id} (visit ${state.phase.visit})`,
+    `Artifact: ${kind}`,
+    "",
+    "## What to cover",
+    "",
+    ...prompts.map((prompt) => `- ${prompt}`),
+    "",
+    "## Record",
+    "",
+    "<!-- Write this human-owned record in your own words. Preserve evidence, uncertainty, and rationale. -->",
+    "",
+  ].join("\n");
+}
+
+function formatArtifactStatus(artifact: ArtifactState): string {
+  const owner = artifact.actor === "ai" ? "AI" : artifact.actor === "human" ? "you" : "you/AI";
+  return `${artifact.present ? "✓" : "○"} ${artifact.title} [${owner}]`;
+}

package/src/index.ts

@@ -7,6 +7,13 @@ 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 { humanActor, projectRoot, RunStore } from "./storage.js";
 import type { Actor, Capability, EventAction, Run, RunState } from "./types.js";
 
@@ -33,36 +40,22 @@ const RecordArtifactParams = Type.Object({
 });
 
 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-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 +65,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 +96,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 +125,25 @@ 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",
+          "",
+          "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",
       );
@@ -290,7 +215,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 +236,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 +253,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 +267,16 @@ 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.",
     ].join("\n");
     return { systemPrompt: `${event.systemPrompt}\n\n${phaseInstructions}\n\n${liveContext}\n` };
   });
@@ -337,6 +285,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 +302,357 @@ 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")
+  ) {
+    actions.push({
+      label: `Ask AI to assist · ${state.phase.title}`,
+      run: async () => requestAiAssistance(pi, state),
+    });
+  }
+
+  if (state.return_targets.length > 0) {
+    actions.push({
+      label: "Return to an earlier phase",
+      run: async () => returnToEarlierPhase(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 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 +671,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 +713,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();