ahead-pi 0.2.0 → 0.2.1

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?

package/generated/reference/docs/rationale.md

@@ -0,0 +1,210 @@
+# Why AHEAD
+
+## Human-led engineering, amplified by AI
+
+AI can make software engineering faster. It can search broadly, synthesize information, identify omissions, generate alternatives, produce routine code, explain unfamiliar systems, and review more material than a person can inspect unaided.
+
+Those capabilities create real leverage. They also create a temptation to optimize for the visible artifact—an answer, design, plan, or code change—while weakening the human understanding that makes the artifact trustworthy.
+
+AHEAD exists because software engineering is not merely the production of code. It is the development and application of judgment under incomplete information. Engineers frame problems, construct mental models, decide which tradeoffs matter, test explanations, recognize abnormalities, and remain accountable when systems affect other people.
+
+The goal is therefore not maximum AI autonomy. It is a stronger combined engineering system in which automation increases human capability without displacing the thinking required to direct, evaluate, and improve it.
+
+The central principle is:
+
+> **Human thinks first → AI amplifies and challenges → Human decides.**
+
+## The Toyota lesson
+
+In 2014, Bloomberg reported that Toyota was putting skilled people back into selected production processes that had been automated. The objective was not nostalgia or the wholesale rejection of robots. Toyota wanted workers to deepen their manual knowledge of how parts were made so they could discover improvements and build better processes and machines.
+
+Toyota's own description of the Toyota Production System gives the broader principle. Its concept of *jidoka* is commonly described as “automation with a human touch.” Toyota explains that people first need to understand work well enough to perform it, detect abnormalities, remove waste and inconsistency, and then embody that learning in machinery. Automation handles repeatable work, while people supply judgment and *kaizen*—continuous improvement.
+
+Toyota has continued to describe its approach as automation centered on people. Its position is not that machines are undesirable. It is that machines do not independently determine what improvement means. Human skill and technological capability must develop together.
+
+That is the analogy AHEAD applies to software engineering.
+
+AI can generate an implementation without possessing the team's lived understanding of its customers, constraints, architecture, operations, risk tolerance, or long-term intent. If engineers become reviewers of artifacts they did not reason toward, they may gradually lose the ability to recognize subtle errors, challenge framing, diagnose novel failures, or improve the engineering process itself.
+
+AHEAD therefore keeps humans engaged in the parts of engineering that create and exercise judgment. AI is used aggressively where it expands human reach, but not in ways that turn engineers into passive supervisors of a process they no longer understand.
+
+The analogy has limits. Software development is not an assembly line, generative AI is not an industrial robot, and Toyota's experience does not prove a particular software methodology. The useful lesson is narrower: **capability that is fully delegated can stop developing, and people need direct contact with the work to recognize abnormalities and invent better ways of doing it.**
+
+Sources:
+
+- [Humans Replacing Robots Herald Toyota's Vision of Future — Bloomberg, 2014](https://www.bloomberg.com/news/articles/2014-04-06/humans-replacing-robots-herald-toyota-s-vision-of-future)
+- [Toyota Production System — Toyota Motor Corporation](https://global.toyota/en/company/vision-and-philosophy/production-system/)
+- [Skilled Manufacturing Key to the Future — Toyota Motor Corporation](https://global.toyota/en/newsroom/corporate/35433493.html)
+
+## Understanding is productive capacity
+
+An engineer's mental model is part of the organization's productive capacity. It enables the engineer to:
+
+- determine whether the requested solution addresses the real problem;
+- recognize when a generated answer is plausible but wrong;
+- reason about behavior that is not represented in the immediate prompt;
+- debug unfamiliar or emergent failures;
+- make safe changes under time pressure;
+- explain and defend architectural decisions;
+- teach teammates and improve tools and processes;
+- remain accountable for the result.
+
+Code produced quickly without corresponding understanding can create hidden debt. The organization receives an artifact, but it may lose the ability to operate and evolve that artifact safely. AHEAD treats understanding as a required engineering outcome rather than incidental overhead.
+
+## Why humans think first
+
+AI suggestions are influential even when they are weak. Once an apparently coherent answer is present, people tend to evaluate that answer instead of exploring the problem independently. The question can quietly change from “What do we think is right?” to “Can we find a reason to accept or reject what the AI proposed?”
+
+AHEAD asks the human to contribute first where independent judgment matters:
+
+- define the problem and desired outcome;
+- state an initial understanding or set of questions;
+- propose at least one option before AI expands the option space;
+- select debugging hypotheses and tests;
+- choose the decision and accept its tradeoffs;
+- write the first-pass implementation or remediation plan;
+- own the implementation; for lasting changes, a different human performs the final engineering review.
+
+The first human contribution does not need to be polished or complete. Its purpose is to make the person's current mental model visible before AI influences it. AI can then do what it is particularly good at: broaden the search, find contradictions, identify omissions, generate counterarguments, and expose assumptions.
+
+## Why AI still matters
+
+Human-led does not mean AI-last, AI-light, or manually performing every task. Refusing useful automation would also weaken engineering.
+
+AI can improve the process by:
+
+- researching internal and external sources;
+- compiling evidence and tracing claims back to sources;
+- identifying missing questions and contradictory information;
+- proposing additional options after the human has framed the space;
+- arguing against a preferred approach;
+- generating debugging hypotheses and discriminating tests;
+- assisting with bounded implementation, tests, and mechanical changes;
+- reviewing correctness, security, architecture, test coverage, and plan compliance;
+- comparing observed outcomes with original intent;
+- preserving and connecting engineering knowledge.
+
+The correct boundary is not “human work” versus “AI work.” It is **human accountability and judgment supported by appropriately scoped AI capabilities**.
+
+## Why decisions remain human
+
+Engineering decisions are rarely determined by technical facts alone. They encode product priorities, acceptable risk, reversibility, organizational capability, operational burden, opportunity cost, and obligations to users.
+
+AI can make those considerations visible, but it cannot legitimately accept their consequences for the organization. AHEAD therefore requires humans to select approaches, record rationale and tradeoffs, accept unresolved uncertainty, and approve consequential actions.
+
+This is not ceremonial approval. If a human cannot explain the decision and the evidence behind it, the workflow has produced an approval record without producing accountable engineering.
+
+## Why debugging remains human-led
+
+Debugging is not simply locating a suspicious line of code. It is an iterative process of constructing and correcting a model of reality:
+
+```text
+Facts → mental model → hypothesis → test
+→ updated evidence → revised model → conclusion
+```
+
+AI can generate many plausible explanations and suggest evidence to collect. Humans still choose which explanations are credible enough to test, authorize safe experiments, interpret results in context, and decide when the evidence justifies a conclusion or intervention.
+
+This matters even more for operational systems. A production failure may not be a software bug. It may arise from reconciliation behavior, configuration drift, capacity, an external provider, timing, data, or an emergent interaction between individually functioning components. Investigation requires an understanding of desired versus actual state, timelines, control loops, scope, and recovery signals. AHEAD supports that human reasoning rather than reducing every failure to AI-assisted source-code search.
+
+## Why AI review does not replace human review
+
+AI review and human review provide different defenses.
+
+AI can consistently compare a large changeset against requirements, plans, common defect patterns, security concerns, and missing tests. It can revisit the work without fatigue and produce useful challenges.
+
+Human reviewers understand organizational context, implicit architectural boundaries, operational history, product consequences, and whether the implementation is one the team is willing and able to own. They also carry accountability that an AI system cannot.
+
+AHEAD uses AI review before final human review. For a lasting engineering change, that final review is performed by a person other than the implementer. The AI broadens scrutiny; the independent human reviewer makes the final engineering judgment. In an emergency, review may be deferred to restore service, but it remains due after stabilization.
+
+## The failure modes AHEAD is designed to prevent
+
+### Artifact without understanding
+
+The AI produces a persuasive design or implementation, but nobody can adequately explain why it is correct or how it will behave outside the happy path.
+
+### Automation bias
+
+The first generated answer anchors the team's thinking, narrowing the options and hypotheses they seriously consider.
+
+### Accountability theater
+
+A human clicks approve after inspecting output but did not own the framing, decision, or reasoning that produced it.
+
+### Skill atrophy
+
+Engineers increasingly supervise generated work while exercising less of the problem solving, debugging, and system modeling needed for novel situations.
+
+### Self-confirming automation
+
+AI proposes the approach, implements it, generates its tests, and reviews its own assumptions. Multiple artifacts create the appearance of independent checks while sharing the same blind spots.
+
+### Process theater
+
+Required documents and gates are completed to satisfy tooling, but they do not record real reasoning or improve decisions.
+
+AHEAD must resist all six. Its workflows should create useful moments for thought, challenge, evidence, and decision—not merely more generated paperwork.
+
+## What AHEAD optimizes for
+
+AHEAD does not optimize for lines of AI-generated code or the percentage of a workflow performed autonomously. It optimizes for:
+
+- better problem framing;
+- broader and better-supported option sets;
+- explicit decisions and tradeoffs;
+- stronger human mental models;
+- faster access to relevant evidence;
+- safer implementation and operations;
+- independent challenge before consequential actions;
+- earlier detection of incorrect assumptions;
+- durable, inspectable engineering knowledge;
+- learning that improves both people and automation.
+
+Delivery speed matters. AHEAD's claim is that sustainable speed comes from combining human understanding with AI leverage, not from maximizing automation at every step.
+
+## The intended relationship
+
+The relationship between an engineer and AI should resemble a strong engineering partnership, with an important asymmetry: the human is accountable.
+
+The human supplies intent, context, judgment, and responsibility. AI supplies reach, recall, variation, synthesis, and challenge. Each compensates for limitations of the other, but only the human can decide what the organization should do and own what happens next.
+
+That is why AHEAD means **Assisted Human Engineering and Development**. The adjective is “assisted.” The subject is human engineering.
+
+## How AHEAD expects engineers to work
+
+AHEAD's philosophy applies beyond explicit workflow gates. Engineers should:
+
+- care about the quality and consequences of their work;
+- think deliberately rather than operate on autopilot;
+- understand the user, domain, constraints, and system before optimizing a solution;
+- make assumptions, evidence, decisions, and uncertainty visible;
+- prefer simple, local, independently changeable parts over convenient but entangled designs;
+- prototype to learn without quietly turning exploratory code into production code;
+- automate repeatable mechanics while retaining mastery of the work being automated;
+- design for testing, failure, diagnosis, and recovery;
+- use version control, traceable decisions, and durable engineering records;
+- fix problems without turning investigation into blame;
+- communicate from genuine understanding and state uncertainty honestly;
+- keep learning, including learning when a favored tool or practice does not improve outcomes.
+
+The detailed [engineering-practice guide](engineering-practice.md) traces these recommendations to empirical research, standards, and practitioner sources. Not every useful craft principle has experimental support; AHEAD labels the source and strength instead of presenting all advice as settled science.
+
+## Acceptable use of AI
+
+AI use is appropriate when it expands human reach without replacing the human reasoning, knowledge, or accountability the work requires. Typical uses include research, bounded boilerplate, candidate tests after a human defines expected behavior, examples and fixtures, explanations, proposed refactorings, documentation drafts based on supplied facts, structured meeting notes, additional design options, debugging hypotheses, and first-pass review.
+
+Full vibe coding is also appropriate for explicitly disposable, isolated prototypes built to answer a learning question quickly. The prototype may demonstrate feasibility or reveal how an idea feels, but it is not production evidence. Useful learning is preserved; prototype code is discarded. Anything retained must re-enter the ordinary human-led engineering workflow.
+
+AI use is not acceptable when it defines business behavior, substitutes for learning or codebase knowledge, makes a consequential decision, produces core business logic on the engineer's behalf, hides uncertainty, invents evidence, impersonates human authorship, performs final approval, uses unauthorized sensitive context, or produces code the responsible engineer cannot explain, test, maintain, debug, and change.
+
+The boundary depends on risk. AI may assist with security, authorization, cryptography, data migrations, infrastructure, CI/CD, or production operations, but such work requires explicit human design, authorization, and independent verification. Workflow permission never grants operational permission.
+
+The full [acceptable-use policy](acceptable-ai-use.md) records the conditions, heightened-review areas, prohibited uses, and evidence behind these boundaries.
+
+## Evidence posture
+
+AHEAD is evidence-informed; it is not yet an experimentally validated methodology. No single study establishes that the complete AHEAD sequence is optimal. Some principles have direct support from empirical software-engineering research, some draw on adjacent cognitive research or consensus standards, and some—especially the exact “human first” sequencing—remain design hypotheses that AHEAD must test.
+
+The existing evidence also resists simplistic claims about AI. A randomized field study across 4,867 developers found increased completed tasks with access to an AI coding assistant, while a smaller randomized study of experienced open-source developers working in familiar repositories found that the available AI tools increased completion time. The responsible conclusion is that AI's effect depends on the people, task, system, tool, and outcome being measured—not that AI is inherently productive or unproductive.
+
+AHEAD will maintain a [research map](evidence/research-map.md) that records the evidence and limitations behind each important process choice. Its [evidence standard](evidence/evidence-standard.md) defines how claims are classified and how the methodology should be revised when better evidence appears.