ahead-pi 0.4.0 → 0.6.0

package/generated/product-change/ai-review.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=ai-review sha256=ff114ee0a859569db494eecf5bc969ea95d92e3b808d8823d047ad1bcd91ad05 -->
+<!-- workflow=product-change@0.3.0 phase=ai-review sha256=869a69183087b1ee4c2ea7382a54209bd1c56d6faf460312e919a0073f64cae4 -->
 
 # AHEAD agent profile
 
@@ -34,7 +34,7 @@ AI findings are hypotheses, not verdicts. The implementing human must dispositio
 
 ## Enforced phase contract
 
-- Workflow: `product-change@0.2.0`
+- Workflow: `product-change@0.3.0`
 - Current phase: `ai-review`
 - Human gate: `ai-review-disposed` — Implementing human disposes blocking AI findings; acceptance identity must match `review-disposition`
 - Normal next phase: `human-review`
@@ -44,5 +44,6 @@ AI findings are hypotheses, not verdicts. The implementing human must dispositio
 
 ### Phase artifacts
 
-- `ai-review`: AI review findings bound to the current changeset (required; actor: ai)
+- `review-inputs`: Enumeration of run inputs read for review: decision, plan, plan-deviations, reference-updates, changeset, tests, and evidence (required; actor: ai)
+- `ai-review`: AI review findings bound to the current changeset and evaluated against the full open run (required; actor: ai)
 - `review-disposition`: Implementing-human disposition of every material AI finding (required; actor: human; actor identity must match latest changeset)

package/generated/product-change/decision.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=decision sha256=94f5fdd19a60bdcea3268e616b2ed254b70b3e189e82943c0de061fc6105723e -->
+<!-- workflow=product-change@0.3.0 phase=decision sha256=5cc6419168253edefc53b431dda34aff33ec25d180a7c76f866e961377c43e18 -->
 
 # AHEAD agent profile
 
@@ -34,7 +34,7 @@ Keep value choices, risk acceptance, product intent, and irreversible tradeoffs
 
 ## Enforced phase contract
 
-- Workflow: `product-change@0.2.0`
+- Workflow: `product-change@0.3.0`
 - Current phase: `decision`
 - Human gate: `decision-approved` — Accountable human approves the decision
 - Normal next phase: `plan`

package/generated/product-change/define.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=define sha256=fdb0a9f7dc06fbf3c8e7ce49be120ee676ebf64ad2f7683431f41affc92c9871 -->
+<!-- workflow=product-change@0.3.0 phase=define sha256=c4b57dc030a4064864b3497e6d8363686ccbb9147fdd76a46c8b974fd7db07fd -->
 
 # AHEAD agent profile
 
@@ -27,7 +27,7 @@ The human defines the desired outcome, users, constraints, scope, success signal
 
 ## Enforced phase contract
 
-- Workflow: `product-change@0.2.0`
+- Workflow: `product-change@0.3.0`
 - Current phase: `define`
 - Human gate: `framing-accepted` — Human accepts the framing
 - Normal next phase: `research`

package/generated/product-change/deploy.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=deploy sha256=b7f6d2e3844c8719ec01bc277ebdfb66b4501cb4f024ce5cdc5fb71ccdec78ba -->
+<!-- workflow=product-change@0.3.0 phase=deploy sha256=395dd1c2d28831ea323f89153d136f0675b93a0b5d53b959ec86730d1888c720 -->
 
 # AHEAD agent profile
 
@@ -27,7 +27,7 @@ A human authorizes deployment or release. You may analyze readiness evidence, bu
 
 ## Enforced phase contract
 
-- Workflow: `product-change@0.2.0`
+- Workflow: `product-change@0.3.0`
 - Current phase: `deploy`
 - Human gate: `deployment-confirmed` — Human confirms the intended version reached the target or deployment is not applicable
 - Normal next phase: `verify`

package/generated/product-change/human-review.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=human-review sha256=ed70af1697f2a87fb3e7757b65f0dd3fa94bc6113da5c9e95862edfad37f20c2 -->
+<!-- workflow=product-change@0.3.0 phase=human-review sha256=f666027a5648ffa0c84c50dc245f7eb45fb60c4dddb33acd2c9000bc84e3e577 -->
 
 # AHEAD agent profile
 
@@ -34,7 +34,7 @@ AI findings are hypotheses, not verdicts. The implementing human must dispositio
 
 ## Enforced phase contract
 
-- Workflow: `product-change@0.2.0`
+- Workflow: `product-change@0.3.0`
 - Current phase: `human-review`
 - Human gate: `human-review-accepted` — Independent human reviewer accepts the current change; acceptance identity must match `human-review`
 - Normal next phase: `deploy`
@@ -44,4 +44,4 @@ AI findings are hypotheses, not verdicts. The implementing human must dispositio
 
 ### Phase artifacts
 
-- `human-review`: Independent human review (required; actor: human; actor identity must differ from latest changeset)
+- `human-review`: Independent human review made against the full open run (required; actor: human; actor identity must differ from latest changeset)

package/generated/product-change/implement.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=implement sha256=80c450e0f6487c32f5a8b4f4bc7338ab9eb13e5f54d78f1606a21f6d5c2e57bb -->
+<!-- workflow=product-change@0.3.0 phase=implement sha256=1a9c33bb3f8ff0e5bc2e6a2314e2996d79eb090792f9d35fb85fd2d599ff3319 -->
 
 # AHEAD agent profile
 
@@ -31,12 +31,12 @@ Call out plan deviations; do not silently redefine behavior or policy. Passing c
 
 ## Enforced phase contract
 
-- Workflow: `product-change@0.2.0`
+- Workflow: `product-change@0.3.0`
 - Current phase: `implement`
-- Human gate: `implementation-ready` — Human confirms work is ready for review and checks pass
+- Human gate: `implementation-ready` — Human confirms work, tests, and durable reference updates are ready for review
 - Normal next phase: `ai-review`
 - Human-authorized return targets: plan
-- AI unlock artifacts: none
+- AI unlock artifacts: `reference-updates`
 - AI capabilities after unlock: `inspect`, `search`, `analyze`, `modify`, `execute`
 
 ### Phase artifacts
@@ -44,3 +44,4 @@ Call out plan deviations; do not silently redefine behavior or policy. Passing c
 - `changeset`: Linked changeset (required; actor: human)
 - `tests`: Test and check evidence (required; actor: human)
 - `plan-deviations`: Plan deviations and rationale, including none (required; actor: human)
+- `reference-updates`: Actual creates or updates of decision records, design docs, and runbooks during implementation, or explicit none; AI may propose entries, human accepts each (required; actor: human)

package/generated/product-change/manifest.json

@@ -1,6 +1,6 @@
 {
   "workflow": "product-change",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "generated": [
     "define.md",
     "research.md",
@@ -17,7 +17,7 @@
     "outcome.md"
   ],
   "sources": [
-    "spec/workflows/product-change-v0.2.json",
+    "spec/workflows/product-change-v0.3.json",
     "policy/common.md",
     "policy/product-change/<phase>.md or policy/shared/<phase>.md",
     "policy/methods/index.json",

package/generated/product-change/options.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=options sha256=595c1fbecf433d64a4c8a647df372c3937006c101fcbe5235bb4975403f0c61a -->
+<!-- workflow=product-change@0.3.0 phase=options sha256=ef4710ecbe488f46798e9c16610f605568ee4394dc716aeb081d796b6f82ef4c -->
 
 # AHEAD agent profile
 
@@ -34,7 +34,7 @@ Keep value choices, risk acceptance, product intent, and irreversible tradeoffs
 
 ## Enforced phase contract
 
-- Workflow: `product-change@0.2.0`
+- Workflow: `product-change@0.3.0`
 - Current phase: `options`
 - Human gate: `options-understood` — Human confirms viable options and tradeoffs are understood
 - Normal next phase: `decision`

package/generated/product-change/outcome.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=outcome sha256=0c2a79dcb011adc8e99985e2add7ea90b12d7056839f0d746654f2dc34aa54ab -->
+<!-- workflow=product-change@0.3.0 phase=outcome sha256=98e154ceaf14f6971995da0319dde1f084b62ae192d82aa815986ca9bd3ad77b -->
 
 # AHEAD agent profile
 
@@ -27,9 +27,9 @@ The human decides to accept, roll back, follow up, abandon, or reopen work and r
 
 ## Enforced phase contract
 
-- Workflow: `product-change@0.2.0`
+- Workflow: `product-change@0.3.0`
 - Current phase: `outcome`
-- Human gate: `outcome-accepted` — Human accepts closure
+- Human gate: `outcome-accepted` — Human accepts closure and explicitly closes the run
 - Normal next phase: `close run`
 - Human-authorized return targets: plan, implement
 - AI unlock artifacts: none

package/generated/product-change/plan.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=plan sha256=9863c8de33161735bb3bf9ba146c4d520faa99ce617d974ae763be1ac7f0e266 -->
+<!-- workflow=product-change@0.3.0 phase=plan sha256=0816b73f07560b714a0eaeedf7fb7f642072258bde7429f7593141314b89c431 -->
 
 # AHEAD agent profile
 
@@ -40,12 +40,12 @@ For broad migrations, use expand, migrate, verify, and contract stages so interm
 
 ## Enforced phase contract
 
-- Workflow: `product-change@0.2.0`
+- Workflow: `product-change@0.3.0`
 - Current phase: `plan`
-- Human gate: `plan-approved` — Human approves the final plan
+- Human gate: `plan-approved` — Human approves the final plan and its planned durable reference updates
 - Normal next phase: `implement`
 - Human-authorized return targets: options, decision
-- AI unlock artifacts: `first-pass-plan`
+- AI unlock artifacts: `first-pass-plan`, `reference-updates`
 - AI capabilities after unlock: `inspect`, `search`, `analyze`, `record`
 
 ### Phase artifacts
@@ -53,3 +53,4 @@ For broad migrations, use expand, migrate, verify, and contract stages so interm
 - `first-pass-plan`: Human first-pass implementation plan (required; actor: human)
 - `ai-plan-review`: AI plan challenge (optional; actor: ai)
 - `plan`: Human-approved sequenced plan, tests, rollout, recovery, and deviations policy (required; actor: human)
+- `reference-updates`: Planned creates or updates of decision records, design docs, and runbooks, or explicit none (required; actor: human)

package/generated/product-change/questions.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=questions sha256=7960c7ed009449dfe17c6219890645066d6aa72dcee6c3059279dccc4386cee7 -->
+<!-- workflow=product-change@0.3.0 phase=questions sha256=e075c845d6a88b58a78b53e974e28414bfdea70d6cc69adb6ea99bc4eb12677d -->
 
 # AHEAD agent profile
 
@@ -40,7 +40,7 @@ Research should change a decision, hypothesis, plan, or confidence level. Put pr
 
 ## Enforced phase contract
 
-- Workflow: `product-change@0.2.0`
+- Workflow: `product-change@0.3.0`
 - Current phase: `questions`
 - Human gate: `unknowns-disposed` — Human confirms important unknowns are answered or explicitly accepted
 - Normal next phase: `options`

package/generated/product-change/research.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=research sha256=871000313681366e424b39a987b9973edc7c03e82d68668d3fb49e5e3f56bdc5 -->
+<!-- workflow=product-change@0.3.0 phase=research sha256=38da5e605e95015ac13bbe84b65ab5d38cf98937dee1cb07ad52f9f1edc0ceb0 -->
 
 # AHEAD agent profile
 
@@ -34,7 +34,7 @@ Research should change a decision, hypothesis, plan, or confidence level. Put pr
 
 ## Enforced phase contract
 
-- Workflow: `product-change@0.2.0`
+- Workflow: `product-change@0.3.0`
 - Current phase: `research`
 - Human gate: `research-reviewed` — Human confirms material evidence is available
 - Normal next phase: `questions`

package/generated/product-change/verify.md

@@ -1,5 +1,5 @@
 <!-- GENERATED FILE. DO NOT EDIT. -->
-<!-- workflow=product-change@0.2.0 phase=verify sha256=69ad233303afbfe6de12aa14e50243c41955de7a5a56ebdecf4939adff9c20ec -->
+<!-- workflow=product-change@0.3.0 phase=verify sha256=c1e3ade3f9d79fa2c51001799f3d83798252e0e063bbb8a1b22bc9d146f68076 -->
 
 # AHEAD agent profile
 
@@ -27,7 +27,7 @@ Help suggest checks and analyze authorized observations against the recorded pro
 
 ## Enforced phase contract
 
-- Workflow: `product-change@0.2.0`
+- Workflow: `product-change@0.3.0`
 - Current phase: `verify`
 - Human gate: `outcome-demonstrated` — Human confirms the intended outcome is demonstrated or failure is recorded
 - Normal next phase: `ai-audit`

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

@@ -3,7 +3,7 @@
 Audience: AHEAD evidence readers and framework maintainers
 
 Status: living evidence review
-Last reviewed: 2026-08-12
+Last reviewed: 2026-08-20
 
 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.
 
@@ -27,6 +27,7 @@ The evidence supports using AI and evaluating it contextually. It gives indirect
 | 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 assistance should preserve human understanding and responsibility. | [Google Summer of Code's 2026 AI guidance](https://developers.google.com/open-source/gsoc/resources/ai_guidance) summarizes mentor advice favoring validation, complete understanding, research and learning, human-defined test scope, and caution on complex or unfamiliar work. | E4 | Corroborates AHEAD's human-owned, learning-oriented boundaries with documented practitioner concerns. | GSoC is a mentored open-source learning context, the page is not an independent or controlled study, and organizations that prohibit AI cannot use AHEAD as designed. |
 | 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. |

package/generated/reference/docs/guide/README.md

@@ -12,11 +12,16 @@ This is the starting point for people applying AHEAD to engineering work. These
 4. [Engineering practice](engineering-practice.md) describes the habits AHEAD asks engineers to cultivate.
 5. [Pilot workflows](workflows/README.md) explains how to choose and execute one of the six flows.
 6. [Work items and planning handoffs](work-items.md) explains provider-neutral links, configurable gates, and sprint-ahead preparation.
-7. [Recommended skills](recommended-skills.md) lists optional, reviewed third-party aids.
+7. [Durable references](durable-reference.md) defines the three durable artifact classes AHEAD standardizes — decision records, design docs, and runbooks — and adopts Diátaxis for the rest.
+8. [Recommended skills](recommended-skills.md) lists optional, reviewed third-party aids.
 
 ## Authority
 
-The Constitution, Acceptable AI Use policy, and active workflow contract are binding during an AHEAD pilot. The rationale explains why those rules exist. Engineering Practice is proposed guidance, and recommended skills are optional. Organization and repository rules may narrow AI authority but cannot broaden it beyond AHEAD policy.
+The Constitution, Acceptable AI Use policy, and active workflow contract are binding during an AHEAD pilot. The rationale explains why those rules exist. Engineering Practice, durable references, and work-item guidance are proposed guidance, and recommended skills are optional. Organization and repository rules may narrow AI authority but cannot broaden it beyond AHEAD policy.
+
+## Scope
+
+AHEAD prescribes run artifacts, workflow gates, decision records, design docs, and runbooks. It explicitly leaves tutorials, most how-to guides, user-facing product documentation, contributor references, and project-specific coding-agent instructions to each project. [Durable references](durable-reference.md) names what AHEAD covers and points at [Diátaxis](https://diataxis.fr/) for the rest.
 
 ## When you need the basis for a rule
 

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

@@ -6,7 +6,7 @@ Status: binding pilot policy v0.1
 
 ## Authority
 
-This policy is binding for AHEAD pilot workflows. The [AHEAD Constitution](../../CONSTITUTION.md) is the highest authority; this policy interprets its human-ownership boundaries; workflow profiles apply both and may narrow AI permissions for a phase. A workflow phase, diagram, tool permission, or local convenience cannot broaden AI authority beyond this policy. Organization and repository policies may impose stricter controls.
+This policy is binding for AHEAD pilot workflows. The [AHEAD Constitution](../../CONSTITUTION.md) is the highest authority; this policy interprets its human-ownership boundaries; workflow profiles apply both and may narrow AI permissions for a phase. A workflow phase, diagram, tool permission, or local convenience cannot broaden AI authority beyond this policy. Organization and repository policies may impose stricter controls. Because AHEAD is an AI-assisted methodology, it cannot be used as designed where AI use is prohibited entirely.
 
 If two rules appear to conflict, apply the more protective rule and record the ambiguity for correction. No exception may transfer human authorship, judgment, approval, accountability, or unscoped consequential authority to AI.
 
@@ -43,6 +43,8 @@ AI may locate, organize, compare, and summarize approved internal and external s
 
 Why: AI increases search and synthesis capacity, while NIST identifies confident false content as an inherent generative-AI risk. Summaries are navigation aids, not new authorities.
 
+For novel, complex, or unfamiliar work, prefer primary documentation, direct inspection, and experiments. State what the AI may not know and treat confident synthesis as unverified until evidence supports it.
+
 ### Boilerplate and repetitive structure
 
 AI may generate scaffolding, serializers, routine handlers, adapters, setup code, repetitive mappings, and other bounded structure after the human identifies the intended pattern and integration boundary.
@@ -101,7 +103,7 @@ AI may help organize evidence, explain unfamiliar mechanisms, generate competing
 
 Before broad AI assistance in normal debugging, the human records at least the observed failure, evidence already checked, and an initial mental model or question. A team may use a timebox before asking AI, but the purpose is independent thought—not withholding useful tools. During incidents, AI may assist immediately once the current observation and safety constraints are established.
 
-The human remains the investigator: selecting or authorizing tests, interpreting results, deciding whether evidence supports a conclusion, and choosing the intervention.
+Debugging is not grunt work. The human remains the investigator: selecting or authorizing tests, interpreting results, deciding whether evidence supports a conclusion, and choosing the intervention.
 
 ### Design alternatives
 
@@ -215,5 +217,6 @@ For a disposable prototype, also answer:
 - [NIST AI 600-1, *Generative Artificial Intelligence Profile*](https://doi.org/10.6028/NIST.AI.600-1) — authoritative risk guidance on confabulation, privacy, provenance, testing, and governance.
 - [NIST DevSecOps reference model: Artificial Intelligence](https://pages.nist.gov/nccoe-devsecops/notational-reference-model.html#artificial-intelligence) — human validation and verifiable-process guidance for AI-augmented software development.
 - [OWASP Secure Coding with AI Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secure_Coding_with_AI_Cheat_Sheet.html) — practitioner security guidance for sensitive context, agent permissions, generated tests, supply chains, and CI/CD.
+- [Google Summer of Code, *Guidance for GSoC Contributors using AI tooling in GSoC 2026*](https://developers.google.com/open-source/gsoc/resources/ai_guidance) — practitioner guidance summarizing mentor advice on human responsibility, understanding, research, human-defined test scope, and the limits of AI on complex work.
 
 The [research map](../evidence/research-map.md) classifies these sources and records their limitations. Exact boundaries such as “core business logic” and the human-first debugging checkpoint remain AHEAD policy choices that should be tested and refined.

package/generated/reference/docs/guide/durable-reference.md

@@ -0,0 +1,262 @@
+# Durable References
+
+Audience: AHEAD practitioners
+
+Status: pilot v0.1
+
+## Purpose
+
+AHEAD's workflows produce two kinds of records. **Run artifacts** are scoped to a single run and describe what happened: framing, research, decisions, plans, changesets, review findings, outcomes. **Durable references** outlive a run and describe how the system *ought to be* going forward.
+
+Durable references are where a project's decisions and design accrete. Without them, every run has to reconstruct context from code and memory. With them, each run inherits what earlier runs concluded and updates the record when it changes.
+
+AHEAD standardizes three durable reference classes and explicitly does not standardize the rest. For the rest, use [Diátaxis](https://diataxis.fr/).
+
+## The three durable classes
+
+| Class | Also called | Diátaxis mode | Shape draws from |
+|---|---|---|---|
+| `decision-record` | ADR (Architecture Decision Record) | explanation with reference lookup | [MADR](https://adr.github.io/madr/) |
+| `design-doc` | design document, architecture document | reference plus explanation, layered | [arc42](https://arc42.org/), [C4](https://c4model.com/) |
+| `runbook` | ops runbook (Google SRE: playbook) | how-to | [Google SRE Book](https://sre.google/sre-book/) |
+
+The three names are what practitioners and coding agents already grep for. AHEAD uses the same strings in workflow specifications (`spec/workflows/*.json` artifact `kind` values) so the guide and the machine contract match.
+
+## Decision records
+
+### What one is
+
+A `decision-record` captures a consequential choice made by an accountable human, its context, the drivers that shaped it, the alternatives considered, the choice, and its expected consequences. It is the durable form of a Decision workflow's publish artifact.
+
+Not every Decision workflow run produces one. Small, reversible decisions may live only in the run record. A decision-record is warranted when the choice will bind future work, when it forecloses alternatives, or when a future engineer or reviewer must be able to understand why the current shape exists.
+
+### When to create or update
+
+- Create at the `publish` phase of a Decision workflow.
+- Create when a Product Change or Internal Improvement run makes a decision durable enough to bind future work; log the creation in that run's `reference-updates` artifact.
+- Update the `status` and `superseded_by` fields when a later decision-record replaces this one. The prior record is not deleted.
+- Update the `revisit` date when a scheduled review of the decision occurs.
+
+Decision records are otherwise immutable. A changed conclusion is a new decision-record that supersedes the prior one.
+
+### Shape
+
+Follow [MADR](https://adr.github.io/madr/). Concretely:
+
+- Filename `NNNN-title-with-dashes.md` where `NNNN` is a zero-padded consecutive number.
+- Store in `docs/adr/` or `docs/architecture/adr/`. Pick one location per project and hold to it.
+- YAML front matter:
+  ```yaml
+  ---
+  type: decision-record
+  status: proposed | accepted | superseded | deprecated
+  date: YYYY-MM-DD
+  deciders: [names or roles]
+  consulted: []
+  informed: []
+  supersedes: [NNNN, ...]        # optional
+  superseded_by: NNNN            # optional
+  revisit: YYYY-MM-DD            # optional
+  ---
+  ```
+- First heading `# ADR NNNN: <Short title>`.
+- Required sections: `Context and Problem Statement`, `Decision Drivers`, `Considered Options`, `Decision Outcome`, `Consequences`.
+- Optional sections: `Confirmation`, per-option `Pros and Cons`, `More Information`.
+
+Keep the whole record to a small number of screens. Long context, exhaustive alternatives, or deep technical detail belongs in a linked design-doc or research artifact.
+
+### Human-only and AI-assistable sections
+
+AHEAD is human-led. AI may scaffold and question everywhere. The following table records which sections humans must own outright versus where AI may draft, propose, or maintain material for the human to accept.
+
+| Section | Human owns | AI may |
+|---|---|---|
+| Context and Problem Statement | final wording | propose questions to sharpen framing |
+| Decision Drivers | final list | propose candidate drivers for approval |
+| Considered Options | first-pass options | expand alternatives, add missing options |
+| Pros and Cons per option | curates | draft skeletons, cite evidence |
+| **Decision Outcome** | **writes** | summarize *after* the human has written it |
+| Consequences | owns | propose overlooked consequences |
+| Confirmation | owns | propose validation checks |
+| Front matter (`status`, `supersedes`, `superseded_by`, `revisit`) | approves each transition | maintain on approved state changes |
+
+An AI that produces a Decision Outcome for the human to rubber-stamp violates the human ownership boundary. An AI that proposes a Decision Outcome after the human has written one, framed as a summary the human then accepts or discards, is assistance.
+
+## Design docs
+
+### What one is
+
+A `design-doc` describes a capability, subsystem, or cross-cutting concept as it is intended to be — its contract, its shape, and the reasoning that produced that shape. It is a living document. Runs that alter its subject update it.
+
+A design-doc is not a decision. It records the design that decisions have produced. Where a decision is contained, a design-doc is layered:
+
+- **Reference layer** — components, contracts, interfaces, invariants, sequence, deployment. What the thing is. Kept austere and scannable.
+- **Explanation layer** — why this shape, what tradeoffs, what constraints hold, what the design is *not*. Kept adjacent to but distinct from the reference layer.
+
+Both layers are required. A design-doc that is only "what" rots into a stale catalog. A design-doc that is only "why" duplicates the decision records.
+
+### When to create or update
+
+- Create at the `plan` phase of a Product Change or Internal Improvement run when the capability has no design-doc yet.
+- Update at `implement` when a run changes what the design-doc describes. The update lands in that run's `reference-updates` artifact.
+- Update the reference layer when code changes shift the contract, module structure, or diagram-worthy topology.
+- Update the explanation layer when a new decision changes the design's rationale — link the new decision-record.
+- Update `last-updated` metadata on every change.
+
+### Shape
+
+AHEAD does not prescribe a rigid template. Draw on [arc42](https://arc42.org/) for section coverage and [C4](https://c4model.com/) for layered detail. A useful minimum:
+
+- Filename descriptive: `docs/architecture/<capability>.md` or `docs/design/<capability>.md`. Pick one root per project.
+- YAML front matter:
+  ```yaml
+  ---
+  type: design-doc
+  status: draft | current | deprecated
+  last-updated: YYYY-MM-DD
+  supersedes: <path>              # optional
+  related-decisions: [NNNN, ...]  # ADR numbers
+  related-runbooks: [<path>, ...] # optional
+  ---
+  ```
+- First heading `# Design: <Capability>` or `# <Capability> — Design`.
+- Reference section: overview, contract, components, interfaces, data, sequence and runtime behavior, deployment, invariants. Kept factual.
+- Explanation section: rationale, tradeoffs, constraints, alternatives that were considered and rejected (link the decision-record), residual risks.
+- Cross-reference table: linked decision-records and linked runbooks.
+
+If a design-doc grows beyond what one screen can hold at each layer, split by C4 layer or by subsystem rather than mixing modes.
+
+### Human-only and AI-assistable sections
+
+| Section | Human owns | AI may |
+|---|---|---|
+| Overview of the capability | edits | draft from code inspection |
+| Contract and API surface | approves | generate and update from code |
+| Component and module reference | approves | generate and maintain |
+| Diagrams derived from code | approves | generate and update |
+| **Rationale — why this shape** | **writes** | pose sharpening questions |
+| Tradeoffs and constraints | owns | pose questions, cite evidence |
+| Cross-reference table | approves | maintain |
+| Change log and `last-updated` metadata | approves | maintain |
+
+AI edits to a design-doc are only made inside a run. Every AI-proposed change lands in that run's `reference-updates` artifact and is accepted or edited by the human before it is applied. AHEAD does not permit background AI edits to durable references.
+
+## Runbooks
+
+### What one is
+
+A `runbook` is a procedure a human executes when a specific operational condition occurs — an alert, a symptom, a scheduled event, a deployment step. Written to be usable under pressure.
+
+A runbook is a how-to guide, not a reference. Contextual explanation belongs in a linked design-doc; per-alert action steps belong here. Google SRE calls the same artifact a "playbook"; the artifact is the same shape.
+
+Not every operational note is a runbook. Environment variable listings, resource limits, and alert catalogs are reference material and belong in a design-doc chapter.
+
+### When to create or update
+
+- Create when a Product Change introduces a new alert, deployment step, or operational condition that a human must handle.
+- Update at the `implement` phase of any run that alters operational behavior. Log in `reference-updates`.
+- Update after an Operational Stabilization run that revealed a diagnosis or mitigation not previously documented.
+- Update after any postmortem that identifies missing or incorrect procedure. Link the postmortem.
+
+### Shape
+
+Draw on [Google SRE Book](https://sre.google/sre-book/) chapters on on-call and effective troubleshooting. A useful minimum:
+
+- Filename `docs/runbooks/runbook-<symptom>.md` or `docs/operations/runbooks/runbook-<symptom>.md`.
+- YAML front matter:
+  ```yaml
+  ---
+  type: runbook
+  status: draft | current | deprecated
+  severity: [P1|P2|P3|P4]
+  alert: <alert identifier or none>
+  owning-team: <team>
+  last-updated: YYYY-MM-DD
+  related-designs: [<path>, ...]
+  ---
+  ```
+- First heading `# Runbook: <Alert or symptom>`.
+- Required sections: `Symptom`, `Severity and Impact`, `Diagnosis`, `Mitigation`, `Escalation`, `Rollback`, `Related`.
+
+Lead with the symptom. Every diagnosis and mitigation step is executable — a command, a query, a specific console page, a specific decision. Prose belongs in the linked design-doc, not here.
+
+### Human-only and AI-assistable sections
+
+| Section | Human owns | AI may |
+|---|---|---|
+| Symptom and alert description | approves | draft from monitoring configuration |
+| **Severity and Impact** | **writes** (operator judgment) | ask clarifying questions |
+| Diagnosis steps | validates each step | propose steps from code and prior incidents |
+| **Mitigation steps** | **explicitly approves each** | propose candidates |
+| Escalation contacts | approves | maintain from team directory |
+| Rollback procedure | owns | propose from the deployment path |
+| Related design-docs and decisions | approves | maintain link table |
+| Postmortem links | approves | maintain |
+
+Mitigation is high-consequence. AI may propose mitigation steps; the human on the run must explicitly approve each. AI-only mitigation is out of bounds regardless of how obvious the mitigation appears.
+
+## How runs interact with durable references
+
+### The `reference-updates` artifact
+
+Product Change, Internal Improvement, and Operational Stabilization workflows require a `reference-updates` artifact during both `plan` and `implement` phases. It names:
+
+- every decision-record the run creates or updates (including status/supersession changes);
+- every design-doc the run creates or updates;
+- every runbook the run creates or updates; and
+- an explicit "none" when the run intentionally updates no durable reference.
+
+The `plan` phase records the *intended* updates. The `implement` phase records the *actual* updates. Deviations between the two are recorded in `plan-deviations` like any other plan deviation.
+
+An AI review that sees a code change without a corresponding `reference-updates` entry flags it. This is the primary mechanism AHEAD uses to keep durable references from drifting behind behavior.
+
+### Co-authoring during implement
+
+An AHEAD run's session stays live from framing through outcome. During `implement`, a practitioner may ask the AI to:
+
+- check whether an in-progress change is covered by the plan and flag gaps;
+- draft the reference-layer sections of an affected design-doc based on the code change;
+- draft diagnosis and mitigation candidates for a runbook affected by the change;
+- log a plan-deviation as it occurs;
+- answer questions with the full run context available (decision, plan, evidence, prior updates).
+
+The human accepts, edits, or discards each AI-proposed update. The human-only sections named in the tables above are not drafted by AI on the human's behalf.
+
+### Review with full run context
+
+The run remains open through review. The AI review phase reads the entire live run — decision-record, plan, plan-deviations, all `reference-updates`, changeset, tests, and evidence — and reports findings against that whole context, not the changeset alone. Reviewer findings remain snapshot-bound to the exact changeset fingerprint.
+
+The independent human reviewer opens the same live run. The reviewer may query the run interactively ("why did we deviate at step 4?", "which design-doc changed here?") and receive answers from the record. The independent-review requirement is unchanged: reviewer must not be the implementer.
+
+The run closes only at the outcome gate, and only when the accountable human explicitly closes it. There is no automatic close after time or after review.
+
+## What AHEAD does not standardize
+
+Adopt [Diátaxis](https://diataxis.fr/) for these. Diátaxis distinguishes four modes — tutorial, how-to guide, reference, and explanation — by user need. Use its vocabulary to shape and separate:
+
+- **Tutorials** — first-time learning experiences. Owned by the project.
+- **How-to guides** not tied to an operational alert — for example, "how to add a new API endpoint" or "how to run the integration tests." Owned by the project.
+- **User-facing product documentation** — everything the end user reads about the product. Owned by the project.
+- **Contributor references** — repository layout, build system, lint matrix, local development setup. Owned by the project.
+- **Coding-agent instructions** — project-specific AGENTS-file conventions and per-repo skill collections. Owned by the project. AHEAD provides only [recommended optional skills](recommended-skills.md).
+
+AHEAD does not disclaim these because they are unimportant. It disclaims them because their shape is well established in the wider industry, and every project should adopt existing practice rather than have AHEAD reinvent it. A project may choose to keep decision-records, design-docs, and runbooks alongside its Diátaxis-shaped documentation. AHEAD only constrains the three durable classes.
+
+## Diátaxis anti-patterns — the soft nudge
+
+Diátaxis identifies four common failure modes when documentation mixes modes. AHEAD's durable classes inherit them as review heuristics:
+
+1. **Reference contaminated with narrative explanation** — the design-doc reference layer becomes hard to scan. Split into reference and explanation sections.
+2. **How-to padded with tutorial-style context** — the runbook becomes too slow to execute at 3am. Move context into a linked design-doc.
+3. **Explanation written as procedure** — a design-doc's rationale reads as steps and rots when the steps change. Rewrite as argument, not sequence.
+4. **Tutorial that assumes prior knowledge** — not applicable to AHEAD's three classes but a common trap in the surrounding project docs.
+
+These are conversational heuristics for review, not enforced fields. A reviewer who sees one of them says so; the implementer decides how to address it.
+
+## Style baseline
+
+For prose in decision-records, design-docs, and runbooks, adopt the [Google developer documentation style guide](https://developers.google.com/style) as the default. It is freely available, comprehensive, and consistent with the terse-and-scannable tone AHEAD's classes require. A project may layer its own conventions on top; the Google guide sets the floor.
+
+## Rule of thumb
+
+If a run's outcome will bind future work, it produces or updates a durable reference. If a run's outcome only affects itself, its record is enough. When in doubt, ask whether a future engineer, reviewer, or on-call responder would be worse off without the record; if yes, write the durable reference.

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

@@ -106,7 +106,7 @@ Reframe or seek evidence ─────────↺ FRAME / RESEARCH
 | Options | At least one human-originated option | Expand, combine, challenge, and propose alternatives | Options with provenance | Plausible option space is understood |
 | Compare | Interpretation of tradeoffs | Structure comparison and sensitivity analysis | Benefits, costs, risks, consequences, reversibility | Decision is ready for accountable judgment |
 | Decide | Selection, rationale, accepted tradeoffs, and dissent | Test rationale for inconsistency or missing consequence | Decision and rejected alternatives | Accountable human approves a specific revision |
-| Publish and revisit | Consequence check, communication, review trigger, revisit date, and linked work | Improve clarity, traceability, and proposed validation checks | Consequences, reversibility, review trigger, revisit date, and links | Decision is published and accepted as current |
+| Publish and revisit | Consequence check, communication, review trigger, revisit date, linked work, and a durable decision record written in the project's ADR convention | Improve clarity, traceability, and proposed validation checks | MADR-shaped decision record with status, consequences, reversibility, review trigger, revisit date, and links | Decision record is written, communicated, and accepted as current |
 
 ## Decision evidence chain
 

package/generated/reference/docs/guide/workflows/internal-improvement.md

@@ -153,10 +153,10 @@ Preservation and improvement are separate judgments. A failed invariant cannot b
 | Target | Quality to improve, success threshold, and tradeoffs | Suggest measures and unintended effects | Target quality and acceptance signal | Improvement can be evaluated |
 | Options | Initial approach and evaluation of alternatives | After the human first pass, expand alternatives, expose coupling, and challenge abstraction | Human option, AI challenge when used, and evaluated options | Viable approaches and tradeoffs are understood |
 | Decision | Selection, risk, confidence, and reversibility | Check the option against baseline, target, and invariants | Decision and rationale | Human approves the approach |
-| Plan | First-pass sequence, verification, and rollback | Find affected boundaries, migration needs, and missing tests | Plan and invariant checks | Human approves the final plan |
-| Implement | Engineering change and scope control | Bounded refactoring, explanation, tests, and mechanical assistance | Linked changeset and deviations | Change is ready for review |
-| AI review | Validate and disposition every material AI finding | Review the exact snapshot for hidden behavior changes, incidental complexity, tests, and plan alignment without modifying it | Snapshot-bound AI findings; separate human disposition | Every material finding is fixed, invalid, accepted risk, or follow-up with rationale |
-| Human review | Independent final judgment by someone other than the implementer about simplicity, coupling, risk, and preservation | Answer targeted questions and retrieve evidence | Current independent human review | Independent human reviewer accepts the current change |
+| Plan | First-pass sequence, verification, rollback, and the durable references the run will touch | Find affected boundaries, migration needs, missing tests, and propose reference updates | Plan, invariant checks, and planned reference updates (decision records, design docs, runbooks, or explicit none) | Human approves the final plan |
+| Implement | Engineering change, scope control, and the reference edits that record the change | Bounded refactoring, explanation, tests, mechanical assistance, and proposed reference-update drafts | Linked changeset, deviations, and actual reference updates | Change is ready for review |
+| AI review | Validate and disposition every material AI finding | Review against the full open run — decision, plan, plan-deviations, reference-updates, changeset, tests, and evidence — without modifying the change | Review inputs enumeration, snapshot-bound AI findings, and separate human disposition | Every material finding is fixed, invalid, accepted risk, or follow-up with rationale |
+| Human review | Independent final judgment by someone other than the implementer about simplicity, coupling, risk, and preservation, with the full open run available | Answer targeted questions and retrieve evidence from the live run | Current independent human review | Independent human reviewer accepts the current change |
 | Deploy or release | Authorization and rollout decision | Analyze readiness evidence within policy | Version, environment, actor, time, and result | The intended version reaches the target environment or deployment is explicitly not applicable |
 | Verify | Invariant preservation and target-quality comparison | Analyze measurements and suggest negative checks | Before/after and deployed-outcome evidence when applicable, plus invariant results | Invariants are evaluated and target-quality results are measured; an invariant failure routes to rollback, rework, or product-change reclassification |
 | AI audit | Disposition of findings and required response | Compare invariants, target, plan, reviews, deployment, and observed evidence; identify divergence or weak proof | AI audit findings; separate human disposition | The human disposer accepts the audit gate or reopens work |