ahead-pi 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ahead-pi",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "AHEAD workflow enforcement and context for Pi",
   "keywords": [
     "ahead",
@@ -45,6 +45,9 @@
     "verify": "npm run build && npm run format:check && npm run lint && node --test ./test/*.test.mjs",
     "test": "npm run verify && npm run pack:verify"
   },
+  "dependencies": {
+    "@earendil-works/pi-ai": "^0.84.4"
+  },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.1",
     "@earendil-works/pi-tui": "^0.84.1",

package/src/examples.ts

@@ -0,0 +1,127 @@
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+export interface FieldExamplesInput {
+  workflowTitle: string;
+  phaseTitle: string;
+  runTitle: string;
+  fields: string[];
+}
+
+const EXAMPLES_TIMEOUT_MS = 25_000;
+
+/**
+ * Draft two inspiration-only example lines per artifact field.
+ *
+ * The model is called without repository context on purpose: the examples are
+ * creative sparks to react to, not guidance the human should trust. They are
+ * rendered as HTML comments inside the field so form validation still treats
+ * an untouched field as empty.
+ */
+export async function draftFieldExamples(
+  ctx: ExtensionCommandContext,
+  input: FieldExamplesInput,
+): Promise<string[][] | undefined> {
+  const model = ctx.model;
+  if (!model) {
+    return undefined;
+  }
+
+  const prompt = [
+    "You are helping a human begin a short written artifact in a software workflow.",
+    `Run title: ${input.runTitle}`,
+    `Workflow: ${input.workflowTitle} · Phase: ${input.phaseTitle}`,
+    "",
+    "You have NO access to the codebase or real project details. For each numbered field, write exactly 2 short example answers that are creative sparks only — plausibly generic and concrete, never claimed as fact about this project. Keep each line under 15 words.",
+    "",
+    "Output format, nothing else:",
+    "1: <example line>",
+    "1: <example line>",
+    "2: <example line>",
+    "2: <example line>",
+    "...one pair per field, in order.",
+    "",
+    "Fields:",
+    ...input.fields.map((field, index) => `${index + 1}. ${field}`),
+  ].join("\n");
+
+  try {
+    const auth = await ctx.modelRegistry.getProviderAuth(model.provider);
+    if (!auth) {
+      return undefined;
+    }
+    const message = await Promise.race([
+      completeSimple(
+        model,
+        {
+          messages: [
+            {
+              role: "user",
+              content: [{ type: "text", text: prompt }],
+              timestamp: Date.now(),
+            },
+          ],
+        },
+        {
+          apiKey: auth.auth.apiKey,
+          headers: auth.auth.headers,
+          env: auth.env,
+          reasoning: "minimal",
+        },
+      ),
+      new Promise<undefined>((resolve) => {
+        setTimeout(() => resolve(undefined), EXAMPLES_TIMEOUT_MS);
+      }),
+    ]);
+    if (!message) {
+      return undefined;
+    }
+    return parseExampleLines(message, input.fields.length);
+  } catch {
+    return undefined;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function textBlocks(content: unknown): string[] {
+  if (!Array.isArray(content)) {
+    return [];
+  }
+  const blocks: string[] = [];
+  for (const block of content) {
+    if (isRecord(block) && block.type === "text" && typeof block.text === "string") {
+      blocks.push(block.text);
+    }
+  }
+  return blocks;
+}
+
+function parseExampleLines(message: unknown, fieldCount: number): string[][] | undefined {
+  const text = textBlocks(isRecord(message) ? message.content : undefined).join("\n");
+
+  const perField: string[][] = Array.from({ length: fieldCount }, () => []);
+  for (const line of text.split("\n")) {
+    const match = /^\s*(\d+)\s*:\s*(.+)$/.exec(line);
+    if (!match) {
+      continue;
+    }
+    const fieldIndex = Number.parseInt(match[1] ?? "", 10) - 1;
+    const example = match[2]?.trim();
+    if (
+      Number.isInteger(fieldIndex) &&
+      fieldIndex >= 0 &&
+      fieldIndex < fieldCount &&
+      example &&
+      perField[fieldIndex].length < 2
+    ) {
+      perField[fieldIndex].push(example);
+    }
+  }
+  if (perField.every((examples) => examples.length === 0)) {
+    return undefined;
+  }
+  return perField;
+}

package/src/guidance.ts

@@ -491,7 +491,7 @@ export function buildHeaderLines(
       : undefined;
 
   return [
-    `AHEAD · ${workflow.title} · ${position.current}/${position.total} · ${state.phase.title}`,
+    `AHEAD · ${workflow.title} · ${state.phase.title}  (${position.current}/${position.total})`,
     ...(workItem ? [workItem] : []),
     `Goal: ${guide.objective}`,
     `Required: ${checklist}`,
@@ -511,14 +511,14 @@ export function buildArtifactTemplate(
     return [
       `### ${number}. ${prompt}`,
       `<!-- AHEAD-FIELD:${number}:BEGIN -->`,
-      "<!-- Required. Replace this comment with your response. Use “Not applicable — reason” only when justified. -->",
+      "",
       "",
       `<!-- AHEAD-FIELD:${number}:END -->`,
       "",
     ];
   });
   return [
-    `# ${title}`,
+    "# " + title,
     "",
     `AHEAD run: ${run.id}`,
     `Phase: ${state.phase.id} (visit ${state.phase.visit})`,
@@ -526,12 +526,38 @@ export function buildArtifactTemplate(
     "",
     "## Required responses",
     "",
-    "Complete every field in your own words. Preserve evidence, uncertainty, and rationale; form completion does not replace accountable judgment.",
+    "Write directly under each question, between the AHEAD-FIELD markers. Every field is required; use “Not applicable — reason” only when you can justify it.",
     "",
     ...fields,
   ].join("\n");
 }
 
+/**
+ * Insert inspiration-only example lines into each field as HTML comments.
+ * Validation strips comments, so an untouched field still counts as empty.
+ */
+export function insertFieldExamples(template: string, perField: string[][]): string {
+  let updated = template;
+  for (const [index, examples] of perField.entries()) {
+    if (!examples || examples.length === 0) {
+      continue;
+    }
+    const marker = `<!-- AHEAD-FIELD:${index + 1}:BEGIN -->`;
+    if (!updated.includes(marker)) {
+      continue;
+    }
+    updated = updated.replace(
+      marker,
+      [
+        marker,
+        "<!-- Examples — inspiration only, not requirements. Delete them and write your own answer. -->",
+        ...examples.map((example) => `<!-- ~ ${example} ~ -->`),
+      ].join("\n"),
+    );
+  }
+  return updated;
+}
+
 export function validateArtifactForm(content: string, prompts: string[]): string[] {
   const errors: string[] = [];
   for (const [index, prompt] of prompts.entries()) {

package/src/index.ts

@@ -14,12 +14,14 @@ import { AheadEngine, AheadEngineError } from "./engine.js";
 import {
   buildArtifactTemplate,
   buildHeaderLines,
+  insertFieldExamples,
   nextAction,
   phaseGuide,
   phasePosition,
   promptsForArtifact,
   validateArtifactForm,
 } from "./guidance.js";
+import { draftFieldExamples } from "./examples.js";
 import {
   findReference,
   loadReferenceIndex,
@@ -740,6 +742,35 @@ async function openAheadMode(
     });
   }
 
+  if (
+    state.allowed_ai_capabilities.length > 0 &&
+    state.artifacts.some(
+      (artifact) => artifact.present && artifact.recorded_by?.kind === "human" && artifact.path,
+    )
+  ) {
+    actions.push({
+      label: "Ask AI to challenge the latest artifact",
+      run: async () => {
+        const artifact = [...state.artifacts]
+          .toReversed()
+          .find(
+            (candidate) =>
+              candidate.present && candidate.recorded_by?.kind === "human" && candidate.path,
+          );
+        if (!artifact?.path) {
+          return;
+        }
+        pi.sendUserMessage(
+          [
+            `AHEAD mode: challenge my ${artifact.title} artifact before I accept the gate.`,
+            `Read ${artifact.path} and name the 2-3 weakest points: missing risks, vague claims, or things that would not survive implementation.`,
+            "Be specific and brief. Do not rewrite the artifact; I stay the author.",
+          ].join("\n"),
+        );
+      },
+    });
+  }
+
   if (state.return_targets.length > 0) {
     actions.push({
       label: "Return to an earlier phase",
@@ -757,33 +788,32 @@ async function openAheadMode(
   }
 
   actions.push({
-    label: "Configure project AHEAD policy for future runs",
-    run: async () => manageProjectConfig(ctx),
-  });
-
-  actions.push({
-    label: "Read AHEAD framework guidance for this phase",
-    run: async () => showAheadGuide(ctx, ""),
-  });
-
-  actions.push({
-    label: "Inspect optional skills reviewed for this phase",
-    run: async () => showRecommendedSkills(ctx),
-  });
-
-  actions.push({
-    label: "Explain this phase and its expectations",
+    label: "Help · policy, guidance, skills, phase explanation",
     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 helpChoice = await ctx.ui.select("Help · pick one", [
+        "Configure project AHEAD policy for future runs",
+        "Read AHEAD framework guidance for this phase",
+        "Inspect optional skills reviewed for this phase",
+        "Explain this phase and its expectations",
+      ]);
+      if (helpChoice === "Configure project AHEAD policy for future runs") {
+        await manageProjectConfig(ctx);
+      } else if (helpChoice === "Read AHEAD framework guidance for this phase") {
+        await showAheadGuide(ctx, "");
+      } else if (helpChoice === "Inspect optional skills reviewed for this phase") {
+        await showRecommendedSkills(ctx);
+      } else if (helpChoice === "Explain this phase and its expectations") {
+        ctx.ui.notify(
+          [
+            state.phase.title,
+            `Goal: ${guidance.objective}`,
+            `You: ${guidance.human}`,
+            `AI: ${guidance.ai}`,
+            `Gate: ${state.gate.title}`,
+          ].join("\n"),
+          "info",
+        );
+      }
     },
   });
 
@@ -1475,7 +1505,10 @@ async function startRun(ctx: ExtensionCommandContext, request: string): Promise<
     parsed.title ||
     linkedTitle ||
     (ctx.hasUI
-      ? await ctx.ui.input(`Enter AHEAD mode · ${workflow.title}`, "What work are you doing?")
+      ? await ctx.ui.input(
+          `AHEAD · ${workflow.title} · Name this work — e.g. ${titleExample(workflow.id)}`,
+          "",
+        )
       : parsed.workItemUrl);
   if (!title?.trim()) {
     return undefined;
@@ -1499,14 +1532,14 @@ async function startRun(ctx: ExtensionCommandContext, request: string): Promise<
   await store.save(run);
   await refreshUi(ctx, run);
   const state = engine.deriveState(run);
+  const requiredPhase = state.policy.work_items.required_before_phase;
   ctx.ui.notify(
     [
       `AHEAD mode started · ${workflow.title} · ${run.title}`,
-      "Human leads · AI assists",
       ...(state.work_item ? [`Work item: ${state.work_item.url}`] : []),
-      ...(state.policy.work_items.required_before_phase
+      ...(requiredPhase && !state.work_item
         ? [
-            `Project policy requires a work item before ${state.policy.work_items.required_before_phase}.`,
+            `Before the ${requiredPhase} phase, link a work item: /ahead, then choose “Link or create a work item”.`,
           ]
         : []),
       "This run remains active until an accountable human closes the outcome or uses /ahead-stop.",
@@ -1517,6 +1550,25 @@ async function startRun(ctx: ExtensionCommandContext, request: string): Promise<
   return run;
 }
 
+function titleExample(workflowId: string): string {
+  switch (workflowId) {
+    case "product-change":
+      return "“Add audit log viewer page”";
+    case "internal-improvement":
+      return "“Reduce cola-api cold-start time”";
+    case "corrective-debugging":
+      return "“Fix race in worker claim loop”";
+    case "operational-stabilization":
+      return "“Restore queue throughput after incident”";
+    case "decision":
+      return "“Choose audit-log retention policy”";
+    case "investigation":
+      return "“Why are runs flaking on CI?”";
+    default:
+      return "“Improve X”";
+  }
+}
+
 async function recordHumanArtifact(
   ctx: ExtensionCommandContext,
   requestedKind: string,
@@ -1548,8 +1600,20 @@ async function recordHumanArtifact(
     );
   }
 
-  const template = await humanArtifactTemplate(store, state, run, artifact.kind, artifact.title);
-  const content = await ctx.ui.editor(
+  const prompts = promptsForArtifact(state.workflow_id, state.phase.id, artifact.kind);
+  let template = await humanArtifactTemplate(store, state, run, artifact.kind, artifact.title);
+  if (ctx.hasUI && artifact.kind !== "review-disposition" && prompts.length > 0) {
+    const examples = await draftFieldExamples(ctx, {
+      workflowTitle: engine.getWorkflow(state.workflow_id).title,
+      phaseTitle: state.phase.title,
+      runTitle: run.title,
+      fields: prompts,
+    });
+    if (examples) {
+      template = insertFieldExamples(template, examples);
+    }
+  }
+  let content = await ctx.ui.editor(
     `AHEAD mode · ${artifact.title} · write in your own words`,
     template,
   );
@@ -1557,17 +1621,36 @@ async function recordHumanArtifact(
     return;
   }
   if (artifact.kind !== "review-disposition") {
-    const formErrors = validateArtifactForm(
-      content,
-      promptsForArtifact(state.workflow_id, state.phase.id, artifact.kind),
-    );
-    if (formErrors.length > 0) {
-      throw new AheadEngineError(
-        "artifact_form_incomplete",
-        `complete these required fields before saving ${artifact.title}:\n${formErrors
-          .map((error) => `- ${error}`)
-          .join("\n")}`,
+    // Keep the form open until validation passes or the human explicitly cancels,
+    // so partial input is never discarded by a validation failure.
+    while (true) {
+      const formErrors = validateArtifactForm(content, prompts);
+      if (formErrors.length === 0) {
+        break;
+      }
+      const retry = await ctx.ui.confirm(
+        "Some required fields are still empty",
+        [
+          `The following fields in ${artifact.title} need a response:`,
+          "",
+          ...formErrors.map((error) => `- ${error}`),
+          "",
+          "Your text is preserved. Reopen to finish, or discard?",
+        ].join("\n"),
+      );
+      if (!retry) {
+        ctx.ui.notify("Draft discarded. Nothing was saved.", "info");
+        return;
+      }
+      const revised = await ctx.ui.editor(
+        `AHEAD mode · ${artifact.title} · finish the required fields`,
+        content,
       );
+      if (!revised?.trim()) {
+        ctx.ui.notify("Draft kept in this dialog only — nothing was saved.", "info");
+        return;
+      }
+      content = revised;
     }
   }
   await validateHumanReviewArtifact(store, state, artifact.kind, content);
@@ -1582,8 +1665,21 @@ async function recordHumanArtifact(
   await store.writeArtifact(path.absolute, content);
   await store.save(updated);
   await refreshUi(ctx, updated);
+  const nextState = engine.deriveState(updated);
+  const nextArtifact = nextState.artifacts.find(
+    (candidate) => candidate.required && !candidate.present,
+  );
+  const nextStep = nextState.gate.accepted
+    ? nextState.gate.title
+    : nextArtifact
+      ? `Next artifact: ${nextArtifact.title}`
+      : `Accept the gate when ready: ${nextState.gate.title}`;
   ctx.ui.notify(
-    `Saved ${artifact.title}. AHEAD mode remains active; continue the conversation.`,
+    [
+      `✓ Saved ${artifact.title}.`,
+      `Next: ${nextStep}`,
+      "/ahead is available for the action menu; or just tell me what to do next.",
+    ].join("\n"),
     "info",
   );
 }
@@ -1887,7 +1983,7 @@ async function refreshUi(ctx: ExtensionContext, supplied?: Run): Promise<void> {
     "ahead",
     state.closed
       ? `AHEAD · complete · ${state.workflow_id}`
-      : `AHEAD · ${position.current}/${position.total} · ${state.phase.id} · ${action.actor} action`,
+      : `AHEAD · ${state.phase.id} · ${action.actor} action  (${position.current}/${position.total})`,
   );
   if (state.closed) {
     ctx.ui.setWidget("ahead", undefined);
@@ -2052,8 +2148,8 @@ async function toolResult(action: () => Promise<unknown>) {
 }
 
 function errorMessage(error: unknown): string {
-  if (error instanceof AheadEngineError) {
-    return `${error.code}: ${error.message}`;
-  }
+  // User-facing messages should read as prose. The internal error code is
+  // available on AheadEngineError.code for tooling, but does not belong in
+  // the user-visible text.
   return error instanceof Error ? error.message : String(error);
 }

package/src/storage.ts

@@ -44,17 +44,54 @@ export class RunStore {
     this.aheadDirectory = join(rootPath, ".ahead");
   }
 
-  newRunId(): string {
-    const date = new Date().toISOString().slice(0, 10).replaceAll("-", "");
-    return `${date}-${randomUUID().slice(0, 8)}`;
+  private get localDirectory(): string {
+    return join(this.aheadDirectory, "local");
   }
 
-  async loadCurrent(): Promise<Run | undefined> {
+  private get currentPath(): string {
+    return join(this.localDirectory, "current.json");
+  }
+
+  private get legacyCurrentPath(): string {
+    return join(this.aheadDirectory, "current.json");
+  }
+
+  private async ensureLocalDirectory(): Promise<void> {
+    await mkdir(this.localDirectory, { recursive: true });
+    const gitignorePath = join(this.localDirectory, ".gitignore");
     try {
-      const pointer = parseCurrentRunPointer(
-        await readFile(join(this.aheadDirectory, "current.json"), "utf8"),
-      );
-      return this.load(pointer.run_id);
+      await writeFile(gitignorePath, "*\n!.gitignore\n", { encoding: "utf8", flag: "wx" });
+    } catch (error) {
+      if (!isExists(error)) {
+        throw error;
+      }
+    }
+  }
+
+  private async writeCurrentPointer(pointer: CurrentRunPointer): Promise<void> {
+    await this.ensureLocalDirectory();
+    await atomicJson(this.currentPath, pointer);
+    // Cleanup legacy pointer at the old shared path, if present.
+    try {
+      await unlink(this.legacyCurrentPath);
+    } catch (error) {
+      if (!isMissing(error)) {
+        throw error;
+      }
+    }
+  }
+
+  private async readCurrentPointer(): Promise<string | undefined> {
+    try {
+      return await readFile(this.currentPath, "utf8");
+    } catch (error) {
+      if (!isMissing(error)) {
+        throw error;
+      }
+    }
+    // Legacy fallback: read from the pre-0.7.0 shared path if the local path is absent.
+    try {
+      return await readFile(this.legacyCurrentPath, "utf8");
     } catch (error) {
       if (isMissing(error)) {
         return undefined;
@@ -63,6 +100,20 @@ export class RunStore {
     }
   }
 
+  newRunId(): string {
+    const date = new Date().toISOString().slice(0, 10).replaceAll("-", "");
+    return `${date}-${randomUUID().slice(0, 8)}`;
+  }
+
+  async loadCurrent(): Promise<Run | undefined> {
+    const content = await this.readCurrentPointer();
+    if (content === undefined) {
+      return undefined;
+    }
+    const pointer = parseCurrentRunPointer(content);
+    return this.load(pointer.run_id);
+  }
+
   async load(runId: string): Promise<Run> {
     return parseRun(await readFile(this.runPath(runId), "utf8"));
   }
@@ -139,7 +190,7 @@ export class RunStore {
     await atomicJson(this.runPath(run.id), run);
     if (makeCurrent) {
       const pointer: CurrentRunPointer = { api_version: "ahead.current/v0", run_id: run.id };
-      await atomicJson(join(this.aheadDirectory, "current.json"), pointer);
+      await this.writeCurrentPointer(pointer);
     }
   }
 
@@ -166,7 +217,7 @@ export class RunStore {
   async resume(runId: string): Promise<Run> {
     const run = await this.load(runId);
     const pointer: CurrentRunPointer = { api_version: "ahead.current/v0", run_id: runId };
-    await atomicJson(join(this.aheadDirectory, "current.json"), pointer);
+    await this.writeCurrentPointer(pointer);
     return run;
   }
 
@@ -219,25 +270,31 @@ export class RunStore {
   }
 
   private async clearCurrent(expectedRunId: string): Promise<void> {
-    const path = join(this.aheadDirectory, "current.json");
-    let pointer: CurrentRunPointer;
-    try {
-      pointer = parseCurrentRunPointer(await readFile(path, "utf8"));
-    } catch (error) {
-      if (isMissing(error)) {
-        return;
+    // Clear the current pointer wherever it lives (new local path and legacy shared path).
+    for (const path of [this.currentPath, this.legacyCurrentPath]) {
+      let pointer: CurrentRunPointer;
+      try {
+        pointer = parseCurrentRunPointer(await readFile(path, "utf8"));
+      } catch (error) {
+        if (isMissing(error)) {
+          continue;
+        }
+        throw error;
       }
-      throw error;
-    }
-    if (pointer.run_id !== expectedRunId) {
-      throw new Error(
-        `active AHEAD run changed from ${expectedRunId} to ${pointer.run_id}; stop or resume again`,
-      );
+      if (pointer.run_id !== expectedRunId) {
+        throw new Error(
+          `active AHEAD run changed from ${expectedRunId} to ${pointer.run_id}; stop or resume again`,
+        );
+      }
+      await unlink(path);
     }
-    await unlink(path);
   }
 }
 
+function isExists(error: unknown): boolean {
+  return !!error && typeof error === "object" && "code" in error && error.code === "EEXIST";
+}
+
 export function humanActor(cwd: string): Actor {
   const explicit = process.env.AHEAD_HUMAN_IDENTITY?.trim();
   if (explicit) {