ahead-pi 0.5.0 → 0.7.0

package/generated/reference/docs/guide/workflows/operational-stabilization.md

@@ -177,6 +177,7 @@ During incident or emergency mode, maintain at minimum:
 - A live intervention requires an accountable human unless existing automation was previously authorized for that action.
 - Any lasting engineering change produced during stabilization still requires a human first-pass plan and independent human review, either in this record or a linked change run; emergency policy may defer but not erase those gates.
 - Kubernetes readiness, controller status, or a successful command is not automatically user-visible recovery.
+- The outcome records the durable references (runbooks, design docs, decision records) this stabilization creates or updates, or explicit none; emergency policy may defer the reference-update record to a linked postmortem, but the deferral itself is recorded. See [Durable references](../durable-reference.md).
 - The conclusion may include mechanism, trigger, enabling conditions, and detection or containment gaps rather than one root cause.
 - Closure does not require every follow-up to remain inside the operational run.
 

package/generated/reference/docs/guide/workflows/product-change.md

@@ -151,10 +151,10 @@ An important unknown is disposed only when it is answered or an accountable huma
 | Questions | Understanding and disposition of unknowns | Find missing questions and research answers | Answered, accepted, blocked, or deferred unknowns | Important unknowns are answered or explicitly accepted |
 | Options | At least one initial approach and evaluation criteria | Expand, compare, challenge, add alternatives | Options and tradeoffs | Viable options are understood |
 | Decide | Selection and consequences | Check rationale and surface risks | Decision, rationale, tradeoffs, reversibility | Accountable human approves the decision |
-| Plan | First-pass implementation plan | Identify gaps, dependencies, tests, risks, and rollback needs | Sequenced plan and deviations policy | Human approves the final plan |
-| Implement | Code and engineering changes | Bounded generation, explanation, tests, debugging, and refactoring assistance | Linked changeset and plan deviations | Work is ready for independent review and checks pass |
-| AI review | Validate and disposition every material AI finding | Review the exact snapshot for behavior, security, tests, architecture, and plan alignment without modifying it | Snapshot-bound AI findings; separate human disposition | Every material finding is fixed, invalid, accepted risk, or follow-up with rationale |
-| Human review | Independent final engineering judgment by someone other than the implementer | Answer targeted questions and retrieve evidence | Current independent human review | Independent human reviewer accepts the current change |
+| Plan | First-pass implementation plan and the set of durable references it will touch | Identify gaps, dependencies, tests, risks, rollback needs, and propose reference updates | Sequenced plan, deviations policy, and planned reference updates (decision records, design docs, runbooks, or explicit none) | Human approves the final plan |
+| Implement | Code, engineering changes, and the durable-reference edits that record the change | Bounded generation, explanation, tests, debugging, refactoring assistance, and proposed reference-update drafts | Linked changeset, plan deviations, and actual reference updates | Work is ready for independent review and checks pass |
+| AI review | Validate and disposition every material AI finding | Review against the full open run — decision, plan, plan-deviations, reference-updates, changeset, tests, and evidence — without modifying the change | Review inputs enumeration, snapshot-bound AI findings, and separate human disposition | Every material finding is fixed, invalid, accepted risk, or follow-up with rationale |
+| Human review | Independent final engineering judgment by someone other than the implementer, with the full open run available | Answer targeted questions and retrieve evidence from the live run | Current independent human review | Independent human reviewer accepts the current change |
 | Deploy or release | Authorization and rollout decision | Analyze readiness evidence within policy | Version, environment, actor, time, and result | The intended version reaches the target environment or deployment is explicitly not applicable |
 | Verify and observe | Evaluation against intended behavior | Suggest checks and analyze authorized observations | Test, deployment, and user-visible evidence | Intended outcome is demonstrated or failure is recorded |
 | AI audit | Disposition of findings and any required response | Compare the result with the problem, decision, plan, reviews, and observed behavior; identify divergence, weak evidence, and missed learning | AI audit findings; separate human disposition | The human disposer accepts the audit gate or reopens work |
@@ -207,6 +207,8 @@ HUMAN OUTCOME / LEARNING
 - A human defines or affirms the problem and outcome.
 - A human contributes an option before AI expands the option set.
 - A human authors the first-pass plan.
+- The plan and implementation each record the durable references touched (decision records, design docs, runbooks) or explicit none. See [Durable references](../durable-reference.md).
+- The run stays open from framing through outcome. AI review and independent human review both read the full open run.
 - AI review and implementer self-review do not satisfy independent human review.
 - Implementation completion is not deployment or outcome verification.
 

package/generated/reference/index.json

@@ -10,6 +10,7 @@
     "docs/evidence/sources/tigerstyle.md",
     "docs/guide/README.md",
     "docs/guide/acceptable-ai-use.md",
+    "docs/guide/durable-reference.md",
     "docs/guide/engineering-practice.md",
     "docs/guide/rationale.md",
     "docs/guide/recommended-skills.md",
@@ -156,6 +157,19 @@
         "*"
       ]
     },
+    {
+      "id": "durable-reference",
+      "path": "docs/guide/durable-reference.md",
+      "title": "Durable References",
+      "summary": "AHEAD's workflows produce two kinds of records. **Run artifacts** are scoped to a single run and describe what happened: framing, research, decisions, plans, changesets, review findings, outcomes. **Durable references** outlive a run and de",
+      "audience": "practitioner",
+      "authority": "guidance",
+      "distribution": "agent-and-human",
+      "phases": [],
+      "workflows": [
+        "*"
+      ]
+    },
     {
       "id": "engineering-practice",
       "path": "docs/guide/engineering-practice.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ahead-pi",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "AHEAD workflow enforcement and context for Pi",
   "keywords": [
     "ahead",
@@ -63,6 +63,11 @@
   "engines": {
     "node": ">=22.19.0"
   },
+  "omp": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
   "pi": {
     "extensions": [
       "./src/index.ts"

package/src/guidance.ts

@@ -35,6 +35,7 @@ const guides: Record<string, PhaseGuide> = {
         "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?",
+        "Does novelty or unfamiliarity require primary documentation, direct inspection, or an experiment?",
         "What important evidence is still missing?",
       ],
     },
@@ -109,7 +110,7 @@ const guides: Record<string, PhaseGuide> = {
       ],
       plan: [
         "What is the final ordered implementation sequence?",
-        "What tests and observable evidence are required?",
+        "What human-defined behavior, invariants, test oracles, and observable evidence must the checks evaluate?",
         "How will rollout and recovery work?",
         "Which deviations require returning to decision or plan?",
       ],
@@ -305,11 +306,20 @@ const artifactPromptCatalog: Record<string, string[]> = {
     "How does each option perform against the recorded criteria?",
     "What tradeoffs, risks, sensitivity, confidence, and disagreement remain?",
   ],
-  "published-decision": [
-    "Where is the durable decision and rationale recorded?",
+  "decision-record": [
+    "Where is the durable decision record written, and does it follow the project's ADR convention?",
     "Who is affected, what downstream work is linked, and how will it be communicated?",
     "What event or date should trigger review?",
   ],
+  "reference-updates": [
+    "Which decision records, design docs, or runbooks does this run create or update?",
+    "For each, what section changes and who accepts the change?",
+    "If none, is the run genuinely not altering any durable behavior or documented contract?",
+  ],
+  "review-inputs": [
+    "Which run inputs did the review read: decision, plan, plan-deviations, reference-updates, changeset, tests, and evidence?",
+    "Which inputs were unavailable or intentionally excluded?",
+  ],
   question: [
     "What exact question is being investigated, and why does it matter?",
     "Who owns it, how will findings be used, and what would count as an answer?",
@@ -481,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}`,
@@ -501,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})`,
@@ -516,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) {