ahead-pi 0.2.1 → 0.3.0

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

@@ -23,20 +23,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 +51,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 +69,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 +104,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 +123,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 +149,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 +178,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/investigation.md

@@ -72,6 +72,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 +112,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/operational-stabilization.md

@@ -40,7 +40,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 +56,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 +65,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 +83,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 +93,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 +106,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 +115,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/product-change.md

@@ -110,6 +110,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 +126,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 +151,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 +179,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

package/generated/reference/index.json

@@ -2,13 +2,17 @@
   "generated_from": [
     "CONSTITUTION.md",
     "docs/acceptable-ai-use.md",
+    "docs/design/adapted-skill-guidance.md",
     "docs/design/debugging-and-operations.md",
     "docs/design/executable-workflows.md",
+    "docs/design/instruction-authoring.md",
     "docs/design/process-taxonomy.md",
+    "docs/design/review-workbench.md",
     "docs/engineering-practice.md",
     "docs/evidence/evidence-standard.md",
     "docs/evidence/research-map.md",
     "docs/rationale.md",
+    "docs/recommended-skills.md",
     "docs/references/pragmatic-programmer-page-index.md",
     "docs/references/submitted-engineering-notes.md",
     "docs/releasing-pi.md",
@@ -28,6 +32,9 @@
       "summary": "This constitution records the durable principles of **Assisted Human Engineering and Development**. Workflows and tools may evolve. These principles define what makes them AHEAD.",
       "phases": [
         "*"
+      ],
+      "workflows": [
+        "*"
       ]
     },
     {
@@ -37,6 +44,19 @@
       "summary": "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",
       "phases": [
         "*"
+      ],
+      "workflows": [
+        "*"
+      ]
+    },
+    {
+      "id": "design:adapted-skill-guidance",
+      "path": "docs/design/adapted-skill-guidance.md",
+      "title": "Adapted Skill Guidance",
+      "summary": "AHEAD reviewed the [Matt Pocock skills collection](https://www.skills.sh/mattpocock/skills), including the specifically discussed [grill-me](https://www.skills.sh/mattpocock/skills/grill-me), [prototype](https://www.skills.sh/mattpocock/ski",
+      "phases": [],
+      "workflows": [
+        "*"
       ]
     },
     {
@@ -44,7 +64,10 @@
       "path": "docs/design/debugging-and-operations.md",
       "title": "Debugging and Operational Investigation",
       "summary": "The minimal [corrective-debugging](../workflows/corrective-debugging.md) and [operational-stabilization](../workflows/operational-stabilization.md) profiles translate this discussion into pilotable flows. This document retains the reasoning",
-      "phases": []
+      "phases": [],
+      "workflows": [
+        "*"
+      ]
     },
     {
       "id": "design:executable-workflows",
@@ -53,6 +76,19 @@
       "summary": "The executable layer makes AHEAD workflow state durable and makes selected human/AI boundaries enforceable across integrations. It does not turn judgment into a checklist or make workflow artifacts proof of understanding.",
       "phases": [
         "*"
+      ],
+      "workflows": [
+        "*"
+      ]
+    },
+    {
+      "id": "design:instruction-authoring",
+      "path": "docs/design/instruction-authoring.md",
+      "title": "Instruction Authoring",
+      "summary": "AHEAD instructions are an executable interface to the framework. They should make the next valid behavior clear without duplicating the full Constitution, rationale, or workflow documentation into every model turn.",
+      "phases": [],
+      "workflows": [
+        "*"
       ]
     },
     {
@@ -60,7 +96,25 @@
       "path": "docs/design/process-taxonomy.md",
       "title": "AHEAD Process Taxonomy",
       "summary": "AHEAD should not create a workflow for every issue label. “Security,” “performance,” “data,” “incident,” and “technical debt” often describe risk, domain, urgency, or cause—not the kind of reasoning needed to complete the work.",
-      "phases": []
+      "phases": [],
+      "workflows": [
+        "*"
+      ]
+    },
+    {
+      "id": "design:review-workbench",
+      "path": "docs/design/review-workbench.md",
+      "title": "Review Workbench",
+      "summary": "The review workbench makes the handoff from implementation to independent human review explicit and inspectable:",
+      "phases": [
+        "ai-review",
+        "human-review"
+      ],
+      "workflows": [
+        "product-change",
+        "corrective-debugging",
+        "internal-improvement"
+      ]
     },
     {
       "id": "engineering-practice",
@@ -69,6 +123,9 @@
       "summary": "AHEAD is not only a sequence of AI gates. It is a way of practicing engineering. This guide distills general habits from the submitted starting list into a smaller set of principles that can be remembered, applied, and evaluated.",
       "phases": [
         "*"
+      ],
+      "workflows": [
+        "*"
       ]
     },
     {
@@ -86,6 +143,9 @@
         "verify",
         "ai-audit",
         "outcome"
+      ],
+      "workflows": [
+        "*"
       ]
     },
     {
@@ -93,7 +153,10 @@
       "path": "docs/evidence/research-map.md",
       "title": "AHEAD Research Map",
       "summary": "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.",
-      "phases": []
+      "phases": [],
+      "workflows": [
+        "*"
+      ]
     },
     {
       "id": "rationale",
@@ -102,6 +165,19 @@
       "summary": "AI can make software engineering faster. It can search broadly, synthesize information, identify omissions, generate alternatives, produce routine code, explain unfamiliar systems, and review more material than a person can inspect unaided.",
       "phases": [
         "*"
+      ],
+      "workflows": [
+        "*"
+      ]
+    },
+    {
+      "id": "recommended-skills",
+      "path": "docs/recommended-skills.md",
+      "title": "Recommended Skills",
+      "summary": "AHEAD may recommend independently maintained agent skills when they strengthen an active phase. Recommendations are references, not bundled code or silent dependencies. A human chooses whether to inspect and install one, and AHEAD's workflo",
+      "phases": [],
+      "workflows": [
+        "*"
       ]
     },
     {
@@ -109,63 +185,102 @@
       "path": "docs/references/pragmatic-programmer-page-index.md",
       "title": "*The Pragmatic Programmer* Page Index",
       "summary": "This index preserves the page-level provenance from the original AHEAD engineering-practice notes for:",
-      "phases": []
+      "phases": [],
+      "workflows": [
+        "*"
+      ]
     },
     {
       "id": "references:submitted-engineering-notes",
       "path": "docs/references/submitted-engineering-notes.md",
       "title": "Submitted Engineering Notes",
       "summary": "This document preserves submitted engineering tips, checklists, and practices that are intentionally condensed in the [AHEAD Engineering Practice](../engineering-practice.md) guide. It is a source record, not a claim that every item is an e",
-      "phases": []
+      "phases": [],
+      "workflows": [
+        "*"
+      ]
     },
     {
       "id": "releasing-pi",
       "path": "docs/releasing-pi.md",
       "title": "Releasing the Pi Extension",
       "summary": "- npm package: `ahead-pi` - package source: `integrations/pi` - release workflow: `.github/workflows/publish-pi.yml` - release tag: `pi-v<package-version>` - stable npm dist-tag: `latest` - prerelease npm dist-tag: `next` - registry: `https",
-      "phases": []
+      "phases": [],
+      "workflows": [
+        "*"
+      ]
     },
     {
       "id": "workflows:readme",
       "path": "docs/workflows/README.md",
       "title": "AHEAD Pilot Workflows",
-      "summary": "These six minimal workflow profiles are meant to be used on real engineering work before AHEAD builds a workflow engine, editor extension, or CI enforcement. They are deliberately small. The pilot should reveal which phases, gates, and reco",
-      "phases": []
+      "summary": "These six minimal workflow profiles are meant to be used on real engineering work through the Pi adapter or a manual record. Their canonical executable contracts live in `spec/workflows`, while these documents explain the same boundaries an",
+      "phases": [
+        "*"
+      ],
+      "workflows": [
+        "*"
+      ]
     },
     {
       "id": "workflows:corrective-debugging",
       "path": "docs/workflows/corrective-debugging.md",
       "title": "Corrective Debugging Workflow",
       "summary": "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.",
-      "phases": []
+      "phases": [
+        "*"
+      ],
+      "workflows": [
+        "corrective-debugging"
+      ]
     },
     {
       "id": "workflows:decision",
       "path": "docs/workflows/decision.md",
       "title": "Decision Workflow",
       "summary": "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.",
-      "phases": []
+      "phases": [
+        "*"
+      ],
+      "workflows": [
+        "decision"
+      ]
     },
     {
       "id": "workflows:internal-improvement",
       "path": "docs/workflows/internal-improvement.md",
       "title": "Internal Improvement Workflow",
       "summary": "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.",
-      "phases": []
+      "phases": [
+        "*"
+      ],
+      "workflows": [
+        "internal-improvement"
+      ]
     },
     {
       "id": "workflows:investigation",
       "path": "docs/workflows/investigation.md",
       "title": "Investigation Workflow",
       "summary": "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.",
-      "phases": []
+      "phases": [
+        "*"
+      ],
+      "workflows": [
+        "investigation"
+      ]
     },
     {
       "id": "workflows:operational-stabilization",
       "path": "docs/workflows/operational-stabilization.md",
       "title": "Operational Stabilization Workflow",
       "summary": "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 ",
-      "phases": []
+      "phases": [
+        "*"
+      ],
+      "workflows": [
+        "operational-stabilization"
+      ]
     },
     {
       "id": "workflows:product-change",
@@ -174,6 +289,9 @@
       "summary": "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.",
       "phases": [
         "*"
+      ],
+      "workflows": [
+        "product-change"
       ]
     }
   ]