@timurproko/a1 0.1.8-dev.407 → 0.1.8-dev.436

package/docs/openspec-archive-automation.md

@@ -1,128 +1,246 @@
-# Automatic OpenSpec archival
+# Atomic OpenSpec delivery and legacy archival
 
-The archive workflow handles merged OpenSpec implementations, visible acceptance review, a daily 90-day catch-up, and targeted retries. When acceptance is missing, it creates or reuses `Accept: <change> — implementation #<number>`; only an authorized maintainer's verified manual merge of that exact record grants PR-backed acceptance. It then creates an OpenSpec-only archive PR, which existing documentation automation squash-integrates after real current-head CI. An open acceptance or archive PR is not completed acceptance or 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.
 
-Documentation CI installs only the pinned OpenSpec archive tool into runner temporary storage, not the repository dependency tree. Candidate validation selects that installation with `--tool-root`; the override is unavailable to publication and audit modes. The documentation job has read-only contents, PR, and Actions permissions; the existing merge owner also declares Actions read access for checking source validation.
+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.
 
-## One PR: specs, implementation, CI, validation, merge, archive, cleanup
+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.
 
-A new implementation-bound change starts as OpenSpec-only artifacts in one draft PR, not a plan merged ahead of its implementation. Planning requests authorize no code. The agent prepares the link below while opening that draft. After explicit plan approval and an implementation request, continue in the same worktree, branch, history, and PR; reconcile approved planning refinements before their code edits and include related product documentation there too.
+## Version-3 lifecycle
 
-Use this delivery sequence:
+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. **In-branch finalization:** reconcile current `origin/develop`, conservatively synchronize all deltas, move the active change into its dated archive, and stage the conditional acceptance manifest in the same branch.
+6. **Ready and validate:** mark the finalized PR ready without changing its body lifecycle marker because none exists. One normal exact-head workflow validates the 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, acceptance-list change, or advanced target 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.
 
-1. **Specs:** prepare and approve the plan in the draft PR. Planning does not authorize implementation by itself.
-2. **Implementation:** after explicit approval/request, implement in that same worktree, branch, history, and PR. Keep it draft while implementation is unfinished.
-3. **CI:** push the completed candidate and mark the PR **ready for review before running required CI**. Normal `ready_for_review`/`synchronize` events provide PR-visible test progress. Do not manually dispatch ordinary CI merely to keep the completed candidate draft and then run it again on readiness. Dedicated Full regression/native workflows remain separate required evidence where applicable.
-4. **Implementation review:** after applicable CI passes, obtain actual maintainer validation of the exact final head. Readiness, plan approval, and green CI are not acceptance or merge authorization. A changed candidate requires current-head CI and renewed review.
-5. **Implementation merge:** merge manually only after explicit authorization; implementation auto-merge stays disabled. This integrates code but does not invent post-merge archival acceptance.
-6. **Visible acceptance:** trusted automation creates or reuses one acceptance PR from exact source and CI evidence. Pending substantive tasks and unknown outcomes keep it draft/blocked. Reconcile only evidence-backed stale bookkeeping in that same PR. After its current-head CI passes, an authorized maintainer manually merges it; auto-merge is always forbidden. That merge records archival acceptance without a JSON comment or acceptance-of-acceptance PR.
-7. **Docs/specs auto-merge:** the verified acceptance merge resumes conservative synchronization and prepares the OpenSpec-only archive PR. Documentation automation merges that follow-up after its own required CI. Do not separately merge specs/docs or archive before implementation and acceptance integration.
-8. **Cleanup:** verify implementation, acceptance, and archive integration before removing retained local task/acceptance worktrees. Preserve ownership, clean-tree, and closed/unmerged safety checks. The owning agent performs eligible local cleanup or explicitly releases a registered checkout to the opt-in [local cleanup worker](local-worktree-cleanup.md); no always-running service is provisioned automatically. Hosted remote-branch cleanup remains independently gated on the corresponding PR's verified merge.
+The implementation, synchronized canonical specs, conditional acceptance record, and archive therefore reach `develop` atomically. Closing the PR unmerged integrates none of them.
 
-When a PR check fails, repair routine failures in its existing worktree, branch, and PR and repush; a separate proposal or PR is not required solely for the repair, including a narrowly scoped inherited failure. Preserve the tested behavior, assertions, coverage, and required checks, record the cause and validation, and obtain fresh current-head CI and renewed implementation review; post-merge acceptance remains separately recorded. Substantive new scope still requires clarification. Reclaim a registered released checkout before resuming work; a repair grants no live cleanup or merge authority.
+## Draft PR body
 
-The implementation, acceptance, and archive PRs each need their own CI because they carry different decisions and bytes. The redundant draft-dispatch-then-ready implementation run is what this sequence avoids. The documentation merge owner holds implementation-associated PRs, new active changes, and acceptance records/branches even if marked ready or their editable marker is removed. PR body edits trigger reconciliation and disable an excluded armed merge. Ordinary docs, standalone revisions to existing merged plans, and verified archive moves remain automatic under the exact path allowlist.
+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:
 
-## Normal implementation handoff
+```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
 
-The delivery agent adds one version-2 block to the initial draft PR description. It identifies the plan and implementation in that same PR, without `specificationPr`:
+<!-- 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. Keep the finalized 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": 2,
+  "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",
-  "archivePreparationTasks": { "recordEvidence": "7.1", "stageArchive": "7.2" }
+  "archive": "openspec/changes/archive/2026-09-15-example-change/",
+  "acceptanceManifest": "openspec/changes/archive/2026-09-15-example-change/acceptance.md"
 }
 ```
+
+</details>
 ````
 
-The minimal link is `{ "version": 2, "change": "example-change" }`. Version 2 verifies that the linked artifacts are present and identical in the accepted source and implementation merge; it never invents a separate specification PR. Omit `archivePreparationTasks` when no mechanical task mapping is needed. If used, the mapped task IDs must have exactly these descriptions:
+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
-- [ ] 7.1 Record verified implementation acceptance and merge evidence for archive preparation.
-- [ ] 7.2 Stage and verify delta synchronization and the archive move in an OpenSpec-only candidate.
+## Acceptance
+
+- Conservative fallback runs all required validation.
+- Failed or stale evidence blocks integration.
+- Finalized specs and archive match the implementation.
 ```
 
-All implementation, tests, CI, and manual-review tasks must be completed separately before acceptance. Never combine physical review or merge authorization into these mechanical tasks. An old mixed task is a blocker, not permission to tick unperformed work.
+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.
 
-After implementation merge, automation commits one version-1 JSON request at `openspec/acceptance/<change>/<source-head>.json` on `docs/accept-<change>-<source-pr>`. Its PR body shows the exact implementation head/merge, spec baseline, final-head source CI, recorded evidence, every original task and continuation line, unfinished work, known gaps, and this sentence: **Merging this PR records your acceptance.** It is a review record, not another proposal.
+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.
 
-A generated record expresses only the conditional decision `accept-on-manual-merge`; it never names a reviewer or claims the merge already occurred. Completed source tasks stay recorded. An unchecked substantive task remains pending until actual evidence is linked and its unchanged task identity is explicitly marked `evidenced`. Only the exact pure task `Record maintainer acceptance by manually merging the acceptance PR.` may use `signoff-on-merge`. Implementation, test, live/physical review, mixed, unknown, or known-gap work cannot use that shortcut. Archive-preparation tasks retain their existing mechanical handling.
+## Finalization command
 
-The acceptance PR starts draft whenever source CI or substantive evidence is incomplete. Edit the record on its existing bot-owned branch without unrelated files; automation preserves reviewer edits and makes a complete draft ready on a later synchronize/scheduled/targeted pass. Closing it without merging records no acceptance; replacement requires an authorized targeted retry. Never enable auto-merge. Reserved paths, branch identity, complete diff, both rename names, and authoritative base/head state preserve the manual hold even if title, label, or body metadata is removed.
+Finalization 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:
 
-Candidate CI checks the exact single added record using trusted base policy and read-only permissions; it does not execute candidate scripts or wait for its own result. After manual merge, the reader separately verifies exact committed bytes, current-head CI including the acceptance check, source identities, develop ancestry, write/maintain/admin human merger, and absence of automatic/App/merge-queue provenance. Archive evidence retains acceptance PR/head/merge, record digest, author and reviewed task reconciliation. Acceptance integration alone never authorizes local deletion.
+```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"
+```
 
-Existing valid version-1 `openspec-acceptance` comments remain supported. Their author still needs repository write/maintain/admin authority, and edited, contradictory, revoked, stale, known-gap, or current-head conflicts fail closed. Automation never creates a synthetic comment or chooses between conflicting comment-backed and PR-backed authority.
+Inspect the reported paths. Then rerun with `--write` and update the existing PR body from the emitted file:
 
-The code PR still requires explicit manual merge authorization. After a verified acceptance merge, no additional archive command is needed for an eligible change. Planning-only and archive PRs never count as implemented changes. Existing `acceptance.md` files require manual reconciliation rather than being silently overwritten.
+```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"
+```
 
-## Rejection, standalone docs, and legacy migration
+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.
 
-- **New draft rejected:** if `example-change` never merged, close its PR. Neither its plan nor code lands on `develop`, and no main-branch reconciliation or completed-change archive is required. Closing alone does not authorize deleting an unmerged branch or dirty worktree; follow separate cleanup approvals.
-- **Legacy merged plan rejected:** preserve its historical merge. Obtain an explicit reconciliation disposition; do not claim successful implementation or archive it as complete.
-- **Legacy implementation continues:** keep the existing PR (for example #376 following #362), or create an isolated implementation stream only if none exists and implementation is explicitly requested. Retain the original version-1 link; the historical specification merge and ancestry are still verified. Unknown versions and version-2 links containing `specificationPr` are rejected.
-- **Standalone docs/revision:** an unassociated non-draft README/docs PR or revision of an already-present active change retains the usual CI-gated automatic path. Renaming an archive into a new active plan establishes a hold; moving a completed active change into its archive does not.
+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.
 
-Legacy link example:
+Before finalization, canonical specs must still equal the selected target. If `develop` advances, rebase/reconcile and regenerate. To refine a finalized but unmerged change, restore the active artifacts with ordinary branch history, update plan/code coherently, and rerun finalization; never hand-edit only the synchronized spec or archive copy.
 
-````markdown
-```openspec-implementation
-{ "version": 1, "change": "legacy-change", "specificationPr": 123 }
-```
-````
+## Conditional acceptance and derived receipt
 
-The repository-owned [change-delivery skill](../.agents/skills/change-delivery/SKILL.md) follows these boundaries without changing external or globally installed skills. This bootstrap still needs live evidence of the new draft/approval/same-PR/refinement lifecycle, a ready-but-unimplemented plan remaining held, rejection without archival, an ordinary docs control, and accepted merge through automatic archival. Unit tests are not that evidence.
+`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:
 
-## One-time publication setup
+- 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.
 
-Provisioning is a separate maintainer-approved operation, not performed by installing or running the script.
+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.
 
-1. Create and install a repository-scoped GitHub App for this repository, without administration permissions or ruleset bypass.
-2. Grant repository contents and pull-request read/write permissions. The workflow's ordinary token reads contents, PR metadata, and Actions validation; the App token is restricted to publication and status comments.
-3. Set repository Actions secrets `OPENSPEC_ARCHIVE_APP_ID` and `OPENSPEC_ARCHIVE_APP_PRIVATE_KEY`. Do not paste keys into PRs, source, reports, or acceptance evidence.
-4. Verify trusted default-branch deployment and run a read-only audit before the isolated live lifecycle test.
-5. Record a real App-authored archive PR triggering ordinary CI, automatic protected squash integration, and exact-head branch cleanup before accepting live operation.
+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.
 
-The script mints and revokes a short-lived installation token. It does not publish with `GITHUB_TOKEN`: GitHub can suppress the resulting PR events, leaving a PR without required CI. Missing App setup blocks mutation and does not relax protection. No extra merge owner, status spoofing, or automatic repository-settings application is introduced.
+## CI and automation ownership
 
-## Audit and retry
+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.
 
-From a dependency-installed checkout, run a read-only audit using existing GitHub CLI authentication:
+`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.
 
-```bash
-GH_TOKEN="$(gh auth token)" node scripts/governance/reconcile-openspec-archive.mjs --dry-run
-```
+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 legacy candidates it retains its existing scoped App publication behavior.
+
+## Status and audit
 
-To inspect one implementation PR, including one older than the scheduled window:
+Read-only inspection remains:
 
 ```bash
-GH_TOKEN="$(gh auth token)" node scripts/governance/reconcile-openspec-archive.mjs --dry-run --pr 123
+GH_TOKEN="$(gh auth token)" node scripts/governance/reconcile-openspec-archive.mjs --dry-run --pr <implementation-pr>
 ```
 
-These commands do not launch the product UI and do not require a product build. They never mutate remote refs, PRs, comments, source specs/tasks, or persistent scan checkpoints. Disposable local staging verifies the proposed archive; the audit report is written to `.artifacts/openspec-archive/report.json`.
+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
 
-For authorized publication or retry, use the **OpenSpec archive** Actions dispatch. Keep `dry_run` enabled for inspection. Set a specific PR and `retry_closed` only when deliberately authorizing replacement of its closed/unmerged archive PR. Closing an archive PR otherwise stops automatic recreation.
+After version-3 merge, verify:
 
-## Outcomes and bounds
+- 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.
 
-- **awaiting-evidence**: an acceptance PR exists but lists missing CI, substantive tasks, or actual outcomes; update that same request without fabricating results.
-- **awaiting-manual-acceptance-merge**: the validated acceptance request needs explicit maintainer review and manual merge.
-- **eligible**: accepted evidence and isolated archive staging passed; dry-run did not publish.
-- **accepted-archive-blocked**: acceptance is verified, but tasks, synchronization, archive CI, or publication still blocks archival.
-- **blocked**: a named evidence/task/spec/setup/ownership/conflict problem requires attention.
-- **pending**: archive PR exists; current-head CI and automatic merge are not yet complete.
-- **already-archived**: merged archive identity and retained evidence were verified.
-- **deferred**: the queue or scan budget prevented work this run.
-- **unlinked**: no explicit implementation metadata; not presumed accepted or archived.
+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.
 
-Only one automatic archive PR is outstanding at a time. Runs never wait on CI. A failing pending PR blocks the queue until fixed or explicitly closed; neither a rerun nor a successful old head bypasses its required checks. Human-edited branches and unrelated paths are preserved.
+Closing an unmerged PR does not authorize local or remote deletion. Remote cleanup deletes only the exact unchanged same-repository unprotected topic ref and never touches local worktrees.
 
-Catch-up scans a fixed 90-day window, up to 500 PRs per pass, with a 10-minute workflow budget and one publication per run. A small versioned cursor resumes unfinished windows; reports and cursors are retained for 14 days. Missing/expired cursors restart a bounded scan, not an assumed complete audit. Older PRs remain targetable. Exceptionally dense search buckets or incomplete GitHub search results are explicit blockers rather than silent truncation.
+## Legacy delivery
 
-Known-gap archival remains a separately authorized manual path. The existing backlog is not bulk-approved when automation starts. Local worktree cleanup remains local: the owning agent can release an explicitly registered checkout to the separately enabled [local reconciler](local-worktree-cleanup.md) after stopping its use. The reconciler waits for verified archive integration and remote-ref absence, checks ownership and all local content, and never force-discards dirty work. Unregistered or unreleased worktrees remain untouched.
+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;
+- 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
 
-Disable the **OpenSpec archive** workflow or revoke its App publication credentials to stop new request/archive publication. Preserve authoritative acceptance records, their manual auto-merge hold, active changes, and open review/archive PRs. Do not delete receipts, undo synchronized specs, or modify repository rulesets merely to stop automation. Readers must remain compatible with existing PR-backed and legacy comment receipts or fail closed. Existing documentation auto-merge and remote branch cleanup remain independently governed.
+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/validation.md

@@ -0,0 +1,62 @@
+# Validation ownership and evidence
+
+Development validation computes one exact base/head selection with:
+
+```bash
+npm run select:validation-impact -- --base <full-base-sha> --head <full-head-sha> --output .artifacts/validation/impact.json
+```
+
+The versioned `config/validation-ownership.json` registry maps stable product and test path groups to a mandatory PR core, affected unit tests, resource-sensitive tests, and integration owners. The initial coarse owners are UI/rendering, launch/startup, release/package/update, Pi, native containment, image/history, governance, and shared product inputs. Each integration owner in `config/integration-owners.json` declares `pull-request` or `exhaustive` cadence. A changed pull-request test selects its owner; a changed exhaustive test selects focused deterministic contracts and records the exhaustive owner as cadence-deferred. Shared support selects every declared PR consumer and records affected exhaustive consumers; copies, renames, and deletions inspect both identities. Reasons and changed paths are recorded in `impact.json`.
+
+Unknown operational inputs, unavailable comparison history, workflow/selector/suite/aggregate changes, and manual Development dispatch select every pull-request owner. Missing, malformed, or unknown cadence blocks instead of guessing. Documentation-only and version-only changes retain explicit exemptions. Selection does not require whole-repository source parsing.
+
+## Commands and coverage levels
+
+The public complete commands remain unchanged:
+
+```bash
+npm run test:pr-core               # mandatory type/architecture checks and bounded smoke tests
+npm run test:fast                  # typecheck, changed docs, complete fast composition
+npm run test:scope -- <scope...>   # named atomic scopes
+npm run test:full                  # complete deduplicated local composition
+npm run test:release               # release gates; publication authority is unchanged
+```
+
+`test:pr-core` is not a replacement for `test:fast`: CI combines it with directly changed and coarse-owner tests from the exact impact selection. Selected resource-sensitive tests run independently on an isolated Windows runner. Selected package, startup, rendering, Pi, compatibility, and platform owners also run independently after their actual prerequisites.
+
+Conservative Development retains every pull-request owner but does not schedule exhaustive owners. Full regression and nightly/stable release retain both cadence classes and declared Windows Node 22/24, Linux Node 24, and macOS Node 24 coverage. The real three-release `update-predecessor` exact-package oracle is exhaustive; deterministic predecessor command, fixture, materialization, warmup, package, and update contracts remain PR-eligible. Preview and release continue to consume exact candidate bytes under their channel-specific contracts. Use manual Full regression before merge when a risky release change needs real published-history evidence. The generated ownership ledger command is:
+
+```bash
+node scripts/release/generate-validation-ownership-ledger.mjs --output .artifacts/validation/ownership-ledger.json
+```
+
+## Failed-job reruns and attempt evidence
+
+Every modular outcome, content-free job envelope, and uploaded artifact name is qualified by `github.run_attempt`. Authority remains bound to the workflow run ID, exact head, complete selection identity, logical job, and platform/runtime target.
+
+For GitHub's explicit **re-run failed jobs** action, a successful job that GitHub did not rerun may be reused only from an earlier attempt of that same run/head/selection. A job executed in the current attempt must use its current outcome; failure, cancellation, malformed evidence, duplicate authority, or missing evidence blocks the aggregate. No result is reused across commits, workflow runs, or changed selections. The aggregate lists each reused job and original attempt. Workflows do not automatically retry semantic assertions or performance failures.
+
+## Receipts and artifact boundaries
+
+Checkout-bound type, architecture, governance, unit, and smoke outcomes bind head/run/selection/scope authority without inventing package identity. Build and package receipts remain mandatory wherever validation consumes emitted or packed bytes: package, startup, update, compatibility, preview, release, and publication boundaries.
+
+A build receipt binds checkout head, complete build inputs, toolchain, emitted files, and native artifacts. A package receipt additionally binds exact tarball bytes, packed entries, manifest/bin identity, producer, and verified build/source authority. `VALIDATION_BUILD_READY` and `VALIDATION_CANDIDATE_TARBALL` only locate prerequisites; stale or tampered receipts cause fresh preparation or failure.
+
+Npm download bytes may be reused with integrity checks and `--prefer-offline`, with normal network fallback. Every installation prefix remains fresh. Installed package trees, dependency certification, startup/profile state, mutable fixture repositories, passing outcomes, and publication evidence are never restored from caches.
+
+## Evidence inspection
+
+Download these artifacts from the exact workflow run:
+
+- `development-validation-impact`: base/head, global selection identity, PR-core tests, selected pull-request owners, cadence-deferred exhaustive owners, exclusions, and bounded reasons.
+- `development-validation-outcome-<job>-<platform>-node<node>-attempt-<attempt>`: attempt-qualified outcome, content-free envelope, per-scope authority and duration, and applicable exact-artifact evidence.
+- `development-validation-aggregate-<head>-<run>-<attempt>`: selected/deferred owners, accepted/reused attempts, evidence count, runner critical path, total runner time, aggregate processing, setup/gate/scope time, cache state, and invocation count. It reports the eight-minute critical-path and five-minute individual-scope targets as met or unmet; hosted queue delay is not test execution and remains separate.
+- startup/resume phase JSONL and performance JSON: first-attempt launch evidence and retained failed setup/readiness records.
+
+A finalized version-3 PR keeps its phase-free body unchanged. Its ordinary exact-head workflow runs selected product/governance lanes and `Finalized delivery validation` in parallel, then emits the stable protected `Development validation required` aggregate only when both authorities succeed. Green CI enables maintainer review and manual merge but does not claim human acceptance or merge automatically. No lifecycle body edit or second workflow run is required. Any implementation commit changes the head and reruns applicable validation; any body change reruns finalized-record validation and must continue to match the committed manifest. Legacy acceptance-record-only PRs retain their separate trusted `Acceptance record validation` route. Queue availability remains explicitly unavailable inside a runner and is calculated from the Actions API during final run analysis rather than guessed.
+
+## Rollback
+
+To disable selective execution without reducing PR coverage, use manual Development dispatch or force conservative ownership selection. To restore the historical predecessor oracle to every applicable PR, change its cadence from `exhaustive` to `pull-request`; do not delete it from Full/nightly/release. To disable prior-attempt reuse, require all accepted attempts to equal the aggregate attempt; this must not remove attempt-qualified artifacts or failure visibility. To disable prerequisite reuse, unset readiness/tarball variables and receipt paths so tier orchestration rebuilds and repacks.
+
+Rollback must retain every test, startup budget, zero automatic retry policy, platform/runtime lane, exact-package identity, resource isolation, complete fast/full/release compositions, and the single stable protected-branch aggregate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.8-dev.407",
+  "version": "0.1.8-dev.436",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "privateLaunchContract": "neutral-launch-v1",
@@ -24,7 +24,7 @@
   "scripts": {
     "postinstall": "node bin/sync-pi-tui-proxy.js",
     "clean": "node scripts/clean.mjs",
-    "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/development/build-process-guardian.mjs && node scripts/release/generate-runtime-payload-inventory.mjs",
+    "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/pi/build-startup-public.mjs && node scripts/development/build-process-guardian.mjs && node scripts/release/generate-runtime-payload-inventory.mjs",
     "build:process-guardian": "node scripts/development/build-process-guardian.mjs",
     "typecheck": "tsgo -p tsconfig.json --noEmit",
     "check:architecture": "node scripts/governance/check-architecture.mjs && node scripts/governance/check-product-identity-boundaries.mjs && node scripts/governance/check-package-identity.mjs && node scripts/governance/check-pinned-pi-source-ledger.mjs && node scripts/governance/check-terminal-host-provenance.mjs",
@@ -42,6 +42,7 @@
     "develop": "node scripts/development/develop.mjs",
     "release": "node scripts/release/release.mjs",
     "test": "npm run test:fast",
+    "test:pr-core": "node scripts/release/run-validation-tier.mjs pr-core",
     "test:fast": "node scripts/release/run-validation-tier.mjs typecheck documentation-changed fast",
     "test:scope": "node scripts/release/run-validation-tier.mjs",
     "test:full": "node scripts/release/run-validation-tier.mjs full-release",
@@ -80,6 +81,7 @@
     "@types/semver": "7.8.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "@xterm/headless": "6.0.0",
+    "esbuild": "0.25.10",
     "node-pty": "1.1.0",
     "tsx": "4.20.3",
     "typescript": "5.9.2",