@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

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,79 @@
+# 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`.
+- [ ] Bare A1 quit (`/quit` and the second `Ctrl+C`): the configured quit effect plays over the last frame on the alternate screen, the terminal is restored once, and the parent shows only its earlier scrollback plus the dim `To resume this session:` hint. No frame rows, transcript rows, editor box, or footer may remain. With `/settings` → Quit → Effect set to `off`, the leave is immediate and the parent output is identical.
+- [ ] Fullscreen exit `transcript` (`a1 pi` only): 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` (`a1 pi`) and bare A1: 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
 

package/docs/openspec-archive-automation.md

@@ -0,0 +1,259 @@
+# Atomic OpenSpec delivery and legacy archival
+
+New OpenSpec deliveries use one ordinary development pull request from draft planning through implementation, validation, acceptance, specification synchronization, and archival. The only integration action is an authorized maintainer's manual merge. Automation never auto-merges implementation-bound work and never creates a version-3 acceptance or archive follow-up PR.
+
+Unrelated standalone documentation remains separate: a non-draft unassociated PR changing only `openspec/**`, `docs/**`, and/or root `README.md` retains the existing CI-gated automatic route. A new active change, implementation association, malformed lifecycle data, or mixed path keeps the manual hold.
+
+Version-1 and version-2 deliveries and their existing comments, acceptance PRs, archive PRs, receipts, retries, and bounded catch-up remain supported under [Legacy delivery](#legacy-delivery). Do not silently convert an in-flight legacy delivery.
+
+## Version-3 lifecycle
+
+1. **Draft plan:** create one normally named branch/PR such as `feature/...`, `fix/...`, or `chore/...`. Start the body with `## Proposal`, use it for one or two sentences of intent, follow it with `## Implementation` for the concrete planned work, omit quoted phase lines and routine validation command lists, and keep machine linkage under final collapsed `Automation`. Keep it draft and include only planning artifacts until the maintainer approves the plan and explicitly requests implementation.
+2. **Same-PR implementation:** continue after explicit approval in the same worktree, branch, history, draft PR, and phase-free body. Reconcile approved refinements in proposal, design, deltas, and tasks before corresponding code edits.
+3. **Complete evidence:** finish implementation, required tests/evidence, substantive tasks, and explicit known-gap disposition. CI success is objective evidence, not acceptance.
+4. **Plain acceptance list:** keep the body phase-free and add final `## Acceptance` with one to three concise implementation-specific behavior-and-result bullets. Do not use checkboxes, generic review/CI/approval/archive statements, URLs, mentions, or automated-test inventory.
+5. **Ready and automated finalization:** mark the PR ready. The trusted `OpenSpec finalization` workflow reconciles current `develop`, conservatively synchronizes all deltas, moves the active change into its dated archive, stages the conditional acceptance manifest, commits that to the same branch with the archive App identity, and writes the emitted paths into the body's implementation fence. Running the [finalization command](#finalization-command) locally first is optional and yields the same bytes.
+6. **Validate:** one normal exact-head workflow validates the finalized head: implementation, synchronized specs, archive, manifest, tasks/evidence, exact PR-body list, and every selected product/governance scope before emitting the stable protected aggregate. A new commit or acceptance-list change re-finalizes automatically when needed and requires full renewed validation; no lifecycle body edit or second workflow run is required.
+7. **Manual merge accepts:** after the stable protected aggregate succeeds, an authorized human reviews and manually merges the exact validated head. That single action means the listed scenarios are accepted and explicitly authorizes integration. Auto-merge, merge queue, Apps, bots, and documentation reconciliation are forbidden.
+8. **Verify and clean:** trusted post-merge policy derives `Archived` and reports `accepted-and-archived` from committed bytes and immutable GitHub provenance without editing the accepted PR body. It publishes no lifecycle branch or PR. Shared exact-head remote cleanup may delete the unchanged topic ref; local cleanup remains separately ownership-controlled: the agent parks the worktree with `handoff` at step 7, and the next session's `sweep` removes it once the merge, archive, and remote-ref evidence verify (see [local cleanup](local-worktree-cleanup.md)).
+
+The implementation, synchronized canonical specs, conditional acceptance record, and archive therefore reach `develop` atomically. Closing the PR unmerged integrates none of them.
+
+## Draft PR body
+
+The first screen should separate purpose from delivery detail, not foreground CI mechanics. Distill `Proposal` into one or two sentences answering why the PR exists, then put two to five concrete points under `Implementation` answering what it will deliver:
+
+```markdown
+## Proposal
+
+Replace the multi-PR OpenSpec handoff with one manually merged development PR while preserving standalone documentation automation.
+
+## Implementation
+
+- Keep planning and implementation in the same draft PR.
+- Integrate implementation, synchronized specs, acceptance, and archive atomically.
+- Preserve standalone documentation auto-merge while forbidding implementation auto-merge.
+
+## Automation
+
+<details>
+<summary>Used by CI to link this PR to its OpenSpec change</summary>
+
+<!-- the openspec-implementation fence goes here -->
+
+</details>
+```
+
+Do not add a quoted phase line or a routine `Validation` section listing commands to an initial draft. Actual validation results belong in CI and the eventual implementation handoff. Continue with the same phase-free body after approval. When implementation is complete and ready for required tests, use this visible order:
+
+```markdown
+## Proposal
+
+<!-- one or two sentences explaining why the PR exists -->
+
+## Implementation
+
+<!-- concrete implementation bullets -->
+
+## Acceptance
+
+<!-- one to three plain behavior-and-result bullets -->
+
+## Automation
+
+<details>
+<summary>Used by CI to link this PR to its OpenSpec change</summary>
+
+<!-- the finalized openspec-implementation fence goes here -->
+
+</details>
+```
+
+Keep acceptance absent during proposal review so unfinished intent is not mistaken for final acceptance criteria. The finalization workflow rewrites only the implementation fence; keep the rest of the phase-free body unchanged through exact-head validation, maintainer review, and authorized manual merge. The same workflow run validates its finalized delivery record and applicable product/governance scopes before the stable protected aggregate succeeds. Do not add a lifecycle body edit or start a second validation run. After manual merge, trusted verification derives `Archived`; do not rewrite the accepted body.
+
+## Version-3 implementation metadata
+
+The initial draft uses the existing metadata fence:
+
+````markdown
+## Automation
+
+<details>
+<summary>Used by CI to link this PR to its OpenSpec change</summary>
+
+```openspec-implementation
+{
+  "version": 3,
+  "change": "example-change"
+}
+```
+
+</details>
+````
+
+After finalization, replace it with the exact emitted paths:
+
+````markdown
+## Automation
+
+<details>
+<summary>Used by CI to link this PR to its OpenSpec change</summary>
+
+```openspec-implementation
+{
+  "version": 3,
+  "change": "example-change",
+  "archive": "openspec/changes/archive/2026-09-15-example-change/",
+  "acceptanceManifest": "openspec/changes/archive/2026-09-15-example-change/acceptance.md"
+}
+```
+
+</details>
+````
+
+Version 3 forbids `specificationPr` and `archivePreparationTasks`. Both final paths must be absent for a draft or present and mutually consistent for a finalized candidate. Unknown fields, duplicate fences/JSON keys, unsafe paths, mismatched dates/change identities, and partial finalization fail closed.
+
+## Acceptance list
+
+Use plain bullets:
+
+```markdown
+## Acceptance
+
+- Conservative fallback runs all required validation.
+- Failed or stale evidence blocks integration.
+- Finalized specs and archive match the implementation.
+```
+
+The committed conditional manifest contains the same ordered text. Trusted policy validates membership but never checks or edits it and never claims that the scenarios passed. Manual merge is the acceptance decision; no acceptance comment, checkbox edit, review-approval requirement, JSON edit, acceptance PR, archive PR, or later command is needed.
+
+If the body list changes, candidate validation reruns and compares it with the committed manifest. If the head changes, all prior exact-head CI is stale. If only the body changes to disagree with the manifest, integration remains blocked until the list and committed candidate agree again. No lifecycle body edit is needed after green CI.
+
+## Automated finalization
+
+The `OpenSpec finalization` workflow (`.github/workflows/openspec-finalization.yml`) runs on `pull_request_target` for `synchronize`, `ready_for_review`, `reopened`, and `edited` events of every non-draft PR targeting `develop`, one event at a time per PR. It checks out default-branch policy, installs the pinned tooling without hooks, and runs `scripts/governance/publish-openspec-finalization.mjs --pr <n>`; the PR head enters that process only as the `openspec/` tree the pinned OpenSpec engine reads. Drafts, closed, legacy, and unassociated PRs are skipped. For a version-3 candidate it reconciles the head to its finalized form:
+
+- **Active and current:** ordinary finalization with today's UTC date; one `docs(openspec): finalize <change>` commit.
+- **Finalized, valid, and current:** nothing is pushed; the run reports `already-finalized`.
+- **Finalized but drifted:** a later commit edited the archived tasks, evidence, design, or deltas, or the acceptance list changed. Finalization reruns from the archived form under the same archive date; one `docs(openspec): refinalize <change>` commit replaces the manifest and resynchronized specs.
+- **Behind `develop`:** a restore commit returns the archive to its active form with the merge-base's spec bytes, a merge of `develop` follows, and finalization runs against the new tip. A merge conflict outside `openspec/` stops the run with `finalization-merge-conflict`; rebase or merge `develop` yourself and push.
+
+The commit is pushed with a lease on the head the run read, so a developer push in between makes the run report `retry` and the next event finishes the work. Only after the push does the workflow `PATCH` the body fence, and only when the body is unchanged since it was read. The workflow's own push and body edit trigger further runs that report `already-finalized`. Every pushed commit is either a merge of the exact `develop` tip or confined to the change's active path, its archive path, and its declared canonical specs.
+
+Because the branch gains commits from the archive App, pull before pushing. A rebase that drops them is harmless: the next push is reconciled from whatever the head contains. Do not revert a finalization commit to make a fix; push the fix and let the workflow re-finalize. When the workflow fails, its summary names the finalization code (`tasks-incomplete`, `acceptance-*`, `delivery-known-gaps`, `openspec-operation`, `finalization-merge-conflict`, ...), nothing is pushed, and `Finalized delivery validation` on the unfinalized head reports that automated finalization is pending.
+
+## Finalization command
+
+The local command remains available for inspection or when a developer prefers to finalize before marking the PR ready; the workflow then verifies the head and pushes nothing. It has inspection mode by default and an explicit `--write` mode. It never commits, pushes, edits GitHub, marks a PR ready, or merges. Use a temporary body file so the operation can update exact version-3 paths without mutating remote PR state:
+
+```bash
+git fetch origin develop
+git rebase origin/develop
+gh pr view <pr> --json body --jq .body > "$TMPDIR/openspec-pr-body.md"
+node scripts/governance/finalize-openspec-delivery.mjs \
+  --change example-change \
+  --repository owner/repo \
+  --pr <pr> \
+  --date YYYY-MM-DD \
+  --target "$(git rev-parse origin/develop)" \
+  --body-file "$TMPDIR/openspec-pr-body.md"
+```
+
+Inspect the reported paths. Then rerun with `--write` and update the existing PR body from the emitted file:
+
+```bash
+node scripts/governance/finalize-openspec-delivery.mjs \
+  --change example-change \
+  --repository owner/repo \
+  --pr <pr> \
+  --date YYYY-MM-DD \
+  --target "$(git rev-parse origin/develop)" \
+  --body-file "$TMPDIR/openspec-pr-body.md" \
+  --write
+gh pr edit <pr> --body-file "$TMPDIR/openspec-pr-body.md"
+```
+
+Use repeated `--known-gap "exact disposition"` only for an actually reviewed explicit gap. Gaps remain visible in the committed manifest and do not become test results. Missing or ambiguous disposition blocks finalization.
+
+The operation validates the active change strictly, requires complete substantive tasks, runs the pinned OpenSpec archive/synchronization engine in isolation, verifies the resulting canonical specs, retains every archive artifact, computes deterministic content digests, writes `acceptance.md`, and applies only the allowed OpenSpec diff. Repeating it against identical finalized inputs is verification-only and byte-stable.
+
+Before a first finalization, canonical specs must still equal the selected target. On an already finalized head the command re-finalizes from the archived form: it resets the synchronized specs to the target's bytes, reapplies the deltas, and rewrites the manifest under the same archive path, reporting `refinalized` (or `would-refinalize` without `--write`). If `develop` advances, merge or rebase onto it and rerun; the archive engine, not a hand edit, must produce the synchronized spec and archive copy.
+
+## Conditional acceptance and derived receipt
+
+`acceptance.md` truthfully says its verdict activates only when the containing exact head is manually merged by an authorized human after required current-head checks. Its `openspec-delivery` block records stable pre-merge facts:
+
+- schema version, repository, change, and source PR;
+- archive and manifest paths and finalization date;
+- reviewed target/spec baseline;
+- ordered acceptance scenarios;
+- archive, canonical-spec, task, and evidence digests; and
+- explicit known-gap dispositions.
+
+It does not predict source head, merge commit, merger, or merge time. The PR head contains the manifest, so required CI binds those bytes without a recursive self-hash. After merge, the shared reader combines the manifest with immutable GitHub source head, successful required run, authorized human actor, absence of automatic/queue/App provenance, merge commit/time, and `develop` ancestry. That derived result is the durable version-3 receipt used by audit and cleanup.
+
+Unavailable, stale, automatic, unauthorized, conflicting, or contradictory provenance produces `invalid-provenance`/`blocked`, not acceptance. Post-merge code does not repair it by pushing `develop` or publishing another PR.
+
+## CI and automation ownership
+
+Normal Development CI remains complete for the implementation. An archive-shaped final diff does not select documentation-only validation because the authoritative version-3 association remains implementation-bound. The trusted acceptance-policy job validates finalization from base-controlled policy while ordinary impact selection retains all applicable product and governance owners. A ready head that still holds the active change fails that job with an `Awaiting automated finalization` notice pointing at the finalization workflow; the head the workflow pushes receives its own complete validation, and `Development validation` cancels the superseded run.
+
+`pull_request` body edits rerun required CI. The ordinary finalized phase-free run exposes the stable protected aggregate directly; it does not wait for a lifecycle body edit. Documentation auto-merge's trusted owner also reevaluates lifecycle association and disables any armed merge. Every publication entry point explicitly refuses version 3.
+
+The OpenSpec archive workflow remains default-branch trusted. For version 3 it uses read-only contents, PR, and Actions access to report the integrated result; App credentials are unnecessary and are not minted for post-merge verification. For legacy candidates it retains its existing scoped App publication behavior. The OpenSpec finalization workflow is the one version-3 user of the archive App: it mints a short-lived installation token with `contents: write` and `pull_requests: write`, pushes only to the candidate's own branch under a lease, edits only the body fence, and revokes the token when the run ends.
+
+## Status and audit
+
+Read-only inspection remains:
+
+```bash
+GH_TOKEN="$(gh auth token)" node scripts/governance/reconcile-openspec-archive.mjs --dry-run --pr <implementation-pr>
+```
+
+For version 3, status distinguishes `needs-finalization`, `ready-for-manual-merge`, `accepted-and-archived`, `closed`, `blocked`, and `invalid-provenance`. A successful workflow invocation does not imply acceptance while the PR is open. Dry run never mutates refs, PRs, body text, tasks, evidence, specs, or acceptance.
+
+Scheduled scans continue to serve legacy catch-up. Version-3 candidates are verification-only and do not consume publication slots or block the legacy queue.
+
+## Cleanup
+
+After version-3 merge, verify:
+
+- the source PR is merged with the exact reviewed head by an authorized human;
+- required exact-head CI succeeded;
+- current `develop` descends from the merge;
+- the active change is absent;
+- the declared archive, conditional manifest, and synchronized specs match their digests; and
+- the unchanged remote topic ref is absent.
+
+Only then shall the owning agent invoke the exact-candidate `complete` operation documented in [local cleanup](local-worktree-cleanup.md) from the primary checkout. The command owns registration/release, repository-generated disposables, one bounded evidence pass, non-force worktree removal, and unchanged local-ref cleanup; agents do not manually delete generated content, worktrees, or branches. Version 3 uses the implementation PR as both source and candidate and does not wait for nonexistent acceptance/archive PRs.
+
+Closing an unmerged PR does not by itself authorize local or remote deletion. After explicit candidate-specific rejection and remote-deletion confirmation, the repository-owned local `discard` command may compare-and-delete only that closed-unmerged PR's exact unchanged same-repository unprotected topic ref, then apply the ordinary non-force local safeguards. Automatic remote cleanup remains merge-only and never touches local worktrees.
+
+## Legacy delivery
+
+Version 1 retains `specificationPr` and authorized exact-head comment-backed acceptance. Version 2 retains the same-PR planning/implementation link, final `## Acceptance checks` handoff, generated `#<source>(accept): ...` checkbox PR, verified authorized manual acceptance merge, and generated CI-gated archive PR. Existing records remain immutable and readable.
+
+Legacy reconciliation may create/reuse only its established acceptance/archive branches and PRs, uses bounded catch-up/retry, preserves human edits, fails closed on missing evidence or conflicts, and never treats version 3 as publishable. Its App remains repository-scoped without administration/ruleset bypass; write credentials execute only trusted default-branch policy and never PR-head code.
+
+A closed legacy follow-up requires targeted retry authorization. Existing valid acceptance comments and PR receipts are not rewritten. Legacy local cleanup continues to wait for implementation, acceptance where applicable, and archive integration.
+
+## First version-3 canary
+
+This bootstrap policy itself finishes under deployed version-2 authority. The first isolated version-3 canary must record live evidence of:
+
+- draft planning remaining unmerged;
+- explicit plan approval and same-PR implementation;
+- automated current-target finalization and exact-head CI;
+- authorized human manual merge with plain acceptance scenarios;
+- integrated canonical specs/archive and no generated acceptance/archive PR;
+- read-only `accepted-and-archived` verification and exact-head branch cleanup;
+- stale head/body/base, incomplete tasks/evidence, malformed manifest, and automatic-merge refusal fixtures; and
+- an unrelated standalone spec/docs PR retaining auto-merge.
+
+Unit tests or API success alone are not live acceptance. Until this evidence exists, version 3 is deployable but documented as awaiting its operational canary.
+
+## Disable or roll back
+
+Before a version-3 merge, disable new version-3 authoring and continue using legacy version 2. After a version-3 merge, preserve its integrated archive and provenance and use an ordinary explicit corrective PR. Never direct-push a rewritten receipt, delete historical evidence, relax branch protection, or reinterpret an automatic merge as human acceptance.
+
+Disabling the OpenSpec archive workflow stops legacy publication and version-3 post-merge reporting, but does not change existing acceptance records, documentation auto-merge, remote branch cleanup, or release authority.

package/docs/repository-governance-live-acceptance.md

@@ -0,0 +1,77 @@
+# Repository governance live acceptance
+
+## Implementation lifecycle
+
+- PR #165 was manually squash-merged by `timurproko` from validated head
+  `45aab61c5e4568d3d26dc970f76e9ec86918f323` to `develop` commit
+  `e4cdc67555e9f25d03f251be19baa8fc446ac313`.
+- Cleanup run `33185942656` used trusted `develop` policy with `contents: write` only
+  and reported `already-absent`; the implementation branch remained absent.
+- The read-only live governance report matched every declared field after merge.
+
+## Acceptance defect and correction
+
+- Initial OpenSpec probe PR #166 automatically squash-merged validated head
+  `c30c0a091a6a6a727057befcdd775422988be382` to
+  `f8d60080cfd9925b33a19a5d40c707637ac00b08`, but GitHub suppressed the recursive
+  close-event workflow because integration was authored with `GITHUB_TOKEN`.
+- Its exact unchanged branch remained, proving the first implementation incomplete.
+  The branch was manually deleted only after its expected SHA and lack of an open PR
+  were reverified.
+- Corrective PR #167 was manually squash-merged from validated head
+  `3a09042386df2501accc1eec3b424b94ae84daa4` to
+  `e8d639985a811f01cd5daeb027db5069d1724596`. Cleanup run `33188206793`
+  succeeded with `already-absent`.
+
+## Automatic OpenSpec acceptance
+
+- PR #168 contained only `openspec/**` paths.
+- Development validation run `33188285639` passed for exact head
+  `6678d9237ca7c4109beaed0d97d5fb1183fe5f97` without product tests.
+- `github-actions` automatically squash-merged it to
+  `c2fa730a4b070f9f6717329c24158def5c766f11`.
+- Trusted documentation reconciliation run `33188329123` reported `deleted` for the
+  same expected head SHA, and the remote branch was verified absent.
+
+## Automatic root README acceptance
+
+- PR #169 changed only root `README.md`.
+- Development validation run `33188400573` passed for exact head
+  `165c5159031d80059c4d93c36c6d10113ec7ba8e` without product tests.
+- `github-actions` automatically squash-merged it to
+  `0180088a42b7cdacaf84ec66ff5a87be1a697155`.
+- Trusted documentation reconciliation run `33188434277` reported `deleted` for the
+  same expected head SHA, and the remote branch was verified absent.
+
+## Mixed-path manual acceptance
+
+PR #170 combined this evidence file outside the exact automatic allowlist with an
+OpenSpec task update. Development validation run `33188542485` passed for exact head
+`b95bdbf08ad6db76c5fab2bfca254026a3c4bcc1` without product tests. Auto-merge
+remained disabled and the pull request remained open and mergeable until `timurproko`
+manually squash-merged it to `6ab1e4d29b9edec8501bac774bc755e66240ea40`.
+Close-event cleanup run `33188616709` reported `already-absent`, and the remote branch
+was verified absent after the explicit merge.
+
+## Automatic maintained-documentation acceptance
+
+- Implementation PR #180 was manually squash-merged after required validation from
+  head `8f40bfaaa5e8410e77b1c9cc0667c62bc4c62d4b` to
+  `45a59a7b696d537a4dc8fe62000a60c20e504ab2`.
+- PR #181 changes only this maintained `docs/**` file and is the live acceptance
+  probe for the expanded allowlist.
+- Acceptance requires current-head documentation validation, automatic squash
+  integration without maintainer merge action, and exact-head remote branch cleanup.
+  Exact run and merge evidence is recorded with the completed OpenSpec change.
+
+## Advanced-ref refusal and final policy state
+
+The isolated mocked-GitHub fixture executed the production shared reconciler with
+expected SHA `1111111111111111111111111111111111111111` and advanced live SHA
+`2222222222222222222222222222222222222222`. It returned `refused` with reason
+`live branch advanced after merge` and issued zero DELETE requests. The bounded
+record is archived as `evidence/advanced-ref-refusal.json`.
+
+The final read-only live report matched all declared repository settings, Actions
+policy, security capabilities, environments, protected refs, complete rulesets, and
+workflow inventory with zero differences. No policy apply was run.