@timurproko/a1 0.1.8-dev.3b54f21 → 0.1.8-dev.407

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

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

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

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

package/docs/openspec-archive-automation.md

@@ -0,0 +1,128 @@
+# Automatic OpenSpec 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.
+
+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.
+
+## One PR: specs, implementation, CI, validation, merge, archive, cleanup
+
+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.
+
+Use this delivery sequence:
+
+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.
+
+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.
+
+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.
+
+## Normal implementation handoff
+
+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`:
+
+````markdown
+```openspec-implementation
+{
+  "version": 2,
+  "change": "example-change",
+  "archivePreparationTasks": { "recordEvidence": "7.1", "stageArchive": "7.2" }
+}
+```
+````
+
+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:
+
+```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.
+```
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+## Rejection, standalone docs, and legacy migration
+
+- **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.
+
+Legacy link example:
+
+````markdown
+```openspec-implementation
+{ "version": 1, "change": "legacy-change", "specificationPr": 123 }
+```
+````
+
+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.
+
+## One-time publication setup
+
+Provisioning is a separate maintainer-approved operation, not performed by installing or running the script.
+
+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 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.
+
+## Audit and retry
+
+From a dependency-installed checkout, run a read-only audit using existing GitHub CLI authentication:
+
+```bash
+GH_TOKEN="$(gh auth token)" node scripts/governance/reconcile-openspec-archive.mjs --dry-run
+```
+
+To inspect one implementation PR, including one older than the scheduled window:
+
+```bash
+GH_TOKEN="$(gh auth token)" node scripts/governance/reconcile-openspec-archive.mjs --dry-run --pr 123
+```
+
+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 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.
+
+## Outcomes and bounds
+
+- **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 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.
+
+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.
+
+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.
+
+## 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.

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

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

package/package.json

@@ -1,17 +1,15 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.8-dev.3b54f21",
+  "version": "0.1.8-dev.407",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
+  "privateLaunchContract": "neutral-launch-v1",
   "packageManager": "npm@11.13.0",
   "bin": {
     "a1": "bin/cli.js"
   },
   "imports": {
-    "#pi-tui": [
-      "./node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-tui/dist/index.js",
-      "@earendil-works/pi-tui"
-    ]
+    "#pi-tui": "./bin/pi-tui.js"
   },
   "files": [
     "bin",
@@ -24,44 +22,59 @@
     "node": ">=22.19.0 <25"
   },
   "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/build-process-guardian.mjs",
-    "build:process-guardian": "node scripts/build-process-guardian.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:process-guardian": "node scripts/development/build-process-guardian.mjs",
     "typecheck": "tsgo -p tsconfig.json --noEmit",
-    "check:architecture": "node scripts/check-architecture.mjs && node scripts/product-identifier-policy.mjs --check && node scripts/check-product-identity-boundaries.mjs && node scripts/check-package-identity.mjs && node scripts/check-pinned-pi-source-ledger.mjs && node scripts/check-terminal-host-provenance.mjs",
-    "check:customization-ready": "node scripts/check-owned-ui-customization-prerequisites.mjs",
-    "check:deprecated": "node scripts/check-deprecated-dependencies.mjs",
+    "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",
+    "check:names": "node scripts/governance/product-identifier-policy.mjs --check",
+    "check:names:changed": "node scripts/governance/product-identifier-policy.mjs --check --selection .artifacts/validation/impact.json",
+    "check:code-documentation": "node scripts/governance/check-code-documentation.mjs --mode full",
+    "check:code-documentation:changed": "node scripts/release/run-changed-documentation.mjs",
+    "select:validation-impact": "node scripts/release/select-validation-impact.mjs",
+    "check:customization-ready": "node scripts/governance/check-owned-ui-customization-prerequisites.mjs",
+    "check:deprecated": "node scripts/governance/check-deprecated-dependencies.mjs",
+    "check:docs-governance": "node scripts/governance/check-docs-governance.mjs",
+    "check:repository-governance": "node scripts/governance/check-github-repository-governance.mjs --check",
     "branches:prune": "node scripts/prune-merged-branches.mjs",
     "check": "npm run test:fast",
-    "release": "node scripts/release.mjs",
+    "develop": "node scripts/development/develop.mjs",
+    "release": "node scripts/release/release.mjs",
     "test": "npm run test:fast",
-    "test:fast": "node scripts/run-validation-tier.mjs typecheck fast",
-    "test:scope": "node scripts/run-validation-tier.mjs",
-    "test:full": "node scripts/run-validation-tier.mjs full-release",
-    "test:release": "node scripts/run-release-gates.mjs",
-    "test:terminal-host": "node scripts/run-terminal-host-probe.mjs",
-    "test:pi-engine-conformance": "vitest run test/foundation/pi-engine-adapter/conformance.test.ts test/foundation/pi-engine-adapter/runtime-integration.test.ts test/foundation/pi-engine-adapter/session-integration.test.ts",
-    "report:pi-engine-conformance": "npm run build --silent && node scripts/run-pi-engine-conformance.mjs",
+    "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",
+    "test:release": "node scripts/release/run-release-gates.mjs",
+    "test:terminal-host": "node scripts/development/run-terminal-host-probe.mjs",
+    "test:pi-engine-conformance": "vitest run test/integrations/pi/engine/conformance.test.ts test/integrations/pi/engine/runtime-integration.test.ts test/integrations/pi/engine/session-integration.test.ts",
+    "report:pi-engine-conformance": "npm run build --silent && node scripts/pi/run-pi-engine-conformance.mjs",
+    "report:rendering-stability": "tsx scripts/pi/report-rendering-stability.ts",
+    "report:input-responsiveness": "tsx scripts/pi/report-input-responsiveness.ts",
     "sync:pi-ui": "npm run update:pi-component-parity && npm run update:pi-event-frame-parity && npm run update:pi-settings-metadata",
-    "update:pi-component-parity": "tsx scripts/update-pi-component-parity.ts",
-    "update:pi-event-frame-parity": "tsx scripts/update-pi-event-frame-parity.ts",
-    "proof:terminal-host": "node scripts/run-terminal-host.mjs",
-    "start": "npm run build && node scripts/dev-launch.mjs",
-    "start:pi": "npm run build && node scripts/dev-launch.mjs pi",
-    "start:sandbox": "npm run build && node scripts/dev-launch.mjs sandbox",
-    "prepack": "node scripts/prepack-gate.mjs",
+    "update:pi-component-parity": "tsx scripts/pi/update-pi-component-parity.ts",
+    "update:pi-event-frame-parity": "tsx scripts/pi/update-pi-event-frame-parity.ts",
+    "proof:terminal-host": "node scripts/development/run-terminal-host.mjs",
+    "start": "npm run build && node scripts/development/dev-launch.mjs",
+    "start:pi": "npm run build && node scripts/development/dev-launch.mjs pi",
+    "prepack": "node scripts/release/prepack-gate.mjs",
     "prepublishOnly": "npm run test:release",
     "prepare": "npm run build",
-    "update:pi-settings-metadata": "node scripts/update-pi-settings-metadata.mjs"
+    "update:pi-settings-metadata": "node scripts/pi/update-pi-settings-metadata.mjs"
   },
   "dependencies": {
     "@earendil-works/pi-coding-agent": "0.84.2",
     "@earendil-works/pi-tui": "0.84.2",
+    "@silvia-odwyer/photon-node": "0.3.4",
+    "chalk": "5.6.2",
     "cross-spawn": "7.0.6",
     "grok-mermaid": "0.2.2",
-    "semver": "7.8.5"
+    "semver": "7.8.5",
+    "undici": "8.9.0"
   },
   "devDependencies": {
+    "@fission-ai/openspec": "1.11.0",
+    "@lezer/python": "1.1.19",
     "@types/cross-spawn": "6.0.6",
     "@types/node": "24.2.1",
     "@types/semver": "7.8.0",
@@ -70,7 +83,8 @@
     "node-pty": "1.1.0",
     "tsx": "4.20.3",
     "typescript": "5.9.2",
-    "vitest": "3.2.7"
+    "vitest": "3.2.7",
+    "yaml": "2.9.1"
   },
   "keywords": [
     "cli",
@@ -87,5 +101,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "optionalDependencies": {
+    "@mariozechner/clipboard": "^0.3.9"
   }
 }

package/dist/src/cli/capabilities.d.ts

@@ -1,15 +0,0 @@
-/**
- * `pi` and `sandbox` exist to compare A1 against pinned Pi and to try resources
- * against an isolated profile. Both are development instruments rather than
- * product, so a stable release does not carry them: what a released `a1` exposes
- * is the product plus its maintenance and package commands.
- *
- * Which build this is comes from its own version. A prerelease version is a
- * `next`-channel build, which is where that work happens; a release version is
- * not. Nothing to configure, and no way for a released build to be talked into it.
- */
-export interface CliCapabilities {
-    readonly developmentProfiles: boolean;
-}
-export declare function cliCapabilities(version: string): CliCapabilities;
-export declare function isPrereleaseVersion(version: string): boolean;

package/dist/src/cli/dispatch.js

@@ -1,142 +0,0 @@
-import { interactiveLaunchIntent } from "../features/launch/index.js";
-import { PRODUCT_TEXT } from "../product-identity.js";
-export function cliUsage(capabilities) {
-    return PRODUCT_TEXT.usage([
-        "",
-        ...(capabilities.developmentProfiles ? ["pi", "sandbox"] : []),
-        "version",
-        "update [self|<source>|--extensions|--models]",
-        "update:next",
-        "update:<commit>",
-        "install <source>",
-        "remove <source>",
-        "list",
-    ]);
-}
-const PROFILE_WORDS = new Set(["pi", "sandbox"]);
-export async function dispatchCli(arguments_, handlers, output, capabilities) {
-    const command = parseCliCommand(arguments_, capabilities);
-    if (command.kind === "error") {
-        output.stderr(`${command.message}\n${cliUsage(capabilities)}\n`);
-        return 2;
-    }
-    if (command.kind === "launch")
-        return await handlers.launch(interactiveLaunchIntent(command.profileId));
-    if (command.kind === "version")
-        return await handlers.version();
-    if (command.kind === "packages")
-        return await handlers.packages(command.request);
-    return await handlers.update(command.channel, command.target);
-}
-export function parseCliCommand(arguments_, capabilities) {
-    if (arguments_.length === 0)
-        return { kind: "launch", profileId: "a1" };
-    const [command, ...rest] = arguments_;
-    if (capabilities.developmentProfiles && (command === "pi" || command === "sandbox")) {
-        return withoutArguments(rest, { kind: "launch", profileId: command });
-    }
-    if (command === "version")
-        return withoutArguments(rest, { kind: "version" });
-    if (command !== undefined && command.startsWith("update:"))
-        return parseColonUpdate(command.slice("update:".length), rest);
-    if (command === "update")
-        return parseUpdate(rest);
-    if (command === "install" || command === "remove" || command === "uninstall") {
-        return parseSourceCommand(command === "install" ? "install" : "remove", rest);
-    }
-    if (command === "list")
-        return withoutArguments(rest, { kind: "packages", request: { verb: "list", source: null } });
-    if (command === "ui")
-        return { kind: "error", message: `The ui subcommand was removed; run bare ${PRODUCT_TEXT.commandName} for the owned UI.` };
-    if (command === "agent")
-        return { kind: "error", message: `Bare ${PRODUCT_TEXT.commandName} is the ${PRODUCT_TEXT.displayName} agent experience; there is no agent subcommand.` };
-    return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unknown command: ${command ?? ""}`) };
-}
-/**
- * What follows the colon says which build to move to. `next` is the newest
- * preview; anything else names one outright, by the commit it was built from or by
- * its full version — a preview is published as `<version>-dev.<commit>`, so the
- * commit alone is enough to find it.
- */
-function parseColonUpdate(suffix, rest) {
-    if (rest.length > 0)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic("update takes what to move to after the colon, and nothing else.") };
-    if (suffix === "next")
-        return { kind: "update", channel: "next" };
-    if (suffix.length === 0)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`update: needs a preview after the colon, as in ${PRODUCT_TEXT.commandName} update:next.`) };
-    if (!/^[0-9a-z][0-9a-z.+-]*$/i.test(suffix)) {
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unusable preview: ${suffix}`) };
-    }
-    return { kind: "update", channel: "next", target: suffix };
-}
-/**
- * `update` carries both meanings pinned Pi gives it: itself by default, and the
- * profile's packages when a target says so. Pi is refused as a target because A1
- * certifies each release against one pinned Pi, so moving Pi underneath it would
- * invalidate what was certified.
- */
-function parseUpdate(rest) {
-    if (rest.length === 0)
-        return { kind: "update", channel: "stable" };
-    if (rest.length > 1)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic("update accepts one target.") };
-    const [target] = rest;
-    if (target === "self")
-        return { kind: "update", channel: "stable" };
-    if (target === "pi") {
-        return {
-            kind: "error",
-            message: PRODUCT_TEXT.diagnostic(`pins the Pi version it was certified against; run ${PRODUCT_TEXT.commandName} update to move ${PRODUCT_TEXT.displayName} itself.`),
-        };
-    }
-    // A release channel is spelled with the colon. Taking the bare word as a package
-    // source would turn a near miss into a confident search for a package nobody has.
-    if (target === "next" || target === "stable") {
-        const form = target === "next" ? `${PRODUCT_TEXT.commandName} update:next` : `${PRODUCT_TEXT.commandName} update`;
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`selects a release channel with a colon; run ${form}.`) };
-    }
-    if (target === "--extensions")
-        return { kind: "packages", request: { verb: "update", source: null } };
-    if (target === "--models")
-        return { kind: "packages", request: { verb: "refresh-models", source: null } };
-    if (target === undefined || target.startsWith("-"))
-        return unknownOption(target ?? "", "update");
-    if (PROFILE_WORDS.has(target))
-        return profileRejection("update");
-    return { kind: "packages", request: { verb: "update", source: target } };
-}
-function parseSourceCommand(verb, rest) {
-    const flag = rest.find(argument => argument.startsWith("-"));
-    if (flag !== undefined)
-        return unknownOption(flag, verb);
-    if (rest.length === 0)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${verb} requires a package source.`) };
-    if (rest.length > 1)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${verb} accepts one package source.`) };
-    const [source] = rest;
-    if (source === undefined)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${verb} requires a package source.`) };
-    if (PROFILE_WORDS.has(source))
-        return profileRejection(verb);
-    return { kind: "packages", request: { verb, source } };
-}
-function withoutArguments(rest, command) {
-    if (rest.length === 0)
-        return command;
-    const [argument] = rest;
-    if (argument !== undefined && (PROFILE_WORDS.has(argument) || argument.startsWith("--profile")))
-        return profileRejection("list");
-    return { kind: "error", message: PRODUCT_TEXT.diagnostic("commands do not accept additional arguments.") };
-}
-function profileRejection(verb) {
-    return {
-        kind: "error",
-        message: PRODUCT_TEXT.diagnostic(`manages packages in its own profile, so ${verb} takes no profile; Pi manages Pi's own profile.`),
-    };
-}
-function unknownOption(option, verb) {
-    if (option.startsWith("--profile"))
-        return profileRejection(verb);
-    return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unknown option for ${verb}: ${option}`) };
-}

package/dist/src/cli/version-stats.js

@@ -1,72 +0,0 @@
-import { spawn } from "node:child_process";
-import { readFile } from "node:fs/promises";
-import { resolve } from "node:path";
-import crossSpawn from "cross-spawn";
-import { valid as validSemver } from "semver";
-import { PRODUCT_TEXT } from "../product-identity.js";
-const defaultOutput = {
-    stdout(message) { process.stdout.write(message); },
-    stderr(message) { process.stderr.write(message); },
-};
-export async function runVersionStats(options) {
-    const output = options.output ?? defaultOutput;
-    const runner = options.runner ?? createVersionProcessRunner();
-    let installed;
-    try {
-        const manifest = JSON.parse(await readFile(resolve(options.packageRoot, "package.json"), "utf8"));
-        installed = parseVersion(manifest.version, "installed package");
-    }
-    catch (error) {
-        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not read its installed version: ${message(error)}`)}\n`);
-        return 1;
-    }
-    const remote = await queryDistTags(runner);
-    output.stdout(`Installed: ${installed}\nRelease:   ${remote.release ?? "unavailable"}\nNext:      ${remote.next ?? "unavailable"}\n`);
-    if (remote.error)
-        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not resolve npm dist-tags: ${remote.error}`)}\n`);
-    return 0;
-}
-async function queryDistTags(runner) {
-    let result;
-    try {
-        result = await runner("npm", ["view", PRODUCT_TEXT.packageName, "dist-tags", "--json"]);
-    }
-    catch (error) {
-        return unavailable(message(error));
-    }
-    if (result.code !== 0)
-        return unavailable(`npm exited with status ${result.code ?? "unknown"}`);
-    try {
-        const metadata = JSON.parse(result.stdout);
-        if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata))
-            throw new TypeError("npm returned a non-object dist-tags value");
-        const tags = metadata;
-        const release = parseVersion(tags.latest, "npm latest");
-        const next = tags.next === undefined ? null : parseVersion(tags.next, "npm next");
-        return { release, next, error: null };
-    }
-    catch (error) {
-        return unavailable(message(error));
-    }
-}
-function unavailable(error) {
-    return { release: null, next: null, error };
-}
-function createVersionProcessRunner() {
-    return async (command, arguments_) => await new Promise((resolvePromise, rejectPromise) => {
-        const child = process.platform === "win32"
-            ? crossSpawn(command, [...arguments_], { stdio: ["ignore", "pipe", "ignore"] })
-            : spawn(command, [...arguments_], { stdio: ["ignore", "pipe", "ignore"] });
-        const stdout = [];
-        child.stdout?.on("data", chunk => stdout.push(Buffer.from(chunk)));
-        child.once("error", rejectPromise);
-        child.once("close", code => resolvePromise({ code, stdout: Buffer.concat(stdout).toString("utf8") }));
-    });
-}
-function parseVersion(value, source) {
-    const parsed = typeof value === "string" ? validSemver(value) : null;
-    if (!parsed)
-        throw new Error(`${source} did not provide a valid semantic version`);
-    return parsed;
-}
-function message(error) { return error instanceof Error ? error.message : String(error); }