@etiquekit/etq 1.0.12 → 1.0.13

package/packages/control/src/cli/commands/memory.ts

@@ -0,0 +1,445 @@
+import { resolve } from 'node:path';
+import { optionalString, parseInt32, parseList, requireString } from '../argv';
+import { buildMemoryContext } from '../../memory/context';
+import { drainImportMemoryCandidates } from '../../memory/drain-import';
+import { shardedDrainImportMemoryCandidates } from '../../memory/sharded-drain-import';
+import { defaultMemoryExportDir, indexMemory } from '../../memory/indexer';
+import { preflightMemory, rejectedMemory, searchMemory, showMemory, staleMemory } from '../../memory/query';
+import { memoryCapabilityStatus, type MemoryCapabilityStatus } from '../../memory/status';
+import {
+  addMemoryStoreCandidate,
+  consolidateMemoryStores,
+  initMemoryStore,
+  listMemoryStores,
+  parseEvidenceRefs,
+  showMemoryStore,
+  type MemoryStoreSummary,
+} from '../../memory/store-lifecycle';
+import {
+  WORKSPACE_MEMORY_ACCESS,
+  WORKSPACE_MEMORY_MOUNT_MODES,
+  WORKSPACE_MEMORY_SCOPES,
+  WORKSPACE_MEMORY_WRITE_POLICIES,
+  type WorkspaceMemoryAccess,
+  type WorkspaceMemoryMountMode,
+  type WorkspaceMemoryScope,
+  type WorkspaceMemoryWritePolicy,
+} from '../../workspace/authority';
+
+const MEMORY_VERBS = new Set([
+  'index',
+  'search',
+  'show',
+  'preflight',
+  'context',
+  'status',
+  'stale',
+  'rejected',
+  'store',
+  'consolidate',
+  'drain-import',
+  'sharded-drain-import',
+]);
+
+export function isMemoryCommand(command: string): boolean {
+  return command === 'memory';
+}
+
+function asLimit(raw: string | boolean | undefined, fallback: number): number {
+  if (raw === undefined) return fallback;
+  const parsed = parseInt32(raw, 'limit');
+  if (parsed < 1 || parsed > 50) {
+    throw new Error('--limit must be between 1 and 50');
+  }
+  return parsed;
+}
+
+function renderCompact(items: {
+  capsule_id: string;
+  title: string;
+  category: string;
+  confidence: string;
+  stale_status: string;
+  evidence_count: number;
+}[]): string {
+  if (items.length === 0) return 'memory: no matching capsules\n';
+  return `${items.map((item) => [
+    `capsule: ${item.capsule_id}`,
+    `title: ${item.title}`,
+    `category: ${item.category}`,
+    `confidence: ${item.confidence}`,
+    `stale_status: ${item.stale_status}`,
+    `evidence_count: ${item.evidence_count}`,
+  ].join('\n')).join('\n---\n')}\n`;
+}
+
+function renderRejected(items: {
+  candidate_id: string;
+  title: string;
+  category: string;
+  risk_flags: string[];
+  rejection_reasons: string[];
+  source_refs: { type: string; ref: string }[];
+}[]): string {
+  if (items.length === 0) return 'memory: no rejected candidates\n';
+  return `${items.map((item) => [
+    `candidate: ${item.candidate_id}`,
+    `title: ${item.title}`,
+    `category: ${item.category}`,
+    `risk_flags: ${item.risk_flags.join(', ') || 'none'}`,
+    `rejection_reasons: ${item.rejection_reasons.join(', ') || 'none'}`,
+    `source_refs: ${item.source_refs.map((ref) => `${ref.type}:${ref.ref}`).join(', ')}`,
+  ].join('\n')).join('\n---\n')}\n`;
+}
+
+function renderContext(context: ReturnType<typeof buildMemoryContext>): string {
+  const scope = [
+    context.scope.org_id ? `org_id=${context.scope.org_id}` : undefined,
+    context.scope.workspace_id ? `workspace_id=${context.scope.workspace_id}` : undefined,
+    context.scope.lane_ref ? `lane_ref=${context.scope.lane_ref}` : undefined,
+    context.scope.task_ref ? `task_ref=${context.scope.task_ref}` : undefined,
+  ].filter(Boolean).join(' ');
+  const items = context.items.length === 0
+    ? ['  capsules: none']
+    : context.items.flatMap((item) => [
+      `  - ${item.capsule_id}`,
+      `    title: ${item.title}`,
+      `    category: ${item.category}`,
+      `    confidence: ${item.confidence}`,
+      `    stale_status: ${item.stale_status}`,
+      `    evidence_refs: ${item.evidence_refs.map((ref) => `${ref.type}:${ref.ref}`).join(', ')}`,
+    ]);
+  return [
+    'memory_context:',
+    `  schema: ${context.schema}`,
+    `  query: ${context.query}`,
+    `  scope: ${scope || 'workspace_local'}`,
+    '  boundary: summaries-only; advisory memory; cannot authorize, close, replace receipts, or mutate ledger',
+    ...items,
+  ].join('\n') + '\n';
+}
+
+function enumValue<T extends readonly string[]>(values: T, raw: string, key: string): T[number] {
+  if (!(values as readonly string[]).includes(raw)) {
+    throw new Error(`--${key} must be one of: ${values.join(', ')}`);
+  }
+  return raw as T[number];
+}
+
+function optionalBoolean(flags: Record<string, string | boolean>, key: string): boolean | undefined {
+  const value = flags[key];
+  if (value === undefined) return undefined;
+  if (value === true) return true;
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  throw new Error(`--${key} must be true or false`);
+}
+
+function renderStoreSummary(summary: MemoryStoreSummary): string {
+  return [
+    `store: ${summary.store.store_id}`,
+    `scope: ${summary.store.scope}`,
+    `access: ${summary.store.access}`,
+    `mount_mode: ${summary.store.mount_mode}`,
+    `write_policy: ${summary.store.write_policy}`,
+    `evidence_required: ${String(summary.store.evidence_required)}`,
+    `candidate_entries: ${summary.counts.candidate_entries}`,
+    `rollups: ${summary.counts.rollups}`,
+    `agent_can_write_canonical_memory: ${String(summary.store.authority_boundary.agent_can_write_canonical_memory)}`,
+  ].join('\n');
+}
+
+function renderStoreList(summaries: MemoryStoreSummary[]): string {
+  if (summaries.length === 0) return 'memory_stores: none\n';
+  return `${summaries.map(renderStoreSummary).join('\n---\n')}\n`;
+}
+
+function renderMemoryCapabilityStatus(status: MemoryCapabilityStatus): string {
+  return [
+    'memory_capability_status:',
+    `  schema: ${status.schema}`,
+    `  module_status: ${status.module_status}`,
+    `  full_feature_parity_claimed: ${String(status.parity_posture.full_feature_parity_claimed)}`,
+    `  managed_runtime_filesystem_memory: ${status.parity_posture.managed_runtime_filesystem_memory}`,
+    `  mem0_style_semantic_memory: ${status.parity_posture.mem0_style_semantic_memory}`,
+    `  approved_file_count: ${status.evidence_sources.approved_file_count}`,
+    `  recall_capsules: ${status.recall_index.stats.recall_capsules}`,
+    `  memory_candidates: ${status.recall_index.stats.candidates.total}`,
+    `  rejected_candidates: ${status.recall_index.stats.candidates.rejected}`,
+    `  search_adapter: ${status.recall_index.search_adapter}`,
+    `  vector_adapter: ${status.recall_index.vector_adapter}`,
+    `  store_count: ${status.store_lifecycle.store_count}`,
+    `  store_candidate_entries: ${status.store_lifecycle.candidate_entries}`,
+    `  rollups: ${status.store_lifecycle.rollups}`,
+    `  drain_import_receipts: ${status.remote_writeback.drain_import_receipts}`,
+    `  memory_can_authorize_work: ${String(status.authority_boundary.memory_can_authorize_work)}`,
+    `  memory_can_mutate_ledger: ${String(status.authority_boundary.memory_can_mutate_ledger)}`,
+    `  memory_is_execution_truth: ${String(status.authority_boundary.memory_is_execution_truth)}`,
+    `  marination_is_same_primitive: ${String(status.consolidation.marination_is_same_primitive)}`,
+    `  missing_for_full_parity: ${status.missing_for_full_parity.join(', ')}`,
+  ].join('\n') + '\n';
+}
+
+function parseShardSpecs(raw: string | boolean | undefined): Array<{ shardId: string; sourceProjectRoot: string }> {
+  const specs = parseList(raw);
+  if (specs.length === 0) throw new Error('--shard must include at least one id=path entry');
+  return specs.map((spec) => {
+    const index = spec.indexOf('=');
+    if (index <= 0 || index === spec.length - 1) {
+      throw new Error('--shard entries must use id=path');
+    }
+    const sourceProjectRoot = spec.slice(index + 1).trim();
+    if (sourceProjectRoot.length === 0) throw new Error('--shard entries must use id=path');
+    return {
+      shardId: spec.slice(0, index).trim(),
+      sourceProjectRoot: resolve(sourceProjectRoot),
+    };
+  });
+}
+
+export async function dispatchMemory(
+  positionals: string[],
+  flags: Record<string, string | boolean>,
+): Promise<void> {
+  const verb = positionals[1];
+  if (!verb || !MEMORY_VERBS.has(verb)) {
+    throw new Error(`memory verb must be one of: ${[...MEMORY_VERBS].join(', ')}`);
+  }
+  const projectRoot = resolve(optionalString(flags, 'project') ?? process.cwd());
+  const dbPath = optionalString(flags, 'db');
+  const json = Boolean(flags.json);
+
+  if (verb === 'index') {
+    const requestedExport = flags.export;
+    const exportDir = requestedExport === true
+      ? defaultMemoryExportDir(projectRoot, optionalString(flags, 'workspace-id'))
+      : optionalString(flags, 'export');
+    const localPrivate = Boolean(flags['local-private']);
+    if (localPrivate && !json) {
+      console.error([
+        'WARNING: --local-private bypasses only the private-context promotion guard.',
+        'Local-private capsules stay local and must not be shared, exported, or used as authority.',
+      ].join('\n'));
+    }
+    const result = await indexMemory({
+      projectRoot,
+      dbPath,
+      exportDir,
+      localPrivate,
+      orgId: optionalString(flags, 'org-id'),
+      workspaceId: optionalString(flags, 'workspace-id'),
+      confirmSharedExport: Boolean(flags['confirm-shared-export']),
+    });
+    console.log(json ? JSON.stringify(result, null, 2) : [
+      'memory_index:',
+      `  candidates: ${result.candidates}`,
+      `  promoted: ${result.promoted}`,
+      `  rejected: ${result.rejected}`,
+    ].join('\n'));
+    return;
+  }
+
+  if (verb === 'status') {
+    const storesRoot = optionalString(flags, 'root') ? resolve(requireString(flags, 'root')) : undefined;
+    const status = await memoryCapabilityStatus({ projectRoot, dbPath, storesRoot });
+    console.log(json ? JSON.stringify(status, null, 2) : renderMemoryCapabilityStatus(status));
+    return;
+  }
+
+  if (verb === 'store') {
+    const subverb = positionals[2];
+    if (!subverb || !['init', 'list', 'show', 'add'].includes(subverb)) {
+      throw new Error('memory store verb must be one of: init, list, show, add');
+    }
+    const storesRoot = optionalString(flags, 'root') ? resolve(requireString(flags, 'root')) : undefined;
+    if (subverb === 'init') {
+      const access = enumValue(
+        WORKSPACE_MEMORY_ACCESS,
+        requireString(flags, 'access'),
+        'access',
+      ) as WorkspaceMemoryAccess;
+      const result = await initMemoryStore({
+        projectRoot,
+        storesRoot,
+        storeId: requireString(flags, 'store'),
+        scope: enumValue(WORKSPACE_MEMORY_SCOPES, requireString(flags, 'scope'), 'scope') as WorkspaceMemoryScope,
+        access,
+        mountMode: optionalString(flags, 'mount-mode')
+          ? enumValue(WORKSPACE_MEMORY_MOUNT_MODES, requireString(flags, 'mount-mode'), 'mount-mode') as WorkspaceMemoryMountMode
+          : undefined,
+        writePolicy: optionalString(flags, 'write-policy')
+          ? enumValue(WORKSPACE_MEMORY_WRITE_POLICIES, requireString(flags, 'write-policy'), 'write-policy') as WorkspaceMemoryWritePolicy
+          : undefined,
+        evidenceRequired: optionalBoolean(flags, 'evidence-required'),
+        at: optionalString(flags, 'at'),
+      });
+      console.log(json ? JSON.stringify(result, null, 2) : [
+        'memory_store_init:',
+        `  store_id: ${result.store_id}`,
+        `  scope: ${result.scope}`,
+        `  access: ${result.access}`,
+        `  write_policy: ${result.write_policy}`,
+        `  agent_can_write_canonical_memory: ${String(result.authority_boundary.agent_can_write_canonical_memory)}`,
+      ].join('\n'));
+      return;
+    }
+    if (subverb === 'list') {
+      const summaries = await listMemoryStores({ projectRoot, storesRoot });
+      console.log(json ? JSON.stringify(summaries, null, 2) : renderStoreList(summaries));
+      return;
+    }
+    if (subverb === 'show') {
+      const summary = await showMemoryStore({ projectRoot, storesRoot, storeId: requireString(flags, 'store') });
+      console.log(json ? JSON.stringify(summary, null, 2) : `${renderStoreSummary(summary)}\n`);
+      return;
+    }
+    const entry = await addMemoryStoreCandidate({
+      projectRoot,
+      storesRoot,
+      storeId: requireString(flags, 'store'),
+      path: requireString(flags, 'path'),
+      content: requireString(flags, 'content'),
+      evidenceRefs: parseEvidenceRefs(requireString(flags, 'evidence')),
+      at: optionalString(flags, 'at'),
+    });
+    console.log(json ? JSON.stringify(entry, null, 2) : [
+      'memory_store_candidate:',
+      `  entry_id: ${entry.entry_id}`,
+      `  store_id: ${entry.store_id}`,
+      `  path: ${entry.path}`,
+      `  content_ref: ${entry.content_ref}`,
+      `  evidence_refs: ${entry.evidence_refs.map((ref) => `${ref.type}:${ref.ref}`).join(', ')}`,
+      `  agent_wrote_canonical_memory: ${String(entry.authority_boundary.agent_wrote_canonical_memory)}`,
+    ].join('\n'));
+    return;
+  }
+
+  if (verb === 'consolidate') {
+    const storesRoot = optionalString(flags, 'root') ? resolve(requireString(flags, 'root')) : undefined;
+    const rollup = await consolidateMemoryStores({
+      projectRoot,
+      storesRoot,
+      inputStores: parseList(flags.input),
+      outputStore: requireString(flags, 'out'),
+      at: optionalString(flags, 'at'),
+    });
+    console.log(json ? JSON.stringify(rollup, null, 2) : [
+      'memory_consolidation_rollup:',
+      `  rollup_id: ${rollup.rollup_id}`,
+      `  input_stores: ${rollup.input_stores.join(', ')}`,
+      `  output_store: ${rollup.output_store}`,
+      `  candidate_count: ${rollup.candidate_count}`,
+      `  output_policy: ${rollup.output_policy}`,
+      `  mutates_input_store: ${String(rollup.authority_boundary.mutates_input_store)}`,
+      `  promotes_without_curator: ${String(rollup.authority_boundary.promotes_without_curator)}`,
+    ].join('\n'));
+    return;
+  }
+
+  if (verb === 'drain-import') {
+    const receipt = await drainImportMemoryCandidates({
+      sourceProjectRoot: resolve(requireString(flags, 'from-project')),
+      targetProjectRoot: projectRoot,
+      sourceStoresRoot: optionalString(flags, 'from-root') ? resolve(requireString(flags, 'from-root')) : undefined,
+      targetStoresRoot: optionalString(flags, 'to-root') ? resolve(requireString(flags, 'to-root')) : undefined,
+      sourceStoreId: requireString(flags, 'from-store'),
+      targetStoreId: requireString(flags, 'to-store'),
+      sourceWorkspaceRef: optionalString(flags, 'source-ref'),
+      targetWorkspaceRef: optionalString(flags, 'target-ref'),
+      pathPrefix: optionalString(flags, 'path-prefix'),
+      receiptPath: optionalString(flags, 'receipt') ? resolve(requireString(flags, 'receipt')) : undefined,
+      at: optionalString(flags, 'at'),
+    });
+    console.log(json ? JSON.stringify(receipt, null, 2) : [
+      'memory_drain_import:',
+      `  receipt_id: ${receipt.receipt_id}`,
+      `  source: ${receipt.source.workspace_ref}/${receipt.source.store_id}`,
+      `  target: ${receipt.target.workspace_ref}/${receipt.target.store_id}`,
+      `  imported_count: ${receipt.target.imported_count}`,
+      `  drain_can_write_parent_ledger: ${String(receipt.authority_boundary.drain_can_write_parent_ledger)}`,
+      `  imported_entries_are_candidates: ${String(receipt.authority_boundary.imported_entries_are_candidates)}`,
+      `  source_store_mutated: ${String(receipt.authority_boundary.source_store_mutated)}`,
+    ].join('\n'));
+    return;
+  }
+
+  if (verb === 'sharded-drain-import') {
+    const receipt = await shardedDrainImportMemoryCandidates({
+      targetProjectRoot: projectRoot,
+      sourceStoreId: requireString(flags, 'from-store'),
+      targetStoreId: requireString(flags, 'to-store'),
+      shards: parseShardSpecs(flags.shard),
+      sourceStoresRoot: optionalString(flags, 'from-root') ? resolve(requireString(flags, 'from-root')) : undefined,
+      targetStoresRoot: optionalString(flags, 'to-root') ? resolve(requireString(flags, 'to-root')) : undefined,
+      targetWorkspaceRef: optionalString(flags, 'target-ref'),
+      receiptDir: optionalString(flags, 'receipt-dir'),
+      receiptPath: optionalString(flags, 'receipt') ? resolve(requireString(flags, 'receipt')) : undefined,
+      at: optionalString(flags, 'at'),
+    });
+    console.log(json ? JSON.stringify(receipt, null, 2) : [
+      'memory_sharded_drain_import:',
+      `  receipt_id: ${receipt.receipt_id}`,
+      `  drain_topology: ${receipt.topology.drain_topology}`,
+      `  shard_key: ${receipt.topology.shard_key}`,
+      `  shard_count: ${receipt.topology.shard_count}`,
+      `  imported_count: ${receipt.totals.imported_count}`,
+      `  promotion_gate_required: ${String(receipt.authority_boundary.promotion_gate_required)}`,
+      `  sharded_drain_can_write_parent_ledger: ${String(receipt.authority_boundary.sharded_drain_can_write_parent_ledger)}`,
+      `  candidate_import_is_canonical_truth: ${String(receipt.authority_boundary.candidate_import_is_canonical_truth)}`,
+    ].join('\n'));
+    return;
+  }
+
+  if (verb === 'search') {
+    const query = positionals.slice(2).join(' ').trim();
+    if (!query) throw new Error('<query> is required');
+    const items = searchMemory({ projectRoot, dbPath, query, limit: asLimit(flags.limit, 10) });
+    console.log(json ? JSON.stringify(items, null, 2) : renderCompact(items));
+    return;
+  }
+
+  if (verb === 'show') {
+    const capsuleId = positionals[2];
+    if (!capsuleId) throw new Error('<capsule_id> is required');
+    const capsule = showMemory({ projectRoot, dbPath, capsuleId });
+    if (!capsule) throw new Error(`unknown capsule: ${capsuleId}`);
+    console.log(JSON.stringify(capsule, null, 2));
+    return;
+  }
+
+  if (verb === 'preflight') {
+    const topic = positionals.slice(2).join(' ').trim();
+    if (!topic) throw new Error('<lane-or-task> is required');
+    const items = preflightMemory({ projectRoot, dbPath, topic, limit: asLimit(flags.limit, 5) });
+    console.log(json ? JSON.stringify(items, null, 2) : renderCompact(items));
+    return;
+  }
+
+  if (verb === 'context') {
+    const positionalQuery = positionals.slice(2).join(' ').trim();
+    const query = optionalString(flags, 'query') ?? (positionalQuery || undefined);
+    const context = buildMemoryContext({
+      projectRoot,
+      dbPath,
+      query,
+      laneRef: optionalString(flags, 'lane'),
+      taskRef: optionalString(flags, 'task'),
+      orgId: optionalString(flags, 'org-id'),
+      workspaceId: optionalString(flags, 'workspace-id'),
+      limit: asLimit(flags.limit, 5),
+    });
+    console.log(json ? JSON.stringify(context, null, 2) : renderContext(context));
+    return;
+  }
+
+  if (verb === 'stale') {
+    const items = staleMemory({ projectRoot, dbPath, limit: asLimit(flags.limit, 10) });
+    console.log(json ? JSON.stringify(items, null, 2) : renderCompact(items));
+    return;
+  }
+
+  if (verb === 'rejected') {
+    const items = rejectedMemory({ projectRoot, dbPath, limit: asLimit(flags.limit, 10) });
+    console.log(json ? JSON.stringify(items, null, 2) : renderRejected(items));
+  }
+}

package/packages/control/src/cli/commands/release.ts

@@ -0,0 +1,108 @@
+import { resolve } from 'node:path';
+import { optionalString } from '../argv';
+import {
+  buildReleaseGaReadinessReport,
+  buildReleaseReadinessReport,
+  listReleaseDistributionChannels,
+  type ReleaseDistributionChannel,
+  type ReleaseGaReadinessReport,
+  type ReleaseReadinessReport,
+} from '../../release/readiness';
+
+const RELEASE_VERBS = new Set(['readiness', 'ga-readiness', 'channels']);
+
+export function isReleaseCommand(command: string): boolean {
+  return command === 'release';
+}
+
+function renderReadiness(report: ReleaseReadinessReport): string {
+  const lines = [
+    'release_readiness:',
+    `  schema: ${report.schema}`,
+    `  verdict: ${report.verdict}`,
+    `  package: ${report.package.name ?? 'unknown'}@${report.package.version ?? 'unknown'}`,
+    `  private: ${String(report.package.private)}`,
+    `  codex_recommended_minimum: ${report.client_compatibility.codex_recommended_minimum}`,
+    `  core_release_requires_codex: ${String(report.client_compatibility.core_release_requires_codex)}`,
+    `  blockers: ${report.blockers.join(', ') || 'none'}`,
+    `  warnings: ${report.warnings.join(', ') || 'none'}`,
+    `  command_can_publish: ${String(report.authority_boundary.command_can_publish)}`,
+    `  command_can_flip_private: ${String(report.authority_boundary.command_can_flip_private)}`,
+    `  command_can_create_distribution_channel: ${String(report.authority_boundary.command_can_create_distribution_channel)}`,
+  ];
+  for (const item of report.checks) {
+    lines.push(`  - ${item.id}: ${item.status} (${item.summary})`);
+    if (item.next_action) lines.push(`    next: ${item.next_action}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function renderGaReadiness(report: ReleaseGaReadinessReport): string {
+  const lines = [
+    'release_ga_readiness:',
+    `  schema: ${report.schema}`,
+    `  verdict: ${report.verdict}`,
+    `  channel: ${report.channel ?? 'missing'}`,
+    `  tag: ${report.tag ?? 'unknown'}`,
+    `  channels: ${report.channels.map((item) => `${item.id}(${item.kind})`).join(', ') || 'none'}`,
+    `  package_readiness: ${report.package_readiness}`,
+    `  blockers: ${report.blockers.join(', ') || 'none'}`,
+    `  warnings: ${report.warnings.join(', ') || 'none'}`,
+    `  command_can_publish: ${String(report.authority_boundary.command_can_publish)}`,
+    `  command_can_sign: ${String(report.authority_boundary.command_can_sign)}`,
+    `  command_can_tag: ${String(report.authority_boundary.command_can_tag)}`,
+    `  command_can_create_distribution_channel: ${String(report.authority_boundary.command_can_create_distribution_channel)}`,
+  ];
+  for (const item of report.checks) {
+    lines.push(`  - ${item.id}: ${item.status} (${item.summary})`);
+    if (item.next_action) lines.push(`    next: ${item.next_action}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function renderChannels(channels: ReleaseDistributionChannel[]): string {
+  const lines = ['release_channels:'];
+  for (const item of channels) {
+    lines.push(`  - ${item.id}: ${item.kind}`);
+    lines.push(`    label: ${item.label}`);
+    lines.push(`    private_repo_compatible: ${String(item.private_repo_compatible)}`);
+    lines.push(`    artifact: ${item.artifact}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+export async function dispatchRelease(
+  positionals: string[],
+  flags: Record<string, string | boolean>,
+): Promise<void> {
+  const verb = positionals[1];
+  if (!verb || !RELEASE_VERBS.has(verb)) {
+    throw new Error(`release verb must be one of: ${[...RELEASE_VERBS].join(', ')}`);
+  }
+
+  const projectRoot = resolve(optionalString(flags, 'project') ?? process.cwd());
+  if (verb === 'channels') {
+    const channels = listReleaseDistributionChannels();
+    console.log(Boolean(flags.json) ? JSON.stringify({ schema: 'release-channels.v0', channels }, null, 2) : renderChannels(channels));
+    return;
+  }
+
+  if (verb === 'readiness') {
+    const report = await buildReleaseReadinessReport(projectRoot);
+    console.log(Boolean(flags.json) ? JSON.stringify(report, null, 2) : renderReadiness(report));
+    if (flags['fail-on-blocked'] && report.verdict === 'blocked') {
+      process.exit(1);
+    }
+    return;
+  }
+
+  const report = await buildReleaseGaReadinessReport(projectRoot, {
+    channel: optionalString(flags, 'channel'),
+    tagFreeConfirmed: Boolean(flags['tag-free-confirmed']),
+    verifyTagRemote: optionalString(flags, 'verify-tag-remote'),
+  });
+  console.log(Boolean(flags.json) ? JSON.stringify(report, null, 2) : renderGaReadiness(report));
+  if (flags['fail-on-blocked'] && report.verdict === 'blocked') {
+    process.exit(1);
+  }
+}

package/packages/control/src/cli/commands/rubric.ts

@@ -0,0 +1,103 @@
+import { resolve } from 'node:path';
+import { optionalString, requireString } from '../argv';
+import {
+  loadFixtureSet,
+  loadPromotionPolicy,
+  loadRubric,
+  loadSandboxReceipt,
+} from '../../rubric/loader';
+import { runRubricSandbox } from '../../rubric/runner';
+import { evaluatePromotionReadiness } from '../../rubric/promotion';
+import { RUN_ENVIRONMENTS, type RunEnvironment } from '../../rubric/types';
+
+const RUBRIC_VERBS = new Set(['validate', 'sandbox', 'promote-check']);
+
+export function isRubricCommand(command: string): boolean {
+  return command === 'rubric';
+}
+
+function parseRunEnvironment(raw: string | boolean | undefined): RunEnvironment {
+  if (raw === undefined) return 'local';
+  if (typeof raw !== 'string' || !(RUN_ENVIRONMENTS as readonly string[]).includes(raw)) {
+    throw new Error(`--environment must be one of: ${RUN_ENVIRONMENTS.join(', ')}`);
+  }
+  return raw as RunEnvironment;
+}
+
+function renderValidate(rubric: Awaited<ReturnType<typeof loadRubric>>): string {
+  return [
+    'rubric_validate:',
+    `  rubric_id: ${rubric.rubric_id}`,
+    `  rubric_version: ${rubric.rubric_version}`,
+    `  kind: ${rubric.kind}`,
+    `  status: ${rubric.status}`,
+  ].join('\n');
+}
+
+function renderSandbox(receipt: Awaited<ReturnType<typeof runRubricSandbox>>): string {
+  return [
+    'rubric_sandbox:',
+    `  receipt_id: ${receipt.receipt_id}`,
+    `  rubric_id: ${receipt.rubric_id}`,
+    `  total_fixtures: ${receipt.summary.total_fixtures}`,
+    `  known_bad_rejected: ${receipt.summary.known_bad_rejected}`,
+    `  known_good_accepted: ${receipt.summary.known_good_accepted}`,
+    `  unexpected_outcomes: ${receipt.summary.unexpected_outcomes}`,
+  ].join('\n');
+}
+
+function renderPromotion(result: Awaited<ReturnType<typeof evaluatePromotionReadiness>>): string {
+  return [
+    'rubric_promotion_check:',
+    `  rubric_id: ${result.rubric_id}`,
+    `  recommendation: ${result.recommendation}`,
+    `  missing: ${result.missing.join(', ') || 'none'}`,
+    `  can_activate_rubric: ${String(result.authority_boundary.can_activate_rubric)}`,
+  ].join('\n');
+}
+
+export async function dispatchRubric(
+  positionals: string[],
+  flags: Record<string, string | boolean>,
+): Promise<void> {
+  const verb = positionals[1];
+  if (!verb || !RUBRIC_VERBS.has(verb)) {
+    throw new Error(`rubric verb must be one of: ${[...RUBRIC_VERBS].join(', ')}`);
+  }
+  const json = Boolean(flags.json);
+
+  if (verb === 'validate') {
+    const rubric = await loadRubric(resolve(requireString(flags, 'rubric')));
+    console.log(json ? JSON.stringify(rubric, null, 2) : renderValidate(rubric));
+    return;
+  }
+
+  if (verb === 'sandbox') {
+    const rubric = await loadRubric(resolve(requireString(flags, 'rubric')));
+    const fixtureSet = await loadFixtureSet(resolve(requireString(flags, 'fixtures')));
+    const receipt = await runRubricSandbox({
+      rubric,
+      fixtureSet,
+      runBy: requireString(flags, 'run-by'),
+      runEnvironment: parseRunEnvironment(flags.environment),
+      runAt: optionalString(flags, 'at'),
+      receiptPath: optionalString(flags, 'receipt') ? resolve(requireString(flags, 'receipt')) : undefined,
+    });
+    console.log(json ? JSON.stringify(receipt, null, 2) : renderSandbox(receipt));
+    return;
+  }
+
+  if (verb === 'promote-check') {
+    const rubric = await loadRubric(resolve(requireString(flags, 'rubric')));
+    const receipt = await loadSandboxReceipt(resolve(requireString(flags, 'receipt')));
+    const policyPath = optionalString(flags, 'policy');
+    const policy = policyPath ? await loadPromotionPolicy(resolve(policyPath)) : undefined;
+    const result = evaluatePromotionReadiness({
+      rubric,
+      receipt,
+      policy,
+      grantRef: optionalString(flags, 'grant-ref'),
+    });
+    console.log(json ? JSON.stringify(result, null, 2) : renderPromotion(result));
+  }
+}