ahead-pi 0.5.0 → 0.6.0

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

@@ -177,6 +177,7 @@ During incident or emergency mode, maintain at minimum:
 - 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 outcome records the durable references (runbooks, design docs, decision records) this stabilization creates or updates, or explicit none; emergency policy may defer the reference-update record to a linked postmortem, but the deferral itself is recorded. See [Durable references](../durable-reference.md).
 - 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.
 

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

@@ -151,10 +151,10 @@ An important unknown is disposed only when it is answered or an accountable huma
 | 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 | 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 |
+| Plan | First-pass implementation plan and the set of durable references it will touch | Identify gaps, dependencies, tests, risks, rollback needs, and propose reference updates | Sequenced plan, deviations policy, and planned reference updates (decision records, design docs, runbooks, or explicit none) | Human approves the final plan |
+| Implement | Code, engineering changes, and the durable-reference edits that record the change | Bounded generation, explanation, tests, debugging, refactoring assistance, and proposed reference-update drafts | Linked changeset, plan deviations, and actual reference updates | Work is ready for independent review and checks pass |
+| AI review | Validate and disposition every material AI finding | Review against the full open run — decision, plan, plan-deviations, reference-updates, changeset, tests, and evidence — without modifying the change | Review inputs enumeration, snapshot-bound AI findings, and separate human disposition | Every material finding is fixed, invalid, accepted risk, or follow-up with rationale |
+| Human review | Independent final engineering judgment by someone other than the implementer, with the full open run available | Answer targeted questions and retrieve evidence from the live run | Current independent human review | Independent human reviewer accepts the current change |
 | Deploy or release | Authorization and rollout decision | Analyze readiness evidence within policy | Version, environment, actor, time, and result | The intended version reaches the target environment or deployment is explicitly not applicable |
 | Verify 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 | AI audit findings; separate human disposition | The human disposer accepts the audit gate or reopens work |
@@ -207,6 +207,8 @@ HUMAN OUTCOME / LEARNING
 - 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.
+- The plan and implementation each record the durable references touched (decision records, design docs, runbooks) or explicit none. See [Durable references](../durable-reference.md).
+- The run stays open from framing through outcome. AI review and independent human review both read the full open run.
 - AI review and implementer self-review do not satisfy independent human review.
 - Implementation completion is not deployment or outcome verification.
 

package/generated/reference/index.json

@@ -10,6 +10,7 @@
     "docs/evidence/sources/tigerstyle.md",
     "docs/guide/README.md",
     "docs/guide/acceptable-ai-use.md",
+    "docs/guide/durable-reference.md",
     "docs/guide/engineering-practice.md",
     "docs/guide/rationale.md",
     "docs/guide/recommended-skills.md",
@@ -156,6 +157,19 @@
         "*"
       ]
     },
+    {
+      "id": "durable-reference",
+      "path": "docs/guide/durable-reference.md",
+      "title": "Durable References",
+      "summary": "AHEAD's workflows produce two kinds of records. **Run artifacts** are scoped to a single run and describe what happened: framing, research, decisions, plans, changesets, review findings, outcomes. **Durable references** outlive a run and de",
+      "audience": "practitioner",
+      "authority": "guidance",
+      "distribution": "agent-and-human",
+      "phases": [],
+      "workflows": [
+        "*"
+      ]
+    },
     {
       "id": "engineering-practice",
       "path": "docs/guide/engineering-practice.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ahead-pi",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "AHEAD workflow enforcement and context for Pi",
   "keywords": [
     "ahead",
@@ -63,6 +63,11 @@
   "engines": {
     "node": ">=22.19.0"
   },
+  "omp": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
   "pi": {
     "extensions": [
       "./src/index.ts"

package/src/guidance.ts

@@ -35,6 +35,7 @@ const guides: Record<string, PhaseGuide> = {
         "What sources, code, behavior, history, or measurements were examined?",
         "What findings are supported, contradicted, or still uncertain?",
         "How directly does each finding apply to this work?",
+        "Does novelty or unfamiliarity require primary documentation, direct inspection, or an experiment?",
         "What important evidence is still missing?",
       ],
     },
@@ -109,7 +110,7 @@ const guides: Record<string, PhaseGuide> = {
       ],
       plan: [
         "What is the final ordered implementation sequence?",
-        "What tests and observable evidence are required?",
+        "What human-defined behavior, invariants, test oracles, and observable evidence must the checks evaluate?",
         "How will rollout and recovery work?",
         "Which deviations require returning to decision or plan?",
       ],
@@ -305,11 +306,20 @@ const artifactPromptCatalog: Record<string, string[]> = {
     "How does each option perform against the recorded criteria?",
     "What tradeoffs, risks, sensitivity, confidence, and disagreement remain?",
   ],
-  "published-decision": [
-    "Where is the durable decision and rationale recorded?",
+  "decision-record": [
+    "Where is the durable decision record written, and does it follow the project's ADR convention?",
     "Who is affected, what downstream work is linked, and how will it be communicated?",
     "What event or date should trigger review?",
   ],
+  "reference-updates": [
+    "Which decision records, design docs, or runbooks does this run create or update?",
+    "For each, what section changes and who accepts the change?",
+    "If none, is the run genuinely not altering any durable behavior or documented contract?",
+  ],
+  "review-inputs": [
+    "Which run inputs did the review read: decision, plan, plan-deviations, reference-updates, changeset, tests, and evidence?",
+    "Which inputs were unavailable or intentionally excluded?",
+  ],
   question: [
     "What exact question is being investigated, and why does it matter?",
     "Who owns it, how will findings be used, and what would count as an answer?",