@timurproko/a1 0.1.8-dev.21b95d6 → 0.1.8-dev.224

package/docs/ci-release-runbook.md

@@ -5,107 +5,214 @@ 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 |
+
+`.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`.
+
+`.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.
+
+`.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.
+
+`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:
 
-Publishing is one workflow, `.github/workflows/release.yml`, triggered by pushes
-rather than dispatched by hand.
+```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 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.
+`develop` is where work lands. `master` records what npm `latest` serves and is an
+effect of stable publication, not a trigger.
 
-## How much validation runs when
+## Validation by trigger
 
-| Change | Validation |
+| 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` | Modular fast validation; changed/new source documentation is checked once, and rendering runs as `none`, `smoke`, or `full` from the exact impact |
+| `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 |
+
+## 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.
+
+Inspect local committed and worktree impact without running tests:
+
+```sh
+npm run select:validation-impact -- --include-worktree
+```
+
+Check documentation only for modified, added, copied, and renamed-to policy files:
+
+```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.
 
-Need more coverage for something risky? Run the **Full regression** workflow on
-demand.
+## Resource-sensitive fast validation
 
-## Previews publish themselves
+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 as `vitest-fast-resource-sensitive` with file parallelism disabled. 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 retains Vitest's five-second default test timeout. It does not add a test, suite, platform, or workflow timeout, and a failure is not retried or converted to success. If a serialized test still approaches five seconds, use `scripts/release/report-resource-sensitive-validation.mjs` to record repeated per-file and test-body timing, then optimize repository setup, subprocess count, storage operations, or release fixtures. Do not increase a timeout to create margin.
 
-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.
+Inspect the partition without running tests:
 
-One consequence worth knowing: a push that would republish an existing version
-fails early, before anything is packed.
+```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
+```
+
+## Pull request integration
+
+`Development validation required` remains the merge gate for every pull request.
+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`.
+
+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. A legitimate generated baseline update remains outside the allowlist and
+follows the manually accepted mixed/code path.
+
+A specification request lands as an OpenSpec-only pull request. Implementation
+starts only after that specification merges and the maintainer explicitly requests
+it, in a fresh worktree and pull request based on updated `origin/develop`. Every
+code/operational pull request remains open after CI until the maintainer validates it
+locally and explicitly authorizes manual integration.
+
+## 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 a clean `develop` matching its remote:
 
 ```sh
 npm run release -- patch     # or minor, major, or an exact x.y.z
 ```
 
-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.
-
-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`.
+The command lands `x.y.z` through its version pull request, explicitly dispatches
+stable publication for that exact current `origin/develop` commit, and waits. Only
+after success does it land `x.y.(z+1)-dev`.
 
-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.
+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 tier optional.
+- **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.
+- **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.
+- **Stable publication fails before npm accepts bytes:** no tag, release, or moved branch exists. Fix the cause and release the next version.
+- **Stable publication is uncertain after npm accepted bytes:** stop and inspect registry version, digest, tag, and release. Never republish immutable bytes.
+
+## 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

@@ -5,16 +5,15 @@
 | 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 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 +30,20 @@ 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
+## Pi comparison profile
 
-`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.
-
-## Sandbox profile
-
-`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.
-
-“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.
+`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
 
-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` 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/manual-launch-instance-acceptance.md

@@ -4,63 +4,40 @@ Run this checklist only against a packaged candidate on a user-controlled termin
 
 ## Artifact identity
 
-Record before testing:
-
-```text
-A1 release ID:
-A1 package version:
-Source commit:
-Candidate tarball SHA-256/integrity:
-Process guardian target: win32-x64
-Process guardian crate version:
-Process guardian protocol version:
-Process guardian SHA-256:
-Process guardian signature/attestation status:
-Machine/Windows/terminal versions:
-Tester or worker attestation:
-```
-
-The process guardian values must match `dist/native/win32-x64/manifest.json` inside the exact installed candidate. Stop if the file is missing, mismatched, altered, or reports an unsupported capability.
+Record the A1 release ID, package version, source commit, candidate integrity, process-guardian target/version/protocol/integrity, platform and terminal versions, and tester attestation. The guardian values must match `dist/native/win32-x64/manifest.json` inside the exact installed candidate.
 
 ## Concurrent launch matrix
 
-Open four independent terminal tabs and launch:
+Open four independent terminal tabs:
 
 ```text
 Terminal 1: a1
 Terminal 2: a1
 Terminal 3: a1 pi
-Terminal 4: a1 sandbox
+Terminal 4: a1 pi
 ```
 
-Confirm all four become usable without a global foreground-lease error. Record each launch-instance ID from supervisor metadata and verify all four IDs are distinct.
+Confirm all four become usable without a global foreground-lease error and have distinct launch-instance IDs.
 
 ## Isolated closure
 
-1. Exit Terminal 3 normally. Confirm only its vanilla Pi tree exits; Terminals 1, 2, and 4 remain usable.
-2. Close the Terminal 4 tab/window without exiting Pi first. Confirm its sandbox Pi, extension daemons, agent workers, tools, and descendants disappear within the bounded deadline while both bare-A1 terminals remain usable.
-3. Exit Terminal 1 normally after causing a fixture extension to create a child and grandchild. Confirm the complete tree disappears and Terminal 2 remains usable.
-4. Force the Terminal 2 launch guardian to fail on the isolated worker. Confirm Job Object kill-on-close removes its root and descendants and leaves unrelated fixture processes alive.
+1. Exit Terminal 3 normally. Confirm only its Pi comparison tree exits.
+2. Close Terminal 4 without exiting first. Confirm its complete process tree disappears while both bare-A1 terminals remain usable.
+3. Exit Terminal 1 after causing a fixture extension to create a child and grandchild. Confirm the complete tree disappears and Terminal 2 remains usable.
+4. Force the Terminal 2 launch guardian to fail on the isolated worker. Confirm containment removes its root and descendants and leaves unrelated fixture processes alive.
 
-Record root, child, and grandchild native identities before each close and the observed terminal outcome afterward. Do not substitute manual PID termination for a failed cleanup.
+Record root, child, and grandchild native identities before each close and the observed terminal outcome afterward. Do not substitute manual PID termination for failed cleanup.
 
 ## Stale-state recovery
 
-Using isolated control directories, install a version-4 fixture database containing one requested or active legacy foreground lease whose former PID is dead. Run `a1 sandbox` once. Confirm that the same invocation migrates the row to historical interrupted state and launches normally without restarting the supervisor, deleting state, or discovering a PID.
+Using isolated control directories, install a version-4 fixture database containing one requested or active legacy foreground lease whose former PID is dead. Run bare `a1` and confirm the invocation migrates the row to historical interrupted state and launches normally.
 
 Repeat with an ownership-uncertain fixture process. Confirm a new independent launch still starts and the uncertain unrelated process is not terminated.
 
 ## Update fan-out
 
-With at least three mixed-profile instances active, run the candidate's update-shutdown fixture. Confirm every instance receives one stop intent, each complete process tree closes, and cohort replacement occurs only after all verified terminal outcomes. A delayed or uncertain instance must prevent unsafe replacement without causing another instance to be reported idle prematurely.
+With at least three mixed-profile instances active, run the candidate's update-shutdown fixture. Confirm every instance receives one stop intent, each complete process tree closes, and cohort replacement occurs only after all verified terminal outcomes.
 
 ## Verdict
 
-Record one of:
-
-```text
-ACCEPTED — exact package and guardian digests above passed every scenario
-REJECTED — include failed step, observed process identities, outcomes, and diagnostics
-```
-
-Acceptance applies only to the exact package and process-guardian bytes recorded above. It does not certify macOS, Linux, composed terminals, detached agents, or an operating-system security sandbox.
+Record either exact-artifact acceptance or rejection with the failed step, process identities, outcomes, and diagnostics. Acceptance applies only to the recorded package and process-guardian bytes.

package/docs/manual-owned-ui-checkpoint.md

@@ -0,0 +1,78 @@
+# Manual owned-UI checkpoint
+
+This checkpoint is user-controlled. Tests and coding agents must not launch or focus a terminal, inject desktop input, resize windows, close applications, or clean up workstation processes.
+
+## Prepare an exact candidate
+
+For a checkout smoke test in Git Bash, build once and launch with `./scripts/dev` or `./scripts/dev pi`. Do not invoke `node scripts/development/dev-launch.mjs` or `node scripts/development/start-local.mjs` directly: that bypasses the color-preserving shell `exec` shape and can collapse the pinned 24-bit palette to Git Bash's 16 terminal colors. Run `node scripts/check-terminal-colour.mjs` first when color fidelity is in doubt; the first color block must differ from the terminal-palette cyan block.
+
+From the candidate checkout, pack once and install that tarball into a disposable prefix:
+
+```powershell
+npm ci
+npm run build
+npm pack --ignore-scripts --pack-destination .artifacts/manual-owned-ui
+npm install --prefix .artifacts/manual-owned-ui/install --ignore-scripts .artifacts/manual-owned-ui/<exact-tarball>.tgz
+```
+
+Use isolated A1 control state:
+
+```powershell
+$manualRoot = (Resolve-Path ".artifacts/manual-owned-ui").Path
+$env:A1_CONFIG_DIR = "$manualRoot\state\config"
+$env:A1_DATA_DIR = "$manualRoot\state\data"
+$env:A1_RUNTIME_DIR = "$manualRoot\state\runtime"
+$env:A1_DATABASE_PATH = "$manualRoot\state\data\control.sqlite3"
+```
+
+Run each installed launch form yourself:
+
+```powershell
+& ".artifacts/manual-owned-ui/install/node_modules/.bin/a1.cmd"
+& ".artifacts/manual-owned-ui/install/node_modules/.bin/a1.cmd" pi
+```
+
+Both commands use the same A1-owned rendering and input pipeline. Bare `a1` enables A1-owned screens. `a1 pi` withholds those screens and reads the ordinary Pi profile. Confirm that files created through `/settings`, `/login`, sessions, and resource directories remain under the selected profile root.
+
+Physical automation is not part of this repository baseline. Future certification tooling may run only on dedicated disposable workers or VMs with exclusive test desktops, never on this workstation.
+
+## Compare bare A1 with `a1 pi`
+
+Use the same terminal, working directory, dimensions, environment, and equivalent profile resources. Bare A1 and the comparison profile intentionally use separate profile roots.
+
+- [ ] Startup resources, logo, notices, spacing, editor, and footer match.
+- [ ] Text, Unicode, emoji, styles, cursor, and layout match.
+- [ ] Rapid typing has no visible delay or dropped or duplicated characters.
+- [ ] Ctrl+C, Ctrl+P, arrows, paste, focus, dialogs, mouse, and wheel behave correctly.
+- [ ] Selection, copy, clipboard, scrollback, and resize behave correctly.
+- [ ] Normal and error exits return a usable parent prompt.
+- [ ] Parent typing, cursor movement, Backspace, Delete, and submission work after exit.
+
+### Setting-controlled visual matrix
+
+Use equivalent values in bare A1 and the Pi comparison profile. Exercise both a wide frame and a narrow frame that forces wrapping/clipping.
+
+- [ ] `/settings`: selected cursor, label and value accent; unselected values muted; descriptions and hints dim; search uses `> ` with inverse cursor; scalar menus, numeric controls, warning-parts dialog, deferred notice, failed write, section spacing, clipping, and hidden-entry absence match their pinned semantic roles.
+- [ ] Transcript: toggle images and image width, thinking level/visibility, Mermaid mode, output padding, cache notices, warnings, auto-compaction, queue modes, command autocomplete, provider timeout/retry/error, and changelog collapse. Existing and streaming blocks must re-render without focus, selection, scroll, or queued-work loss.
+- [ ] Trust startup: from an undecided project, compare selected Trust/Do not trust rows, arrow navigation, Enter, Escape/Ctrl+C, clearing, cursor state, and restoration. No project extension/theme/prompt/skill may run before selection, and a fail-closed diagnostic must appear once on the restored parent rather than above a blank fullscreen frame.
+- [ ] Terminal lifecycle: toggle hardware cursor, clear-on-shrink, and terminal progress; resize smaller/larger; open/close selectors; select and copy transcript text; verify no duplicate rows, stale OSC progress, leaked mouse mode, misplaced cursor, or broken parent input.
+- [ ] Images: in Kitty or iTerm2 verify inline width and clipping; in Windows Terminal verify the textual fallback and absence of image protocol bytes without hiding `showImages`.
+- [ ] Fullscreen exit `transcript`: verify the parent is restored before styled user, assistant Markdown, thinking, tool, notice, warning, error, and spacing rows are printed. No overlay, draft, animation, scrollbar, or inline-image payload may appear.
+- [ ] Fullscreen exit `resume-hint`: verify only dim `To resume this session:` plus `a1 --session <compact-id>` is printed for the default directory. A custom directory must place quoted `--session-dir <dir>` before `--session`; the raw default `.jsonl` path must never print.
+
+Record acceptance with:
+
+```text
+A1 commit/tarball:
+Pi package: @earendil-works/pi-coding-agent 0.84.2
+OS/version:
+Terminal/version:
+Terminal dimensions (wide/narrow):
+Image protocol result:
+Settings values exercised:
+Outcome and any declared substitutions:
+```
+
+Report failures with bare-versus-comparison behavior, platform and terminal versions, exact command, dimensions, settings values, reproducibility, and optional manually captured evidence.
+
+For recovery, use `a1 pi`; do not use the removed `a1 ui` command. Manual acceptance can authorize an exact uncertified development preview after non-desktop gates pass. It does not certify stable presentation parity or platform support.

package/docs/manual-pi-boundary-candidate.md

@@ -21,12 +21,11 @@ Use the exact generated filename if wildcard expansion is unavailable.
 1. **Bare owned UI:** run `& $Candidate`. Confirm startup, typing, submission, transcript streaming, selector focus, mouse/keyboard scrolling, and ordinary shutdown.
 2. **Extension surfaces:** in bare UI use `/reload`, then exercise configured extension notification, select, confirm, input, editor, replacement custom surface, and overlay custom surface. Confirm cancellation restores editor focus.
 3. **Vanilla oracle:** run `& $Candidate pi`. Confirm untouched Pi uses the ordinary `~/.pi/agent` profile and does not show owned-UI or workspace surfaces.
-4. **Isolated profile:** run `& $Candidate sandbox`. Confirm Pi uses `~/.a1/sandbox` and starts with project approval disabled for that run.
-5. **Resize and input:** while each mode is active, narrow and widen the terminal, enter Unicode and multiline text, use history/navigation keys, and scroll in both directions.
-6. **Shutdown:** exit normally, then repeat and use Ctrl+C during work. Confirm the parent prompt remains usable and no child remains attached.
-7. **Recovery:** after any owned-UI failure, run `& $Candidate pi`; confirm the vanilla oracle remains available. Restart bare UI and confirm its normal profile remains intact.
+4. **Resize and input:** while each mode is active, narrow and widen the terminal, enter Unicode and multiline text, use history/navigation keys, and scroll in both directions.
+5. **Shutdown:** exit normally, then repeat and use Ctrl+C during work. Confirm the parent prompt remains usable and no child remains attached.
+6. **Recovery:** after any owned-UI failure, run `& $Candidate pi`; confirm the vanilla oracle remains available. Restart bare UI and confirm its normal profile remains intact.
 
-Do not remove `~/.a1/agent`, `~/.pi/agent`, or `~/.a1/sandbox` during this checkpoint.
+Do not remove `~/.a1/agent` or `~/.pi/agent` during this checkpoint.
 
 ## Verdict recording
 

package/docs/manual-terminal-colour-check.md

@@ -29,9 +29,10 @@ leave the launch without a terminal on its input; the launcher says so and stops
 rather than opening a session that closes as it starts. Running `scripts/dev`
 from the shell is the direct path.
 
-A directly launched `node scripts/start-local.mjs` under Git Bash does not, and
-neither does a directly launched `node …/pi/dist/cli.js`: the collapse belongs to
-the launch, not to either application.
+A directly launched `node scripts/development/dev-launch.mjs` or
+`node scripts/development/start-local.mjs` under Git Bash does not, and neither
+does a directly launched `node …/pi/dist/cli.js`: the collapse belongs to the
+launch, not to either application.
 
 ## Checking a terminal