ahead-pi 0.8.2 → 0.8.4

package/package.json

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

package/src/guidance.ts

@@ -424,7 +424,9 @@ export function nextAction(state: RunState, workflow: WorkflowDefinition): Guide
         ? "Ask AI to challenge the human option and expand alternatives"
         : state.phase.id === "plan"
           ? "Ask AI to challenge the human first-pass plan"
-          : `Ask AI to contribute ${artifact.title}`;
+          : artifact.title.startsWith("AI ")
+            ? `Ask AI for ${lowercaseFirst(artifact.title.slice(3))}`
+            : `Ask AI to contribute ${artifact.title}`;
     return artifact.required
       ? { actor, label, artifactKind: artifact.kind }
       : { actor, label, artifactKind: artifact.kind, optional: true };
@@ -533,8 +535,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 +552,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,17 +590,28 @@ 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)`);
     }
   }
   return errors;
 }
 
+function lowercaseFirst(value: string): string {
+  return value.charAt(0).toLowerCase() + value.slice(1);
+}
+
 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

@@ -702,7 +702,7 @@ async function openAheadMode(
         });
       } else if (missingRequired.length === 0) {
         actions.push({
-          label: `Continue without optional AI contribution · Accept ${state.gate.title}`,
+          label: `Continue without optional AI contribution · ${state.gate.title}`,
           run: async () => acceptAndContinue(ctx),
         });
       }
@@ -752,8 +752,12 @@ async function openAheadMode(
       });
     }
 
+    // The generic challenger appears only when the next move is the human's.
+    // When the primary action is already an AI contribution, the formal AI
+    // artifact owns that job and a second "challenge me" entry is noise.
     if (
       state.allowed_ai_capabilities.length > 0 &&
+      action.actor !== "ai" &&
       state.artifacts.some(
         (artifact) => artifact.present && artifact.recorded_by?.kind === "human" && artifact.path,
       )
@@ -1617,15 +1621,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") {