Merge pull request #23 from iiwish/codex/p9-3-stable-surface-gate

[codex] add stable surface regression gate

Author: iiwish

README.md

@@ -245,6 +245,7 @@ Use a local checkout:
 ```bash
 npm ci
 npm run build
+npm run stable:surface:check
 node ./dist/cli/main.js --help
 npm run daemon:verify
 npm run dogfood

README.zh-CN.md

@@ -243,6 +243,7 @@ npx --package agent-cli-runtime agent-runtime conformance --mode fixtures --json
 ```bash
 npm ci
 npm run build
+npm run stable:surface:check
 node ./dist/cli/main.js --help
 npm run daemon:verify
 npm run dogfood

docs/api-schema-contract.md

@@ -61,6 +61,7 @@ Internal but packaged files under `dist/**` may exist in the npm tarball because
 | `agent-cli-runtime.releaseArtifactNormalization.v1` | `schemaVersion`, `ok`, `downloadDir`, `outDir`, `artifacts`, `diagnostics` | `ok`, `diagnostics[].code`, `artifacts[].artifactName` | No absolute local paths; repo-external input/output directories are represented as `<external_artifact_dir>` / `<external_output_dir>`, and only expected release-candidate artifact filenames are copied. |
 | `agent-cli-runtime.mainReleaseCandidateEvidence.v1` | `schemaVersion`, `stage`, `evidenceKind`, `checkedAt`, `releaseTargetSha`, `targetRef`, `mainEvidence`, `branchEvidence`, `historicalMainEvidence`, `compatibilityVerification`, `localReleaseCandidate`, `remoteReleaseCandidate`, `downloadedArtifacts`, `boundary` | `mainEvidence`, `branchEvidence`, `historicalMainEvidence[].historical`, `historicalMainEvidence[].currentMainFreshEvidence`, `compatibilityVerification.ok`, `remoteReleaseCandidate.run.status`, `remoteReleaseCandidate.run.conclusion`, `remoteReleaseCandidate.artifacts.valid`, `downloadedArtifacts.verified` | Repo-only current main summary; historical P8 summaries are listed as historical and non-current; no raw stdout/stderr, workflow logs, prompts, private paths, token-looking values, Bearer values, auth env assignments, tarball shasums, or pack shasums. |
 | `agent-cli-runtime.packageContentEquivalence.v1` | `schemaVersion`, `ok`, `baseRef`, `headRef`, `packageName`, `packageVersion`, `packageContentEqual`, `basePackageDigest`, `headPackageDigest`, `baseFileCount`, `headFileCount`, `changedPackageFiles`, `evidenceOnlyDrift`, `freshReleaseCandidateRequired`, `diagnostics` | `ok`, `packageContentEqual`, `evidenceOnlyDrift`, `freshReleaseCandidateRequired`, `diagnostics[].code`, `changedPackageFiles[].status` | Diagnostics and ref labels are redacted; no temp worktree path, private path, token-looking value, Bearer value, auth env assignment, raw stdout/stderr, workflow log, prompt, tarball shasum, or pack shasum. |
+| `agent-cli-runtime.stableSurfaceCheck.v1` | `schemaVersion`, `ok`, `packageRoot`, `publicTypes`, `schemaInventory`, `cliVocabularies`, `packagedDocs`, `diagnostics`, `boundary` | `ok`, `packageRoot.ok`, `publicTypes.ok`, `schemaInventory.ok`, `cliVocabularies.ok`, `packagedDocs.ok`, `diagnostics[].code`, `boundary.repoOnlyGate`, `boundary.stableSurfaceCheckIsRuntimePublicApi` | Repo-only stable surface gate summary; no raw stdout/stderr, workflow log, prompt, private path, token-looking value, Bearer value, or auth env assignment. |
 
 ## Failure Taxonomy
 
@@ -117,3 +118,5 @@ Downloaded release-candidate artifacts are normalized with `npm run release:arti
 Main release-candidate evidence uses `agent-cli-runtime.mainReleaseCandidateEvidence.v1` and is generated with `npm run release:main-candidate:evidence -- --stage <stage> --release-target-sha <origin-main-sha> --local-release-dir <local-strict-dir> --remote-run-json <run.json> --artifacts-json <artifacts.json> --downloaded-dir <normalized-artifact-dir> --out .release-evidence/<stage-lower>-main-release-candidate.json`. The stage label accepts current phase labels such as `P9-2` and is not tied to P8. The summary binds `releaseTargetSha` to `origin/main`, records local strict compatibility and release verification, records a fresh `release-candidate.yml --ref main` run with matching `headSha`, and lists P8 main release-candidate files only under `historicalMainEvidence` with `historical: true` and `currentMainFreshEvidence: false`.
 
 Package content equivalence uses `agent-cli-runtime.packageContentEquivalence.v1` and is run with `npm run release:package-content:verify -- --base-ref <release-target-sha> --head-ref <sha-or-ref>`. It compares npm package-visible files from temporary git worktrees by package-relative file list, mode, size, and file-content hashes. It does not treat gzip/tarball bytes as the only equivalence signal. Package-external evidence, tests, and repo-only scripts can produce `evidenceOnlyDrift: true` with `freshReleaseCandidateRequired: false`; package-visible README/docs/package.json/dist/types/bin/examples changes produce package content drift and require fresh release-candidate evidence before the head ref is treated as a release target.
+
+Stable surface regression checking uses `agent-cli-runtime.stableSurfaceCheck.v1` and is run with `npm run stable:surface:check` after `npm run build`. It verifies the package-root runtime value export, root declaration boundary, schema inventory documentation, terminal/classification vocabularies, experimental adapter-surface classification, and npm package exclusions for repo-only paths and scripts. This is a beta-candidate repository/release gate, not a runtime public API schema for package consumers.

docs/release-checklist.md

@@ -24,6 +24,8 @@ Run these before treating a future alpha version as a local release candidate:
 npm test
 npm run typecheck
 npm run lint
+npm run build
+npm run stable:surface:check
 npm run package:check
 npm run package:docs:check
 npm run compat:real:evidence:verify
@@ -41,6 +43,8 @@ Acceptance:
 - [x] `npm test` passes.
 - [x] `npm run typecheck` passes.
 - [x] `npm run lint` passes.
+- [x] `npm run build` passes before build-output gates.
+- [x] `npm run stable:surface:check` passes with `schemaVersion: "agent-cli-runtime.stableSurfaceCheck.v1"` and keeps package-root value exports limited to `createAgentRuntime`.
 - [x] `npm run package:check` passes and rejects `.release-evidence/` plus `.reference/` if they appear in pack metadata.
 - [x] `npm run package:docs:check` unpacks the local tarball and rejects stale publish-state claims for this version, dry-run stop wording, publish-ready candidate wording, and old current dist-tag claims.
 - [x] `npm run compat:real:evidence:verify` passes without launching authenticated real agent runs.
@@ -111,7 +115,7 @@ The package must not contain:
 - The package root value export remains `createAgentRuntime`.
 - The schema inventory and versioning policy live in [docs/api-schema-contract.md](./api-schema-contract.md).
 - The daemon/product shell embedding contract lives in [docs/daemon-ready-contract.md](./daemon-ready-contract.md).
-- `agent-cli-runtime.releaseVerification.v1`, `agent-cli-runtime.releaseGateEvidence.v1`, `agent-cli-runtime.mainReleaseCandidateEvidence.v1`, and `agent-cli-runtime.packagedDocsVerification.v1` are release artifact schemas.
+- `agent-cli-runtime.releaseVerification.v1`, `agent-cli-runtime.releaseGateEvidence.v1`, `agent-cli-runtime.mainReleaseCandidateEvidence.v1`, `agent-cli-runtime.packagedDocsVerification.v1`, and `agent-cli-runtime.stableSurfaceCheck.v1` are release or repository gate schemas.
 
 ## Schema Vocabulary
 

docs/release-report.md

@@ -96,6 +96,8 @@ Main-scoped remote release-candidate closure uses `npm run release:main-candidat
 
 Package-content drift review uses `npm run release:package-content:verify -- --base-ref <release-target-sha> --head-ref <sha-or-ref>`. The verifier emits `schemaVersion: "agent-cli-runtime.packageContentEquivalence.v1"` and compares the npm package file list plus file-content hashes for both refs from temporary git worktrees. `.release-evidence/`, tests, and repo-only scripts can change without changing package content; README, README.zh-CN, packaged docs, package.json, dist, type declarations, bin files, examples, and other package-visible files trigger `freshReleaseCandidateRequired: true` when their package content differs. The P8-8 evidence file is `.release-evidence/p8-8-package-content-equivalence.json`. It is a package-content decision, not a replacement for fresh main release-candidate workflow evidence.
 
+Stable surface regression review uses `npm run stable:surface:check` after `npm run build`. The verifier emits `schemaVersion: "agent-cli-runtime.stableSurfaceCheck.v1"` and checks the package-root runtime value export, root declarations, schema inventory docs, terminal/classification vocabularies, experimental adapter-surface classification, and repo-only package exclusions. It is a local repository/release gate; it does not publish npm, create a GitHub Release, launch authenticated real agent runs, or make `dist/**` subpaths public API.
+
 ## Package Boundary
 
 The npm package may include stable docs, examples, `dist/`, and the runtime entrypoints. It must not include:
@@ -123,6 +125,7 @@ The API and CLI schema inventory, versioning policy, root export boundary, and f
 - `agent-cli-runtime.releaseArtifactNormalization.v1`
 - `agent-cli-runtime.mainReleaseCandidateEvidence.v1`
 - `agent-cli-runtime.packageContentEquivalence.v1`
+- `agent-cli-runtime.stableSurfaceCheck.v1`
 - `agent-cli-runtime.realCompatibilityEvidenceVerification.v1`
 - `agent-cli-runtime.realCompatibilityMatrix.v1`
 - `agent-cli-runtime.realCompatibilityEvidence.v1`

docs/stable-readiness.md

@@ -31,6 +31,7 @@ The project remains pre-alpha / developer preview. The labels below describe rea
 | Built-in adapter values, parser helpers, executable resolution, stores, schedulers, task-graph helpers, and storage modules | `internal` | These are implementation details and must not be documented as public API. |
 | Daemon embedding gate and runtime safety gate | `beta-candidate` | `daemon:verify` and `runtime:safety` prove installed-tarball local-kernel behavior with fake CLIs. They do not create a hosted daemon contract. |
 | Release verification, published verification, package-content, packaged-docs, and compatibility evidence schemas | `beta-candidate` | These are repository/release gate contracts. They are not runtime public API for package consumers. |
+| Stable surface regression gate | `beta-candidate` | `npm run stable:surface:check` emits `agent-cli-runtime.stableSurfaceCheck.v1` and verifies package-root exports, public declarations, schema inventory docs, frozen CLI vocabularies, experimental adapter-surface classification, and repo-only package exclusions. It is a repository/release gate, not runtime public API. |
 | Repo-only scripts for release evidence, real compatibility evidence, published verification, package-content equivalence, artifact normalization, and package checks | `internal` | Script outputs can be versioned, but the scripts themselves are repository workflow surfaces, not package-root public contract. |
 | `.release-evidence/`, downloaded verification material, raw workflow logs, and local machine observations | `internal` | These are evidence inputs or summaries outside the npm package boundary. |
 
@@ -62,13 +63,15 @@ This list is synchronized with `src/core/schema-contract.ts`.
 | `agent-cli-runtime.releaseArtifactNormalization.v1` | `beta-candidate` |
 | `agent-cli-runtime.mainReleaseCandidateEvidence.v1` | `beta-candidate` |
 | `agent-cli-runtime.packageContentEquivalence.v1` | `beta-candidate` |
+| `agent-cli-runtime.stableSurfaceCheck.v1` | `beta-candidate` |
 
 ## Stable Gaps
 
 - `getAdapter` and `RuntimeOptions.adapters` remain `experimental`; adapter authoring needs real external consumer dogfood before any stable promise.
 - Internal `dist/**` subpath imports remain unsupported, even when those files appear in the tarball.
 - CLI JSON schemas have a versioning policy, but command removal or flag semantic changes still need an explicit pre-alpha breaking-change note.
 - Release evidence schemas are repository and release-gate contracts; they do not become runtime public API for package consumers.
+- `agent-cli-runtime.stableSurfaceCheck.v1` is a repository/release gate schema; it does not become runtime public API for package consumers.
 - Codex `session` and `authProbe` remain in `needsVerification`.
 - Claude Code `session.id` and `reasoning` remain in `needsVerification`.
 - OpenCode `extraAllowedDirs`, `session`, and `permissionPolicy.read-only` remain in `needsVerification`.

package.json

@@ -47,14 +47,14 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "ci": "npm run typecheck && npm run lint && npm test && npm run build && npm audit --omit=dev && npm run package:check && npm pack --dry-run",
+    "ci": "npm run typecheck && npm run lint && npm test && npm run build && npm run stable:surface:check && npm audit --omit=dev && npm run package:check && npm pack --dry-run",
     "compat:real:evidence": "node ./scripts/create-real-compatibility-evidence.mjs",
     "compat:real:evidence:verify": "node ./scripts/verify-real-compatibility-evidence.mjs",
     "daemon:verify": "node ./scripts/verify-daemon-ready.mjs",
     "dogfood": "node ./scripts/dogfood.mjs",
     "package:check": "node ./scripts/check-package-boundary.mjs && node ./scripts/check-packaged-docs.mjs",
     "package:docs:check": "node ./scripts/check-packaged-docs.mjs",
-    "prepublish:check": "npm run typecheck && npm run lint && npm test && npm run build && npm run daemon:verify && npm run runtime:safety && npm run compat:real:evidence:verify && npm run dogfood && npm audit --omit=dev && npm run package:check && npm pack --dry-run",
+    "prepublish:check": "npm run typecheck && npm run lint && npm test && npm run build && npm run stable:surface:check && npm run daemon:verify && npm run runtime:safety && npm run compat:real:evidence:verify && npm run dogfood && npm audit --omit=dev && npm run package:check && npm pack --dry-run",
     "prepack": "npm run build",
     "published:adapters:verify": "node ./scripts/verify-published-adapters.mjs",
     "published:daemon:verify": "node ./scripts/verify-published-daemon-consumer.mjs",
@@ -70,6 +70,7 @@
     "release:verify": "node ./scripts/verify-release-artifacts.mjs",
     "runtime:safety": "node ./scripts/verify-runtime-safety.mjs",
     "smoke:published": "node ./scripts/smoke-published.mjs",
+    "stable:surface:check": "node ./scripts/check-stable-surface.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && vitest run --reporter=verbose --no-file-parallelism --testTimeout 30000"