@timurproko/a1 0.1.8-dev.518 → 0.1.8-dev.527

package/docs/architecture/toolchain.md

@@ -34,6 +34,8 @@ It contains no PTY, terminal emulator, browser/desktop GUI, custom renderer, inp
 
 ## Native launch containment
 
+`npm run doctor` reports this contract against the current machine—Node range, npm major, git, the GitHub CLI, Rust/Cargo, and whether `node_modules` matches the lockfile—and names the install command for anything missing. `npm run build` runs the same check as its first step, so an unmet prerequisite fails by name rather than inside a module resolver or Cargo. Unmet tool prerequisites block; a Node or npm version outside the declared contract is reported as an advisory without failing the build.
+
 Source builds require Rust/Cargo 1.85 or newer. `npm run build` compiles the standalone `native/process-guardian` crate for the host platform, places it under `dist/native/<platform>-<architecture>/`, and writes an integrity manifest. Preview and stable candidate workflows build platform artifacts on isolated Windows, Linux, and macOS runners and assemble them before packing. macOS remains explicitly unsupported until its exact containment adapter is certified; the package must fail before runtime startup rather than use PID-only cleanup.
 
 The process guardian inherits terminal handles but transports no terminal bytes. See [`process-guardian-provenance.md`](process-guardian-provenance.md).

package/docs/ci-release-runbook.md

@@ -49,7 +49,7 @@ effect of stable publication, not a trigger.
 | Pull request into `develop` | Bounded PR-cadence validation; changed/new source documentation is checked once, rendering runs as `none`, `smoke`, or `full`, and exhaustive owners are reported as deferred |
 | `npm run develop` | Preview package gates on Windows, Linux, and macOS; an existing numbered preview is an early successful no-op |
 | Nightly at `03:17 UTC` | One full documentation review plus the complete non-physical suite on Windows, Linux, and macOS, every night |
-| `npm run release -- ...` | Complete exact-byte stable gates, then npm `latest`, tag, GitHub Release, and `master` |
+| `npm run release -- ...` | Stamps the requested stable version on the open `develop` source, runs the complete exact-byte stable gates, then npm `latest`, tag, GitHub Release, and `master`; one reopening PR follows |
 | `.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/nightly-regression-triage.yml` | After every completed `Full regression` run on `develop` or scheduled `Release` 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 carrying the failed commands per lane, their tests, a bounded log excerpt, the `develop` commits since the last green run, and an OpenSpec fix scaffold, or refreshes the open candidate with the same failed scope set; re-runs nothing, never writes `develop`, never merges |
@@ -149,7 +149,7 @@ validation; malformed, mixed, renamed, stale, or unavailable inputs fail closed.
 A legitimate generated baseline update remains outside the allowlist and follows the
 manually accepted mixed/code path.
 
-A new implementation-bound specification starts as OpenSpec-only artifacts in one normally named draft PR. Explicit approval to implement continues in that same worktree, branch, history, and PR; the plan does not merge first. Approved refinements reconcile planning before code. After implementation, add one to three plain implementation-specific bullets under `## Acceptance` and mark the PR ready; the trusted `OpenSpec finalization` workflow conservatively synchronizes deltas, stages the dated archive plus conditional acceptance manifest, and commits them to the same branch, and exact-head CI validates that head. Auto-merge remains disabled: an authorized maintainer's manual merge accepts the listed scenarios and atomically integrates implementation, specs, and archive. No acceptance or archive follow-up PR is created. Closing an unmerged draft integrates nothing; cleanup still needs separate approval. See [delivery and archive handoff](openspec-archive-automation.md) for commands and legacy compatibility.
+A new implementation-bound specification starts as OpenSpec-only artifacts in one normally named draft PR. Explicit approval to implement continues in that same worktree, branch, history, and PR; the plan does not merge first. Approved refinements reconcile planning before code. After implementation, add one to ten plain implementation-specific bullets under `## Acceptance` and mark the PR ready; the trusted `OpenSpec finalization` workflow conservatively synchronizes deltas, stages the dated archive plus conditional acceptance manifest, and commits them to the same branch, and exact-head CI validates that head. Auto-merge remains disabled: an authorized maintainer's manual merge accepts the listed scenarios and atomically integrates implementation, specs, and archive. No acceptance or archive follow-up PR is created. Closing an unmerged draft integrates nothing; cleanup still needs separate approval. See [delivery and archive handoff](openspec-archive-automation.md) for commands and legacy compatibility.
 
 ## Numbered development previews
 
@@ -195,43 +195,50 @@ work.
 From the repository root on clean `develop` matching `origin/develop`:
 
 ```sh
-npm run release -- patch     # 0.1.8-dev -> 0.1.8; already-stable 0.1.8 -> 0.1.9
+npm run release -- patch     # 0.1.8-dev -> 0.1.8
 npm run release -- minor     # 0.1.8-dev -> 0.2.0
 npm run release -- major     # 0.1.8-dev -> 1.0.0
 npm run release -- 0.4.0     # exact stable target
 ```
 
 A target is required: `npm run release` alone is a mutation-free usage error.
-`patch` preserves prerelease-aware semantics, including `0.1.8-dev.123 -> 0.1.8`.
+`patch` promotes the open prerelease, `0.1.8-dev -> 0.1.8`. `develop` must declare
+exactly one open `x.y.z-dev` version; a stable or numbered version there is refused.
 The command reports its source, stable target, and prospective reopening before
-preparing anything.
-
-1. The stable-version edit is committed in an owned detached worktree beneath
-   `.worktrees/`. Only this package's manifest and root lockfile version change.
-2. Follow the printed PR URL, wait for required CI, perform local validation, and
-   **merge manually after acceptance**. The helper does not merge PRs or enable
-   auto-merge. It polls for actual merge with a bounded 30-minute wait.
-3. The helper verifies the merged version and source SHA against authoritative
-   develop, then explicitly dispatches stable publication for that exact source.
-   A changed source is an error, not permission to substitute a newer commit.
-4. Only after verified publication of `0.1.8` does it prepare a separate PR for
-   `0.1.9-dev`. Validate and manually merge that PR as well. Until then the helper
-   reports development reopening as incomplete.
+touching anything, and the stable version is never committed to `develop`.
+
+1. The helper checks that the registry and `v<version>` tag do not already hold the
+   target, re-reads authoritative `develop`, and explicitly dispatches stable
+   publication for that exact source with the stable version in the request. A changed source is
+   an error, not permission to substitute a newer commit.
+2. The workflow stamps the requested version on the checked-out source
+   (`npm version <x.y.z> --no-git-tag-version`) before packing, so the tarball
+   declares `0.1.8` while the tagged commit still declares `0.1.8-dev`. Everything
+   else about the package is byte-identical to that commit's tree; `git checkout
+   v0.1.8 && npm version 0.1.8 --no-git-tag-version && npm pack` reproduces it.
+3. Only after verified publication of `0.1.8` does the helper commit `0.1.9-dev`
+   in an owned detached worktree beneath `.worktrees/` (only this package's manifest
+   and root lockfile version change), open the one version PR, and wait for you to
+   **merge it manually** with a bounded 30-minute poll. The helper never merges
+   PRs or enables auto-merge. Until that merge the helper reports development
+   reopening as incomplete, and previews cannot be published from a `develop`
+   whose `-dev` version sorts below the stable release.
 
 Closed PRs, timeout, cancellation, and query failures retain identifiable phase
 work for inspection. Conflicting existing branches/PRs are not overwritten;
-matching pending PRs can be observed again without replacing them. Worktrees
+a matching pending reopening PR is observed rather than replaced. Worktrees
 retained by an earlier attempt are not removed by a later invocation. Cleanup
 only removes clean, owned, confirmed-merged phase worktrees and unchanged remote
 phase branches. The caller is never hard-reset: a final fast-forward is attempted
 only when its branch, original HEAD, and cleanliness remain unchanged. Otherwise
 preserve local work and synchronize manually with the reported remote state.
 
-Stable publication builds the process guardian on all supported platforms, packs
-once, runs the complete suite against those exact bytes on Windows, Linux, and
-macOS, publishes to npm `latest` with provenance from the `npm-publish`
-environment, and then writes `vx.y.z`, records the GitHub Release, and fast-forwards
-`master`. A push of the stable version does not publish it.
+Stable publication builds the process guardian on all supported platforms, stamps
+the version, packs once, runs the complete suite against those exact bytes on
+Windows, Linux, and macOS, publishes to npm `latest` with provenance from the
+`npm-publish` environment, and then writes `vx.y.z` on the source commit, records
+the GitHub Release, and fast-forwards `master`. A push of the stable version does
+not publish it, and no automation ever pushes one.
 
 Rules that do not bend:
 
@@ -257,7 +264,8 @@ Rules that do not bend:
 - **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:** fix the cause and rerun `npm run develop`; an npm version that already exists is never overwritten.
 - **Registry verification times out:** a `has not propagated` failure after a successful `npm publish` means npm is still ingesting the upload; it warns that a provenance-signed package "may take a few minutes" and the publisher polls for ten minutes. Confirm the version and its shasum on `https://registry.npmjs.org/<name>/<version>`, then rerun the failed jobs: the final registry check finds the exact bytes, skips `npm publish`, and verification passes. A digest or tag mismatch is not a timeout and is never repaired by rerunning.
-- **Stable preparation stops before dispatch:** inspect the reported version PR/worktree. After preserving work, an exact matching pending PR can be observed again. If develop already declares the prepared stable version, use its exact target (for example `npm run release -- 0.1.8`) only after verifying that source's merged PR and confirming the registry/tag guards still permit it. Do not use `patch` from stable develop to retry the same version: that deliberately selects the next patch.
+- **Stable publication fails or is uncertain:** no reopening PR was prepared and `develop` still declares the open `-dev` version. Inspect the workflow run, npm, and the `v<version>` tag. When nothing was published, fix the cause and rerun the same target; the registry and tag guards refuse a version that already exists.
+- **Stable is published but reopening stopped:** the helper reports the reopening PR or retained worktree. Merge the pending `chore/release-<x.y.z>-dev` PR by hand once its CI passes, or repair the branch and open the PR yourself; never rerun the release for the published version.
 - **Stable publication fails or is uncertain:** inspect the workflow, registry version/digest, tag, and release before choosing recovery. No reopening PR is prepared. Never republish immutable bytes or move a release tag.
 - **Stable publication succeeded but reopening stops:** the stable version is already published. Inspect and finish the reported next-development PR manually; do not repeat stable publication. If no reopening PR was created, prepare the next-development version through a separately validated manual PR after inspecting remote state.
 

package/docs/openspec-archive-automation.md

@@ -11,7 +11,7 @@ Version-1 and version-2 deliveries and their existing comments, acceptance PRs,
 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.
+4. **Plain acceptance list:** 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. **Ready and automated finalization:** mark the PR ready. The trusted `OpenSpec finalization` workflow reconciles current `develop`, conservatively synchronizes all deltas, moves the active change into its dated archive, stages the conditional acceptance manifest, commits that to the same branch with the archive App identity, and writes the emitted paths into the body's implementation fence. Running the [finalization command](#finalization-command) locally first is optional and yields the same bytes.
 6. **Validate:** one normal exact-head workflow validates the finalized head: implementation, synchronized specs, archive, manifest, tasks/evidence, exact PR-body list, and every selected product/governance scope before emitting the stable protected aggregate. A new commit or acceptance-list change re-finalizes automatically when needed and requires full renewed validation; no lifecycle body edit or second workflow run is required.
 7. **Manual merge accepts:** after the stable protected aggregate succeeds, an authorized human reviews and manually merges the exact validated head. That single action means the listed scenarios are accepted and explicitly authorizes integration. Auto-merge, merge queue, Apps, bots, and documentation reconciliation are forbidden.
@@ -57,7 +57,7 @@ Do not add a quoted phase line or a routine `Validation` section listing command
 
 ## Acceptance
 
-<!-- one to three plain behavior-and-result bullets -->
+<!-- one to ten plain behavior-and-result bullets -->
 
 ## Automation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.8-dev.518",
+  "version": "0.1.8-dev.527",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "privateLaunchContract": "neutral-launch-v1",
@@ -23,7 +23,7 @@
   },
   "scripts": {
     "clean": "node scripts/clean.mjs",
-    "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/pi/build-pi-settings-metadata.mjs && node scripts/pi/build-startup-public.mjs && node scripts/development/build-process-guardian.mjs && node scripts/release/generate-runtime-payload-inventory.mjs",
+    "build": "node scripts/development/check-environment.mjs && npm run clean && tsc -p tsconfig.build.json && node scripts/pi/build-pi-settings-metadata.mjs && 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 && tsgo -p tsconfig.bin.json",
     "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",
@@ -39,6 +39,7 @@
     "branches:prune": "node scripts/prune-merged-branches.mjs",
     "check": "npm run test:fast",
     "develop": "node scripts/development/develop.mjs",
+    "doctor": "node scripts/development/check-environment.mjs --report",
     "release": "node scripts/release/release.mjs",
     "test": "npm run test:fast",
     "test:pr-core": "node scripts/release/run-validation-tier.mjs pr-core",
@@ -63,8 +64,8 @@
     "typecheck:bin": "tsgo -p tsconfig.bin.json"
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "0.85.1",
-    "@earendil-works/pi-tui": "0.85.1",
+    "@earendil-works/pi-coding-agent": "0.86.1",
+    "@earendil-works/pi-tui": "0.86.1",
     "@silvia-odwyer/photon-node": "0.3.4",
     "chalk": "5.6.2",
     "cross-spawn": "7.0.6",