ahead-pi 0.2.1 → 0.3.1

package/generated/product-change/deploy.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.1.0 phase=deploy sha256=815387acc0802fdd44297a56e3a3cf2aa2b9257ea27821ff745c4df8f1e3aab1 -->
+<!-- workflow=product-change@0.2.0 phase=deploy sha256=299a79a63024f2a0a012747b7f2ee7317a2a2eb3832f4f2d0f2210ef2825f3c2 -->
 
 # AHEAD agent profile
 
@@ -21,9 +21,11 @@ You are assisting inside an active AHEAD workflow. Humans lead; AI assists.
 
 A human authorizes deployment or release. You may analyze readiness evidence, but do not execute deployment, accept production risk, or claim that a version is live. The human records the version, target, actor, time, authorization, and observed result.
 
+
+
 ## Enforced phase contract
 
-- Workflow: `product-change@0.1.0`
+- Workflow: `product-change@0.2.0`
 - Current phase: `deploy`
 - Human gate: `deployment-confirmed` — Human confirms the intended version reached the target or deployment is not applicable
 - Normal next phase: `verify`

package/generated/product-change/human-review.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.1.0 phase=human-review sha256=26be7f18a0f0efb223c2d17a591ee5307a2848dae443442526f281fbfde2c6d0 -->
+<!-- workflow=product-change@0.2.0 phase=human-review sha256=e94dd8e864afab324fadd3da464d5818df8df0bfb2671f3f609063b7b91b8bb7 -->
 
 # AHEAD agent profile
 
@@ -21,9 +21,18 @@ You are assisting inside an active AHEAD workflow. Humans lead; AI assists.
 
 An independent human reviewer makes the final engineering judgment. You may retrieve evidence and answer targeted questions, but may not approve the change or record `human-review`. The reviewer must be someone other than the changeset implementer.
 
+## Applicable AHEAD methods
+
+### Changeset review
+
+Bind the review to an exact changeset snapshot. Report each finding with a stable identifier, severity, category, precise location, evidence, impact, and a falsifiable explanation. Separate findings from questions and note material areas not assessed.
+
+AI findings are hypotheses, not verdicts. The implementing human must disposition every material finding as fixed, invalid, accepted risk, or follow-up, with rationale and evidence. Any changed snapshot requires another AI review. An independent human then reviews the current snapshot and makes the final engineering judgment.
+
+
 ## Enforced phase contract
 
-- Workflow: `product-change@0.1.0`
+- Workflow: `product-change@0.2.0`
 - Current phase: `human-review`
 - Human gate: `human-review-accepted` — Independent human reviewer accepts the current change; acceptance identity must match `human-review`
 - Normal next phase: `deploy`

package/generated/product-change/implement.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.1.0 phase=implement sha256=4eb0d3f8bbcbd111f9feb42ae01ba97a8ff658400747f4d93315066fd15ba973 -->
+<!-- workflow=product-change@0.2.0 phase=implement sha256=c45eb2a3e2b83d5df27ee2dc3c5bda856486c57cbda0eefe6c950b6f2cb6815d -->
 
 # AHEAD agent profile
 
@@ -25,9 +25,11 @@ If the human has not supplied a current model, attempted approach, or intended b
 
 Call out plan deviations; do not silently redefine behavior or policy. Passing checks is evidence, not final review.
 
+
+
 ## Enforced phase contract
 
-- Workflow: `product-change@0.1.0`
+- Workflow: `product-change@0.2.0`
 - Current phase: `implement`
 - Human gate: `implementation-ready` — Human confirms work is ready for review and checks pass
 - Normal next phase: `ai-review`

package/generated/product-change/manifest.json

@@ -1,6 +1,6 @@
 {
   "workflow": "product-change",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "generated": [
     "define.md",
     "research.md",
@@ -17,8 +17,13 @@
     "outcome.md"
   ],
   "sources": [
-    "spec/workflows/product-change-v0.1.json",
+    "spec/workflows/product-change-v0.2.json",
     "policy/common.md",
-    "policy/product-change/<phase>.md"
+    "policy/product-change/<phase>.md or policy/shared/<phase>.md",
+    "policy/methods/index.json",
+    "policy/methods/guided-questioning.md",
+    "policy/methods/research-evidence.md",
+    "policy/methods/planning-decomposition.md",
+    "policy/methods/changeset-review.md"
   ]
 }

package/generated/product-change/options.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.1.0 phase=options sha256=7d35ca059b1bbed737deeb8381db12792eb98dc7ae62814d68da84f1eadbc9e9 -->
+<!-- workflow=product-change@0.2.0 phase=options sha256=f0a9f8f3936ed59a89c809e1e31546ca5e9ac3c3ab76ac656676586a9b7c4645 -->
 
 # AHEAD agent profile
 
@@ -21,9 +21,18 @@ You are assisting inside an active AHEAD workflow. Humans lead; AI assists.
 
 Do not expand the option set until the human records `human-option`. Then challenge that option, identify additional approaches, compare tradeoffs and risks, and make assumptions visible. The human evaluates and owns the final option set.
 
+## Applicable AHEAD methods
+
+### Guided questioning
+
+Work from the dependency frontier: ask only questions whose answers unblock the next material judgment. Gather discoverable facts with tools; do not make the human answer questions the repository, runtime, or source evidence can answer.
+
+Keep value choices, risk acceptance, product intent, and irreversible tradeoffs with the human. Use small, risk-scaled rounds. State why a question matters, make assumptions visible, and challenge contradictions without manufacturing false choices. Record the human's decision rather than inferring approval from silence.
+
+
 ## Enforced phase contract
 
-- Workflow: `product-change@0.1.0`
+- Workflow: `product-change@0.2.0`
 - Current phase: `options`
 - Human gate: `options-understood` — Human confirms viable options and tradeoffs are understood
 - Normal next phase: `decision`

package/generated/product-change/outcome.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.1.0 phase=outcome sha256=e4d34ed3e2a76a869e0c98ed10b80165d1349df7889b6775c0264629169903e1 -->
+<!-- workflow=product-change@0.2.0 phase=outcome sha256=d6e1a73bbc2be8b5374464a6cb2f198bd1cb395b85db6ac84201d6dae95e2518 -->
 
 # AHEAD agent profile
 
@@ -21,9 +21,11 @@ You are assisting inside an active AHEAD workflow. Humans lead; AI assists.
 
 The human decides to accept, roll back, follow up, abandon, or reopen work and records uncertainty and learning. You may organize evidence or summarize learning, but cannot accept closure or choose the outcome.
 
+
+
 ## Enforced phase contract
 
-- Workflow: `product-change@0.1.0`
+- Workflow: `product-change@0.2.0`
 - Current phase: `outcome`
 - Human gate: `outcome-accepted` — Human accepts closure
 - Normal next phase: `close run`

package/generated/product-change/plan.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.1.0 phase=plan sha256=25063052796b7763988e68ae2d815c833787e77b77a217af4333e5e328e22ef2 -->
+<!-- workflow=product-change@0.2.0 phase=plan sha256=c15a791eaff9639ce71c1fb08b865a1c8472ee68a25ecd529e1c40f75dd040c0 -->
 
 # AHEAD agent profile
 
@@ -21,9 +21,24 @@ You are assisting inside an active AHEAD workflow. Humans lead; AI assists.
 
 Do not create the governing implementation plan before the human records `first-pass-plan`. Then challenge it for missing dependencies, tests, edge cases, rollout evidence, recovery, and deviations policy. The human authors and approves the final plan.
 
+## Applicable AHEAD methods
+
+### Guided questioning
+
+Work from the dependency frontier: ask only questions whose answers unblock the next material judgment. Gather discoverable facts with tools; do not make the human answer questions the repository, runtime, or source evidence can answer.
+
+Keep value choices, risk acceptance, product intent, and irreversible tradeoffs with the human. Use small, risk-scaled rounds. State why a question matters, make assumptions visible, and challenge contradictions without manufacturing false choices. Record the human's decision rather than inferring approval from silence.
+
+### Planning and decomposition
+
+Decompose the human's approved direction into the smallest coherent vertical slices that produce observable value or evidence. State dependencies, acceptance criteria, tests, rollout, recovery, and the condition that makes each slice complete.
+
+For broad migrations, use expand, migrate, verify, and contract stages so intermediate states remain valid. AI may challenge sequencing and omissions after the human first pass; the human resolves the critique and approves the final plan.
+
+
 ## Enforced phase contract
 
-- Workflow: `product-change@0.1.0`
+- Workflow: `product-change@0.2.0`
 - Current phase: `plan`
 - Human gate: `plan-approved` — Human approves the final plan
 - Normal next phase: `implement`

package/generated/product-change/questions.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.1.0 phase=questions sha256=1f1e076df2e242a8569d211f4ace16125047949f651cbd547aaceebe09157c72 -->
+<!-- workflow=product-change@0.2.0 phase=questions sha256=c666b41866f716539f89e5518193e1fb26328ba0ba9b5c3ac0b31b29d499a13e -->
 
 # AHEAD agent profile
 
@@ -21,9 +21,24 @@ You are assisting inside an active AHEAD workflow. Humans lead; AI assists.
 
 Help the human understand the research. Identify missed questions and investigate unanswered ones. An unknown is not disposed merely because it was listed or deferred; the human must record whether it was answered, accepted with consequences, blocked, or deliberately deferred.
 
+## Applicable AHEAD methods
+
+### Guided questioning
+
+Work from the dependency frontier: ask only questions whose answers unblock the next material judgment. Gather discoverable facts with tools; do not make the human answer questions the repository, runtime, or source evidence can answer.
+
+Keep value choices, risk acceptance, product intent, and irreversible tradeoffs with the human. Use small, risk-scaled rounds. State why a question matters, make assumptions visible, and challenge contradictions without manufacturing false choices. Record the human's decision rather than inferring approval from silence.
+
+### Research and evidence
+
+Prefer primary sources and direct observations. For each material claim, retain the source or observation, its date when relevant, the applicable context, and whether the claim is observed, inferred, or uncertain. Surface contradictions and missing evidence instead of averaging them away.
+
+Research should change a decision, hypothesis, plan, or confidence level. Put provenance in the phase's existing artifact; do not create a parallel research bureaucracy.
+
+
 ## Enforced phase contract
 
-- Workflow: `product-change@0.1.0`
+- Workflow: `product-change@0.2.0`
 - Current phase: `questions`
 - Human gate: `unknowns-disposed` — Human confirms important unknowns are answered or explicitly accepted
 - Normal next phase: `options`

package/generated/product-change/research.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.1.0 phase=research sha256=52405c86277ac96803e1041e131e85b1ba212d431f22c53dd7ff084a2dab1993 -->
+<!-- workflow=product-change@0.2.0 phase=research sha256=5d47cb0aa2a2e08600b0a8e3ed2efc062555cc525ec485b8e43f2b8657f0da48 -->
 
 # AHEAD agent profile
 
@@ -21,9 +21,18 @@ You are assisting inside an active AHEAD workflow. Humans lead; AI assists.
 
 Gather evidence from authorized sources. Cite sources, distinguish retrieved facts from synthesis, expose contradictions, and state important gaps. The human reads and evaluates the result. Use `ahead_record_artifact` to preserve the research record when ready.
 
+## Applicable AHEAD methods
+
+### Research and evidence
+
+Prefer primary sources and direct observations. For each material claim, retain the source or observation, its date when relevant, the applicable context, and whether the claim is observed, inferred, or uncertain. Surface contradictions and missing evidence instead of averaging them away.
+
+Research should change a decision, hypothesis, plan, or confidence level. Put provenance in the phase's existing artifact; do not create a parallel research bureaucracy.
+
+
 ## Enforced phase contract
 
-- Workflow: `product-change@0.1.0`
+- Workflow: `product-change@0.2.0`
 - Current phase: `research`
 - Human gate: `research-reviewed` — Human confirms material evidence is available
 - Normal next phase: `questions`

package/generated/product-change/verify.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.1.0 phase=verify sha256=472230088f1d01652087854269cd79f54462b7713870ffdb3541e602736e9d45 -->
+<!-- workflow=product-change@0.2.0 phase=verify sha256=f16d886eef6a02cdfa0dc0fbf89b19c8dfcd67c584b2e37b2c0f6ba54097b273 -->
 
 # AHEAD agent profile
 
@@ -21,9 +21,11 @@ You are assisting inside an active AHEAD workflow. Humans lead; AI assists.
 
 Help suggest checks and analyze authorized observations against the recorded problem and success signals. Keep code landed, deployed version, and observed behavior separate. A human decides whether the intended outcome is demonstrated or failure is recorded.
 
+
+
 ## Enforced phase contract
 
-- Workflow: `product-change@0.1.0`
+- Workflow: `product-change@0.2.0`
 - Current phase: `verify`
 - Human gate: `outcome-demonstrated` — Human confirms the intended outcome is demonstrated or failure is recorded
 - Normal next phase: `ai-audit`

package/generated/recommended-skills.json

@@ -0,0 +1,24 @@
+{
+  "api_version": "ahead.recommended-skills/v0.1",
+  "reviewed_at": "2026-08-12",
+  "skills": [
+    {
+      "id": "ponytail",
+      "title": "Ponytail",
+      "summary": "A persistent problem-solving loop for difficult implementation, debugging, and investigation work.",
+      "source": "DietrichGebert/ponytail",
+      "skill": "skills/ponytail",
+      "reviewed_ref": "2ed6c52c9d7e5e56942508591085fd45dea277d3",
+      "reviewed_url": "https://github.com/DietrichGebert/ponytail/tree/2ed6c52c9d7e5e56942508591085fd45dea277d3/skills/ponytail",
+      "license": "MIT",
+      "install": "npx skills add https://github.com/DietrichGebert/ponytail/tree/2ed6c52c9d7e5e56942508591085fd45dea277d3/skills/ponytail --agent pi",
+      "workflows": ["corrective-debugging", "investigation", "product-change", "internal-improvement"],
+      "phases": ["investigate", "explore", "implement"],
+      "compatibility": [
+        "AHEAD remains authoritative for human ownership, required artifacts, and gates.",
+        "Persistence never permits skipping human understanding, decisions, plans, tests, or review.",
+        "Treat suggestions to ship a quick or lazy version as experiments unless the active AHEAD flow has approved production implementation."
+      ]
+    }
+  ]
+}

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/guide/recommended-skills.md

@@ -0,0 +1,21 @@
+# 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.
+
+The machine-readable catalog is `recommendations/skills-v0.1.json`. Every entry pins the exact revision AHEAD reviewed, supplies an inspectable source URL and install command, identifies applicable workflows and phases, and records compatibility constraints. Updating a recommendation requires reviewing the new revision before changing the pin.
+
+## Ponytail
+
+[Ponytail](https://github.com/DietrichGebert/ponytail/tree/2ed6c52c9d7e5e56942508591085fd45dea277d3/skills/ponytail) is recommended as an optional persistence and problem-solving aid for difficult implementation, corrective debugging, and investigation work. AHEAD does not adopt Ponytail's authority model: the human still leads, its suggestions remain subject to the active phase, and a quick version is not production-ready merely because it works.
+
+Inspect the pinned source, then opt in with:
+
+```sh
+npx skills add https://github.com/DietrichGebert/ponytail/tree/2ed6c52c9d7e5e56942508591085fd45dea277d3/skills/ponytail --agent pi
+```
+
+The Pi integration exposes this catalog but never runs the command itself. Future editor adapters should render the same canonical catalog through their native UI.

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

@@ -1,10 +1,12 @@
 # AHEAD Pilot Workflows
 
-Status: pilot v0.1
+Audience: AHEAD practitioners
+
+Status: executable dogfood v0.1
 
 ## Purpose
 
-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 records improve reasoning and which create process burden.
+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 and show the human/AI rhythm. Dogfooding should reveal which phases, gates, and records improve reasoning and which create process burden.
 
 The profiles are:
 
@@ -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
@@ -83,7 +85,7 @@ Diagram language is normative for the pilot:
 
 - `HUMAN` or `ENGINEER` means the person owns the reasoning, decision, action, or artifact.
 - `AI — ASSIST` means AI may research, organize, propose, explain, generate bounded material, or challenge; it does not own or approve the phase.
-- `AI REVIEW` is an additional review and never satisfies a human-review gate.
+- `AI REVIEW` produces snapshot-bound hypotheses. The implementing human separately dispositions every material finding, and neither action satisfies the independent human-review gate.
 - Every decision, test selection, risk acceptance, consequential-action authorization, final review, and outcome gate is human.
 - All diagram permissions remain bounded by the rule hierarchy above. Humans lead and remain accountable; AI assists.