@timurproko/a1 0.2.7-dev.772 → 0.2.7-dev.788

package/docs/architecture/toolchain.md

@@ -71,7 +71,7 @@ This optional, mutating presentation-maintenance workflow regenerates component
 
 `node scripts/pi/sync-pi-inventories.mjs` re-resolves `modal-surface-inventory.json`, `presenter-ownership-inventory.json`, and `pinned-pi-interactive-baseline.json` against the installed Pi packages: anchors that still match stay, anchors that match only ignoring whitespace are rewritten, anchors that match nowhere mark their entry `orphaned`, behavior line ranges that lost their anchors move to their symbols' span, hashes and manifests are regenerated, and interactive components the modal graph has never recorded are reported as unmapped. `--check` reports without writing; `--commit <sha>` records a new version's upstream commit; `--report <path>` writes the resolution report.
 
-`node scripts/pi/propose-pi-upgrade.mjs [--version <v>] [--commit <sha>] [--skip <v>...] [--refresh] [--output <dir>]` proposes a Pi upgrade in the working tree: it captures the old upstream sources, pins both packages at the target (by default the newest published version newer than the pin that is not skipped; `--version` ignores skips), evaluates the candidate through `pi-candidate-evaluator.mjs` and keeps the complete compile output in the artifact (summarized per file in the body), installs and builds, three-way merges each vendored copy under `src/integrations/pi/components/upstream/` whose ledger record says `upgradeStrategy: three-way` (`git merge-file --diff3` of the A1 copy, the old upstream, and the new upstream; conflict markers stay in the file as review items) and, for a `keep-owned` copy, leaves the file alone and writes the upstream delta to `kept/<record>.diff` in the artifact, regenerates the ledger and headers, re-resolves the inventories, refreshes the public API baseline (listing removed or changed exports with their A1 consumers as adoption items) and the feature adoption matrix (listing new upstream rows as pending), re-pins the startup graph, refreshes parity evidence, runs the type, architecture, engine-conformance, and parity gates, scaffolds `openspec/changes/pi-upgrade-<version>/` with the pin moved in the requirement that names it (only when the change directory is absent), and writes `report.json` and the pull-request `body.md`. A failed step is recorded and the run continues; while conflict markers remain in any copy, the gates that compile the tree (`startup-graph`, `parity`, `typecheck`, `architecture`, `parity-suites`) are recorded as `blocked` by those copies instead of running to fail, and the isolated evaluation and engine conformance still report the candidate's verdicts. `--refresh` re-runs the derived steps and gates on the checked-out proposal branch without bumping, evaluating, installing, or merging, comparing against the pin of `--base` (`origin/develop`). `.github/workflows/pi-upstream-sync.yml` runs it nightly and opens or refreshes the draft pull request `chore/pi-<version>` with the App identity: the body's report lives between `<!-- pi-upgrade-report -->` markers and only that part is rewritten on a re-run (`scripts/pi/refresh-pi-upgrade-body.mjs`), and a branch that carries commits the bot did not author is never pushed to; the fresh report is posted as a comment instead. Closing a proposal with the `pi-upgrade-skipped` label skips its version; `PI_UPGRADE_FREEZE_UNTIL` silences the schedule until a date. A human resolves the review items and merges. The pinned identity every check compares itself to comes from `scripts/governance/pinned-pi-identity.mjs`: versions from the dependency authority, the commit from `pinned-pi-interactive-baseline.json`.
+`node scripts/pi/propose-pi-upgrade.mjs [--version <v>] [--commit <sha>] [--skip <v>...] [--refresh] [--output <dir>]` proposes a Pi upgrade in the working tree: it captures the old upstream sources, pins both packages at the target (by default the newest published version newer than the pin that is not skipped; `--version` ignores skips), evaluates the candidate through `pi-candidate-evaluator.mjs` and keeps the complete compile output in the artifact (summarized per file in the sync report), installs and builds, three-way merges each vendored copy under `src/integrations/pi/components/upstream/` whose ledger record says `upgradeStrategy: three-way` (`git merge-file --diff3` of the A1 copy, the old upstream, and the new upstream; conflict markers stay in the file as review items) and, for a `keep-owned` copy, leaves the file alone and writes the upstream delta to `kept/<record>.diff` in the artifact, regenerates the ledger and headers, re-resolves the inventories, refreshes the public API baseline (listing removed or changed exports with their A1 consumers as adoption items) and the feature adoption matrix (listing new upstream rows as pending), re-pins the startup graph, refreshes parity evidence, runs the type, architecture, engine-conformance, and parity gates, scaffolds `openspec/changes/pi-upgrade-<version>/` with the pin moved in the requirement that names it (only when the change directory is absent), and writes `report.json`, the pull-request `body.md` in the ordinary delivery layout with its generated implementation and acceptance outcomes, and the sync report `comment.md` carrying the version delta, changelog excerpt, verdicts, and review items. A failed step is recorded and the run continues; while conflict markers remain in any copy, the gates that compile the tree (`startup-graph`, `parity`, `typecheck`, `architecture`, `parity-suites`) are recorded as `blocked` by those copies instead of running to fail, and the isolated evaluation and engine conformance still report the candidate's verdicts. `--refresh` re-runs the derived steps and gates on the checked-out proposal branch without bumping, evaluating, installing, or merging, comparing against the pin of `--base` (`origin/develop`). `.github/workflows/pi-upstream-sync.yml` runs it nightly and opens the draft pull request `chore/pi-<version>` with the App identity and posts the sync report comment; every later run posts another comment and never edits the body, whose outcomes the reviewer checks, and a branch that carries commits the bot did not author is never pushed to. Closing a proposal with the `pi-upgrade-skipped` label skips its version; `PI_UPGRADE_FREEZE_UNTIL` silences the schedule until a date. A human resolves the review items and merges. The pinned identity every check compares itself to comes from `scripts/governance/pinned-pi-identity.mjs`: versions from the dependency authority, the commit from `pinned-pi-interactive-baseline.json`.
 
 `node scripts/pi/update-pinned-pi-public-api.mjs [--check] [--packages-root <node_modules>] [--output <path>]` records `config/baselines/pinned-pi-public-api.json`, the package-root export surface of both pinned packages read from their declaration entries with the TypeScript compiler API: each export's kind, the hash of its normalized declaration, and the A1 modules under `src/` whose imports name it, directly or through a barrel such as `startup-public.ts`. The baseline is tooling evidence read by path, never a production import. `node scripts/pi/update-pi-feature-adoption-matrix.mjs [--check] [--packages-root <node_modules>] [--report <path>]` records `config/baselines/pi-feature-adoption-matrix.json`: one row per advertised and hidden command, TUI and app keybinding, session event, settings callback, presented setting, and stateful component from the interactive baseline's manifests and the engine's settings source, plus one row per changelog "New Features" entry newer than the matrix's `changelogSince`, each carrying A1's disposition: `pinned` (reused as is), `owned` (the behavior id and the test that proves it), `diverged` (the approved deviation id), `declined` (a reason), or `pending` (what the refresher writes for a new row). The refresher rewrites the upstream side only and marks a row upstream dropped `retired`; `test/repository-governance/pi-feature-adoption-matrix.test.ts` fails on a pending row, on missing evidence, and on a row whose feature upstream no longer presents unless it is retired. `node scripts/pi/update-startup-graph-baseline.mjs [--check]` re-pins the file and byte totals in `config/startup-graph-baseline.json` from the measured startup reachability and the manifest the last build wrote; optional modules and pinned dynamic imports stay reviewed.
 

package/docs/ci-release-runbook.md

@@ -88,7 +88,7 @@ effect of stable publication, not a trigger.
 | Native **Publish release** on the prepared draft | GitHub creates the source-bound tag; `.github/workflows/release.yml` requires the successful candidate run, adopts the package pair it validated (replacing only the packaged release-note resource when the note was edited), proves npm trust, publishes both packages to npm `latest`, and proposes one reopening-and-note PR that auto-merges after required CI; a failure before npm returns the Release to draft |
 | `.github/workflows/release-tag-cleanup.yml` | When a stable Release is deleted, or on dispatch with a version (`gh workflow run release-tag-cleanup.yml -f version=X.Y.Z`): the release-automation App deletes the leftover `vX.Y.Z` tag only while no Release uses it and npm serves neither package; a published version's tag is permanent |
 | `.github/workflows/full-regression.yml` | Additional on-demand complete regression without publication authority |
-| `.github/workflows/pi-upstream-sync.yml` | Nightly at `03:23 UTC`: when npm publishes a newer Pi than the pin that no closed proposal skipped, proposes the upgrade as a draft pull request with the vendored copies that follow upstream merged, the kept copies reported with their upstream delta, the ledger, headers, inventories, public API and feature baselines, startup graph, and parity evidence regenerated, and every gate verdict (passed, failed, or blocked by conflict markers) and review item in the body; never merges and never replaces a proposal a human has continued |
+| `.github/workflows/pi-upstream-sync.yml` | Nightly at `03:23 UTC`: when npm publishes a newer Pi than the pin that no closed proposal skipped, proposes the upgrade as a draft pull request with the vendored copies that follow upstream merged, the kept copies reported with their upstream delta, the ledger, headers, inventories, public API and feature baselines, startup graph, and parity evidence regenerated, and the body in the ordinary delivery layout with its four implementation outcomes and one acceptance outcome generated, and posts a sync report comment carrying the version delta, changelog excerpt, every gate verdict (passed, failed, or blocked by conflict markers), and review item; every later run posts another comment and never edits the body; never merges and never replaces a proposal a human has continued |
 | `.github/workflows/nightly-regression-triage.yml` | After every completed `Full regression` run on `develop` or scheduled `Publish` validation: judges the startup budget across the three most recent runs and, after a failure or a persistent overrun, opens `fix/nightly-regression-<date>` as a draft pull request in the ordinary delivery layout with its two implementation outcomes and one acceptance outcome generated, posts a triage comment carrying the failed commands per lane, their tests, a bounded log excerpt, and the `develop` commits since the last green run, and commits an OpenSpec fix scaffold, or refreshes the open candidate with the same failed scope set through another comment and design record; re-runs nothing, never writes `develop`, never merges |
 
 ## Impact-aware development validation
@@ -372,7 +372,7 @@ Rules that do not bend:
   with another token.
 - **Repository governance drifts:** run the read-only checker, review every reported
   path, and use the confirmed apply mode only for an accepted mutable policy change.
-- **A Pi upgrade proposal needs a re-run:** the sync never force-pushes over `chore/pi-<version>` once it carries a commit the bot did not author; a scheduled re-run posts its fresh verdicts as a comment headed with the version and date and rewrites only the report between the `<!-- pi-upgrade-report -->` markers of the description. To re-run the derived steps and gates on the reviewer's head, dispatch the workflow with `refresh` and the `version`; it checks out the proposal branch, skips bump, evaluation, install, and merge, and reports without pushing. A branch whose commits are all the bot's is recreated from `develop` as before.
+- **A Pi upgrade proposal needs a re-run:** the sync never force-pushes over `chore/pi-<version>` once it carries a commit the bot did not author; a scheduled re-run posts its fresh verdicts as another sync report comment headed with the version and date and never edits the description. The description is the ordinary delivery layout: check each generated implementation outcome as its work completes, including one the report shows nothing for, never rewrite the generated items, and let trusted readiness promote the all-checked draft like any other. To re-run the derived steps and gates on the reviewer's head, dispatch the workflow with `refresh` and the `version`; it checks out the proposal branch, skips bump, evaluation, install, and merge, and reports without pushing. A branch whose commits are all the bot's is recreated from `develop` as before.
 - **A Pi version should not be adopted:** close its proposal pull request with the `pi-upgrade-skipped` label (declared in `config/github-repository-governance.json`) and say why in the closing comment; the next run proposes the newest unskipped version newer than the pin, or nothing, and names the skipped versions in its log. A proposal closed without the label is proposed again the next night. Dispatching the workflow with a `version` ignores skips, which is how a skipped version is reconsidered. To silence the schedule through a release window, set the repository variable `PI_UPGRADE_FREEZE_UNTIL` to a date (`2026-10-01`); scheduled runs exit before proposing until it passes, manual dispatches still run.
 - **Nightly documentation review fails:** inspect the reported paths and rules, identify the introducing merge from the nightly interval, and repair the invariant before unrelated work proceeds.
 - **Development publication fails:** inspect both package versions and digests, fix the cause, and rerun `npm run develop`; an npm version that already exists is verified and never overwritten.

package/docs/openspec-archive-automation.md

@@ -8,11 +8,11 @@ Version-1 and version-2 deliveries and their existing comments, acceptance PRs,
 
 ## 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, and follow it with two to ten unchecked, outcome-sized task items under `## Implementation`. Omit generic process tasks, 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. Check an Implementation item as soon as its associated implementation, focused pre-ready evidence, and detailed task bookkeeping are complete; an ordinary progress edit changes only `[ ]` to `[x]` and is not deferred until handoff. Adding, removing, reordering, or rewriting an item is a scope refinement requiring explicit approval and coherent planning updates, with affected scope left unchecked. Reconcile approved refinements before corresponding code edits.
-3. **Complete evidence:** finish implementation, required pre-ready tests/evidence, substantive tasks, and explicit known-gap disposition. CI success is later objective evidence, not acceptance, and GitHub check counts are not Implementation task progress.
-4. **Plain acceptance list:** before checking the final item, keep the body phase-free and add final `## Acceptance` with one to ten concise implementation-specific behavior-and-result bullets. Do not use checkboxes, generic review/CI/approval/archive statements, URLs, mentions, or automated-test inventory.
-5. **Automatic readiness and finalization:** reconcile and push current `origin/develop`, then check the final item. That checkbox update completes the agent-owned implementation job; agents never mark implementation PRs ready themselves. Trusted automation revalidates the exact fully complete version-3 task-list snapshot and all pre-finalization inputs, marks the PR ready, and then 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. It never checks tasks or infers completion. Running the [finalization command](#finalization-command) locally first is optional and yields the same bytes.
+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, and follow it with two to ten unchecked, outcome-sized task items under `## Implementation`. Each item names a delivered code outcome. Omit generic process tasks; run, verify, validate, evidence, or manual-test items; 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. Check an Implementation item as soon as its associated code and tests are written and its detailed task bookkeeping is complete; an ordinary progress edit changes only `[ ]` to `[x]` and is not deferred until handoff. Adding, removing, reordering, or rewriting an item is a scope refinement requiring explicit approval and coherent planning updates, with affected scope left unchecked. Reconcile approved refinements before corresponding code edits.
+3. **Complete implementation:** finish the code and its tests, substantive tasks, and explicit known-gap disposition. CI runs those tests after readiness; its success is objective evidence, not acceptance, and GitHub check counts are not Implementation task progress. Manual validation is the maintainer's optional choice before integrating and never blocks a checkbox, finalization, or merge.
+4. **Plain acceptance list:** before checking the final item, keep the body phase-free and add final `## Acceptance` with one to ten concise implementation-specific behavior-and-result bullets. Do not use checkboxes, generic review/CI/approval/archive statements, angle-bracket placeholders or HTML, URLs, mentions, or automated-test inventory.
+5. **Automatic readiness and finalization:** reconcile and push current `origin/develop`, run the [delivery body check](#delivery-body-check) on the intended final body, then check the final item. That checkbox update completes the agent-owned implementation job; agents never mark implementation PRs ready themselves. Trusted automation revalidates the exact fully complete version-3 task-list snapshot and all pre-finalization inputs, marks the PR ready, and then 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. It never checks tasks or infers completion. 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. **Maintainer integration accepts:** after reviewing the finalized candidate, an authorized human either manually merges the exact validated head after the stable protected aggregate succeeds or personally enables GitHub native auto-merge for that unchanged head so protected integration waits for the aggregate. That human action means the listed scenarios are accepted. Agents, Apps, bots, merge queue, automation-owned implementation arms, and documentation integration remain forbidden. A changed head, acceptance list, or finalization invalidates the earlier arm and requires the maintainer to choose again.
 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)).
@@ -50,7 +50,7 @@ Replace the multi-PR OpenSpec handoff with one manually merged development PR wh
 </details>
 ```
 
-Do not add a quoted phase line, generic CI/review/acceptance/merge/archive tasks, 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. Toggle only the exact marker when ordinary work completes; body history must not hide a scope change as progress. Historical version-3 bodies with only plain Implementation bullets remain readable, but new bodies use the task-list form. When implementation is complete and ready for required tests, use this visible order:
+Do not add a quoted phase line, generic CI/review/acceptance/merge/archive tasks, run/verify/validate/evidence/manual-test items, 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. Toggle only the exact marker when ordinary work completes; body history must not hide a scope change as progress. Historical version-3 bodies with only plain Implementation bullets remain readable, but new bodies use the task-list form. When implementation is complete and ready for required tests, use this visible order:
 
 ```markdown
 ## Proposal
@@ -141,13 +141,25 @@ Use plain bullets:
 - Finalized specs and archive match the implementation.
 ```
 
+Each Implementation and Acceptance item is one line of 20 to 300 bytes. Draft promotion and the delivery body check reject an Implementation item that starts with `Manually`, `Validate`, `Verify`, `Confirm`, `Prove`, `Run`, or `Test`, mentions manual testing, records or captures evidence, or delivers work "with" coverage, evidence, or validation (`implementation-progress-validation`); merged bodies keep their earlier wording. It must not contain angle-bracket text such as `<job>` or other HTML, URLs, or `@` mentions, and Acceptance items must not be checkboxes. Write a concrete example instead of a placeholder, such as `Develop / Build process guardian`.
+
+### Delivery body check
+
+Before checking the final Implementation item, write the intended final body to an ignored artifact file and run the same body validators that trusted promotion uses:
+
+```bash
+node scripts/governance/check-delivery-body.mjs --body-file .artifacts/agent/pr-body.md --final
+```
+
+`--final` validates the body as if every Implementation item were checked, so it can run before the last marker changes. `--pr <n>` reads the current pull request body instead. A defect exits 1 and prints the same `draft-<code>` reason the finalization run would report. The check covers association, Implementation, layout, and Acceptance only; detailed tasks, evidence, and target state remain covered by the [finalization command](#finalization-command) inspection mode.
+
 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. The authorized maintainer's manual merge or personal native auto-merge arm for the unchanged exact head 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 `opened`, `synchronize`, `ready_for_review`, `reopened`, and `edited` events 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. An all-checked version-3 task-list draft with valid Acceptance and complete detailed pre-finalization inputs is re-read as one exact snapshot and marked ready; no content is changed, and incomplete, malformed, legacy, unassociated, forked, or raced drafts remain draft with a stable reason. Closed PRs are skipped. For a ready version-3 candidate the workflow reconciles the head to its finalized form:
+The `OpenSpec finalization` workflow (`.github/workflows/openspec-finalization.yml`) runs on `pull_request_target` for `opened`, `synchronize`, `ready_for_review`, `reopened`, and `edited` events 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. An all-checked version-3 task-list draft with valid Acceptance and complete detailed pre-finalization inputs is re-read as one exact snapshot and marked ready; no content is changed, and incomplete, malformed, legacy, unassociated, forked, or raced drafts remain draft with a stable reason. A draft with any unchecked item is skipped quietly. A draft whose every task-list item is checked but whose promotion is refused for a body, task, evidence, or other content defect fails the run with an `OpenSpec finalization` error annotation naming the `draft-<code>` reason, so the stall shows as a red check instead of a green skip. Closed PRs are skipped. For a ready version-3 candidate the workflow 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`.

package/docs/validation.md

@@ -24,7 +24,15 @@ npm run test:full                  # complete deduplicated local composition
 npm run test:release               # release gates; publication authority is unchanged
 ```
 
-Before every push, run the fast governance gates locally:
+Before a push, run only quick targeted checks of what changed; CI after the pull request becomes ready is the validation authority:
+
+```bash
+npm run typecheck                          # type check
+npx vitest run <changed test files...>     # tests covering the changed code
+npx openspec validate <change> --strict    # the OpenSpec change
+```
+
+Do not run preflight, `test:fast`, `test:full`, `test:release`, or directory-wide test runs before pushing. They are for reproducing a failure CI reported, or when the maintainer asks. Preflight is the optional tool for reproducing a fast-gate failure:
 
 ```bash
 npm run preflight                  # pull-request validation's fast gates on the committed head

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.2.7-dev.772",
+  "version": "0.2.7-dev.788",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "privateLaunchContract": "neutral-launch-v1",
@@ -69,8 +69,8 @@
     "typecheck:bin": "tsgo -p tsconfig.bin.json"
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "1.2.0",
-    "@earendil-works/pi-tui": "1.2.0",
+    "@earendil-works/pi-coding-agent": "1.3.0",
+    "@earendil-works/pi-tui": "1.3.0",
     "@silvia-odwyer/photon-node": "0.3.4",
     "chalk": "5.6.2",
     "cross-spawn": "7.0.6",