ahead-pi 0.2.0 → 0.3.0

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: executable dogfood v0.1
+
+## Purpose
+
+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 and show the human/AI rhythm. Dogfooding 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` produces snapshot-bound hypotheses. The implementing human separately dispositions every material finding, and neither action satisfies the independent 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.

package/generated/reference/docs/workflows/corrective-debugging.md

@@ -0,0 +1,221 @@
+# Corrective Debugging Workflow
+
+Status: pilot v0.1
+
+## Outcome
+
+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.
+
+Use operational stabilization instead when a live system is unhealthy and restoration or convergence is the immediate objective.
+
+## Lifecycle
+
+```text
+                  BUG REPORTED
+                       │
+                       ▼
+              ┌─────────────────┐
+              │ 1. CHARACTERIZE │
+              │                 │
+              │ HUMAN           │
+              │ • What happens? │
+              │ • Expected?     │
+              │ • When / where? │
+              │ • Impact/scope? │
+              │ • Reproducible? │
+              └───────┬─────────┘
+                      │
+                      ▼
+              ┌─────────────────┐
+              │ 2. HUMAN MODEL  │
+              │                 │
+              │ What do we      │
+              │ currently think │
+              │ is happening?   │
+              └───────┬─────────┘
+                      │
+                      ▼
+              ┌─────────────────┐
+              │ 3A. AI ASSISTS  │
+              │ EVIDENCE REVIEW │
+              │                 │
+              │ • Code          │
+              │ • Logs/history  │
+              │ • Dependencies  │
+              │ • Runtime data  │
+              │ • Contradictions│
+              └───────┬─────────┘
+                      │
+                      ▼
+              ┌─────────────────┐
+              │ 3B. HYPOTHESES  │
+              │                 │
+              │ HUMAN LEADS     │
+              │ AI ASSISTS      │
+              │ • H1 / H2 / H3  │
+              │ • Evidence FOR  │
+              │ • Evidence      │
+              │   AGAINST       │
+              └───────┬─────────┘
+                      │
+                      ▼
+              ┌─────────────────┐
+              │ 3C. HUMAN       │
+              │ SELECTS TEST    │
+              │                 │
+              │ • Prediction    │
+              │ • Safety/scope  │
+              └───────┬─────────┘
+                      │
+                      ▼
+              ┌─────────────────┐
+              │ 3D. TEST        │
+              │ HYPOTHESIS      │
+              │                 │
+              │ HUMAN/ENGINEER  │
+              │ Run / inspect / │
+              │ instrument      │
+              │ AI — ASSIST     │
+              └───────┬─────────┘
+                      │
+                      ▼
+                ┌──────────────┐
+                │ HUMAN READY  │
+                │ TO CHOOSE?   │
+                └──────┬───────┘
+                   NO ↙  ↘ YES
+                     │    │
+                     │    ▼
+        ↺ HUMAN MODEL     HUMAN ACCEPTS DIAGNOSIS
+                          OR UNKNOWN CAUSE / RISK (4)
+                                  │
+                                  ▼
+                         HUMAN FIX APPROACH (5)
+                                  │
+                                  ▼
+                         HUMAN FIRST-PASS PLAN (6)
+                                  │
+                                  ▼
+                       ENGINEER IMPLEMENTS (7)
+                                  │
+                                  ▼
+                              AI REVIEW (8)
+                                  │
+                                  ▼
+                 HUMAN DISPOSITIONS MATERIAL FINDINGS
+                                  │
+                                  ▼
+                    INDEPENDENT HUMAN REVIEW (9)
+                                  │
+                                  ▼
+                  HUMAN AUTHORIZES DEPLOY / RELEASE (10)
+                           WHEN APPLICABLE
+                                  │
+                                  ▼
+          HUMAN VERIFIES CORRECTION OF ORIGINAL FAILURE (11)
+                                  │
+                                  ▼
+                 HUMAN OBSERVES DEPLOYED OUTCOME
+                                  │
+                                  ▼
+                              AI AUDIT (12)
+                                  │
+                                  ▼
+                    HUMAN DISPOSITIONS AUDIT FINDINGS
+                                  │
+                                  ▼
+                         HUMAN OUTCOME GATE (13)
+
+Not corrected ───────────────────↺ HUMAN MODEL
+```
+
+Reproduction is useful but not a universal gate. Historical, intermittent, production-only, or already mitigated failures may proceed when the limitation is recorded.
+
+“Ready to choose” means either the evidence sufficiently supports a human-accepted diagnosis or the accountable human explicitly accepts that the cause remains unknown and records the risk of proceeding. Unsupported hypotheses alone do not satisfy the gate.
+
+Executable phase 3, `investigate`, contains the evidence review, hypothesis, human test-selection, and test loop shown as 3A–3D. The human conclusion is a separate gate so a plausible hypothesis cannot silently become a diagnosis.
+
+## Minimal phases
+
+| Phase | Human owns | AI may | Minimum record | Advance when |
+|---|---|---|---|---|
+| Report and characterize | Intended behavior, observed behavior, impact, scope, and evidence quality | Organize evidence and identify missing characterization | Failure statement and evidence links | The failure is bounded enough to investigate |
+| Mental model | Current explanation of relevant components, state, and interactions | Explain unfamiliar mechanisms and challenge omissions | Model, assumptions, and unknowns | The model can generate testable hypotheses |
+| Investigate and test | Hypothesis selection, test authorization, prediction, and interpretation | Generate alternatives, evidence for/against, and discriminating tests | Facts, inferences, hypotheses, predictions, tests, results, confidence | Evidence is ready for a human conclusion |
+| Conclude diagnosis | Supported diagnosis or explicit acceptance of unknown cause, confidence, and risk | Challenge the conclusion against evidence and counterevidence | Diagnosis or accepted uncertainty | Human accepts the diagnosis or remaining uncertainty |
+| Choose correction | Desired correction and tradeoffs | Compare fix approaches and recurrence risks | Selected correction and rationale | Human approves the correction |
+| Plan | First-pass correction and verification plan | Find missing cases, risks, regression tests, and rollout concerns | Plan and rollback or containment needs | Human approves the plan |
+| Implement | Code and engineering changes | Bounded implementation and debugging assistance | Linked changeset and regression evidence | Change is ready for review |
+| AI review | Validate and disposition every material AI finding | Review the exact snapshot for correction, tests, risks, 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 correction reaches the target environment or deployment is explicitly not applicable |
+| Verify and observe | Original failure, regression protection, and deployed behavior when applicable | Suggest checks and analyze authorized evidence | Pre-change comparison, fix validation, deployment evidence, and observed outcome | The original failure and user-visible outcome are evaluated |
+| AI audit | Disposition of findings and required response | Compare the result with the failure, diagnosis or accepted uncertainty, correction, plan, reviews, and observed behavior | AI audit findings; separate human disposition | The human disposer accepts the audit gate or reopens work |
+| Outcome | Acceptance, rollback, continued investigation, follow-up, or abandonment | Summarize learning | Result, causal confidence, uncertainty, and follow-ups | Human accepts closure or reopens/routes work |
+
+## Evidence chain
+
+```text
+OBSERVED FAILURE
+       │
+       ▼
+FACTS / EVIDENCE ──► HUMAN MENTAL MODEL
+                            │
+                            ▼
+            HUMAN-LED / AI-EXPANDED HYPOTHESES
+                            │
+                            ▼
+                 PREDICTION / TEST / RESULT
+                            │
+                            └────────────↺ MODEL
+                            │
+                            ▼
+                HUMAN CONCLUSION / CONFIDENCE
+                            │
+                            ▼
+             HUMAN CORRECTION DECISION / PLAN
+                            │
+                            ▼
+                  ENGINEER CHANGE
+                            │
+                            ▼
+              SNAPSHOT-BOUND AI REVIEW
+                            │
+                            ▼
+           IMPLEMENTING-HUMAN DISPOSITION
+                            │
+                            ▼
+               INDEPENDENT HUMAN REVIEW
+                            │
+                            ▼
+                HUMAN-AUTHORIZED DEPLOYMENT
+                            │
+                            ▼
+              CORRECTION VERIFICATION EVIDENCE
+                            │
+                            ▼
+                DEPLOYED OUTCOME EVIDENCE
+                            │
+                            ▼
+               AI AUDIT / HUMAN DISPOSITION
+                            │
+                            ▼
+                    HUMAN OUTCOME
+```
+
+## Non-waivable pilot rules
+
+- Facts, inferences, and hypotheses remain distinguishable.
+- AI hypotheses are candidates, not diagnoses.
+- The human chooses or authorizes tests and interprets their results.
+- A plausible cause is not treated as proven.
+- Fix validation and post-deployment outcome verification are distinct when deployment applies.
+- AI review and implementer self-review do not satisfy independent human review.
+- Implementation completion is not deployment, recovery, or outcome verification.
+
+## Pilot questions
+
+- What was the minimum useful investigation record?
+- Did recording predictions before tests reduce hindsight interpretation?
+- When was correction justified without a conclusive cause?
+- Did AI broaden hypotheses or anchor the investigator?

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

@@ -0,0 +1,149 @@
+# Decision Workflow
+
+Status: pilot v0.1
+
+## Outcome
+
+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.
+
+Implementation is optional and normally belongs in a linked product-change or internal-improvement run.
+
+## Lifecycle
+
+```text
+┌──────────────────────────────────────────────┐
+│ 1. FRAME DECISION                            │
+│                                              │
+│ HUMAN                                        │
+│ • State the choice to be made                │
+│ • Name accountable decider/stakeholders      │
+│ • Define scope and deadline                  │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 2. DEFINE CRITERIA                           │
+│                                              │
+│ HUMAN                                        │
+│ • Goals • constraints • criteria             │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Expose hidden criteria and tensions        │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 3. RESEARCH AND QUESTIONS                    │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Gather cited evidence                      │
+│ • Find contradictions and missing questions  │
+│                                              │
+│ HUMAN                                        │
+│ • Read, evaluate, and accept unknowns        │
+└──────────────────────┬───────────────────────┘
+                       ↓
+                ┌───────────────┐
+                │ EVIDENCE      │
+                │ REVIEWED AND  │
+                │ UNCERTAINTY   │
+                │ DISPOSED?     │
+                └───────┬───────┘
+                   NO ↙   ↘ YES
+              ↺ RESEARCH    │
+                            ▼
+┌──────────────────────────────────────────────┐
+│ 4. HUMAN INITIAL OPTION                      │
+│ • Propose at least one viable course         │
+│ • Explain the initial reasoning              │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 5. EXPAND AND CHALLENGE OPTIONS              │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Add alternatives • compare • challenge     │
+│ • Surface consequences and risks             │
+│ • Analyze reversibility                      │
+│                                              │
+│ HUMAN                                        │
+│ • Evaluate and refine the option set         │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 6. HUMAN DECISION GATE                       │
+│ • Select the course                          │
+│ • Accept tradeoffs and uncertainty           │
+│ • Record rationale and dissent               │
+└──────────────────────┬───────────────────────┘
+                       ↓
+┌──────────────────────────────────────────────┐
+│ 7. VALIDATE AND PUBLISH                      │
+│                                              │
+│ HUMAN                                        │
+│ • Validate consequences                      │
+│ • Set reversibility and review trigger       │
+│ • Link resulting work                        │
+│                                              │
+│ AI — ASSIST                                  │
+│ • Challenge consistency and missing effects  │
+└──────────────────────┬───────────────────────┘
+                       ↓
+                 HUMAN OUTCOME
+
+Reframe or seek evidence ─────────↺ FRAME / RESEARCH
+```
+
+“Disposed” means the uncertainty is answered or the accountable human explicitly accepts it. AI does not introduce solution alternatives during research; option expansion begins only after the human initial option is recorded.
+
+## Minimal phases
+
+| Phase | Human owns | AI may | Minimum record | Advance when |
+|---|---|---|---|---|
+| Frame | Decision to be made, accountable decider, scope, deadline, and stakeholders | Clarify ambiguity and identify missing stakeholders | Decision statement and owner | Human accepts the frame |
+| Criteria | Goals, constraints, evaluation criteria, and relative importance | Challenge hidden criteria and identify tensions | Criteria and non-negotiable constraints | Criteria are sufficient for comparison |
+| Research | Evaluation of evidence and disposition of uncertainty | Gather cited evidence and find contradictions or missing questions; do not introduce solution alternatives yet | Sources, findings, assumptions, unknowns, and limits | Material evidence is reviewed and uncertainty is answered or explicitly accepted |
+| Options | At least one human-originated option | Expand, combine, challenge, and propose alternatives | Options with provenance | Plausible option space is understood |
+| Compare | Interpretation of tradeoffs | Structure comparison and sensitivity analysis | Benefits, costs, risks, consequences, reversibility | Decision is ready for accountable judgment |
+| Decide | Selection, rationale, accepted tradeoffs, and dissent | Test rationale for inconsistency or missing consequence | Decision and rejected alternatives | Accountable human approves a specific revision |
+| Publish and revisit | Consequence check, communication, review trigger, revisit date, and linked work | Improve clarity, traceability, and proposed validation checks | Consequences, reversibility, review trigger, revisit date, and links | Decision is published and accepted as current |
+
+## Decision evidence chain
+
+```text
+HUMAN DECISION FRAME / CRITERIA
+              │
+              ▼
+AI-ASSISTED EVIDENCE / HUMAN-ACCEPTED UNKNOWNS
+              │
+              ▼
+HUMAN INITIAL OPTION
+              │
+              ▼
+AI-EXPANDED / HUMAN-EVALUATED OPTION SET
+              │
+              ▼
+TRADEOFFS / CONSEQUENCES
+              │
+              ▼
+HUMAN DECISION / RATIONALE / DISSENT
+              │
+              ▼
+HUMAN-OWNED REVERSIBILITY / REVIEW TRIGGER
+              │
+              ▼
+LINKED IMPLEMENTATION OR INVESTIGATION
+```
+
+## Non-waivable pilot rules
+
+- The accountable human defines the decision and evaluation criteria.
+- A human contributes an initial option before AI expands the option set.
+- AI does not select, approve, or manufacture consensus.
+- Unknowns and dissent are not erased by polished rationale.
+- The decision records when and why it should be revisited.
+
+## Pilot questions
+
+- Did human-first option generation preserve useful diversity?
+- Were the criteria defined before a preferred answer emerged?
+- Which evidence actually changed the decision?
+- Did the review trigger cause a stale decision to be revisited?