ahead-pi 0.3.0 → 0.3.1

package/generated/reference/docs/design/debugging-and-operations.md

@@ -1,119 +0,0 @@
-# Debugging and Operational Investigation
-
-Status: design discussion, not an approved workflow specification
-
-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 and unresolved questions behind them.
-
-## Human ownership
-
-Debugging is human-owned. AI may help collect and organize evidence, suggest hypotheses and tests, identify contradictions, explain systems, and challenge conclusions. The human chooses what to investigate, performs or authorizes tests, interprets the evidence, selects interventions, and accepts the conclusion or remaining uncertainty.
-
-There is no “AI investigation” phase. Investigation is a human engineering activity in which AI may participate.
-
-## Shared reasoning loop
-
-```text
-Observation
-→ Characterize
-→ Build or update the mental model
-→ Generate hypotheses
-→ Human selects a discriminating test
-→ Predict expected results
-→ Run the test
-→ Record evidence
-→ Update or refute hypotheses
-→ Repeat
-```
-
-The process distinguishes:
-
-- **Fact:** directly observed and linked to evidence.
-- **Inference:** an interpretation derived from facts.
-- **Hypothesis:** a falsifiable proposed explanation.
-- **Test:** an experiment or observation capable of changing confidence in a hypothesis.
-- **Result:** what the test actually produced.
-- **Conclusion:** a human-accepted explanation with confidence, limits, and remaining uncertainty.
-
-Predictions should be recorded before a test when practical. This reduces hindsight interpretation of ambiguous results.
-
-## Bug debugging
-
-A bug is a defect where observed software behavior conflicts with intended behavior.
-
-```text
-Observe → Reproduce or establish
-→ Characterize
-→ Human-led investigation loop
-→ Human accepts diagnosis or uncertainty
-→ Choose fix → Plan → Implement → Validate locally
-→ AI review → Independent human review
-→ Human-authorized deploy or release when applicable
-→ Verify the original failure and observe the outcome
-→ Audit assumptions → Human outcome
-```
-
-Reproduction is valuable but not universally required. A failure may be intermittent, historical, production-only, environment-specific, or already mitigated.
-
-## Operational investigation
-
-An operational issue is undesirable system behavior that may not be a software defect. Examples include reconciliation storms, configuration drift, capacity exhaustion, cloud-provider behavior, dependency failures, identity or certificate failures, resource contention, bad rollout sequencing, and emergent controller interactions.
-
-```text
-Observed condition
-→ Desired state versus actual state
-→ Impact and scope
-→ Timeline
-→ System and control-loop model
-→ Recent changes and external events
-→ Evidence/hypothesis/test loop
-→ Intervention decision
-→ Verify convergence and user-visible behavior
-→ Monitor recurrence
-→ Corrective actions
-```
-
-The initial cause classification must remain tentative. Labeling an issue a code bug, configuration error, or provider failure before collecting evidence can bias the investigation.
-
-## Incident mode
-
-“Incident” describes impact and urgency rather than cause. An incident may be caused by a bug, configuration, capacity, provider behavior, a security event, data, or an interaction that remains partially unexplained.
-
-Incident mode adds parallel concerns:
-
-```text
-Response:       assess impact → contain → recover → monitor
-Investigation:  evidence → model → hypotheses → tests → conclusion
-Coordination:   ownership → decisions → communications → timeline
-```
-
-Mitigation and recovery must not be blocked on completing a full diagnosis. Risky interventions still require explicit human authorization. After recovery, unresolved causal analysis and prevention work may continue as a linked bug, operational investigation, security issue, or technical-debt item.
-
-## Current design direction
-
-- Treat bug debugging and operational investigation as separate work types.
-- Treat incident mode as an overlay that may apply to several work types.
-- Keep the evidence and hypothesis loop flexible rather than gating every iteration.
-- Reserve hard gates for human accountability, risky tests, consequential interventions, accepted conclusions, implementation plans, reviews, and verified outcomes.
-- Distinguish hypothesis testing, fix validation, and post-deployment outcome verification.
-- Allow causal conclusions to include a failure mechanism, trigger, enabling conditions, and detection or containment gaps instead of insisting on one root cause.
-
-## Open questions
-
-- What minimum evidence is needed before a human may accept a diagnosis?
-- When may a team remediate while explicitly accepting that the cause is unknown?
-- Which tests require approval based on environment, reversibility, or blast radius?
-- How should AHEAD represent multiple interacting causes and confidence changes?
-- When does an operational anomaly become incident mode?
-- Which incident records must be produced during response, and which may be reconstructed afterward?
-- How should follow-up work remain linked without keeping the incident itself permanently open?
-
-## Evidence basis
-
-The current reasoning loop is supported by direct empirical software-engineering research, though the exact AHEAD recording requirements are not yet validated:
-
-- [Li and Coblenz, *A Grounded Theory of Debugging in Professional Software Engineering Practice*](https://arxiv.org/abs/2602.11435) observed professional developers and describes debugging as iterative mental-model construction that guides information gathering.
-- [Alaboudi and LaToza, *Using Hypotheses as a Debugging Aid*](https://doi.org/10.1109/VL/HCC50065.2020.9127273) found that early correct hypotheses predicted success and that supplying potential hypotheses helped more than supplying fault locations in their controlled experiment.
-- [Sillito and Kutomi, *Failures and Fixes*](https://doi.org/10.1109/ICSME46990.2020.00027) analyzed 30 incidents and identified distinct investigative and mitigative strategies.
-- [Ghosh et al., *How to Fight Production Incidents?*](https://doi.org/10.1145/3542929.3563482) studied hundreds of high-severity cloud incidents, including non-code causes, across detection, diagnosis, and mitigation.
-
-These studies support the shape of the process. They do not prove that requiring engineers to record every fact, hypothesis, or test improves results. AHEAD must test the minimum useful structure and remove requirements that interrupt investigation without improving reasoning, handoff, or learning.

package/generated/reference/docs/design/executable-workflows.md

@@ -1,122 +0,0 @@
-# Executable AHEAD Workflows
-
-Status: six-flow executable dogfood v0.1
-
-## Purpose
-
-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.
-
-The executable layer implements all six pilot workflows. They share a versioned event model and enforcement engine while retaining workflow-specific phases, artifacts, gates, returns, AI capabilities, and generated instructions.
-
-## Architecture
-
-```text
-CONSTITUTION / ACCEPTABLE-AI-USE
-                 │
-                 ▼
-CANONICAL WORKFLOW SPEC + POLICY FRAGMENTS
-                 │
-        ┌────────┴────────┐
-        ▼                 ▼
-RUST WORKFLOW CORE   GENERATED INSTRUCTIONS
-        │                 │
-        └────────┬────────┘
-                 ▼
-         INTEGRATION ADAPTER
-        (Pi first; others later)
-                 │
-        ┌────────┴─────────┐
-        ▼                  ▼
-HOST TOOLS / MODEL     DURABLE RUN FILES
-```
-
-The Rust core owns workflow semantics. It is deterministic and has no filesystem, network, clock, model-provider, or editor dependency. Hosts supply identity and timestamps, persist returned runs, and map their tools to canonical capabilities.
-
-The initial WebAssembly boundary is a small versioned JSON ABI. This avoids coupling the core to one JavaScript binding generator and lets a later editor or CI integration load the same state machine.
-
-## Sources of truth
-
-| Concern | Canonical source |
-|---|---|
-| Durable principles | `CONSTITUTION.md` |
-| AI authority | `docs/acceptable-ai-use.md` |
-| Human-readable flows | `docs/workflows/*.md` |
-| Current executable phases, artifacts, gates, transitions, and capabilities | `spec/workflows/*.json` |
-| Published historical workflow definitions retained for replay | `spec/workflows/legacy/*.json` |
-| Compact binding agent profile and shared AI behavior | `policy/common.md` |
-| Phase AI behavior | `policy/<workflow>/*.md` with shared engineering-tail fragments in `policy/shared/*.md` |
-| Reusable phase practices | `policy/methods/*.md`, selected by `policy/methods/index.json` |
-| Reviewed optional skills | `recommendations/skills-v0.1.json` |
-| State transition enforcement | `crates/ahead-core` |
-| Host mapping, storage, and UI | `integrations/pi` |
-
-Generated integration instructions are build artifacts. They include the compact agent profile, active phase policy, enforced contract, workflow version, and a source hash and must not be edited directly.
-
-The engine retains published historical workflow definitions for replay while new runs use the current definition. Product Change `0.1.0` remains embedded for existing runs; the review and audit disposition contract is Product Change `0.2.0`. A run is always replayed against the version recorded when it started rather than silently reinterpreted under the newest workflow.
-
-The Pi package also copies the canonical Constitution and `docs/**/*.md` into a generated reference catalog. These full documents are not injected into every prompt. The adapter recommends references applicable to the active phase, lets humans read them through `/ahead-guide`, and lets AI retrieve a specific source through `ahead_get_reference`. This keeps the binding prompt small while making the framework, rationale, evidence, and original page-level provenance available on demand.
-
-## State and evidence
-
-A run is an append-only event log. Events record an actor kind and identity, host-supplied timestamp, sequence, and one action:
-
-- start the run;
-- record an artifact;
-- accept a human gate;
-- advance or return between phases;
-- close the run.
-
-State is derived by replay. The core rejects invalid history rather than trusting a cached phase field. A return transition creates a new visit to the target phase. Earlier evidence remains in history, but only evidence recorded during the current visit satisfies its gate.
-
-Pi stores state under the work's Git root:
-
-```text
-.ahead/
-├── current.json
-└── runs/
-    └── <run-id>/
-        ├── run.json
-        └── artifacts/
-            └── <sequence>-<phase>-<kind>.md
-```
-
-These are intended to be inspectable, diffable repository artifacts. A team can decide which records belong in Git, while CI and GitHub enforcement are later adapters over the same run contract.
-
-## Enforced boundaries in v0.1
-
-- Only a human actor can start a run, accept a gate, transition a phase, return work, or close a run.
-- Artifact definitions state whether a human, AI, or either may record them.
-- Workflow-specific human-first artifacts unlock AI assistance only after the human's initial model, option, plan, baseline, or other required reasoning exists.
-- Required current-visit artifacts must exist before gate acceptance.
-- Advancement requires the current human gate.
-- Independent human review must be recorded by an identity other than the latest changeset implementer, and that reviewer must accept the review gate.
-- Lasting-change flows distinguish implementation, AI review, independent human review, deployment, observation, audit, and human outcome.
-- AI review is bound to a fingerprint of the exact current engineering changeset. The implementing human records a separate disposition for every material AI finding before independent human review.
-- AI-audit findings and their human disposition are separate required records, and the human disposer personally accepts the audit gate.
-- Operational Stabilization permits investigation and recovery work to proceed without proven root cause, but never grants AI the `execute` capability for the intervention or its execution phase.
-- Decision and Investigation close with human-owned records and do not silently authorize downstream implementation.
-- Model-invoked host tools require an explicit adapter mapping to an allowed canonical capability.
-
-Instructions explain these boundaries to the model. The Rust core enforces the transition, actor, artifact, identity, and capability decisions even if instructions are ignored.
-
-During implementation, instructions explicitly permit questions, explanation, debugging help, and bounded suggestions while keeping the engineer first. If the engineer has not supplied a current model, attempted approach, or intended behavior, AI asks for it before proposing a solution. A request for help does not authorize AI to take over the implementation.
-
-## Trust boundaries and limits
-
-The Pi adapter is an engineering workflow control, not a security sandbox.
-
-- Local human identity comes from `AHEAD_HUMAN_IDENTITY`, then Git email/name, then the local user. It is self-attested. GitHub review identity and protected-branch rules will provide a stronger boundary later.
-- Pi's direct `!` shell is a human action and is not intercepted. Model-invoked `bash` is intercepted.
-- Unknown model tools are denied until the adapter classifies them. This prevents a newly installed effectful tool from silently acquiring authority.
-- Artifact and run writes are atomic, but v0.1 has no multi-process lock. One writer should operate a run at a time.
-- Workflow files can prove that a named action was recorded, not that a person genuinely understood it. Human review and organizational accountability remain necessary.
-- No GitHub checks, PR gates, migration engine, signature scheme, or backwards-compatible workflow upgrade exists yet.
-- Local review fingerprints detect changes but are not signatures. A future GitHub adapter must add remote identity and protected-branch evidence rather than treating the local record as cryptographic proof.
-
-## Reuse path
-
-The reusable boundary is the engine API, not a CLI. Pi is the first adapter. A VS Code extension, GitHub check, or future WASM-capable editor can reuse the same compiled core and canonical fragments while providing its own UI, storage transport, identity strength, and tool-capability map.
-
-Review presentation follows the same rule. The core requires snapshot-bound findings, dispositions, and review gates; a host maps portable paths and locations to a terminal viewer, VS Code diff/comment UI, or GitHub review API. See `docs/design/review-workbench.md`.
-
-Dogfooding should test whether the six encoded flows route real work correctly, whether their records and gates earn their cost, and whether phase visits, returns, capability vocabulary, and identity rules generalize across integrations.

package/generated/reference/docs/design/instruction-authoring.md

@@ -1,28 +0,0 @@
-# Instruction Authoring
-
-Status: initial authoring standard v0.1
-
-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.
-
-## Progressive disclosure
-
-Use three layers:
-
-1. The active profile supplies the binding human/AI authority boundary and live workflow state.
-2. The generator adds the workflow phase fragment and only the method overlays mapped to that phase in `policy/methods/index.json`.
-3. Humans and AI retrieve full framework Markdown on demand through the host integration.
-
-The canonical workflow spec owns phases, artifacts, gates, transitions, and capabilities. Phase policies own local AI behavior. Method overlays own reusable practices such as evidence handling or debugging. Full documents explain why. Do not restate one rule in every layer.
-
-## Authoring rules
-
-- State the desired observable behavior in direct, positive language.
-- Put human ownership and prohibited transfers of authority where a model cannot mistake them for suggestions.
-- Give checkable completion criteria: an exact artifact, observation, identifier, or gate condition.
-- Point to the canonical source instead of copying large passages.
-- Keep host-specific UI out of core workflow semantics.
-- Do not cache repository facts that tools can discover cheaply and reliably.
-- Use examples to clarify a schema, not to narrow judgment to the example.
-- Treat generated instructions as build artifacts and test the generated output for required boundaries.
-
-The build fails when a method overlay names an unknown workflow or phase. Adding a method therefore requires its source fragment, an explicit mapping, generated-output coverage, and documentation when it changes user-visible expectations.

package/generated/reference/docs/design/process-taxonomy.md

@@ -1,144 +0,0 @@
-# AHEAD Process Taxonomy
-
-Status: proposed design
-Last reviewed: 2026-08-12
-
-## Why classify by outcome
-
-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.
-
-The primary workflow should be selected by the **dominant outcome** the human is trying to produce. Variants and overlays then adapt that workflow to context.
-
-This gives AHEAD six proposed process families. All six now have minimal [pilot workflow profiles](../workflows/README.md) for use and evaluation; that does not yet validate the taxonomy or justify automated enforcement.
-
-## The six process families
-
-| Process family | Dominant question | Terminal outcome | Examples | Status |
-|---|---|---|---|---|
-| 1. [Product change](../workflows/product-change.md) | What behavior or capability should exist, and how should we deliver it? | Verified intended behavior | Feature, API change, integration, migration, dependency adaptation, decommission | Pilot v0.1 |
-| 2. [Corrective debugging](../workflows/corrective-debugging.md) | Why does observed behavior differ from intended behavior, and how should we correct it? | Verified correction or explicitly accepted uncertainty | Deterministic bug, flaky failure, regression, incorrect data processing | Pilot v0.1 |
-| 3. [Operational stabilization](../workflows/operational-stabilization.md) | Why is a live system outside an acceptable operating state, and how do we restore and stabilize it? | Demonstrated recovery/convergence and follow-up disposition | Reconciliation storm, capacity exhaustion, configuration drift, dependency outage | Pilot v0.1 |
-| 4. [Decision](../workflows/decision.md) | Which course should humans choose, given goals, evidence, constraints, and tradeoffs? | Approved decision and rationale | Architecture decision, buy/build, technology selection, policy or platform choice | Pilot v0.1 |
-| 5. [Investigation](../workflows/investigation.md) | What is true, feasible, or likely when no intervention has yet been selected? | Bounded conclusion, confidence, evidence, and remaining unknowns | Technical spike, feasibility study, causal follow-up, capacity study, vendor evaluation | Pilot v0.1 |
-| 6. [Internal improvement](../workflows/internal-improvement.md) | How can we improve system qualities while preserving an explicit behavioral contract? | Verified invariants plus improved target qualities | Refactor, preventive maintenance, maintainability debt, performance optimization without semantic change | Pilot v0.1 |
-
-Six is a working taxonomy, not a sacred number. The threshold for adding a seventh family is deliberately high.
-
-## Selection test
-
-```text
-Is the primary outcome new or changed externally meaningful behavior?
-  → Product change
-
-Is an observed behavior wrong and the main work is causal diagnosis plus correction?
-  → Corrective debugging
-
-Is a live system unhealthy, unstable, or failing to converge, with restoration as the immediate outcome?
-  → Operational stabilization
-
-Is the deliverable an accountable choice among alternatives?
-  → Decision
-
-Is the deliverable knowledge or reduced uncertainty, without a predetermined change?
-  → Investigation
-
-Must behavior remain invariant while internal qualities improve?
-  → Internal improvement
-```
-
-A large effort may link several runs. An architecture decision can lead to a product change. An incident can create an operational investigation, a corrective bug, and an internal-improvement follow-up. A technical spike can end in a decision without pretending that knowledge production and option selection are the same activity.
-
-## Why the additional three differ
-
-### Decision
-
-A feature includes decisions, but some engineering work ends with a decision rather than code. Its quality depends on framing, option coverage, evidence, tradeoffs, consequences, reversibility, and accountable approval. Forcing it through implementation and deployment creates meaningless states.
-
-### Investigation
-
-An investigation begins with a question, not an assumed defect or desired change. It may conclude that no action is needed, evidence is insufficient, a vendor owns the behavior, or several interventions remain viable. Its terminal quality is epistemic: evidence, confidence, limitations, and unknowns.
-
-### Internal improvement
-
-Refactoring and preventive work are judged differently from feature work. They begin by specifying invariants and target qualities. Success means that required behavior was preserved while maintainability, performance, safety, comprehensibility, or another quality improved. Treating this as a feature encourages invented product outcomes; treating it as a bug assumes a failure that may not exist.
-
-## Overlays, not primary processes
-
-### Incident mode
-
-Incident mode represents urgency, impact, coordination, containment, communication, and recovery. It can overlay corrective debugging, operational stabilization, a security event, or a data issue. It relaxes nonessential documentation during response but strengthens action authorization and decision logging.
-
-### Security
-
-Security adds confidentiality, evidence preservation, threat modeling, restricted AI access, disclosure, and security approval. A vulnerability may use corrective debugging; proactive hardening may use internal improvement; an active compromise may use incident-mode operational stabilization; a threat assessment may use investigation.
-
-### Safety, regulatory, and compliance
-
-These overlays strengthen traceability, independence, evidence retention, required reviewers, and non-waivable gates. They do not change whether the underlying work is a change, correction, operation, decision, investigation, or improvement.
-
-### Emergency
-
-Emergency handling changes sequencing and permits explicitly governed deferrals. It does not erase human accountability or evidence requirements; it moves some reconstruction and learning after stabilization.
-
-## Labels and modifiers
-
-Context belongs in typed modifiers rather than new workflow definitions:
-
-```yaml
-process: operational-stabilization
-urgency: incident
-domain: infrastructure
-assurance: standard
-failure_character: intermittent
-environment: production
-data_classification: internal
-```
-
-Useful modifiers may include:
-
-- urgency: normal, expedited, incident, emergency;
-- assurance: standard, security, safety-critical, regulated;
-- environment: local, test, staging, production, external provider;
-- failure character: deterministic, intermittent, performance, data, distributed, unknown;
-- change character: additive, adaptive, migration, retirement;
-- reversibility and blast radius;
-- evidence sensitivity.
-
-## Where common work maps
-
-| Work label | Primary process or routing rule |
-|---|---|
-| Feature | Product change |
-| Bug | Corrective debugging |
-| Production reconciliation storm | Operational stabilization; add incident mode when impact/urgency warrants it |
-| Architecture decision | Decision; link resulting implementation separately |
-| Technical debt | Internal improvement when preserving behavior; product change when behavior changes; corrective debugging when it represents a known defect |
-| Refactor | Internal improvement |
-| Performance regression | Corrective debugging |
-| Proactive performance optimization | Internal improvement or product change, depending on whether performance is a new product outcome |
-| Security vulnerability | Corrective debugging plus security overlay |
-| Active security compromise | Operational stabilization plus incident and security overlays |
-| Security hardening | Internal improvement or product change plus security overlay |
-| Research spike | Investigation |
-| Compliance audit | Investigation plus compliance overlay; corrective or improvement runs handle findings |
-| Dependency or platform upgrade | Product change with adaptive-change modifier |
-| Service retirement | Product change with retirement and risk modifiers |
-
-## Test for adding another family
-
-A new primary process family should be added only when all of these are true:
-
-1. It has a distinct terminal outcome.
-2. It has a distinct central reasoning loop.
-3. It requires materially different human decisions or gates.
-4. It cannot be represented clearly as a variant, overlay, modifier, or linked combination of existing families.
-5. Evidence or repeated practice shows that using an existing family creates confusion, unsafe behavior, or process theater.
-6. The additional cognitive and tooling cost is justified.
-
-## Evidence basis and limits
-
-[ISO/IEC/IEEE 12207:2026](https://standards.ieee.org/ieee/12207/11416/) covers development, operation, maintenance, support, and retirement and allows processes to operate concurrently, iteratively, and recursively. [ISO/IEC/IEEE 14764:2022](https://www.iso.org/standard/80710.html) separately establishes software-maintenance types. These standards support broad coverage and composition, but they do not validate this six-family taxonomy.
-
-Empirical debugging research supports a mental-model and hypothesis-testing process distinct from planned change. Empirical production-incident research distinguishes code and non-code causes and separates detection, investigation, and mitigation. Those findings support keeping corrective debugging and operational stabilization separate.
-
-The proposed six-family classification itself remains an AHEAD design hypothesis. The pilot profiles should be tested against a diverse sample of real engineering work by asking whether teams can route work consistently, whether important states or gates differ, which records improve reasoning or handoff, and whether any family is rarely used or routinely misclassified.

package/generated/reference/docs/design/review-workbench.md

@@ -1,37 +0,0 @@
-# Review Workbench
-
-Status: Pi host v0.1; editor-neutral contract v0.1
-
-## Purpose
-
-The review workbench makes the handoff from implementation to independent human review explicit and inspectable:
-
-```text
-HUMAN IMPLEMENTS AND SELF-CHECKS
-              │
-              ▼
-CAPTURE EXACT CHANGESET FINGERPRINT
-              │
-              ▼
-AI REVIEWS WITHOUT MODIFYING
-              │
-              ▼
-HUMAN DISPOSITIONS EACH MATERIAL FINDING
-              │
-              ▼
-INDEPENDENT HUMAN REVIEWS CURRENT SNAPSHOT
-```
-
-The adapter computes a fingerprint from the selected base and merge base, HEAD, engineering working-tree status, tracked diff, and hashes of untracked files. `.ahead/**` records are excluded so recording the review does not invalidate the engineering snapshot. AI and human review artifacts must carry `AHEAD-Review-Snapshot: <fingerprint>`. If the engineering changeset changes, the fingerprint changes and the review must be repeated.
-
-## Portable contract
-
-`integrations/pi/src/review.ts` defines host-neutral snapshot and source-location data plus a small `ReviewHost` boundary. Core workflow semantics require the AI findings, implementing-human disposition, and independent-human review; they do not require a terminal, VS Code, GitHub, or a particular comment API.
-
-Pi is the first host. `/ahead-review` can show the snapshot and diff in the terminal, open a changed path in detected VS Code or `AHEAD_EDITOR=vscode`, request the AI review, and open the correct human record. A future VS Code adapter can map the same locations to native diffs and comments. A GitHub adapter can publish selected findings and verify protected-branch identities without changing the workflow contract.
-
-## Finding and disposition shape
-
-AI findings use stable `AR-001` identifiers and include severity, category, precise location, evidence, impact, and a falsifiable explanation. They are hypotheses. The implementing human separately marks every material finding `fixed`, `invalid`, `accepted-risk`, or `follow-up` and records rationale and evidence. An independent human then reviews the current snapshot and makes the final engineering judgment.
-
-The workbench does not post comments, push branches, mark a pull request ready, or approve a pull request automatically. Those are explicit future host effects governed by human authorization and stronger remote identity.

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

@@ -1,89 +0,0 @@
-# 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.