@dzhechkov/harness-cli 0.3.210 → 0.3.212

package/README.md

@@ -132,7 +132,7 @@ point any tool at (a skill is just Markdown). Dedicated targets are on the [road
 
 ## User Journey — from install to mastery
 
-All 41 commands mapped to a real workflow:
+All 43 commands mapped to a real workflow:
 
 ```
 DISCOVER → INSTALL → USE → CREATE → MAINTAIN → SHARE
@@ -280,6 +280,81 @@ npx @dzhechkov/keysarium init                        # 7-phase research + comman
 - Need a **themed set** that works together → `--preset`
 - Need a **full pipeline** with commands and governance → `npx`
 
+### `dz sign` / `dz verify-pack` — cryptographic tamper-evidence
+
+Ed25519 over a file manifest, plus a CycloneDX SBOM. Zero dependencies (`node:crypto`).
+
+**What it answers:** *are the bytes I am looking at the bytes the holder of the pinned key signed?*
+**What it does NOT answer:** whether those bytes are any good. A signature gives provenance and
+tamper-evidence, never truthfulness.
+
+```bash
+# Sign a pack. The private key MUST live outside the repo — dz refuses otherwise.
+dz sign --pack packages/@dzhechkov/skills-qe --key ~/.dz/keys/dz.key
+
+# Verify. The public key comes from the REPO (keys/dz.pub), never from the pack itself:
+# whoever replaced the pack would have replaced a key shipped inside it.
+dz verify-pack --pack packages/@dzhechkov/skills-qe          # exit 0 = unmodified
+dz verify-pack --pack ./downloaded-pack --pubkey keys/dz.pub # explicit trust root
+```
+
+A single flipped byte, a deleted file, or an **added** file all fail verification and the offending
+path is named. Every degenerate input (no manifest, empty file list, empty signature, no public key)
+fails **closed** — absence never reads as success.
+
+`dz publish` runs the check before publishing anything. With `keys/dz.pub` committed, an unsigned or
+mismatching pack **blocks the release**. Until then, packs publish unsigned and `dz publish` says so on
+every run; `--require-signing` turns that into a refusal today.
+
+**From Claude Code, in plain language:**
+> "Sign the QE skill pack with my key at ~/.dz/keys/dz.key, then verify it."
+> "Check whether the pack I just downloaded matches what we published."
+> "Publish, but refuse if anything is unsigned."
+
+### Signature checks in `dz doctor` and `dz upgrade`
+
+`dz doctor` verifies every installed `skills-*` pack against a **pinned** Ed25519 key, and `dz upgrade`
+verifies what it just installed. A pack that does not match its signed manifest is **fatal**:
+
+```bash
+dz doctor                      # ... signatures: 3 verified, 0 unsigned, 0 TAMPERED, 0 unverifiable
+dz doctor --require-signing    # an unsigned pack becomes fatal too
+dz upgrade                     # a TAMPERED pack aborts the upgrade
+dz doctor --pubkey ./my.pub    # verify against a key you pinned yourself
+```
+
+Key precedence: `--pubkey` > the repository's `keys/dz.pub` > the key shipped inside `harness-cli`.
+The key **never** comes from the pack being verified — whoever replaced the pack would have replaced a
+key that travelled inside it.
+
+**Honest limits.** The packaged key lives in the verifier and vouches for *other* packs; a compromised
+`harness-cli` is outside the threat model, because you have already run its code. And a signature proves
+the bytes are unmodified — never that the skill is any good. Today no key is committed, so every pack
+reports `unverifiable` and nothing fails.
+
+**From Claude Code, in plain language:**
+> "Run doctor and tell me if any installed pack was modified."
+> "Upgrade, but abort if anything fails its signature."
+
+### npm provenance on release
+
+`dz publish` appends `--provenance` **only** where an OIDC token can be minted — `GITHUB_ACTIONS=true`
+plus both `ACTIONS_ID_TOKEN_REQUEST_URL` and `ACTIONS_ID_TOKEN_REQUEST_TOKEN`, which GitHub exports under
+`permissions: id-token: write`.
+
+```bash
+dz publish                 # auto: provenance in CI, silent no-op locally
+dz publish --provenance    # force. FAILS before the batch if the environment cannot mint a token
+dz publish --no-provenance # escape hatch for a registry outage; prints why it was used
+```
+
+Provenance proves *which workflow, at which commit, built this tarball* — and there is no private key for
+anyone to leak. It does **not** prove the code is good, and an attacker who can push to `main` and trigger
+the release job gets a perfectly attested malicious package.
+
+A ready-to-install workflow is at `features/publish-provenance/07_code_changes/publish.yml`; copy it to
+`.github/workflows/` and add an `NPM_TOKEN` secret.
+
 ### Skill Packs (22 packs · 173 skills)
 
 Each pack is an npm package — click through for the **full per-skill documentation** (what each skill does + how to trigger it). Install a whole pack with `dz install <pkg>`, or pick skills with `dz init --select` / a `--preset`.
@@ -301,7 +376,7 @@ Each pack is an npm package — click through for the **full per-skill documenta
 | [@dzhechkov/skills-pm](https://www.npmjs.com/package/@dzhechkov/skills-pm) | 18 | *imported (MIT)* — product-management toolkit: OST, RICE/ICE prioritization, product-strategy, pricing, OKRs, NSM/metrics/A-B/cohort, outcome-roadmap, stakeholder-map, sprint-plan, strategy-red-team, GTM/growth/beachhead, market-sizing; curated from phuryn/pm-skills (`dz init --preset pm`) ([ADR-0002](https://github.com/djd1m/dz-harness-hub/blob/main/docs/adr/0002-product-and-design-expansion.md)) |
 | [@dzhechkov/skills-taste](https://www.npmjs.com/package/@dzhechkov/skills-taste) | 1 | *imported (MIT)* — `design-taste-frontend`: anti-slop landing/portfolio/redesign framework (dials + pre-flight + GSAP skeletons); complements frontend-design (`dz init --select design-taste-frontend`) ([ADR-0002](https://github.com/djd1m/dz-harness-hub/blob/main/docs/adr/0002-product-and-design-expansion.md)) |
 | [@dzhechkov/skills-book-digitizer](https://www.npmjs.com/package/@dzhechkov/skills-book-digitizer) | 8 | *dz-original* — book → installable methodology pack: `digitize-book` (orchestrator) + ingest/extract/distill/pack/kb-index + `book-brain-register` (CP6 promote → cross-project brain) + `source-brain-ingest` (repo sibling). Verified provenance, IP-safe, resumable (`dz init --select digitize-book`) ([ADR-001](https://github.com/djd1m/dz-harness-hub/blob/main/features/book-knowledge-digitizer/03_adr/001-book-to-skillpack-pipeline.md)) |
-| [@dzhechkov/skills-12factor](https://www.npmjs.com/package/@dzhechkov/skills-12factor) | 12 | *generated by the digitizer, CC BY 4.0* — The Twelve-Factor App distilled into 12 decision-moment skills (one per factor). The first PUBLIC digitized-book pack; paraphrased (shingling-gated), routing-gated 100%/0%, attributed (`NOTICE`) (`dz init --select 12factor-config-in-environment,…`) |
+| [@dzhechkov/skills-12factor](https://www.npmjs.com/package/@dzhechkov/skills-12factor) | 12 | *generated by the digitizer, CC BY 4.0* — The Twelve-Factor App distilled into 12 decision-moment skills (one per factor). The first PUBLIC digitized-book pack; paraphrased (shingling-gated), routing-gated (every factor carries triggers), attributed (`NOTICE`) (`dz init --select 12factor-config-in-environment,…`) |
 
 ### Available Presets (13)
 
@@ -356,7 +431,7 @@ Get the whole set with `dz init --target claude-code --preset meta`, or pick one
 
 > **A skill and its npx toolkit are not duplicates — they're a graduation.** Several skills (e.g. `feature-adr`, `design-thinking`) exist BOTH as a skill inside a `dz` preset AND as a standalone `npx` package. The preset's SKILL.md is **fully functional on its own** (the whole methodology — modules + references — travels with it, and it auto-activates by description), and it's the only way to compile that capability to the **non-Claude platforms** (Codex/OpenCode/Hermes/OpenClaude) via `dz`. The npx package adds **project-level runtime governance** around the same skill: a slash command, governance rules, a context shard, and (for feature-adr) reward-learning + `/harvest`. So: pick the **skill/preset** for a working capability across platforms; pick the **npx toolkit** when you want it as a governed, command-driven fixture of one project.
 
-## All Commands (41)
+## All Commands (43)
 
 ```
 dz setup             --target <name> [--preset <name>] [--select id,id,...] [--skills-dir <dir>] [--memory agentdb] [--no-memory] [--no-hooks] [--install-driver] [--force]
@@ -1049,7 +1124,7 @@ Or cherry-pick: `dz compose meta+keysarium` for competitive analysis.
 
 Without optional skills, design-thinking uses built-in fallbacks.
 
-BTO benchmark: L0 Grade A (100%), L2 Opus weighted 7.58/10.
+BTO benchmark: L0 Grade A, L2 Opus weighted 7.58/10.
 
 ---
 

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAuKH,2EAA2E;AAC3E,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AA+xHD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkH5E"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAqLH,2EAA2E;AAC3E,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAyiID,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAsH5E"}

package/dist/cli.js

@@ -5,11 +5,11 @@
  */
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, rmdirSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { execSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { createRequire } from 'node:module';
-import { fileURLToPath } from 'node:url';
-import { createSkill, getSkillInfo, getWorkflow, isTargetName, listSkills, runDoctor, runInit, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, TARGET_NAMES, WORKFLOW_NAMES, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, } from '@dzhechkov/harness-core';
+import { createSkill, getSkillInfo, getWorkflow, isTargetName, listSkills, runDoctor, runInit, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, TARGET_NAMES, WORKFLOW_NAMES, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, buildManifest, buildSbom, resolveTrustRoot, decideVerifyPolicy, decideProvenance, isInsideTree, signManifest, verifyManifest, assertKeyOutsideTree, decidePublishGate, MANIFEST_NAME, SBOM_NAME, } from '@dzhechkov/harness-core';
 import { getPreset, PRESET_NAMES } from '@dzhechkov/harness-presets';
 import { scanGitHub, analyzeRepo, generateReport, deepAnalyze, scanAllSources, ScoutMemory } from '@dzhechkov/scout';
 const USAGE = `dz - DZ cross-platform harness CLI
@@ -22,13 +22,16 @@ Usage:
   dz list   [--skills-dir <dir>]
   dz info   <skill-id> [--skills-dir <dir>]
   dz migrate [--project <dir>]
-  dz doctor [--project <dir>]
   dz create-skill --name <id> [--description <text>] [--skills-dir <dir>] [--tier <1-3>] [--with-references] [--no-evals] [--bto]
   dz scout   [--topics <list>] [--since <date>] [--deep] [--output <file>] [--diff] [--report]
   dz workflow <task> [--dry-run]
   dz install <npm-pkg> [--target <name>] [--project <dir>] [--force]
   dz bundle  [--preset <name> | --select id,id,...] [--out <dir>] [--skills-dir <dir>] [--force]   (portable self-contained skill bundles for a generic/LangGraph consumer)
-  dz publish [--filter <name>] [--bump-only] [--claim-check <off|warn|error>]   (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 doctor  [--project <dir>] [--pubkey <path>] [--require-signing]   (health + signature check of installed packs)
+  dz upgrade [--target <name>] [--pubkey <path>] [--require-signing]   (a TAMPERED pack aborts the upgrade)
+  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 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)
@@ -57,7 +60,6 @@ Usage:
   dz recommend "<task description>"
   dz compose <preset1+preset2+...> [--target <name>]
   dz diff <skill-dir>
-  dz upgrade [--target <name>] [--project <dir>]
   dz auto-canonicalize --source <github-url> --pack <skills-pack>
   dz registry [search <query>] [--category <cat>]
   dz benchmark <skill-dir> [--compare <dir>] [--all]
@@ -505,14 +507,18 @@ function cmdMigrate(options, cwd, write) {
     write(`\nRecommendation: ${report.recommendation}`);
     return 0;
 }
-async function cmdDoctor(options, cwd, write) {
+async function cmdDoctor(options, flags, cwd, write) {
     const projectRoot = resolve(cwd, options.get('project') ?? '.');
     const report = await runDoctor({ projectRoot });
     write(`dz doctor (${report.node}):`);
     for (const check of report.checks) {
         write(`  [${check.ok ? 'OK' : 'XX'}] ${check.name} - ${check.detail}`);
     }
-    return report.ok ? 0 : 1;
+    // ADR-001 (verify-apply-leg): the consumer-side apply-leg. A TAMPERED pack is fatal; an unsigned
+    // pack or a missing trust root is reported. A signature proves the bytes are unmodified — never
+    // that the skill is any good.
+    const sigFatal = reportPackVerification(projectRoot, options.get('pubkey'), flags.has('require-signing'), write);
+    return report.ok && sigFatal === 0 ? 0 : 1;
 }
 function cmdRoam(options, flags, cwd, write) {
     const apply = flags.has('apply');
@@ -2653,7 +2659,7 @@ function cmdRecommend(options, cwd, write) {
     write(`   Get it: dz init --target claude-code --select skill-advisor   (or --preset meta)`);
     return 0;
 }
-function cmdUpgrade(options, cwd, write) {
+function cmdUpgrade(options, flags, cwd, write) {
     const targetOpt = options.get('target') ?? 'claude-code';
     if (!isTargetName(targetOpt)) {
         write(`dz upgrade: --target must be one of: ${TARGET_NAMES.join(', ')}`);
@@ -2692,6 +2698,12 @@ function cmdUpgrade(options, cwd, write) {
     if (report.needsUpdate > 0) {
         write(`\n${report.needsUpdate} skill(s) need update. Run: dz init --target ${targetOpt} --force`);
     }
+    // ADR-001 (verify-apply-leg): verify what we just left on disk. A TAMPERED pack aborts.
+    const sigFatal = reportPackVerification(projectRoot, options.get('pubkey'), flags.has('require-signing'), write);
+    if (sigFatal !== 0) {
+        write('dz upgrade: aborting — an installed pack does not match its signed manifest');
+        return 1;
+    }
     return 0;
 }
 async function cmdAutoCanonicalize(options, cwd, write) {
@@ -2753,10 +2765,212 @@ async function cmdAutoCanonicalize(options, cwd, write) {
         return 1;
     }
 }
+/** The pinned trust root. A key inside the artifact under verification is data, not a key (ADR-001). */
+const TRUST_ROOT_REL = 'keys/dz.pub';
+function packFiles(dir) {
+    const out = [];
+    const walk = (d, rel) => {
+        for (const e of readdirSync(d, { withFileTypes: true })) {
+            if (e.name === 'node_modules' || e.name === '.git')
+                continue;
+            if (e.name === MANIFEST_NAME || e.name === SBOM_NAME)
+                continue;
+            const abs = join(d, e.name);
+            const r = rel ? rel + '/' + e.name : e.name;
+            if (e.isDirectory())
+                walk(abs, r);
+            else if (e.isFile())
+                out.push(r);
+        }
+    };
+    walk(dir, '');
+    return out.sort();
+}
+/**
+ * The consumer-side apply-leg (ADR-001, verify-apply-leg). All security content lives in the two pure
+ * functions in harness-core; this only resolves paths, reads bytes, and reports.
+ *
+ * The packaged key sits inside harness-cli — the VERIFIER — and vouches for other packs. It never
+ * comes from the pack under verification.
+ */
+function packagedTrustRootPath() {
+    // dist/cli.js -> ../keys/dz.pub  (and src/cli.ts -> ../keys/dz.pub when run from source)
+    const p = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'keys', 'dz.pub');
+    return existsSync(p) ? p : undefined;
+}
+function verifyInstalledPacks(cwd, explicitPubkey) {
+    // Cross-model review: `--pubkey ./missing.pub` used to fall back to the repo/packaged key and could
+    // then report `verified` against a key the caller never asked for. An explicit request that cannot be
+    // honoured is an error, not a suggestion.
+    const explicit = explicitPubkey ? resolve(cwd, explicitPubkey) : undefined;
+    if (explicit !== undefined && !existsSync(explicit)) {
+        throw new Error('dz: --pubkey ' + explicit + ' does not exist — refusing to fall back to another key');
+    }
+    const repoKey = resolve(cwd, TRUST_ROOT_REL);
+    const trustRoot = resolveTrustRoot({
+        explicit: explicit && existsSync(explicit) ? explicit : undefined,
+        repo: existsSync(repoKey) ? repoKey : undefined,
+        packaged: packagedTrustRootPath(),
+    });
+    const packs = discoverSkillPackDirs(cwd);
+    // Cross-model review: `--pubkey <pack>/evil.pub` would let the artifact supply its own verifying key
+    // through the caller. The tool must never verify a pack against a key that lives inside it.
+    if (trustRoot?.source === 'explicit') {
+        for (const { dir } of packs) {
+            if (isInsideTree(trustRoot.path, dir)) {
+                throw new Error('dz: --pubkey lives inside the pack being verified (' + dir + ') — refusing');
+            }
+        }
+    }
+    const checks = [];
+    for (const { pack, dir } of packs) {
+        if (trustRoot === null) {
+            checks.push({ pack, verdict: 'no-trust-root', failures: [] });
+            continue;
+        }
+        const manifestPath = join(dir, MANIFEST_NAME);
+        if (!existsSync(manifestPath)) {
+            checks.push({ pack, verdict: 'unsigned', failures: [] });
+            continue;
+        }
+        let signed;
+        try {
+            signed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        }
+        catch {
+            checks.push({ pack, verdict: 'tampered', failures: [{ path: MANIFEST_NAME, reason: 'not valid JSON' }] });
+            continue;
+        }
+        // The key existed when the trust root was resolved; it can vanish before it is read. A crash is
+        // not a verdict — fail closed with a named reason.
+        let keyPem;
+        try {
+            keyPem = readFileSync(trustRoot.path, 'utf8');
+        }
+        catch {
+            checks.push({ pack, verdict: 'no-trust-root', failures: [] });
+            continue;
+        }
+        const res = verifyManifest(dir, signed, keyPem);
+        checks.push({
+            pack,
+            verdict: res.ok ? 'verified' : 'tampered',
+            failures: res.failures.map((f) => ({ path: f.path, reason: f.reason })),
+        });
+    }
+    return { trustRoot, checks };
+}
+/** Print the pack verdicts and return 1 iff the policy says any of them is fatal. */
+function reportPackVerification(cwd, explicitPubkey, requireSigning, write) {
+    let trustRoot;
+    let checks;
+    try {
+        ({ trustRoot, checks } = verifyInstalledPacks(cwd, explicitPubkey));
+    }
+    catch (err) {
+        // A refusal is a result, not a crash: the user gets one line, not a stack trace.
+        write(`  [XX] ${err.message}`);
+        return 1;
+    }
+    if (checks.length === 0)
+        return 0;
+    const counts = { verified: 0, unsigned: 0, tampered: 0, 'no-trust-root': 0 };
+    let fatal = 0;
+    for (const c of checks) {
+        counts[c.verdict]++;
+        const decision = decideVerifyPolicy(c.verdict, requireSigning);
+        // Only a FATAL verdict earns a line of its own. 22 identical "unverifiable" lines is noise, and
+        // noise is how a real failure gets scrolled past.
+        if (decision.action === 'fail') {
+            fatal++;
+            write(`  [XX] ${c.pack} - ${decision.reason}`);
+            for (const f of c.failures)
+                write(`         ${f.path}: ${f.reason}`);
+        }
+    }
+    const root = trustRoot ? `${trustRoot.source} (${trustRoot.path})` : 'none';
+    write(`  signatures: ${counts.verified} verified, ${counts.unsigned} unsigned, ` +
+        `${counts.tampered} TAMPERED, ${counts['no-trust-root']} unverifiable; trust root: ${root}`);
+    // A signature proves the bytes are unmodified. It never proves the skill is any good.
+    return fatal > 0 ? 1 : 0;
+}
+function cmdSign(options, flags, cwd, write) {
+    const pack = options.get('pack');
+    const key = options.get('key');
+    if (!pack || !key) {
+        write('dz sign: --pack <dir> and --key <path> are both required');
+        write('  the key path MUST be outside the repository working tree (a leaked signing key is not revertible)');
+        return 1;
+    }
+    const packDir = resolve(cwd, pack);
+    if (!existsSync(packDir)) {
+        write(`dz sign: no such pack: ${packDir}`);
+        return 1;
+    }
+    try {
+        assertKeyOutsideTree(resolve(cwd, key), cwd);
+    }
+    catch (err) {
+        write(`dz sign: ${err.message}`);
+        return 1;
+    }
+    if (!existsSync(resolve(cwd, key))) {
+        write(`dz sign: private key not found: ${resolve(cwd, key)}`);
+        return 1;
+    }
+    const files = packFiles(packDir);
+    if (files.length === 0) {
+        write('dz sign: the pack contains no files — refusing to sign nothing');
+        return 1;
+    }
+    const manifest = buildManifest(packDir, basename(packDir), files);
+    const signed = signManifest(manifest, readFileSync(resolve(cwd, key), 'utf8'));
+    writeFileSync(join(packDir, MANIFEST_NAME), JSON.stringify(signed, null, 2) + '\n');
+    writeFileSync(join(packDir, SBOM_NAME), JSON.stringify(buildSbom(manifest), null, 2) + '\n');
+    write(`dz sign: signed ${files.length} file(s) in ${packDir}`);
+    write(`  ${MANIFEST_NAME} + ${SBOM_NAME} written. Ed25519 gives tamper-evidence, never truthfulness.`);
+    return 0;
+}
+function cmdVerifyPack(options, flags, cwd, write) {
+    const pack = options.get('pack');
+    if (!pack) {
+        write('dz verify-pack: --pack <dir> is required');
+        return 1;
+    }
+    const packDir = resolve(cwd, pack);
+    // The key is pinned in the repo. Never read it from the pack (ADR-001, recalled lesson).
+    const pubPath = resolve(cwd, options.get('pubkey') ?? TRUST_ROOT_REL);
+    if (!existsSync(pubPath)) {
+        write(`dz verify-pack: no trust root at ${pubPath} — refusing to verify (fail closed)`);
+        return 1;
+    }
+    const manifestPath = join(packDir, MANIFEST_NAME);
+    if (!existsSync(manifestPath)) {
+        write(`dz verify-pack: ${packDir} carries no ${MANIFEST_NAME}`);
+        return 1;
+    }
+    let signed = null;
+    try {
+        signed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    }
+    catch {
+        write(`dz verify-pack: ${MANIFEST_NAME} is not valid JSON`);
+        return 1;
+    }
+    const res = verifyManifest(packDir, signed, readFileSync(pubPath, 'utf8'));
+    if (res.ok) {
+        write(`dz verify-pack: OK — ${packDir} matches its signed manifest`);
+        return 0;
+    }
+    write(`dz verify-pack: FAILED — ${packDir}`);
+    for (const f of res.failures)
+        write(`  ${f.path}: ${f.reason}`);
+    return 1;
+}
 function cmdPublish(options, flags, cwd, write) {
     // Reject unknown flags/options so a typo (e.g. `--dry-rum`) can NEVER be
     // silently swallowed and flip the command into live-publish mode.
-    const allowedFlags = new Set(['dry-run', 'no-dry-run', 'yes', 'confirm', 'bump-only', 'help']);
+    const allowedFlags = new Set(['dry-run', 'no-dry-run', 'yes', 'confirm', 'bump-only', 'help', 'require-signing', 'provenance', 'no-provenance']);
     const allowedOptions = new Set(['filter', 'claim-check']);
     const allowedHelp = '  allowed: --dry-run (default), --yes/--confirm/--no-dry-run (go live), --bump-only, --filter <substr>, --claim-check <off|warn|error>';
     for (const flag of flags) {
@@ -2775,6 +2989,20 @@ function cmdPublish(options, flags, cwd, write) {
             return 1;
         }
     }
+    // ADR-001 (publish-provenance): decide BEFORE any work — flag validation, then a pre-flight that
+    // refuses `--provenance` where no OIDC token can be minted. `off` is an escape hatch that names itself.
+    if (flags.has('provenance') && flags.has('no-provenance')) {
+        write('dz publish: --provenance and --no-provenance are mutually exclusive');
+        return 1;
+    }
+    const provenance = flags.has('provenance') ? 'on' : flags.has('no-provenance') ? 'off' : 'auto';
+    try {
+        write(`dz publish: ${decideProvenance(provenance, process.env).reason}`);
+    }
+    catch (err) {
+        write(err.message);
+        return 1;
+    }
     // Pre-publish claim-check gate strictness: reject (never coerce) an invalid value. Default 'warn'
     // per ADR-001 — findings are SURFACED on every publish, but 'warn' never changes publish status,
     // so the success path is unchanged. 'off' disables the gate; 'error' fails an offending package.
@@ -2825,7 +3053,44 @@ function cmdPublish(options, flags, cwd, write) {
         }
         write(`╚══════════════════════════════════════════════════════════════════════╝`);
     }
-    const report = publishPackages(cwd, { dryRun, filter, bumpOnly, claimGate: claimCheckOpt });
+    // FR-4 — the signature gate, BEFORE anything is published (ADR-001).
+    // Strictness follows the trust root: with no keys/dz.pub committed there is nothing to verify
+    // against, and blocking would refuse every release forever. That is stated on every run.
+    {
+        const trustRoot = resolve(cwd, TRUST_ROOT_REL);
+        const trustRootPresent = existsSync(trustRoot);
+        const requireSigning = flags.has('require-signing');
+        // `filter` is a string[] of substrings (matching publishPackages' own semantics), not a string.
+        const targets = discoverPackages(cwd).filter((pk) => !filter || filter.length === 0 || filter.some((f) => pk.name.includes(f)));
+        let blocked = 0;
+        for (const pk of targets) {
+            const manifestPath = join(pk.dir, MANIFEST_NAME);
+            const manifestPresent = existsSync(manifestPath);
+            let verifyOk = false;
+            if (trustRootPresent && manifestPresent) {
+                try {
+                    const signed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+                    verifyOk = verifyManifest(pk.dir, signed, readFileSync(trustRoot, 'utf8')).ok;
+                }
+                catch {
+                    verifyOk = false;
+                }
+            }
+            const decision = decidePublishGate({ trustRootPresent, manifestPresent, verifyOk, requireSigning });
+            if (decision.action === 'block') {
+                write(`dz publish: BLOCKED ${pk.name} — ${decision.reason}`);
+                blocked++;
+            }
+            else if (decision.action === 'publish-unsigned') {
+                write(`dz publish: ${pk.name} — ${decision.reason}`);
+            }
+        }
+        if (blocked > 0) {
+            write(`dz publish: refusing to publish (${blocked} package(s) failed the signature gate)`);
+            return 1;
+        }
+    }
+    const report = publishPackages(cwd, { provenance, dryRun, filter, bumpOnly, claimGate: claimCheckOpt });
     write(`\ndz publish${dryRun ? ' --dry-run' : ''}${bumpOnly ? ' --bump-only' : ''}${claimCheckOpt !== 'warn' ? ` --claim-check ${claimCheckOpt}` : ''}`);
     write(`  Published: ${report.published}  Skipped: ${report.skipped}  Errors: ${report.errors}\n`);
     for (const pkg of report.packages) {
@@ -3799,7 +4064,7 @@ export async function runCli(argv, io = {}) {
             case 'migrate':
                 return cmdMigrate(options, cwd, write);
             case 'doctor':
-                return await cmdDoctor(options, cwd, write);
+                return await cmdDoctor(options, flags, cwd, write);
             case 'install':
                 return await cmdInstall(options, flags, cwd, write);
             case 'bundle':
@@ -3820,6 +4085,10 @@ export async function runCli(argv, io = {}) {
                 return cmdUsage(options, optionLists, flags, cwd, write);
             case 'claim-check':
                 return cmdClaimCheck(options, optionLists, flags, cwd, write);
+            case 'sign':
+                return cmdSign(options, flags, cwd, write);
+            case 'verify-pack':
+                return cmdVerifyPack(options, flags, cwd, write);
             case 'setup':
                 return await cmdSetup(options, flags, cwd, write);
             case 'pretrain':
@@ -3831,7 +4100,7 @@ export async function runCli(argv, io = {}) {
             case 'recommend':
                 return cmdRecommend(options, cwd, write);
             case 'upgrade':
-                return cmdUpgrade(options, cwd, write);
+                return cmdUpgrade(options, flags, cwd, write);
             case 'auto-canonicalize':
                 return await cmdAutoCanonicalize(options, cwd, write);
             case 'publish':