ahead-pi 0.2.0 → 0.3.0

package/generated/reference/docs/acceptable-ai-use.md

@@ -0,0 +1,217 @@
+# Acceptable AI Use in AHEAD
+
+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.
+
+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.
+
+## Purpose
+
+AHEAD encourages substantial AI assistance while preserving human understanding, judgment, skill, and accountability. Acceptable use is determined by the role AI plays, the risk of the work, the information exposed, and the engineer's ability to verify and own the result—not simply by how many lines AI produced.
+
+The default relationship is:
+
+```text
+Human supplies intent, context, and an initial model
+→ AI retrieves, generates, compares, or challenges
+→ Human verifies, decides, and owns the result
+```
+
+## Conditions for acceptable use
+
+An AI-assisted contribution is acceptable only when all applicable conditions hold:
+
+1. A human owns the problem, intended behavior, and consequences.
+2. The AI's task is bounded and appropriate to the active workflow phase.
+3. The model receives only information authorized for that provider, tool, and purpose.
+4. Claims, citations, commands, dependencies, and generated artifacts can be checked against authoritative evidence.
+5. The responsible engineer can explain, maintain, debug, test, and modify accepted code.
+6. Verification is proportionate to risk and does not rely solely on the same AI that produced the work.
+7. Material AI involvement remains visible when repository, organizational, legal, or review policy requires it.
+8. The AI has no implicit authority to approve, merge, deploy, communicate commitments, accept risk, or act in production.
+
+## Generally acceptable uses
+
+### Research and information gathering
+
+AI may locate, organize, compare, and summarize approved internal and external sources. The engineer follows important claims to their sources and distinguishes retrieved evidence from AI synthesis.
+
+Why: AI increases search and synthesis capacity, while NIST identifies confident false content as an inherent generative-AI risk. Summaries are navigation aids, not new authorities.
+
+### Boilerplate and repetitive structure
+
+AI may generate scaffolding, serializers, routine handlers, adapters, setup code, repetitive mappings, and other bounded structure after the human identifies the intended pattern and integration boundary.
+
+The engineer checks local conventions, error handling, dependencies, security posture, and whether generation introduced unnecessary abstraction. “Boilerplate” is not a label that makes risky code safe.
+
+### Disposable prototypes and full vibe coding
+
+Full “vibe coding”-prompting AI to produce most or all of an implementation without first understanding every detail-is acceptable for a disposable prototype whose purpose is to learn quickly whether an idea is feasible or how an experience might turn out.
+
+This exception applies only when all of these boundaries are explicit:
+
+- the learning question and prototype status are stated before generation;
+- the prototype is isolated from production systems, credentials, customer data, and consequential decisions;
+- nobody relies on its correctness, security, scalability, accessibility, or maintainability;
+- generated dependencies, licenses, and external content remain subject to inspection;
+- the prototype has an owner, an expiration or disposal decision, and a conspicuous `PROTOTYPE — NOT FOR PRODUCTION` label;
+- demonstrations disclose material limitations rather than presenting simulated behavior as validated capability;
+- any code selected for retention leaves the prototype exception and enters the normal AHEAD process for human understanding, design, implementation, testing, security review, and approval.
+
+Throwaway describes the artifact, not the evidence learned from it. Preserve useful observations, constraints, failed approaches, and decisions as durable artifacts, then discard the code. A prototype must not become production software through incremental cleanup or repeated deployment.
+
+This is an AHEAD operating policy supported by established prototyping practice, not evidence that unrestricted vibe coding produces production-quality systems.
+
+### Candidate tests
+
+AI may propose test cases, fixtures, mocks, generators, boundary values, and failure scenarios after a human defines the expected behavior, important invariants, and test oracle.
+
+Tests are reviewed as production code. The engineer checks that they can fail, do not merely encode the current implementation, cover meaningful states and failure paths, and do not silently weaken or replace existing tests. Security-critical tests require independent human authorship or review.
+
+Research has found that LLM support can increase generated tests and defect detection, but also test volume and false positives. Test-guided interaction can improve people's ability to evaluate generated code. These findings support AI-assisted testing with human-defined intent and independent verification—not treating passing AI-generated tests as proof.
+
+### First-pass review
+
+AI may perform an additional early review for likely defects, security concerns, missing tests, plan divergence, unclear code, and relevant edge cases.
+
+AI review never constitutes final approval. Findings are hypotheses until a human validates them. Human review remains required because empirical work links substantive review participation and expertise with quality, while current LLM reviewers exhibit systematic false-positive and conformance-judgment failures.
+
+For a lasting engineering change, independent human review means review by a person other than the implementer. The implementer and reviewer must both understand the behavior, risks, and evidence relevant to their responsibilities. Implementer self-review and AI review do not satisfy this gate. An emergency policy may defer independent review to restore service, but the gate remains unsatisfied until a named human reviewer completes it after stabilization.
+
+### Refactoring proposals
+
+AI may identify duplication, coupling, unclear names, complicated control flow, possible abstractions, or opportunities to isolate state. The human decides whether the proposed change makes the artifact simpler and verifies preserved behavior.
+
+AI may not manufacture a justification for a refactor or substitute rearranged files for reduced conceptual complexity.
+
+### Documentation and communication assistance
+
+AI may organize engineer-provided facts, edit for clarity, create an outline, derive reference documentation from verified interfaces, and draft routine sections that the named author reviews.
+
+The human supplies and verifies the reasoning, status, decisions, commitments, uncertainty, and audience judgment. AI must not fabricate citations, test results, incident facts, user claims, approvals, or confidence. It must not make weak understanding sound authoritative.
+
+### Debugging support
+
+AI may help organize evidence, explain unfamiliar mechanisms, generate competing hypotheses, identify contradicting evidence, and propose discriminating tests.
+
+Before broad AI assistance in normal debugging, the human records at least the observed failure, evidence already checked, and an initial mental model or question. A team may use a timebox before asking AI, but the purpose is independent thought—not withholding useful tools. During incidents, AI may assist immediately once the current observation and safety constraints are established.
+
+The human remains the investigator: selecting or authorizing tests, interpreting results, deciding whether evidence supports a conclusion, and choosing the intervention.
+
+### Design alternatives
+
+After the human frames the problem and contributes an initial option, AI may broaden the option set, compare tradeoffs, find examples, expose assumptions, and argue against the favored approach.
+
+The human-first sequence is an AHEAD policy and design hypothesis, not a proven universal optimum. Adjacent experimental evidence shows that generative-AI ideas can improve individual creative output while reducing collective diversity, giving AHEAD a reason to test this sequence rather than claim it is settled.
+
+### Learning and onboarding
+
+AI may explain code, concepts, patterns, libraries, tools, and unfamiliar terminology. Prefer explanations, questions, small examples, critiques, and hints that require the learner to retrieve and apply knowledge.
+
+When skill formation is the goal, avoid full-solution delegation. A randomized study of developers learning an unfamiliar Python library found lower mastery for the AI-assisted group overall; participants who used AI to ask conceptual questions and build comprehension did better than those who delegated the work.
+
+### Examples, mocks, and planning mechanics
+
+AI may generate non-sensitive sample payloads, mock data, fixtures, command examples, ticket structure, acceptance-criteria candidates, and summaries of human-provided notes.
+
+Generated examples are checked for realism, privacy, security, and accidental use of production identifiers. AI may organize a human first-pass plan; it may not create the reasoning and relabel it as human-authored.
+
+## Uses requiring heightened review
+
+AI may assist in these areas, but it does not originate the governing policy or act without explicit human control:
+
+- authentication, authorization, cryptography, privacy, and security controls;
+- business rules, financial calculations, safety constraints, and regulated behavior;
+- database schemas, migrations, destructive maintenance, and data correction;
+- concurrency, distributed consistency, recovery, and idempotency;
+- dependencies, generated build steps, package scripts, and supply-chain changes;
+- infrastructure, CI/CD, identity, permissions, and secrets;
+- production commands, remediation, deployment, rollback, or containment;
+- legal, compliance, personnel, customer, or public communication;
+- generated licenses, attribution, or content with unclear provenance.
+
+These uses require a named human owner, authoritative requirements, explicit scope, risk-appropriate tests, relevant specialist review, and separately authorized effects. Critical code and its only validation should not come from one AI context.
+
+## Unacceptable uses
+
+### Submitting work the engineer does not understand
+
+Do not accept long-lived code that its responsible engineer cannot explain, maintain, debug, test, and safely change. Passing current tests is not sufficient.
+
+### Outsourcing core business logic
+
+AI may explain, challenge, review, or help test core business rules. Under AHEAD, the accountable engineer authors their implementation and traces it to human-approved requirements. This is a constitutional policy choice whose precise boundary must be refined by teams.
+
+### Letting AI define behavior or policy
+
+AI is not the authority for business rules, authorization, privacy, data retention, workflow behavior, acceptable risk, or production semantics. It may retrieve an authoritative rule; it may not become that authority.
+
+### Blind copying or unverified execution
+
+Do not copy generated code, commands, dependencies, citations, or configuration without inspecting their meaning and validating them in the relevant environment. Never treat confident explanation as evidence.
+
+### Bypassing learning
+
+Do not use AI to avoid acquiring skills needed to oversee the resulting system. When learning is the objective, the workflow should favor explanation, retrieval, prediction, and modification over full answer generation.
+
+### AI-first debugging with no human observation
+
+Do not reduce debugging to pasting an error into a model and following its first answer. Establish what was observed and what evidence exists. AI-generated hypotheses are candidates, not diagnoses.
+
+### Outsourcing judgment or approval
+
+AI may not select the team's technical opinion, accept tradeoffs, waive a gate, approve a change, declare an incident recovered, or perform final engineering review.
+
+### Impersonating human communication
+
+AI may help edit or structure communication, but it may not invent reasoning and present it as the named person's own understanding. Humans own PR rationales, incident updates, decisions, commitments, and explanations sent under their identity.
+
+### Polishing over uncertainty
+
+Do not use AI to make incomplete evidence appear conclusive, conceal disagreement, erase caveats, or make a person sound as though they understand work they have not examined.
+
+### Unauthorized data or access
+
+Do not expose secrets, credentials, personal data, confidential source, customer information, incident evidence, regulated data, or proprietary material to an unapproved model or provider. Do not assume `.gitignore` prevents an editor assistant from reading a file.
+
+Do not give an AI agent broader filesystem, network, repository, CI, cloud, or production permissions than its bounded task requires. Repository text, issues, logs, web pages, and tool output are untrusted inputs that may attempt to redirect the agent.
+
+## Verification checklist
+
+Before accepting material AI-assisted work, the responsible engineer answers:
+
+- What did the human decide before AI involvement?
+- What did the AI contribute?
+- Can I explain the result without appealing to the AI's authority?
+- Which facts, requirements, and sources did I independently verify?
+- What tests could disprove the implementation or conclusion?
+- Did the same AI create both the work and all evidence used to validate it?
+- What sensitive context was shared, with which provider, under what policy?
+- Did the AI introduce dependencies, licenses, commands, or external content?
+- What could fail outside the examples the AI saw?
+- Am I willing and authorized to own this result?
+
+For a disposable prototype, also answer:
+
+- What specific question is this prototype meant to answer?
+- Where is it isolated, and what production access or sensitive data is excluded?
+- When will it be discarded or deliberately re-enter the normal engineering workflow?
+
+## Evidence and sources
+
+- [Cui et al., *The Effects of Generative AI on High-Skilled Work*](https://doi.org/10.1287/mnsc.2025.00535) — randomized field evidence that coding assistants can increase completed tasks in some organizational contexts.
+- [Becker et al., *Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity*](https://arxiv.org/abs/2507.09089) — randomized evidence that the same broad category of tool can slow experienced developers in familiar repositories, despite perceived speedups.
+- [Shen and Tamkin, *How AI Impacts Skill Formation*](https://arxiv.org/abs/2601.20245) — randomized study of AI assistance, code understanding, and learning an unfamiliar library.
+- [Ramler et al., *Unit Testing Past vs. Present*](https://arxiv.org/abs/2502.09801) — experiment on LLM-supported unit testing, defect detection, and false positives.
+- [Fakhoury et al., *LLM-Based Test-Driven Interactive Code Generation*](https://www.microsoft.com/en-us/research/publication/llm-based-test-driven-interactive-code-generation-user-study-and-empirical-evaluation/) — user study and evaluation of test-guided intent clarification.
+- [Jin and Chen, *Are LLMs Reliable Code Reviewers?*](https://arxiv.org/abs/2603.00539) — evidence of systematic overcorrection in LLM requirement-conformance review.
+- [Doshi and Hauser, *Generative AI enhances individual creativity but reduces the collective diversity of novel content*](https://doi.org/10.1126/sciadv.adn5290) — adjacent experimental evidence relevant to AI anchoring and option diversity.
+- [Bjarnason, Lang, and Mjöberg, *An empirically based model of software prototyping*](https://doi.org/10.1007/s10664-023-10331-w) — a systematic mapping study and multi-company study of prototypes used to explore and validate feasibility, desirability, usability, and requirements.
+- [NIST AI 600-1, *Generative Artificial Intelligence Profile*](https://doi.org/10.6028/NIST.AI.600-1) — authoritative risk guidance on confabulation, privacy, provenance, testing, and governance.
+- [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.

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/debugging-and-operations.md

@@ -0,0 +1,119 @@
+# Debugging and Operational Investigation
+
+Status: design discussion, not an approved workflow specification
+
+The minimal [corrective-debugging](../workflows/corrective-debugging.md) and [operational-stabilization](../workflows/operational-stabilization.md) profiles translate this discussion into pilotable flows. This document retains the reasoning and unresolved questions behind them.
+
+## Human ownership
+
+Debugging is human-owned. AI may help collect and organize evidence, suggest hypotheses and tests, identify contradictions, explain systems, and challenge conclusions. The human chooses what to investigate, performs or authorizes tests, interprets the evidence, selects interventions, and accepts the conclusion or remaining uncertainty.
+
+There is no “AI investigation” phase. Investigation is a human engineering activity in which AI may participate.
+
+## Shared reasoning loop
+
+```text
+Observation
+→ Characterize
+→ Build or update the mental model
+→ Generate hypotheses
+→ Human selects a discriminating test
+→ Predict expected results
+→ Run the test
+→ Record evidence
+→ Update or refute hypotheses
+→ Repeat
+```
+
+The process distinguishes:
+
+- **Fact:** directly observed and linked to evidence.
+- **Inference:** an interpretation derived from facts.
+- **Hypothesis:** a falsifiable proposed explanation.
+- **Test:** an experiment or observation capable of changing confidence in a hypothesis.
+- **Result:** what the test actually produced.
+- **Conclusion:** a human-accepted explanation with confidence, limits, and remaining uncertainty.
+
+Predictions should be recorded before a test when practical. This reduces hindsight interpretation of ambiguous results.
+
+## Bug debugging
+
+A bug is a defect where observed software behavior conflicts with intended behavior.
+
+```text
+Observe → Reproduce or establish
+→ Characterize
+→ Human-led investigation loop
+→ Human accepts diagnosis or uncertainty
+→ Choose fix → Plan → Implement → Validate locally
+→ AI review → Independent human review
+→ Human-authorized deploy or release when applicable
+→ Verify the original failure and observe the outcome
+→ Audit assumptions → Human outcome
+```
+
+Reproduction is valuable but not universally required. A failure may be intermittent, historical, production-only, environment-specific, or already mitigated.
+
+## Operational investigation
+
+An operational issue is undesirable system behavior that may not be a software defect. Examples include reconciliation storms, configuration drift, capacity exhaustion, cloud-provider behavior, dependency failures, identity or certificate failures, resource contention, bad rollout sequencing, and emergent controller interactions.
+
+```text
+Observed condition
+→ Desired state versus actual state
+→ Impact and scope
+→ Timeline
+→ System and control-loop model
+→ Recent changes and external events
+→ Evidence/hypothesis/test loop
+→ Intervention decision
+→ Verify convergence and user-visible behavior
+→ Monitor recurrence
+→ Corrective actions
+```
+
+The initial cause classification must remain tentative. Labeling an issue a code bug, configuration error, or provider failure before collecting evidence can bias the investigation.
+
+## Incident mode
+
+“Incident” describes impact and urgency rather than cause. An incident may be caused by a bug, configuration, capacity, provider behavior, a security event, data, or an interaction that remains partially unexplained.
+
+Incident mode adds parallel concerns:
+
+```text
+Response:       assess impact → contain → recover → monitor
+Investigation:  evidence → model → hypotheses → tests → conclusion
+Coordination:   ownership → decisions → communications → timeline
+```
+
+Mitigation and recovery must not be blocked on completing a full diagnosis. Risky interventions still require explicit human authorization. After recovery, unresolved causal analysis and prevention work may continue as a linked bug, operational investigation, security issue, or technical-debt item.
+
+## Current design direction
+
+- Treat bug debugging and operational investigation as separate work types.
+- Treat incident mode as an overlay that may apply to several work types.
+- Keep the evidence and hypothesis loop flexible rather than gating every iteration.
+- Reserve hard gates for human accountability, risky tests, consequential interventions, accepted conclusions, implementation plans, reviews, and verified outcomes.
+- Distinguish hypothesis testing, fix validation, and post-deployment outcome verification.
+- Allow causal conclusions to include a failure mechanism, trigger, enabling conditions, and detection or containment gaps instead of insisting on one root cause.
+
+## Open questions
+
+- What minimum evidence is needed before a human may accept a diagnosis?
+- When may a team remediate while explicitly accepting that the cause is unknown?
+- Which tests require approval based on environment, reversibility, or blast radius?
+- How should AHEAD represent multiple interacting causes and confidence changes?
+- When does an operational anomaly become incident mode?
+- Which incident records must be produced during response, and which may be reconstructed afterward?
+- How should follow-up work remain linked without keeping the incident itself permanently open?
+
+## Evidence basis
+
+The current reasoning loop is supported by direct empirical software-engineering research, though the exact AHEAD recording requirements are not yet validated:
+
+- [Li and Coblenz, *A Grounded Theory of Debugging in Professional Software Engineering Practice*](https://arxiv.org/abs/2602.11435) observed professional developers and describes debugging as iterative mental-model construction that guides information gathering.
+- [Alaboudi and LaToza, *Using Hypotheses as a Debugging Aid*](https://doi.org/10.1109/VL/HCC50065.2020.9127273) found that early correct hypotheses predicted success and that supplying potential hypotheses helped more than supplying fault locations in their controlled experiment.
+- [Sillito and Kutomi, *Failures and Fixes*](https://doi.org/10.1109/ICSME46990.2020.00027) analyzed 30 incidents and identified distinct investigative and mitigative strategies.
+- [Ghosh et al., *How to Fight Production Incidents?*](https://doi.org/10.1145/3542929.3563482) studied hundreds of high-severity cloud incidents, including non-code causes, across detection, diagnosis, and mitigation.
+
+These studies support the shape of the process. They do not prove that requiring engineers to record every fact, hypothesis, or test improves results. AHEAD must test the minimum useful structure and remove requirements that interrupt investigation without improving reasoning, handoff, or learning.

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

@@ -0,0 +1,122 @@
+# Executable AHEAD Workflows
+
+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 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
+
+```text
+CONSTITUTION / ACCEPTABLE-AI-USE
+                 │
+                 ▼
+CANONICAL WORKFLOW SPEC + POLICY FRAGMENTS
+                 │
+        ┌────────┴────────┐
+        ▼                 ▼
+RUST WORKFLOW CORE   GENERATED INSTRUCTIONS
+        │                 │
+        └────────┬────────┘
+                 ▼
+         INTEGRATION ADAPTER
+        (Pi first; others later)
+                 │
+        ┌────────┴─────────┐
+        ▼                  ▼
+HOST TOOLS / MODEL     DURABLE RUN FILES
+```
+
+The Rust core owns workflow semantics. It is deterministic and has no filesystem, network, clock, model-provider, or editor dependency. Hosts supply identity and timestamps, persist returned runs, and map their tools to canonical capabilities.
+
+The initial WebAssembly boundary is a small versioned JSON ABI. This avoids coupling the core to one JavaScript binding generator and lets a later editor or CI integration load the same state machine.
+
+## Sources of truth
+
+| Concern | Canonical source |
+|---|---|
+| Durable principles | `CONSTITUTION.md` |
+| AI authority | `docs/acceptable-ai-use.md` |
+| 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/<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
+
+A run is an append-only event log. Events record an actor kind and identity, host-supplied timestamp, sequence, and one action:
+
+- start the run;
+- record an artifact;
+- accept a human gate;
+- advance or return between phases;
+- close the run.
+
+State is derived by replay. The core rejects invalid history rather than trusting a cached phase field. A return transition creates a new visit to the target phase. Earlier evidence remains in history, but only evidence recorded during the current visit satisfies its gate.
+
+Pi stores state under the work's Git root:
+
+```text
+.ahead/
+├── current.json
+└── runs/
+    └── <run-id>/
+        ├── run.json
+        └── artifacts/
+            └── <sequence>-<phase>-<kind>.md
+```
+
+These are intended to be inspectable, diffable repository artifacts. A team can decide which records belong in Git, while CI and GitHub enforcement are later adapters over the same run contract.
+
+## Enforced boundaries in v0.1
+
+- 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.
+- 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.
+- 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.
+
+During implementation, instructions explicitly permit questions, explanation, debugging help, and bounded suggestions while keeping the engineer first. If the engineer has not supplied a current model, attempted approach, or intended behavior, AI asks for it before proposing a solution. A request for help does not authorize AI to take over the implementation.
+
+## Trust boundaries and limits
+
+The Pi adapter is an engineering workflow control, not a security sandbox.
+
+- Local human identity comes from `AHEAD_HUMAN_IDENTITY`, then Git email/name, then the local user. It is self-attested. GitHub review identity and protected-branch rules will provide a stronger boundary later.
+- Pi's direct `!` shell is a human action and is not intercepted. Model-invoked `bash` is intercepted.
+- Unknown model tools are denied until the adapter classifies them. This prevents a newly installed effectful tool from silently acquiring authority.
+- 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.
+
+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.