ahead-pi 0.2.1 → 0.3.0

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/docs/design/adapted-skill-guidance.md

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

package/generated/reference/docs/design/executable-workflows.md

@@ -1,12 +1,12 @@
 # Executable AHEAD Workflows
 
-Status: initial vertical slice v0.1
+Status: six-flow executable dogfood v0.1
 
 ## Purpose
 
 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.
 
-The first vertical slice implements the Product Change workflow. The other five pilot workflows remain manual profiles until dogfooding provides evidence about the reusable state model.
+The executable layer implements all six pilot workflows. They share a versioned event model and enforcement engine while retaining workflow-specific phases, artifacts, gates, returns, AI capabilities, and generated instructions.
 
 ## Architecture
 
@@ -40,15 +40,20 @@ The initial WebAssembly boundary is a small versioned JSON ABI. This avoids coup
 |---|---|
 | Durable principles | `CONSTITUTION.md` |
 | AI authority | `docs/acceptable-ai-use.md` |
-| Human-readable Product Change flow | `docs/workflows/product-change.md` |
-| Executable phases, artifacts, gates, transitions, and capabilities | `spec/workflows/product-change-v0.1.json` |
+| Human-readable flows | `docs/workflows/*.md` |
+| Current executable phases, artifacts, gates, transitions, and capabilities | `spec/workflows/*.json` |
+| Published historical workflow definitions retained for replay | `spec/workflows/legacy/*.json` |
 | Compact binding agent profile and shared AI behavior | `policy/common.md` |
-| Phase AI behavior | `policy/product-change/*.md` |
+| Phase AI behavior | `policy/<workflow>/*.md` with shared engineering-tail fragments in `policy/shared/*.md` |
+| Reusable phase practices | `policy/methods/*.md`, selected by `policy/methods/index.json` |
+| Reviewed optional skills | `recommendations/skills-v0.1.json` |
 | State transition enforcement | `crates/ahead-core` |
 | Host mapping, storage, and UI | `integrations/pi` |
 
 Generated integration instructions are build artifacts. They include the compact agent profile, active phase policy, enforced contract, workflow version, and a source hash and must not be edited directly.
 
+The engine retains published historical workflow definitions for replay while new runs use the current definition. Product Change `0.1.0` remains embedded for existing runs; the review and audit disposition contract is Product Change `0.2.0`. A run is always replayed against the version recorded when it started rather than silently reinterpreted under the newest workflow.
+
 The Pi package also copies the canonical Constitution and `docs/**/*.md` into a generated reference catalog. These full documents are not injected into every prompt. The adapter recommends references applicable to the active phase, lets humans read them through `/ahead-guide`, and lets AI retrieve a specific source through `ahead_get_reference`. This keeps the binding prompt small while making the framework, rationale, evidence, and original page-level provenance available on demand.
 
 ## State and evidence
@@ -81,11 +86,15 @@ These are intended to be inspectable, diffable repository artifacts. A team can
 
 - Only a human actor can start a run, accept a gate, transition a phase, return work, or close a run.
 - Artifact definitions state whether a human, AI, or either may record them.
-- Human-first option and plan artifacts unlock AI assistance in those phases.
+- Workflow-specific human-first artifacts unlock AI assistance only after the human's initial model, option, plan, baseline, or other required reasoning exists.
 - Required current-visit artifacts must exist before gate acceptance.
 - Advancement requires the current human gate.
 - Independent human review must be recorded by an identity other than the latest changeset implementer, and that reviewer must accept the review gate.
-- The Product Change flow distinguishes implementation, deployment, observation, audit, and human outcome.
+- Lasting-change flows distinguish implementation, AI review, independent human review, deployment, observation, audit, and human outcome.
+- AI review is bound to a fingerprint of the exact current engineering changeset. The implementing human records a separate disposition for every material AI finding before independent human review.
+- AI-audit findings and their human disposition are separate required records, and the human disposer personally accepts the audit gate.
+- Operational Stabilization permits investigation and recovery work to proceed without proven root cause, but never grants AI the `execute` capability for the intervention or its execution phase.
+- Decision and Investigation close with human-owned records and do not silently authorize downstream implementation.
 - Model-invoked host tools require an explicit adapter mapping to an allowed canonical capability.
 
 Instructions explain these boundaries to the model. The Rust core enforces the transition, actor, artifact, identity, and capability decisions even if instructions are ignored.
@@ -102,9 +111,12 @@ The Pi adapter is an engineering workflow control, not a security sandbox.
 - Artifact and run writes are atomic, but v0.1 has no multi-process lock. One writer should operate a run at a time.
 - Workflow files can prove that a named action was recorded, not that a person genuinely understood it. Human review and organizational accountability remain necessary.
 - No GitHub checks, PR gates, migration engine, signature scheme, or backwards-compatible workflow upgrade exists yet.
+- Local review fingerprints detect changes but are not signatures. A future GitHub adapter must add remote identity and protected-branch evidence rather than treating the local record as cryptographic proof.
 
 ## Reuse path
 
 The reusable boundary is the engine API, not a CLI. Pi is the first adapter. A VS Code extension, GitHub check, or future WASM-capable editor can reuse the same compiled core and canonical fragments while providing its own UI, storage transport, identity strength, and tool-capability map.
 
-Dogfooding should test whether phase visits, artifacts, gates, returns, capability vocabulary, and identity rules generalize before the remaining five workflow profiles are encoded.
+Review presentation follows the same rule. The core requires snapshot-bound findings, dispositions, and review gates; a host maps portable paths and locations to a terminal viewer, VS Code diff/comment UI, or GitHub review API. See `docs/design/review-workbench.md`.
+
+Dogfooding should test whether the six encoded flows route real work correctly, whether their records and gates earn their cost, and whether phase visits, returns, capability vocabulary, and identity rules generalize across integrations.

package/generated/reference/docs/design/instruction-authoring.md

@@ -0,0 +1,28 @@
+# Instruction Authoring
+
+Status: initial authoring standard v0.1
+
+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.
+
+## Progressive disclosure
+
+Use three layers:
+
+1. The active profile supplies the binding human/AI authority boundary and live workflow state.
+2. The generator adds the workflow phase fragment and only the method overlays mapped to that phase in `policy/methods/index.json`.
+3. Humans and AI retrieve full framework Markdown on demand through the host integration.
+
+The canonical workflow spec owns phases, artifacts, gates, transitions, and capabilities. Phase policies own local AI behavior. Method overlays own reusable practices such as evidence handling or debugging. Full documents explain why. Do not restate one rule in every layer.
+
+## Authoring rules
+
+- State the desired observable behavior in direct, positive language.
+- Put human ownership and prohibited transfers of authority where a model cannot mistake them for suggestions.
+- Give checkable completion criteria: an exact artifact, observation, identifier, or gate condition.
+- Point to the canonical source instead of copying large passages.
+- Keep host-specific UI out of core workflow semantics.
+- Do not cache repository facts that tools can discover cheaply and reliably.
+- Use examples to clarify a schema, not to narrow judgment to the example.
+- Treat generated instructions as build artifacts and test the generated output for required boundaries.
+
+The build fails when a method overlay names an unknown workflow or phase. Adding a method therefore requires its source fragment, an explicit mapping, generated-output coverage, and documentation when it changes user-visible expectations.

package/generated/reference/docs/design/review-workbench.md

@@ -0,0 +1,37 @@
+# Review Workbench
+
+Status: Pi host v0.1; editor-neutral contract v0.1
+
+## Purpose
+
+The review workbench makes the handoff from implementation to independent human review explicit and inspectable:
+
+```text
+HUMAN IMPLEMENTS AND SELF-CHECKS
+              │
+              ▼
+CAPTURE EXACT CHANGESET FINGERPRINT
+              │
+              ▼
+AI REVIEWS WITHOUT MODIFYING
+              │
+              ▼
+HUMAN DISPOSITIONS EACH MATERIAL FINDING
+              │
+              ▼
+INDEPENDENT HUMAN REVIEWS CURRENT SNAPSHOT
+```
+
+The adapter computes a fingerprint from the selected base and merge base, HEAD, engineering working-tree status, tracked diff, and hashes of untracked files. `.ahead/**` records are excluded so recording the review does not invalidate the engineering snapshot. AI and human review artifacts must carry `AHEAD-Review-Snapshot: <fingerprint>`. If the engineering changeset changes, the fingerprint changes and the review must be repeated.
+
+## Portable contract
+
+`integrations/pi/src/review.ts` defines host-neutral snapshot and source-location data plus a small `ReviewHost` boundary. Core workflow semantics require the AI findings, implementing-human disposition, and independent-human review; they do not require a terminal, VS Code, GitHub, or a particular comment API.
+
+Pi is the first host. `/ahead-review` can show the snapshot and diff in the terminal, open a changed path in detected VS Code or `AHEAD_EDITOR=vscode`, request the AI review, and open the correct human record. A future VS Code adapter can map the same locations to native diffs and comments. A GitHub adapter can publish selected findings and verify protected-branch identities without changing the workflow contract.
+
+## Finding and disposition shape
+
+AI findings use stable `AR-001` identifiers and include severity, category, precise location, evidence, impact, and a falsifiable explanation. They are hypotheses. The implementing human separately marks every material finding `fixed`, `invalid`, `accepted-risk`, or `follow-up` and records rationale and evidence. An independent human then reviews the current snapshot and makes the final engineering judgment.
+
+The workbench does not post comments, push branches, mark a pull request ready, or approve a pull request automatically. Those are explicit future host effects governed by human authorization and stronger remote identity.

package/generated/reference/docs/recommended-skills.md

@@ -0,0 +1,19 @@
+# Recommended Skills
+
+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/README.md

@@ -1,10 +1,10 @@
 # AHEAD Pilot Workflows
 
-Status: pilot v0.1
+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:
 
@@ -83,7 +83,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.
 

package/generated/reference/docs/workflows/corrective-debugging.md

@@ -36,7 +36,7 @@ Use operational stabilization instead when a live system is unhealthy and restor
                       │
                       ▼
               ┌─────────────────┐
-              │ 3. AI ASSISTS   │
+              │ 3A. AI ASSISTS  │
               │ EVIDENCE REVIEW │
               │                 │
               │ • Code          │
@@ -48,7 +48,7 @@ Use operational stabilization instead when a live system is unhealthy and restor
                       │
                       ▼
               ┌─────────────────┐
-              │ 4. HYPOTHESES   │
+              │ 3B. HYPOTHESES  │
               │                 │
               │ HUMAN LEADS     │
               │ AI ASSISTS      │
@@ -60,8 +60,8 @@ Use operational stabilization instead when a live system is unhealthy and restor
                       │
                       ▼
               ┌─────────────────┐
-              │ 5. HUMAN SELECTS│
-              │ WHAT TO TEST    │
+              │ 3C. HUMAN       │
+              │ SELECTS TEST    │
               │                 │
               │ • Prediction    │
               │ • Safety/scope  │
@@ -69,7 +69,7 @@ Use operational stabilization instead when a live system is unhealthy and restor
                       │
                       ▼
               ┌─────────────────┐
-              │ 6. TEST         │
+              │ 3D. TEST        │
               │ HYPOTHESIS      │
               │                 │
               │ HUMAN/ENGINEER  │
@@ -87,38 +87,44 @@ Use operational stabilization instead when a live system is unhealthy and restor
                      │    │
                      │    ▼
         ↺ HUMAN MODEL     HUMAN ACCEPTS DIAGNOSIS
-                          OR UNKNOWN CAUSE / RISK
+                          OR UNKNOWN CAUSE / RISK (4)
                                   │
                                   ▼
-                         HUMAN FIX APPROACH
+                         HUMAN FIX APPROACH (5)
                                   │
                                   ▼
-                         HUMAN FIRST-PASS PLAN
+                         HUMAN FIRST-PASS PLAN (6)
                                   │
                                   ▼
-                       ENGINEER IMPLEMENTS
+                       ENGINEER IMPLEMENTS (7)
                                   │
                                   ▼
-                              AI REVIEW
+                              AI REVIEW (8)
                                   │
                                   ▼
-                    INDEPENDENT HUMAN REVIEW
+                 HUMAN DISPOSITIONS MATERIAL FINDINGS
                                   │
                                   ▼
-                  HUMAN AUTHORIZES DEPLOY / RELEASE
+                    INDEPENDENT HUMAN REVIEW (9)
+                                  │
+                                  ▼
+                  HUMAN AUTHORIZES DEPLOY / RELEASE (10)
                            WHEN APPLICABLE
                                   │
                                   ▼
-          HUMAN VERIFIES CORRECTION OF ORIGINAL FAILURE
+          HUMAN VERIFIES CORRECTION OF ORIGINAL FAILURE (11)
                                   │
                                   ▼
                  HUMAN OBSERVES DEPLOYED OUTCOME
                                   │
                                   ▼
-                              AI AUDIT
+                              AI AUDIT (12)
+                                  │
+                                  ▼
+                    HUMAN DISPOSITIONS AUDIT FINDINGS
                                   │
                                   ▼
-                         HUMAN OUTCOME GATE
+                         HUMAN OUTCOME GATE (13)
 
 Not corrected ───────────────────↺ HUMAN MODEL
 ```
@@ -127,21 +133,24 @@ Reproduction is useful but not a universal gate. Historical, intermittent, produ
 
 “Ready to choose” means either the evidence sufficiently supports a human-accepted diagnosis or the accountable human explicitly accepts that the cause remains unknown and records the risk of proceeding. Unsupported hypotheses alone do not satisfy the gate.
 
+Executable phase 3, `investigate`, contains the evidence review, hypothesis, human test-selection, and test loop shown as 3A–3D. The human conclusion is a separate gate so a plausible hypothesis cannot silently become a diagnosis.
+
 ## Minimal phases
 
 | Phase | Human owns | AI may | Minimum record | Advance when |
 |---|---|---|---|---|
 | Report and characterize | Intended behavior, observed behavior, impact, scope, and evidence quality | Organize evidence and identify missing characterization | Failure statement and evidence links | The failure is bounded enough to investigate |
 | Mental model | Current explanation of relevant components, state, and interactions | Explain unfamiliar mechanisms and challenge omissions | Model, assumptions, and unknowns | The model can generate testable hypotheses |
-| Hypothesize and test | Hypothesis selection, test authorization, prediction, and interpretation | Generate alternatives, evidence for/against, and discriminating tests | Facts, inferences, hypotheses, predictions, tests, results, confidence | Human accepts a diagnosis or explicitly accepts uncertainty |
+| Investigate and test | Hypothesis selection, test authorization, prediction, and interpretation | Generate alternatives, evidence for/against, and discriminating tests | Facts, inferences, hypotheses, predictions, tests, results, confidence | Evidence is ready for a human conclusion |
+| Conclude diagnosis | Supported diagnosis or explicit acceptance of unknown cause, confidence, and risk | Challenge the conclusion against evidence and counterevidence | Diagnosis or accepted uncertainty | Human accepts the diagnosis or remaining uncertainty |
 | Choose correction | Desired correction and tradeoffs | Compare fix approaches and recurrence risks | Selected correction and rationale | Human approves the correction |
 | Plan | First-pass correction and verification plan | Find missing cases, risks, regression tests, and rollout concerns | Plan and rollback or containment needs | Human approves the plan |
 | Implement | Code and engineering changes | Bounded implementation and debugging assistance | Linked changeset and regression evidence | Change is ready for review |
-| AI review | Disposition of valid findings | Review correction, tests, risks, and plan alignment | AI findings and dispositions | Blocking findings are resolved or rejected with rationale |
+| AI review | Validate and disposition every material AI finding | Review the exact snapshot for correction, tests, risks, and plan alignment without modifying it | Snapshot-bound AI findings; separate human disposition | Every material finding is fixed, invalid, accepted risk, or follow-up with rationale |
 | Human review | Independent final engineering judgment by someone other than the implementer | Answer targeted questions and retrieve evidence | Current independent human review | Independent human reviewer accepts the current change |
 | Deploy or release | Authorization and rollout decision | Analyze readiness evidence within policy | Version, environment, actor, time, and result | The intended correction reaches the target environment or deployment is explicitly not applicable |
 | Verify and observe | Original failure, regression protection, and deployed behavior when applicable | Suggest checks and analyze authorized evidence | Pre-change comparison, fix validation, deployment evidence, and observed outcome | The original failure and user-visible outcome are evaluated |
-| AI audit | Disposition of findings and required response | Compare the result with the failure, diagnosis or accepted uncertainty, correction, plan, reviews, and observed behavior | Audit findings and dispositions | Human has reviewed material findings |
+| AI audit | Disposition of findings and required response | Compare the result with the failure, diagnosis or accepted uncertainty, correction, plan, reviews, and observed behavior | AI audit findings; separate human disposition | The human disposer accepts the audit gate or reopens work |
 | Outcome | Acceptance, rollback, continued investigation, follow-up, or abandonment | Summarize learning | Result, causal confidence, uncertainty, and follow-ups | Human accepts closure or reopens/routes work |
 
 ## Evidence chain
@@ -167,7 +176,16 @@ FACTS / EVIDENCE ──► HUMAN MENTAL MODEL
              HUMAN CORRECTION DECISION / PLAN
                             │
                             ▼
-     ENGINEER CHANGE / AI REVIEW / INDEPENDENT REVIEW
+                  ENGINEER CHANGE
+                            │
+                            ▼
+              SNAPSHOT-BOUND AI REVIEW
+                            │
+                            ▼
+           IMPLEMENTING-HUMAN DISPOSITION
+                            │
+                            ▼
+               INDEPENDENT HUMAN REVIEW
                             │
                             ▼
                 HUMAN-AUTHORIZED DEPLOYMENT

package/generated/reference/docs/workflows/decision.md

@@ -100,11 +100,11 @@ Reframe or seek evidence ─────────↺ FRAME / RESEARCH
 |---|---|---|---|---|
 | Frame | Decision to be made, accountable decider, scope, deadline, and stakeholders | Clarify ambiguity and identify missing stakeholders | Decision statement and owner | Human accepts the frame |
 | Criteria | Goals, constraints, evaluation criteria, and relative importance | Challenge hidden criteria and identify tensions | Criteria and non-negotiable constraints | Criteria are sufficient for comparison |
-| Research and questions | Evaluation of evidence and disposition of uncertainty | Gather cited evidence and find contradictions or missing questions; do not introduce solution alternatives yet | Sources, findings, unknowns, and limits | Material evidence is reviewed and uncertainty is answered or explicitly accepted |
+| Research | Evaluation of evidence and disposition of uncertainty | Gather cited evidence and find contradictions or missing questions; do not introduce solution alternatives yet | Sources, findings, assumptions, unknowns, and limits | Material evidence is reviewed and uncertainty is answered or explicitly accepted |
 | Options | At least one human-originated option | Expand, combine, challenge, and propose alternatives | Options with provenance | Plausible option space is understood |
 | Compare | Interpretation of tradeoffs | Structure comparison and sensitivity analysis | Benefits, costs, risks, consequences, reversibility | Decision is ready for accountable judgment |
 | Decide | Selection, rationale, accepted tradeoffs, and dissent | Test rationale for inconsistency or missing consequence | Decision and rejected alternatives | Accountable human approves a specific revision |
-| Validate and publish | Consequence check, communication, review trigger, and linked work | Summarize and propose validation checks | Consequences, reversibility, review trigger, links | Decision is published and accepted as current |
+| Publish and revisit | Consequence check, communication, review trigger, revisit date, and linked work | Improve clarity, traceability, and proposed validation checks | Consequences, reversibility, review trigger, revisit date, and links | Decision is published and accepted as current |
 
 ## Decision evidence chain