docs: add release publication readiness gate (#1786)

docs/ECC-2.0-GA-ROADMAP.md

@@ -27,6 +27,9 @@ As of 2026-05-12:
 - `npm run harness:adapters -- --check` validates that the public adapter
   matrix still matches the source data in
   `scripts/lib/harness-adapter-compliance.js`.
+- `docs/releases/2.0.0-rc.1/publication-readiness.md` gates GitHub release,
+  npm dist-tag, Claude plugin, Codex plugin, OpenCode package, billing, and
+  announcement publication on fresh evidence fields.
 - AgentShield PR #53 reduced two context-rule false positives and closed the
   remaining AgentShield issues.
 - ECC PR #1778 recovered the useful stale #1413 network/homelab architect-agent
@@ -182,12 +185,11 @@ Acceptance:
 
 ## Next Engineering Slices
 
-1. Add the release/name/plugin publication checklist with evidence fields.
+1. Start AgentShield enterprise policy schema and SARIF implementation in the
-2. Start AgentShield enterprise policy schema and SARIF implementation in the
    AgentShield repo.
-3. Audit ECC Tools billing and check-run surfaces before any native GitHub
+2. Audit ECC Tools billing and check-run surfaces before any native GitHub
    payments announcement.
-4. Inventory `_legacy-documents-*` and map useful artifacts to landed,
+3. Inventory `_legacy-documents-*` and map useful artifacts to landed,
    milestone-tracked, salvage, or archive states.
-5. Build the stale-PR salvage ledger from closed cleanup batches, then port
+4. Build the stale-PR salvage ledger from closed cleanup batches, then port
    useful pieces in small attributed maintainer PRs.

docs/releases/2.0.0-rc.1/launch-checklist.md

@@ -13,6 +13,7 @@
 
 - verify package, plugin, marketplace, OpenCode, and agent metadata stays at `2.0.0-rc.1`
 - verify `ecc2/Cargo.toml` stays at `0.1.0` for rc.1; `ecc2/` remains an alpha control-plane scaffold
+- complete `publication-readiness.md` with fresh evidence before any GitHub release, npm publish, plugin submission, or announcement post
 - update release metadata in one dedicated release-version PR
 - run the root test suite
 - run `cd ecc2 && cargo test`

docs/releases/2.0.0-rc.1/publication-readiness.md

@@ -0,0 +1,73 @@
+# ECC v2.0.0-rc.1 Publication Readiness
+
+This checklist is the release gate for public publication surfaces. Do not use
+it as evidence by itself. Fill the evidence fields with fresh command output or
+URLs from the exact commit being released.
+
+## Release Identity Matrix
+
+| Surface | Expected value | Source of truth | Fresh check | Evidence artifact | Owner | Status |
+| --- | --- | --- | --- | --- | --- | --- |
+| Product name | Everything Claude Code / ECC | `README.md`, `CHANGELOG.md`, release notes | `rg -n "Everything Claude Code" README.md CHANGELOG.md docs/releases/2.0.0-rc.1` | Pending | Release owner | Pending |
+| GitHub repo | `affaan-m/everything-claude-code` | Git remote and release URLs | `git remote get-url origin` | Pending | Release owner | Pending |
+| Git tag | `v2.0.0-rc.1` | GitHub releases | `gh release view v2.0.0-rc.1 --repo affaan-m/everything-claude-code` | Pending | Release owner | Pending |
+| npm package | `ecc-universal` | `package.json` | `node -p "require('./package.json').name"` | Pending | Package owner | Pending |
+| npm version | `2.0.0-rc.1` | `VERSION`, `package.json`, lockfiles | `node -p "require('./package.json').version"` | Pending | Package owner | Pending |
+| npm dist-tag | `next` for rc, `latest` only for GA | npm registry | `npm view ecc-universal dist-tags --json` | Pending | Package owner | Pending |
+| Claude plugin slug | `ecc` / `ecc@ecc` install path | `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` | `node tests/hooks/hooks.test.js` | Pending | Plugin owner | Pending |
+| Claude plugin manifest | `2.0.0-rc.1`, no unsupported `agents` or explicit `hooks` fields | `.claude-plugin/plugin.json`, `.claude-plugin/PLUGIN_SCHEMA_NOTES.md` | `claude plugin validate .claude-plugin/plugin.json` | Pending | Plugin owner | Pending |
+| Codex plugin manifest | `2.0.0-rc.1` with shared skill source | `.codex-plugin/plugin.json` | `node tests/docs/ecc2-release-surface.test.js` | Pending | Plugin owner | Pending |
+| OpenCode package | `ecc-universal` plugin module | `.opencode/package.json`, `.opencode/index.ts` | `npm run build:opencode` | Pending | Package owner | Pending |
+| Agent metadata | `2.0.0-rc.1` | `agent.yaml`, `.agents/plugins/marketplace.json` | `node tests/scripts/catalog.test.js` | Pending | Release owner | Pending |
+| Migration copy | rc.1 upgrade path, not GA claim | `release-notes.md`, `quickstart.md`, `HERMES-SETUP.md` | `npx markdownlint-cli docs/releases/2.0.0-rc.1/*.md` | Pending | Docs owner | Pending |
+
+## Publication Gates
+
+| Gate | Required evidence | Fresh check | Blocker field | Owner | Status |
+| --- | --- | --- | --- | --- | --- |
+| GitHub release | Tag exists, release notes use final URLs, assets attached if needed | `gh release view v2.0.0-rc.1 --json tagName,url,isPrerelease` | `Blocker:` | Release owner | Pending |
+| npm package | `npm pack --dry-run` has expected files, version matches, rc goes to `next` | `npm pack --dry-run` and `npm publish --tag next --dry-run` where supported | `Blocker:` | Package owner | Pending |
+| Claude plugin | Manifest validates, marketplace JSON points to public repo, install docs match slug | `claude plugin validate .claude-plugin/plugin.json` | `Blocker:` | Plugin owner | Pending |
+| Codex plugin | Manifest version matches package and docs, hook limitations are explicit | `node tests/docs/ecc2-release-surface.test.js` | `Blocker:` | Plugin owner | Pending |
+| OpenCode package | Build output is regenerated from source and package metadata is current | `npm run build:opencode` | `Blocker:` | Package owner | Pending |
+| ECC Tools billing reference | Any billing claim links to verified Marketplace/App state | `gh api repos/ECC-Tools/ECC-Tools` plus app/marketplace URL check | `Blocker:` | ECC Tools owner | Pending |
+| Announcement copy | X, LinkedIn, GitHub release, and longform copy point to live URLs | `rg -n "TODO" docs/releases/2.0.0-rc.1` and repeat for `TBD` | `Blocker:` | Release owner | Pending |
+
+## Required Command Evidence
+
+Record the exact commit SHA and command output before any publication action:
+
+| Evidence | Command | Required result | Recorded output |
+| --- | --- | --- | --- |
+| Clean release branch | `git status --short --branch` | On intended release commit; no unrelated files | Pending |
+| Harness audit | `npm run harness:audit -- --format json` | 70/70 passing | Pending |
+| Adapter scorecard | `npm run harness:adapters -- --check` | PASS | Pending |
+| Observability readiness | `npm run observability:ready` | 14/14 passing | Pending |
+| Root suite | `node tests/run-all.js` | 0 failures | Pending |
+| Markdown lint | `npx markdownlint-cli '**/*.md' --ignore node_modules` | 0 failures | Pending |
+| Package surface | `node tests/scripts/npm-publish-surface.test.js` | 0 failures | Pending |
+| Release surface | `node tests/docs/ecc2-release-surface.test.js` | 0 failures | Pending |
+| Optional Rust surface | `cd ecc2 && cargo test` | 0 failures or explicit deferral | Pending |
+
+## Do Not Publish If
+
+- `main` has unreviewed release-surface changes after the evidence was recorded.
+- `npm view ecc-universal dist-tags --json` contradicts the intended rc/GA tag.
+- Claude plugin validation is unavailable and no manual install smoke test is
+  recorded.
+- Release notes or announcement drafts still contain placeholder URLs,
+  `TODO`, `TBD`, private workspace paths, or personal operator references.
+- Billing, Marketplace, or plugin-submission copy claims a live surface before
+  the live URL exists.
+- Stale PR salvage work is mid-flight on the same branch.
+
+## Announcement Order
+
+1. Merge the release-version PR.
+2. Record the required command evidence from the release commit.
+3. Create or verify the GitHub prerelease.
+4. Publish npm with the rc dist-tag.
+5. Submit or update plugin marketplace surfaces.
+6. Update release notes with final live URLs.
+7. Publish GitHub release copy.
+8. Publish X, LinkedIn, and longform copy only after the public URLs work.

tests/docs/ecc2-release-surface.test.js

@@ -50,6 +50,7 @@ const expectedReleaseFiles = [
   'telegram-handoff.md',
   'demo-prompts.md',
   'quickstart.md',
+  'publication-readiness.md',
 ];
 
 test('release candidate directory includes the public launch pack', () => {
@@ -175,6 +176,53 @@ test('launch checklist records the ecc2 alpha version policy', () => {
   assert.ok(!launchChecklist.includes('confirm whether `ecc2/Cargo.toml` moves'));
 });
 
+test('publication readiness checklist gates public release actions on evidence', () => {
+  const source = read('docs/releases/2.0.0-rc.1/publication-readiness.md');
+
+  for (const section of [
+    '## Release Identity Matrix',
+    '## Publication Gates',
+    '## Required Command Evidence',
+    '## Do Not Publish If',
+    '## Announcement Order',
+  ]) {
+    assert.ok(source.includes(section), `publication readiness missing ${section}`);
+  }
+
+  for (const field of [
+    'Fresh check',
+    'Evidence artifact',
+    'Owner',
+    'Status',
+    'Blocker field',
+    'Recorded output',
+  ]) {
+    assert.ok(source.includes(field), `publication readiness missing ${field}`);
+  }
+
+  for (const surface of [
+    'GitHub release',
+    'npm package',
+    'Claude plugin',
+    'Codex plugin',
+    'OpenCode package',
+    'ECC Tools billing reference',
+    'Announcement copy',
+  ]) {
+    assert.ok(source.includes(surface), `publication readiness missing ${surface}`);
+  }
+});
+
+test('release checklist and roadmap link to publication readiness evidence gate', () => {
+  const launchChecklist = read('docs/releases/2.0.0-rc.1/launch-checklist.md');
+  const roadmap = read('docs/ECC-2.0-GA-ROADMAP.md');
+
+  assert.ok(launchChecklist.includes('publication-readiness.md'));
+  assert.ok(launchChecklist.includes('fresh evidence'));
+  assert.ok(roadmap.includes('docs/releases/2.0.0-rc.1/publication-readiness.md'));
+  assert.ok(roadmap.includes('npm dist-tag'));
+});
+
 test('localized changelogs include rc.1 and 1.10.0 release entries', () => {
   for (const relativePath of ['docs/tr/CHANGELOG.md', 'docs/zh-CN/CHANGELOG.md']) {
     const source = read(relativePath);