@dzhechkov/harness-cli 0.3.233 → 0.3.235

package/dist/index.d.ts

@@ -6,5 +6,5 @@
 /** Package version. Kept in sync with `package.json`. */
 export declare const HARNESS_CLI_VERSION: string;
 export { runCli } from './cli.js';
-export type { CliIo } from './cli.js';
+export type { CliIo, ReleaseExecRunner } from './cli.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,EAAE,MACkD,CAAC;AAErF,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,EAAE,MACkD,CAAC;AAErF,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.233",
+  "version": "0.3.235",
   "description": "The dz CLI — install AI skills for Claude Code, Codex, OpenCode, Hermes, OpenClaude, GitHub Copilot. 35 commands, 13 presets, 6 platform targets.",
   "type": "module",
   "license": "MIT",
@@ -57,7 +57,7 @@
     "@dzhechkov/skills-reverse-engineering": "^0.1.0",
     "@dzhechkov/skills-presentation-storyteller": "^0.1.0",
     "@dzhechkov/skills-website-cloner": "^0.1.0",
-    "@dzhechkov/harness-core": "0.3.125"
+    "@dzhechkov/harness-core": "0.3.126"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",

package/sbom.json

@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "028658845c4fc1e9bd9487b575be0aee727d477fa9ad1b08c26299ce61f622c3"
+          "content": "99fa5178a48b6953b8f3a6f1690204a3b5449004b7dd105e7a3155ad3658266c"
         }
       ]
     },
@@ -45,7 +45,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "23ae1f330a8fad23eabe444e89dc9d4588297cc1abca5929356eb6fec9f5079d"
+          "content": "cab99dd5d4068013a0c5f4f1c2d29dbec07729dc47c1d77adba6a53b773d0026"
         }
       ]
     },
@@ -55,7 +55,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "2eade3dbce1a9fd33a0775269af13fe97c62fdf1dbf44a8569ba0e7341315433"
+          "content": "2cc80ec378c1f9cd2588676588ee1b73bfe4f2f7ef3b96879c295eb86dccd2c2"
         }
       ]
     },
@@ -85,7 +85,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "b28a956544f4358d57df98fc6c8df0b8f5d5cd8e8b102cee80ed3aabdf0a112b"
+          "content": "84842f3916c558b1f4f2da2a5b0236587f146dda1f6ab4ba4c31ed7b8b17f943"
         }
       ]
     },
@@ -105,7 +105,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "406be5cb9294367793daed191b2418bb99669186c8ead8a3a3f994f0db36e1b6"
+          "content": "378ef9c8fcde4e77594b29a5f043b57f880f5df2b40fce679addfae756670154"
         }
       ]
     },
@@ -175,7 +175,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "d304769099f8a7f79ba6c295e0348c2aa211527b050dbfff597f7e87c2b80505"
+          "content": "628c55bb864dd8a8f337a9cb3fe4271f0df7c0bf9237b1150427171f0577fd57"
         }
       ]
     },
@@ -185,7 +185,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "680727bef753625ed99fd9d79ab846c9024608ef0f88d19ee2c8aec25eccf130"
+          "content": "45c0c1328829a56cfe0ea0ebc74c15477a00bb683b496404688ab4b7b7a88ef8"
         }
       ]
     },
@@ -195,7 +195,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "672bc2fd640d9a92b5af7bfe2880843a770bfedd610f679ae022892fa7c8e66c"
+          "content": "20974a159438ac73a4c308cdb3710154dd9fe0450ed5184f6f3938792380fece"
         }
       ]
     },
@@ -205,7 +205,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "08ec7cf51a49ec818b789cbb6f32b8fc71756e498c99d8756212d16329a8b147"
+          "content": "bfb9ecebeb1c3cc631f2c8e7f46af4318e3698789c9dda49aaebbe26fe1c7fa7"
         }
       ]
     },
@@ -215,7 +215,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "c1ddc3aa44ca13264d54a72ad8376d8321de06ab48262eb2a6c8d5023c011bb6"
+          "content": "aaac0134a074fd06e9b5e09daa952ef6353510e481885da51a6e4f2e92beba35"
         }
       ]
     },
@@ -225,7 +225,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "a8697ddfabf35947e17a255fce26dfee141f2184f6789c32ba1de75dcd80e36c"
+          "content": "459c3381a9fbcd3378b623f9fe103a8d3337e4025a2f546b6d40e4d9dd4e0f70"
         }
       ]
     },
@@ -265,7 +265,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "b48c494a4d4e2126e033c2d0019e463b9ad6cd3bae7a2aa0da296eba1ab66fcf"
+          "content": "c03aafaeaf663bb47b756608049bf77f6460615f1e806054644ec830c524cf72"
         }
       ]
     },
@@ -285,7 +285,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "14ca947c27f366c1377c129b3def86cdd4577536249e44f0009f31884fff9018"
+          "content": "6b8d21416576a2744b5d9bf973d7b878c255495829fcf3679b183a977abc55a2"
         }
       ]
     },
@@ -295,7 +295,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "f0aea91d07867603d177da6029f97851ced0b91b62e9db5d0bab5b464f794a91"
+          "content": "395b27b317e575b94a1049cdb284db185e0ec382fbae1e588c78ff2398b2563f"
         }
       ]
     },
@@ -305,7 +305,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "d9374e1cc23923c2d5c4cca1e228f31e2c3465f187d1c84cf3f50ad947401537"
+          "content": "09472c195254c359f14256c39e8c7afd08c0b71aadb57cd077534f0d7c482005"
         }
       ]
     },

package/src/cli.ts

@@ -114,6 +114,15 @@ import {
   listSignablePackFiles,
   assertKeyOutsideTree,
   decidePublishGate,
+  collectPackageFacts,
+  planReleaseGates,
+  selectAffectedPackages,
+  classifyGateExecutions,
+  buildFailureIssue,
+  buildReleaseNotes,
+  releaseTagName,
+  firstOutputLine,
+  formatPublishError,
   MANIFEST_NAME,
   SBOM_NAME,
   buildArchitectureMap,
@@ -170,7 +179,7 @@ import {
 } from '@dzhechkov/harness-core';
 import type { Family, ModelRung, Candidate as BtoCandidate, DimScores } from '@dzhechkov/harness-core';
 import type { SetupSpec } from '@dzhechkov/harness-core';
-import type { ProvenanceMode, PackVerdict, ClaudeUsageModel, PatternRecord, TargetName, BookKU, HarmonizeReport, UsageCalibrationPlan, ClaimFinding, RecallUsagePatternRow } from '@dzhechkov/harness-core';
+import type { ProvenanceMode, PackVerdict, ClaudeUsageModel, PatternRecord, TargetName, BookKU, HarmonizeReport, UsageCalibrationPlan, ClaimFinding, RecallUsagePatternRow, GateExecution, GateStep } from '@dzhechkov/harness-core';
 import { getPreset, PRESET_NAMES } from '@dzhechkov/harness-presets';
 import { scanGitHub, analyzeRepo, generateReport, deepAnalyze, scanAllSources, ScoutMemory } from '@dzhechkov/scout';
 
@@ -194,6 +203,7 @@ Usage:
   dz sign   --pack <dir> --key <path-outside-repo>          (Ed25519 manifest + CycloneDX SBOM for a pack)
   dz verify-pack --pack <dir> [--pubkey <path>]             (signature check; fail-closed; key from the repo, never the pack)
   dz publish [--filter <name>] [--bump-only] [--claim-check <off|warn|error>] [--require-signing] [--provenance|--no-provenance]   (dry-run by default; pass --yes/--confirm/--no-dry-run to go live; claim-check gate default warn — surfaces README claim findings, never blocks; error fails an offending package)
+  dz release [--filter <name>] [--tag] [--publish] [--json] [--dry-run] [--no-issue]   (VERIFIED release: 4 HARD gates in FRONT of dz publish — full package test suites, audit >=high, node --check of every dist/bin file, bin smoke-boot via "node <bin> --help" — any red gate STOPS the release (exit 1) + best-effort gh issue; all green ⇒ re-sign reminder, then prints the ready dz publish command (or chains with --publish); never duplicates publish's own gates)
   dz setup --target <name> [--preset <name>] [--select id,id,...] [--skills-dir <dir>] [--project <dir>] [--memory agentdb] [--no-memory] [--no-hooks] [--install-driver] [--force] [--enrich]
   dz teach "<pattern>" [--reward <0-1>] [--domain <name>] [--type rule|success-pattern|lesson-learned] [--project <dir>] [--no-mirror]   (--project pins the learned store to <dir>/.dz, not the cwd — pin to a canonical brain)
   dz teach --from-json <file> [--project <dir>] [--no-mirror]   (bulk-import a 'dz recall --all --json' export — share a learned store across machines)
@@ -254,8 +264,21 @@ export interface CliIo {
    * command that needs it (`brain ground`), and never when stdin is a TTY (nothing piped).
    */
   readonly stdin?: string;
+  /**
+   * Test seam for `dz release`: overrides subprocess execution for gate steps and the
+   * gh/git side channels (production leaves it unset → real `execSync`, stdio piped).
+   * A scripted runner makes failing gates, gh outages, and git-tag failures testable
+   * without spawning anything.
+   */
+  readonly releaseRunner?: ReleaseExecRunner;
 }
 
+/** Injected subprocess runner used by `dz release` (see {@link CliIo.releaseRunner}). */
+export type ReleaseExecRunner = (
+  cmd: string,
+  opts: { readonly cwd: string; readonly timeoutMs: number },
+) => { exitCode: number; stdout: string; stderr: string; timedOut?: boolean };
+
 interface ParsedArgs {
   readonly command: string;
   readonly options: Map<string, string>;
@@ -3548,6 +3571,294 @@ function cmdPublish(options: Map<string, string>, flags: Set<string>, cwd: strin
   return report.errors > 0 ? 1 : 0;
 }
 
+/* ------------------------------------------------------------------ */
+/*  dz release — verified-release conveyor (feature release-verified,  */
+/*  ADR-001): 4 HARD gates in FRONT of the untouched dz publish.       */
+/* ------------------------------------------------------------------ */
+
+/**
+ * The single executor of the pure engine's {@link GateStep} plan. ALL subprocess side effects
+ * of the release live here (engine purity, NFR-1). Contract highlights:
+ *
+ * - ALL four gates execute even after an earlier gate fails (AM-9/FR-6 — no fail-fast hiding);
+ *   one red gate still reddens the release.
+ * - Smoke steps run in a THROWAWAY cwd (AM-4): skills bins are installers that mutate
+ *   `.claude/` on default action.
+ * - gh issue + git tag are best-effort periphery: loud on failure, NEVER verdict- or
+ *   exit-code-affecting (FR-7/FR-8, AM-6).
+ * - On green it never injects `--yes/--confirm/--no-dry-run` into the printed/chained publish
+ *   (AM-5): live publish stays the operator's explicit act, and `--publish` chains into
+ *   publish's own default (dry-run) protocol with ALL its gates untouched.
+ */
+function cmdRelease(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write, runner?: ReleaseExecRunner): number {
+  const json = flags.has('json');
+  const warnings: string[] = [];
+  const say = (line: string): void => {
+    if (!json) write(line);
+  };
+  const loud = (line: string): void => {
+    warnings.push(line);
+    if (!json) write(line);
+  };
+  const emitJson = (obj: Record<string, unknown>): void => {
+    if (json) write(JSON.stringify({ ...obj, warnings }, null, 2));
+  };
+  // G9 reuse-never-copy: the engine's firstOutputLine, not a byte-parallel local copy.
+  const oneLine = firstOutputLine;
+
+  // Strict allowlist (cmdPublish's typo-rejection pattern) — a mistyped flag is NEVER
+  // swallowed, and the rejection honors the --json contract too (AC-7).
+  // `--verified` is accepted but not read: verified is the DEFAULT and only mode of
+  // `dz release` in this slice — the flag exists so the branded invocation is not a typo error.
+  const allowedFlags = new Set(['verified', 'tag', 'publish', 'json', 'dry-run', 'no-issue', 'affected', 'audit-dev', 'help']);
+  const allowedOptions = new Set(['filter']);
+  const allowedHelp = '  allowed: --verified, --filter <substr>, --affected, --audit-dev, --tag, --publish, --json, --dry-run, --no-issue';
+  const rejectUnknown = (key: string): number => {
+    if (json) write(JSON.stringify({ error: `unknown option --${key}`, allowed: allowedHelp.trim(), publishAction: 'blocked', exitCode: 1 }, null, 2));
+    else {
+      write(`dz release: unknown option --${key}`);
+      write(allowedHelp);
+    }
+    return 1;
+  };
+  for (const flag of flags) if (!allowedFlags.has(flag)) return rejectUnknown(flag);
+  for (const key of options.keys()) {
+    if (key.startsWith('_positional_')) continue;
+    if (!allowedOptions.has(key)) return rejectUnknown(key);
+  }
+
+  // --filter mirrors publish semantics: trim + drop empties; empty result is an ERROR,
+  // never "match all" (the publish P0 regression this deliberately copies).
+  const filterStr = options.get('filter');
+  let filter: string[] | undefined;
+  if (filterStr !== undefined) {
+    filter = filterStr.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+    if (filter.length === 0) {
+      if (json) write(JSON.stringify({ error: '--filter requires a non-empty comma-separated list of package-name substrings', publishAction: 'blocked', exitCode: 1 }, null, 2));
+      else write('dz release: --filter requires a non-empty comma-separated list of package-name substrings');
+      return 1;
+    }
+  }
+
+  // DETECT — real facts via the engine's one fs seam (discoverPackages underneath).
+  let factsList: ReturnType<typeof collectPackageFacts>;
+  try {
+    factsList = collectPackageFacts(cwd, filter);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (json) write(JSON.stringify({ error: msg, publishAction: 'blocked', exitCode: 1 }, null, 2));
+    else write(`dz release: ${msg}`);
+    return 1;
+  }
+  if (factsList.length === 0) {
+    // C-6: outside a workspace (or an over-narrow filter) — explain and exit non-zero, never throw.
+    const msg = 'no publishable packages found under packages/@dzhechkov — run from the monorepo root (or widen --filter)';
+    if (json) write(JSON.stringify({ error: msg, packages: [], publishAction: 'blocked', exitCode: 1 }, null, 2));
+    else write(`dz release: ${msg}`);
+    return 1;
+  }
+
+  // Executor: default = real execSync with piped stdio + timeout; injectable for tests.
+  // Defined BEFORE planning because --affected needs read-only git diffs at DETECT time.
+  const run: ReleaseExecRunner =
+    runner ??
+    ((cmd, opts) => {
+      try {
+        const stdout = execSync(cmd, { cwd: opts.cwd, stdio: 'pipe', encoding: 'utf-8', timeout: opts.timeoutMs });
+        return { exitCode: 0, stdout: stdout == null ? '' : String(stdout), stderr: '' };
+      } catch (err) {
+        const e = err as Error & { status?: number | null; signal?: string | null; killed?: boolean; stdout?: unknown; stderr?: unknown };
+        // execSync's timeout kills via signal and leaves status null — that IS the timeout shape.
+        const timedOut = (e.status === null || e.status === undefined) && (e.signal != null || e.killed === true);
+        return {
+          exitCode: typeof e.status === 'number' ? e.status : 1,
+          stdout: e.stdout == null ? '' : String(e.stdout),
+          stderr: e.stderr == null || String(e.stderr).trim() === '' ? formatPublishError(e) : String(e.stderr),
+          timedOut,
+        };
+      }
+    });
+
+  // AM-8/--affected: narrow the release set to packages touched by the working tree + last
+  // commit. Selection is the PURE selectAffectedPackages; the two read-only git diffs are the
+  // injected fact source. Any git failure ⇒ null ⇒ FAIL-OPEN to the full set (never zero).
+  if (flags.has('affected')) {
+    const dWork = run('git diff --name-only HEAD', { cwd, timeoutMs: 10_000 });
+    const dLast = run('git diff --name-only HEAD~1..HEAD', { cwd, timeoutMs: 10_000 });
+    const anyOk = dWork.exitCode === 0 || dLast.exitCode === 0;
+    const changed = anyOk
+      ? [dWork, dLast]
+          .filter((r) => r.exitCode === 0)
+          .flatMap((r) => r.stdout.split('\n'))
+          .map((s) => s.trim())
+          .filter((s) => s.length > 0)
+      : null;
+    const selected = selectAffectedPackages(changed, factsList);
+    if (changed === null) loud('dz release --affected: ⚠ git diff unavailable — FAIL-OPEN to the full package set');
+    else say(`dz release --affected: ${selected.length}/${factsList.length} package(s) selected from ${changed.length} changed file(s)${selected.length === factsList.length ? ' (no narrowing — full set)' : ''}`);
+    factsList = selected;
+  }
+
+  const plan = planReleaseGates(factsList, {
+    monorepoRoot: cwd,
+    pnpmLockPresent: existsSync(join(cwd, 'pnpm-lock.yaml')),
+    includeDevDeps: flags.has('audit-dev'),
+  });
+
+  // --dry-run: print the full plan, execute NOTHING (deterministic, byte-testable preview).
+  if (flags.has('dry-run')) {
+    if (json) {
+      write(JSON.stringify({ dryRun: true, packages: plan.packages, steps: plan.steps, skips: plan.skips, warnings }, null, 2));
+      return 0;
+    }
+    write(`\ndz release --dry-run — plan only, zero commands executed (${plan.packages.length} package(s))`);
+    for (const gate of ['tests', 'audit', 'syntax', 'smoke'] as const) {
+      const steps = plan.steps.filter((s) => s.gate === gate);
+      write(`  ${gate} (${steps.length} step(s)):`);
+      for (const s of steps) {
+        if (s.kind === 'synthetic-fail') write(`    ✗ [planned ${s.failClass ?? 'FAIL'}] ${s.pkg ?? ''}: ${s.reason}`);
+        else write(`    · ${s.cmd}  (cwd=${s.tempCwd === true ? '<temp>' : s.cwd}, timeout=${s.timeoutMs}ms)`);
+      }
+      if (gate === 'tests') for (const sk of plan.skips) write(`    ○ [${sk.class}] ${sk.pkg}: ${sk.reason}`);
+    }
+    write('  → run without --dry-run to execute the gates');
+    return 0;
+  }
+
+  // VERIFY — execute EVERY exec step (AM-9: all 4 gates run and report even after a failure).
+  const executions: GateExecution[] = [];
+  let smokeTmp: string | undefined;
+  const execSteps: GateStep[] = plan.steps.filter((s) => s.kind !== 'synthetic-fail');
+  say(`\ndz release — executing ${execSteps.length} gate step(s) across ${plan.packages.length} package(s)…`);
+  for (const step of execSteps) {
+    let stepCwd = step.cwd;
+    if (step.tempCwd === true) {
+      // AM-4: boot bins in a throwaway cwd so an installer-style bin cannot mutate the workspace.
+      if (smokeTmp === undefined) smokeTmp = mkdtempSync(join(tmpdir(), 'dz-release-smoke-'));
+      stepCwd = smokeTmp;
+    }
+    const started = Date.now();
+    const r = run(step.cmd, { cwd: stepCwd, timeoutMs: step.timeoutMs });
+    executions.push({
+      stepId: step.id,
+      exitCode: r.exitCode,
+      stdout: r.stdout,
+      stderr: r.stderr,
+      durationMs: Date.now() - started,
+      timedOut: r.timedOut,
+    });
+  }
+  if (smokeTmp !== undefined) {
+    try { rmSync(smokeTmp, { recursive: true, force: true }); } catch { /* best-effort cleanup */ }
+  }
+
+  const verdict = classifyGateExecutions(plan, executions);
+
+  // Report: per-gate ✓/✗/○ with package granularity + timestamp (NFR-5). Skips are named,
+  // never folded into pass wording (AM-2: "N passed, M skipped", not "all tests passed").
+  for (const g of verdict.gates) {
+    const icon = g.status === 'pass' ? '✓' : g.status === 'fail' ? '✗' : '○';
+    say(`  ${icon} ${g.gate.padEnd(7)} ${g.status.toUpperCase().padEnd(4)}  ${g.passed} passed, ${g.failures.length} failed, ${g.skips.length} skipped`);
+    for (const f of g.failures) say(`      [${f.class}] ${f.pkg !== undefined ? `${f.pkg}: ` : ''}${f.reason}`);
+    for (const sk of g.skips) say(`      [${sk.class}] ${sk.pkg}: ${sk.reason}`);
+  }
+  say(`  verdict at ${verdict.timestamp}: ${verdict.publishAction === 'proceed' ? '✓ all gates green' : '✗ RELEASE BLOCKED'}`);
+
+  const invocation = `dz release${filterStr !== undefined ? ` --filter ${filterStr}` : ''}`;
+  const shq = (s: string): string => `'${s.replace(/'/g, `'\\''`)}'`;
+
+  if (verdict.publishAction === 'blocked') {
+    say(`dz release: ✗ release STOPPED — ${verdict.blockedBy.join('; ')}`);
+    // FR-7 / AM-6: best-effort issue — a courier, never a judge. Loud on any failure;
+    // the verdict and exit code are ALREADY decided and cannot change here.
+    let issueUrl: string | undefined;
+    if (!flags.has('no-issue')) {
+      const issue = buildFailureIssue(verdict, { invocation });
+      const probe = run('command -v gh', { cwd, timeoutMs: 10_000 });
+      if (probe.exitCode !== 0) {
+        loud(`dz release: ⚠ gh unavailable — file the issue manually: ${issue.title}`);
+      } else {
+        const res = run(`gh issue create --title ${shq(issue.title)} --body ${shq(issue.body)}`, { cwd, timeoutMs: 30_000 });
+        if (res.exitCode === 0) {
+          issueUrl = oneLine(res.stdout) || undefined;
+          say(`dz release: gh issue created${issueUrl !== undefined ? `: ${issueUrl}` : ''}`);
+        } else {
+          loud(`dz release: ⚠ gh issue creation failed (${oneLine(res.stderr, res.stdout) || 'unknown error'}) — file the issue manually: ${issue.title}`);
+        }
+      }
+    }
+    emitJson({
+      gates: verdict.gates,
+      ok: verdict.ok,
+      blockedBy: verdict.blockedBy,
+      skipped: verdict.skipped,
+      publishAction: verdict.publishAction,
+      timestamp: verdict.timestamp,
+      ...(issueUrl !== undefined ? { issueUrl } : {}),
+      exitCode: 1,
+    });
+    return 1;
+  }
+
+  // Success path. FR-8: --tag is best-effort trimming — loud on failure, never gate-affecting.
+  let tagName: string | undefined;
+  if (flags.has('tag')) {
+    const sha = run('git rev-parse --short HEAD', { cwd, timeoutMs: 10_000 });
+    const log = run('git log --oneline -n 15 --no-decorate', { cwd, timeoutMs: 10_000 });
+    const notes = buildReleaseNotes(log.exitCode === 0 ? log.stdout.split('\n') : []);
+    tagName = releaseTagName(new Date(), sha.exitCode === 0 ? sha.stdout.trim() : '');
+    const tag = run(`git tag -a ${tagName} -m ${shq(notes)}`, { cwd, timeoutMs: 10_000 });
+    if (tag.exitCode === 0) {
+      say(`dz release: tagged ${tagName} (annotated with short release notes from recent commits)`);
+      say('dz release: note — the tag attests a VERIFIED tree, not a completed publish');
+    } else {
+      loud(`dz release: ⚠ git tag failed (${oneLine(tag.stderr, tag.stdout) || 'unknown error'}) — non-blocking; tag manually: git tag -a ${tagName}`);
+    }
+  }
+
+  // FR-10 / AC-8: re-sign reminder BEFORE the handoff — publish's signature gate is
+  // refuse-unsigned, and gates 3–4 often follow a rebuild.
+  say('dz release: reminder — re-sign any rebuilt packs BEFORE publishing (dz sign --pack <dir> --key <path-outside-repo>); the publish signature gate is refuse-unsigned');
+
+  // FR-9 / AM-5: the handoff NEVER injects --yes/--confirm/--no-dry-run — live publish stays
+  // the operator's explicit, loud-bannered act inside dz publish itself.
+  const publishCommand = `dz publish${filterStr !== undefined ? ` --filter ${filterStr}` : ''}`;
+  let publishExit: number | undefined;
+  let publishOutput: string[] | undefined;
+  if (flags.has('publish')) {
+    say(`dz release: ✓ gates green — chaining into ${publishCommand} in-process (ALL publish gates + its dry-run-by-default protocol run untouched)`);
+    const pubOptions = new Map<string, string>(filterStr !== undefined ? [['filter', filterStr]] : []);
+    // --json contract: the chained publish must NOT print prose before the JSON envelope —
+    // capture its lines and carry them INSIDE the envelope instead (stdout stays one JSON doc).
+    if (json) {
+      publishOutput = [];
+      const captured = publishOutput;
+      publishExit = cmdPublish(pubOptions, new Set<string>(), cwd, (line: string) => {
+        captured.push(line);
+      });
+    } else {
+      publishExit = cmdPublish(pubOptions, new Set<string>(), cwd, write);
+    }
+  } else {
+    say(`dz release: ✓ all gates green — publish when ready: ${publishCommand}`);
+  }
+
+  emitJson({
+    gates: verdict.gates,
+    ok: verdict.ok,
+    blockedBy: verdict.blockedBy,
+    skipped: verdict.skipped,
+    publishAction: verdict.publishAction,
+    timestamp: verdict.timestamp,
+    ...(tagName !== undefined ? { tag: tagName } : {}),
+    publishCommand,
+    ...(publishExit !== undefined ? { publishExit } : {}),
+    ...(publishOutput !== undefined ? { publishOutput } : {}),
+    exitCode: publishExit ?? 0,
+  });
+  return publishExit ?? 0;
+}
+
 function cmdRegistry(options: Map<string, string>, cwd: string, write: Write): number {
   const registry = buildRegistry(cwd);
   if (registry.totalSkills === 0) {
@@ -4234,6 +4545,26 @@ function gatherReadmeCounts(root: string): { label: string; a: number; b: number
   const rootAll = num(rootMd, /## All Commands \((\d+)\)/);
   if (cjm !== null && cliAll !== null) pairs.push({ label: 'commands (root CJM header vs cli All Commands)', a: cjm, b: cliAll });
   if (rootAll !== null && cliAll !== null) pairs.push({ label: 'All Commands (root vs cli)', a: rootAll, b: cliAll });
+  // sitedoc in the readme-first contour (feature sitedoc-readme-first, ADR-001 + Codex QE AM-3/AM-4):
+  // the docs SITE carries the same command count as the cli README. A MISSING file skips its pair
+  // (target repo without sitedoc — missing-evidence contract). But a file that EXISTS and no longer
+  // matches its anchored pattern emits a MISMATCH pair (a: -1) — silent non-extraction is the exact
+  // disease this contour cures (AM-1 applies to the guard path too, not only the CI test).
+  const sitePair = (rel: string, re: RegExp, label: string): void => {
+    if (cliAll === null || !existsSync(join(root, rel))) return;
+    const found = num(read(rel), re);
+    pairs.push({ label, a: found ?? -1, b: cliAll });
+  };
+  sitePair(
+    'packages/@dzhechkov/sitedoc/src/content/docs/cli/overview.md',
+    /^description: All (\d+) dz commands/m,
+    'commands (docs-site CLI overview description vs cli All Commands)',
+  );
+  sitePair(
+    'packages/@dzhechkov/sitedoc/src/content/docs/index.mdx',
+    /^\s*tagline: "[^"]*?(\d+) commands/m,
+    'commands (docs-site index hero tagline vs cli All Commands)',
+  );
   return pairs;
 }
 
@@ -5399,6 +5730,8 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         return await cmdAutoCanonicalize(options, cwd, write);
       case 'publish':
         return cmdPublish(options, flags, cwd, write);
+      case 'release':
+        return cmdRelease(options, flags, cwd, write, io.releaseRunner);
       case 'registry':
         return cmdRegistry(options, cwd, write);
       case 'benchmark':

package/src/index.ts

@@ -11,4 +11,4 @@ export const HARNESS_CLI_VERSION: string =
   (createRequire(import.meta.url)('../package.json') as { version: string }).version;
 
 export { runCli } from './cli.js';
-export type { CliIo } from './cli.js';
+export type { CliIo, ReleaseExecRunner } from './cli.js';