ahead-pi 0.3.0 → 0.3.1

package/README.md

@@ -1,5 +1,7 @@
 # AHEAD for Pi
 
+Audience: AHEAD practitioners
+
 Status: guided-mode dogfood v0.3
 
 The Pi integration runs the Rust AHEAD state machine as WebAssembly, injects generated phase instructions into any Pi model, persists the event/evidence chain, and presents AHEAD as a guided mode with human-owned gates.
@@ -17,7 +19,7 @@ pi install npm:ahead-pi
 Pin an exact version for a team or project:
 
 ```sh
-pi install -l npm:ahead-pi@0.3.0
+pi install -l npm:ahead-pi@0.3.1
 ```
 
 Or try it for one session without changing settings:
@@ -26,40 +28,17 @@ Or try it for one session without changing settings:
 pi -e npm:ahead-pi
 ```
 
-## Build from this repository
-
-Requirements: Rust with `wasm32-unknown-unknown`, Node 22 or newer, npm, and Pi 0.84.1 or a compatible release.
-
-```sh
-cd integrations/pi
-npm install
-npm run build
-```
-
-For a quick source-checkout dogfood run from the repository root:
-
-```sh
-pi --no-extensions -e ./integrations/pi/src/index.ts
-```
-
-Or install the package into the current project through Pi:
-
-```sh
-pi install -l ./integrations/pi
-pi
-```
-
-Pi may ask you to trust the project-local extension. Review it before accepting; project trust is not a sandbox.
-
 ## Guided mode
 
 1. Start Pi in the repository where the engineering work will occur.
-2. Run `/ahead <short title>` once, choose the workflow that fits the dominant outcome, and enter AHEAD mode. Advanced noninteractive use may pass `/ahead-start <workflow-id> :: <title>`.
-3. Work through normal conversation. The persistent widget shows the current goal, what the human owns, what AI may do, required evidence, and the next valid action.
-4. Run `/ahead` again whenever you want the contextual action menu. It opens the right guided editor, requests the right AI contribution, accepts and advances a human gate, returns to an earlier phase, or opens applicable framework guidance.
+2. Run `/ahead <short title>` once, explicitly choose the workflow that fits the dominant outcome, and enter AHEAD mode. A new run never defaults to Product Change. Advanced noninteractive use must pass `/ahead-start <workflow-id> :: <title>`.
+3. Work through normal conversation. A compact header above the chat shows the phase goal, required evidence, and whether the human or AI owns the next action. The full human/AI boundary continues to govern every model turn without occupying the conversation.
+4. Run `/ahead` again only when you want the contextual action menu. It opens the right guided editor, requests the right AI contribution, accepts and advances a human gate, returns to an earlier phase, or opens applicable framework guidance.
 5. Keep the `.ahead` records with the work so another session or independent reviewer resumes the same authoritative run.
 
-AHEAD remains active across Pi sessions until an accountable human completes the outcome phase and closes the run. Restarting Pi does not leave the mode or reset the workflow.
+AHEAD remains active across Pi sessions until an accountable human completes the outcome phase or runs `/ahead-stop`. Restarting Pi does not leave the mode or reset the workflow.
+
+`/ahead-stop` defaults to discarding the unfinished AHEAD run record and its `.ahead` artifacts; it never deletes, resets, or reverts source code or other repository changes. The human may instead explicitly save the run for later. `/ahead-resume` restores that exact workflow, phase, evidence, and unmet gates.
 
 During implementation, the engineer can ask questions at any time. The guided help form captures the engineer's current model and first attempt, then asks AI for explanation, evidence, hints, debugging help, or bounded next steps without handing over human ownership. Normal conversation follows the same rule. A bounded mechanical edit still requires clear human intent and later human inspection and understanding.
 
@@ -69,7 +48,7 @@ Run `/ahead-skills` to inspect optional third-party skills AHEAD has reviewed fo
 
 AHEAD behaves as a dynamic policy profile layered onto whichever model Pi is already using. Every model turn receives a compact binding agent profile, the active phase contract, current workflow state, and human/AI boundary. The full framework is not injected into every prompt.
 
-All repository framework Markdown is copied into the published package at build time and indexed for on-demand use. Run `/ahead-guide` to read references applicable to the active phase, `/ahead-guide all` to browse the complete packaged set, or `/ahead-guide <topic>` to open a specific document. AI uses `ahead_get_reference` when it needs the same source material. This preserves traceability without filling the context window with unrelated documents.
+The Constitution, practitioner guide, and evidence library are copied into the published package at build time and indexed with audience and authority metadata. Maintainer and tooling-development documents are excluded. Run `/ahead-guide` to read practitioner references applicable to the active phase, `/ahead-guide all` to browse the complete runtime set, or `/ahead-guide <topic>` to open a specific document. AI uses `ahead_get_reference` when it needs the same source material. This preserves traceability without filling the context window with unrelated documents.
 
 The normal implementation handoff is:
 
@@ -93,10 +72,12 @@ A draft branch or draft PR may exist earlier. The handoff gate is requesting hum
 
 | Command | Effect |
 |---|---|
-| `/ahead [title]` | Choose a workflow for new work, or resume and perform the next guided AHEAD action |
+| `/ahead [title]` | Choose a workflow for new work, or open the active workflow's action menu |
 | `/ahead-guide [topic]` | Read phase-relevant or requested AHEAD Markdown |
 | `/ahead-skills` | Inspect optional skills reviewed for the active phase; never installs them |
 | `/ahead-review` | Inspect the exact diff and complete the AI-to-human 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 was explicitly saved |
 | `/ahead-help` | Show commands and authority boundaries |
 
 `/ahead-start`, `/ahead-status`, `/ahead-record`, `/ahead-accept`, `/ahead-advance`, and `/ahead-return` remain available as advanced recovery and inspection commands. Normal use should not require memorizing them.
@@ -129,14 +110,8 @@ Human identity is resolved from `AHEAD_HUMAN_IDENTITY`, Git `user.email`, Git `u
 AHEAD_HUMAN_IDENTITY=reviewer@example.com pi -e ./integrations/pi/src/index.ts
 ```
 
-This is local self-attestation, not cryptographic identity. The initial version is single-writer, implements all six pilot workflows, and has no GitHub/CI workflow enforcement yet. v0.3 binds local review records to a SHA-256 fingerprint of the selected base, merge base, HEAD, tracked diff, working-tree status, and untracked-file hashes. That fingerprint is not signed or remotely attested; a changed changeset must be reviewed again. See [Executable AHEAD workflows](https://github.com/Kade-Powell/ahead/blob/main/docs/design/executable-workflows.md) for the architecture and trust boundaries.
-
-## Package and release verification
-
-`npm test` builds the Rust core for `wasm32-unknown-unknown`, regenerates instructions, checks formatting with Oxfmt, runs Oxlint source and type-aware analysis, runs TypeScript checking and the Rust/WASM-facing and guided-mode tests, creates the exact npm tarball, verifies its allowlisted contents, loads the extracted package through the real Pi binary, and confirms that the packaged extension persists a valid run.
-
-Use `npm run format`, `npm run format:check`, `npm run lint`, and `npm run typecheck` for individual JavaScript and TypeScript quality gates. Oxc configuration is repository-wide so the root generators and Pi integration follow the same policy.
+This is local self-attestation, not cryptographic identity. The initial version is single-writer, implements all six pilot workflows, and has no GitHub/CI workflow enforcement yet. v0.3 binds local review records to a SHA-256 fingerprint of the selected base, merge base, HEAD, tracked diff, working-tree status, and untracked-file hashes. That fingerprint is not signed or remotely attested; a changed changeset must be reviewed again.
 
-The npm package contains only its README, package metadata, TypeScript runtime, generated phase instructions, and compiled WASM engine. Build scripts, tests, source specs, development dependencies, and repository files are excluded.
+## Contributing
 
-See [Releasing the Pi extension](https://github.com/Kade-Powell/ahead/blob/main/docs/releasing-pi.md) for versioning, first-publish authentication, trusted publishing, and rollback rules.
+Source builds, architecture, package verification, and release procedures are maintained separately in the [AHEAD development guide](https://github.com/Kade-Powell/ahead/blob/main/docs/development/README.md).

package/generated/reference/CONSTITUTION.md

@@ -1,5 +1,7 @@
 # AHEAD Constitution
 
+Audience: AHEAD practitioners and framework maintainers
+
 This constitution records the durable principles of **Assisted Human Engineering and Development**. Workflows and tools may evolve. These principles define what makes them AHEAD.
 
 ## 1. Human ownership

package/generated/reference/docs/evidence/README.md

@@ -0,0 +1,17 @@
+# AHEAD Evidence and Provenance
+
+Audience: AHEAD evidence readers and framework maintainers
+
+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 engineering work.
+
+## Evidence governance
+
+- [Evidence standard](evidence-standard.md) defines evidence classes, applicability, limitations, and revision expectations.
+- [Research map](research-map.md) maps important AHEAD claims to current research, standards, established practice, and open hypotheses.
+
+## Preserved source notes
+
+- [Pragmatic Programmer page index](sources/pragmatic-programmer-page-index.md) preserves edition-specific page locators.
+- [Submitted engineering notes](sources/submitted-engineering-notes.md) preserves the original tips and checklists behind the distilled practitioner guidance.
+
+Practitioners may consult this material when they need the basis or limitation of a rule. Framework maintainers use it when proposing, evaluating, or revising AHEAD policy.

package/generated/reference/docs/evidence/evidence-standard.md

@@ -1,5 +1,7 @@
 # AHEAD Evidence Standard
 
+Audience: AHEAD evidence readers and framework maintainers
+
 Status: proposed
 
 ## Purpose

package/generated/reference/docs/evidence/research-map.md

@@ -1,5 +1,7 @@
 # AHEAD Research Map
 
+Audience: AHEAD evidence readers and framework maintainers
+
 Status: living evidence review
 Last reviewed: 2026-08-12
 

package/generated/reference/docs/{references → evidence/sources}/pragmatic-programmer-page-index.md

@@ -1,5 +1,7 @@
 # *The Pragmatic Programmer* Page Index
 
+Audience: AHEAD evidence readers and framework maintainers
+
 Status: submitted source notes
 
 ## Edition and use
@@ -8,7 +10,7 @@ This index preserves the page-level provenance from the original AHEAD engineeri
 
 > David Thomas and Andrew Hunt, *The Pragmatic Programmer: Your Journey to Mastery*, 20th Anniversary Edition, ISBN 9780135957059.
 
-Page numbers are edition-specific and may not match an ebook or another printing. The titles and locators below are the submitter's reading notes, retained so AHEAD's distilled guidance remains traceable. They are not presented as scientific evidence; the [research map](../evidence/research-map.md) separately records empirical support.
+Page numbers are edition-specific and may not match an ebook or another printing. The titles and locators below are the submitter's reading notes, retained so AHEAD's distilled guidance remains traceable. They are not presented as scientific evidence; the [research map](../research-map.md) separately records empirical support.
 
 Two submitted locators look like transcription errors but are intentionally preserved pending a check against the physical edition:
 

package/generated/reference/docs/{references → evidence/sources}/submitted-engineering-notes.md

@@ -1,10 +1,12 @@
 # Submitted Engineering Notes
 
+Audience: AHEAD evidence readers and framework maintainers
+
 Status: submitted source notes
 
 ## Purpose and provenance
 
-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 experimentally validated rule.
+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 item is an experimentally validated rule.
 
 Tips 1–70 and their submitted page locators from *The Pragmatic Programmer* are retained in the [edition-specific page index](pragmatic-programmer-page-index.md). Their accompanying submitted meanings are retained below, followed by the additional tips and the full submitted checklist and practice content. The submitted language-learning list is intentionally omitted.
 

package/generated/reference/docs/guide/README.md

@@ -0,0 +1,28 @@
+# AHEAD Practitioner Guide
+
+Audience: AHEAD practitioners
+
+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 generator, or release process is implemented.
+
+## Start here
+
+1. [Why AHEAD](rationale.md) explains the philosophy and intended human–AI relationship.
+2. [AHEAD Constitution](../../CONSTITUTION.md) defines the durable, non-negotiable principles.
+3. [Acceptable AI use](acceptable-ai-use.md) defines binding authority boundaries.
+4. [Engineering practice](engineering-practice.md) describes the habits AHEAD asks engineers to cultivate.
+5. [Pilot workflows](workflows/README.md) explains how to choose and execute one of the six flows.
+6. [Recommended skills](recommended-skills.md) lists optional, reviewed third-party aids.
+
+## Authority
+
+The Constitution, Acceptable AI Use policy, and active workflow contract are binding during an AHEAD pilot. The rationale explains why those rules exist. Engineering Practice is proposed guidance, and recommended skills are optional. Organization and repository rules may narrow AI authority but cannot broaden it beyond AHEAD policy.
+
+## When you need the basis for a rule
+
+Use the [evidence library](../evidence/README.md) for research, limitations, and original source notes. Evidence documents support and challenge the framework; they are not additional workflow steps unless a workflow explicitly requires them.
+
+## Tooling
+
+[AHEAD for Pi](https://github.com/Kade-Powell/ahead/tree/main/integrations/pi) explains installation, guided mode, commands, review handoff, identity, and current pilot limitations. Implementation architecture and release procedures belong in the repository's [development guide](https://github.com/Kade-Powell/ahead/blob/main/docs/development/README.md), which is intentionally not packaged as runtime guidance.
+
+Stopping AHEAD does not imply completion. An integration should discard unfinished workflow records by default without touching engineering work, retain them only when the human explicitly chooses to save, and resume saved work at the same phase and gates.

package/generated/reference/docs/{acceptable-ai-use.md → guide/acceptable-ai-use.md}

@@ -1,10 +1,12 @@
 # Acceptable AI Use in AHEAD
 
+Audience: AHEAD practitioners
+
 Status: binding pilot policy v0.1
 
 ## Authority
 
-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 phase. A workflow phase, diagram, tool permission, or local convenience cannot broaden AI authority beyond this policy. Organization and repository policies may impose stricter controls.
+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 phase. A workflow phase, diagram, tool permission, or local convenience cannot broaden AI authority beyond this policy. Organization and repository policies may impose stricter controls.
 
 If two rules appear to conflict, apply the more protective rule and record the ambiguity for correction. No exception may transfer human authorship, judgment, approval, accountability, or unscoped consequential authority to AI.
 
@@ -214,4 +216,4 @@ For a disposable prototype, also answer:
 - [NIST DevSecOps reference model: Artificial Intelligence](https://pages.nist.gov/nccoe-devsecops/notational-reference-model.html#artificial-intelligence) — human validation and verifiable-process guidance for AI-augmented software development.
 - [OWASP Secure Coding with AI Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secure_Coding_with_AI_Cheat_Sheet.html) — practitioner security guidance for sensitive context, agent permissions, generated tests, supply chains, and CI/CD.
 
-The [research map](evidence/research-map.md) classifies these sources and records their limitations. Exact boundaries such as “core business logic” and the human-first debugging checkpoint remain AHEAD policy choices that should be tested and refined.
+The [research map](../evidence/research-map.md) classifies these sources and records their limitations. Exact boundaries such as “core business logic” and the human-first debugging checkpoint remain AHEAD policy choices that should be tested and refined.

package/generated/reference/docs/{engineering-practice.md → guide/engineering-practice.md}

@@ -1,5 +1,7 @@
 # AHEAD Engineering Practice
 
+Audience: AHEAD practitioners
+
 Status: proposed guidance
 
 ## Purpose
@@ -8,7 +10,7 @@ AHEAD is not only a sequence of AI gates. It is a way of practicing engineering.
 
 Many of these ideas come from practitioner literature rather than controlled experiments. The source type matters: a useful craft principle can guide work without being misrepresented as science.
 
-The submitted notes include page-level references to *The Pragmatic Programmer*. Those locators are preserved in the [edition-specific page index](references/pragmatic-programmer-page-index.md) and grouped below so the distillation remains traceable to its source. Additional submitted tips, complete checklists, and practices are retained in the [submitted engineering notes](references/submitted-engineering-notes.md); the practice guide condenses them without replacing that source record.
+The submitted notes include page-level references to *The Pragmatic Programmer*. Those locators are preserved in the [edition-specific page index](../evidence/sources/pragmatic-programmer-page-index.md) and grouped below so the distillation remains traceable to its source. Additional submitted tips, complete checklists, and practices are retained in the [submitted engineering notes](../evidence/sources/submitted-engineering-notes.md); the practice guide condenses them without replacing that source record.
 
 ## 1. Care about the craft and own the result
 
@@ -142,7 +144,7 @@ Before merge or delivery:
 These are recommended practitioner sources, not scientific proof of AHEAD:
 
 - David Thomas and Andrew Hunt, [*The Pragmatic Programmer: Your Journey to Mastery*, 20th Anniversary Edition](https://pragprog.com/titles/tpp20/the-pragmatic-programmer-20th-anniversary-edition/), ISBN 9780135957059.
-  - AHEAD preserves the submitted print-page locators in its [Pragmatic Programmer page index](references/pragmatic-programmer-page-index.md).
+  - AHEAD preserves the submitted print-page locators in its [Pragmatic Programmer page index](../evidence/sources/pragmatic-programmer-page-index.md).
 - Luca Palmieri, [*Zero To Production In Rust*](https://www.zero2prod.com/), ISBN 9798847211437. This is a concrete production-backend learning path rather than a general philosophy source.
 - Richard Hamming, [*The Art of Doing Science and Engineering: Learning to Learn*](https://press.stripe.com/the-art-of-doing-science-and-engineering), ISBN 9781732265172.
 - Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
@@ -160,4 +162,4 @@ These are recommended practitioner sources, not scientific proof of AHEAD:
 - [Becker et al., *Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity*](https://arxiv.org/abs/2507.09089)
 - [Bjarnason, Lang, and Mjöberg, *An empirically based model of software prototyping*](https://doi.org/10.1007/s10664-023-10331-w)
 
-Detailed applicability and limitations belong in the [AHEAD research map](evidence/research-map.md).
+Detailed applicability and limitations belong in the [AHEAD research map](../evidence/research-map.md).

package/generated/reference/docs/{rationale.md → guide/rationale.md}

@@ -1,5 +1,7 @@
 # Why AHEAD
 
+Audience: AHEAD practitioners
+
 ## Human-led engineering, amplified by AI
 
 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.
@@ -207,4 +209,4 @@ AHEAD is evidence-informed; it is not yet an experimentally validated methodolog
 
 The existing evidence also resists simplistic claims about AI. A randomized field study across 4,867 developers found increased completed tasks with access to an AI coding assistant, while a smaller randomized study of experienced open-source developers working in familiar repositories found that the available AI tools increased completion time. The responsible conclusion is that AI's effect depends on the people, task, system, tool, and outcome being measured—not that AI is inherently productive or unproductive.
 
-AHEAD will maintain a [research map](evidence/research-map.md) that records the evidence and limitations behind each important process choice. Its [evidence standard](evidence/evidence-standard.md) defines how claims are classified and how the methodology should be revised when better evidence appears.
+AHEAD will maintain a [research map](../evidence/research-map.md) that records the evidence and limitations behind each important process choice. Its [evidence standard](../evidence/evidence-standard.md) defines how claims are classified and how the methodology should be revised when better evidence appears.

package/generated/reference/docs/{recommended-skills.md → guide/recommended-skills.md}

@@ -1,5 +1,7 @@
 # Recommended Skills
 
+Audience: AHEAD practitioners
+
 Status: reviewed catalog v0.1
 
 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 workflow, authority boundaries, and gates remain controlling.

package/generated/reference/docs/{workflows → guide/workflows}/README.md

@@ -1,5 +1,7 @@
 # AHEAD Pilot Workflows
 
+Audience: AHEAD practitioners
+
 Status: executable dogfood v0.1
 
 ## Purpose
@@ -21,7 +23,7 @@ Choose the flow by its dominant outcome, not by the issue label. Incident, emerg
 
 The pilot applies rules in this order:
 
-1. [AHEAD Constitution](../../CONSTITUTION.md)
+1. [AHEAD Constitution](../../../CONSTITUTION.md)
 2. [Acceptable AI Use](../acceptable-ai-use.md)
 3. The selected workflow profile and applicable overlays
 4. Organization and repository guidance, which may narrow but not broaden AI authority

package/generated/reference/docs/{workflows → guide/workflows}/corrective-debugging.md

@@ -1,5 +1,7 @@
 # Corrective Debugging Workflow
 
+Audience: AHEAD practitioners
+
 Status: pilot v0.1
 
 ## Outcome

package/generated/reference/docs/{workflows → guide/workflows}/decision.md

@@ -1,5 +1,7 @@
 # Decision Workflow
 
+Audience: AHEAD practitioners
+
 Status: pilot v0.1
 
 ## Outcome

package/generated/reference/docs/{workflows → guide/workflows}/internal-improvement.md

@@ -1,5 +1,7 @@
 # Internal Improvement Workflow
 
+Audience: AHEAD practitioners
+
 Status: pilot v0.1
 
 ## Outcome

package/generated/reference/docs/{workflows → guide/workflows}/investigation.md

@@ -1,5 +1,7 @@
 # Investigation Workflow
 
+Audience: AHEAD practitioners
+
 Status: pilot v0.1
 
 ## Outcome

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

@@ -1,5 +1,7 @@
 # Operational Stabilization Workflow
 
+Audience: AHEAD practitioners
+
 Status: pilot v0.1
 
 ## Outcome

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

@@ -1,5 +1,7 @@
 # Product Change Workflow
 
+Audience: AHEAD practitioners
+
 Status: pilot v0.1
 
 ## Outcome