ahead-pi 0.3.0 → 0.3.1

package/generated/reference/index.json

@@ -1,28 +1,24 @@
 {
+  "api_version": "ahead.references/v0.1",
   "generated_from": [
     "CONSTITUTION.md",
-    "docs/acceptable-ai-use.md",
-    "docs/design/adapted-skill-guidance.md",
-    "docs/design/debugging-and-operations.md",
-    "docs/design/executable-workflows.md",
-    "docs/design/instruction-authoring.md",
-    "docs/design/process-taxonomy.md",
-    "docs/design/review-workbench.md",
-    "docs/engineering-practice.md",
+    "docs/evidence/README.md",
     "docs/evidence/evidence-standard.md",
     "docs/evidence/research-map.md",
-    "docs/rationale.md",
-    "docs/recommended-skills.md",
-    "docs/references/pragmatic-programmer-page-index.md",
-    "docs/references/submitted-engineering-notes.md",
-    "docs/releasing-pi.md",
-    "docs/workflows/README.md",
-    "docs/workflows/corrective-debugging.md",
-    "docs/workflows/decision.md",
-    "docs/workflows/internal-improvement.md",
-    "docs/workflows/investigation.md",
-    "docs/workflows/operational-stabilization.md",
-    "docs/workflows/product-change.md"
+    "docs/evidence/sources/pragmatic-programmer-page-index.md",
+    "docs/evidence/sources/submitted-engineering-notes.md",
+    "docs/guide/README.md",
+    "docs/guide/acceptable-ai-use.md",
+    "docs/guide/engineering-practice.md",
+    "docs/guide/rationale.md",
+    "docs/guide/recommended-skills.md",
+    "docs/guide/workflows/README.md",
+    "docs/guide/workflows/corrective-debugging.md",
+    "docs/guide/workflows/decision.md",
+    "docs/guide/workflows/internal-improvement.md",
+    "docs/guide/workflows/investigation.md",
+    "docs/guide/workflows/operational-stabilization.md",
+    "docs/guide/workflows/product-change.md"
   ],
   "references": [
     {
@@ -30,6 +26,9 @@
       "path": "CONSTITUTION.md",
       "title": "AHEAD Constitution",
       "summary": "This constitution records the durable principles of **Assisted Human Engineering and Development**. Workflows and tools may evolve. These principles define what makes them AHEAD.",
+      "audience": "practitioner",
+      "authority": "binding",
+      "distribution": "agent-and-human",
       "phases": [
         "*"
       ],
@@ -38,89 +37,88 @@
       ]
     },
     {
-      "id": "acceptable-ai-use",
-      "path": "docs/acceptable-ai-use.md",
-      "title": "Acceptable AI Use in AHEAD",
-      "summary": "This policy is binding for AHEAD pilot workflows. The [AHEAD Constitution](../CONSTITUTION.md) is the highest authority; this policy interprets its human-ownership boundaries; workflow profiles apply both and may narrow AI permissions for a",
-      "phases": [
-        "*"
-      ],
-      "workflows": [
-        "*"
-      ]
-    },
-    {
-      "id": "design:adapted-skill-guidance",
-      "path": "docs/design/adapted-skill-guidance.md",
-      "title": "Adapted Skill Guidance",
-      "summary": "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/ski",
-      "phases": [],
-      "workflows": [
-        "*"
-      ]
-    },
-    {
-      "id": "design:debugging-and-operations",
-      "path": "docs/design/debugging-and-operations.md",
-      "title": "Debugging and Operational Investigation",
-      "summary": "The minimal [corrective-debugging](../workflows/corrective-debugging.md) and [operational-stabilization](../workflows/operational-stabilization.md) profiles translate this discussion into pilotable flows. This document retains the reasoning",
+      "id": "evidence",
+      "path": "docs/evidence/README.md",
+      "title": "AHEAD Evidence and Provenance",
+      "summary": "This library records why AHEAD makes its process choices and how strong the support for those choices is. It is separate from the practitioner guide so source material and methodology governance do not become extra steps in ordinary enginee",
+      "audience": "evidence",
+      "authority": "supporting",
+      "distribution": "agent-and-human",
       "phases": [],
       "workflows": [
         "*"
       ]
     },
     {
-      "id": "design:executable-workflows",
-      "path": "docs/design/executable-workflows.md",
-      "title": "Executable AHEAD Workflows",
-      "summary": "The executable layer makes AHEAD workflow state durable and makes selected human/AI boundaries enforceable across integrations. It does not turn judgment into a checklist or make workflow artifacts proof of understanding.",
+      "id": "evidence:evidence-standard",
+      "path": "docs/evidence/evidence-standard.md",
+      "title": "AHEAD Evidence Standard",
+      "summary": "AHEAD should be supported by the best available evidence without claiming more certainty than software-engineering research can provide. A credible methodology must distinguish evidence for a descriptive claim from evidence that a particula",
+      "audience": "evidence",
+      "authority": "supporting",
+      "distribution": "agent-and-human",
       "phases": [
-        "*"
+        "research",
+        "questions",
+        "decision",
+        "plan",
+        "ai-review",
+        "human-review",
+        "verify",
+        "ai-audit",
+        "outcome"
       ],
       "workflows": [
         "*"
       ]
     },
     {
-      "id": "design:instruction-authoring",
-      "path": "docs/design/instruction-authoring.md",
-      "title": "Instruction Authoring",
-      "summary": "AHEAD instructions are an executable interface to the framework. They should make the next valid behavior clear without duplicating the full Constitution, rationale, or workflow documentation into every model turn.",
+      "id": "evidence:research-map",
+      "path": "docs/evidence/research-map.md",
+      "title": "AHEAD Research Map",
+      "summary": "This document maps current AHEAD design claims to available evidence. It is not a bibliography of everything related to software engineering. It focuses on claims that materially shape the methodology.",
+      "audience": "evidence",
+      "authority": "supporting",
+      "distribution": "agent-and-human",
       "phases": [],
       "workflows": [
         "*"
       ]
     },
     {
-      "id": "design:process-taxonomy",
-      "path": "docs/design/process-taxonomy.md",
-      "title": "AHEAD Process Taxonomy",
-      "summary": "AHEAD should not create a workflow for every issue label. “Security,” “performance,” “data,” “incident,” and “technical debt” often describe risk, domain, urgency, or cause—not the kind of reasoning needed to complete the work.",
+      "id": "evidence:sources:pragmatic-programmer-page-index",
+      "path": "docs/evidence/sources/pragmatic-programmer-page-index.md",
+      "title": "*The Pragmatic Programmer* Page Index",
+      "summary": "This index preserves the page-level provenance from the original AHEAD engineering-practice notes for:",
+      "audience": "evidence",
+      "authority": "supporting",
+      "distribution": "agent-and-human",
       "phases": [],
       "workflows": [
         "*"
       ]
     },
     {
-      "id": "design:review-workbench",
-      "path": "docs/design/review-workbench.md",
-      "title": "Review Workbench",
-      "summary": "The review workbench makes the handoff from implementation to independent human review explicit and inspectable:",
-      "phases": [
-        "ai-review",
-        "human-review"
-      ],
+      "id": "evidence:sources:submitted-engineering-notes",
+      "path": "docs/evidence/sources/submitted-engineering-notes.md",
+      "title": "Submitted Engineering Notes",
+      "summary": "This document preserves submitted engineering tips, checklists, and practices that are intentionally condensed in the [AHEAD Engineering Practice](../../guide/engineering-practice.md) guide. It is a source record, not a claim that every ite",
+      "audience": "evidence",
+      "authority": "supporting",
+      "distribution": "agent-and-human",
+      "phases": [],
       "workflows": [
-        "product-change",
-        "corrective-debugging",
-        "internal-improvement"
+        "*"
       ]
     },
     {
-      "id": "engineering-practice",
-      "path": "docs/engineering-practice.md",
-      "title": "AHEAD Engineering Practice",
-      "summary": "AHEAD is not only a sequence of AI gates. It is a way of practicing engineering. This guide distills general habits from the submitted starting list into a smaller set of principles that can be remembered, applied, and evaluated.",
+      "id": "guide",
+      "path": "docs/guide/README.md",
+      "title": "AHEAD Practitioner Guide",
+      "summary": "This is the starting point for people applying AHEAD to engineering work. These documents explain what practitioners are expected to understand, decide, record, and review. They do not describe how the Rust engine, Pi adapter, instruction g",
+      "audience": "practitioner",
+      "authority": "guidance",
+      "distribution": "agent-and-human",
       "phases": [
         "*"
       ],
@@ -129,40 +127,43 @@
       ]
     },
     {
-      "id": "evidence:evidence-standard",
-      "path": "docs/evidence/evidence-standard.md",
-      "title": "AHEAD Evidence Standard",
-      "summary": "AHEAD should be supported by the best available evidence without claiming more certainty than software-engineering research can provide. A credible methodology must distinguish evidence for a descriptive claim from evidence that a particula",
+      "id": "acceptable-ai-use",
+      "path": "docs/guide/acceptable-ai-use.md",
+      "title": "Acceptable AI Use in AHEAD",
+      "summary": "This policy is binding for AHEAD pilot workflows. The [AHEAD Constitution](../../CONSTITUTION.md) is the highest authority; this policy interprets its human-ownership boundaries; workflow profiles apply both and may narrow AI permissions fo",
+      "audience": "practitioner",
+      "authority": "binding",
+      "distribution": "agent-and-human",
       "phases": [
-        "research",
-        "questions",
-        "decision",
-        "plan",
-        "ai-review",
-        "human-review",
-        "verify",
-        "ai-audit",
-        "outcome"
+        "*"
       ],
       "workflows": [
         "*"
       ]
     },
     {
-      "id": "evidence:research-map",
-      "path": "docs/evidence/research-map.md",
-      "title": "AHEAD Research Map",
-      "summary": "This document maps current AHEAD design claims to available evidence. It is not a bibliography of everything related to software engineering. It focuses on claims that materially shape the methodology.",
-      "phases": [],
+      "id": "engineering-practice",
+      "path": "docs/guide/engineering-practice.md",
+      "title": "AHEAD Engineering Practice",
+      "summary": "AHEAD is not only a sequence of AI gates. It is a way of practicing engineering. This guide distills general habits from the submitted starting list into a smaller set of principles that can be remembered, applied, and evaluated.",
+      "audience": "practitioner",
+      "authority": "guidance",
+      "distribution": "agent-and-human",
+      "phases": [
+        "*"
+      ],
       "workflows": [
         "*"
       ]
     },
     {
       "id": "rationale",
-      "path": "docs/rationale.md",
+      "path": "docs/guide/rationale.md",
       "title": "Why AHEAD",
       "summary": "AI can make software engineering faster. It can search broadly, synthesize information, identify omissions, generate alternatives, produce routine code, explain unfamiliar systems, and review more material than a person can inspect unaided.",
+      "audience": "practitioner",
+      "authority": "guidance",
+      "distribution": "agent-and-human",
       "phases": [
         "*"
       ],
@@ -172,49 +173,25 @@
     },
     {
       "id": "recommended-skills",
-      "path": "docs/recommended-skills.md",
+      "path": "docs/guide/recommended-skills.md",
       "title": "Recommended Skills",
       "summary": "AHEAD may recommend independently maintained agent skills when they strengthen an active phase. Recommendations are references, not bundled code or silent dependencies. A human chooses whether to inspect and install one, and AHEAD's workflo",
+      "audience": "practitioner",
+      "authority": "guidance",
+      "distribution": "agent-and-human",
       "phases": [],
       "workflows": [
         "*"
       ]
     },
     {
-      "id": "references:pragmatic-programmer-page-index",
-      "path": "docs/references/pragmatic-programmer-page-index.md",
-      "title": "*The Pragmatic Programmer* Page Index",
-      "summary": "This index preserves the page-level provenance from the original AHEAD engineering-practice notes for:",
-      "phases": [],
-      "workflows": [
-        "*"
-      ]
-    },
-    {
-      "id": "references:submitted-engineering-notes",
-      "path": "docs/references/submitted-engineering-notes.md",
-      "title": "Submitted Engineering Notes",
-      "summary": "This document preserves submitted engineering tips, checklists, and practices that are intentionally condensed in the [AHEAD Engineering Practice](../engineering-practice.md) guide. It is a source record, not a claim that every item is an e",
-      "phases": [],
-      "workflows": [
-        "*"
-      ]
-    },
-    {
-      "id": "releasing-pi",
-      "path": "docs/releasing-pi.md",
-      "title": "Releasing the Pi Extension",
-      "summary": "- npm package: `ahead-pi` - package source: `integrations/pi` - release workflow: `.github/workflows/publish-pi.yml` - release tag: `pi-v<package-version>` - stable npm dist-tag: `latest` - prerelease npm dist-tag: `next` - registry: `https",
-      "phases": [],
-      "workflows": [
-        "*"
-      ]
-    },
-    {
-      "id": "workflows:readme",
-      "path": "docs/workflows/README.md",
+      "id": "workflows",
+      "path": "docs/guide/workflows/README.md",
       "title": "AHEAD Pilot Workflows",
       "summary": "These six minimal workflow profiles are meant to be used on real engineering work through the Pi adapter or a manual record. Their canonical executable contracts live in `spec/workflows`, while these documents explain the same boundaries an",
+      "audience": "practitioner",
+      "authority": "binding",
+      "distribution": "agent-and-human",
       "phases": [
         "*"
       ],
@@ -224,9 +201,12 @@
     },
     {
       "id": "workflows:corrective-debugging",
-      "path": "docs/workflows/corrective-debugging.md",
+      "path": "docs/guide/workflows/corrective-debugging.md",
       "title": "Corrective Debugging Workflow",
       "summary": "Use this flow when observed behavior conflicts with intended behavior and the dominant work is causal diagnosis plus correction. It ends with a verified correction or an explicit human acceptance of remaining uncertainty.",
+      "audience": "practitioner",
+      "authority": "binding",
+      "distribution": "agent-and-human",
       "phases": [
         "*"
       ],
@@ -236,9 +216,12 @@
     },
     {
       "id": "workflows:decision",
-      "path": "docs/workflows/decision.md",
+      "path": "docs/guide/workflows/decision.md",
       "title": "Decision Workflow",
       "summary": "Use this flow when the deliverable is an accountable human choice among alternatives: architecture, buy versus build, technology selection, platform direction, policy, or another consequential course.",
+      "audience": "practitioner",
+      "authority": "binding",
+      "distribution": "agent-and-human",
       "phases": [
         "*"
       ],
@@ -248,9 +231,12 @@
     },
     {
       "id": "workflows:internal-improvement",
-      "path": "docs/workflows/internal-improvement.md",
+      "path": "docs/guide/workflows/internal-improvement.md",
       "title": "Internal Improvement Workflow",
       "summary": "Use this flow when externally required behavior should remain invariant while an internal quality improves: maintainability, comprehensibility, performance, reliability margin, operability, testability, cost, or preventive risk reduction.",
+      "audience": "practitioner",
+      "authority": "binding",
+      "distribution": "agent-and-human",
       "phases": [
         "*"
       ],
@@ -260,9 +246,12 @@
     },
     {
       "id": "workflows:investigation",
-      "path": "docs/workflows/investigation.md",
+      "path": "docs/guide/workflows/investigation.md",
       "title": "Investigation Workflow",
       "summary": "Use this flow when the primary deliverable is knowledge or reduced uncertainty and no intervention has yet been selected. It may answer feasibility, causal, capacity, vendor, architectural, or technical questions.",
+      "audience": "practitioner",
+      "authority": "binding",
+      "distribution": "agent-and-human",
       "phases": [
         "*"
       ],
@@ -272,9 +261,12 @@
     },
     {
       "id": "workflows:operational-stabilization",
-      "path": "docs/workflows/operational-stabilization.md",
+      "path": "docs/guide/workflows/operational-stabilization.md",
       "title": "Operational Stabilization Workflow",
       "summary": "Use this flow when a live system is outside an acceptable operating state and the immediate outcome is restoration, stabilization, or demonstrated convergence. It covers code and non-code causes such as reconciliation storms, configuration ",
+      "audience": "practitioner",
+      "authority": "binding",
+      "distribution": "agent-and-human",
       "phases": [
         "*"
       ],
@@ -284,9 +276,12 @@
     },
     {
       "id": "workflows:product-change",
-      "path": "docs/workflows/product-change.md",
+      "path": "docs/guide/workflows/product-change.md",
       "title": "Product Change Workflow",
       "summary": "Use this flow when the dominant outcome is new, changed, adapted, migrated, or retired externally meaningful behavior. It ends with verified intended behavior and an accountable human outcome decision.",
+      "audience": "practitioner",
+      "authority": "binding",
+      "distribution": "agent-and-human",
       "phases": [
         "*"
       ],

package/package.json

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

package/src/engine.ts

@@ -60,7 +60,7 @@ export class AheadEngine {
     title: string;
     owner: Actor;
     timestamp: string;
-    workflow_id?: string;
+    workflow_id: string;
   }): Run {
     return this.call("create_run", input);
   }

package/src/guidance.ts

@@ -442,7 +442,7 @@ function nextPendingArtifact(state: RunState): ArtifactState | undefined {
   );
 }
 
-export function buildWidgetLines(
+export function buildHeaderLines(
   run: Run,
   state: RunState,
   workflow: WorkflowDefinition,
@@ -464,14 +464,10 @@ export function buildWidgetLines(
   const action = nextAction(state, workflow);
 
   return [
-    `AHEAD MODE · ${workflow.title.toUpperCase()} · ${position.current}/${position.total}`,
-    `${guide.handoff ?? state.phase.title.toUpperCase()} · HUMAN LEADS · AI ASSISTS`,
+    `AHEAD · ${workflow.title} · ${position.current}/${position.total} · ${state.phase.title}`,
     `Goal: ${guide.objective}`,
-    `You: ${guide.human}`,
-    `AI: ${guide.ai}`,
     `Required: ${checklist}`,
-    `Next (${action.actor === "human" ? "you" : "AI"}): ${action.label}`,
-    "Run /ahead for the guided action · /ahead-guide for framework docs.",
+    `Next: ${action.actor === "human" ? "You" : "AI"} → ${action.label}`,
   ];
 }