ahead-pi 0.2.1 → 0.3.1

package/generated/reference/index.json

@@ -1,24 +1,24 @@
 {
+  "api_version": "ahead.references/v0.1",
   "generated_from": [
     "CONSTITUTION.md",
-    "docs/acceptable-ai-use.md",
-    "docs/design/debugging-and-operations.md",
-    "docs/design/executable-workflows.md",
-    "docs/design/process-taxonomy.md",
-    "docs/engineering-practice.md",
+    "docs/evidence/README.md",
     "docs/evidence/evidence-standard.md",
     "docs/evidence/research-map.md",
-    "docs/rationale.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": [
     {
@@ -26,48 +26,26 @@
       "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": [
         "*"
-      ]
-    },
-    {
-      "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: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",
-      "phases": []
-    },
-    {
-      "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.",
-      "phases": [
-        "*"
-      ]
-    },
-    {
-      "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.",
-      "phases": []
-    },
-    {
-      "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.",
-      "phases": [
+      "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": [
         "*"
       ]
     },
@@ -76,6 +54,9 @@
       "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",
@@ -86,6 +67,9 @@
         "verify",
         "ai-audit",
         "outcome"
+      ],
+      "workflows": [
+        "*"
       ]
     },
     {
@@ -93,87 +77,216 @@
       "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": "rationale",
-      "path": "docs/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.",
-      "phases": [
+      "audience": "evidence",
+      "authority": "supporting",
+      "distribution": "agent-and-human",
+      "phases": [],
+      "workflows": [
         "*"
       ]
     },
     {
-      "id": "references:pragmatic-programmer-page-index",
-      "path": "docs/references/pragmatic-programmer-page-index.md",
+      "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:",
-      "phases": []
+      "audience": "evidence",
+      "authority": "supporting",
+      "distribution": "agent-and-human",
+      "phases": [],
+      "workflows": [
+        "*"
+      ]
     },
     {
-      "id": "references:submitted-engineering-notes",
-      "path": "docs/references/submitted-engineering-notes.md",
+      "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](../engineering-practice.md) guide. It is a source record, not a claim that every item is an e",
-      "phases": []
+      "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": [
+        "*"
+      ]
     },
     {
-      "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": []
+      "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": [
+        "*"
+      ],
+      "workflows": [
+        "*"
+      ]
+    },
+    {
+      "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": [
+        "*"
+      ],
+      "workflows": [
+        "*"
+      ]
     },
     {
-      "id": "workflows:readme",
-      "path": "docs/workflows/README.md",
+      "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/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": [
+        "*"
+      ],
+      "workflows": [
+        "*"
+      ]
+    },
+    {
+      "id": "recommended-skills",
+      "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": "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 before AHEAD builds a workflow engine, editor extension, or CI enforcement. They are deliberately small. The pilot should reveal which phases, gates, and reco",
-      "phases": []
+      "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": [
+        "*"
+      ],
+      "workflows": [
+        "*"
+      ]
     },
     {
       "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.",
-      "phases": []
+      "audience": "practitioner",
+      "authority": "binding",
+      "distribution": "agent-and-human",
+      "phases": [
+        "*"
+      ],
+      "workflows": [
+        "corrective-debugging"
+      ]
     },
     {
       "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.",
-      "phases": []
+      "audience": "practitioner",
+      "authority": "binding",
+      "distribution": "agent-and-human",
+      "phases": [
+        "*"
+      ],
+      "workflows": [
+        "decision"
+      ]
     },
     {
       "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.",
-      "phases": []
+      "audience": "practitioner",
+      "authority": "binding",
+      "distribution": "agent-and-human",
+      "phases": [
+        "*"
+      ],
+      "workflows": [
+        "internal-improvement"
+      ]
     },
     {
       "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.",
-      "phases": []
+      "audience": "practitioner",
+      "authority": "binding",
+      "distribution": "agent-and-human",
+      "phases": [
+        "*"
+      ],
+      "workflows": [
+        "investigation"
+      ]
     },
     {
       "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 ",
-      "phases": []
+      "audience": "practitioner",
+      "authority": "binding",
+      "distribution": "agent-and-human",
+      "phases": [
+        "*"
+      ],
+      "workflows": [
+        "operational-stabilization"
+      ]
     },
     {
       "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": [
         "*"
+      ],
+      "workflows": [
+        "product-change"
       ]
     }
   ]

package/package.json

@@ -1,62 +1,71 @@
 {
   "name": "ahead-pi",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "AHEAD workflow enforcement and context for Pi",
+  "keywords": [
+    "ahead",
+    "human-in-the-loop",
+    "pi-package"
+  ],
+  "homepage": "https://github.com/Kade-Powell/ahead/tree/main/integrations/pi#readme",
+  "bugs": {
+    "url": "https://github.com/Kade-Powell/ahead/issues"
+  },
   "license": "MIT",
-  "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Kade-Powell/ahead.git",
     "directory": "integrations/pi"
   },
-  "homepage": "https://github.com/Kade-Powell/ahead/tree/main/integrations/pi#readme",
-  "bugs": {
-    "url": "https://github.com/Kade-Powell/ahead/issues"
-  },
-  "engines": {
-    "node": ">=22.19.0"
-  },
   "files": [
     "dist/ahead_wasm.wasm",
     "generated/",
     "src/"
   ],
+  "type": "module",
   "publishConfig": {
     "access": "public",
     "provenance": true,
     "registry": "https://registry.npmjs.org/"
   },
-  "keywords": [
-    "pi-package",
-    "ahead",
-    "human-in-the-loop"
-  ],
-  "pi": {
-    "extensions": [
-      "./src/index.ts"
-    ]
-  },
   "scripts": {
     "build": "npm run build:instructions && npm run build:wasm && npm run typecheck",
     "build:instructions": "node ../../scripts/build-instructions.mjs",
     "build:wasm": "node ./scripts/build-wasm.mjs",
+    "format": "cd ../.. && integrations/pi/node_modules/.bin/oxfmt -c ./.oxfmtrc.json .oxfmtrc.json .oxlintrc.json scripts integrations/pi/scripts integrations/pi/src integrations/pi/test integrations/pi/package.json integrations/pi/tsconfig.json",
+    "format:check": "npm run format -- --check",
+    "lint": "npm run lint:source && npm run lint:types",
+    "lint:source": "cd ../.. && integrations/pi/node_modules/.bin/oxlint -c ./.oxlintrc.json --report-unused-disable-directives-severity=off scripts integrations/pi/scripts integrations/pi/src integrations/pi/test",
+    "lint:types": "cd ../.. && integrations/pi/node_modules/.bin/oxlint -c ./.oxlintrc.json --type-aware --tsconfig integrations/pi/tsconfig.json integrations/pi/src",
     "prepack": "npm run build",
     "prepublishOnly": "npm run verify",
     "pack:verify": "node ./scripts/verify-package.mjs",
+    "quality": "npm run format:check && npm run lint && npm run typecheck",
     "typecheck": "tsc --noEmit",
-    "verify": "npm run build && node --test ./test/*.test.mjs",
+    "verify": "npm run build && npm run format:check && npm run lint && node --test ./test/*.test.mjs",
     "test": "npm run verify && npm run pack:verify"
   },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
-    "typebox": "*"
-  },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.1",
     "@earendil-works/pi-tui": "^0.84.1",
     "@types/node": "24.12.4",
+    "oxfmt": "^0.63.0",
+    "oxlint": "^1.78.0",
+    "oxlint-tsgolint": "^7.0.2001",
     "typebox": "1.1.38",
     "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
   }
 }

package/src/engine.ts

@@ -40,11 +40,9 @@ export class AheadEngine {
   static async load(path: string): Promise<AheadEngine> {
     const bytes = await readFile(path);
     const instantiated = await WebAssembly.instantiate(bytes, {});
-    const wasm = instantiated.instance.exports as WasmExports;
-    for (const name of ["memory", "ahead_alloc", "ahead_dealloc", "ahead_dispatch"]) {
-      if (!(name in wasm)) {
-        throw new Error(`AHEAD WebAssembly module is missing export: ${name}`);
-      }
+    const wasm = instantiated.instance.exports;
+    if (!isWasmExports(wasm)) {
+      throw new Error("AHEAD WebAssembly module does not expose the required engine ABI");
     }
     return new AheadEngine(wasm);
   }
@@ -53,12 +51,16 @@ export class AheadEngine {
     return this.call("get_workflow", { workflow_id: workflowId });
   }
 
+  listWorkflows(): WorkflowDefinition[] {
+    return this.call("list_workflows", {});
+  }
+
   createRun(input: {
     id: string;
     title: string;
     owner: Actor;
     timestamp: string;
-    workflow_id?: string;
+    workflow_id: string;
   }): Run {
     return this.call("create_run", input);
   }
@@ -78,10 +80,14 @@ export class AheadEngine {
     });
   }
 
-  toolAllowed(run: Run, capability: Capability): { allowed: boolean; reason: string; capability: Capability } {
+  toolAllowed(
+    run: Run,
+    capability: Capability,
+  ): { allowed: boolean; reason: string; capability: Capability } {
     return this.call("tool_allowed", { run, capability });
   }
 
+  // oxlint-disable-next-line typescript/no-unnecessary-type-parameters -- the operation selects the Rust response type
   private call<T>(operation: string, input: unknown): T {
     const request = new TextEncoder().encode(
       JSON.stringify({ api_version: ENGINE_API_VERSION, operation, input }),
@@ -96,9 +102,13 @@ export class AheadEngine {
       outputPointer = Number(packed >> 32n);
       outputLength = Number(packed & 0xffff_ffffn);
       const output = new Uint8Array(this.wasm.memory.buffer, outputPointer, outputLength).slice();
+      // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the versioned Rust ABI owns this response envelope
       const response = JSON.parse(new TextDecoder().decode(output)) as EngineResponse<T>;
       if (!response.ok || response.result === undefined) {
-        const error = response.error ?? { code: "unknown_engine_error", message: "AHEAD engine call failed" };
+        const error = response.error ?? {
+          code: "unknown_engine_error",
+          message: "AHEAD engine call failed",
+        };
         throw new AheadEngineError(error.code, error.message);
       }
       return response.result;
@@ -110,3 +120,12 @@ export class AheadEngine {
     }
   }
 }
+
+function isWasmExports(exports: WebAssembly.Exports): exports is WasmExports {
+  return (
+    exports.memory instanceof WebAssembly.Memory &&
+    typeof exports.ahead_alloc === "function" &&
+    typeof exports.ahead_dealloc === "function" &&
+    typeof exports.ahead_dispatch === "function"
+  );
+}