ahead-pi 0.2.0 → 0.2.1

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/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,110 @@
+# Executable AHEAD Workflows
+
+Status: initial vertical slice 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.
+
+## 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 Product Change flow | `docs/workflows/product-change.md` |
+| Executable phases, artifacts, gates, transitions, and capabilities | `spec/workflows/product-change-v0.1.json` |
+| Compact binding agent profile and shared AI behavior | `policy/common.md` |
+| Phase AI behavior | `policy/product-change/*.md` |
+| 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 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.
+- Human-first option and plan artifacts unlock AI assistance in those phases.
+- 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.
+- 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.
+
+## 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.

package/generated/reference/docs/design/process-taxonomy.md

@@ -0,0 +1,144 @@
+# AHEAD Process Taxonomy
+
+Status: proposed design
+Last reviewed: 2026-08-12
+
+## Why classify by outcome
+
+AHEAD should not create a workflow for every issue label. “Security,” “performance,” “data,” “incident,” and “technical debt” often describe risk, domain, urgency, or cause—not the kind of reasoning needed to complete the work.
+
+The primary workflow should be selected by the **dominant outcome** the human is trying to produce. Variants and overlays then adapt that workflow to context.
+
+This gives AHEAD six proposed process families. All six now have minimal [pilot workflow profiles](../workflows/README.md) for use and evaluation; that does not yet validate the taxonomy or justify automated enforcement.
+
+## The six process families
+
+| Process family | Dominant question | Terminal outcome | Examples | Status |
+|---|---|---|---|---|
+| 1. [Product change](../workflows/product-change.md) | What behavior or capability should exist, and how should we deliver it? | Verified intended behavior | Feature, API change, integration, migration, dependency adaptation, decommission | Pilot v0.1 |
+| 2. [Corrective debugging](../workflows/corrective-debugging.md) | Why does observed behavior differ from intended behavior, and how should we correct it? | Verified correction or explicitly accepted uncertainty | Deterministic bug, flaky failure, regression, incorrect data processing | Pilot v0.1 |
+| 3. [Operational stabilization](../workflows/operational-stabilization.md) | Why is a live system outside an acceptable operating state, and how do we restore and stabilize it? | Demonstrated recovery/convergence and follow-up disposition | Reconciliation storm, capacity exhaustion, configuration drift, dependency outage | Pilot v0.1 |
+| 4. [Decision](../workflows/decision.md) | Which course should humans choose, given goals, evidence, constraints, and tradeoffs? | Approved decision and rationale | Architecture decision, buy/build, technology selection, policy or platform choice | Pilot v0.1 |
+| 5. [Investigation](../workflows/investigation.md) | What is true, feasible, or likely when no intervention has yet been selected? | Bounded conclusion, confidence, evidence, and remaining unknowns | Technical spike, feasibility study, causal follow-up, capacity study, vendor evaluation | Pilot v0.1 |
+| 6. [Internal improvement](../workflows/internal-improvement.md) | How can we improve system qualities while preserving an explicit behavioral contract? | Verified invariants plus improved target qualities | Refactor, preventive maintenance, maintainability debt, performance optimization without semantic change | Pilot v0.1 |
+
+Six is a working taxonomy, not a sacred number. The threshold for adding a seventh family is deliberately high.
+
+## Selection test
+
+```text
+Is the primary outcome new or changed externally meaningful behavior?
+  → Product change
+
+Is an observed behavior wrong and the main work is causal diagnosis plus correction?
+  → Corrective debugging
+
+Is a live system unhealthy, unstable, or failing to converge, with restoration as the immediate outcome?
+  → Operational stabilization
+
+Is the deliverable an accountable choice among alternatives?
+  → Decision
+
+Is the deliverable knowledge or reduced uncertainty, without a predetermined change?
+  → Investigation
+
+Must behavior remain invariant while internal qualities improve?
+  → Internal improvement
+```
+
+A large effort may link several runs. An architecture decision can lead to a product change. An incident can create an operational investigation, a corrective bug, and an internal-improvement follow-up. A technical spike can end in a decision without pretending that knowledge production and option selection are the same activity.
+
+## Why the additional three differ
+
+### Decision
+
+A feature includes decisions, but some engineering work ends with a decision rather than code. Its quality depends on framing, option coverage, evidence, tradeoffs, consequences, reversibility, and accountable approval. Forcing it through implementation and deployment creates meaningless states.
+
+### Investigation
+
+An investigation begins with a question, not an assumed defect or desired change. It may conclude that no action is needed, evidence is insufficient, a vendor owns the behavior, or several interventions remain viable. Its terminal quality is epistemic: evidence, confidence, limitations, and unknowns.
+
+### Internal improvement
+
+Refactoring and preventive work are judged differently from feature work. They begin by specifying invariants and target qualities. Success means that required behavior was preserved while maintainability, performance, safety, comprehensibility, or another quality improved. Treating this as a feature encourages invented product outcomes; treating it as a bug assumes a failure that may not exist.
+
+## Overlays, not primary processes
+
+### Incident mode
+
+Incident mode represents urgency, impact, coordination, containment, communication, and recovery. It can overlay corrective debugging, operational stabilization, a security event, or a data issue. It relaxes nonessential documentation during response but strengthens action authorization and decision logging.
+
+### Security
+
+Security adds confidentiality, evidence preservation, threat modeling, restricted AI access, disclosure, and security approval. A vulnerability may use corrective debugging; proactive hardening may use internal improvement; an active compromise may use incident-mode operational stabilization; a threat assessment may use investigation.
+
+### Safety, regulatory, and compliance
+
+These overlays strengthen traceability, independence, evidence retention, required reviewers, and non-waivable gates. They do not change whether the underlying work is a change, correction, operation, decision, investigation, or improvement.
+
+### Emergency
+
+Emergency handling changes sequencing and permits explicitly governed deferrals. It does not erase human accountability or evidence requirements; it moves some reconstruction and learning after stabilization.
+
+## Labels and modifiers
+
+Context belongs in typed modifiers rather than new workflow definitions:
+
+```yaml
+process: operational-stabilization
+urgency: incident
+domain: infrastructure
+assurance: standard
+failure_character: intermittent
+environment: production
+data_classification: internal
+```
+
+Useful modifiers may include:
+
+- urgency: normal, expedited, incident, emergency;
+- assurance: standard, security, safety-critical, regulated;
+- environment: local, test, staging, production, external provider;
+- failure character: deterministic, intermittent, performance, data, distributed, unknown;
+- change character: additive, adaptive, migration, retirement;
+- reversibility and blast radius;
+- evidence sensitivity.
+
+## Where common work maps
+
+| Work label | Primary process or routing rule |
+|---|---|
+| Feature | Product change |
+| Bug | Corrective debugging |
+| Production reconciliation storm | Operational stabilization; add incident mode when impact/urgency warrants it |
+| Architecture decision | Decision; link resulting implementation separately |
+| Technical debt | Internal improvement when preserving behavior; product change when behavior changes; corrective debugging when it represents a known defect |
+| Refactor | Internal improvement |
+| Performance regression | Corrective debugging |
+| Proactive performance optimization | Internal improvement or product change, depending on whether performance is a new product outcome |
+| Security vulnerability | Corrective debugging plus security overlay |
+| Active security compromise | Operational stabilization plus incident and security overlays |
+| Security hardening | Internal improvement or product change plus security overlay |
+| Research spike | Investigation |
+| Compliance audit | Investigation plus compliance overlay; corrective or improvement runs handle findings |
+| Dependency or platform upgrade | Product change with adaptive-change modifier |
+| Service retirement | Product change with retirement and risk modifiers |
+
+## Test for adding another family
+
+A new primary process family should be added only when all of these are true:
+
+1. It has a distinct terminal outcome.
+2. It has a distinct central reasoning loop.
+3. It requires materially different human decisions or gates.
+4. It cannot be represented clearly as a variant, overlay, modifier, or linked combination of existing families.
+5. Evidence or repeated practice shows that using an existing family creates confusion, unsafe behavior, or process theater.
+6. The additional cognitive and tooling cost is justified.
+
+## Evidence basis and limits
+
+[ISO/IEC/IEEE 12207:2026](https://standards.ieee.org/ieee/12207/11416/) covers development, operation, maintenance, support, and retirement and allows processes to operate concurrently, iteratively, and recursively. [ISO/IEC/IEEE 14764:2022](https://www.iso.org/standard/80710.html) separately establishes software-maintenance types. These standards support broad coverage and composition, but they do not validate this six-family taxonomy.
+
+Empirical debugging research supports a mental-model and hypothesis-testing process distinct from planned change. Empirical production-incident research distinguishes code and non-code causes and separates detection, investigation, and mitigation. Those findings support keeping corrective debugging and operational stabilization separate.
+
+The proposed six-family classification itself remains an AHEAD design hypothesis. The pilot profiles should be tested against a diverse sample of real engineering work by asking whether teams can route work consistently, whether important states or gates differ, which records improve reasoning or handoff, and whether any family is rarely used or routinely misclassified.