ahead-pi 0.8.1 → 0.8.3

package/package.json

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

package/src/guidance.ts

@@ -533,8 +533,10 @@ export function buildArtifactTemplate(
 }
 
 /**
- * Insert inspiration-only example lines into each field as HTML comments.
- * Validation strips comments, so an untouched field still counts as empty.
+ * Insert inspiration-only example lines into each field as plain text with
+ * an "ex. - " prefix. Validation strips these lines for the emptiness
+ * check and rejects any saved form that still contains them, so no example
+ * line can ever persist in a recorded artifact.
  */
 export function insertFieldExamples(template: string, perField: string[][]): string {
   let updated = template;
@@ -548,16 +550,27 @@ export function insertFieldExamples(template: string, perField: string[][]): str
     }
     updated = updated.replace(
       marker,
-      [
-        marker,
-        "<!-- Examples — inspiration only, not requirements. Delete them and write your own answer. -->",
-        ...examples.map((example) => `<!-- ~ ${example} ~ -->`),
-      ].join("\n"),
+      [marker, ...examples.map((example) => `ex. - ${example}`)].join("\n"),
     );
   }
   return updated;
 }
 
+const EXAMPLE_LINE_PATTERN = /^\s*ex\.\s*-\s?/;
+
+function stripExampleLines(text: string): { cleaned: string; hadExamples: boolean } {
+  const kept: string[] = [];
+  let hadExamples = false;
+  for (const line of text.split("\n")) {
+    if (EXAMPLE_LINE_PATTERN.test(line)) {
+      hadExamples = true;
+      continue;
+    }
+    kept.push(line);
+  }
+  return { cleaned: kept.join("\n").trim(), hadExamples };
+}
+
 export function validateArtifactForm(content: string, prompts: string[]): string[] {
   const errors: string[] = [];
   for (const [index, prompt] of prompts.entries()) {
@@ -575,11 +588,18 @@ export function validateArtifactForm(content: string, prompts: string[]): string
       .slice(beginIndex + begin.length, endIndex)
       .replace(/<!--[\s\S]*?-->/g, "")
       .trim();
-    if (!response) {
-      errors.push(prompt);
+    const { cleaned, hadExamples } = stripExampleLines(response);
+    if (!cleaned) {
+      errors.push(
+        hadExamples ? `${prompt} (replace the “ex. -” example lines with your own answer)` : prompt,
+      );
+      continue;
+    }
+    if (hadExamples) {
+      errors.push(`${prompt} (remove the leftover “ex. -” example lines)`);
       continue;
     }
-    if (/^(?:n\/?a|not applicable)\s*[.!]?$/i.test(response)) {
+    if (/^(?:n\/?a|not applicable)\s*[.!]?$/i.test(cleaned)) {
       errors.push(`${prompt} (explain why it is not applicable)`);
     }
   }

package/src/index.ts

@@ -648,186 +648,200 @@ async function openAheadMode(
     run = await linkWorkItem(ctx, store, run, workItemFromUrl(args));
   }
 
-  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(run.workflow_id, state.phase.id);
-  const action = nextAction(state, workflow);
-  const actions: GuidedAction[] = [];
-  const missingRequired = state.artifacts.filter(
-    (artifact) => artifact.required && !artifact.present,
-  );
-  if (action.artifactKind) {
-    const actionArtifact = state.artifacts.find(
-      (artifact) => artifact.kind === action.artifactKind,
+  // Action-menu loop: the run is reloaded and the state re-derived after
+  // every action, then the menu reappears — help screens and completed
+  // actions never strand the user. Escaping the menu, or an action that
+  // clears the run, leaves the wizard.
+  while (true) {
+    const current = await store.loadCurrent();
+    if (!current) {
+      return;
+    }
+    run = current;
+    await refreshUi(ctx, run);
+    const state = engine.deriveState(run);
+    const workflow = engine.getWorkflow(run.workflow_id);
+    const guidance = phaseGuide(run.workflow_id, state.phase.id);
+    const action = nextAction(state, workflow);
+    const actions: GuidedAction[] = [];
+    const missingRequired = state.artifacts.filter(
+      (artifact) => artifact.required && !artifact.present,
     );
-    actions.push({
-      label: action.label,
-      run:
-        action.actor === "ai"
-          ? state.phase.id === "ai-review"
-            ? async () => openReviewWorkbench(pi, ctx)
-            : async () => requestAiAssistance(pi, state, action.artifactKind)
-          : async () => recordHumanArtifact(ctx, action.artifactKind ?? ""),
-    });
-    if (action.actor === "ai" && actionArtifact?.actor === "any") {
+    if (action.artifactKind) {
+      const actionArtifact = state.artifacts.find(
+        (artifact) => artifact.kind === action.artifactKind,
+      );
       actions.push({
-        label: `Write ${actionArtifact.title} yourself`,
-        run: async () => recordHumanArtifact(ctx, actionArtifact.kind),
+        label: action.label,
+        run:
+          action.actor === "ai"
+            ? state.phase.id === "ai-review"
+              ? async () => openReviewWorkbench(pi, ctx)
+              : async () => requestAiAssistance(pi, state, action.artifactKind)
+            : async () => recordHumanArtifact(ctx, action.artifactKind ?? ""),
       });
+      if (action.actor === "ai" && actionArtifact?.actor === "any") {
+        actions.push({
+          label: `Write ${actionArtifact.title} yourself`,
+          run: async () => recordHumanArtifact(ctx, actionArtifact.kind),
+        });
+      }
     }
-  }
 
-  if (action.optional) {
-    const nextHumanArtifact = missingRequired.find((artifact) => artifact.actor !== "ai");
-    if (nextHumanArtifact) {
+    if (action.optional) {
+      const nextHumanArtifact = missingRequired.find((artifact) => artifact.actor !== "ai");
+      if (nextHumanArtifact) {
+        actions.push({
+          label: `Continue without optional AI challenge · Write ${nextHumanArtifact.title}`,
+          run: async () => recordHumanArtifact(ctx, nextHumanArtifact.kind),
+        });
+      } else if (missingRequired.length === 0) {
+        actions.push({
+          label: `Continue without optional AI contribution · Accept ${state.gate.title}`,
+          run: async () => acceptAndContinue(ctx),
+        });
+      }
+    }
+
+    if (state.work_item_required_for_next_phase && state.gate.accepted) {
       actions.push({
-        label: `Continue without optional AI challenge · Write ${nextHumanArtifact.title}`,
-        run: async () => recordHumanArtifact(ctx, nextHumanArtifact.kind),
+        label: action.label,
+        run: async () => manageWorkItem(ctx, ""),
       });
-    } else if (missingRequired.length === 0) {
+    } else if (missingRequired.length === 0 && !action.artifactKind) {
       actions.push({
-        label: `Continue without optional AI contribution · Accept ${state.gate.title}`,
+        label: state.gate.accepted ? action.label : `Accept and continue · ${state.gate.title}`,
         run: async () => acceptAndContinue(ctx),
       });
     }
-  }
 
-  if (state.work_item_required_for_next_phase && state.gate.accepted) {
-    actions.push({
-      label: action.label,
-      run: async () => manageWorkItem(ctx, ""),
-    });
-  } else 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.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") {
+      if (!state.artifacts.some((artifact) => artifact.kind === "changeset" && artifact.present)) {
+        actions.push({
+          label: "Save this ready-to-implement run for a later sprint",
+          run: async () => saveImplementationHandoff(ctx),
+        });
+      }
+      actions.push({
+        label: "Ask AI for help understanding or solving a problem",
+        run: async () => askImplementationQuestion(pi, ctx, state),
+      });
+    }
 
-  if (state.phase.id === "implement") {
-    if (!state.artifacts.some((artifact) => artifact.kind === "changeset" && artifact.present)) {
+    if (state.phase.id === "ai-review" || state.phase.id === "human-review") {
       actions.push({
-        label: "Save this ready-to-implement run for a later sprint",
-        run: async () => saveImplementationHandoff(ctx),
+        label: "Open the changeset review workbench",
+        run: async () => openReviewWorkbench(pi, ctx),
       });
     }
-    actions.push({
-      label: "Ask AI for help understanding or solving a problem",
-      run: async () => askImplementationQuestion(pi, ctx, state),
-    });
-  }
 
-  if (state.phase.id === "ai-review" || state.phase.id === "human-review") {
-    actions.push({
-      label: "Open the changeset review workbench",
-      run: async () => openReviewWorkbench(pi, ctx),
-    });
-  }
+    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",
+        run: async () => returnToEarlierPhase(ctx, ""),
+      });
+    }
+
+    if (!state.work_item_required_for_next_phase || !state.gate.accepted) {
+      actions.push({
+        label: state.work_item
+          ? "View or replace the linked work item"
+          : "Link or create a work item",
+        run: async () => manageWorkItem(ctx, ""),
+      });
+    }
 
-  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",
+      label: "Help · policy, guidance, skills, phase explanation",
       run: async () => {
-        const artifact = [...state.artifacts]
-          .toReversed()
-          .find(
-            (candidate) =>
-              candidate.present && candidate.recorded_by?.kind === "human" && candidate.path,
+        // "← Back" and escaping both return to the action-menu loop above.
+        const helpChoice = await ctx.ui.select("Help · pick one", [
+          "← Back to action menu",
+          "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",
           );
-        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",
-      run: async () => returnToEarlierPhase(ctx, ""),
+      label: "Stop AHEAD mode",
+      run: async () => stopAheadMode(ctx),
     });
-  }
 
-  if (!state.work_item_required_for_next_phase || !state.gate.accepted) {
-    actions.push({
-      label: state.work_item
-        ? "View or replace the linked work item"
-        : "Link or create a work item",
-      run: async () => manageWorkItem(ctx, ""),
-    });
-  }
-
-  actions.push({
-    label: "Help · policy, guidance, skills, phase explanation",
-    run: async () => {
-      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",
-        );
-      }
-    },
-  });
-
-  actions.push({
-    label: "Stop AHEAD mode",
-    run: async () => stopAheadMode(ctx),
-  });
-
-  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) {
+    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) {
+      return;
+    }
     await chosen.run();
   }
 }
@@ -1555,7 +1569,7 @@ function titleExample(workflowId: string): string {
     case "product-change":
       return "“Add audit log viewer page”";
     case "internal-improvement":
-      return "“Reduce cola-api cold-start time”";
+      return "“Reduce cold-start time”";
     case "corrective-debugging":
       return "“Fix race in worker claim loop”";
     case "operational-stabilization":
@@ -1603,15 +1617,27 @@ async function recordHumanArtifact(
   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) {
-    if (ctx.model) {
-      ctx.ui.notify("Drafting two example prompts per field (inspiration only)…", "info");
+    // Visible progress while drafting: the loader row and footer status show
+    // until the call resolves, so the wait never looks like a hang.
+    const showProgress = ctx.model !== undefined;
+    if (showProgress) {
+      ctx.ui.setWorkingMessage("Drafting example prompts (inspiration only)…");
+      ctx.ui.setStatus("ahead-examples", "Drafting example prompts…");
+    }
+    let draft;
+    try {
+      draft = await draftFieldExamples(ctx, {
+        workflowTitle: engine.getWorkflow(state.workflow_id).title,
+        phaseTitle: state.phase.title,
+        runTitle: run.title,
+        fields: prompts,
+      });
+    } finally {
+      if (showProgress) {
+        ctx.ui.setWorkingMessage();
+        ctx.ui.setStatus("ahead-examples", undefined);
+      }
     }
-    const draft = await draftFieldExamples(ctx, {
-      workflowTitle: engine.getWorkflow(state.workflow_id).title,
-      phaseTitle: state.phase.title,
-      runTitle: run.title,
-      fields: prompts,
-    });
     if (draft.examples) {
       template = insertFieldExamples(template, draft.examples);
     } else if (draft.skipped === "no-auth") {