@etiquekit/etq 1.0.12 → 1.0.14

package/packages/control/src/release/readiness.ts

@@ -0,0 +1,842 @@
+import { spawnSync } from 'node:child_process';
+import { access, readFile } from 'node:fs/promises';
+import { join, posix } from 'node:path';
+
+type JsonRecord = Record<string, unknown>;
+
+export type ReleaseReadinessVerdict = 'ready' | 'blocked';
+export type ReleaseReadinessStatus = 'pass' | 'warn' | 'block';
+
+export interface ReleaseReadinessCheck {
+  id: string;
+  status: ReleaseReadinessStatus;
+  summary: string;
+  evidence_ref: string;
+  next_action?: string;
+}
+
+export interface ReleaseDistributionChannel {
+  id: string;
+  label: string;
+  kind: 'primary' | 'wrapper' | 'plugin' | 'runtime-image';
+  private_repo_compatible: boolean;
+  artifact: string;
+  ga_note: string;
+}
+
+export interface ReleaseReadinessReport {
+  schema: 'release-readiness.v0';
+  verdict: ReleaseReadinessVerdict;
+  package: {
+    name: string | null;
+    version: string | null;
+    private: boolean | null;
+    bin: Record<string, string>;
+    files: string[];
+  };
+  client_compatibility: {
+    codex_recommended_minimum: string;
+    codex_required_for: string[];
+    core_release_requires_codex: false;
+  };
+  checks: ReleaseReadinessCheck[];
+  blockers: string[];
+  warnings: string[];
+  authority_boundary: {
+    command_can_publish: false;
+    command_can_flip_private: false;
+    command_can_create_distribution_channel: false;
+  };
+}
+
+export interface ReleaseGaReadinessReport {
+  schema: 'release-ga-readiness.v0';
+  verdict: ReleaseReadinessVerdict;
+  channel: string | null;
+  channels: ReleaseDistributionChannel[];
+  tag: string | null;
+  package_readiness: ReleaseReadinessVerdict;
+  checks: ReleaseReadinessCheck[];
+  blockers: string[];
+  warnings: string[];
+  authority_boundary: {
+    command_can_publish: false;
+    command_can_sign: false;
+    command_can_tag: false;
+    command_can_create_distribution_channel: false;
+  };
+}
+
+export interface ReleaseGaReadinessOptions {
+  channel?: string | null;
+  tagFreeConfirmed?: boolean;
+  verifyTagRemote?: string | null;
+}
+
+const CODEX_RECOMMENDED_MINIMUM = '0.141.0';
+const CODEX_COMPATIBILITY_DOC = 'docs/CODEX_CLIENT_COMPATIBILITY.md';
+const RELEASE_LINEAGE_REF = 'release/lineage.v0.json';
+const ETQ_PACKAGE_NAME = '@etiquekit/etq';
+export const DEFAULT_RELEASE_BASE_URL = 'https://etiquette.example.com/releases';
+const PRODUCTION_AGENT_PLANE_SOURCE_REF = 'packages/control/src/agent-plane/index.ts';
+const PRODUCTION_AGENT_PLANE_CONTRACT_ROOT = 'internal/docs/contracts/production-agent-plane';
+const PRODUCTION_AGENT_PLANE_EXAMPLES = [
+  'examples/local-solo-code-change.profiles.yaml',
+  'examples/eks-choreography-two-worker.profiles.yaml',
+  'examples/human-gated-policy-change.profiles.yaml',
+] as const;
+const CODEX_REQUIRED_FOR = [
+  'remote-runtime app-server/exec-server canaries',
+  'plugin-scoped MCP adapter canaries',
+  'hook/action-auth resume canaries',
+];
+
+const RELEASE_DISTRIBUTION_CHANNELS: ReleaseDistributionChannel[] = [
+  {
+    id: 'shell-installer',
+    label: 'signed shell installer',
+    kind: 'primary',
+    private_repo_compatible: true,
+    artifact: `install.sh from https://etiquette.example.com over signed artifacts at ${DEFAULT_RELEASE_BASE_URL}`,
+    ga_note: 'Use as the primary first-run path; install user-local and keep agent integrations explicit.',
+  },
+  {
+    id: 'npm',
+    label: 'npm-compatible package registry',
+    kind: 'primary',
+    private_repo_compatible: true,
+    artifact: 'signed npm tarball or private npm registry package',
+    ga_note: 'Use for Node-heavy teams, CI, and npx-style checks while the source repo remains private.',
+  },
+  {
+    id: 'homebrew-tap',
+    label: 'private Homebrew tap',
+    kind: 'wrapper',
+    private_repo_compatible: true,
+    artifact: 'formula wrapper over the same signed CLI artifact',
+    ga_note: 'Use for macOS convenience after the npm/global CLI artifact is proven.',
+  },
+  {
+    id: 'github-release',
+    label: 'GitHub release artifact',
+    kind: 'primary',
+    private_repo_compatible: true,
+    artifact: 'signed tarball plus SHA256SUMS',
+    ga_note: 'Use as a universal artifact channel; the repository may stay private.',
+  },
+  {
+    id: 'codex-plugin-private',
+    label: 'private Codex plugin channel',
+    kind: 'plugin',
+    private_repo_compatible: true,
+    artifact: 'Codex plugin/skills/MCP bundle',
+    ga_note: 'Use for Codex seat ergonomics; it must not add authority semantics.',
+  },
+  {
+    id: 'claude-code-plugin-private',
+    label: 'private Claude Code plugin channel',
+    kind: 'plugin',
+    private_repo_compatible: true,
+    artifact: 'Claude Code plugin/skills/hooks/MCP bundle',
+    ga_note: 'Use for Claude Code seat ergonomics; receipts remain workflow proof.',
+  },
+  {
+    id: 'chocolatey-internal',
+    label: 'internal Chocolatey feed',
+    kind: 'wrapper',
+    private_repo_compatible: true,
+    artifact: 'Windows wrapper over the same signed CLI artifact',
+    ga_note: 'Use after the primary CLI artifact is proven.',
+  },
+  {
+    id: 'winget-private',
+    label: 'private WinGet source',
+    kind: 'wrapper',
+    private_repo_compatible: true,
+    artifact: 'Windows manifest over the same signed CLI artifact',
+    ga_note: 'Use after the primary CLI artifact is proven.',
+  },
+  {
+    id: 'runtime-oci',
+    label: 'runtime cell OCI image',
+    kind: 'runtime-image',
+    private_repo_compatible: true,
+    artifact: 'container image for remote verifier/runtime cells',
+    ga_note: 'Use for managed runtime cells, separate from Core CLI GA.',
+  },
+];
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function asRecord(value: unknown): JsonRecord | null {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? value as JsonRecord : null;
+}
+
+function asString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+
+function asStringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : [];
+}
+
+function asStringRecord(value: unknown): Record<string, string> {
+  const record = asRecord(value);
+  if (!record) return {};
+  return Object.fromEntries(Object.entries(record).filter((entry): entry is [string, string] => (
+    typeof entry[1] === 'string' && entry[1].trim().length > 0
+  )));
+}
+
+function repositoryUrl(value: unknown): string | null {
+  if (typeof value === 'string') return asString(value);
+  return asString(asRecord(value)?.url);
+}
+
+function semverTuple(value: string | null): [number, number, number] | null {
+  const match = value?.match(/^(\d+)\.(\d+)\.(\d+)$/);
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+function compareSemver(left: string | null, right: string | null): number | null {
+  const a = semverTuple(left);
+  const b = semverTuple(right);
+  if (!a || !b) return null;
+  for (let index = 0; index < a.length; index += 1) {
+    if (a[index] !== b[index]) return a[index] > b[index] ? 1 : -1;
+  }
+  return 0;
+}
+
+function check(status: ReleaseReadinessStatus, id: string, summary: string, evidenceRef: string, nextAction?: string): ReleaseReadinessCheck {
+  return {
+    id,
+    status,
+    summary,
+    evidence_ref: evidenceRef,
+    ...(nextAction ? { next_action: nextAction } : {}),
+  };
+}
+
+function scriptExists(scripts: Record<string, string>, name: string): boolean {
+  return typeof scripts[name] === 'string' && scripts[name].trim().length > 0;
+}
+
+async function scriptDeclarationOk(
+  scripts: Record<string, string>,
+  name: string,
+  projectRoot: string,
+): Promise<{ declared: boolean; present: boolean; ref: string }> {
+  const value = scripts[name]?.trim();
+  if (!value) return { declared: false, present: false, ref: 'package.json' };
+  const scriptRef = value.match(/\b(scripts\/[A-Za-z0-9._/-]+\.sh)\b/)?.[1] ?? null;
+  if (!scriptRef) return { declared: true, present: true, ref: 'package.json' };
+  return {
+    declared: true,
+    present: await exists(join(projectRoot, scriptRef)),
+    ref: scriptRef,
+  };
+}
+
+function safeBinPath(raw: string): string | null {
+  const normalized = posix.normalize(raw.replaceAll('\\', '/'));
+  if (
+    normalized.startsWith('../')
+    || normalized === '..'
+    || normalized.startsWith('/')
+    || /^[A-Za-z]:\//.test(normalized)
+  ) {
+    return null;
+  }
+  return normalized;
+}
+
+function packageTarballName(packageName: string | null, version: string | null): string | null {
+  if (!packageName || !version) return null;
+  return `${packageName.replace(/^@/, '').replaceAll('/', '-')}-${version}.tgz`;
+}
+
+function validGaVersion(version: string | null): boolean {
+  return typeof version === 'string' && /^\d+\.\d+\.\d+$/.test(version);
+}
+
+function safeChannelName(value: string | null): string | null {
+  if (!value) return null;
+  return /^[a-z0-9][a-z0-9._-]{1,62}[a-z0-9]$/.test(value) ? value : null;
+}
+
+function splitChannelNames(value: string | null): string[] {
+  if (!value) return [];
+  return value.split(',').map((item) => item.trim()).filter(Boolean);
+}
+
+function verifyTagIsFree(projectRoot: string, remote: string, tag: string | null): ReleaseReadinessCheck {
+  if (!tag) {
+    return check(
+      'block',
+      'tag_uniqueness',
+      'cannot derive release tag for remote uniqueness check',
+      'package.json',
+      'set a GA package version before checking remote tags',
+    );
+  }
+
+  const trimmedRemote = remote.trim();
+  if (!trimmedRemote || trimmedRemote.startsWith('-')) {
+    return check(
+      'block',
+      'tag_uniqueness',
+      'remote tag uniqueness check requires a safe remote name or URL',
+      'operator:--verify-tag-remote',
+      'rerun with --verify-tag-remote origin or a trusted remote URL',
+    );
+  }
+
+  const tagRef = `refs/tags/${tag}`;
+  const result = spawnSync('git', ['ls-remote', '--tags', trimmedRemote, tagRef, `${tagRef}^{}`], {
+    cwd: projectRoot,
+    encoding: 'utf-8',
+    env: {
+      ...process.env,
+      GIT_TERMINAL_PROMPT: '0',
+    },
+    timeout: 15_000,
+  });
+  const evidenceRef = `git ls-remote --tags ${trimmedRemote} ${tagRef}`;
+
+  if (result.error) {
+    return check(
+      'block',
+      'tag_uniqueness',
+      `remote tag uniqueness check failed: ${result.error.message}`,
+      evidenceRef,
+      'verify credentials/network access, then rerun the remote tag check',
+    );
+  }
+  if (result.status !== 0) {
+    const message = (result.stderr || result.stdout || 'git ls-remote returned non-zero').trim().split('\n')[0];
+    return check(
+      'block',
+      'tag_uniqueness',
+      `remote tag uniqueness check failed: ${message}`,
+      evidenceRef,
+      'verify the release remote is reachable before GA',
+    );
+  }
+
+  if (result.stdout.trim().length > 0) {
+    return check(
+      'block',
+      'tag_uniqueness',
+      `release tag already exists on target remote: ${tag}`,
+      evidenceRef,
+      'choose a new version or reconcile the existing tag before GA',
+    );
+  }
+
+  return check(
+    'pass',
+    'tag_uniqueness',
+    `remote tag uniqueness verified for ${tag} on ${trimmedRemote}`,
+    evidenceRef,
+  );
+}
+
+function lookupChannels(value: string | null): { selected: ReleaseDistributionChannel[]; unknown: string[] } {
+  const names = splitChannelNames(value);
+  const catalog = new Map(RELEASE_DISTRIBUTION_CHANNELS.map((item) => [item.id, item]));
+  const selected: ReleaseDistributionChannel[] = [];
+  const unknown: string[] = [];
+  const seen = new Set<string>();
+  for (const rawName of names) {
+    const name = safeChannelName(rawName);
+    if (!name) {
+      unknown.push(rawName);
+      continue;
+    }
+    if (seen.has(name)) continue;
+    seen.add(name);
+    const item = catalog.get(name);
+    if (item) {
+      selected.push(item);
+    } else {
+      unknown.push(name);
+    }
+  }
+  return { selected, unknown };
+}
+
+export function listReleaseDistributionChannels(): ReleaseDistributionChannel[] {
+  return RELEASE_DISTRIBUTION_CHANNELS.map((item) => ({ ...item }));
+}
+
+async function readTextIfExists(path: string): Promise<string | null> {
+  try {
+    return await readFile(path, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+function sanitizeError(error: unknown, projectRoot: string): string {
+  const raw = error instanceof Error ? error.message : String(error);
+  return raw.replaceAll(projectRoot, '<project>').split('\n')[0];
+}
+
+async function appendProductionAgentPlaneChecks(
+  projectRoot: string,
+  checks: ReleaseReadinessCheck[],
+): Promise<void> {
+  const sourcePresent = await exists(join(projectRoot, PRODUCTION_AGENT_PLANE_SOURCE_REF));
+  const contractRootPresent = await exists(join(projectRoot, PRODUCTION_AGENT_PLANE_CONTRACT_ROOT, 'README.md'));
+  if (!sourcePresent && !contractRootPresent) return;
+
+  // agent-plane validation is source-workspace-only; in the devkit the presence of
+  // agent-plane sources without the validator is itself a release blocker.
+  checks.push(check(
+    'block',
+    'production_agent_plane_profiles',
+    'agent-plane sources detected; validate from a source workspace, not the devkit package',
+    PRODUCTION_AGENT_PLANE_CONTRACT_ROOT,
+    'run release readiness from a source workspace that carries the agent-plane validator',
+  ));
+  return;
+}
+
+async function appendReleaseLineageChecks(
+  projectRoot: string,
+  packageJson: JsonRecord,
+  packageInfo: {
+    name: string | null;
+    version: string | null;
+    bin: Record<string, string>;
+    files: string[];
+    scripts: Record<string, string>;
+  },
+  checks: ReleaseReadinessCheck[],
+): Promise<void> {
+  const lineagePath = join(projectRoot, RELEASE_LINEAGE_REF);
+  const lineagePresent = await exists(lineagePath);
+  if (!lineagePresent && packageInfo.name !== ETQ_PACKAGE_NAME) return;
+
+  let lineage: JsonRecord | null = null;
+  try {
+    lineage = asRecord(JSON.parse(await readFile(lineagePath, 'utf-8')));
+  } catch {
+    lineage = null;
+  }
+
+  if (!lineage || asString(lineage.schema) !== 'etq-release-lineage.v0') {
+    checks.push(check(
+      'block',
+      'release_lineage_manifest',
+      'canonical Etq release lineage manifest is missing or malformed',
+      RELEASE_LINEAGE_REF,
+      'restore a valid etq-release-lineage.v0 manifest before release',
+    ));
+    return;
+  }
+
+  checks.push(check('pass', 'release_lineage_manifest', 'release lineage manifest is present and parseable', RELEASE_LINEAGE_REF));
+
+  const expectedName = asString(lineage.package_name);
+  const candidateVersion = asString(lineage.candidate_version);
+  const registryFloor = asString(lineage.registry_floor);
+  const distributionMode = asString(lineage.distribution_mode);
+  const sourceRepository = asString(lineage.source_repository);
+  const distributionRepository = asString(lineage.distribution_repository);
+  const sourceBaseCommit = asString(lineage.source_base_commit);
+  const requiredBins = asStringArray(lineage.required_bins);
+  const packageRepository = repositoryUrl(packageJson.repository);
+
+  const identityMatches = expectedName === ETQ_PACKAGE_NAME
+    && packageInfo.name === expectedName
+    && packageInfo.version === candidateVersion;
+  checks.push(identityMatches
+    ? check('pass', 'release_package_identity', `package identity matches lineage: ${expectedName}@${candidateVersion}`, RELEASE_LINEAGE_REF)
+    : check(
+      'block',
+      'release_package_identity',
+      `package identity does not match lineage: package=${packageInfo.name ?? 'unknown'}@${packageInfo.version ?? 'unknown'} lineage=${expectedName ?? 'unknown'}@${candidateVersion ?? 'unknown'}`,
+      RELEASE_LINEAGE_REF,
+      'align package.json and the reviewed release lineage manifest',
+    ));
+
+  const versionComparison = compareSemver(candidateVersion, registryFloor);
+  checks.push(versionComparison !== null && versionComparison > 0
+    ? check('pass', 'release_version_floor', `candidate ${candidateVersion} is newer than registry floor ${registryFloor}`, RELEASE_LINEAGE_REF)
+    : check(
+      'block',
+      'release_version_floor',
+      `candidate version must be a GA semver newer than registry floor: candidate=${candidateVersion ?? 'unknown'} floor=${registryFloor ?? 'unknown'}`,
+      RELEASE_LINEAGE_REF,
+      'choose a candidate version strictly above the observed registry version',
+    ));
+
+  const missingBins = requiredBins.filter((name) => !packageInfo.bin[name]);
+  checks.push(requiredBins.length > 0 && missingBins.length === 0
+    ? check('pass', 'release_required_bins', `required package bins declared: ${requiredBins.join(', ')}`, RELEASE_LINEAGE_REF)
+    : check(
+      'block',
+      'release_required_bins',
+      `required package bins are missing: ${missingBins.join(', ') || 'manifest declares none'}`,
+      RELEASE_LINEAGE_REF,
+      'restore all reviewed CLI aliases before building the candidate',
+    ));
+
+  checks.push(sourceRepository
+    ? check('pass', 'release_source_repository', `source repository is declared: ${sourceRepository}`, RELEASE_LINEAGE_REF)
+    : check(
+      'block',
+      'release_source_repository',
+      'source repository is missing from release lineage',
+      RELEASE_LINEAGE_REF,
+      'declare the reviewed source-of-record repository',
+    ));
+
+  checks.push(distributionRepository && packageRepository === distributionRepository
+    ? check('pass', 'release_distribution_repository', `package repository matches public distribution home: ${distributionRepository}`, RELEASE_LINEAGE_REF)
+    : check(
+      'block',
+      'release_distribution_repository',
+      `package repository does not match public distribution home: package=${packageRepository ?? 'unknown'} lineage=${distributionRepository ?? 'unknown'}`,
+      RELEASE_LINEAGE_REF,
+      'point package metadata at the reviewed public distribution repository',
+    ));
+
+  const shipsSource = packageInfo.files.includes('packages/control/src/')
+    && packageInfo.files.includes('packages/protocol/src/')
+    && packageInfo.files.includes(RELEASE_LINEAGE_REF)
+    && !packageInfo.files.some((entry) => entry === 'lib' || entry.startsWith('lib/'))
+    && !scriptExists(packageInfo.scripts, 'prepack')
+    && !scriptExists(packageInfo.scripts, 'release:build');
+  checks.push(distributionMode === 'bun-typescript-source' && shipsSource
+    ? check('pass', 'release_distribution_mode', 'package surface matches bun-typescript-source lineage', RELEASE_LINEAGE_REF)
+    : check(
+      'block',
+      'release_distribution_mode',
+      `package surface does not match declared distribution mode: ${distributionMode ?? 'unknown'}`,
+      RELEASE_LINEAGE_REF,
+      'ship reviewed Bun/TypeScript source and remove implicit compiled prepack output',
+    ));
+
+  const candidateScript = await scriptDeclarationOk(packageInfo.scripts, 'release:candidate', projectRoot);
+  checks.push(candidateScript.declared && candidateScript.present
+    ? check('pass', 'release_candidate_verifier', 'isolated-install candidate verifier is declared and present', candidateScript.ref)
+    : check(
+      'block',
+      'release_candidate_verifier',
+      `release candidate verifier is ${candidateScript.declared ? 'missing' : 'not declared'}`,
+      candidateScript.ref,
+      'wire release:candidate to the isolated-install verifier',
+    ));
+
+  if (!sourceBaseCommit || !/^[0-9a-f]{40}$/.test(sourceBaseCommit)) {
+    checks.push(check('block', 'release_source_ancestry', 'source base commit is missing or invalid', RELEASE_LINEAGE_REF, 'record the reviewed 40-character source base commit'));
+    return;
+  }
+
+  const ancestry = spawnSync('git', ['merge-base', '--is-ancestor', sourceBaseCommit, 'HEAD'], {
+    cwd: projectRoot,
+    encoding: 'utf-8',
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    timeout: 10_000,
+  });
+  checks.push(ancestry.status === 0
+    ? check('pass', 'release_source_ancestry', `HEAD descends from reviewed source base ${sourceBaseCommit}`, RELEASE_LINEAGE_REF)
+    : check(
+      'block',
+      'release_source_ancestry',
+      `HEAD does not prove ancestry from reviewed source base ${sourceBaseCommit}`,
+      RELEASE_LINEAGE_REF,
+      'build the candidate from the reviewed source branch in a Git worktree',
+    ));
+}
+
+export async function buildReleaseReadinessReport(projectRoot: string): Promise<ReleaseReadinessReport> {
+  const packageRef = 'package.json';
+  const packagePath = join(projectRoot, packageRef);
+  const checks: ReleaseReadinessCheck[] = [];
+  let packageJson: JsonRecord | null = null;
+
+  try {
+    packageJson = asRecord(JSON.parse(await readFile(packagePath, 'utf-8')));
+  } catch {
+    packageJson = null;
+  }
+
+  if (!packageJson) {
+    checks.push(check(
+      'block',
+      'package_json',
+      'package.json is missing or malformed',
+      packageRef,
+      'restore a valid root package.json before evaluating release readiness',
+    ));
+    return finalize({
+      name: null,
+      version: null,
+      private: null,
+      bin: {},
+      files: [],
+    }, checks);
+  }
+
+  const name = asString(packageJson.name);
+  const version = asString(packageJson.version);
+  const privateFlag = typeof packageJson.private === 'boolean' ? packageJson.private : null;
+  const bin = asStringRecord(packageJson.bin);
+  const files = asStringArray(packageJson.files);
+  const scripts = asStringRecord(packageJson.scripts);
+
+  checks.push(name && version
+    ? check('pass', 'package_metadata', `package metadata present: ${name}@${version}`, packageRef)
+    : check('block', 'package_metadata', 'package name and version are required', packageRef, 'declare stable package name and version'));
+
+  await appendReleaseLineageChecks(projectRoot, packageJson, {
+    name,
+    version,
+    bin,
+    files,
+    scripts,
+  }, checks);
+
+  checks.push(privateFlag === false
+    ? check('pass', 'package_private_gate', 'package publishing is not blocked by private:true', packageRef)
+    : check('block', 'package_private_gate', 'package remains private; publish/global distro is intentionally blocked', packageRef, 'flip private only in an explicit release/distribution decision'));
+
+  const binEntries = Object.entries(bin);
+  if (binEntries.length === 0) {
+    checks.push(check('block', 'bin_entrypoint', 'no package bin entrypoint is declared', packageRef, 'declare the etiquette CLI bin entrypoint'));
+  } else {
+    const missingBins: string[] = [];
+    const unsafeBins: string[] = [];
+    for (const [, rawPath] of binEntries) {
+      const safePath = safeBinPath(rawPath);
+      if (!safePath) {
+        unsafeBins.push(rawPath);
+        continue;
+      }
+      if (!(await exists(join(projectRoot, safePath)))) missingBins.push(safePath);
+    }
+    if (unsafeBins.length > 0) {
+      checks.push(check('block', 'bin_entrypoint', `bin entrypoint paths must be repo-relative: ${unsafeBins.join(', ')}`, packageRef, 'replace absolute or parent-relative bin paths'));
+    } else if (missingBins.length > 0) {
+      checks.push(check('block', 'bin_entrypoint', `declared bin files are missing: ${missingBins.join(', ')}`, packageRef, 'restore declared bin files'));
+    } else {
+      checks.push(check('pass', 'bin_entrypoint', `declared bin entrypoint(s) exist: ${binEntries.map(([key, value]) => `${key}->${value}`).join(', ')}`, packageRef));
+    }
+  }
+
+  checks.push(files.length > 0
+    ? check('pass', 'files_allowlist', `package files allowlist declared with ${files.length} entr${files.length === 1 ? 'y' : 'ies'}`, packageRef)
+    : check('block', 'files_allowlist', 'package files allowlist is missing; pack output may include internal surfaces', packageRef, 'declare package.json files before enabling distribution'));
+
+  checks.push(scriptExists(scripts, 'test') && scriptExists(scripts, 'typecheck')
+    ? check('pass', 'validation_scripts', 'test and typecheck scripts are declared', packageRef)
+    : check('block', 'validation_scripts', 'test and typecheck scripts are required for release readiness', packageRef, 'declare test and typecheck scripts'));
+
+  const releaseScanScript = scriptExists(scripts, 'release:scan') && await exists(join(projectRoot, 'scripts', 'release-scan.sh'));
+  checks.push(releaseScanScript
+    ? check('pass', 'release_scan', 'release scan script is declared and present', 'scripts/release-scan.sh')
+    : check('block', 'release_scan', 'release scan script must be declared and present', packageRef, 'wire npm run release:scan to scripts/release-scan.sh'));
+
+  const packScript = await scriptDeclarationOk(scripts, 'release:pack', projectRoot);
+  if (!packScript.declared) {
+    checks.push(check('block', 'pack_canary', 'no release pack canary script is declared', packageRef, 'add a script that proves tarball contents from a fresh package output'));
+  } else if (!packScript.present) {
+    checks.push(check('block', 'pack_canary', `release pack script is declared but missing: ${packScript.ref}`, packScript.ref, 'restore the referenced pack canary script'));
+  } else {
+    checks.push(check('pass', 'pack_canary', 'release pack canary script is declared and present', packScript.ref));
+  }
+
+  const checksumScript = await scriptDeclarationOk(scripts, 'release:checksum', projectRoot);
+  const signScript = await scriptDeclarationOk(scripts, 'release:sign', projectRoot);
+  if (!checksumScript.declared || !signScript.declared) {
+    checks.push(check('block', 'checksum_signature', 'checksum/signature posture is not declared', packageRef, 'add checksum and signing scripts or record an explicit internal-channel waiver'));
+  } else if (!checksumScript.present || !signScript.present) {
+    const missing = [checksumScript, signScript].filter((item) => !item.present).map((item) => item.ref).join(', ');
+    checks.push(check('block', 'checksum_signature', `checksum/signature script is declared but missing: ${missing}`, packageRef, 'restore the referenced checksum/signing scripts'));
+  } else {
+    checks.push(check('pass', 'checksum_signature', 'checksum and signature scripts are declared and present', `${checksumScript.ref}, ${signScript.ref}`));
+  }
+
+  const shellInstaller = await exists(join(projectRoot, 'scripts', 'install.sh'));
+  checks.push(shellInstaller
+    ? check('pass', 'shell_installer', 'signed shell installer is present for user-local bootstrap', 'scripts/install.sh')
+    : check('warn', 'shell_installer', 'signed shell installer is not present; package-manager channels remain the only bootstrap path', 'scripts/install.sh', 'add a user-local installer before org-wide onboarding'));
+
+  if (shellInstaller) {
+    const installerText = await readTextIfExists(join(projectRoot, 'scripts', 'install.sh'));
+    const supportsPinnedKeyUrl = installerText?.includes('--public-key-url')
+      && installerText.includes('--public-key-sha256')
+      && installerText.includes('public key SHA-256 mismatch');
+    checks.push(supportsPinnedKeyUrl
+      ? check('pass', 'installer_trust_bootstrap', 'installer supports hosted public key URL with SHA-256 pin', 'scripts/install.sh')
+      : check('warn', 'installer_trust_bootstrap', 'installer does not expose a pinned hosted public-key bootstrap path', 'scripts/install.sh', 'require public-key URL plus SHA-256 pin before org-wide curl bootstrap'));
+  }
+
+  checks.push(check(
+    'warn',
+    'package_manager_wrappers',
+    'Homebrew, Chocolatey, WinGet, and registry wrappers are not proven by this command',
+    'site/guide/distribution.md',
+    'treat wrappers as follow-up channels after the signed installer and core tarball are green',
+  ));
+
+  const codexCompatibilityDocExists = await exists(join(projectRoot, CODEX_COMPATIBILITY_DOC));
+  checks.push(codexCompatibilityDocExists
+    ? check(
+      'pass',
+      'codex_client_compatibility',
+      `Codex client policy documented; ${CODEX_RECOMMENDED_MINIMUM}+ recommended and required for remote/plugin-MCP canaries`,
+      CODEX_COMPATIBILITY_DOC,
+    )
+    : check(
+      'warn',
+      'codex_client_compatibility',
+      `Codex client policy is not documented; ${CODEX_RECOMMENDED_MINIMUM}+ should be treated as the remote/plugin-MCP canary floor`,
+      CODEX_COMPATIBILITY_DOC,
+      'add client compatibility guidance before routing remote-runtime or plugin-MCP pilots',
+    ));
+
+  await appendProductionAgentPlaneChecks(projectRoot, checks);
+
+  return finalize({
+    name,
+    version,
+    private: privateFlag,
+    bin,
+    files,
+  }, checks);
+}
+
+export async function buildReleaseGaReadinessReport(
+  projectRoot: string,
+  options: ReleaseGaReadinessOptions = {},
+): Promise<ReleaseGaReadinessReport> {
+  const packageReport = await buildReleaseReadinessReport(projectRoot);
+  const checks: ReleaseReadinessCheck[] = [];
+  const tag = packageReport.package.version ? `v${packageReport.package.version}` : null;
+  const { selected: channels, unknown: unknownChannels } = lookupChannels(options.channel ?? null);
+  const channel = channels.length > 0 ? channels.map((item) => item.id).join(',') : null;
+  const tarballName = packageTarballName(packageReport.package.name, packageReport.package.version);
+
+  checks.push(packageReport.verdict === 'ready'
+    ? check('pass', 'package_readiness', 'base release readiness is ready', 'package.json')
+    : check('block', 'package_readiness', `base release readiness is blocked: ${packageReport.blockers.join(', ') || 'unknown'}`, 'package.json', 'resolve base readiness blockers first'));
+
+  checks.push(validGaVersion(packageReport.package.version)
+    ? check('pass', 'ga_version', `package version is GA-shaped: ${packageReport.package.version}`, 'package.json')
+    : check('block', 'ga_version', `package version is not GA-shaped: ${packageReport.package.version ?? 'unknown'}`, 'package.json', 'set a non-prerelease semver version before GA'));
+
+  if (channels.length > 0 && unknownChannels.length === 0) {
+    checks.push(check('pass', 'distribution_channel', `distribution channel(s) declared: ${channel}`, 'operator:--channel'));
+  } else if (unknownChannels.length > 0) {
+    checks.push(check('block', 'distribution_channel', `unknown distribution channel(s): ${unknownChannels.join(', ')}`, 'operator:--channel', `choose one or more known channels: ${RELEASE_DISTRIBUTION_CHANNELS.map((item) => item.id).join(', ')}`));
+  } else {
+    checks.push(check('block', 'distribution_channel', 'GA requires at least one named distribution channel', 'operator:--channel', 'rerun with --channel shell-installer,npm or another known channel'));
+  }
+
+  if (options.verifyTagRemote) {
+    checks.push(verifyTagIsFree(projectRoot, options.verifyTagRemote, tag));
+  } else if (options.tagFreeConfirmed === true) {
+    checks.push(check(
+      'block',
+      'tag_uniqueness',
+      `manual confirmation is insufficient for GA tag ${tag ?? 'unknown'}; verify the remote directly`,
+      'operator:--tag-free-confirmed',
+      'rerun with --verify-tag-remote origin after credentials are available',
+    ));
+  } else {
+    checks.push(check(
+      'block',
+      'tag_uniqueness',
+      `GA requires remote verification that tag ${tag ?? 'unknown'} is unused`,
+      'operator:--verify-tag-remote',
+      'rerun with --verify-tag-remote origin or another trusted release remote',
+    ));
+  }
+
+  if (!tarballName) {
+    checks.push(check('block', 'release_artifact', 'cannot derive package tarball name', 'package.json', 'restore package name and version'));
+  } else {
+    const tarballPath = join(projectRoot, 'dist', tarballName);
+    const checksumsPath = join(projectRoot, 'dist', 'SHA256SUMS');
+    const checksums = await readTextIfExists(checksumsPath);
+    if (!(await exists(tarballPath))) {
+      checks.push(check('block', 'release_artifact', `missing release tarball: dist/${tarballName}`, 'dist/', 'run npm run release:checksum after setting the GA version'));
+    } else if (!checksums?.includes(tarballName)) {
+      checks.push(check('block', 'release_artifact', `dist/SHA256SUMS does not reference ${tarballName}`, 'dist/SHA256SUMS', 'regenerate checksums from the final GA tarball'));
+    } else {
+      checks.push(check('pass', 'release_artifact', `tarball and checksum manifest present for ${tarballName}`, 'dist/SHA256SUMS'));
+    }
+  }
+
+  const signatureManifest = await readTextIfExists(join(projectRoot, 'dist', 'SIGNATURE_MANIFEST.txt'));
+  const hasTrustedSignature = signatureManifest?.includes('method=openssl-rsa-sha256')
+    && await exists(join(projectRoot, 'dist', 'SHA256SUMS.sig'));
+  const hasCanaryHmac = signatureManifest?.includes('method=hmac-sha256')
+    || await exists(join(projectRoot, 'dist', 'SHA256SUMS.hmac'));
+  if (hasTrustedSignature) {
+    checks.push(check('pass', 'trusted_signature', 'trusted RSA signature exists for dist/SHA256SUMS', 'dist/SIGNATURE_MANIFEST.txt'));
+  } else if (hasCanaryHmac) {
+    checks.push(check('block', 'trusted_signature', 'HMAC signature is canary-only and cannot satisfy GA', 'dist/SIGNATURE_MANIFEST.txt', 'sign dist/SHA256SUMS with ETIQUETTE_RELEASE_SIGNING_KEY'));
+  } else {
+    checks.push(check('block', 'trusted_signature', 'trusted release signature is missing', 'dist/SIGNATURE_REQUIRED.txt', 'set ETIQUETTE_RELEASE_SIGNING_KEY and run npm run release:sign'));
+  }
+
+  const blockers = checks.filter((item) => item.status === 'block').map((item) => item.id);
+  const warnings = checks.filter((item) => item.status === 'warn').map((item) => item.id);
+  return {
+    schema: 'release-ga-readiness.v0',
+    verdict: blockers.length === 0 ? 'ready' : 'blocked',
+    channel,
+    channels,
+    tag,
+    package_readiness: packageReport.verdict,
+    checks,
+    blockers,
+    warnings,
+    authority_boundary: {
+      command_can_publish: false,
+      command_can_sign: false,
+      command_can_tag: false,
+      command_can_create_distribution_channel: false,
+    },
+  };
+}
+
+function finalize(
+  packageInfo: ReleaseReadinessReport['package'],
+  checks: ReleaseReadinessCheck[],
+): ReleaseReadinessReport {
+  const blockers = checks.filter((item) => item.status === 'block').map((item) => item.id);
+  const warnings = checks.filter((item) => item.status === 'warn').map((item) => item.id);
+  return {
+    schema: 'release-readiness.v0',
+    verdict: blockers.length === 0 ? 'ready' : 'blocked',
+    package: packageInfo,
+    client_compatibility: {
+      codex_recommended_minimum: CODEX_RECOMMENDED_MINIMUM,
+      codex_required_for: CODEX_REQUIRED_FOR,
+      core_release_requires_codex: false,
+    },
+    checks,
+    blockers,
+    warnings,
+    authority_boundary: {
+      command_can_publish: false,
+      command_can_flip_private: false,
+      command_can_create_distribution_channel: false,
+    },
+  };
+}