ahead-pi 0.2.1 → 0.3.1

package/generated/reference/docs/{workflows → guide/workflows}/corrective-debugging.md

@@ -1,5 +1,7 @@
 # Corrective Debugging Workflow
 
+Audience: AHEAD practitioners
+
 Status: pilot v0.1
 
 ## Outcome
@@ -36,7 +38,7 @@ Use operational stabilization instead when a live system is unhealthy and restor
                       │
                       ▼
               ┌─────────────────┐
-              │ 3. AI ASSISTS   │
+              │ 3A. AI ASSISTS  │
               │ EVIDENCE REVIEW │
               │                 │
               │ • Code          │
@@ -48,7 +50,7 @@ Use operational stabilization instead when a live system is unhealthy and restor
                       │
                       ▼
               ┌─────────────────┐
-              │ 4. HYPOTHESES   │
+              │ 3B. HYPOTHESES  │
               │                 │
               │ HUMAN LEADS     │
               │ AI ASSISTS      │
@@ -60,8 +62,8 @@ Use operational stabilization instead when a live system is unhealthy and restor
                       │
                       ▼
               ┌─────────────────┐
-              │ 5. HUMAN SELECTS│
-              │ WHAT TO TEST    │
+              │ 3C. HUMAN       │
+              │ SELECTS TEST    │
               │                 │
               │ • Prediction    │
               │ • Safety/scope  │
@@ -69,7 +71,7 @@ Use operational stabilization instead when a live system is unhealthy and restor
                       │
                       ▼
               ┌─────────────────┐
-              │ 6. TEST         │
+              │ 3D. TEST        │
               │ HYPOTHESIS      │
               │                 │
               │ HUMAN/ENGINEER  │
@@ -87,38 +89,44 @@ Use operational stabilization instead when a live system is unhealthy and restor
                      │    │
                      │    ▼
         ↺ HUMAN MODEL     HUMAN ACCEPTS DIAGNOSIS
-                          OR UNKNOWN CAUSE / RISK
+                          OR UNKNOWN CAUSE / RISK (4)
+                                  │
+                                  ▼
+                         HUMAN FIX APPROACH (5)
                                   │
                                   ▼
-                         HUMAN FIX APPROACH
+                         HUMAN FIRST-PASS PLAN (6)
                                   │
                                   ▼
-                         HUMAN FIRST-PASS PLAN
+                       ENGINEER IMPLEMENTS (7)
                                   │
                                   ▼
-                       ENGINEER IMPLEMENTS
+                              AI REVIEW (8)
                                   │
                                   ▼
-                              AI REVIEW
+                 HUMAN DISPOSITIONS MATERIAL FINDINGS
                                   │
                                   ▼
-                    INDEPENDENT HUMAN REVIEW
+                    INDEPENDENT HUMAN REVIEW (9)
                                   │
                                   ▼
-                  HUMAN AUTHORIZES DEPLOY / RELEASE
+                  HUMAN AUTHORIZES DEPLOY / RELEASE (10)
                            WHEN APPLICABLE
                                   │
                                   ▼
-          HUMAN VERIFIES CORRECTION OF ORIGINAL FAILURE
+          HUMAN VERIFIES CORRECTION OF ORIGINAL FAILURE (11)
                                   │
                                   ▼
                  HUMAN OBSERVES DEPLOYED OUTCOME
                                   │
                                   ▼
-                              AI AUDIT
+                              AI AUDIT (12)
                                   │
                                   ▼
-                         HUMAN OUTCOME GATE
+                    HUMAN DISPOSITIONS AUDIT FINDINGS
+                                  │
+                                  ▼
+                         HUMAN OUTCOME GATE (13)
 
 Not corrected ───────────────────↺ HUMAN MODEL
 ```
@@ -127,21 +135,24 @@ Reproduction is useful but not a universal gate. Historical, intermittent, produ
 
 “Ready to choose” means either the evidence sufficiently supports a human-accepted diagnosis or the accountable human explicitly accepts that the cause remains unknown and records the risk of proceeding. Unsupported hypotheses alone do not satisfy the gate.
 
+Executable phase 3, `investigate`, contains the evidence review, hypothesis, human test-selection, and test loop shown as 3A–3D. The human conclusion is a separate gate so a plausible hypothesis cannot silently become a diagnosis.
+
 ## Minimal phases
 
 | Phase | Human owns | AI may | Minimum record | Advance when |
 |---|---|---|---|---|
 | Report and characterize | Intended behavior, observed behavior, impact, scope, and evidence quality | Organize evidence and identify missing characterization | Failure statement and evidence links | The failure is bounded enough to investigate |
 | Mental model | Current explanation of relevant components, state, and interactions | Explain unfamiliar mechanisms and challenge omissions | Model, assumptions, and unknowns | The model can generate testable hypotheses |
-| Hypothesize and test | Hypothesis selection, test authorization, prediction, and interpretation | Generate alternatives, evidence for/against, and discriminating tests | Facts, inferences, hypotheses, predictions, tests, results, confidence | Human accepts a diagnosis or explicitly accepts uncertainty |
+| Investigate and test | Hypothesis selection, test authorization, prediction, and interpretation | Generate alternatives, evidence for/against, and discriminating tests | Facts, inferences, hypotheses, predictions, tests, results, confidence | Evidence is ready for a human conclusion |
+| Conclude diagnosis | Supported diagnosis or explicit acceptance of unknown cause, confidence, and risk | Challenge the conclusion against evidence and counterevidence | Diagnosis or accepted uncertainty | Human accepts the diagnosis or remaining uncertainty |
 | Choose correction | Desired correction and tradeoffs | Compare fix approaches and recurrence risks | Selected correction and rationale | Human approves the correction |
 | Plan | First-pass correction and verification plan | Find missing cases, risks, regression tests, and rollout concerns | Plan and rollback or containment needs | Human approves the plan |
 | Implement | Code and engineering changes | Bounded implementation and debugging assistance | Linked changeset and regression evidence | Change is ready for review |
-| AI review | Disposition of valid findings | Review correction, tests, risks, and plan alignment | AI findings and dispositions | Blocking findings are resolved or rejected with rationale |
+| AI review | Validate and disposition every material AI finding | Review the exact snapshot for correction, tests, risks, 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 engineering judgment by someone other than the implementer | Answer targeted questions and retrieve evidence | 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 correction reaches the target environment or deployment is explicitly not applicable |
 | Verify and observe | Original failure, regression protection, and deployed behavior when applicable | Suggest checks and analyze authorized evidence | Pre-change comparison, fix validation, deployment evidence, and observed outcome | The original failure and user-visible outcome are evaluated |
-| AI audit | Disposition of findings and required response | Compare the result with the failure, diagnosis or accepted uncertainty, correction, plan, reviews, and observed behavior | Audit findings and dispositions | Human has reviewed material findings |
+| AI audit | Disposition of findings and required response | Compare the result with the failure, diagnosis or accepted uncertainty, correction, plan, reviews, and observed behavior | AI audit findings; separate human disposition | The human disposer accepts the audit gate or reopens work |
 | Outcome | Acceptance, rollback, continued investigation, follow-up, or abandonment | Summarize learning | Result, causal confidence, uncertainty, and follow-ups | Human accepts closure or reopens/routes work |
 
 ## Evidence chain
@@ -167,7 +178,16 @@ FACTS / EVIDENCE ──► HUMAN MENTAL MODEL
              HUMAN CORRECTION DECISION / PLAN
                             │
                             ▼
-     ENGINEER CHANGE / AI REVIEW / INDEPENDENT REVIEW
+                  ENGINEER CHANGE
+                            │
+                            ▼
+              SNAPSHOT-BOUND AI REVIEW
+                            │
+                            ▼
+           IMPLEMENTING-HUMAN DISPOSITION
+                            │
+                            ▼
+               INDEPENDENT HUMAN REVIEW
                             │
                             ▼
                 HUMAN-AUTHORIZED DEPLOYMENT

package/generated/reference/docs/{workflows → guide/workflows}/decision.md

@@ -1,5 +1,7 @@
 # Decision Workflow
 
+Audience: AHEAD practitioners
+
 Status: pilot v0.1
 
 ## Outcome
@@ -100,11 +102,11 @@ Reframe or seek evidence ─────────↺ FRAME / RESEARCH
 |---|---|---|---|---|
 | Frame | Decision to be made, accountable decider, scope, deadline, and stakeholders | Clarify ambiguity and identify missing stakeholders | Decision statement and owner | Human accepts the frame |
 | Criteria | Goals, constraints, evaluation criteria, and relative importance | Challenge hidden criteria and identify tensions | Criteria and non-negotiable constraints | Criteria are sufficient for comparison |
-| Research and questions | Evaluation of evidence and disposition of uncertainty | Gather cited evidence and find contradictions or missing questions; do not introduce solution alternatives yet | Sources, findings, unknowns, and limits | Material evidence is reviewed and uncertainty is answered or explicitly accepted |
+| Research | Evaluation of evidence and disposition of uncertainty | Gather cited evidence and find contradictions or missing questions; do not introduce solution alternatives yet | Sources, findings, assumptions, unknowns, and limits | Material evidence is reviewed and uncertainty is answered or explicitly accepted |
 | 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 |
-| Validate and publish | Consequence check, communication, review trigger, and linked work | Summarize and propose validation checks | Consequences, reversibility, review trigger, links | Decision is published and accepted as current |
+| 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 |
 
 ## Decision evidence chain
 

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

@@ -1,5 +1,7 @@
 # Internal Improvement Workflow
 
+Audience: AHEAD practitioners
+
 Status: pilot v0.1
 
 ## Outcome
@@ -23,20 +25,21 @@ Use product change when externally meaningful behavior is intentionally changing
 └──────────────────────┬───────────────────────┘
                        ↓
 ┌──────────────────────────────────────────────┐
-│ 2. BASELINE AND TARGET                       │
+│ 2. BASELINE                                  │
 │                                              │
-│ HUMAN                                        │
-│ • Accept current evidence and measurement    │
-│ • Define target quality                      │
-│ • Define success threshold                   │
+│ HUMAN accepts method, evidence, uncertainty  │
+│ AI — ASSIST challenges noise / confounders   │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 3. TARGET                                    │
 │                                              │
-│ AI — ASSIST                                  │
-│ • Gather metrics • find measurement gaps     │
-│ • Suggest unintended effects to watch        │
+│ HUMAN defines quality, threshold, guardrails │
+│ AI — ASSIST exposes gaming / shifted cost    │
 └──────────────────────┬───────────────────────┘
                        ↓
 ┌──────────────────────────────────────────────┐
-│ 3. OPTIONS                                   │
+│ 4. OPTIONS                                   │
 │                                              │
 │ HUMAN — FIRST PASS                           │
 │ • Propose at least one improvement approach  │
@@ -50,13 +53,13 @@ Use product change when externally meaningful behavior is intentionally changing
 └──────────────────────┬───────────────────────┘
                        ↓
 ┌──────────────────────────────────────────────┐
-│ 4. HUMAN DECISION GATE                       │
+│ 5. HUMAN DECISION GATE                       │
 │ • Select approach and accept tradeoffs       │
 │ • Record rationale                           │
 └──────────────────────┬───────────────────────┘
                        ↓
 ┌──────────────────────────────────────────────┐
-│ 5. PLAN                                      │
+│ 6. PLAN                                      │
 │                                              │
 │ HUMAN — FIRST PASS                           │
 │ • Sequence change, checks, and rollback      │
@@ -68,28 +71,31 @@ Use product change when externally meaningful behavior is intentionally changing
 └──────────────────────┬───────────────────────┘
                        ↓
 ┌──────────────────────────────────────────────┐
-│ 6. IMPLEMENT                                 │
+│ 7. IMPLEMENT                                 │
 │ ENGINEER owns and understands the change     │
 │ AI — ASSIST with bounded contributions       │
 └──────────────────────┬───────────────────────┘
                        ↓
 ┌──────────────────────────────────────────────┐
-│ 7. AI REVIEW                                 │
+│ 8. AI REVIEW                                 │
 │ • Hidden behavior changes • complexity       │
 │ • Tests • coupling • plan compliance         │
 └──────────────────────┬───────────────────────┘
                        ↓
+          HUMAN DISPOSITIONS EACH MATERIAL
+          AI FINDING WITH RATIONALE / EVIDENCE
+                       ↓
 ┌──────────────────────────────────────────────┐
-│ 8. INDEPENDENT HUMAN REVIEW                  │
+│ 9. INDEPENDENT HUMAN REVIEW                  │
 │ • Reviewer is not the implementer            │
 │ • Final judgment on preservation/improvement │
 └──────────────────────┬───────────────────────┘
                        ↓
-       9. HUMAN AUTHORIZES DEPLOY / RELEASE
+       10. HUMAN AUTHORIZES DEPLOY / RELEASE
                     WHEN APPLICABLE
                        ↓
 ┌──────────────────────────────────────────────┐
-│ 10. VERIFY                                   │
+│ 11. VERIFY                                   │
 │                                              │
 │ HUMAN                                        │
 │ • Verify invariants                          │
@@ -100,12 +106,13 @@ Use product change when externally meaningful behavior is intentionally changing
 └──────────────────────┬───────────────────────┘
                        ↓
 ┌──────────────────────────────────────────────┐
-│ 11. AI AUDIT                                 │
+│ 12. AI AUDIT                                 │
 │ • Compare invariants, target, plan, reviews, │
 │   deployment, and observed evidence          │
-│ HUMAN disposes material findings             │
 └──────────────────────┬───────────────────────┘
                        ↓
+          HUMAN DISPOSITIONS AUDIT FINDINGS
+                       ↓
                 ┌───────────────┐
                 │ INVARIANTS    │
                 │ PRESERVED?    │
@@ -118,7 +125,7 @@ Use product change when externally meaningful behavior is intentionally changing
                      │  │ IMPROVED?      │
                      │  └───────┬────────┘
                      │     NO ↙   ↘ YES
-                     │       │      └────► HUMAN OUTCOME GATE
+                     │       │      └────► HUMAN OUTCOME GATE (13)
                      │       ▼
                      │  HUMAN CHOOSES
                      │  ├─ Rework ─────────────↺ IMPLEMENT
@@ -144,14 +151,15 @@ Preservation and improvement are separate judgments. A failed invariant cannot b
 | Invariants | Behavior that must remain unchanged, scope, and non-goals | Identify overlooked contracts and consumers | Explicit invariants and exclusions | Human accepts the preservation contract |
 | Baseline | Current quality evidence and measurement validity | Gather metrics and identify measurement gaps | Tests, measurements, structural evidence, or observations | Baseline is credible enough for comparison |
 | Target | Quality to improve, success threshold, and tradeoffs | Suggest measures and unintended effects | Target quality and acceptance signal | Improvement can be evaluated |
-| Options and decision | Initial approach, selection, and risk | Expand alternatives, expose coupling, and challenge abstraction | Options, decision, and rationale | Human approves the approach |
+| 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 | Disposition of valid findings | Review for hidden behavior changes, incidental complexity, tests, and plan alignment | AI findings and dispositions | Blocking findings are resolved or rejected with rationale |
+| 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 |
 | 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 | Audit findings and dispositions | Human has reviewed material findings |
+| 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 |
 | Outcome | Acceptance, rollback, partial result, or new work | Summarize learning | Outcome, remaining debt, and follow-ups | Human accepts closure |
 
 ## Preservation and improvement chain
@@ -172,7 +180,13 @@ HUMAN DECISION / FIRST-PASS PLAN
 ENGINEER-OWNED CHANGESET
                │
                ▼
-AI REVIEW + INDEPENDENT HUMAN REVIEW
+SNAPSHOT-BOUND AI REVIEW
+               │
+               ▼
+IMPLEMENTING-HUMAN DISPOSITION
+               │
+               ▼
+INDEPENDENT HUMAN REVIEW
                │
                ▼
 HUMAN-AUTHORIZED DEPLOYMENT WHEN APPLICABLE

package/generated/reference/docs/{workflows → guide/workflows}/investigation.md

@@ -1,5 +1,7 @@
 # Investigation Workflow
 
+Audience: AHEAD practitioners
+
 Status: pilot v0.1
 
 ## Outcome
@@ -72,6 +74,8 @@ An investigation may end with no action, insufficient evidence, several viable i
 │ AI — ASSIST                                  │
 │ • May fully generate an isolated throwaway   │
 │   prototype under prototype policy           │
+│ HUMAN records prototype disposition, or      │
+│ explicitly records that none was used        │
 └──────────────────────┬───────────────────────┘
                        ↓
                 ┌───────────────┐
@@ -110,7 +114,7 @@ Stopping conditions may be satisfied by enough evidence for a conclusion, exhaus
 | Frame | Question, decision relevance, audience, scope, and initial understanding | Clarify ambiguity and identify adjacent questions | Primary question and why it matters | Human accepts the question |
 | Bound | Confidence needed, exclusions, time or evidence budget, and stopping conditions | Challenge whether the question is answerable | Scope, limits, and stopping rule | Investigation can proceed without unbounded research |
 | Gather | Source evaluation and evidence access | Locate, summarize, compare, cite, and expose conflicts | Evidence links, source quality, and observations | Relevant available evidence is assembled |
-| Model and explore | Mental model, path selection, test authorization, and interpretation | Generate hypotheses, analysis approaches, or prototype ideas | Model, assumptions, hypotheses, tests, and results | Evidence is sufficient for synthesis or budget is reached |
+| Model and explore | Mental model, path selection, test authorization, interpretation, and prototype disposition | Generate hypotheses, analysis approaches, or an isolated disposable prototype | Model, predictions, tests, results, and human prototype disposition or no-prototype record | Evidence is sufficient for synthesis or budget is reached |
 | Synthesize | Meaning, confidence, contradictory evidence, and limitations | Organize findings and challenge overclaiming | Findings, confidence, limits, and unknowns | Human can state a bounded conclusion |
 | Conclude and route | Accepted conclusion, recommendation, and next workflow | Suggest follow-up questions or routes | Conclusion and linked decision/change/debug/improvement runs | Human accepts closure or explicitly extends the investigation |
 

package/generated/reference/docs/{workflows → guide/workflows}/operational-stabilization.md

@@ -1,5 +1,7 @@
 # Operational Stabilization Workflow
 
+Audience: AHEAD practitioners
+
 Status: pilot v0.1
 
 ## Outcome
@@ -40,7 +42,8 @@ Incident mode is an urgency and coordination overlay. It does not assert a cause
         │                                            │
         ▼                                            ▼
 ┌──────────────────────┐          ┌──────────────────────┐
-│ 2A. INVESTIGATE      │          │ 2B. STABILIZE        │
+│ 2A. RESPOND:         │          │ 2B. RESPOND:         │
+│ INVESTIGATE          │          │ STABILIZE            │
 │                      │          │                      │
 │ HUMAN LEADS          │          │ HUMAN LEADS          │
 │ • Model system       │          │ • Set priorities     │
@@ -55,7 +58,7 @@ Incident mode is an urgency and coordination overlay. It does not assert a cause
            │ CONTINUES                         │
            │ WHILE NEEDED                      ▼
            │                      ┌─────────────────────────┐
-           │                      │ 3. HUMAN ACTION GATE    │
+           │                      │ 2C. HUMAN ACTION GATE   │
            │ MAY INFORM           │                         │
            ├─ - - - - - - - - - ►│ • Authorize actor/scope │
            │   NO BARRIER         │ • Blast radius          │
@@ -64,14 +67,14 @@ Incident mode is an urgency and coordination overlay. It does not assert a cause
            │                      └────────────┬────────────┘
            │                                   ↓
 ┌──────────────────────────────────────────────┐
-│ 4. EXECUTE AND OBSERVE                       │
+│ 3. EXECUTE AND OBSERVE                       │
 │                                              │
 │ HUMAN / PREAUTHORIZED AUTOMATION             │
 │ • Performs the operational action            │
 │                                              │
 │ AI — ASSIST                                  │
-│ • May act only through separate, scoped,     │
-│   human-authorized operational permission    │
+│ • Interprets authorized observations         │
+│ • Does not execute the intervention          │
 │ • Workflow phase grants no production access │
 └──────────────────────┬───────────────────────┘
                        ↓
@@ -82,7 +85,7 @@ Incident mode is an urgency and coordination overlay. It does not assert a cause
           ↺ INVESTIGATE     │
             / STABILIZE     ▼
 ┌──────────────────────────────────────────────┐
-│ 5. VERIFY RECOVERY                           │
+│ 4. VERIFY RECOVERY                           │
 │                                              │
 │ HUMAN                                        │
 │ • Verify convergence and user-visible state │
@@ -92,7 +95,7 @@ Incident mode is an urgency and coordination overlay. It does not assert a cause
 └──────────────────────┬───────────────────────┘
                        ↓
 ┌──────────────────────────────────────────────┐
-│ 6. MONITOR RECURRENCE                        │
+│ 5. MONITOR RECURRENCE                        │
 │ HUMAN selects duration and signals           │
 │ AI — ASSIST                                  │
 │ • Summarize authorized telemetry             │
@@ -105,7 +108,7 @@ Incident mode is an urgency and coordination overlay. It does not assert a cause
           ↺ INVESTIGATE     │
             / STABILIZE     ▼
 ┌──────────────────────────────────────────────┐
-│ 7. HUMAN OUTCOME                             │
+│ 6. HUMAN OUTCOME                             │
 │ • Accept closure and remaining risk          │
 │ • Link corrective, investigation, decision, │
 │   or improvement follow-up runs              │
@@ -114,14 +117,15 @@ Incident mode is an urgency and coordination overlay. It does not assert a cause
 
 Investigation and stabilization proceed independently: there is no join gate. Investigation may inform an intervention and continue after it, but service restoration does not wait for a complete causal explanation when a human authorizes a proportionate intervention.
 
+The executable `respond` phase contains both parallel tracks and the human action gate shown as 2A–2C. Combining their evidence in one phase visit preserves the no-join rule: a bounded intervention may be authorized while causal investigation remains incomplete.
+
 ## Minimal phases
 
 | Phase | Human owns | AI may | Minimum record | Advance when |
 |---|---|---|---|---|
-| Detect and assess | Incident declaration, impact, scope, severity, and desired operating state | Correlate authorized signals and expose missing information | Timeline start, affected users/systems, actual and desired state | Response mode and ownership are clear |
-| Investigate | System/control-loop model, hypothesis selection, test authorization, and conclusions | Organize telemetry, identify changes, generate hypotheses, find contradictions | Facts, timeline, model, hypotheses, tests, and unknowns | Enough is known to guide action or bound uncertainty |
-| Stabilize | Containment, mitigation, recovery priorities, and risk | Compare interventions, rollback paths, and likely side effects | Candidate action, purpose, scope, blast radius, rollback | Human authorizes consequential action |
-| Execute and observe | Action execution and interpretation | Assist only within separately authorized operational permissions | Actor, command or change, time, result, and new evidence | Result is known and desired state is approached |
+| Assess | Response-mode declaration, impact, scope, urgency, desired state, ownership, and recovery signals | Correlate authorized signals and expose missing information after the human assessment begins | Assessment and response-mode record | Response mode, ownership, boundaries, and recovery criteria are clear |
+| Respond | System model, investigation direction, stabilization priorities, and selected intervention | Organize telemetry, generate hypotheses, compare interventions, and expose contradictions or side effects | Human model, optional investigation ledger, and bounded intervention with rollback and stop conditions | Human authorizes the consequential action; proven root cause is not required |
+| Execute and observe | Action execution, stop or rollback decisions, and interpretation | Analyze observations; AI has no execute capability in this phase | Actor, command or change, time, result, and new evidence | Result is known and desired state is approached |
 | Verify recovery | Recovery criteria and user-visible validation | Analyze convergence and recurrence indicators | Health, convergence, and external behavior evidence | Recovery is demonstrated, not merely assumed |
 | Monitor | Duration and signals sufficient to detect recurrence | Summarize authorized telemetry | Monitoring window and result | Human accepts stability or reopens response |
 | Outcome and follow-up | Closure, remaining risk, causal confidence, and routed work | Summarize timeline and proposed follow-ups | Outcome, unknowns, deferred records, linked runs | Human accepts closure and follow-up disposition |

package/generated/reference/docs/{workflows → guide/workflows}/product-change.md

@@ -1,5 +1,7 @@
 # Product Change Workflow
 
+Audience: AHEAD practitioners
+
 Status: pilot v0.1
 
 ## Outcome
@@ -110,6 +112,9 @@ Do not use it when the main task is explaining an observed failure, restoring a
 │ • Maintainability                            │
 └──────────────────────┬───────────────────────┘
                        ↓
+          HUMAN DISPOSITIONS EACH MATERIAL
+          AI FINDING WITH RATIONALE / EVIDENCE
+                       ↓
 ┌──────────────────────────────────────────────┐
 │ 9. INDEPENDENT HUMAN REVIEW                  │
 │ • Final engineering judgment by a reviewer   │
@@ -123,6 +128,8 @@ Do not use it when the main task is explaining an observed failure, restoring a
                        ↓
                   12. AI AUDIT
                        ↓
+          HUMAN DISPOSITIONS AUDIT FINDINGS
+                       ↓
 ┌──────────────────────────────────────────────┐
 │ 13. HUMAN OUTCOME                            │
 │ • Accept, roll back, follow up, or abandon   │
@@ -146,11 +153,11 @@ An important unknown is disposed only when it is answered or an accountable huma
 | Decide | Selection and consequences | Check rationale and surface risks | Decision, rationale, tradeoffs, reversibility | Accountable human approves the decision |
 | Plan | First-pass implementation plan | Identify gaps, dependencies, tests, risks, and rollback needs | Sequenced plan and deviations policy | Human approves the final plan |
 | Implement | Code and engineering changes | Bounded generation, explanation, tests, debugging, and refactoring assistance | Linked changeset and plan deviations | Work is ready for independent review and checks pass |
-| AI review | Resolution of valid findings | Review behavior, security, tests, architecture, and plan alignment | Findings and dispositions | Blocking findings are resolved or rejected with rationale |
+| AI review | Validate and disposition every material AI finding | Review the exact snapshot for behavior, security, tests, architecture, 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 engineering judgment by someone other than the implementer | Answer targeted questions and retrieve evidence | 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 and observe | Evaluation against intended behavior | Suggest checks and analyze authorized observations | Test, deployment, and user-visible evidence | Intended outcome is demonstrated or failure is recorded |
-| AI audit | Disposition of findings and any required response | Compare the result with the problem, decision, plan, reviews, and observed behavior; identify divergence, weak evidence, and missed learning | Audit findings and dispositions | Human has reviewed material findings |
+| AI audit | Disposition of findings and any required response | Compare the result with the problem, decision, plan, reviews, and observed behavior; identify divergence, weak evidence, and missed learning | AI audit findings; separate human disposition | The human disposer accepts the audit gate or reopens work |
 | Outcome | Acceptance, rollback, follow-up, or abandonment | Summarize learning | Result, uncertainty, follow-ups | Human accepts closure or routes more work |
 
 ## Artifact and evidence chain
@@ -174,7 +181,13 @@ HUMAN FIRST-PASS / FINAL PLAN
 CHANGESET / TESTS
             │
             ▼
-AI REVIEW / INDEPENDENT HUMAN REVIEW
+SNAPSHOT-BOUND AI REVIEW
+            │
+            ▼
+IMPLEMENTING-HUMAN DISPOSITION
+            │
+            ▼
+INDEPENDENT HUMAN REVIEW
             │
             ▼
 HUMAN-AUTHORIZED DEPLOYMENT