ahead-pi 0.3.0 → 0.3.1

package/src/index.ts

@@ -4,12 +4,14 @@ import type {
   ExtensionAPI,
   ExtensionCommandContext,
   ExtensionContext,
+  Theme,
 } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { AheadEngine, AheadEngineError } from "./engine.js";
 import {
   buildArtifactTemplate,
-  buildWidgetLines,
+  buildHeaderLines,
   nextAction,
   phaseGuide,
   phasePosition,
@@ -19,6 +21,7 @@ import {
   loadReferenceIndex,
   readReference,
   relevantReferences,
+  type ReferenceEntry,
 } from "./reference.js";
 import { showReferenceViewer } from "./reference-viewer.js";
 import {
@@ -71,7 +74,7 @@ const ReferenceParams = Type.Object({
 
 export default function aheadExtension(pi: ExtensionAPI): void {
   pi.registerCommand("ahead", {
-    description: "Enter or continue the guided AHEAD mode",
+    description: "Enter AHEAD mode or open its action menu",
     handler: async (args, ctx) =>
       command(ctx, async () => {
         await openAheadMode(pi, args, ctx);
@@ -102,8 +105,24 @@ export default function aheadExtension(pi: ExtensionAPI): void {
       }),
   });
 
+  pi.registerCommand("ahead-stop", {
+    description: "Exit AHEAD mode; discard the unfinished record or explicitly save it",
+    handler: async (_args, ctx) =>
+      command(ctx, async () => {
+        await stopAheadMode(ctx);
+      }),
+  });
+
+  pi.registerCommand("ahead-resume", {
+    description: "Resume unfinished AHEAD work that was explicitly saved",
+    handler: async (args, ctx) =>
+      command(ctx, async () => {
+        await resumeSavedRun(ctx, args.trim());
+      }),
+  });
+
   pi.registerCommand("ahead-start", {
-    description: "Advanced: start a workflow directly with [workflow-id ::] title",
+    description: "Advanced: start directly with <workflow-id> :: <title>",
     handler: async (args, ctx) =>
       command(ctx, async () => {
         await startRun(ctx, args);
@@ -208,14 +227,16 @@ export default function aheadExtension(pi: ExtensionAPI): void {
     handler: async (_args, ctx) => {
       ctx.ui.notify(
         [
-          "/ahead [title] — choose a workflow for new work, or resume guided AHEAD mode",
+          "/ahead [title] — choose a workflow for new work, or open the active action menu",
           "/ahead-guide [topic] — read the applicable AHEAD framework Markdown",
           "/ahead-skills — inspect optional reviewed skills relevant to this phase",
           "/ahead-review — inspect the exact changeset and review handoff",
+          "/ahead-stop — leave AHEAD mode; discard the unfinished record by default or explicitly save it",
+          "/ahead-resume [run-id] — resume an unfinished run that you explicitly saved",
           "",
-          "Once started, the repository run remains in AHEAD mode until an accountable human closes the outcome.",
-          "Use normal conversation to think and work with AI. Run /ahead whenever you want the next valid action.",
-          "The persistent guide explains what you own, what AI may do, required evidence, and what happens next.",
+          "Once started, the repository run remains in AHEAD mode until an accountable human closes it or uses /ahead-stop.",
+          "Use normal conversation to think and work with AI. AHEAD remains active and guides every turn.",
+          "The compact header shows the goal, required evidence, and next owner. /ahead reopens the action menu when you need a recorded action.",
           "",
           "Advanced fallback commands: /ahead-status, /ahead-record, /ahead-accept, /ahead-advance, /ahead-return.",
           "AI can record only AI/shared artifacts allowed in the active phase. It cannot accept gates, transition, approve, deploy, or close the run.",
@@ -301,7 +322,13 @@ export default function aheadExtension(pi: ExtensionAPI): void {
             phase: phase ?? null,
             workflow: workflowId ?? null,
             recommended: await relevantReferences(workflowId, phase),
-            available: index.references.map(({ id, title, path }) => ({ id, title, path })),
+            available: index.references.map(({ id, title, path, audience, authority }) => ({
+              id,
+              title,
+              path,
+              audience,
+              authority,
+            })),
             instruction: "Request one reference by id, path, or title. Load only what is relevant.",
           };
         }
@@ -402,7 +429,7 @@ export default function aheadExtension(pi: ExtensionAPI): void {
       if (run && !(await enginePromise).deriveState(run).closed && ctx.hasUI) {
         const state = (await enginePromise).deriveState(run);
         ctx.ui.notify(
-          `AHEAD mode resumed · ${state.phase.title}. Human leads, AI assists. Run /ahead for the next guided action.`,
+          `AHEAD mode resumed · ${state.phase.title}. Continue in normal conversation; /ahead is available when you need the action menu.`,
           "info",
         );
       }
@@ -517,6 +544,23 @@ async function openAheadMode(
     run = undefined;
   }
 
+  if (!run) {
+    if (!args.trim() && ctx.hasUI) {
+      const saved = await loadResumableRuns(ctx);
+      if (saved.length > 0) {
+        const choice = await ctx.ui.select("No active AHEAD run", [
+          "Resume explicitly saved AHEAD work",
+          "Start new AHEAD work",
+        ]);
+        if (choice === "Resume explicitly saved AHEAD work") {
+          run = await resumeSavedRun(ctx, "", saved);
+        } else if (choice !== "Start new AHEAD work") {
+          return;
+        }
+      }
+    }
+  }
+
   if (!run) {
     run = await startRun(ctx, args);
     if (!run) {
@@ -640,6 +684,11 @@ async function openAheadMode(
     },
   });
 
+  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),
@@ -650,6 +699,126 @@ async function openAheadMode(
   }
 }
 
+async function stopAheadMode(ctx: ExtensionCommandContext): Promise<void> {
+  if (!ctx.hasUI) {
+    throw new Error("/ahead-stop requires interactive or RPC UI support");
+  }
+  const store = storeFor(ctx);
+  const run = await requireRun(ctx);
+  const state = (await enginePromise).deriveState(run);
+  if (state.closed) {
+    ctx.ui.notify("This AHEAD run is already complete.", "info");
+    return;
+  }
+
+  const discard = "Stop and discard the unfinished AHEAD record";
+  const save = "Stop and save the unfinished run for later";
+  const selected = await ctx.ui.select("Stop AHEAD mode", [discard, save]);
+  if (selected === discard) {
+    const confirmed = await ctx.ui.confirm(
+      "Discard this unfinished AHEAD record?",
+      [
+        `${run.title} · ${state.phase.title}`,
+        "",
+        "This removes only this run's .ahead workflow state and artifacts.",
+        "It does not delete, reset, or revert source code or other repository changes.",
+      ].join("\n"),
+    );
+    if (!confirmed) {
+      return;
+    }
+    await store.discardCurrent(run.id);
+    await refreshUi(ctx);
+    ctx.ui.notify(
+      "AHEAD mode stopped and its unfinished workflow record was discarded. Repository changes were left untouched.",
+      "info",
+    );
+  } else if (selected === save) {
+    await store.saveCurrentForResume(run.id);
+    await refreshUi(ctx);
+    ctx.ui.notify(
+      `AHEAD mode stopped and run ${run.id} was saved. Resume it with /ahead-resume ${run.id}.`,
+      "info",
+    );
+  }
+}
+
+async function resumeSavedRun(
+  ctx: ExtensionCommandContext,
+  requestedRunId: string,
+  supplied?: Run[],
+): Promise<Run | undefined> {
+  const store = storeFor(ctx);
+  const current = await store.loadCurrent();
+  if (current && !(await enginePromise).deriveState(current).closed) {
+    throw new AheadEngineError(
+      "active_run_exists",
+      `run ${current.id} is still active; stop it before resuming another run`,
+    );
+  }
+
+  const saved = supplied ?? (await loadResumableRuns(ctx));
+  if (saved.length === 0) {
+    ctx.ui.notify("No saved unfinished AHEAD runs are available.", "info");
+    return undefined;
+  }
+
+  let selected = requestedRunId
+    ? saved.find((candidate) => candidate.id === requestedRunId)
+    : undefined;
+  if (requestedRunId && !selected) {
+    throw new AheadEngineError(
+      "saved_run_not_found",
+      `saved unfinished run ${requestedRunId} was not found`,
+    );
+  }
+  if (!selected) {
+    if (!ctx.hasUI) {
+      throw new Error("/ahead-resume requires a run id without interactive UI");
+    }
+    const options = saved.map(savedRunOption);
+    const choice = await ctx.ui.select("Resume saved AHEAD work", options);
+    selected = saved.find((candidate) => savedRunOption(candidate) === choice);
+  }
+  if (!selected) {
+    return undefined;
+  }
+
+  const resumed = await store.resume(selected.id);
+  const state = (await enginePromise).deriveState(resumed);
+  await refreshUi(ctx, resumed);
+  ctx.ui.notify(
+    `AHEAD mode resumed · ${state.phase.title}. Existing artifacts and unmet gates were preserved.`,
+    "info",
+  );
+  return resumed;
+}
+
+async function loadResumableRuns(ctx: ExtensionContext): Promise<Run[]> {
+  const store = storeFor(ctx);
+  const engine = await enginePromise;
+  const resumable: Run[] = [];
+  const invalid: string[] = [];
+  for (const runId of await store.listRunIds()) {
+    try {
+      const run = await store.load(runId);
+      if (!engine.deriveState(run).closed) {
+        resumable.push(run);
+      }
+    } catch {
+      invalid.push(runId);
+    }
+  }
+  if (invalid.length > 0 && ctx.hasUI) {
+    ctx.ui.notify(`Ignored invalid saved AHEAD runs: ${invalid.join(", ")}`, "warning");
+  }
+  return resumable;
+}
+
+function savedRunOption(run: Run): string {
+  return `${run.title} · ${run.workflow_id} · ${run.id}`;
+}
+
 async function showRecommendedSkills(ctx: ExtensionCommandContext): Promise<void> {
   if (!ctx.hasUI) {
     throw new Error("Inspecting recommended skills requires interactive or RPC UI support");
@@ -782,11 +951,11 @@ async function showAheadGuide(ctx: ExtensionCommandContext, requestedTopic: stri
       requestedTopic.trim().toLowerCase() === "all"
         ? index.references
         : await relevantReferences(workflowId, phase);
-    const browseAll = "Browse all packaged AHEAD Markdown";
+    const browseAll = "Browse all practitioner and evidence Markdown";
     const selected = await ctx.ui.select(
       phase ? `AHEAD guidance · ${phase}` : "AHEAD framework guidance",
       [
-        ...recommended.map((candidate) => candidate.title),
+        ...recommended.map(referenceOption),
         ...(recommended.length < index.references.length ? [browseAll] : []),
       ],
     );
@@ -796,7 +965,7 @@ async function showAheadGuide(ctx: ExtensionCommandContext, requestedTopic: stri
     if (selected === browseAll) {
       return showAheadGuide(ctx, "all");
     }
-    entry = recommended.find((candidate) => candidate.title === selected);
+    entry = recommended.find((candidate) => referenceOption(candidate) === selected);
   }
   if (!entry) {
     return;
@@ -805,6 +974,11 @@ async function showAheadGuide(ctx: ExtensionCommandContext, requestedTopic: stri
   await showReferenceViewer(ctx, `AHEAD reference · ${entry.title}`, await readReference(entry));
 }
 
+function referenceOption(entry: ReferenceEntry): string {
+  const classification = entry.audience === "evidence" ? "evidence" : entry.authority;
+  return `${classification} · ${entry.title}`;
+}
+
 async function startRun(ctx: ExtensionCommandContext, request: string): Promise<Run | undefined> {
   const engine = await enginePromise;
   const store = storeFor(ctx);
@@ -836,10 +1010,15 @@ async function startRun(ctx: ExtensionCommandContext, request: string): Promise<
       workflows.map((candidate) => candidate.title),
     );
     workflow = workflows.find((candidate) => candidate.title === selected);
+    if (!workflow) {
+      return undefined;
+    }
   }
-  workflow ??= workflows.find((candidate) => candidate.id === "product-change");
   if (!workflow) {
-    throw new AheadEngineError("missing_workflow", "the engine did not provide Product Change");
+    throw new AheadEngineError(
+      "workflow_required",
+      `choose a workflow explicitly: ${workflows.map((candidate) => candidate.id).join(", ")}. Noninteractive usage: /ahead-start <workflow-id> :: <title>`,
+    );
   }
 
   const title =
@@ -865,8 +1044,8 @@ async function startRun(ctx: ExtensionCommandContext, request: string): Promise<
     [
       `AHEAD mode started · ${workflow.title} · ${run.title}`,
       "Human leads · AI assists",
-      "This run remains active in the repository until an accountable human closes the outcome.",
-      "Use /ahead for the next guided action; use normal conversation to think and work with AI.",
+      "This run remains active until an accountable human closes the outcome or uses /ahead-stop.",
+      "Continue in normal conversation. /ahead is available when you need the action menu.",
     ].join("\n"),
     "info",
   );
@@ -925,7 +1104,7 @@ async function recordHumanArtifact(
   await store.save(updated);
   await refreshUi(ctx, updated);
   ctx.ui.notify(
-    `Saved ${artifact.title}. AHEAD mode remains active; continue the conversation or run /ahead for the next guided action.`,
+    `Saved ${artifact.title}. AHEAD mode remains active; continue the conversation.`,
     "info",
   );
 }
@@ -1095,13 +1274,13 @@ async function acceptAndContinue(ctx: ExtensionCommandContext): Promise<void> {
         "READY FOR INDEPENDENT HUMAN REVIEW",
         "The AI review is recorded and its material findings were disposed by a human.",
         "A draft branch may already exist, but a human must now request review or mark the PR ready.",
-        "The independent reviewer opens this repository, runs /ahead, and records the review.",
+        "The independent reviewer opens this repository; AHEAD resumes at Human Review and guides the review record.",
       ].join("\n"),
       "info",
     );
   } else {
     ctx.ui.notify(
-      `Continued to ${nextState.phase.title}. AHEAD mode remains active; run /ahead for the next guided action.`,
+      `Continued to ${nextState.phase.title}. AHEAD mode remains active; continue the conversation.`,
       "info",
     );
   }
@@ -1196,6 +1375,9 @@ async function refreshUi(ctx: ExtensionContext, supplied?: Run): Promise<void> {
   if (!run) {
     ctx.ui.setStatus("ahead", undefined);
     ctx.ui.setWidget("ahead", undefined);
+    if (ctx.mode === "tui") {
+      ctx.ui.setHeader(undefined);
+    }
     return;
   }
   const engine = await enginePromise;
@@ -1209,7 +1391,60 @@ async function refreshUi(ctx: ExtensionContext, supplied?: Run): Promise<void> {
       ? `AHEAD · complete · ${state.workflow_id}`
       : `AHEAD · ${position.current}/${position.total} · ${state.phase.id} · ${action.actor} action`,
   );
-  ctx.ui.setWidget("ahead", buildWidgetLines(run, state, workflow), { placement: "aboveEditor" });
+  if (state.closed) {
+    ctx.ui.setWidget("ahead", undefined);
+    if (ctx.mode === "tui") {
+      ctx.ui.setHeader(undefined);
+    }
+    return;
+  }
+
+  const lines = buildHeaderLines(run, state, workflow);
+  if (ctx.mode === "tui") {
+    ctx.ui.setWidget("ahead", undefined);
+    ctx.ui.setHeader((_tui, theme) => aheadHeader(lines, theme));
+  } else {
+    ctx.ui.setWidget("ahead", lines, { placement: "aboveEditor" });
+  }
+}
+
+function aheadHeader(lines: string[], theme: Theme) {
+  return {
+    render(width: number): string[] {
+      const [heading = "AHEAD", ...fields] = lines;
+      const styledHeading = `${theme.fg("accent", theme.bold("AHEAD"))}${theme.fg("muted", heading.slice("AHEAD".length))}`;
+      const ruleWidth = Math.max(0, width - visibleWidth(styledHeading) - 1);
+      const headingLine = `${styledHeading}${
+        ruleWidth > 0 ? ` ${theme.fg("borderMuted", "─".repeat(ruleWidth))}` : ""
+      }`;
+
+      return [
+        truncateToWidth(headingLine, width),
+        ...fields.map((field) => formatAheadHeaderField(field, width, theme)),
+      ];
+    },
+    invalidate() {},
+  };
+}
+
+function formatAheadHeaderField(field: string, width: number, theme: Theme): string {
+  const separator = field.indexOf(":");
+  if (separator < 0) {
+    return truncateToWidth(theme.fg("text", field), width);
+  }
+
+  const label = field.slice(0, separator).toUpperCase().padEnd(8);
+  let value = field.slice(separator + 1).trimStart();
+  let styledValue = theme.fg("text", value);
+  if (label.trim() === "NEXT") {
+    const actor = value.startsWith("You →") ? "You →" : value.startsWith("AI →") ? "AI →" : "";
+    if (actor) {
+      value = value.slice(actor.length);
+      styledValue = `${theme.fg(actor.startsWith("You") ? "success" : "accent", theme.bold(actor))}${theme.fg("text", value)}`;
+    }
+  }
+
+  return truncateToWidth(`${theme.fg("muted", theme.bold(label))} ${styledValue}`, width);
 }
 
 async function loadInstructions(workflowId: string, phase: string): Promise<string> {

package/src/reference.ts

@@ -8,11 +8,15 @@ export interface ReferenceEntry {
   path: string;
   title: string;
   summary: string;
+  audience: "practitioner" | "evidence";
+  authority: "binding" | "guidance" | "supporting";
+  distribution: "agent-and-human";
   phases: string[];
   workflows: string[];
 }
 
 interface ReferenceIndex {
+  api_version: "ahead.references/v0.1";
   generated_from: string[];
   references: ReferenceEntry[];
 }
@@ -75,9 +79,11 @@ function parseReferenceIndex(content: string): ReferenceIndex {
   if (!isRecord(value)) {
     throw new Error("Invalid packaged AHEAD reference index");
   }
+  const apiVersion = value.api_version;
   const generatedFrom = value.generated_from;
   const references = value.references;
   if (
+    apiVersion !== "ahead.references/v0.1" ||
     !Array.isArray(generatedFrom) ||
     !generatedFrom.every((entry) => typeof entry === "string") ||
     !Array.isArray(references) ||
@@ -85,7 +91,7 @@ function parseReferenceIndex(content: string): ReferenceIndex {
   ) {
     throw new Error("Invalid packaged AHEAD reference index");
   }
-  return { generated_from: generatedFrom, references };
+  return { api_version: apiVersion, generated_from: generatedFrom, references };
 }
 
 function isReferenceEntry(value: unknown): value is ReferenceEntry {
@@ -95,6 +101,11 @@ function isReferenceEntry(value: unknown): value is ReferenceEntry {
     typeof value.path === "string" &&
     typeof value.title === "string" &&
     typeof value.summary === "string" &&
+    (value.audience === "practitioner" || value.audience === "evidence") &&
+    (value.authority === "binding" ||
+      value.authority === "guidance" ||
+      value.authority === "supporting") &&
+    value.distribution === "agent-and-human" &&
     Array.isArray(value.phases) &&
     value.phases.every((phase) => typeof phase === "string") &&
     Array.isArray(value.workflows) &&

package/src/storage.ts

@@ -1,6 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rename, rm, unlink, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
 import type { Actor, Run } from "./types.js";
 
@@ -49,6 +49,39 @@ export class RunStore {
     }
   }
 
+  async listRunIds(): Promise<string[]> {
+    try {
+      const entries = await readdir(join(this.aheadDirectory, "runs"), { withFileTypes: true });
+      return entries
+        .filter((entry) => entry.isDirectory() && isSafeRunId(entry.name))
+        .map((entry) => entry.name)
+        .toSorted((left, right) => right.localeCompare(left));
+    } catch (error) {
+      if (isMissing(error)) {
+        return [];
+      }
+      throw error;
+    }
+  }
+
+  async saveCurrentForResume(runId: string): Promise<void> {
+    await this.load(runId);
+    await this.clearCurrent(runId);
+  }
+
+  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);
+    return run;
+  }
+
+  async discardCurrent(runId: string): Promise<void> {
+    const directory = this.runDirectory(runId);
+    await this.clearCurrent(runId);
+    await rm(directory, { recursive: true, force: false });
+  }
+
   artifactPath(run: Run, phase: string, kind: string): { absolute: string; relative: string } {
     const sequence = String(run.events.length + 1).padStart(4, "0");
     const absolute = join(
@@ -81,10 +114,33 @@ export class RunStore {
   }
 
   private runPath(runId: string): string {
-    if (!/^[A-Za-z0-9._-]+$/.test(runId)) {
+    return join(this.runDirectory(runId), "run.json");
+  }
+
+  private runDirectory(runId: string): string {
+    if (!isSafeRunId(runId)) {
       throw new Error("unsafe AHEAD run id");
     }
-    return join(this.aheadDirectory, "runs", runId, "run.json");
+    return join(this.aheadDirectory, "runs", runId);
+  }
+
+  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;
+      }
+      throw error;
+    }
+    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);
   }
 }
 
@@ -137,6 +193,10 @@ function isMissing(error: unknown): boolean {
   return !!error && typeof error === "object" && "code" in error && error.code === "ENOENT";
 }
 
+function isSafeRunId(runId: string): boolean {
+  return runId !== "." && runId !== ".." && /^[A-Za-z0-9._-]+$/.test(runId);
+}
+
 function parseCurrentRunPointer(content: string): CurrentRunPointer {
   const value: unknown = JSON.parse(content);
   if (

package/generated/reference/docs/design/adapted-skill-guidance.md

@@ -1,27 +0,0 @@
-# Adapted Skill Guidance
-
-Status: approved first adaptation set, 2026-08-12
-
-AHEAD reviewed the [Matt Pocock skills collection](https://www.skills.sh/mattpocock/skills), including the specifically discussed [grill-me](https://www.skills.sh/mattpocock/skills/grill-me), [prototype](https://www.skills.sh/mattpocock/skills/prototype), and [ask-matt](https://www.skills.sh/mattpocock/skills/ask-matt) skills. It also reviewed [Ponytail](https://github.com/DietrichGebert/ponytail/tree/2ed6c52c9d7e5e56942508591085fd45dea277d3/skills/ponytail). The useful ideas were treated as design input, not installed wholesale or made authoritative.
-
-## Adapted into AHEAD now
-
-- Guided questioning became a dependency-frontier method: AI discovers facts, humans answer consequential judgment questions, and rounds scale with risk.
-- Research became provenance inside existing workflow artifacts: primary sources, direct observations, contradictions, applicability, and uncertainty.
-- Planning became human-first vertical decomposition with dependencies, acceptance criteria, rollout, recovery, and expand-migrate-verify-contract stages for broad changes.
-- Debugging gained tighter safe feedback loops, minimized reproductions, ranked falsifiable hypotheses, one-variable probes, tagged instrumentation, regression evidence, and an explicit no-safe-reproduction path.
-- Prototyping became an Investigation technique with an explicit learning question, deliberately disposable code, visible outcomes, and mandatory human disposition. Prototype code cannot be promoted directly.
-- Review became an exact-changeset workbench with structured AI findings, a separate implementing-human disposition, and later independent human judgment.
-- Instruction design became progressive disclosure: binding profile, applicable phase and method fragments, then on-demand framework references.
-
-These adaptations live in AHEAD's own workflow specs, `policy/methods`, and host-neutral contracts. They require only artifacts already justified by an AHEAD phase; no source skill's private artifact system or issue format was imported.
-
-## Deliberately not adopted
-
-- Persona emulation such as “ask Matt” is not framework authority or a substitute for project evidence.
-- No skill may skip the human's initial model, decision, plan, understanding, tests, or review.
-- A quick, lazy, or persistent implementation is not production-ready merely because it runs.
-- AHEAD does not silently install third-party skills, create extra artifacts, post GitHub comments, create issues, push code, or mark a pull request ready.
-- Issue intake, domain or architecture specialization, formal understanding handoff, and wayfinding remain deferred until their AHEAD-native process is separately approved.
-
-The recommendation catalog records external code AHEAD suggests installing. The method overlays record guidance AHEAD owns. Keeping those separate allows a project to use any editor or model without depending on a particular skill package.