ahead-pi 0.2.0 → 0.2.1

package/generated/reference/docs/workflows/investigation.md

@@ -0,0 +1,159 @@
+# Investigation Workflow
+
+Status: pilot v0.1
+
+## Outcome
+
+Use this flow when the primary deliverable is knowledge or reduced uncertainty and no intervention has yet been selected. It may answer feasibility, causal, capacity, vendor, architectural, or technical questions.
+
+An investigation may end with no action, insufficient evidence, several viable interventions, or work routed to another flow.
+
+## Lifecycle
+
+```text
+┌──────────────────────────────────────────────┐
+│ 1. FRAME QUESTION                            │
+│                                              │
+│ HUMAN                                        │
+│ • State the question and why it matters      │
+│ • Record initial understanding               │
+│ • Name audience or dependent decision        │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 2. BOUND INVESTIGATION                       │
+│                                              │
+│ HUMAN                                        │
+│ • Define scope, exclusions, confidence need  │
+│ • Set time/evidence budget and stopping rule │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Challenge whether it is answerable         │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 3. GATHER EVIDENCE                           │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Locate, summarize, compare, and cite       │
+│ • Expose conflicting or missing evidence     │
+│                                              │
+│ HUMAN                                        │
+│ • Evaluate source quality and relevance      │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 4. HUMAN MODEL                               │
+│ • Build/update the explanation of the domain │
+│ • Record assumptions and unknowns            │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 5. EXPLORATION PATHS                         │
+│                                              │
+│ HUMAN                                        │
+│ • Contribute/select what is worth exploring  │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Generate hypotheses and alternatives       │
+│ • Suggest analyses, tests, or prototypes     │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 6. HUMAN SELECTS AND AUTHORIZES              │
+│ • Test / analysis / disposable prototype     │
+│ • Prediction, safety, scope, and disposal    │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 7. EXECUTE EXPLORATION                       │
+│                                              │
+│ HUMAN / ENGINEER OWNS THE EXPERIMENT         │
+│ AI — ASSIST                                  │
+│ • May fully generate an isolated throwaway   │
+│   prototype under prototype policy           │
+└──────────────────────┬───────────────────────┘
+                       ↓
+                ┌───────────────┐
+                │ STOPPING      │
+                │ CONDITION     │
+                │ REACHED?      │
+                └───────┬───────┘
+                   NO ↙   ↘ YES
+           ↺ MODEL / PATHS  │
+                            ▼
+┌──────────────────────────────────────────────┐
+│ 8. SYNTHESIZE                                │
+│                                              │
+│ HUMAN                                        │
+│ • Interpret evidence, contradictions, limits │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Organize findings and challenge overclaims │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 9. HUMAN CONCLUSION / OUTCOME GATE           │
+│ • State conclusion, confidence, and unknowns │
+│ • Recommend no action or link another flow   │
+└──────────────────────────────────────────────┘
+```
+
+Full vibe coding is permitted for an isolated, explicitly disposable prototype when its purpose is learning. The learning is retained; prototype code is discarded or deliberately re-enters the appropriate production workflow.
+
+Stopping conditions may be satisfied by enough evidence for a conclusion, exhaustion of the agreed time or evidence budget, discovery that the question is not currently answerable, or another human-approved boundary. Therefore “insufficient evidence” can advance to synthesis and an honest conclusion rather than forcing an endless loop.
+
+## Minimal phases
+
+| Phase | Human owns | AI may | Minimum record | Advance when |
+|---|---|---|---|---|
+| 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 |
+| 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 |
+
+## Knowledge chain
+
+```text
+HUMAN QUESTION / RELEVANCE
+           │
+           ▼
+HUMAN SCOPE / STOPPING RULE
+           │
+           ▼
+AI-ASSISTED EVIDENCE GATHERING
+HUMAN SOURCE EVALUATION
+           │
+           ▼
+HUMAN MODEL / ASSUMPTIONS
+           │
+           ▼
+AI-EXPANDED EXPLORATION PATHS
+HUMAN-SELECTED TEST / ANALYSIS / PROTOTYPE
+           │
+           ▼
+RESULTS / CONTRADICTIONS
+           │
+           ▼
+HUMAN CONCLUSION / CONFIDENCE / LIMITS
+           │
+           ▼
+HUMAN RECOMMENDATION / LINKED RUN
+```
+
+## Non-waivable pilot rules
+
+- The question is human-owned; AI does not quietly redefine it.
+- Facts, retrieved claims, inference, and AI synthesis remain distinguishable.
+- Important citations are followed to authoritative sources.
+- A prototype demonstrates only what it actually tested.
+- “Insufficient evidence” is a valid result.
+
+## Pilot questions
+
+- Were the stopping conditions usable or did research expand indefinitely?
+- Did the conclusion state confidence and contradictory evidence honestly?
+- Did a disposable prototype answer the learning question without leaking into production?
+- Was the next workflow clear when the investigation ended?

package/generated/reference/docs/workflows/operational-stabilization.md

@@ -0,0 +1,185 @@
+# Operational Stabilization Workflow
+
+Status: pilot v0.1
+
+## Outcome
+
+Use this flow when a live system is outside an acceptable operating state and the immediate outcome is restoration, stabilization, or demonstrated convergence. It covers code and non-code causes such as reconciliation storms, configuration drift, capacity exhaustion, provider behavior, dependency failure, and emergent controller interaction.
+
+Incident mode is an urgency and coordination overlay. It does not assert a cause.
+
+## Lifecycle
+
+```text
+             LIVE SYSTEM OUTSIDE
+           ACCEPTABLE OPERATING STATE
+                       │
+                       ▼
+┌──────────────────────────────────────────────┐
+│ 1. ASSESS                                    │
+│                                              │
+│ HUMAN                                        │
+│ • Assess impact, urgency, and scope          │
+│ • Define desired versus actual state         │
+│ • Assign accountable ownership               │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Correlate authorized signals               │
+│ • Identify missing information               │
+└──────────────────────┬───────────────────────┘
+                       ↓
+                ┌───────────────┐
+                │ HUMAN SELECTS │
+                │ RESPONSE MODE │
+                │ Normal /      │
+                │ incident /    │
+                │ emergency     │
+                └───────┬───────┘
+                        ↓
+        ┌──────── PARALLEL — NO JOIN BARRIER ────────┐
+        │                                            │
+        ▼                                            ▼
+┌──────────────────────┐          ┌──────────────────────┐
+│ 2A. INVESTIGATE      │          │ 2B. STABILIZE        │
+│                      │          │                      │
+│ HUMAN LEADS          │          │ HUMAN LEADS          │
+│ • Model system       │          │ • Set priorities     │
+│ • Select tests       │          │ • Select candidate   │
+│ • Interpret evidence│          │   intervention       │
+│                      │          │ • Assess risk        │
+│ AI — ASSIST          │          │                      │
+│ • Organize telemetry│          │ AI — ASSIST          │
+│ • Suggest hypotheses│          │ • Compare actions    │
+│ • Find conflicts     │          │ • Find side effects  │
+└──────────┬───────────┘          └──────────┬───────────┘
+           │ CONTINUES                         │
+           │ WHILE NEEDED                      ▼
+           │                      ┌─────────────────────────┐
+           │                      │ 3. HUMAN ACTION GATE    │
+           │ MAY INFORM           │                         │
+           ├─ - - - - - - - - - ►│ • Authorize actor/scope │
+           │   NO BARRIER         │ • Blast radius          │
+           │                      │ • Rollback/containment  │
+           │                      │ • Accepted uncertainty  │
+           │                      └────────────┬────────────┘
+           │                                   ↓
+┌──────────────────────────────────────────────┐
+│ 4. EXECUTE AND OBSERVE                       │
+│                                              │
+│ HUMAN / PREAUTHORIZED AUTOMATION             │
+│ • Performs the operational action            │
+│                                              │
+│ AI — ASSIST                                  │
+│ • May act only through separate, scoped,     │
+│   human-authorized operational permission    │
+│ • Workflow phase grants no production access │
+└──────────────────────┬───────────────────────┘
+                       ↓
+                ┌───────────────┐
+                │ CONVERGING?   │
+                └───────┬───────┘
+                   NO ↙   ↘ YES
+          ↺ INVESTIGATE     │
+            / STABILIZE     ▼
+┌──────────────────────────────────────────────┐
+│ 5. VERIFY RECOVERY                           │
+│                                              │
+│ HUMAN                                        │
+│ • Verify convergence and user-visible state │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Analyze authorized recovery indicators     │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 6. MONITOR RECURRENCE                        │
+│ HUMAN selects duration and signals           │
+│ AI — ASSIST                                  │
+│ • Summarize authorized telemetry             │
+└──────────────────────┬───────────────────────┘
+                       ↓
+                ┌───────────────┐
+                │ STABLE?       │
+                └───────┬───────┘
+                   NO ↙   ↘ YES
+          ↺ INVESTIGATE     │
+            / STABILIZE     ▼
+┌──────────────────────────────────────────────┐
+│ 7. HUMAN OUTCOME                             │
+│ • Accept closure and remaining risk          │
+│ • Link corrective, investigation, decision, │
+│   or improvement follow-up runs              │
+└──────────────────────────────────────────────┘
+```
+
+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.
+
+## 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 |
+| 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 |
+
+## Parallel evidence and action chains
+
+```text
+OBSERVED OPERATING CONDITION
+              │
+              ▼
+HUMAN-OWNED IMPACT / SCOPE / DESIRED STATE
+              │
+       ┌──────┴────────┐
+       ▼               ▼
+EVIDENCE / MODEL   STABILIZATION OPTIONS
+       │ CONTINUES         │
+       ▼                   ▼
+HUMAN-SELECTED      HUMAN AUTHORIZATION
+HYPOTHESES / TESTS         │
+       │ MAY INFORM        ▼
+       ├─ - - - - - ► ACTION / OBSERVED RESULT
+       │                   │
+       └──── updates ◄─────┘
+                           │
+                           ▼
+            HUMAN-ACCEPTED RECOVERY / CONVERGENCE
+                           │
+                           ▼
+REMAINING RISK / LINKED FOLLOW-UP RUNS
+
+The investigation chain has no join barrier. AI assists
+evidence gathering, option generation, hypothesis
+generation, and analysis; it owns no gate.
+```
+
+## Incident and emergency overlay
+
+During incident or emergency mode, maintain at minimum:
+
+- current owner and impact;
+- timestamped consequential actions and decisions;
+- actor, rationale, scope, blast radius, rollback, and result;
+- current recovery criteria and communications owner;
+- deferred records that must be reconstructed after stabilization.
+
+## Non-waivable pilot rules
+
+- Workflow permission is not production authorization.
+- A live intervention requires an accountable human unless existing automation was previously authorized for that action.
+- Any lasting engineering change produced during stabilization still requires a human first-pass plan and independent human review, either in this record or a linked change run; emergency policy may defer but not erase those gates.
+- Kubernetes readiness, controller status, or a successful command is not automatically user-visible recovery.
+- The conclusion may include mechanism, trigger, enabling conditions, and detection or containment gaps rather than one root cause.
+- Closure does not require every follow-up to remain inside the operational run.
+
+## Pilot questions
+
+- What threshold should activate incident mode?
+- Which records were feasible during response versus reconstructed later?
+- When was unknown-cause remediation justified?
+- What evidence demonstrated convergence and user-visible recovery?
+- Did linked follow-up runs prevent the incident from remaining permanently open?

package/generated/reference/docs/workflows/product-change.md

@@ -0,0 +1,205 @@
+# Product Change Workflow
+
+Status: pilot v0.1
+
+## Outcome
+
+Use this flow when the dominant outcome is new, changed, adapted, migrated, or retired externally meaningful behavior. It ends with verified intended behavior and an accountable human outcome decision.
+
+Do not use it when the main task is explaining an observed failure, restoring a live system, making a decision without implementation, producing knowledge, or improving internals while preserving behavior.
+
+## Lifecycle
+
+```text
+┌──────────────────────────────────────────────┐
+│ 1. DEFINE PROBLEM                            │
+│                                              │
+│ HUMAN                                        │
+│ • Define desired outcome and users           │
+│ • Define constraints and scope               │
+│ • Define success signals                     │
+│ • Define initial questions                   │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 2. RESEARCH                                  │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Search authorized sources                  │
+│ • Compile and cite evidence                  │
+│ • Answer known questions                     │
+│ • Identify contradictions and gaps           │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 3. RESEARCH REVIEW                           │
+│                                              │
+│ HUMAN                                        │
+│ • Read and understand the research           │
+│ • Ask follow-up questions                    │
+│ • Challenge findings                         │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Identify questions humans missed           │
+│ • Research unanswered questions              │
+└──────────────────────┬───────────────────────┘
+                       ↓
+                ┌───────────────┐
+                │ IMPORTANT     │
+                │ UNKNOWNS      │
+                │ DISPOSED?     │
+                └───────┬───────┘
+                   NO ↙   ↘ YES
+                      │     │
+             ↺ RESEARCH     ↓
+┌──────────────────────────────────────────────┐
+│ 4. OPTIONS                                   │
+│                                              │
+│ HUMAN — FIRST PASS                           │
+│ • Propose at least one viable approach       │
+│ • Explain initial reasoning                  │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Research and challenge the human option    │
+│ • Identify additional approaches             │
+│ • Compare tradeoffs and risks                │
+│                                              │
+│ HUMAN                                        │
+│ • Evaluate, refine, add, or remove options   │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 5. DECISION                                  │
+│                                              │
+│ HUMAN GATE                                   │
+│ • Select approach                            │
+│ • Accept tradeoffs and unknowns              │
+│ • Record rationale and reversibility         │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 6. PLAN                                      │
+│                                              │
+│ HUMAN — FIRST PASS                           │
+│ • Define implementation steps and systems    │
+│ • Define testing, rollout, and recovery       │
+│                                              │
+│ AI — OPTIONAL ASSISTANCE                     │
+│ • Find gaps, dependencies, risks, edge cases │
+│ • Challenge assumptions                      │
+│                                              │
+│ HUMAN                                        │
+│ • Finalize and approve the plan              │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 7. IMPLEMENT                                 │
+│                                              │
+│ ENGINEER                                     │
+│ • Own and understand the implementation      │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Bounded code, tests, and explanation       │
+│ • Debugging and refactoring suggestions      │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 8. AI REVIEW                                 │
+│ • Correctness • security • tests             │
+│ • Architecture • plan compliance             │
+│ • Maintainability                            │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 9. INDEPENDENT HUMAN REVIEW                  │
+│ • Final engineering judgment by a reviewer   │
+│   other than the implementer                 │
+│ • Approve or request changes                 │
+└──────────────────────┬───────────────────────┘
+                       ↓
+       10. HUMAN AUTHORIZES DEPLOY / RELEASE
+                       ↓
+           11. HUMAN VERIFIES / OBSERVES
+                       ↓
+                  12. AI AUDIT
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 13. HUMAN OUTCOME                            │
+│ • Accept, roll back, follow up, or abandon   │
+│ • Record learning                            │
+└──────────────────────────────────────────────┘
+
+Review changes requested ─────────↺ IMPLEMENT
+Outcome not demonstrated ─────────↺ PLAN / IMPLEMENT
+```
+
+An important unknown is disposed only when it is answered or an accountable human explicitly accepts the uncertainty and its consequences. Merely recording or deferring it does not satisfy the gate.
+
+## Minimal phases
+
+| Phase | Human owns | AI may | Minimum record | Advance when |
+|---|---|---|---|---|
+| Define | Desired outcome, users, scope, constraints, initial questions | Clarify ambiguity and expose assumptions | Problem and success signals | Human accepts the framing |
+| Research | Reading and evaluating material | Gather internal/external evidence, cite, compare, identify gaps | Evidence links, findings, contradictions | Material evidence is available |
+| Questions | Understanding and disposition of unknowns | Find missing questions and research answers | Answered, accepted, blocked, or deferred unknowns | Important unknowns are answered or explicitly accepted |
+| Options | At least one initial approach and evaluation criteria | Expand, compare, challenge, add alternatives | Options and tradeoffs | Viable options are understood |
+| 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 |
+| 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 |
+| Outcome | Acceptance, rollback, follow-up, or abandonment | Summarize learning | Result, uncertainty, follow-ups | Human accepts closure or routes more work |
+
+## Artifact and evidence chain
+
+```text
+PROBLEM / SUCCESS SIGNALS
+            │
+            ▼
+RESEARCH / QUESTIONS
+            │
+            ▼
+HUMAN OPTION / ALTERNATIVES
+            │
+            ▼
+HUMAN DECISION / RATIONALE
+            │
+            ▼
+HUMAN FIRST-PASS / FINAL PLAN
+            │
+            ▼
+CHANGESET / TESTS
+            │
+            ▼
+AI REVIEW / INDEPENDENT HUMAN REVIEW
+            │
+            ▼
+HUMAN-AUTHORIZED DEPLOYMENT
+            │
+            ▼
+VERIFICATION / OBSERVATIONS
+            │
+            ▼
+AI AUDIT / HUMAN DISPOSITION
+            │
+            ▼
+HUMAN OUTCOME / LEARNING
+```
+
+## Non-waivable pilot rules
+
+- A human defines or affirms the problem and outcome.
+- A human contributes an option before AI expands the option set.
+- A human authors the first-pass plan.
+- AI review and implementer self-review do not satisfy independent human review.
+- Implementation completion is not deployment or outcome verification.
+
+## Pilot questions
+
+- Did separate research and question review improve the decision?
+- Did requiring a human option and first-pass plan improve understanding or only add ceremony?
+- Which changes were material enough to reopen the decision or plan?
+- What outcome evidence was available only after deployment?