@timurproko/a1 0.1.1-dev.9 → 0.1.5-dev.11

package/docs/ci-release-runbook.md

@@ -1,13 +1,20 @@
 # CI and release operations
 
-GitHub Actions is the only automation platform. Two required checks protect the branches:
+GitHub Actions is the only automation platform. Three refs are protected:
 
-| Branch | Required check | Produced by |
+| Ref | Protection | Produced by |
 | --- | --- | --- |
-| `develop` | `Development validation required` | `.github/workflows/ci.yml` |
-| `master` | `Stable candidate required` | `.github/workflows/certify-stable.yml` |
+| `develop` | `Development validation required` on every pull request | `.github/workflows/ci.yml` |
+| `master` | cannot be deleted or force-updated | ruleset only |
+| `refs/tags/v*` | cannot be deleted or moved | ruleset only |
 
-These are job display names. If you rename one, update the ruleset definition, this runbook, and the live ruleset together.
+Publishing is one workflow, `.github/workflows/release.yml`, triggered by pushes
+rather than dispatched by hand.
+
+`develop` is where work lands. `master` records what the npm `latest` tag serves:
+the release fast-forwards it to the commit it published, and nothing else ever
+writes it. There is no promotion to arrange and nothing to keep in sync — `master`
+is an effect of publishing, not a step before it.
 
 ## How much validation runs when
 
@@ -15,53 +22,86 @@ These are job display names. If you rename one, update the ruleset definition, t
 | --- | --- |
 | Docs or specs only | OpenSpec strict lint, nothing else |
 | Any code PR into `develop` | Fast tier: typecheck, architecture checks, unit/contract tests |
-| Preview candidate (`next`) | Fast tier + package gates: content, clean install, dependency policy |
-| Stable candidate (`latest`) | Complete suite on Windows, Linux, and macOS + physical evidence |
-
-Need more coverage for a risky preview? Dispatch the candidate with `full: true`, or run the **Full regression** workflow on demand.
-
-## Publish a preview to npm `next`
+| Preview publish (`next`) | Fast tier + package gates on Windows, Linux, and macOS |
+| Stable publish (`latest`) | Complete suite on Windows, Linux, and macOS |
 
-One command from a clean `develop` checkout runs the whole chain — candidate build, publish, registry verification:
+Need more coverage for something risky? Run the **Full regression** workflow on
+demand.
 
-```sh
-npm run release:next
-```
+## Previews publish themselves
 
-It dispatches the same trusted workflows below and never publishes local bytes. The manual steps remain the reference path:
+Every push to `develop` publishes a preview to the npm `next` tag. Nothing to
+dispatch and nothing to approve.
 
-1. Make sure `Development validation required` is green on the `develop` tip.
-2. Dispatch **Build npm next candidate** with the exact commit and `confirm_candidate=build-uncertified-next-candidate`.
-3. Check the resulting `candidate-evidence.json`: gates passed, package integrity matches.
-4. Approve the `npm-publish` environment and dispatch **Publish npm next** with the candidate run id.
+The version is stamped at publish time — `<major.minor.patch>-dev.<run number>`,
+derived from whatever `package.json` declares — and is never written back to the
+repository. `develop` therefore carries one open prerelease version between
+releases, and no commit is ever spent on a preview.
 
-The publisher uploads the exact validated tarball — it never rebuilds. Candidates expire after 14 days; an expired or mismatched artifact means building a new candidate, not patching the old one.
+One consequence worth knowing: a push that would republish an existing version
+fails early, before anything is packed.
 
-## Publish a stable release to npm `latest`
+## Cutting a stable release
 
-1. Commit the final version to `develop` (clean tree, version not yet on the registry).
-2. Dispatch **Build stable candidate** — it packs once and validates the same bytes on all three platforms.
-3. Dispatch **Certify stable physical platforms** on the dedicated isolated workers (they set `PHYSICAL_WORKER_ISOLATED=true` and run under the `stable-physical` environment). Never run physical host probes on a developer workstation.
-4. Dispatch **Certify stable candidate** with both run ids. `Stable candidate required` passes only when every verdict binds the same commit, version, and digest.
-5. Merge that exact commit to `master`, tag it `v<version>`, and dispatch **Publish npm stable**, then approve `npm-publish`.
+One command, from a clean `develop` that matches its remote:
 
-Stable artifacts expire after 30 days. The same rule as previews applies: publication still requires exact certified bytes. Never upload locally rebuilt bytes, and never route around certification by rebuilding inside a publisher.
+```sh
+npm run release -- patch     # or minor, major, or an exact x.y.z
+```
 
-## When something fails
+It lands `x.y.z` on `develop` through a pull request that merges itself, waits for
+that publication to succeed, and then lands `x.y.(z+1)-dev.0` so previews resume
+immediately. It publishes nothing itself and creates no tag.
 
-- **PR validation fails:** fix the code and push. Do not mark a failed tier optional.
-- **Candidate validation fails:** discard the candidate and build a new one after the fix.
-- **Physical worker fails:** fix or replace the worker, then rerun the full physical evidence for the candidate.
-- **Publisher fails before npm accepted the bytes:** diagnose and retry with the same candidate while it is unexpired and the version is still unpublished.
-- **Publisher is uncertain after npm accepted the bytes:** stop. Check the registry for the version, tag, and digest. Repair a dist-tag only as a separate reviewed operation — never republish.
+Landing the stable version is what publishes. The same pipeline sees a commit
+declaring a stable version and runs its stable form: build the process guardian on
+all three platforms, pack once, run the complete suite against those exact bytes on
+all three platforms, publish to npm `latest` with provenance from the
+`npm-publish` environment, and only then write the tag `vx.y.z`, record the GitHub
+Release, and fast-forward `master`.
 
-## Why the rulesets look the way they do
+That order is the point. A release that fails leaves no tag, no release, and no
+moved branch — only a red run. Nothing ever advertises a version that does not
+exist on the registry.
 
-One person maintains this repository, and GitHub does not let a PR author approve their own PR. Requiring even one approval would therefore deadlock the authorized solo-maintainer path — no PR could ever merge. So both rulesets require a pull request, a green required check, and resolved review threads, but set required approving reviews to zero.
+Rules that do not bend:
 
-- `develop` does not require the branch to be up to date: once a PR is approved and green, it merges even if unrelated work landed first — no re-validation loop.
-- `master` does require it: a stable promotion always validates the exact final state.
+- **Never upload locally rebuilt bytes.** The publisher uploads the artifact the
+  validation ran against, and re-checks its digest before and after.
+- **Never route around validation by rebuilding inside a publisher.** The publish
+  job has no checkout of dependencies, no build, and no pack step.
+- **Never move a release tag.** A wrong tag is superseded by the next version, not
+  repointed. The tag is written by the publication itself, so it exists only for
+  versions that shipped.
 
-If a second maintainer joins, raise the approval count. Do not add a direct-push bypass as a shortcut, and never weaken the force-push or deletion protection.
+## When something fails
 
-Ruleset mutation is a separate administrative operation: run `node scripts/check-github-rulesets.mjs` to see the diff, and apply only when a maintainer explicitly confirms with `--apply --confirm apply-a1-ci-rulesets`.
+- **PR validation fails:** fix the code and push. Do not mark a failed tier optional.
+- **Preview publish fails:** fix and push again; the next push publishes the next
+  run number. Nothing needs cleaning up.
+- **Stable publish fails:** nothing was recorded — no tag, no release, no moved
+  branch. Fix the cause and release the next version. The failed version number is
+  spent, because `develop` has already moved past it.
+- **Stable publish is uncertain after npm accepted the bytes:** stop. Check the
+  registry for the version, tag, and digest. Repair a dist-tag only as a separate
+  reviewed operation — never republish.
+
+## Why the ruleset looks the way it does
+
+One person maintains this repository, and GitHub does not let a PR author approve
+their own PR. Requiring even one approval would deadlock the authorized
+solo-maintainer path — no PR could ever merge. So the `develop` ruleset requires a
+pull request, a green required check, and resolved review threads, but sets required
+approving reviews to zero. It does not require the branch to be up to date: once a
+PR is green it merges even if unrelated work landed first, with no re-validation
+loop.
+
+The `master` and tag rulesets carry no checks at all. Both only ever receive a commit
+that has already been validated and published, so what matters about them is that
+neither can be rewritten. Requiring a pull request on `master` would stop the release
+from recording itself there.
+
+Do not add a direct-push bypass as a shortcut, and never weaken the force-push or
+deletion protection. Ruleset mutation is a separate administrative operation: run
+`node scripts/check-github-rulesets.mjs` to see the diff, and apply only when a
+maintainer explicitly confirms with `--apply --confirm apply-a1-ci-rulesets`.

package/docs/features/launch-profiles.md

@@ -8,6 +8,8 @@
 | `a1 pi` | Untouched vanilla Pi fallback and comparison oracle | ordinary `~/.pi/agent` |
 | `a1 sandbox` | Unchanged isolated vanilla Pi profile for experiments | `~/.a1/sandbox` |
 
+`a1 pi` and `a1 sandbox` are development instruments: one compares A1 against pinned Pi, the other tries resources against an isolated profile. Prerelease builds — what `a1 update:next` installs — expose them. A release build does not, and does not recognize the words: what it exposes is bare `a1` plus the maintenance and package commands. Working in this repository is unaffected, because `npm start:pi` and `npm run start:sandbox` prepare the profile and launch directly rather than through the command line.
+
 There is no `a1 agent` command. The former `a1 ui` subcommand is removed. Bare `a1` is the owned agent product surface and remains the entry point when multi-agent UX is introduced.
 
 ## First launch

package/package.json

@@ -1,12 +1,18 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.1-dev.9",
+  "version": "0.1.5-dev.11",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "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"
+    ]
+  },
   "files": [
     "bin",
     "dist",
@@ -27,8 +33,7 @@
     "check:deprecated": "node scripts/check-deprecated-dependencies.mjs",
     "branches:prune": "node scripts/prune-merged-branches.mjs",
     "check": "npm run test:fast",
-    "publish:next": "tsx scripts/publish-next.ts",
-    "release:next": "node scripts/release-next.mjs",
+    "release": "node scripts/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",