@timurproko/a1 0.1.8-dev.0aceebe → 0.1.8-dev.112

package/docs/ci-release-runbook.md

@@ -5,107 +5,104 @@ GitHub Actions is the only automation platform. Three refs are protected:
 | Ref | Protection | Produced by |
 | --- | --- | --- |
 | `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 |
+| `master` | cannot be deleted or force-updated | stable publication |
+| `refs/tags/v*` | cannot be deleted or moved | stable publication |
 
-Publishing is one workflow, `.github/workflows/release.yml`, triggered by pushes
-rather than dispatched by hand.
+`.github/workflows/release.yml` is the only publisher. A push publishes neither
+channel. The workflow starts at `03:17 UTC` for nightly development verification,
+or by explicit dispatch from `npm run develop` or `npm run release`.
 
-`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.
+`develop` is where work lands. `master` records what npm `latest` serves and is an
+effect of stable publication, not a trigger.
 
-## How much validation runs when
+## Validation by trigger
 
-| Change | Validation |
+| Trigger | Validation and outcome |
 | --- | --- |
-| Docs or specs only | OpenSpec strict lint, nothing else |
-| Any code PR into `develop` | Fast tier: typecheck, architecture checks, unit/contract tests |
-| Preview publish (`next`) | Fast tier + package gates on Windows, Linux, and macOS |
-| Stable publish (`latest`) | Complete suite on Windows, Linux, and macOS |
+| Pull request into `develop` | Fast required validation; docs/spec-only changes use strict OpenSpec validation |
+| `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` | 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` |
+| `.github/workflows/full-regression.yml` | Additional on-demand complete regression without publication authority |
 
-Need more coverage for something risky? Run the **Full regression** workflow on
-demand.
+## Numbered development previews
 
-## Previews publish themselves
+A merge or push to `develop` does not publish by itself. To request a deliberate
+preview from any authorized checkout:
 
-Every push to `develop` publishes a preview to the npm `next` tag. Nothing to
-dispatch and nothing to approve.
+```sh
+npm run develop
+```
+
+The command fetches authoritative `origin/develop`, resolves the unique merged pull
+request associated with that exact commit through GitHub, and derives
+`<major.minor.patch>-dev.<pull-request number>`. Thus GitHub's `develop (#107)`
+source produces `0.1.8-dev.107`. It first checks npm; if the immutable version
+already exists it reports that version without dispatching package work. Otherwise
+it dispatches GitHub Actions, waits, and reports the published version. It never
+builds or uploads npm bytes from the workstation.
+
+Nightly resolves the same current `origin/develop` source. It always runs complete
+verification even if source has not changed. For a new number it packs once and
+runs the suite against that final-version tarball before publication. For an
+existing number it downloads the exact npm tarball and runs package/update gates
+against those registry bytes; publication is then a successful no-op.
+
+Manual and nightly runs share one non-cancelling concurrency group. Their final
+registry check is serialized, so overlapping requests can produce only one publish
+and one successful existing-version no-op. A development publication moves npm's
+internal `next` dist-tag and never moves `latest`.
+
+Users install previews with public `develop` terminology:
 
-The version is stamped at publish time — `<major.minor.patch>-dev.<short commit>`,
-the base taken from whatever `package.json` declares and the suffix from the commit
-being published — and is never written back to the repository. An installed preview
-therefore names the exact source it came from, and rebuilding a commit produces the
-same version rather than a new one. That suffix is also how a specific preview is
-installed: `a1 update:<commit>` resolves it against the published list and
-refuses a commit that was never published. `develop` therefore carries one open prerelease version between
-releases, and no commit is ever spent on a preview.
+```sh
+a1 update:develop       # current development channel
+a1 update:107           # numbered preview
+a1 update:0.1.8-dev.107 # exact full preview version
+```
 
-One consequence worth knowing: a push that would republish an existing version
-fails early, before anything is packed.
+`a1 update:next` is removed and redirects to `a1 update:develop` without registry
+or runtime work.
 
 ## Cutting a stable release
 
-One command, from a clean `develop` that matches its remote:
+From a clean `develop` matching its remote:
 
 ```sh
 npm run release -- patch     # or minor, major, or an exact x.y.z
 ```
 
-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` so previews resume
-immediately. It publishes nothing itself and creates no tag.
-
-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`.
+The command lands `x.y.z` through its version pull request, explicitly dispatches
+stable publication for that exact current `origin/develop` commit, and waits. Only
+after success does it land `x.y.(z+1)-dev`.
 
-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.
+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.
 
 Rules that do not bend:
 
-- **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.
+- **Never upload locally rebuilt bytes.** The publisher uploads the artifact the validation ran against and checks its digest before and after.
+- **Never route around validation by rebuilding inside a publisher.** The publish job receives the packed artifact and does not install dependencies, build, or pack.
+- **Never move a release tag.** A wrong tag is superseded by the next version, not repointed.
 
 ## When something fails
 
-- **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`.
+- **PR validation fails:** fix the code and push; do not mark a failed tier optional.
+- **Development publication fails:** fix the cause and rerun `npm run develop`; an npm version that already exists is never overwritten.
+- **Stable publication fails before npm accepts bytes:** no tag, release, or moved branch exists. Fix the cause and release the next version.
+- **Stable publication is uncertain after npm accepted bytes:** stop and inspect registry version, digest, tag, and release. Never republish immutable bytes.
+
+## Branch protection rationale
+
+One person maintains this repository, and a PR author cannot approve their own PR.
+The `develop` ruleset therefore requires a pull request, a green required check,
+and resolved review threads, but zero approving reviews. `master` and release tags
+are written only after publication and are protected from force-push, movement, and
+deletion.
+
+Do not add direct-push bypasses. Ruleset mutation remains a separate administrative
+operation: inspect with `node scripts/check-github-rulesets.mjs`, and apply only
+with explicit maintainer confirmation.

package/docs/features/launch-profiles.md

@@ -8,7 +8,7 @@
 | `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.
+`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:develop` or `a1 update:<number>` 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.
 

package/docs/manual-transparent-checkpoint.md

@@ -50,4 +50,4 @@ Report failures with direct-versus-A1 behavior, platform/terminal versions, exac
 
 For recovery, use `a1 pi`; do not use the removed `a1 ui` command. `a1 sandbox` remains profile isolation rather than a security boundary.
 
-Manual acceptance can authorize an exact uncertified npm `next` preview after non-desktop gates pass. It does not certify stable terminal parity or platform support.
+Manual acceptance can authorize an exact uncertified development preview after non-desktop gates pass. It does not certify stable terminal parity or platform support.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.8-dev.0aceebe",
+  "version": "0.1.8-dev.112",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "packageManager": "npm@11.13.0",
@@ -33,6 +33,7 @@
     "check:deprecated": "node scripts/check-deprecated-dependencies.mjs",
     "branches:prune": "node scripts/prune-merged-branches.mjs",
     "check": "npm run test:fast",
+    "develop": "node scripts/develop.mjs",
     "release": "node scripts/release.mjs",
     "test": "npm run test:fast",
     "test:fast": "node scripts/run-validation-tier.mjs typecheck fast",
@@ -57,6 +58,7 @@
   "dependencies": {
     "@earendil-works/pi-coding-agent": "0.84.2",
     "@earendil-works/pi-tui": "0.84.2",
+    "chalk": "5.6.2",
     "cross-spawn": "7.0.6",
     "grok-mermaid": "0.2.2",
     "semver": "7.8.5"

package/dist/src/foundation/release/development-preview-release.d.ts

@@ -1,49 +0,0 @@
-export declare const PREVIEW_RELEASE_SCHEMA: string;
-export interface DevelopmentPreviewCandidate {
-    readonly version: string;
-    readonly requiresVersionCommit: boolean;
-}
-export interface DevelopmentPreviewRegistryState {
-    readonly published: boolean;
-    readonly nextVersion: string | null;
-}
-export interface DevelopmentPreviewVerificationOptions {
-    readonly attempts?: number;
-    readonly delayMs?: number;
-    readonly delay?: (milliseconds: number) => Promise<void>;
-}
-export interface DevelopmentPreviewPublishResult {
-    readonly published: boolean;
-    readonly recoveredPublishError: unknown | null;
-}
-export interface UncertifiedDevelopmentPreviewEvidenceInput {
-    readonly packageName: string;
-    readonly version: string;
-    readonly commit: string;
-    readonly tarball: string;
-    readonly integrity: string;
-    readonly shasum: string;
-    readonly platform: NodeJS.Platform;
-    readonly architecture: string;
-    readonly recordedAt: string;
-}
-export interface UncertifiedDevelopmentPreviewEvidence extends UncertifiedDevelopmentPreviewEvidenceInput {
-    readonly schema: typeof PREVIEW_RELEASE_SCHEMA;
-    readonly channel: "next";
-    readonly certificationStatus: "uncertified-development-preview";
-    readonly terminalCapability: "owned-ui";
-    readonly manualAcceptance: "accepted";
-    readonly physicalHostCertification: "deferred";
-    readonly crossPlatformCertification: "deferred";
-    readonly stableReleaseEligible: false;
-}
-export declare function createUncertifiedDevelopmentPreviewEvidence(input: UncertifiedDevelopmentPreviewEvidenceInput): UncertifiedDevelopmentPreviewEvidence;
-export declare function requireManuallyAcceptedDevelopmentPreview(version: string, acceptedVersion: string): void;
-export declare function selectDevelopmentPreviewCandidate(currentVersion: string, publishedVersions: readonly string[]): DevelopmentPreviewCandidate;
-/**
- * Treats npm's process result as provisional: browser-auth completion can fail
- * after the immutable upload succeeds. Registry identity remains authoritative.
- */
-export declare function publishDevelopmentPreviewWithRecovery(publish: () => Promise<void>, verify: () => Promise<void>): Promise<DevelopmentPreviewPublishResult>;
-export declare function verifyDevelopmentPreviewRegistry(version: string, observe: () => Promise<DevelopmentPreviewRegistryState>, repairNextTag: () => Promise<void>, options?: DevelopmentPreviewVerificationOptions): Promise<void>;
-export declare function developmentPreviewTarballName(packageName: string, version: string): string;

package/dist/src/foundation/release/development-preview-release.js

@@ -1,114 +0,0 @@
-import { compare, inc, prerelease, valid } from "semver";
-import { PRODUCT_IDENTITY } from "../../product-identity.js";
-export const PREVIEW_RELEASE_SCHEMA = PRODUCT_IDENTITY.evidence.previewReleaseSchema;
-export function createUncertifiedDevelopmentPreviewEvidence(input) {
-    const prereleaseParts = prerelease(input.version);
-    if (valid(input.version) === null || prereleaseParts?.[0] !== "dev") {
-        throw new Error(`uncertified preview requires a development prerelease: ${input.version}`);
-    }
-    return {
-        schema: PREVIEW_RELEASE_SCHEMA,
-        channel: "next",
-        certificationStatus: "uncertified-development-preview",
-        terminalCapability: "owned-ui",
-        manualAcceptance: "accepted",
-        physicalHostCertification: "deferred",
-        crossPlatformCertification: "deferred",
-        stableReleaseEligible: false,
-        ...input,
-    };
-}
-export function requireManuallyAcceptedDevelopmentPreview(version, acceptedVersion) {
-    const acceptedPrerelease = prerelease(acceptedVersion);
-    if (valid(acceptedVersion) === null || acceptedPrerelease?.[0] !== "dev") {
-        throw new Error(`invalid manually accepted development preview: ${acceptedVersion}`);
-    }
-    if (version !== acceptedVersion) {
-        throw new Error(`development preview ${version} has no exact manual acceptance; accepted version is ${acceptedVersion}`);
-    }
-}
-export function selectDevelopmentPreviewCandidate(currentVersion, publishedVersions) {
-    if (valid(currentVersion) === null)
-        throw new Error(`invalid current package version: ${currentVersion}`);
-    const published = publishedVersions.map(version => {
-        if (valid(version) === null)
-            throw new Error(`invalid published package version: ${version}`);
-        return version;
-    });
-    const publishedSet = new Set(published);
-    const highestPublished = published.reduce((highest, version) => highest === null || compare(version, highest) > 0 ? version : highest, null);
-    const currentPrerelease = prerelease(currentVersion);
-    const currentIsUnpublishedLeadingDev = currentPrerelease?.[0] === "dev"
-        && !publishedSet.has(currentVersion)
-        && (highestPublished === null || compare(currentVersion, highestPublished) > 0);
-    if (currentIsUnpublishedLeadingDev)
-        return { version: currentVersion, requiresVersionCommit: false };
-    const base = highestPublished === null || compare(currentVersion, highestPublished) > 0
-        ? currentVersion
-        : highestPublished;
-    const basePrerelease = prerelease(base);
-    let candidate = basePrerelease?.[0] === "dev"
-        ? inc(base, "prerelease", "dev")
-        : inc(base, "prepatch", "dev");
-    if (candidate === null)
-        throw new Error(`could not increment development preview from ${base}`);
-    while (publishedSet.has(candidate)) {
-        candidate = inc(candidate, "prerelease", "dev");
-        if (candidate === null)
-            throw new Error(`could not increment development preview from ${base}`);
-    }
-    return { version: candidate, requiresVersionCommit: candidate !== currentVersion };
-}
-/**
- * Treats npm's process result as provisional: browser-auth completion can fail
- * after the immutable upload succeeds. Registry identity remains authoritative.
- */
-export async function publishDevelopmentPreviewWithRecovery(publish, verify) {
-    let publishError = null;
-    try {
-        await publish();
-    }
-    catch (error) {
-        publishError = error;
-    }
-    try {
-        await verify();
-        return { published: true, recoveredPublishError: publishError };
-    }
-    catch (verificationError) {
-        if (publishError !== null)
-            throw new AggregateError([publishError, verificationError], "npm publish failed and the exact version could not be verified in the registry");
-        throw verificationError;
-    }
-}
-export async function verifyDevelopmentPreviewRegistry(version, observe, repairNextTag, options = {}) {
-    const attempts = options.attempts ?? 12;
-    const delayMs = options.delayMs ?? 2_000;
-    const delay = options.delay ?? (async (milliseconds) => await new Promise(resolvePromise => setTimeout(resolvePromise, milliseconds)));
-    if (!Number.isInteger(attempts) || attempts < 1)
-        throw new Error(`invalid registry verification attempts: ${attempts}`);
-    let repaired = false;
-    let last = { published: false, nextVersion: null };
-    for (let attempt = 1; attempt <= attempts; attempt += 1) {
-        last = await observe();
-        if (last.published && last.nextVersion === version)
-            return;
-        if (last.published && !repaired) {
-            await repairNextTag();
-            repaired = true;
-        }
-        if (attempt < attempts)
-            await delay(delayMs);
-    }
-    if (!last.published)
-        throw new Error(`npm registry did not expose published version ${version} after ${attempts} attempts`);
-    throw new Error(`npm next resolved ${last.nextVersion ?? "nothing"}; expected ${version} after ${attempts} attempts`);
-}
-export function developmentPreviewTarballName(packageName, version) {
-    if (valid(version) === null)
-        throw new Error(`invalid development preview version: ${version}`);
-    const unscopedName = packageName.startsWith("@") ? packageName.slice(1).replace("/", "-") : packageName;
-    if (!/^[a-z0-9._-]+$/i.test(unscopedName))
-        throw new Error(`invalid package name: ${packageName}`);
-    return `${unscopedName}-${version}.tgz`;
-}