ahead-pi 0.2.0 → 0.2.1

package/generated/reference/docs/references/pragmatic-programmer-page-index.md

@@ -0,0 +1,113 @@
+# *The Pragmatic Programmer* Page Index
+
+Status: submitted source notes
+
+## Edition and use
+
+This index preserves the page-level provenance from the original AHEAD engineering-practice notes for:
+
+> David Thomas and Andrew Hunt, *The Pragmatic Programmer: Your Journey to Mastery*, 20th Anniversary Edition, ISBN 9780135957059.
+
+Page numbers are edition-specific and may not match an ebook or another printing. The titles and locators below are the submitter's reading notes, retained so AHEAD's distilled guidance remains traceable. They are not presented as scientific evidence; the [research map](../evidence/research-map.md) separately records empirical support.
+
+Two submitted locators look like transcription errors but are intentionally preserved pending a check against the physical edition:
+
+- tips 1 and 2 use `xlx`, which is not standard Roman-numeral notation;
+- tip 40 uses p. 15, although it occurs between notes for pp. 151 and 156.
+
+## Tip locators
+
+| No. | Submitted tip title | Page |
+|---:|---|---:|
+| 1 | Care About Your Craft | xlx |
+| 2 | Think! About Your Work | xlx |
+| 3 | Provide Options, Don't Make Lame Excuses | 3 |
+| 4 | Don't Live With Broken Windows | 5 |
+| 5 | Be a Catalyst for Change | 8 |
+| 6 | Remember the Big Picture | 8 |
+| 7 | Make Quality a Requirements Issue | 11 |
+| 8 | Invest Regularly in Your Knowledge Portfolio | 14 |
+| 9 | Critically Analyze What You Read and Hear | 16 |
+| 10 | It's Both What You Say and the Way You Say It | 21 |
+| 11 | DRY—Don't Repeat Yourself | 27 |
+| 12 | Make It Easy to Reuse | 33 |
+| 13 | Eliminate Effects Between Unrelated Things | 35 |
+| 14 | There Are No Final Decisions | 46 |
+| 15 | Use Tracer Bullets to Find the Target | 49 |
+| 16 | Prototype to Learn | 54 |
+| 17 | Program Close to the Problem Domain | 58 |
+| 18 | Estimate to Avoid Surprises | 64 |
+| 19 | Iterate the Schedule with the Code | 69 |
+| 20 | Keep Knowledge in Plain Text | 74 |
+| 21 | Use the Power of Command Shells | 80 |
+| 22 | Use a Single Editor Well | 85 |
+| 23 | Always Use Source Code Control | 88 |
+| 24 | Fix the Problem, Not the Blame | 91 |
+| 25 | Don't Panic When Debugging | 91 |
+| 26 | “select” Isn't Broken | 96 |
+| 27 | Don't Assume It—Prove It | 97 |
+| 28 | Learn a Text Manipulation Language | 100 |
+| 29 | Write Code That Writes Code | 103 |
+| 30 | You Can't Write Perfect Software | 107 |
+| 31 | Design with Contracts | 111 |
+| 32 | Crash Early | 120 |
+| 33 | Use Assertions to Prevent the Impossible | 122 |
+| 34 | Use Exceptions for Exceptional Problems | 127 |
+| 35 | Finish What You Start | 129 |
+| 36 | Minimize Coupling Between Modules | 140 |
+| 37 | Configure, Don't Integrate | 144 |
+| 38 | Put Abstractions in Code, Details in Metadata | 145 |
+| 39 | Analyze Workflow to Improve Concurrency | 151 |
+| 40 | Design Using Services | 15 |
+| 41 | Always Design for Concurrency | 156 |
+| 42 | Separate Views from Model | 161 |
+| 43 | Use Blackboards to Coordinate Workflow | 169 |
+| 44 | Don't Program by Coincidence | 175 |
+| 45 | Estimate the Order of Your Algorithms | 181 |
+| 46 | Test Your Estimates | 182 |
+| 47 | Refactor Early, Refactor Often | 186 |
+| 48 | Design to Test | 192 |
+| 49 | Test Your Software, or Your Users Will | 197 |
+| 50 | Don't Use Wizard Code You Don't Understand | 199 |
+| 51 | Don't Gather Requirements—Dig for Them | 202 |
+| 52 | Work with a User to Think Like a User | 204 |
+| 53 | Abstractions Live Longer than Details | 209 |
+| 54 | Use a Project Glossary | 210 |
+| 55 | Don't Think Outside the Box—Find the Box | 213 |
+| 56 | Start When You're Ready | 215 |
+| 57 | Some Things Are Better Done than Described | 218 |
+| 58 | Don't Be a Slave to Formal Methods | 220 |
+| 59 | Costly Tools Don't Produce Better Designs | 222 |
+| 60 | Organize Team Around Functionality | 227 |
+| 61 | Don't Use Manual Procedures | 231 |
+| 62 | Test Early. Test Often. Test Automatically. | 237 |
+| 63 | Coding Ain't Done 'Til All the Tests Run | 238 |
+| 64 | Use Saboteurs to Test Your Testing | 244 |
+| 65 | Test State Coverage, Not Code Coverage | 245 |
+| 66 | Find Bugs Once | 247 |
+| 67 | English Is Just a Programming Language | 248 |
+| 68 | Build Documentation In, Don't Bolt It On | 249 |
+| 69 | Gently Exceed Your Users' Expectations | 255 |
+| 70 | Sign Your Work | 258 |
+
+## Checklist locators
+
+| Submitted checklist | Page |
+|---|---:|
+| The Wisdom Acrostic | 20 |
+| How to Maintain Orthogonality | 34 |
+| Things to Prototype | 53 |
+| Architectural Questions | 55 |
+| Debugging Checklist | 98 |
+| Law of Demeter for Functions | 141 |
+| How to Program Deliberately | 172 |
+| When to Refactor | 185 |
+| Cutting the Gordian Knot | 212 |
+
+The submitted “Aspects of Testing” checklist did not include a page locator, so this index does not invent one.
+
+The complete submitted checklist bodies and the additional post-Pragmatic tips and practices are retained in the [submitted engineering notes](submitted-engineering-notes.md).
+
+## Maintenance rule
+
+When AHEAD guidance derived from these notes is reorganized or condensed, retain the page-level reference either at the point of use or through a link to this index. If a locator is corrected against the referenced print edition, record the correction in the commit rather than silently replacing the submitted value.

package/generated/reference/docs/references/submitted-engineering-notes.md

@@ -0,0 +1,306 @@
+# Submitted Engineering Notes
+
+Status: submitted source notes
+
+## Purpose and provenance
+
+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 experimentally validated rule.
+
+Tips 1–70 and their submitted page locators from *The Pragmatic Programmer* are retained in the [edition-specific page index](pragmatic-programmer-page-index.md). Their accompanying submitted meanings are retained below, followed by the additional tips and the full submitted checklist and practice content. The submitted language-learning list is intentionally omitted.
+
+## *The Pragmatic Programmer* tip notes
+
+The page index is authoritative for the submitted locators. These concise notes preserve the submitted meaning associated with each title.
+
+| No. | Submitted meaning |
+|---:|---|
+| 1 | Care about doing software development well. |
+| 2 | Turn off autopilot; continually critique and appraise the work. |
+| 3 | Offer viable options instead of excuses or an unsupported claim that something cannot be done. |
+| 4 | Correct bad designs, wrong decisions, and poor code when they are found. |
+| 5 | Catalyze change by showing people a possible future and helping them participate in creating it. |
+| 6 | Keep checking the larger context rather than becoming trapped in implementation detail. |
+| 7 | Involve users in deciding the quality the project actually requires. |
+| 8 | Make continuous learning a regular investment. |
+| 9 | Critically evaluate vendor claims, media, received wisdom, and dogma in the context of the actual project. |
+| 10 | Effective communication depends on both the idea and how it is expressed. |
+| 11 | Give each piece of knowledge one unambiguous, authoritative representation, while avoiding premature abstraction; use the rule of three as a judgment prompt rather than dogma. |
+| 12 | Create an environment in which reuse is easy. |
+| 13 | Design self-contained, independent components with a single well-defined purpose. |
+| 14 | Treat decisions as revisable and plan for change. |
+| 15 | Use tracer implementations to test direction and progressively find the target. |
+| 16 | Treat prototypes as learning artifacts whose value lies in lessons rather than retained code. |
+| 17 | Design and code using the language of the problem domain and its users. |
+| 18 | Estimate before starting so potential problems become visible early. |
+| 19 | Refine schedules with the experience gained during implementation. |
+| 20 | Preserve knowledge in plain text so it remains portable, inspectable, testable, and debuggable. |
+| 21 | Use command shells when graphical interfaces do not provide enough leverage. |
+| 22 | Learn one configurable, extensible, programmable editor deeply enough that it becomes an extension of the hand. |
+| 23 | Always use source control so work and decisions can be recovered and revisited. |
+| 24 | Focus on fixing the problem rather than assigning blame. |
+| 25 | Do not panic while debugging; stop and think about plausible causes. |
+| 26 | Bugs are more often in the application than in foundational tools, but likelihood is not proof. |
+| 27 | Test assumptions in the real environment with realistic data and boundary conditions. |
+| 28 | Learn a text-manipulation language so repetitive text work can be automated. |
+| 29 | Use code generation to improve consistency and reduce duplicated mechanics. |
+| 30 | Perfect software is impossible; protect code and users from inevitable errors. |
+| 31 | Use contracts to state and verify what code promises and requires. |
+| 32 | Fail early when continuing would cause more damage or hide the real fault. |
+| 33 | Use assertions to validate assumptions and prevent impossible states from proceeding unnoticed. |
+| 34 | Reserve exceptions for exceptional conditions so control flow remains readable and maintainable. |
+| 35 | Where possible, make the code that acquires a resource responsible for releasing it. |
+| 36 | Minimize coupling and follow the principle of least knowledge. |
+| 37 | Express technology choices as configuration rather than baking them into unrelated implementation. |
+| 38 | Put general abstractions in code and variable details in metadata. |
+| 39 | Analyze user workflows to find genuine opportunities for concurrency. |
+| 40 | Design around independent, concurrent services behind consistent interfaces. |
+| 41 | Designing for concurrency can produce cleaner interfaces with fewer timing assumptions. |
+| 42 | Separate models from views where useful; this principle is broader than the MVC pattern. |
+| 43 | Use blackboards to coordinate facts and agents while preserving their independence and isolation. |
+| 44 | Do not rely on accidental behavior or confuse coincidence with deliberate design. |
+| 45 | Estimate algorithmic order before implementation to understand likely scaling behavior. |
+| 46 | Mathematical estimates are incomplete; measure behavior in the target environment. |
+| 47 | Refactor early and repeatedly when the system needs it, addressing the underlying problem rather than its surface arrangement. |
+| 48 | Think about testing before implementation so the design is observable and testable; this does not mandate or reject test-driven development. |
+| 49 | Test aggressively rather than relying on users to discover defects. |
+| 50 | Do not incorporate generated or wizard-produced code that the engineer does not understand. |
+| 51 | Discover requirements beneath assumptions, misconceptions, and organizational pressures rather than merely collecting surface statements. |
+| 52 | Work with users to understand how the system will actually be used. |
+| 53 | Invest in stable abstractions rather than transient implementation details. |
+| 54 | Maintain one authoritative glossary for project-specific vocabulary. |
+| 55 | When a problem appears impossible, identify the real constraints and question whether the assumed method or task is necessary. |
+| 56 | Respect accumulated experience and unresolved doubts when deciding whether the work is ready to begin. |
+| 57 | Avoid an endless specification spiral; some understanding emerges only by doing the work. |
+| 58 | Evaluate formal methods in the context of the team's practices and capabilities rather than following them blindly. |
+| 59 | Expensive tools and vendor prestige do not guarantee better designs; judge tools on their merits. |
+| 60 | Organize teams around delivered functionality instead of isolating design, coding, testing, and data work. |
+| 61 | Replace repeatable manual procedures with inspectable automation that executes consistently. |
+| 62 | Run automated tests early and frequently, preferably with every build. |
+| 63 | Coding is not complete until all required tests run. |
+| 64 | Deliberately introduce defects in an isolated copy to verify that tests can detect them. |
+| 65 | Test significant program states, not only executed lines. |
+| 66 | Preserve a reliable automated regression check after a human discovers a defect. |
+| 67 | Treat documentation like code by applying authoritative sources, metadata, separation of model and view, and generation where useful. |
+| 68 | Keep documentation close to the system so it is less likely to become incorrect or stale. |
+| 69 | Understand user expectations and then exceed them gently rather than surprising users with unrequested complexity. |
+| 70 | Take accountable pride in the work and be willing to sign it. |
+
+## Additional tips
+
+### 71. Create simple solutions, not easy ones
+
+Take time to find the simplest solution. The easy solution may use a familiar tool or pattern, but familiarity can conceal complexity and deprive the engineer of learning.
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+### 72. KISS — Keep It Simple, Stupid
+
+Simplicity is the ultimate sophistication. Simpler solutions are generally easier to understand, maintain, and extend.
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+### 73. The Locality of Behavior principle
+
+The behavior of a unit of code should be as obvious as possible from that unit. Separation of concerns may favor splitting behavior into separate pieces, while locality of behavior may favor keeping the tasks for a feature or component together. Some designs can satisfy both; others require an explicit tradeoff.
+
+No external source locator was included with this submitted note.
+
+### 74. Judge tools by the artifacts they produce
+
+Do not choose a language, library, framework, or pattern only because it is pleasant or familiar to use. Judge it by the long-lived software it helps create: reliability, changeability, debuggability, and the incidental complexity it leaves behind.
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+### 75. Avoid complecting independent concerns
+
+Complexity comes from braiding together things that could be reasoned about independently. Watch for value tied to time, function tied to state, policy tied to mechanism, meaning tied to order, and implementation details leaking across boundaries.
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+### 76. Isolate state
+
+State ties value to time. Keep mutable state explicit, minimal, and behind interfaces that let the rest of the system work with stable values when possible.
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+### 77. Prefer values, data, and functions
+
+Prefer immutable values, plain data, functions, queues, set operations, declarative queries, and explicit rules where they fit. These can create simpler artifacts than objects, mutable variables, inheritance, loops, object-relational mapping, and scattered conditionals.
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+### 78. Modular does not automatically mean simple
+
+Separate files, classes, modules, or services can still be deeply entangled. The real test is whether each part needs to know only stable abstractions rather than the hidden details or assumptions of other parts.
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+### 79. Tests are guardrails, not steering
+
+Tests and type checkers help catch mistakes, but they do not replace design clarity or reasoning. A production defect already passed the checks that existed, so the program must remain simple enough to understand.
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+## Submitted checklists
+
+### The Wisdom Acrostic
+
+- **W**hat do you want them to learn?
+- What is their **I**nterest in what you have to say?
+- How **S**ophisticated are they?
+- How much **D**etail do they want?
+- Whom do you want to **O**wn the information?
+- How can you **M**otivate them to listen?
+
+Submitted locator: *The Pragmatic Programmer*, p. 20.
+
+### How to maintain orthogonality
+
+- Design independent, well-defined components.
+- Keep code decoupled.
+- Avoid global data.
+- Refactor similar functions.
+
+Submitted locator: *The Pragmatic Programmer*, p. 34.
+
+### Things to prototype
+
+- Architecture.
+- New functionality in an existing system.
+- The structure or contents of external data.
+- Third-party tools or components.
+- Performance issues.
+- User-interface design.
+
+The submitted note emphasizes that prototype code is intended to be thrown away and may be fully vibe coded under the AHEAD disposable-prototype policy.
+
+Submitted locator: *The Pragmatic Programmer*, p. 53.
+
+### Architectural questions
+
+- Are responsibilities well defined?
+- Are collaborations well defined?
+- Is coupling minimized?
+- Can potential duplication be identified?
+- Are interface definitions and constraints acceptable?
+- Can modules access the data they need when they need it?
+
+Submitted locator: *The Pragmatic Programmer*, p. 55.
+
+### Simplicity and complecting review
+
+- Is this design simple, or only easy because it is familiar?
+- What concepts are tied together that could vary independently?
+- What incidental complexity are we accepting from the selected tools, libraries, frameworks, or patterns?
+- Can this part be understood without loading the rest of the system into your head?
+- Is state explicit, minimized, and isolated?
+- Are policies and rules gathered somewhere clear, or scattered through unrelated code paths?
+- Are we choosing this approach for authoring convenience or for the quality of the artifact it creates?
+- Do tests support our reasoning, or are we depending on them to compensate for unclear design?
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+### Abstraction questions
+
+- What is the operation or capability?
+- Who owns the data or entity?
+- How is the implementation separated from the interface?
+- When does this happen, and is timing unnecessarily coupled to the caller?
+- Where does this run, and is location unnecessarily coupled to the caller?
+- Why does this rule or policy exist, and can it be represented declaratively?
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+### Debugging checklist
+
+- Is the reported problem a direct result of the underlying defect, or merely a symptom?
+- Is the defect really in the compiler, operating system, or another platform component—or is it in the application? Treat likelihood as a starting point and prove the conclusion.
+- If you explained the problem in detail to a coworker, what would you say? Rubber-duck debugging can help make the model explicit.
+- If the suspect code passes its unit tests, are the tests complete enough? What happens with different data?
+- Do the conditions that caused this defect exist elsewhere in the system?
+
+Submitted locator: *The Pragmatic Programmer*, p. 98. The submitted note also references [Rubber Duck Debugging](https://rubberduckdebugging.com/).
+
+### Law of Demeter for functions
+
+An object's method should call only methods belonging to:
+
+- itself;
+- parameters passed to it;
+- objects it creates;
+- its component objects.
+
+Submitted locator: *The Pragmatic Programmer*, p. 141.
+
+### How to program deliberately
+
+- Stay aware of what you are doing.
+- Do not code blindfolded.
+- Proceed from a plan.
+- Rely only on reliable things.
+- Document assumptions.
+- Test assumptions as well as code.
+- Prioritize effort.
+- Do not be a slave to history.
+
+Submitted locator: *The Pragmatic Programmer*, p. 172.
+
+### When to refactor
+
+- A violation of the DRY principle is discovered.
+- Things could be made more orthogonal.
+- Knowledge improves.
+- Requirements evolve.
+- Performance needs improvement.
+
+Submitted locator: *The Pragmatic Programmer*, p. 185.
+
+### Cutting the Gordian knot
+
+When a problem appears impossible, ask:
+
+- Is there an easier way?
+- Am I solving the right problem?
+- Why is this a problem?
+- What makes it hard?
+- Must it be done this way?
+- Must it be done at all?
+
+Submitted locator: *The Pragmatic Programmer*, p. 212.
+
+### Aspects of testing
+
+- Unit testing.
+- Integration testing.
+- Validation and verification.
+- Resource exhaustion, errors, and recovery.
+- Performance testing.
+- Usability testing.
+- Testing the tests themselves.
+
+No page locator was included with this submitted checklist.
+
+## Submitted practices
+
+### Simplicity pass before implementation
+
+- Before building a long-lived feature, separate concerns that do not need to be tied together.
+- Prefer more small, straight, independent pieces over fewer pieces tied into a knot.
+- Name the parts representing problem complexity and those representing incidental complexity.
+
+### Complexity ledger
+
+- For meaningful design decisions, record the benefit, byproducts, what the choice ties together, and why the tradeoff is acceptable.
+- Revisit the ledger when the system becomes difficult to change or debug.
+
+### Quarantine state
+
+- Make mutable state rare, named, easy to find, and surrounded by a simpler interface.
+- Do not pass mutable references through the system when a stable value will do.
+
+### Disentangle during refactoring
+
+- Trace what is tied together, identify the separate concerns, and separate one concern at a time.
+- Refactoring should reduce what a reader must hold in mind rather than merely moving code into different files.
+
+Source for these submitted practices: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.

package/generated/reference/docs/releasing-pi.md

@@ -0,0 +1,89 @@
+# Releasing the Pi Extension
+
+Status: publishing path v0.1
+
+## Contract
+
+- 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://registry.npmjs.org`
+
+The package name was unclaimed when this path was created. Availability is not ownership until the first version is published.
+
+## Human release gate
+
+Publishing is triggered only by publishing a GitHub Release whose tag starts with `pi-v`. The workflow rejects a tag that does not exactly match `integrations/pi/package.json`, rejects a release commit that is not contained in `main`, rebuilds from source, runs the complete test and packed-install smoke suite, and then publishes with npm provenance.
+
+The job uses the GitHub `npm` environment. Configure that environment with a required reviewer if releases need an explicit second confirmation.
+
+AHEAD is released under the MIT License. The repository license file and each published package must declare the same license.
+
+## Prepare a version
+
+From `integrations/pi`:
+
+```sh
+npm version --no-git-tag-version <version>
+npm test
+node ./scripts/check-release.mjs pi-v<version>
+```
+
+Commit the version change, merge it to `main`, and confirm CI. Do not create the release from an unmerged commit.
+
+## Bootstrap the first npm release
+
+This machine was not authenticated to npm when the workflow was created, and npm trusted publishing is configured from an existing package's settings. The first publication therefore needs a short-lived bootstrap credential:
+
+1. Create or select an npm account with 2FA enabled.
+2. Create a granular npm access token that can publish the new public package and is permitted to bypass 2FA for automation.
+3. Store it as `NPM_TOKEN` in the GitHub `npm` environment. Do not put it in repository files, shell history, workflow logs, or release notes.
+4. On GitHub, create and publish a release with tag `pi-v0.1.0` at the corresponding `main` commit.
+5. Verify the workflow, npm package page, provenance, and a clean `pi -e npm:ahead-pi@0.1.0` install.
+
+The workflow has `id-token: write` and publishes with `--provenance`. Before trusted publishing exists, npm uses the bootstrap token and GitHub OIDC supplies the provenance attestation.
+
+## Move to tokenless trusted publishing
+
+The `ahead-pi` package uses this trusted publisher:
+
+| npm field | Value |
+|---|---|
+| Provider | GitHub Actions |
+| Organization or user | `Kade-Powell` |
+| Repository | `ahead` |
+| Workflow filename | `publish-pi.yml` |
+| Environment | `npm` |
+| Allowed action | `npm publish` |
+
+The GitHub `npm` environment must not contain an `NPM_TOKEN` secret. npm publishing access requires 2FA, disallows bypass-2FA tokens, and keeps the trusted publisher. Each release verifies tokenless OIDC authentication and automatic provenance.
+
+## Publish and verify
+
+1. Publish a GitHub Release with tag `pi-v<version>` at the version commit.
+2. Watch the `Publish Pi extension` workflow.
+3. Confirm `npm view ahead-pi@<version> version` returns the release.
+4. Confirm the package page links to this repository and shows provenance.
+5. Test the registry artifact:
+
+   ```sh
+   pi -e npm:ahead-pi@<version>
+   ```
+
+6. For stable releases, confirm `npm view ahead-pi dist-tags.latest`; for prereleases, confirm `dist-tags.next`.
+
+## Failure and rollback
+
+An npm version is immutable. Do not reuse a version after any publish attempt.
+
+- If validation fails before `npm publish`, fix the source, increment the version if a registry publish may have occurred, and publish a new GitHub Release.
+- If publication succeeds but post-publish verification fails, do not rerun the same version blindly. Inspect the registry first.
+- Correct a bad release with a new patch version. Use npm deprecation for a discoverable warning; reserve unpublishing for the narrow cases allowed by npm policy.
+- Moving a dist-tag is a human release decision and does not alter the immutable tarball.
+
+## Why npm and OIDC
+
+Pi natively installs `npm:ahead-pi`, pinned npm versions, Git sources, and local paths. npm provides the simplest cross-machine install path. GitHub-hosted OIDC avoids a long-lived release secret after bootstrap, and npm provenance links the public tarball to this repository and workflow. Neither provenance nor a passing workflow proves the package is safe; they make origin and build history auditable.

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

@@ -0,0 +1,142 @@
+# AHEAD Pilot Workflows
+
+Status: pilot v0.1
+
+## Purpose
+
+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 records improve reasoning and which create process burden.
+
+The profiles are:
+
+1. [Product change](product-change.md)
+2. [Corrective debugging](corrective-debugging.md)
+3. [Operational stabilization](operational-stabilization.md)
+4. [Decision](decision.md)
+5. [Investigation](investigation.md)
+6. [Internal improvement](internal-improvement.md)
+
+Choose the flow by its dominant outcome, not by the issue label. Incident, emergency, security, regulatory, and other concerns are overlays or modifiers.
+
+## Rule hierarchy
+
+The pilot applies rules in this order:
+
+1. [AHEAD Constitution](../../CONSTITUTION.md)
+2. [Acceptable AI Use](../acceptable-ai-use.md)
+3. The selected workflow profile and applicable overlays
+4. Organization and repository guidance, which may narrow but not broaden AI authority
+
+Phase permission is not a waiver of higher-level policy. When rules appear to conflict, apply the more protective rule and record the ambiguity for correction.
+
+## Shared pilot contract
+
+Every pilot run has:
+
+- one accountable human owner;
+- a stated outcome or question;
+- a selected workflow and relevant modifiers;
+- a human-originated initial understanding before AI expansion;
+- links to material evidence rather than unsupported summaries;
+- visible facts, inferences, unknowns, decisions, and accepted risks;
+- recorded AI contributions when they materially influence the work;
+- human authorization for consequential actions;
+- independent human review where a lasting change is produced;
+- outcome evidence and a human closure decision.
+
+Phases may loop or reopen. A workflow is not invalid merely because learning changes an earlier decision or plan. The record should make the change visible.
+
+## Common human gates
+
+| Gate | Required when | Minimum evidence |
+|---|---|---|
+| Framing accepted | Every run | Human-owned outcome, question, failure, or invariant |
+| Decision accepted | A course or intervention is selected | Chosen option, rationale, tradeoffs, unknowns, and accountable human |
+| Plan accepted | Before a lasting implementation | Human first-pass plan plus accepted AI challenges or additions |
+| Action authorized | Before a consequential, risky, destructive, or production action | Actor, purpose, scope, blast radius, rollback or containment, and authorization |
+| Independent human review accepted | Before accepting a lasting engineering change | Review of the current changeset and material evidence by a person other than the implementer; both implementer and reviewer understand their responsibilities |
+| Outcome accepted | Before closure | Verification against the original outcome plus remaining uncertainty and follow-ups |
+
+Emergency policy may defer nonessential documentation and, where explicitly allowed, independent review needed to restore service. It does not remove authorization or accountability, and any deferred review gate remains open until a named human completes it after stabilization. Deferred reasoning is reconstructed after stabilization.
+
+## Minimal run record
+
+For the pilot, keep one Markdown file per run. A team can place it in `.ahead/runs/<id>.md`, an issue, or another durable system as long as links and revision history remain available.
+
+```yaml
+id: AHEAD-YYYY-NNNN
+title: Short description
+workflow: product-change | corrective-debugging | operational-stabilization | decision | investigation | internal-improvement
+owner: human identity
+status: active | blocked | complete | abandoned
+modifiers:
+  urgency: normal | expedited | incident | emergency
+  assurance: standard | security | regulated | safety-critical
+  environment: local | test | staging | production | external
+links: []
+```
+
+The body records only the sections required by the selected flow. Evidence may remain in its native system and be linked rather than copied.
+
+## Shared human–AI rhythm
+
+Diagram language is normative for the pilot:
+
+- `HUMAN` or `ENGINEER` means the person owns the reasoning, decision, action, or artifact.
+- `AI — ASSIST` means AI may research, organize, propose, explain, generate bounded material, or challenge; it does not own or approve the phase.
+- `AI REVIEW` is an additional review and never satisfies a human-review gate.
+- Every decision, test selection, risk acceptance, consequential-action authorization, final review, and outcome gate is human.
+- All diagram permissions remain bounded by the rule hierarchy above. Humans lead and remain accountable; AI assists.
+
+```text
+┌──────────────────────────────────────────────┐
+│ HUMAN FRAMES THE WORK                        │
+│ • Outcome, question, failure, or invariant   │
+│ • Initial understanding                      │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ AI — ASSISTS, AMPLIFIES, AND CHALLENGES      │
+│ • Research • alternatives • hypotheses       │
+│ • Gaps • contradictions • risks              │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ HUMAN UNDERSTANDS AND DECIDES                │
+│ • Evaluate evidence • accept tradeoffs       │
+│ • Resolve or accept important unknowns       │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ HUMAN PLANS OR AUTHORIZES ACTION             │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ ENGINEER ACTS WITH BOUNDED AI ASSISTANCE     │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ AI REVIEW / ANALYSIS                         │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ HUMAN REVIEWS AND ACCEPTS THE OUTCOME        │
+└──────────────────────┬───────────────────────┘
+                       ↓
+              RECORD EVIDENCE AND LEARNING
+
+Questions remain ───────────────↺ AI assistance
+Outcome not accepted ───────────↺ Work / investigation
+```
+
+## Pilot feedback
+
+For each completed run, record:
+
+- which phase or gate prevented a mistake or improved understanding;
+- which required record was unused or burdensome;
+- where the team could not agree on routing or completion;
+- where AI helped, anchored, distracted, or weakened learning;
+- what was reconstructed after the fact;
+- what the eventual engine should enforce, warn about, or leave to judgment.
+
+These profiles are AHEAD design hypotheses. Using them is how AHEAD will learn whether the six-flow taxonomy and its gates deserve stronger enforcement.