ahead-pi 0.2.0 → 0.3.0

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

@@ -0,0 +1,216 @@
+# 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                            │
+└──────────────────────┬───────────────────────┘
+                       ↓
+          HUMAN DISPOSITIONS EACH MATERIAL
+          AI FINDING WITH RATIONALE / EVIDENCE
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 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
+                       ↓
+          HUMAN DISPOSITIONS AUDIT FINDINGS
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 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 | 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 | 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
+
+```text
+PROBLEM / SUCCESS SIGNALS
+            │
+            ▼
+RESEARCH / QUESTIONS
+            │
+            ▼
+HUMAN OPTION / ALTERNATIVES
+            │
+            ▼
+HUMAN DECISION / RATIONALE
+            │
+            ▼
+HUMAN FIRST-PASS / FINAL PLAN
+            │
+            ▼
+CHANGESET / TESTS
+            │
+            ▼
+SNAPSHOT-BOUND AI REVIEW
+            │
+            ▼
+IMPLEMENTING-HUMAN DISPOSITION
+            │
+            ▼
+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?

package/generated/reference/index.json

@@ -0,0 +1,298 @@
+{
+  "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",
+    "docs/workflows/README.md",
+    "docs/workflows/corrective-debugging.md",
+    "docs/workflows/decision.md",
+    "docs/workflows/internal-improvement.md",
+    "docs/workflows/investigation.md",
+    "docs/workflows/operational-stabilization.md",
+    "docs/workflows/product-change.md"
+  ],
+  "references": [
+    {
+      "id": "constitution",
+      "path": "CONSTITUTION.md",
+      "title": "AHEAD Constitution",
+      "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": [
+        "*"
+      ]
+    },
+    {
+      "id": "acceptable-ai-use",
+      "path": "docs/acceptable-ai-use.md",
+      "title": "Acceptable AI Use in AHEAD",
+      "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": [
+        "*"
+      ]
+    },
+    {
+      "id": "design:debugging-and-operations",
+      "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": [],
+      "workflows": [
+        "*"
+      ]
+    },
+    {
+      "id": "design:executable-workflows",
+      "path": "docs/design/executable-workflows.md",
+      "title": "Executable AHEAD Workflows",
+      "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": [
+        "*"
+      ]
+    },
+    {
+      "id": "design:process-taxonomy",
+      "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": [],
+      "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",
+      "path": "docs/engineering-practice.md",
+      "title": "AHEAD Engineering Practice",
+      "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": [
+        "*"
+      ]
+    },
+    {
+      "id": "evidence:evidence-standard",
+      "path": "docs/evidence/evidence-standard.md",
+      "title": "AHEAD Evidence Standard",
+      "summary": "AHEAD should be supported by the best available evidence without claiming more certainty than software-engineering research can provide. A credible methodology must distinguish evidence for a descriptive claim from evidence that a particula",
+      "phases": [
+        "research",
+        "questions",
+        "decision",
+        "plan",
+        "ai-review",
+        "human-review",
+        "verify",
+        "ai-audit",
+        "outcome"
+      ],
+      "workflows": [
+        "*"
+      ]
+    },
+    {
+      "id": "evidence:research-map",
+      "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": [],
+      "workflows": [
+        "*"
+      ]
+    },
+    {
+      "id": "rationale",
+      "path": "docs/rationale.md",
+      "title": "Why AHEAD",
+      "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": [
+        "*"
+      ]
+    },
+    {
+      "id": "references:pragmatic-programmer-page-index",
+      "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": [],
+      "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": [],
+      "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": [],
+      "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 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": [
+        "*"
+      ],
+      "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": [
+        "*"
+      ],
+      "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": [
+        "*"
+      ],
+      "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": [
+        "*"
+      ],
+      "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": [
+        "*"
+      ],
+      "workflows": [
+        "operational-stabilization"
+      ]
+    },
+    {
+      "id": "workflows:product-change",
+      "path": "docs/workflows/product-change.md",
+      "title": "Product Change Workflow",
+      "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"
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,60 +1,71 @@
 {
   "name": "ahead-pi",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "AHEAD workflow enforcement and context for Pi",
+  "keywords": [
+    "ahead",
+    "human-in-the-loop",
+    "pi-package"
+  ],
+  "homepage": "https://github.com/Kade-Powell/ahead/tree/main/integrations/pi#readme",
+  "bugs": {
+    "url": "https://github.com/Kade-Powell/ahead/issues"
+  },
   "license": "MIT",
-  "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Kade-Powell/ahead.git",
     "directory": "integrations/pi"
   },
-  "homepage": "https://github.com/Kade-Powell/ahead/tree/main/integrations/pi#readme",
-  "bugs": {
-    "url": "https://github.com/Kade-Powell/ahead/issues"
-  },
-  "engines": {
-    "node": ">=22.19.0"
-  },
   "files": [
     "dist/ahead_wasm.wasm",
     "generated/",
     "src/"
   ],
+  "type": "module",
   "publishConfig": {
     "access": "public",
     "provenance": true,
     "registry": "https://registry.npmjs.org/"
   },
-  "keywords": [
-    "pi-package",
-    "ahead",
-    "human-in-the-loop"
-  ],
-  "pi": {
-    "extensions": [
-      "./src/index.ts"
-    ]
-  },
   "scripts": {
     "build": "npm run build:instructions && npm run build:wasm && npm run typecheck",
     "build:instructions": "node ../../scripts/build-instructions.mjs",
     "build:wasm": "node ./scripts/build-wasm.mjs",
+    "format": "cd ../.. && integrations/pi/node_modules/.bin/oxfmt -c ./.oxfmtrc.json .oxfmtrc.json .oxlintrc.json scripts integrations/pi/scripts integrations/pi/src integrations/pi/test integrations/pi/package.json integrations/pi/tsconfig.json",
+    "format:check": "npm run format -- --check",
+    "lint": "npm run lint:source && npm run lint:types",
+    "lint:source": "cd ../.. && integrations/pi/node_modules/.bin/oxlint -c ./.oxlintrc.json --report-unused-disable-directives-severity=off scripts integrations/pi/scripts integrations/pi/src integrations/pi/test",
+    "lint:types": "cd ../.. && integrations/pi/node_modules/.bin/oxlint -c ./.oxlintrc.json --type-aware --tsconfig integrations/pi/tsconfig.json integrations/pi/src",
     "prepack": "npm run build",
     "prepublishOnly": "npm run verify",
     "pack:verify": "node ./scripts/verify-package.mjs",
+    "quality": "npm run format:check && npm run lint && npm run typecheck",
     "typecheck": "tsc --noEmit",
-    "verify": "npm run build && node --test ./test/*.test.mjs",
+    "verify": "npm run build && npm run format:check && npm run lint && node --test ./test/*.test.mjs",
     "test": "npm run verify && npm run pack:verify"
   },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "typebox": "*"
-  },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.80.6",
+    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@earendil-works/pi-tui": "^0.84.1",
     "@types/node": "24.12.4",
+    "oxfmt": "^0.63.0",
+    "oxlint": "^1.78.0",
+    "oxlint-tsgolint": "^7.0.2001",
     "typebox": "1.1.38",
     "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
   }
 }