ahead-pi 0.2.0 → 0.2.1

package/generated/reference/docs/workflows/corrective-debugging.md

@@ -0,0 +1,203 @@
+# Corrective Debugging Workflow
+
+Status: pilot v0.1
+
+## Outcome
+
+Use this flow when observed behavior conflicts with intended behavior and the dominant work is causal diagnosis plus correction. It ends with a verified correction or an explicit human acceptance of remaining uncertainty.
+
+Use operational stabilization instead when a live system is unhealthy and restoration or convergence is the immediate objective.
+
+## Lifecycle
+
+```text
+                  BUG REPORTED
+                       │
+                       ▼
+              ┌─────────────────┐
+              │ 1. CHARACTERIZE │
+              │                 │
+              │ HUMAN           │
+              │ • What happens? │
+              │ • Expected?     │
+              │ • When / where? │
+              │ • Impact/scope? │
+              │ • Reproducible? │
+              └───────┬─────────┘
+                      │
+                      ▼
+              ┌─────────────────┐
+              │ 2. HUMAN MODEL  │
+              │                 │
+              │ What do we      │
+              │ currently think │
+              │ is happening?   │
+              └───────┬─────────┘
+                      │
+                      ▼
+              ┌─────────────────┐
+              │ 3. AI ASSISTS   │
+              │ EVIDENCE REVIEW │
+              │                 │
+              │ • Code          │
+              │ • Logs/history  │
+              │ • Dependencies  │
+              │ • Runtime data  │
+              │ • Contradictions│
+              └───────┬─────────┘
+                      │
+                      ▼
+              ┌─────────────────┐
+              │ 4. HYPOTHESES   │
+              │                 │
+              │ HUMAN LEADS     │
+              │ AI ASSISTS      │
+              │ • H1 / H2 / H3  │
+              │ • Evidence FOR  │
+              │ • Evidence      │
+              │   AGAINST       │
+              └───────┬─────────┘
+                      │
+                      ▼
+              ┌─────────────────┐
+              │ 5. HUMAN SELECTS│
+              │ WHAT TO TEST    │
+              │                 │
+              │ • Prediction    │
+              │ • Safety/scope  │
+              └───────┬─────────┘
+                      │
+                      ▼
+              ┌─────────────────┐
+              │ 6. TEST         │
+              │ HYPOTHESIS      │
+              │                 │
+              │ HUMAN/ENGINEER  │
+              │ Run / inspect / │
+              │ instrument      │
+              │ AI — ASSIST     │
+              └───────┬─────────┘
+                      │
+                      ▼
+                ┌──────────────┐
+                │ HUMAN READY  │
+                │ TO CHOOSE?   │
+                └──────┬───────┘
+                   NO ↙  ↘ YES
+                     │    │
+                     │    ▼
+        ↺ HUMAN MODEL     HUMAN ACCEPTS DIAGNOSIS
+                          OR UNKNOWN CAUSE / RISK
+                                  │
+                                  ▼
+                         HUMAN FIX APPROACH
+                                  │
+                                  ▼
+                         HUMAN FIRST-PASS PLAN
+                                  │
+                                  ▼
+                       ENGINEER IMPLEMENTS
+                                  │
+                                  ▼
+                              AI REVIEW
+                                  │
+                                  ▼
+                    INDEPENDENT HUMAN REVIEW
+                                  │
+                                  ▼
+                  HUMAN AUTHORIZES DEPLOY / RELEASE
+                           WHEN APPLICABLE
+                                  │
+                                  ▼
+          HUMAN VERIFIES CORRECTION OF ORIGINAL FAILURE
+                                  │
+                                  ▼
+                 HUMAN OBSERVES DEPLOYED OUTCOME
+                                  │
+                                  ▼
+                              AI AUDIT
+                                  │
+                                  ▼
+                         HUMAN OUTCOME GATE
+
+Not corrected ───────────────────↺ HUMAN MODEL
+```
+
+Reproduction is useful but not a universal gate. Historical, intermittent, production-only, or already mitigated failures may proceed when the limitation is recorded.
+
+“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.
+
+## 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 |
+| 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 |
+| 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 |
+| 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
+
+```text
+OBSERVED FAILURE
+       │
+       ▼
+FACTS / EVIDENCE ──► HUMAN MENTAL MODEL
+                            │
+                            ▼
+            HUMAN-LED / AI-EXPANDED HYPOTHESES
+                            │
+                            ▼
+                 PREDICTION / TEST / RESULT
+                            │
+                            └────────────↺ MODEL
+                            │
+                            ▼
+                HUMAN CONCLUSION / CONFIDENCE
+                            │
+                            ▼
+             HUMAN CORRECTION DECISION / PLAN
+                            │
+                            ▼
+     ENGINEER CHANGE / AI REVIEW / INDEPENDENT REVIEW
+                            │
+                            ▼
+                HUMAN-AUTHORIZED DEPLOYMENT
+                            │
+                            ▼
+              CORRECTION VERIFICATION EVIDENCE
+                            │
+                            ▼
+                DEPLOYED OUTCOME EVIDENCE
+                            │
+                            ▼
+               AI AUDIT / HUMAN DISPOSITION
+                            │
+                            ▼
+                    HUMAN OUTCOME
+```
+
+## Non-waivable pilot rules
+
+- Facts, inferences, and hypotheses remain distinguishable.
+- AI hypotheses are candidates, not diagnoses.
+- The human chooses or authorizes tests and interprets their results.
+- A plausible cause is not treated as proven.
+- Fix validation and post-deployment outcome verification are distinct when deployment applies.
+- AI review and implementer self-review do not satisfy independent human review.
+- Implementation completion is not deployment, recovery, or outcome verification.
+
+## Pilot questions
+
+- What was the minimum useful investigation record?
+- Did recording predictions before tests reduce hindsight interpretation?
+- When was correction justified without a conclusive cause?
+- Did AI broaden hypotheses or anchor the investigator?

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

@@ -0,0 +1,149 @@
+# Decision Workflow
+
+Status: pilot v0.1
+
+## Outcome
+
+Use this flow when the deliverable is an accountable human choice among alternatives: architecture, buy versus build, technology selection, platform direction, policy, or another consequential course.
+
+Implementation is optional and normally belongs in a linked product-change or internal-improvement run.
+
+## Lifecycle
+
+```text
+┌──────────────────────────────────────────────┐
+│ 1. FRAME DECISION                            │
+│                                              │
+│ HUMAN                                        │
+│ • State the choice to be made                │
+│ • Name accountable decider/stakeholders      │
+│ • Define scope and deadline                  │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 2. DEFINE CRITERIA                           │
+│                                              │
+│ HUMAN                                        │
+│ • Goals • constraints • criteria             │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Expose hidden criteria and tensions        │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 3. RESEARCH AND QUESTIONS                    │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Gather cited evidence                      │
+│ • Find contradictions and missing questions  │
+│                                              │
+│ HUMAN                                        │
+│ • Read, evaluate, and accept unknowns        │
+└──────────────────────┬───────────────────────┘
+                       ↓
+                ┌───────────────┐
+                │ EVIDENCE      │
+                │ REVIEWED AND  │
+                │ UNCERTAINTY   │
+                │ DISPOSED?     │
+                └───────┬───────┘
+                   NO ↙   ↘ YES
+              ↺ RESEARCH    │
+                            ▼
+┌──────────────────────────────────────────────┐
+│ 4. HUMAN INITIAL OPTION                      │
+│ • Propose at least one viable course         │
+│ • Explain the initial reasoning              │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 5. EXPAND AND CHALLENGE OPTIONS              │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Add alternatives • compare • challenge     │
+│ • Surface consequences and risks             │
+│ • Analyze reversibility                      │
+│                                              │
+│ HUMAN                                        │
+│ • Evaluate and refine the option set         │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 6. HUMAN DECISION GATE                       │
+│ • Select the course                          │
+│ • Accept tradeoffs and uncertainty           │
+│ • Record rationale and dissent               │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 7. VALIDATE AND PUBLISH                      │
+│                                              │
+│ HUMAN                                        │
+│ • Validate consequences                      │
+│ • Set reversibility and review trigger       │
+│ • Link resulting work                        │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Challenge consistency and missing effects  │
+└──────────────────────┬───────────────────────┘
+                       ↓
+                 HUMAN OUTCOME
+
+Reframe or seek evidence ─────────↺ FRAME / RESEARCH
+```
+
+“Disposed” means the uncertainty is answered or the accountable human explicitly accepts it. AI does not introduce solution alternatives during research; option expansion begins only after the human initial option is recorded.
+
+## Minimal phases
+
+| Phase | Human owns | AI may | Minimum record | Advance when |
+|---|---|---|---|---|
+| 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 |
+| 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 |
+
+## Decision evidence chain
+
+```text
+HUMAN DECISION FRAME / CRITERIA
+              │
+              ▼
+AI-ASSISTED EVIDENCE / HUMAN-ACCEPTED UNKNOWNS
+              │
+              ▼
+HUMAN INITIAL OPTION
+              │
+              ▼
+AI-EXPANDED / HUMAN-EVALUATED OPTION SET
+              │
+              ▼
+TRADEOFFS / CONSEQUENCES
+              │
+              ▼
+HUMAN DECISION / RATIONALE / DISSENT
+              │
+              ▼
+HUMAN-OWNED REVERSIBILITY / REVIEW TRIGGER
+              │
+              ▼
+LINKED IMPLEMENTATION OR INVESTIGATION
+```
+
+## Non-waivable pilot rules
+
+- The accountable human defines the decision and evaluation criteria.
+- A human contributes an initial option before AI expands the option set.
+- AI does not select, approve, or manufacture consensus.
+- Unknowns and dissent are not erased by polished rationale.
+- The decision records when and why it should be revisited.
+
+## Pilot questions
+
+- Did human-first option generation preserve useful diversity?
+- Were the criteria defined before a preferred answer emerged?
+- Which evidence actually changed the decision?
+- Did the review trigger cause a stale decision to be revisited?

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

@@ -0,0 +1,207 @@
+# Internal Improvement Workflow
+
+Status: pilot v0.1
+
+## Outcome
+
+Use this flow when externally required behavior should remain invariant while an internal quality improves: maintainability, comprehensibility, performance, reliability margin, operability, testability, cost, or preventive risk reduction.
+
+Use product change when externally meaningful behavior is intentionally changing, or corrective debugging when an observed defect is the reason for the work.
+
+## Lifecycle
+
+```text
+┌──────────────────────────────────────────────┐
+│ 1. DEFINE INVARIANTS                         │
+│                                              │
+│ HUMAN                                        │
+│ • Define behavior that must not change       │
+│ • Define scope and non-goals                 │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Identify overlooked contracts/consumers    │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 2. BASELINE AND TARGET                       │
+│                                              │
+│ HUMAN                                        │
+│ • Accept current evidence and measurement    │
+│ • Define target quality                      │
+│ • Define success threshold                   │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Gather metrics • find measurement gaps     │
+│ • Suggest unintended effects to watch        │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 3. OPTIONS                                   │
+│                                              │
+│ HUMAN — FIRST PASS                           │
+│ • Propose at least one improvement approach  │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Expand alternatives • expose coupling      │
+│ • Challenge complexity and assumptions       │
+│                                              │
+│ HUMAN                                        │
+│ • Evaluate and refine options                │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 4. HUMAN DECISION GATE                       │
+│ • Select approach and accept tradeoffs       │
+│ • Record rationale                           │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 5. PLAN                                      │
+│                                              │
+│ HUMAN — FIRST PASS                           │
+│ • Sequence change, checks, and rollback      │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Find affected boundaries and missing tests │
+│                                              │
+│ HUMAN finalizes and approves                 │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 6. IMPLEMENT                                 │
+│ ENGINEER owns and understands the change     │
+│ AI — ASSIST with bounded contributions       │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 7. AI REVIEW                                 │
+│ • Hidden behavior changes • complexity       │
+│ • Tests • coupling • plan compliance         │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 8. INDEPENDENT HUMAN REVIEW                  │
+│ • Reviewer is not the implementer            │
+│ • Final judgment on preservation/improvement │
+└──────────────────────┬───────────────────────┘
+                       ↓
+       9. HUMAN AUTHORIZES DEPLOY / RELEASE
+                    WHEN APPLICABLE
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 10. VERIFY                                   │
+│                                              │
+│ HUMAN                                        │
+│ • Verify invariants                          │
+│ • Compare before/after target evidence       │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Analyze measurements / suggest checks      │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 11. AI AUDIT                                 │
+│ • Compare invariants, target, plan, reviews, │
+│   deployment, and observed evidence          │
+│ HUMAN disposes material findings             │
+└──────────────────────┬───────────────────────┘
+                       ↓
+                ┌───────────────┐
+                │ INVARIANTS    │
+                │ PRESERVED?    │
+                └───────┬───────┘
+                   NO ↙   ↘ YES
+                     │     │
+                     │     ▼
+                     │  ┌────────────────┐
+                     │  │ TARGET QUALITY │
+                     │  │ IMPROVED?      │
+                     │  └───────┬────────┘
+                     │     NO ↙   ↘ YES
+                     │       │      └────► HUMAN OUTCOME GATE
+                     │       ▼
+                     │  HUMAN CHOOSES
+                     │  ├─ Rework ─────────────↺ IMPLEMENT
+                     │  ├─ Roll back ─────────► HUMAN OUTCOME
+                     │  └─ Accept partial/no improvement
+                     │     with rationale ─────► HUMAN OUTCOME
+                     ▼
+              HUMAN CHOOSES
+              ├─ Rework ──────────────────────↺ IMPLEMENT
+              ├─ Roll back ──────────────────► HUMAN OUTCOME
+              └─ Reclassify ─────────────────► NEW PRODUCT CHANGE RUN
+                                                + HUMAN OUTCOME
+
+Review changes requested ─────────────↺ IMPLEMENT
+```
+
+Preservation and improvement are separate judgments. A failed invariant cannot be accepted as an internal improvement: the team must roll back, rework, or deliberately reclassify the work as a product change. If invariants hold but the target quality does not improve, a human may stop and record a partial or unsuccessful result rather than manufacture success.
+
+## Minimal phases
+
+| Phase | Human owns | AI may | Minimum record | Advance when |
+|---|---|---|---|---|
+| 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 |
+| 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 |
+| 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 |
+| Outcome | Acceptance, rollback, partial result, or new work | Summarize learning | Outcome, remaining debt, and follow-ups | Human accepts closure |
+
+## Preservation and improvement chain
+
+```text
+HUMAN-OWNED INVARIANTS / NON-GOALS
+               │
+               ▼
+HUMAN-ACCEPTED BASELINE / TARGET
+               │
+               ▼
+HUMAN OPTION + AI-EXPANDED ALTERNATIVES
+               │
+               ▼
+HUMAN DECISION / FIRST-PASS PLAN
+               │
+               ▼
+ENGINEER-OWNED CHANGESET
+               │
+               ▼
+AI REVIEW + INDEPENDENT HUMAN REVIEW
+               │
+               ▼
+HUMAN-AUTHORIZED DEPLOYMENT WHEN APPLICABLE
+               │
+               ▼
+HUMAN-ACCEPTED INVARIANT VERIFICATION
+AND BEFORE / AFTER COMPARISON
+               │
+               ▼
+AI AUDIT / HUMAN DISPOSITION
+               │
+               ▼
+HUMAN OUTCOME / REMAINING DEBT
+```
+
+## Non-waivable pilot rules
+
+- Invariants are stated before the change.
+- Passing existing tests alone does not prove preservation when those tests do not cover the contract.
+- AI may propose a refactor; humans decide whether it reduces conceptual complexity.
+- File movement or abstraction count is not itself an improvement.
+- The outcome compares before and after evidence against the declared target.
+- An invariant failure cannot close as a successful internal improvement.
+- AI review and implementer self-review do not satisfy independent human review.
+- Implementation completion is not deployment or outcome verification.
+
+## Pilot questions
+
+- Were the invariants specific enough to catch unintended behavior changes?
+- Did the selected measure reflect the quality people actually wanted?
+- Did the work reduce conceptual complexity or merely rearrange it?
+- When did an internal improvement reveal that a product change or bug flow was needed?