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

package/docs/openspec-archive-automation.md

@@ -1,124 +1,246 @@
-# Automatic OpenSpec archival
+# Atomic OpenSpec delivery and legacy archival
 
-The archive workflow handles accepted implementation merges into `develop`, a daily 90-day catch-up, and targeted retries. It creates an OpenSpec-only PR; existing documentation auto-merge remains responsible for squash integration after real current-head CI. An archive PR being open is not a completed archive.
+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 draft PR from planning through implementation
+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
 
-Keep the PR draft while incomplete, then make it ready for final review. Approval to implement is not final acceptance or merge authorization. The completed PR still requires required CI, actual final-head maintainer review, and explicit manual integration. The documentation merge owner holds implementation-associated PRs and new active changes even if marked ready or their 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.
+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.
 
-## Normal implementation handoff
+The implementation, synchronized canonical specs, conditional acceptance record, and archive therefore reach `develop` atomically. Closing the PR unmerged integrates none of them.
 
-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`:
+## 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. 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,
-  "change": "example-change",
-  "archivePreparationTasks": { "recordEvidence": "7.1", "stageArchive": "7.2" }
+  "version": 3,
+  "change": "example-change"
 }
 ```
-````
 
-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:
+</details>
+````
 
-```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.
-```
+After finalization, replace it with the exact emitted paths:
 
-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.
+````markdown
+## Automation
 
-After the maintainer actually accepts the final candidate, record one authorized maintainer PR comment:
+<details>
+<summary>Used by CI to link this PR to its OpenSpec change</summary>
 
-````markdown
-```openspec-acceptance
+```openspec-implementation
 {
-  "version": 1,
+  "version": 3,
   "change": "example-change",
-  "headSha": "REPLACE_WITH_FINAL_REVIEWED_40_CHARACTER_SHA",
-  "specBaseSha": "REPLACE_WITH_REVIEWED_SPEC_BASELINE_40_CHARACTER_SHA",
-  "verdict": "accepted",
-  "implementationComplete": true,
-  "manualReview": "passed",
-  "specSyncReviewed": true,
-  "evidence": "Identify the exact candidate, applicable commands, scenarios reviewed, and actual outcomes."
+  "archive": "openspec/changes/archive/2026-09-15-example-change/",
+  "acceptanceManifest": "openspec/changes/archive/2026-09-15-example-change/acceptance.md"
 }
 ```
+
+</details>
 ````
 
-The placeholders intentionally fail validation. The agent fills actual identities and reports; it must never invent a positive review. The spec baseline is an ancestor commit containing the canonical requirements against which the maintainer reviewed the deltas. It is not automatically moved to a newer baseline to conceal conflicts.
+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.
 
-The comment author needs repository write/maintain/admin authority. A newer head needs renewed acceptance; missing, edited, contradictory, revoked, stale, or known-gap records block the automatic route. Acceptance records remain version 1 and require one unambiguous current-head acceptance record. Earlier-head records are retained; same-head contradictions or a later conflicting record require explicit reconciliation before retrying. Source acceptance is copied into the archived `acceptance.md` with PR, head, merge, check-run, and comment provenance.
+## Acceptance list
 
-The code PR still requires explicit manual merge authorization. After that merge, no additional archive request 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.
+Use plain bullets:
 
-## Rejection, standalone docs, and legacy migration
+```markdown
+## Acceptance
 
-- **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.
+- Conservative fallback runs all required validation.
+- Failed or stale evidence blocks integration.
+- Finalized specs and archive match the implementation.
+```
 
-Legacy link example:
+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.
 
-````markdown
-```openspec-implementation
-{ "version": 1, "change": "legacy-change", "specificationPr": 123 }
+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.
+
+## Finalization command
+
+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:
+
+```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"
 ```
-````
 
-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.
+Inspect the reported paths. Then rerun with `--write` and update the existing PR body from the emitted file:
 
-## One-time publication setup
+```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"
+```
 
-Provisioning is a separate maintainer-approved operation, not performed by installing or running the script.
+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.
 
-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.
+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.
 
-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.
+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.
 
-## Audit and retry
+## Conditional acceptance and derived receipt
 
-From a dependency-installed checkout, run a read-only audit using existing GitHub CLI authentication:
+`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:
 
-```bash
-GH_TOKEN="$(gh auth token)" node scripts/governance/reconcile-openspec-archive.mjs --dry-run
-```
+- 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.
 
-To inspect one implementation PR, including one older than the scheduled window:
+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.
+
+`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 legacy candidates it retains its existing scoped App publication behavior.
+
+## Status and audit
+
+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.
 
-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.
+## Cleanup
 
-## Outcomes and bounds
+After version-3 merge, verify:
 
-- **eligible**: evidence and isolated staging passed; dry-run did not publish.
-- **blocked**: a named evidence/task/spec/setup/ownership 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.
+- 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 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.
+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.
 
-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.
+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.
 
-Known-gap archival remains a separately authorized manual path. The existing backlog is not bulk-approved when automation starts. Local worktree cleanup remains with the local agent after verified integration and a clean-tree check.
+## 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;
+- 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. Preserve active changes and open archive PRs for review. Do not delete documents, undo synchronized specs, or modify repository rulesets merely to stop automation. 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.402",
+  "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",