ahead-pi 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ahead-pi",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "AHEAD workflow enforcement and context for Pi",
   "keywords": [
     "ahead",

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,7 +526,7 @@ 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");

package/src/index.ts

@@ -757,33 +757,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 +1474,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(
+          `Enter AHEAD mode · ${workflow.title}`,
+          `Short name for this work — e.g. ${titleExample(workflow.id)}`,
+        )
       : parsed.workItemUrl);
   if (!title?.trim()) {
     return undefined;
@@ -1499,14 +1501,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 +1519,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,
@@ -1549,7 +1570,7 @@ async function recordHumanArtifact(
   }
 
   const template = await humanArtifactTemplate(store, state, run, artifact.kind, artifact.title);
-  const content = await ctx.ui.editor(
+  let content = await ctx.ui.editor(
     `AHEAD mode · ${artifact.title} · write in your own words`,
     template,
   );
@@ -1557,17 +1578,39 @@ 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,
+        promptsForArtifact(state.workflow_id, state.phase.id, artifact.kind),
+      );
+      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 +1625,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 +1943,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 +2108,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) {