@timurproko/a1 0.1.8-dev.50ebb19 → 0.1.8-dev.510

package/docs/ci-release-runbook.md

@@ -5,107 +5,284 @@ GitHub Actions is the only automation platform. Three refs are protected:
 | Ref | Protection | Produced by |
 | --- | --- | --- |
 | `develop` | `Development validation required` on every pull request | `.github/workflows/ci.yml` |
-| `master` | cannot be deleted or force-updated | ruleset only |
-| `refs/tags/v*` | cannot be deleted or moved | ruleset only |
+| `master` | cannot be deleted or force-updated | stable publication |
+| `refs/tags/v*` | cannot be deleted or moved | stable publication |
 
-Publishing is one workflow, `.github/workflows/release.yml`, triggered by pushes
-rather than dispatched by hand.
+`.github/workflows/release.yml` is the only publisher. A push publishes neither
+channel. The workflow starts at `03:17 UTC` for nightly development verification,
+or by explicit dispatch from `npm run develop` or `npm run release`.
 
-`develop` is where work lands. `master` records what the npm `latest` tag serves:
-the release fast-forwards it to the commit it published, and nothing else ever
-writes it. There is no promotion to arrange and nothing to keep in sync — `master`
-is an effect of publishing, not a step before it.
+`.github/workflows/documentation-auto-merge.yml` is the only pull-request
+auto-merge authority. It runs trusted policy from `develop`; it never checks out or
+executes a pull request's code with its write token.
 
-## How much validation runs when
+`.github/workflows/merged-branch-cleanup.yml` owns branch deletion after a human or
+external actor closes a pull request. On the close event it checks out trusted
+default-branch policy and installs no pull-request dependencies. GitHub does not
+emit a new workflow event for a merge authored with the workflow `GITHUB_TOKEN`, so
+Documentation auto-merge also performs the same shared reconciliation synchronously
+after its own validated integration. Both paths delete only an unprotected same-
+repository topic ref whose live object still equals the merged pull request head SHA.
+An absent ref is success; fork, unmerged, advanced, protected, default, release-owned,
+or malformed refs are preserved and reported.
 
-| Change | Validation |
+`config/github-repository-governance.json` is the reviewed policy for repository
+settings, Actions defaults, security capabilities, environments, complete rulesets,
+protected refs, and workflow authority. Inspection is read-only by default:
+
+```sh
+node scripts/governance/check-github-repository-governance.mjs --check
+```
+
+Applying reviewed mutable drift is a separate maintainer operation requiring
+`--apply --confirm apply-a1-github-governance` and a matching post-apply read.
+Secrets and external npm trusted-publisher configuration are capability checks, not
+serialized credentials.
+
+`develop` is where work lands. `master` records what npm `latest` serves and is an
+effect of stable publication, not a trigger.
+
+## Validation by trigger
+
+| Trigger | Validation and outcome |
 | --- | --- |
-| Docs or specs only | OpenSpec strict lint, nothing else |
-| Any code PR into `develop` | Fast tier: typecheck, architecture checks, unit/contract tests |
-| Preview publish (`next`) | Fast tier + package gates on Windows, Linux, and macOS |
-| Stable publish (`latest`) | Complete suite on Windows, Linux, and macOS |
+| Pull request into `develop` | Bounded PR-cadence validation; changed/new source documentation is checked once, rendering runs as `none`, `smoke`, or `full`, and exhaustive owners are reported as deferred |
+| `npm run develop` | Preview package gates on Windows, Linux, and macOS; an existing numbered preview is an early successful no-op |
+| Nightly at `03:17 UTC` | One full documentation review plus the complete non-physical suite on Windows, Linux, and macOS, every night |
+| `npm run release -- ...` | Complete exact-byte stable gates, then npm `latest`, tag, GitHub Release, and `master` |
+| `.github/workflows/full-regression.yml` | Additional on-demand complete regression without publication authority |
+| `.github/workflows/pi-upstream-sync.yml` | Nightly at `03:23 UTC`: when npm publishes a newer Pi than the pin that no closed proposal skipped, proposes the upgrade as a draft pull request with the vendored copies that follow upstream merged, the kept copies reported with their upstream delta, the ledger, headers, inventories, public API and feature baselines, startup graph, and parity evidence regenerated, and every gate verdict (passed, failed, or blocked by conflict markers) and review item in the body; never merges and never replaces a proposal a human has continued |
+| `.github/workflows/nightly-regression-triage.yml` | After every completed `Full regression` run on `develop` or scheduled `Release` validation: judges the startup budget across the three most recent runs and, after a failure or a persistent overrun, opens `fix/nightly-regression-<date>` as a draft pull request carrying the failed commands per lane, their tests, a bounded log excerpt, the `develop` commits since the last green run, and an OpenSpec fix scaffold, or refreshes the open candidate with the same failed scope set; re-runs nothing, never writes `develop`, never merges |
+
+## Impact-aware development validation
+
+`scripts/release/select-validation-impact.mjs` is the single pull-request selector. It records the complete merge-base-to-head name-status diff, changed/new documentation inputs, rendering dependency reasons, conservative fallbacks, and the exact head SHA in a machine-readable artifact. Missing history, unresolved rendering dependencies, unknown relevant inputs, or classifier failure select full rendering rather than silently skipping it.
+
+Ordinary type, architecture, unit/contract, and dist checks always run for code changes. Changed-file documentation and rendering run as independent parallel jobs. Rendered shell/component changes select `smoke`; viewport, scheduler, terminal adapter, evidence harness, package identity, and selector changes select `full`; unrelated changes select `none`. The aggregate accepts a skipped modular job only when the current selector requested the skip.
+
+Integration owners declare one cadence in `config/integration-owners.json`. Impact mode selects affected `pull-request` owners: a changed production path selects its coarse owner, a changed test selects its owner, and a changed file under `test/support/` or `test/fixtures/` selects the owners of the retained tests that import it directly or through other support files (the selection lists those tests as its `shared-support` reason). A support file that no retained test imports, or a test tree the scanner cannot read, falls back to every owner the shared rule declares and records `shared-support-declared`; an invalidator, unknown operational path, or manual Development dispatch selects every `pull-request` owner. An implementation-bound PR body does not force conservative selection; it only removes the documentation-only and version-only shortcuts. The modular matrix itself is derived from the selection by `scripts/release/validation-matrix.mjs`, so inactive jobs are not scheduled at all rather than checking out and exiting early. `exhaustive` owners are never silently skipped or reported as passed: impact and aggregate evidence list them as cadence-deferred, and malformed cadence blocks selection. Full regression and nightly/stable release still execute both cadence classes.
+
+The real three-release `update-predecessor` scenario is exhaustive because four fresh npm installations dominated recent PR critical paths, and `update-performance` is exhaustive because its assertion is wall-clock timing on a shared runner; the update path's deterministic contracts stay on pull requests through `pi-release-resume` and `package-contracts`. PR validation retains deterministic predecessor command, lifecycle, fault, fixture, materialization, warmup, package, and update contracts. This permits a real published-history incompatibility or update slowdown to reach `develop` before the next exhaustive run detects it. `.github/workflows/full-regression.yml` runs every night at `02:47 UTC` against the `develop` tip with every owner and enforced budgets, independent of publication, so such a regression shows as a failed Full regression run the next morning; nightly publication's own complete validation still blocks publication. For a high-risk release/update change, dispatch Full regression before merge instead of adding an exhaustive owner back to ordinary Development.
+
+Development outcomes report each owner/scope invocation separately while sharing authenticated build/package preparation. The aggregate reports setup, scope, job, aggregate-processing, total runner, and runner-critical-path durations. The acceptance targets are at most eight minutes of runner critical path and five minutes for one PR-required scope; an over-target result remains unmet without retries, timeout increases, workload reduction, or mutable installation caches. Hosted queue time is reported separately when available and is not counted as test execution.
+
+Inspect local committed and worktree impact without running tests:
+
+```sh
+npm run select:validation-impact -- --include-worktree
+```
 
-Need more coverage for something risky? Run the **Full regression** workflow on
-demand.
+Check documentation only for modified, added, copied, and renamed-to policy files:
 
-## Previews publish themselves
+```sh
+npm run check:code-documentation:changed
+```
+
+Run the explicit complete documentation review used by nightly and complete regression:
+
+```sh
+npm run check:code-documentation
+```
+
+Rendering evidence captures each selected producer/mode/workload matrix once and reuses it for semantic, paint, parity, and damage assertions. A deliberate second `streamed-prose` capture remains only for determinism. Workflow summaries separate repository-gate timing from runner setup; wall-clock values diagnose runner/cache variance, while selected scopes, matrix captures, producer launches, documentation file counts, and full-scan counts are structural gates.
+
+## Resource-sensitive fast validation
+
+The authoritative fast-tier declaration identifies tests that repeatedly create temporary repositories, launch child processes, mutate storage, or coordinate release cohorts. The planner removes those files from the parallel remainder and runs them exactly once in one serial `vitest-fast-resource-sensitive` process with file parallelism disabled, on an isolated runner that no other partition shares. One process instead of one per file removes about twenty cold starts from the partition; each file still gets a fresh module context. Pull-request, development-package, and complete release plans use the same partition on every platform.
 
-Every push to `develop` publishes a preview to the npm `next` tag. Nothing to
-dispatch and nothing to approve.
+The partition runs under an explicit `--testTimeout=30000`, the same hang bound the other explicit fast-tier invocations use. That bound is a hang detector, not a performance gate: shared Windows runners vary by a factor of two or more for identical work, and a fixed five-second wall-clock limit failed passing suites on runner noise. Per-test durations remain in the reporter evidence; `scripts/release/report-resource-sensitive-validation.mjs` records repeated executions and lists every test body above five seconds under `slowTests` so a real slowdown is visible without failing the pull request. A failure is still not retried or converted to success, and the bound is not raised to create margin.
+
+Inspect the partition without running tests:
+
+```sh
+node scripts/release/run-validation-tier.mjs fast --plan
+```
+
+Record three focused serialized executions without running the complete fast tier:
+
+```sh
+node scripts/release/report-resource-sensitive-validation.mjs --repeats 3 --output .artifacts/validation/resource-sensitive-focused.json
+```
 
-The version is stamped at publish time — `<major.minor.patch>-dev.<short commit>`,
-the base taken from whatever `package.json` declares and the suffix from the commit
-being published — and is never written back to the repository. An installed preview
-therefore names the exact source it came from, and rebuilding a commit produces the
-same version rather than a new one. That suffix is also how a specific preview is
-installed: `a1 update:<commit>` resolves it against the published list and
-refuses a commit that was never published. `develop` therefore carries one open prerelease version between
-releases, and no commit is ever spent on a preview.
+## Pull request integration
 
-One consequence worth knowing: a push that would republish an existing version
-fails early, before anything is packed.
+`Development validation required` remains the merge gate for every pull request. For applicable code changes, it requires the dedicated Defender-enabled exact-package startup lane on Windows Node 22. Development validation (including manual dispatch) does not schedule a Windows Node 24 startup lane. The Node 22 lane retains the complete package-install, image preparation/package, and durable-history checks plus startup evidence artifacts. A missing, cancelled, failed, or unexpectedly skipped required startup result still blocks the aggregate; documentation-only, version-only, and draft exemptions are unchanged.
+
+| Startup runtime | Development validation (PR or manual) | Development preview (`npm run develop`) | Nightly and stable publication | Manual Full regression |
+| --- | --- | --- | --- | --- |
+| Windows Node 22 | Required for applicable changes | Not scheduled | Retained | Retained |
+| Windows Node 24 | Not scheduled | Retained | Retained | Retained |
+
+Each selected startup lane runs the package-install scenarios once: a failed budget remains failed and is never retried to obtain a warmed result. The budgets are the ones the `a1-shell` capability declares (2 seconds after an update and on a warm launch, 2.5 seconds with no live supervisor); development validation, development previews, nightly publication, and Full regression record an overrun as a warning and are judged by the three-run persistent-overrun verdict, while stable publication fails on it (see `STARTUP_BUDGET_ENFORCEMENT` in [validation](validation.md)). The publication lane set comes from `scripts/release/publication-validation-matrix.mjs`: a numbered preview validates on the Windows, Linux, and macOS Node 24 lanes, and nightly covers the same head on Windows Node 22 within a day. Node 24 runtime support, other PR jobs, Defender, and publication gates are unchanged. Full validation retains every deferred startup, image, and history test through its existing suite owners.
+
+The trade-off is delayed detection: a Node-24-specific regression can reach `develop` before nightly catches it, and the same is true for a real published-predecessor regression. A green bounded PR check does not certify Node 24 or real historical predecessor execution, and nightly failure still blocks its publication. When deferred feedback is needed before nightly, explicitly request the non-publishing Full regression workflow for the desired branch or tag:
+
+```sh
+gh workflow run full-regression.yml --ref <branch-or-tag>
+```
+
+Record the run's resolved source SHA and package evidence; do not substitute an unrelated historical green run for current-head acceptance. This full run is a deliberate additional operation, not an automatic step for every PR.
+
+Documentation auto-merge reads the complete GitHub changed-file response and arms
+squash auto-merge for an eligible pull request while required validation is pending;
+branch protection prevents integration until `Development validation required`
+succeeds. If validation finishes before auto-merge can be armed and GitHub already
+reports the pull request clean, the reconciler squash-merges only the validated head
+SHA. Every current and renamed-from path must be under `openspec/**`, under
+`docs/**`, or exactly the root `README.md`. Eligible pull requests must use a
+non-draft branch in this repository and target `develop`. Implementation-associated PRs and newly introduced active OpenSpec changes are held for manual integration even when their diff is documentation-only. Body edits trigger reconciliation; removing a marker cannot bypass the base/head tree check. Standalone existing-change revisions and archive moves remain eligible.
+
+The exact allowlist covers maintained OpenSpec, architecture, feature, manual,
+runbook, and root README documentation. Other root Markdown files, `LICENSE`,
+`.gitignore`, source, tests, scripts, workflows, configuration, generated baselines,
+and mixed changes do not auto-merge. The guard also runs when a pull request changes
+or auto-merge is manually enabled; if any path is outside the allowlist, it disables
+auto-merge while leaving the pull request available for a later manual merge. Every
+docs-only change runs lightweight generated-governance consistency, so archiving an
+inventoried OpenSpec occurrence fails that pull request rather than a later code pull
+request. The only narrower route is an exact single added canonical
+`openspec/acceptance/<change>/<source-head>.json` record: trusted base policy reads the
+complete live diff before dependency installation, then the dedicated acceptance job
+must validate its exact source, CI, scope, branch, body, checklist, and conflict state.
+Only that verified route skips generic impact installation and documentation/all-spec
+validation; malformed, mixed, renamed, stale, or unavailable inputs fail closed.
+A legitimate generated baseline update remains outside the allowlist and follows the
+manually accepted mixed/code path.
+
+A new implementation-bound specification starts as OpenSpec-only artifacts in one normally named draft PR. Explicit approval to implement continues in that same worktree, branch, history, and PR; the plan does not merge first. Approved refinements reconcile planning before code. After implementation, add one to three plain implementation-specific bullets under `## Acceptance` and mark the PR ready; the trusted `OpenSpec finalization` workflow conservatively synchronizes deltas, stages the dated archive plus conditional acceptance manifest, and commits them to the same branch, and exact-head CI validates that head. Auto-merge remains disabled: an authorized maintainer's manual merge accepts the listed scenarios and atomically integrates implementation, specs, and archive. No acceptance or archive follow-up PR is created. Closing an unmerged draft integrates nothing; cleanup still needs separate approval. See [delivery and archive handoff](openspec-archive-automation.md) for commands and legacy compatibility.
+
+## Numbered development previews
+
+A merge or push to `develop` does not publish by itself. To request a deliberate
+preview from any authorized checkout:
+
+```sh
+npm run develop
+```
+
+The command fetches authoritative `origin/develop`, resolves the unique merged pull
+request associated with that exact commit through GitHub, and derives
+`<major.minor.patch>-dev.<pull-request number>`. Thus GitHub's `develop (#107)`
+source produces `0.1.8-dev.107`. It first checks npm; if the immutable version
+already exists it reports that version without dispatching package work. Otherwise
+it dispatches GitHub Actions, waits, and reports the published version. It never
+builds or uploads npm bytes from the workstation.
+
+Nightly resolves the same current `origin/develop` source. It runs one platform-independent full documentation review before the platform matrix, and the matrix records that prerequisite instead of repeating the scan four times. It always runs complete verification even if source has not changed. For a new number it packs once and
+runs the suite against that final-version tarball before publication. For an
+existing number it downloads the exact npm tarball and runs package/update gates
+against those registry bytes; publication is then a successful no-op.
+
+Manual and nightly runs share one non-cancelling concurrency group. Their final
+registry check is serialized, so overlapping requests can produce only one publish
+and one successful existing-version no-op. A development publication moves npm's
+internal `next` dist-tag and never moves `latest`.
+
+Users install previews with public `develop` terminology:
+
+```sh
+a1 update --develop                     # current development channel
+a1 update --develop 107                 # numbered preview
+a1 update --develop 0.1.8-dev.107       # exact full preview version
+```
+
+The former `a1 update:<selector>` commands are removed without compatibility
+aliases or redirects. Unsupported forms exit quietly without registry or runtime
+work.
 
 ## Cutting a stable release
 
-One command, from a clean `develop` that matches its remote:
+From the repository root on clean `develop` matching `origin/develop`:
 
 ```sh
-npm run release -- patch     # or minor, major, or an exact x.y.z
+npm run release -- patch     # 0.1.8-dev -> 0.1.8; already-stable 0.1.8 -> 0.1.9
+npm run release -- minor     # 0.1.8-dev -> 0.2.0
+npm run release -- major     # 0.1.8-dev -> 1.0.0
+npm run release -- 0.4.0     # exact stable target
 ```
 
-It lands `x.y.z` on `develop` through a pull request that merges itself, waits for
-that publication to succeed, and then lands `x.y.(z+1)-dev` so previews resume
-immediately. It publishes nothing itself and creates no tag.
+A target is required: `npm run release` alone is a mutation-free usage error.
+`patch` preserves prerelease-aware semantics, including `0.1.8-dev.123 -> 0.1.8`.
+The command reports its source, stable target, and prospective reopening before
+preparing anything.
 
-Landing the stable version is what publishes. The same pipeline sees a commit
-declaring a stable version and runs its stable form: build the process guardian on
-all three platforms, pack once, run the complete suite against those exact bytes on
-all three platforms, publish to npm `latest` with provenance from the
-`npm-publish` environment, and only then write the tag `vx.y.z`, record the GitHub
-Release, and fast-forward `master`.
+1. The stable-version edit is committed in an owned detached worktree beneath
+   `.worktrees/`. Only this package's manifest and root lockfile version change.
+2. Follow the printed PR URL, wait for required CI, perform local validation, and
+   **merge manually after acceptance**. The helper does not merge PRs or enable
+   auto-merge. It polls for actual merge with a bounded 30-minute wait.
+3. The helper verifies the merged version and source SHA against authoritative
+   develop, then explicitly dispatches stable publication for that exact source.
+   A changed source is an error, not permission to substitute a newer commit.
+4. Only after verified publication of `0.1.8` does it prepare a separate PR for
+   `0.1.9-dev`. Validate and manually merge that PR as well. Until then the helper
+   reports development reopening as incomplete.
 
-That order is the point. A release that fails leaves no tag, no release, and no
-moved branch — only a red run. Nothing ever advertises a version that does not
-exist on the registry.
+Closed PRs, timeout, cancellation, and query failures retain identifiable phase
+work for inspection. Conflicting existing branches/PRs are not overwritten;
+matching pending PRs can be observed again without replacing them. Worktrees
+retained by an earlier attempt are not removed by a later invocation. Cleanup
+only removes clean, owned, confirmed-merged phase worktrees and unchanged remote
+phase branches. The caller is never hard-reset: a final fast-forward is attempted
+only when its branch, original HEAD, and cleanliness remain unchanged. Otherwise
+preserve local work and synchronize manually with the reported remote state.
+
+Stable publication builds the process guardian on all supported platforms, packs
+once, runs the complete suite against those exact bytes on Windows, Linux, and
+macOS, publishes to npm `latest` with provenance from the `npm-publish`
+environment, and then writes `vx.y.z`, records the GitHub Release, and fast-forwards
+`master`. A push of the stable version does not publish it.
 
 Rules that do not bend:
 
-- **Never upload locally rebuilt bytes.** The publisher uploads the artifact the
-  validation ran against, and re-checks its digest before and after.
-- **Never route around validation by rebuilding inside a publisher.** The publish
-  job has no checkout of dependencies, no build, and no pack step.
-- **Never move a release tag.** A wrong tag is superseded by the next version, not
-  repointed. The tag is written by the publication itself, so it exists only for
-  versions that shipped.
+- **Never upload locally rebuilt bytes.** The publisher uploads the artifact the validation ran against and checks its digest before and after.
+- **Never route around validation by rebuilding inside a publisher.** The publish job receives the packed artifact and does not install dependencies, build, or pack.
+- **Never move a release tag.** A wrong tag is superseded by the next version, not repointed.
 
 ## When something fails
 
-- **PR validation fails:** fix the code and push. Do not mark a failed tier optional.
-- **Preview publish fails:** fix and push again; the next push publishes the next
-  run number. Nothing needs cleaning up.
-- **Stable publish fails:** nothing was recorded — no tag, no release, no moved
-  branch. Fix the cause and release the next version. The failed version number is
-  spent, because `develop` has already moved past it.
-- **Stable publish is uncertain after npm accepted the bytes:** stop. Check the
-  registry for the version, tag, and digest. Repair a dist-tag only as a separate
-  reviewed operation — never republish.
-
-## Why the ruleset looks the way it does
-
-One person maintains this repository, and GitHub does not let a PR author approve
-their own PR. Requiring even one approval would deadlock the authorized
-solo-maintainer path — no PR could ever merge. So the `develop` ruleset requires a
-pull request, a green required check, and resolved review threads, but sets required
-approving reviews to zero. It does not require the branch to be up to date: once a
-PR is green it merges even if unrelated work landed first, with no re-validation
-loop.
-
-The `master` and tag rulesets carry no checks at all. Both only ever receive a commit
-that has already been validated and published, so what matters about them is that
-neither can be rewritten. Requiring a pull request on `master` would stop the release
-from recording itself there.
-
-Do not add a direct-push bypass as a shortcut, and never weaken the force-push or
-deletion protection. Ruleset mutation is a separate administrative operation: run
-`node scripts/check-github-rulesets.mjs` to see the diff, and apply only when a
-maintainer explicitly confirms with `--apply --confirm apply-a1-ci-rulesets`.
+- **PR validation fails:** fix the code and push; do not mark a failed PR-cadence tier optional. If real predecessor history is needed, run Full regression rather than changing the exhaustive result into PR success.
+- **Nightly startup budget overruns:** a single overrun on Full regression or nightly publication is a warning in the run summary, not a failure; the triage judges the key across the three most recent `develop` runs and opens a `package-startup` candidate only when all three overran. Stable publication still fails on one overrun; rerun it with the measured phases in hand.
+- **Nightly regression fails:** the triage workflow opens or refreshes a draft `fix/nightly-regression-<date>` pull request whose body and change carry the evidence; start the fix there. Reproduce from the listed tests or commands on the failed lane, fix without weakening assertions, budgets, timeouts, or coverage, then dispatch `gh workflow run full-regression.yml --ref fix/nightly-regression-<date>` on the completed fix head and record the run in the change's design evidence before hand-off; ordinary PR validation does not run the exhaustive owners the nightly failed on. A day whose failed scope set differs from every open candidate opens a new one. A Full regression dispatched on a candidate's own branch is that candidate's proof; its failures never open another candidate. A failure with no candidate means the triage workflow itself failed; read its run summary and dispatch it with the failed run id and `dry_run` off.
+- **Nightly exhaustive predecessor validation fails:** treat the focused PR result as insufficient, keep publication blocked, and repair the incompatibility without reducing predecessor count, timeouts, or exact-package isolation.
+- **Documentation auto-merge fails:** leave the pull request open, inspect its exact
+  changed-file classification, docs-sensitive inventory, and workflow permissions,
+  and never broaden the allowlist to make one pull request pass.
+- **Merged-branch cleanup fails:** inspect the bounded PR/ref/SHA disposition. Never
+  delete an advanced or protected ref merely because its name matches an old PR.
+- **Repository governance drifts:** run the read-only checker, review every reported
+  path, and use the confirmed apply mode only for an accepted mutable policy change.
+- **A Pi upgrade proposal needs a re-run:** the sync never force-pushes over `chore/pi-<version>` once it carries a commit the bot did not author; a scheduled re-run posts its fresh verdicts as a comment headed with the version and date and rewrites only the report between the `<!-- pi-upgrade-report -->` markers of the description. To re-run the derived steps and gates on the reviewer's head, dispatch the workflow with `refresh` and the `version`; it checks out the proposal branch, skips bump, evaluation, install, and merge, and reports without pushing. A branch whose commits are all the bot's is recreated from `develop` as before.
+- **A Pi version should not be adopted:** close its proposal pull request with the `pi-upgrade-skipped` label (declared in `config/github-repository-governance.json`) and say why in the closing comment; the next run proposes the newest unskipped version newer than the pin, or nothing, and names the skipped versions in its log. A proposal closed without the label is proposed again the next night. Dispatching the workflow with a `version` ignores skips, which is how a skipped version is reconsidered. To silence the schedule through a release window, set the repository variable `PI_UPGRADE_FREEZE_UNTIL` to a date (`2026-10-01`); scheduled runs exit before proposing until it passes, manual dispatches still run.
+- **Nightly documentation review fails:** inspect the reported paths and rules, identify the introducing merge from the nightly interval, and repair the invariant before unrelated work proceeds.
+- **Development publication fails:** fix the cause and rerun `npm run develop`; an npm version that already exists is never overwritten.
+- **Registry verification times out:** a `has not propagated` failure after a successful `npm publish` means npm is still ingesting the upload; it warns that a provenance-signed package "may take a few minutes" and the publisher polls for ten minutes. Confirm the version and its shasum on `https://registry.npmjs.org/<name>/<version>`, then rerun the failed jobs: the final registry check finds the exact bytes, skips `npm publish`, and verification passes. A digest or tag mismatch is not a timeout and is never repaired by rerunning.
+- **Stable preparation stops before dispatch:** inspect the reported version PR/worktree. After preserving work, an exact matching pending PR can be observed again. If develop already declares the prepared stable version, use its exact target (for example `npm run release -- 0.1.8`) only after verifying that source's merged PR and confirming the registry/tag guards still permit it. Do not use `patch` from stable develop to retry the same version: that deliberately selects the next patch.
+- **Stable publication fails or is uncertain:** inspect the workflow, registry version/digest, tag, and release before choosing recovery. No reopening PR is prepared. Never republish immutable bytes or move a release tag.
+- **Stable publication succeeded but reopening stops:** the stable version is already published. Inspect and finish the reported next-development PR manually; do not repeat stable publication. If no reopening PR was created, prepare the next-development version through a separately validated manual PR after inspecting remote state.
+
+## Safe release-command validation
+
+Use the isolated harness rather than a live release to validate changes to this command:
+
+```sh
+npm exec --no -- vitest run test/repository-governance/release-target.test.ts test/repository-governance/release-command.test.ts --maxWorkers=1 --minWorkers=1
+```
+
+It uses disposable local Git repositories and fake GitHub, registry, and publication
+services. It does not publish a package or create production version PRs. A real
+release remains a separate deliberate operation.
+
+## Branch protection rationale
+
+One person maintains this repository, and a PR author cannot approve their own PR.
+The `develop` ruleset therefore requires a pull request, a green required check,
+and resolved review threads, but zero approving reviews. `master` and release tags
+are written only after publication and are protected from force-push, movement, and
+deletion.
+
+Do not add direct-push bypasses. Approval count, strict-base validation, repository
+merge methods, Actions allowance/SHA enforcement, Dependabot, and npm environment
+protection remain explicit maintainer decisions; governance automation does not
+silently change them. Repository mutation remains a separate confirmed administrative
+operation through `check-github-repository-governance.mjs`.

package/docs/features/launch-profiles.md

@@ -4,17 +4,17 @@
 
 | Command | Purpose | Pi user profile |
 |---|---|---|
-| `a1` | A1-owned Pi-compatible UI | `~/.a1/agent` |
-| `a1 pi` | Untouched vanilla Pi fallback and comparison oracle | ordinary `~/.pi/agent` |
-| `a1 sandbox` | Unchanged isolated vanilla Pi profile for experiments | `~/.a1/sandbox` |
+| `a1` | Fresh A1-owned Pi-compatible UI session | `~/.a1/agent` |
+| `a1 --session <path\|id>` | Resume a persisted A1 session | `~/.a1/agent` (or explicitly selected storage) |
+| `a1 pi` | Pi-compatible comparison surface using the ordinary Pi profile | ordinary `~/.pi/agent` |
 
-`a1 pi` and `a1 sandbox` are development instruments: one compares A1 against pinned Pi, the other tries resources against an isolated profile. Prerelease builds — what `a1 update:next` installs — expose them. A release build does not, and does not recognize the words: what it exposes is bare `a1` plus the maintenance and package commands. Working in this repository is unaffected, because `npm start:pi` and `npm run start:sandbox` prepare the profile and launch directly rather than through the command line.
+`a1 pi` is a development instrument for comparing A1 against pinned Pi. Prerelease builds — what `a1 update --develop` or `a1 update --develop <number>` installs — expose it. A release build does not recognize the launch form. Repository development can run the comparison directly with `npm start:pi`.
 
-There is no `a1 agent` command. The former `a1 ui` subcommand is removed. Bare `a1` is the owned agent product surface and remains the entry point when multi-agent UX is introduced.
+There is no `a1 agent` command. The former `a1 ui` subcommand is removed. Unsupported commands return quietly without selecting another runtime. Bare `a1` is the owned agent product surface and remains the entry point when multi-agent UX is introduced.
 
 ## First launch
 
-For A1-owned profiles, A1 creates only the selected profile root and empty `extensions`, `skills`, `prompts`, and `themes` directories. Existing content is preserved. A1 does not copy, link, merge, or delete settings, credentials, sessions, packages, trust decisions, or resources from another profile.
+A1 creates only its selected profile root and empty `extensions`, `skills`, `prompts`, and `themes` directories. Existing content is preserved. A1 does not copy, link, merge, or delete settings, credentials, sessions, packages, trust decisions, or resources from another profile.
 
 Pi owns files within the selected root. Common locations are:
 
@@ -31,28 +31,35 @@ npm/
 
 Run Pi’s normal `/login` independently in each profile that needs stored authentication. Provider credentials supplied through supported environment variables remain available to Pi, but profile authentication files never fall back to another root automatically.
 
-## Vanilla Pi
+## Resume a session
 
-`a1 pi` bypasses the A1-owned UI and launches the untouched pinned Pi CLI. It also removes A1’s Pi configuration-root override, so Pi uses its normal `~/.pi/agent` settings, authentication, sessions, resources, packages, and trust decisions. This is both the comparison oracle and the recovery fallback when diagnosing the owned UI.
+After a conversation has been persisted, exit A1 and run the command it prints from the original project directory:
 
-## Sandbox profile
+```sh
+a1 --session <id>
+a1 --session-dir '/path/to/session store' --session <id>
+```
 
-`a1 sandbox` remains a direct vanilla Pi launch. It uses `~/.a1/sandbox` and starts Pi with its supported one-run `--no-approve` trust override. Project-local executable settings and resources are ignored for that run; sandbox-owned resources still load from the selected user profile.
+`--session` also accepts a `.jsonl` file path; `--session-dir` may come before or after it. Explicit storage overrides `PI_CODING_AGENT_SESSION_DIR`, which overrides default storage. IDs are searched in the current project before other projects within the A1 store. A cross-project ID match asks before creating a fork with a new identity; an explicit file resumes directly using its stored working directory. Missing or invalid targets fail rather than create an empty replacement.
 
-“Sandbox” means Pi profile and executable-resource isolation. It is **not** an operating-system security boundary. It does not restrict filesystem access, processes, network access, environment credentials, shell tools, or commands executed by Pi.
+Resume uses the shipped Pi's public restoration behavior, including the compaction format it writes. It sends no model prompt by itself and does not recover, convert, or modify an unrelated conversation. Bare `a1` remains a fresh launch. Pi picker/continue CLI aliases and `a1 pi --session` are not supported by this repair; in-UI `/resume` is unchanged.
 
-## Terminal behavior
+Regression evidence creates disposable sessions through Pi 0.84.2, then executes the emitted command through the packed public entry, bootstrap, guardian, and owned UI. Default/custom storage, Windows Git Bash quoting, supervisor restart, failure cleanup, and simultaneous distinct selections are covered in `test/foundation/release/session-resume.integration.test.ts`. CI runs it in the resource-sensitive `package-smoke` scope, not the fast remainder. Unsupported synthetic retained-tail certification is separate deferred work.
+
+## Pi comparison profile
 
-Bare `a1` runs the A1-owned full-viewport TUI over public Pi engine, component, and terminal APIs. A1 owns composition, input routing, modal focus, selection behavior, scrolling, and restoration without inserting a PTY or terminal-byte relay. Its default presentation is pinned to vanilla Pi parity; structured tabs and A1-specific visual customization are not enabled.
+`a1 pi` uses the same A1-owned rendering and input pipeline as bare `a1`, but withholds A1-specific screens and removes A1’s Pi configuration-root override. The pinned Pi engine therefore uses its normal `~/.pi/agent` settings, authentication, sessions, resources, packages, and trust decisions. Running the standalone `pi` command remains the independent upstream reference.
+
+## Terminal behavior
 
-`a1 pi` and `a1 sandbox` retain transparent direct attachment. In those profiles, untouched Pi and the physical terminal own rendering, input, selection, clipboard, scrollback, and terminal modes; A1 owns only per-invocation process containment and lifecycle evidence.
+Both launch forms run the A1-owned full-viewport TUI over pinned Pi engine, component, and terminal APIs. A1 owns composition, input routing, modal focus, selection behavior, scrolling, and restoration without inserting a PTY or terminal-byte relay. Bare `a1` enables A1-owned screens; `a1 pi` uses the same pipeline with those screens withheld.
 
 ## Concurrent instance lifecycle
 
-Every `a1`, `a1 pi`, and `a1 sandbox` invocation receives a unique non-detachable launch instance. There is no product-wide foreground slot: the same profile or any mixture of profiles may run concurrently in separate terminals. Profile files remain shared according to the selected profile root, while process ownership, lifecycle outcome, and cleanup remain scoped to the command that launched them.
+Every invocation receives a unique non-detachable launch instance. There is no product-wide foreground slot: the same profile or both profiles may run concurrently in separate terminals. Profile files remain shared according to the selected profile root, while process ownership, lifecycle outcome, and cleanup remain scoped to the command that launched them.
 
-Normal root exit, terminal closure, guardian failure, and verified update shutdown all close the instance's remaining process tree within bounded graceful and forced deadlines. Closing one instance never closes another. A control supervisor may remain idle afterward, but closed instances leave no UI, Pi, extension daemon, agent worker, tool, or descendant process. Ordinary recovery never asks users to kill a PID or delete the control database.
+Normal root exit, terminal closure, guardian failure, and verified update shutdown all close the instance's remaining process tree within bounded graceful and forced deadlines. Closing one instance never closes another. A control supervisor may remain idle afterward, but closed instances leave no UI, Pi, extension daemon, agent worker, tool, or descendant process.
 
 ## Recovery and comparison
 
-If bare `a1` cannot start or a UI workflow diverges, run `a1 pi` from the same working directory and compare the behavior. Profile data is intentionally separate, so authentication or settings may need to be configured independently. Use `a1 version` to record the installed A1 release before reporting a difference. `a1 sandbox` is for isolated profile experiments, not recovery from the owned UI and not a security boundary.
+If bare `a1` cannot start or a UI workflow diverges, run `a1 pi` from the same working directory and compare the behavior. Profile data is intentionally separate, so authentication or settings may need to be configured independently. Use `a1 --version` to record the installed A1 release before reporting a difference.

package/docs/features/modal-content-interaction.md

@@ -0,0 +1,38 @@
+# Transcript interaction with modals
+
+Bare A1 keeps the exposed transcript under its normal viewport controller while a modal is open. Scrolling, scrollbar settings, selection styling and boundaries, clipboard output, and speed are the same as without a modal. This is not a new selection implementation or a speed adjustment. The comparison `a1 pi` path is unchanged.
+
+Pointer ownership follows the painted region, not keyboard focus. Docked replacements publish their input bounds from shell layout. The runtime observes public overlay component renders in the protected composition hook, including runtime-created search overlays, and projects the pinned public layout options into terminal hit regions. Terminal-cell tests compare that projection with actual overlay paint across anchors, percentages, margins, clipping, stacking, and resize. No installed dependency or private renderer state is modified.
+
+A pointer gesture stays with its initiating surface through release. Geometry or ownership changes cancel the old viewport gesture, stop its timers, and consume the remaining gesture rather than delivering it to a newly revealed surface. Modal-covered cells do not accept new background gestures. Keyboard input remains with the focused modal, except that a nonempty A1 transcript selection owns its copy chord exactly once. There is no vanilla selection layer or vanilla copy notification for transcript gestures.
+
+## Host inventory
+
+The existing [modal transition inventory](../../config/baselines/modal-surface-inventory.json) remains the authority for specialized workflows. All its nodes cross one of these shared hosts; there is no command allowlist in pointer routing.
+
+| Inventory family | Shared host | Interaction evidence |
+| --- | --- | --- |
+| `editor.root` | Ordinary editor and viewport | Existing viewport/controller and shell regression cases |
+| `settings.*`, `models.*`, `trust.project` | Shell replacement input, including nested component states | Real settings/thinking, Model Configuration and model selection; generic replacement geometry and gesture tests |
+| A1-owned Skills dialog (`/skills`, not a pinned node) | Shell replacement input, presented like `models.select` | `test/app/session-shell/session-shell-skills.test.ts` apply/cancel/resize cases; shared replacement tests |
+| `session.*`, `tree.*` | Shell replacement input and nested replacement/confirmation controllers | Real fork plus existing resume/tree/missing-directory lifecycle cases; shared replacement tests |
+| `auth.*` | Shell replacement input, including provider and nested prompts | Real login/logout plus existing OAuth/API-key/nested restoration cases; shared replacement tests |
+| `command.import-confirm`, `operation.*` | Shell replacement confirmation/loader | Existing confirmation/loader lifecycle cases; shared replacement tests |
+| `extension.select`, `extension.confirm`, `extension.input`, `extension.editor`, `extension.custom-editor`, `extension.custom-replacement` | Extension bridge to shell replacement input | Parameterized public extension UI tests, including an unlisted custom replacement |
+| `extension.overlay`, backend dialogs, owned route panels | Runtime overlay host | Unlisted extension overlay, partial/full-cover/stacked overlay paint and pointer tests |
+| Runtime transcript search | Public runtime overlay entry, not a shell command registration | Runtime-created search geometry/focus/restoration test |
+
+Focused files:
+
+- `test/app/session-shell/session-viewport-controller.test.ts`: modal/no-modal selection/copy and render-cadence comparison, wheel/auto-scroll speed comparison, settings, boundary crossings, and gesture cancellation.
+- `test/app/session-shell/session-shell.test.ts`: real workflows, extension-host families, ordered mixed/chunked input, nested settings, resize, streaming, copy notification exclusion, and modal-over-selection terminal paint.
+- `test/integrations/pi/tui-runtime/overlay-geometry.test.ts`: independent terminal-cell geometry and runtime search coverage.
+- `test/integrations/pi/tui-runtime/mouse-report-input.test.ts`: ordered report delivery, partial reports, and opaque pasted text.
+
+## Manual review
+
+Build the exact candidate, then launch it through `./scripts/dev` from its worktree in Windows Terminal/Git Bash. Populate a long transcript (for example with a few prompts, or `/hotkeys` under `a1 pi`; in bare A1 `/hotkeys` opens a full-screen reference screen and appends nothing), then open `/scoped-models`. Compare scrolling and drag/word/line selection with the dialog closed and open. Try the rail, copy, and jump-to-bottom; the model dialog must not navigate or close as a side effect of transcript gestures. Copy must not show Pi's `Copied` notification.
+
+Repeat with `/models`, settings and a nested settings dialog, and extension-provided docked and floating surfaces. Check that typing, modal buttons and wheel handling, save, and cancel still work. Resize during a drag, close/reopen the modal, and repeat while output streams. A full-cover screen must not allow click-through into hidden transcript cells. `auto` scrollbar visibility remains activity-dependent; `hidden` remains hidden.
+
+User confirmation of the exact built candidate is still required before merging the code PR. The baseline's pre-existing selection boundaries and speed are intentionally preserved, as clarified by the user; this change does not attempt to reconcile older specification wording by changing those behaviors.