Merge pull request #21 from iiwish/codex/p9-2-main-release-evidence

[codex] Generalize main release evidence tooling

Author: iiwish

.release-evidence/README.md

@@ -14,7 +14,7 @@ For a fresh alpha release-candidate review:
    ```
    The normalizer emits `schemaVersion: "agent-cli-runtime.releaseArtifactNormalization.v1"`, copies only `npm-pack.json`, `package-files.txt`, `gate-evidence.json`, `release-verification.json`, and `agent-cli-runtime-*.tgz`, and rejects missing, duplicate, or unknown files without printing absolute local paths. The `agent-cli-runtime-gate-evidence` artifact must include `daemon:verify`, `runtime:safety`, and `compat:real:evidence:verify`. Remote clean-checkout workflow artifacts record repo-only real compatibility evidence as `repo_only_not_run` / `not_refreshed_in_ci`; local strict release evidence is required when the release conclusion depends on the P8-2 matrix matching the target SHA.
 4. Run `npm run release:verify -- --dir <normalized-artifact-dir>`.
-5. Record the run URL, head SHA, artifact list, verification result, local gate results, and go/no-go decision in a local evidence file under this directory. Main-scoped P8 evidence 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`.
+5. Record the run URL, head SHA, artifact list, verification result, local gate results, and go/no-go decision in a local evidence file under this directory. Main-scoped evidence 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`; current stage labels such as `P9-2` are valid and the output schema is `agent-cli-runtime.mainReleaseCandidateEvidence.v1`.
 
 If the commit under review has not reached `main` / `origin/main`, record the evidence explicitly as branch evidence. Use the branch ref in `gh workflow run release-candidate.yml --ref <branch>`, confirm the workflow `headSha` equals the branch target SHA, and keep `mainEvidence: false` plus the observed `originMainShaAtTrigger` in the evidence file. Do not describe branch evidence as current `main` release evidence.
 
@@ -68,4 +68,6 @@ P8-9 uses `.release-evidence/p8-9-main-release-candidate.json` for the fresh mai
 
 P8-8 uses `.release-evidence/p8-8-package-content-equivalence.json` for repo-only package content drift review between a recorded release target SHA and a later ref. Generate it with `npm run release:package-content:verify -- --base-ref <release-target-sha> --head-ref <sha-or-ref> --out .release-evidence/p8-8-package-content-equivalence.json`. The verifier emits `schemaVersion: "agent-cli-runtime.packageContentEquivalence.v1"` and compares npm package file lists plus per-file content hashes from temporary git worktrees. It does not use gzip/tarball bytes as the only equivalence signal. If package-visible files differ, record `packageContentEqual: false` and `freshReleaseCandidateRequired: true`. If changes are limited to package-external evidence, tests, or repo-only scripts, record `packageContentEqual: true`, `evidenceOnlyDrift: true`, and `freshReleaseCandidateRequired: false`. P8-8 does not turn a later HEAD into P8-7 workflow evidence; it only determines whether package content is equal. It must not include raw stdout/stderr, workflow logs, full prompts, token values, Bearer values, auth env assignment values, private absolute paths, local temp paths, worktree paths, tarball shasums, or pack shasums.
 
+P9-2 and later main-scoped evidence uses the stage-neutral generator schema `agent-cli-runtime.mainReleaseCandidateEvidence.v1`. P8 main evidence files remain readable historical exact-SHA evidence; stage-neutral summaries list them as `historicalMainEvidence` with `currentMainFreshEvidence: false` so they are not mistaken for current main evidence after package-visible changes.
+
 Do not put `.reference/`, temporary download directories, private user paths, CI tokens, npm tokens, or real provider tokens in this directory.

README.md

@@ -414,6 +414,8 @@ Main-scoped release-candidate evidence 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 generator emits `schemaVersion: "agent-cli-runtime.mainReleaseCandidateEvidence.v1"`. Stage labels such as `P9-2` are accepted; P8 main evidence files remain historical exact-SHA evidence and are not current fresh main evidence for later package-visible changes.
+
 Package-content equivalence between a recorded release target SHA and a later ref is checked with:
 
 ```bash
@@ -422,7 +424,7 @@ npm run release:package-content:verify -- --base-ref <release-target-sha> --head
 
 The verifier emits `schemaVersion: "agent-cli-runtime.packageContentEquivalence.v1"` and compares npm package-visible file lists plus per-file content hashes from temporary git worktrees. It does not rely on gzip/tarball bytes as the only signal. Package-external `.release-evidence/`, tests, and repo-only script changes can be recorded as `evidenceOnlyDrift: true` with `freshReleaseCandidateRequired: false`; README, packaged docs, package.json, dist, types, bin, examples, and other package-visible changes require fresh release-candidate evidence before the later ref is treated as a release target.
 
-The release evidence summary is [docs/release-report.md](./docs/release-report.md), with volatile P8-4 target-SHA evidence under `.release-evidence/p8-4-release-strict-compatibility.json`, historical P8-5 main remote evidence under `.release-evidence/p8-5-main-release-candidate.json`, and current P8-7 fresh main evidence under `.release-evidence/p8-7-main-release-candidate.json`. The alpha publish decision runbook is [docs/release-publish-runbook.md](./docs/release-publish-runbook.md). `npm publish --dry-run --ignore-scripts --tag alpha` is documented there as a local manual dry-run check; it must not publish and is not required as a remote CI gate. Published package verification is a separate manual post-publish workflow, not a publish workflow.
+The release evidence summary is [docs/release-report.md](./docs/release-report.md), with volatile P8-4 target-SHA evidence under `.release-evidence/p8-4-release-strict-compatibility.json` and historical P8 main remote evidence under `.release-evidence/p8-5-main-release-candidate.json`, `.release-evidence/p8-7-main-release-candidate.json`, and `.release-evidence/p8-9-main-release-candidate.json`. The alpha publish decision runbook is [docs/release-publish-runbook.md](./docs/release-publish-runbook.md). `npm publish --dry-run --ignore-scripts --tag alpha` is documented there as a local manual dry-run check; it must not publish and is not required as a remote CI gate. Published package verification is a separate manual post-publish workflow, not a publish workflow.
 
 Main-scoped evidence proves only its recorded `releaseTargetSha`; an evidence-recording commit or later PR merge commit needs its own fresh main evidence before it can be used as a release target.
 

README.zh-CN.md

@@ -412,6 +412,8 @@ Main-scoped release-candidate evidence 通过以下命令生成：
 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
 ```
 
+该 generator 输出 `schemaVersion: "agent-cli-runtime.mainReleaseCandidateEvidence.v1"`。`P9-2` 这类阶段名是有效标签；P8 main evidence 文件只保留为 exact-SHA historical evidence，不作为后续 package-visible 变化的当前 fresh main evidence。
+
 记录过的 release target SHA 与后续 ref 的 package-content equivalence 通过以下命令判断：
 
 ```bash
@@ -420,7 +422,7 @@ npm run release:package-content:verify -- --base-ref <release-target-sha> --head
 
 该 verifier 输出 `schemaVersion: "agent-cli-runtime.packageContentEquivalence.v1"`，通过临时 git worktree 收集两个 refs 的 npm package 可见文件列表和逐文件内容 hash，不把 gzip/tarball bytes 当作唯一判定依据。`.release-evidence/`、tests 和 repo-only scripts 这类包外变化可以记录为 `evidenceOnlyDrift: true` 且 `freshReleaseCandidateRequired: false`；README、packaged docs、package.json、dist、types、bin、examples 和其它 package-visible 内容变化会要求在把后续 ref 当作 release target 前生成 fresh release-candidate evidence。
 
-Release evidence summary 见 [docs/release-report.md](./docs/release-report.md)，易漂移的 P8-4 target-SHA evidence 保存在 `.release-evidence/p8-4-release-strict-compatibility.json`，历史 P8-5 main remote evidence 保存在 `.release-evidence/p8-5-main-release-candidate.json`，当前 P8-7 fresh main evidence 保存在 `.release-evidence/p8-7-main-release-candidate.json`，alpha publish decision runbook 见 [docs/release-publish-runbook.md](./docs/release-publish-runbook.md)。`npm publish --dry-run --ignore-scripts --tag alpha` 只作为本地手动 dry-run check 记录在这些文档中；它不得真的 publish，也不作为远端 CI 必选 gate。Published package verification 是单独的手动 post-publish workflow，不是 publish workflow。
+Release evidence summary 见 [docs/release-report.md](./docs/release-report.md)，易漂移的 P8-4 target-SHA evidence 保存在 `.release-evidence/p8-4-release-strict-compatibility.json`，历史 P8 main remote evidence 保存在 `.release-evidence/p8-5-main-release-candidate.json`、`.release-evidence/p8-7-main-release-candidate.json` 和 `.release-evidence/p8-9-main-release-candidate.json`，alpha publish decision runbook 见 [docs/release-publish-runbook.md](./docs/release-publish-runbook.md)。`npm publish --dry-run --ignore-scripts --tag alpha` 只作为本地手动 dry-run check 记录在这些文档中；它不得真的 publish，也不作为远端 CI 必选 gate。Published package verification 是单独的手动 post-publish workflow，不是 publish workflow。
 
 Main-scoped evidence 只证明其记录的 `releaseTargetSha`；记录 evidence 的提交或后续 PR merge commit 要作为 release target 时，需要重新生成 fresh main evidence。
 

docs/api-schema-contract.md

@@ -59,6 +59,7 @@ Internal but packaged files under `dist/**` may exist in the npm tarball because
 | `agent-cli-runtime.releaseVerification.v1` | `schemaVersion`, `ok`, `checkedFiles`, `tarball`, `diagnostics`, `artifactNames`, `gateEvidence`, `packageName`, `version` | `ok`, `diagnostics[].code` | Diagnostics are redacted; no private package paths, token-looking values, Bearer values, auth env assignments, npm token references, repo-only real compatibility evidence scripts, repo-only package content scripts, or disallowed package paths. |
 | `agent-cli-runtime.releaseGateEvidence.v1` | `schemaVersion`, `generatedAt`, `gates`, `noAuthenticatedRealRun`, `noNpmPublish`, `noNpmToken` | `gates[].ok`, `gates[].outputSchemaVersion`, `gates[].packageSource`, `gates[].evidenceSchemaVersion`, `gates[].targetSha.status`, `gates[].freshness.status`, `gates[].dirtyPolicy.status`, `gates[].diagnostics.codes`, `gates[].repoOnlyEvidence.status` | No authenticated real run output, npm token references, raw paths, prompts, secrets, raw evidence files, raw stdout/stderr, or diagnostic messages. |
 | `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. |
 
 ## Failure Taxonomy
@@ -113,4 +114,6 @@ Release gates do not refresh real CLI evidence. `npm run prepublish:check` runs
 
 Downloaded release-candidate artifacts are normalized with `npm run release:artifacts:normalize -- --download-dir <gh-download-dir> --out-dir <normalized-artifact-dir>` before `release:verify`. The normalizer copies only `npm-pack.json`, `package-files.txt`, `gate-evidence.json`, `release-verification.json`, and `agent-cli-runtime-*.tgz` from their expected `gh run download` artifact directories; missing, duplicate, unknown, or misplaced files produce stable `agent-cli-runtime.releaseArtifactNormalization.v1` JSON diagnostics. It does not inspect package contents and does not replace `agent-cli-runtime.releaseVerification.v1`.
 
+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.