ahead-pi 0.2.0 → 0.3.0

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.

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/engineering-practice.md

@@ -0,0 +1,163 @@
+# AHEAD Engineering Practice
+
+Status: proposed guidance
+
+## Purpose
+
+AHEAD is not only a sequence of AI gates. It is a way of practicing engineering. This guide distills general habits from the submitted starting list into a smaller set of principles that can be remembered, applied, and evaluated.
+
+Many of these ideas come from practitioner literature rather than controlled experiments. The source type matters: a useful craft principle can guide work without being misrepresented as science.
+
+The submitted notes include page-level references to *The Pragmatic Programmer*. Those locators are preserved in the [edition-specific page index](references/pragmatic-programmer-page-index.md) and grouped below so the distillation remains traceable to its source. Additional submitted tips, complete checklists, and practices are retained in the [submitted engineering notes](references/submitted-engineering-notes.md); the practice guide condenses them without replacing that source record.
+
+## 1. Care about the craft and own the result
+
+Engineering quality begins with attention, pride, and accountability. Treat code, documentation, tests, operations, and communication as parts of one professional result. Do not submit work merely because a tool produced it or a check passed.
+
+Basis: *The Pragmatic Programmer* tips 1 (p. xlx as submitted) and 70 (p. 258), Toyota's human-centered improvement philosophy, and AHEAD's constitution.
+
+## 2. Think deliberately
+
+Stay aware of what you are doing and why. Critique assumptions, inspect evidence, and resist autopilot—whether the automation is an IDE wizard, framework convention, copied snippet, or AI assistant.
+
+When a tool proposes an answer, ask what would disprove it and what information it could not see.
+
+Basis: *The Pragmatic Programmer* tips 2 (p. xlx as submitted), 9 (p. 16), 27 (p. 97), and 44 (p. 175), plus direct debugging research on mental models and hypothesis testing.
+
+## 3. Start from users, domain, and real constraints
+
+Requirements are discovered and refined, not merely received. Work with users and domain experts, use their language, identify the desired outcome, and separate real constraints from inherited habits.
+
+Quality is contextual. Reliability, latency, accessibility, security, cost, maintainability, and delivery time do not have one universal ordering; accountable humans decide what the work requires.
+
+Basis: requirements and traceability research, ISO/IEC/IEEE life-cycle standards, and *The Pragmatic Programmer* tips 7 (p. 11), 17 (p. 58), 51 (p. 202), 52 (p. 204), 54 (p. 210), and 55 (p. 213).
+
+## 4. Make reasoning visible
+
+Record important assumptions, options, decisions, tradeoffs, evidence, uncertainty, and changes in understanding. Link intent to implementation and verification without creating documents that nobody uses.
+
+Traceability should help future engineers understand why and where—not become compliance theater.
+
+Basis: controlled evidence that requirements-to-code traceability can improve maintenance-task performance, AHEAD's evidence standard, and *The Pragmatic Programmer* tips 10 (p. 21), 18 (p. 64), 19 (p. 69), 20 (p. 74), and 23 (p. 88).
+
+## 5. Prefer simple, local reasoning
+
+Choose designs that minimize the number of concepts a person must hold simultaneously. Keep unrelated concerns independently changeable. Make state explicit and contained. Keep policy distinct from mechanism. Prefer stable values, plain data, clear interfaces, and declarative rules when they fit the problem.
+
+Modularity is not automatically simplicity: separate modules can remain tightly coupled through hidden assumptions, timing, shared state, or required call order.
+
+Basis: Rich Hickey's *Simple Made Easy* and *The Pragmatic Programmer* tips 11 (p. 27), 13 (p. 35), 36 (p. 140), 41 (p. 156), and 42 (p. 161). These are design heuristics, not universal experimental laws.
+
+## 6. Design for change without speculative machinery
+
+Decisions can be revised, so record their rationale, reversibility, and review triggers. Avoid building generalized infrastructure for hypothetical futures. Make the current change coherent and create seams where evidence shows variation is likely.
+
+Use a “rule of three” only as a prompt for judgment, not a mechanical law. Duplication of knowledge is more dangerous than superficially similar code; premature abstraction can couple cases that should evolve separately.
+
+Basis: *The Pragmatic Programmer* tips 4 (p. 5), 12 (p. 33), 14 (p. 46), 47 (p. 186), and 53 (p. 209). The precise abstraction threshold is context-dependent.
+
+## 7. Prototype to learn
+
+Use prototypes, spikes, tracer paths, and small vertical experiments to test uncertain architecture, integrations, data, performance, and user interaction. State the learning question and disposal plan first.
+
+This is a legitimate place for full “vibe coding”: AI may rapidly generate the whole experiment when speed of learning matters more than understanding or maintainability of the artifact. Keep it isolated, label it `PROTOTYPE — NOT FOR PRODUCTION`, exclude production credentials and sensitive data, and do not treat a convincing demo as evidence of correctness or readiness.
+
+Prototype code does not silently become production code. Preserve the learning, then discard the implementation. If any code is retained, it leaves the prototype exception and enters the normal human-understanding, design, implementation, test, security, and review process.
+
+Basis: empirical software-prototyping research, *The Pragmatic Programmer* tips 15 (p. 49) and 16 (p. 54), its prototyping checklist (p. 53), and AHEAD's Investigation process hypothesis. The evidence supports prototyping as a learning practice; the permission for full AI generation inside strict boundaries is AHEAD policy.
+
+## 8. Automate repeatable mechanics
+
+Use source control, shells, scripts, formatters, generators, CI, and other automation to make repeatable operations consistent and inspectable. Automation should remove drudgery while leaving intent, effects, and failures visible.
+
+Do not automate a process you cannot evaluate. Judge tools by the long-lived artifacts and operational behavior they produce, not only authoring convenience or initial speed.
+
+Basis: *The Pragmatic Programmer* tips 21 (p. 80), 22 (p. 85), 28 (p. 100), 29 (p. 103), and 61 (p. 231), NIST secure-development guidance, and AHEAD's Toyota analogy.
+
+## 9. Design for testing and failure
+
+Think about verification before implementation. Define observable behavior, invariants, boundaries, significant states, failure modes, resource exhaustion, recovery, and performance expectations.
+
+Coverage is evidence about execution, not proof of correctness. Test the tests through mutation, fault injection, or known negative cases where proportionate. When a defect is fixed, preserve a regression check when one can reliably express the failure.
+
+Basis: software-testing research and *The Pragmatic Programmer* tips 30–35 (pp. 107–129), 48–50 (pp. 192–199), and 62–66 (pp. 237–247). Evidence for specific methods such as strict test-driven development is mixed and context-dependent; AHEAD does not mandate one universal test-writing order.
+
+## 10. Debug with evidence, not confidence or blame
+
+Do not panic, guess from the loudest log, or assume the platform is broken. Establish the observation, characterize it, build a mental model, generate hypotheses, predict discriminating results, test safely, and update the model.
+
+Treat application code, dependencies, infrastructure, configuration, data, operator actions, and external systems as candidates whose likelihood changes with evidence. Focus on restoring and improving the system rather than protecting or assigning personal blame.
+
+Basis: direct empirical debugging and incident-response studies, plus *The Pragmatic Programmer* tips 24–27 (pp. 91–97) and debugging checklist (p. 98).
+
+## 11. Review independently and communicate honestly
+
+Review is a reasoning activity, not an approval button. Review the current artifact against intended behavior, architecture, risks, tests, operations, and maintainability. Automated and AI review add coverage; they do not replace accountable human judgment. A lasting engineering change requires review by a person other than the implementer; implementer self-review is still necessary, but it does not satisfy that independent gate.
+
+Technical communication should be clear, audience-aware, and grounded in the author's understanding. State observed fact, interpretation, uncertainty, decision, and request distinctly. Do not polish weak understanding into false confidence.
+
+Basis: empirical code-review research, NIST generative-AI risk guidance, and *The Pragmatic Programmer* tips 3 (p. 3), 10 (p. 21), and 67–70 (pp. 248–258).
+
+## 12. Learn continuously and measure the tools
+
+Build breadth by learning new languages, paradigms, ecosystems, tools, and operational models. Reimplementing a small system in contrasting languages can reveal how type systems, concurrency models, package managers, and idioms change design choices.
+
+Do not infer learning or productivity from ease, enjoyment, or generated volume. Measure relevant outcomes. AI studies currently show both productivity gains and losses in different settings, and emerging evidence shows that full delegation can reduce skill formation.
+
+Basis: randomized AI/developer studies, *The Pragmatic Programmer* tips 8 (p. 14), 9 (p. 16), 58 (p. 220), and 59 (p. 222), and the Toyota principle that human skill and automation should improve together.
+
+## Compact working checklist
+
+Before implementation:
+
+- What user or operational outcome are we changing?
+- Which constraints are real, and which are assumptions?
+- What is the simplest model of the problem?
+- Which concerns can vary independently?
+- What must remain invariant?
+- How will we know the change works and fails safely?
+- Are we prototyping to learn or building production code?
+- If this is a disposable prototype, what is its learning question, isolation boundary, and disposal date?
+
+Before accepting AI-assisted work:
+
+- Can the responsible engineer explain and change it?
+- Did the AI define behavior that a human should own?
+- Are claims, sources, dependencies, and commands verified?
+- Did AI-generated tests inherit the implementation's assumptions?
+- Was sensitive context authorized for the selected tool?
+- Has a person other than the implementer independently reviewed every lasting engineering change, with additional specialist review proportionate to risk?
+
+Before merge or delivery:
+
+- Does the change trace to the approved problem and decision?
+- Are tests meaningful, current, and capable of failing?
+- Are failure, rollback, observation, and recovery understood?
+- Did review examine system behavior rather than only style?
+- Is the documentation close enough to the system to remain accurate?
+- What accepted uncertainty or follow-up remains?
+
+## Recommended reading and viewing
+
+These are recommended practitioner sources, not scientific proof of AHEAD:
+
+- David Thomas and Andrew Hunt, [*The Pragmatic Programmer: Your Journey to Mastery*, 20th Anniversary Edition](https://pragprog.com/titles/tpp20/the-pragmatic-programmer-20th-anniversary-edition/), ISBN 9780135957059.
+  - AHEAD preserves the submitted print-page locators in its [Pragmatic Programmer page index](references/pragmatic-programmer-page-index.md).
+- Luca Palmieri, [*Zero To Production In Rust*](https://www.zero2prod.com/), ISBN 9798847211437. This is a concrete production-backend learning path rather than a general philosophy source.
+- Richard Hamming, [*The Art of Doing Science and Engineering: Learning to Learn*](https://press.stripe.com/the-art-of-doing-science-and-engineering), ISBN 9781732265172.
+- Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+## Research sources
+
+- [Liang et al., *A Qualitative Study on the Implementation Design Decisions of Developers*](https://arxiv.org/abs/2301.09789)
+- [Egyed and Mäder, *Do developers benefit from requirements traceability when evolving and maintaining a software system?*](https://doi.org/10.1007/s10664-014-9314-z)
+- [Li and Coblenz, *A Grounded Theory of Debugging in Professional Software Engineering Practice*](https://arxiv.org/abs/2602.11435)
+- [Alaboudi and LaToza, *Using Hypotheses as a Debugging Aid*](https://doi.org/10.1109/VL/HCC50065.2020.9127273)
+- [Sillito and Kutomi, *Failures and Fixes*](https://doi.org/10.1109/ICSME46990.2020.00027)
+- [McIntosh et al., *The Impact of Modern Code Review Practices on Software Quality*](https://doi.org/10.1007/s10664-015-9381-9)
+- [Shen and Tamkin, *How AI Impacts Skill Formation*](https://arxiv.org/abs/2601.20245)
+- [Cui et al., *The Effects of Generative AI on High-Skilled Work*](https://doi.org/10.1287/mnsc.2025.00535)
+- [Becker et al., *Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity*](https://arxiv.org/abs/2507.09089)
+- [Bjarnason, Lang, and Mjöberg, *An empirically based model of software prototyping*](https://doi.org/10.1007/s10664-023-10331-w)
+
+Detailed applicability and limitations belong in the [AHEAD research map](evidence/research-map.md).

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

@@ -0,0 +1,123 @@
+# AHEAD Evidence Standard
+
+Status: proposed
+
+## Purpose
+
+AHEAD should be supported by the best available evidence without claiming more certainty than software-engineering research can provide. A credible methodology must distinguish evidence for a descriptive claim from evidence that a particular prescribed workflow improves outcomes.
+
+No paper should be cited merely because its title resembles an AHEAD principle. For every material process rule, AHEAD records what was studied, how it was studied, what outcome was observed, how directly it applies, and what remains unknown.
+
+## Evidence classes
+
+### E1 — Direct empirical software-engineering evidence
+
+Experiments, field experiments, observational studies, repository studies, or qualitative studies of professional software work that directly examine the behavior or outcome in question.
+
+Examples: programmers debugging real code, developers using AI coding tools, or production responders handling incidents.
+
+### E2 — Adjacent empirical evidence
+
+Empirical research on a relevant cognitive, organizational, safety, or creative process outside the precise software-engineering context.
+
+Adjacent evidence can motivate an AHEAD hypothesis. It does not prove that the same intervention will work in software engineering.
+
+### E3 — Consensus standard or authoritative guidance
+
+Standards and institutional guidance such as ISO/IEC/IEEE life-cycle standards or NIST incident-response publications. These establish vocabulary, expected controls, and professional consensus. They are not necessarily controlled evidence that one process outperforms another.
+
+### E4 — Documented practitioner evidence
+
+Published operating practices, case reports, experience reports, or durable methods from organizations and practitioners. This evidence can reveal feasible practices and important failure modes, but is vulnerable to selection bias and local context.
+
+Toyota's human-centered automation philosophy belongs here.
+
+### E5 — AHEAD design hypothesis
+
+A plausible process rule derived from principles, indirect evidence, or design judgment but not directly validated. It must be labeled as a hypothesis and paired with an evaluation plan before being promoted as evidence-backed.
+
+The requirement that a human always produce the first option and first-pass plan is currently E5, with partial E2 support related to AI anchoring and diversity. It is a normative AHEAD commitment, but its exact implementation still needs evaluation.
+
+## Required evidence record
+
+Each material process claim should record:
+
+```yaml
+claim: Human-originated options should precede AI-generated alternatives.
+status: design-hypothesis
+evidence_class: [E2, E5]
+sources:
+  - study: Generative AI enhances individual creativity but reduces collective diversity
+    population: 293 short-story writers
+    result: AI ideas improved evaluated individual output, but outputs became more similar across participants
+applicability: Indirect evidence of anchoring and convergence; not a software-design study.
+counterevidence: AI ideas improved several individual quality measures.
+decision: Pilot human-first option capture, then measure option diversity and decision quality.
+owner: methodology maintainers
+review_date: 2027-01-31
+```
+
+At minimum, a record includes:
+
+- precise claim;
+- evidence class;
+- source and study design;
+- population, tasks, and environment;
+- observed outcome;
+- applicability to AHEAD;
+- limitations and counterevidence;
+- resulting process decision;
+- confidence and review date;
+- proposed validation measure for an AHEAD hypothesis.
+
+## Source policy
+
+- Prefer peer-reviewed primary research for scientific claims.
+- Prefer the original standard or issuing institution for normative guidance.
+- Use systematic reviews to understand a field, then cite primary studies for specific claims when practical.
+- Use vendor or practitioner reports as E4 and disclose the source's interest and context.
+- Do not convert correlation into causation.
+- Do not generalize from students to professionals, small exercises to mature systems, or one organization to all engineering without stating the limitation.
+- Preserve null, mixed, and contrary results.
+- Re-check AI evidence frequently because tools, adoption skill, and work patterns change quickly.
+
+## From evidence to process
+
+Evidence rarely supplies a complete workflow. AHEAD uses this chain:
+
+```text
+Observed evidence
+→ bounded claim
+→ applicability analysis
+→ proposed process mechanism
+→ pilot
+→ measured outcome
+→ retain, revise, or remove
+```
+
+A process rule should become mandatory only when:
+
+1. it protects a constitutional value or meaningful risk;
+2. its mechanism is explicit;
+3. the burden is proportionate to that risk;
+4. there is direct evidence, strong professional consensus, or favorable AHEAD pilot data;
+5. exceptions can be handled safely and visibly;
+6. the team can measure whether the rule is producing its intended result rather than paperwork.
+
+## Evaluation outcomes
+
+AHEAD should evaluate more than delivery speed:
+
+- correctness and escaped defects;
+- decision quality and reversals;
+- option and hypothesis diversity;
+- time to understanding, diagnosis, mitigation, and recovery;
+- operator and reviewer ability to explain the system and change;
+- traceability from intent through outcome;
+- review findings and their novelty;
+- recurrence and corrective-action completion;
+- workflow burden and bypass rate;
+- perceived speed compared with measured speed;
+- learning and retention over time.
+
+The methodology should publish negative findings. If a gate adds delay without improving understanding, decision quality, safety, or learning, it should be changed or removed.

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

@@ -0,0 +1,98 @@
+# AHEAD Research Map
+
+Status: living evidence review
+Last reviewed: 2026-08-12
+
+This document maps current AHEAD design claims to available evidence. It is not a bibliography of everything related to software engineering. It focuses on claims that materially shape the methodology.
+
+Evidence classes are defined in the [AHEAD Evidence Standard](evidence-standard.md).
+
+## Human-led, AI-amplified engineering
+
+| AHEAD claim | Evidence | Class | What it supports | Important limitation |
+|---|---|---:|---|---|
+| AI can create meaningful developer leverage. | [Cui et al., *The Effects of Generative AI on High-Skilled Work*](https://doi.org/10.1287/mnsc.2025.00535) combined randomized field experiments at three companies and 4,867 developers; access to a coding assistant was associated with a 26.08% increase in completed tasks, with larger gains among less-experienced developers. | E1 | AHEAD should use AI materially rather than treating it only as a risk. | The intervention was code completion, the experiments were noisy, and completed tasks do not capture understanding or long-term quality. |
+| AI's productivity effect is contextual and must be measured. | [Becker et al., *Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity*](https://arxiv.org/abs/2507.09089) randomized 246 tasks performed by 16 experienced developers in familiar repositories; AI access increased completion time by 19% even though developers believed it had saved time. | E1 | Measure outcomes instead of assuming felt productivity equals actual productivity. Allow AI use to vary by task and expertise. | Small sample, early-2025 tools, experienced open-source developers, and mature familiar repositories. It does not negate larger positive field studies. |
+| Human-independent thought before AI may preserve diversity. | [Doshi and Hauser, *Generative AI enhances individual creativity but reduces the collective diversity of novel content*](https://doi.org/10.1126/sciadv.adn5290) experimentally studied 293 short stories. AI ideas improved several individual evaluations but made outputs more similar to one another. | E2 | Provides a mechanism for testing human-first option generation: AI suggestions may improve individual output while narrowing the collective search space. | Creative writing is not software design. This does not directly validate AHEAD's exact sequencing or a mandatory human-first gate. |
+| Human capability and automation should improve together. | [Toyota Production System](https://global.toyota/en/company/vision-and-philosophy/production-system/) and [Toyota's account of skilled manufacturing](https://global.toyota/en/newsroom/corporate/35433493.html). | E4 | Establishes a durable practitioner analogy for human-centered automation and improvement through direct mastery. | Manufacturing is not software engineering, and an organizational philosophy is not controlled evidence. |
+
+### Current conclusion
+
+The evidence supports using AI and evaluating it contextually. It gives indirect support for protecting independent thought, but the exact rule “human produces the first option or plan” remains an AHEAD design hypothesis. AHEAD should pilot that rule and measure option diversity, decision quality, explanation quality, and workflow burden.
+
+## Acceptable AI use
+
+| AHEAD claim | Evidence | Class | What it supports | Important limitation |
+|---|---|---:|---|---|
+| AI assistance should build comprehension, not only produce code. | [Shen and Tamkin, *How AI Impacts Skill Formation*](https://arxiv.org/abs/2601.20245) randomized 52 mostly junior software engineers learning an unfamiliar Python library. The AI-assisted group scored lower on a subsequent mastery assessment; interaction style mattered, and explanation/conceptual use was associated with stronger mastery than delegation. | E1 | Prefer explanations, conceptual questions, prediction, and modification when learning; require engineers to understand accepted work. | One short task, one unfamiliar library, mostly junior participants, and a specific assistant. It does not establish long-term skill effects or justify banning AI for learning. |
+| AI can materially assist human test generation and defect discovery. | [Ramler et al., *Unit Testing Past vs. Present*](https://arxiv.org/abs/2502.09801) compared an LLM-supported testing experiment with prior manual-testing experiments and found more tests, coverage, and detected defects, alongside more false positives. | E1 | Allow candidate test generation while requiring human-defined behavior, oracle review, and validation that tests can fail. | Nonconcurrent historical control, master’s-level testing students, seeded defects, and a bounded Java system. More tests and coverage do not prove better production assurance. |
+| Test-guided human interaction can improve evaluation of generated code. | [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/) studied 15 programmers and found the test-guided workflow improved correct evaluation of generated code; the authors also evaluated generation accuracy across models and datasets. | E1 | Define and refine intent through tests rather than asking AI to write code and then trusting tests derived from the same assumptions. | Small user study and an idealized proxy in the scaled evaluation. It does not require strict TDD for all engineering. |
+| AI review findings require human validation and executable evidence. | [Jin and Chen, *Are LLMs Reliable Code Reviewers?*](https://arxiv.org/abs/2603.00539) found systematic overcorrection when models judged requirement conformance, including misclassifying correct implementations as defective. | E1 | Use AI review as a first pass; treat findings as hypotheses and retain final human review. | Benchmark-based study of a specific review judgment. It does not measure every type of real-world review or prove human reviewers are sufficient. |
+| Generated factual and technical content must be verified. | [NIST AI 600-1](https://doi.org/10.6028/NIST.AI.600-1) identifies confabulation, privacy, information integrity, intellectual-property, and related generative-AI risks. | E3 | Verify claims, citations, summaries, code assumptions, and provenance; prohibit AI from inventing evidence or authority. | Cross-sector risk guidance, not a comparative software-development experiment. |
+| AI coding tools require bounded context, permissions, and human validation. | [NIST's DevSecOps reference model](https://pages.nist.gov/nccoe-devsecops/notational-reference-model.html#artificial-intelligence) calls for human monitoring and validation of AI-generated content. The [OWASP Secure Coding with AI Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secure_Coding_with_AI_Cheat_Sheet.html) documents practical context-leakage, agent-permission, test, supply-chain, and CI/CD risks. | E3, E4 | Restrict sensitive context and operational authority; review generated dependencies, commands, pipelines, and security-critical work. | Guidance and threat modeling rather than controlled evidence of AHEAD's specific controls. |
+| Disposable prototypes can accelerate exploration and validation. | [Bjarnason, Lang, and Mjöberg, *An empirically based model of software prototyping*](https://doi.org/10.1007/s10664-023-10331-w) combines a systematic mapping study of 33 primary studies with empirical data from 12 companies. It identifies prototypes used to explore and validate requirements, technical feasibility, business viability, market desirability, and usability. | E1 | Permit rapid, fully AI-generated prototypes when the explicit objective is learning rather than producing production code. | The study concerns prototyping, not generative AI. AHEAD's vibe-coding exception, isolation rules, and mandatory disposal or re-entry are policy choices requiring evaluation. |
+
+### Current conclusion
+
+The evidence supports substantial but bounded AI assistance and supports prototyping as a learning mechanism. It does not establish that AI-generated prototypes are production-ready or that vibe coding is safe outside the prototype boundary. AHEAD's acceptable-use rules combine direct evidence, risk guidance, and constitutional choices; the rules should be reevaluated as tools and work practices change.
+
+## Feature and change work
+
+| AHEAD claim | Evidence | Class | What it supports | Important limitation |
+|---|---|---:|---|---|
+| Implementation is decision-bearing work, not mechanical translation of a plan. | [Liang et al., *A Qualitative Study on the Implementation Design Decisions of Developers*](https://arxiv.org/abs/2301.09789) used 46 survey responses and 14 interviews with professional developers. The study found that implementation decisions require ongoing attention to requirements and architecture and that developers share a general structure without following one identical process. | E1 | Keep humans engaged during implementation; allow iteration back to problem, decision, and plan rather than enforcing a one-way pipeline. | Qualitative and self-reported evidence describes practice; it does not compare AHEAD with another method. |
+| Connecting requirements to implementation can improve maintenance work. | [Egyed and Mäder, *Do developers benefit from requirements traceability when evolving and maintaining a software system?*](https://doi.org/10.1007/s10664-014-9314-z) used a controlled experiment with 71 subjects performing real maintenance tasks on third-party projects; traceability users were faster and produced more correct solutions on average. | E1 | Preserve lightweight links among problem, decision, plan, code, tests, and outcome. | Participants sketched solutions rather than implementing them, and mandatory traceability can become expensive process theater. AHEAD must test a lightweight form. |
+| Human review provides a meaningful quality defense. | [McIntosh et al., *An Empirical Study of the Impact of Modern Code Review Practices on Software Quality*](https://doi.org/10.1007/s10664-015-9381-9) studied Qt, VTK, and ITK and found significant relationships among review coverage, participation, reviewer expertise, and post-release quality. | E1 | Retain accountable human review and treat reviewer expertise and participation as relevant—not just the presence of an approval. | Observational relationships do not establish causality, and the study does not compare AI review with human review. |
+
+### Current conclusion
+
+Evidence supports traceability, iterative decision-making, and substantive human review. The complete feature sequence—especially its exact gates and first-pass-plan rule—still needs AHEAD pilot evidence.
+
+## Debugging
+
+| AHEAD claim | Evidence | Class | What it supports | Important limitation |
+|---|---|---:|---|---|
+| Professional debugging is iterative mental-model construction. | [Li and Coblenz, *A Grounded Theory of Debugging in Professional Software Engineering Practice*](https://arxiv.org/abs/2602.11435) observed 12 professionals on 17 tasks in their own codebases and modeled debugging as iterative diagnosis in which developers update mental models to guide information gathering. | E1 | Make evidence and mental-model revision the center of debugging; do not reduce the workflow to locating code. | Recent qualitative study with a small purposive sample. It describes practice rather than proving one prescribed workflow is superior. |
+| Hypotheses are useful debugging objects, and tools can broaden them. | [Alaboudi and LaToza, *Using Hypotheses as a Debugging Aid*](https://doi.org/10.1109/VL/HCC50065.2020.9127273) found in a controlled experiment with 20 developers that early correct hypotheses predicted success and supplied potential hypotheses made success six times more likely; supplying fault locations did not have the same effect. | E1 | Record competing hypotheses and use AI to propose additional explanations rather than merely pointing at likely files. | Small experiment and specific tasks. AI-generated hypotheses may also be wrong or anchoring; humans must evaluate and test them. |
+
+### Current conclusion
+
+The core loop—evidence → mental model → hypotheses → discriminating test → updated evidence—is directly aligned with empirical descriptions of professional debugging. Human selection and interpretation remain constitutional choices. The amount of required recording must be tested so it does not interrupt reasoning.
+
+## Operational issues and incidents
+
+| AHEAD claim | Evidence | Class | What it supports | Important limitation |
+|---|---|---:|---|---|
+| Incident work contains distinct investigative and mitigative activity. | [Sillito and Kutomi, *Failures and Fixes: A Study of Software System Incident Response*](https://doi.org/10.1109/ICSME46990.2020.00027) qualitatively analyzed 30 incidents using engineer interviews and public incident reports, categorizing investigative and mitigative strategies. | E1 | Keep investigation and service restoration distinct and allow them to proceed in parallel. Capture actions with actor, purpose, result, and evidence. | Qualitative sample of 30 incidents; public postmortems have selection and reconstruction bias. |
+| Production incidents are not limited to application-code bugs. | [Ghosh et al., *How to Fight Production Incidents?*](https://doi.org/10.1145/3542929.3563482) studied hundreds of high-severity incidents in a large cloud service and explicitly included software and non-code causes while separating detection, root-cause work, and mitigation. | E1 | Maintain an operational-issue process separate from bug debugging; represent infrastructure, configuration, dependency, capacity, and emergent-system causes. | One large cloud service; internal taxonomies and operating environment may not generalize directly. |
+| Incident response requires preparation, detection/analysis, response, recovery, and improvement. | [NIST SP 800-61 Rev. 3](https://doi.org/10.6028/NIST.SP.800-61r3) integrates incident response across cybersecurity risk management. | E3 | Supports preparation and learning outside the active incident and the separation of response and recovery concerns. | Cybersecurity guidance, not an experiment and not a complete model for every reliability incident. |
+
+### Current conclusion
+
+Operational issues merit a distinct process. “Incident” is best treated as an urgency and coordination mode that adds containment, recovery, communication, and decision logging to the underlying bug, operational, security, or data work.
+
+## Security and assurance
+
+| AHEAD claim | Evidence | Class | What it supports | Important limitation |
+|---|---|---:|---|---|
+| Human and automated review are complementary. | [Yu et al., *Security Defect Detection via Code Review*](https://arxiv.org/abs/2307.02326) analyzed 20,995 candidate comments from OpenStack and Qt, identifying 614 security-related comments; the authors conclude that security practice should combine context-sensitive manual review with automated detection. | E1 | Treat AI and automation as additional assurance rather than replacements for contextual human security review. | Repository study of four open-source projects; it studied automated tools generally, not current generative-AI review. |
+
+### Current conclusion
+
+Security should normally be an overlay adding confidentiality, evidence handling, threat modeling, disclosure, and approval rules. The underlying work may still be corrective debugging, operational response, investigation, decision-making, or planned change.
+
+## Process taxonomy
+
+[ISO/IEC/IEEE 12207:2026](https://standards.ieee.org/ieee/12207/11416/) describes software life-cycle processes across conception, development, operation, maintenance, support, and retirement, and explicitly allows processes to be concurrent, iterative, recursive, and incremental. [ISO/IEC/IEEE 14764:2022](https://www.iso.org/standard/80710.html) separately details software maintenance and its types.
+
+These standards support broad coverage and a composable lifecycle. They do not prescribe AHEAD's workflow count. The proposed six-family taxonomy is therefore an AHEAD design decision informed by standards, empirical work, and the desire to minimize workflow proliferation.
+
+## Research gaps AHEAD should test
+
+1. Does recording a human option before showing AI alternatives increase option diversity or decision quality?
+2. Does a human first-pass plan improve later explanation, defect rate, or plan compliance compared with an AI-first plan reviewed by a human?
+3. How much debugging structure helps professionals before the recording burden disrupts their mental-model work?
+4. Does AI-generated hypothesis support reproduce the benefits of researcher-supplied hypotheses without causing anchoring or excess testing?
+5. Does a separate operational-issue workflow reduce time to mitigation or improve causal accuracy compared with treating every production problem as a bug?
+6. Does AI review find additional important issues without weakening the attention or independence of subsequent human reviewers?
+7. Which gates improve outcomes, and which produce only approval or documentation theater?