@dzhechkov/harness-cli 0.3.236 → 0.3.237

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.236",
+  "version": "0.3.237",
   "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.127"
+    "@dzhechkov/harness-core": "0.3.128"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",

package/sbom.json

@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "1e36d7e9e6022d412c030975ec686b1ab91c61c64c807ef2e9ff3fa75ac8917c"
+          "content": "7e8b772a6fa9ca0f36364cafd5ea996abeb62dc894c2f67f50ea7704a7a8824d"
         }
       ]
     },
@@ -35,7 +35,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "1abb00d07ab57ad413d2747baa6a68cda0876a9e0c6f75db89c205fbf4863530"
+          "content": "667bf610bf890a7b93480a4b1045e98dc0c765effd80b78fde4e48538f595b3e"
         }
       ]
     },
@@ -45,7 +45,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "42d2a98f54c2ec773b49a0a43c959a78d070c8c427724f4affbd5bafef35621d"
+          "content": "593705e81f851c0e65ffa9feaa9bbd396e7a3295b9b21076cfd953ee5a05b93a"
         }
       ]
     },
@@ -105,7 +105,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "8a00bf14c3fdd437b7e482da8c4018366041755714ed1791b1c523f9dee5de6c"
+          "content": "cf6a3265890a8856ef31e3e7ac58026c15232c3c118ba0fcd1ce0d7590b84dd8"
         }
       ]
     },
@@ -115,7 +115,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "dea4446db1109285c1fc5f5283d7263462cb446f12b0d9b1e1e821374d0ca57d"
+          "content": "b9af9be1bd31acd60e76275ff1055dd8e9b39b531b0c375467648f142b74d2c4"
         }
       ]
     },
@@ -125,7 +125,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "a253625c94835ef94bbd141b1dd759578433423bd098314fd977c515f140dafe"
+          "content": "6a51963ede51129e43524d62f3d757255a002dfec3df2c1dfa519af6f235a667"
         }
       ]
     },
@@ -185,7 +185,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "543319797d47d599a646c7d695f82aa31491ffd97579edd691b6a9cb99af76ef"
+          "content": "1e7ef1d6e0796144999ad64d3650aeb4a2ccc7dfc66c5c5a8b705d783a9d0801"
         }
       ]
     },
@@ -205,7 +205,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "c5d4902f9b0c4133318b15e757d07856872177dc92752d5996440524342b7f88"
+          "content": "5180330ac6612542c80a74ea8e0983f5cd231e95bb3962eccdd65fbdbf6611a8"
         }
       ]
     },
@@ -225,7 +225,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "0538f3cfd8eb880305c08fef05a78601263003c54a6f1b44f97cd7ebd7bd37f9"
+          "content": "461beed08ad6cfde7bbf559701fcbc6978f622c3951c80463c4e4943c538eff5"
         }
       ]
     },

package/src/cli.ts

@@ -179,6 +179,12 @@ import {
   renderProseDiff,
   readScenarioIds,
   DEFAULT_MAX_JUDGE_RUNS,
+  collectDeliveryFacts,
+  planDeliveryCheck,
+  renderDeliveryBrief,
+  classifyDelivery,
+  isUsablePlaneResult,
+  renderDeliveryReview,
 } from '@dzhechkov/harness-core';
 import type { Family, ModelRung, Candidate as BtoCandidate, DimScores } from '@dzhechkov/harness-core';
 import type { SetupSpec } from '@dzhechkov/harness-core';
@@ -208,6 +214,7 @@ Usage:
   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 parity [--target <name>] [--json]   (the honest feature×target map, COMPUTED from the capability model — which harness feature is full / manual / absent on each of the ${TARGET_NAMES.length} targets, and via which form)
+  dz delivery-check --slug <slug> [--context-only] [--findings <f.json>] [--strict] [--author <model>] [--json]   (portable Step-10 Delivery Gate: prints the 4-plane review brief + artifact probes; --findings classifies a fed-back review into a fail-closed ready|blocked hand-off and writes features/<slug>/10_delivery_review.md; --strict exits 1 on blocked)
   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)
@@ -5201,8 +5208,18 @@ function cmdFeatureAdrSetup(options: Map<string, string>, flags: Set<string>, cw
     return 1;
   }
 
+  // portable-gates (direction b): --gates scaffolds the zero-config architecture/gates/delivery-check.md.
+  // Its "runnable here" list is computed for --target (default agents-md, the AGENTS.md-class target class).
+  const wantGates = flags.has('gates');
+  const targetOpt = options.get('target');
+  if (targetOpt !== undefined && !isTargetName(targetOpt)) {
+    write(`dz feature-adr-setup: --target must be one of: ${TARGET_NAMES.join(', ')}`);
+    return 1;
+  }
+  const gatesTarget: TargetName = isTargetName(targetOpt ?? '') ? (targetOpt as TargetName) : 'agents-md';
+
   const specPath = options.get('from-spec');
-  if (specPath === undefined && !wantGuards) {
+  if (specPath === undefined && !wantGuards && !wantGates) {
     // default + --plan: the read-only "which documents, and where?" answer.
     const plan = buildSetupPlan(scanForSetup(repoRoot));
     if (flags.has('json')) { write(JSON.stringify(plan, null, 2)); return 0; }
@@ -5224,8 +5241,9 @@ function cmdFeatureAdrSetup(options: Map<string, string>, flags: Set<string>, cw
     spec = {}; // --guards standalone: scaffold just the guard set
   }
   if (wantGuards) spec = { ...spec, guards: locCap !== undefined ? { locCap } : true };
+  if (wantGates) spec = { ...spec, gates: true };
 
-  const result = scaffoldFromSpec(spec, readExistingForScaffold(repoRoot));
+  const result = scaffoldFromSpec(spec, readExistingForScaffold(repoRoot), gatesTarget);
   if (flags.has('json') && !flags.has('apply')) { write(JSON.stringify(result, null, 2)); return 0; }
   write(renderScaffoldPreview(result));
 
@@ -5428,6 +5446,137 @@ function nameFor(t: { file: string; name?: string }, outcome: 'pass' | 'fail' |
   return t.name !== undefined ? { file: t.file, name: t.name, outcome } : { file: t.file, outcome };
 }
 
+/**
+ * `dz delivery-check` — the portable Step-10 Delivery Gate (feature portable-gates). The `manual` form that
+ * travels to every `shell` target: the deterministic parts (artifact probes, hand-off arithmetic,
+ * cross-validation bookkeeping) run IN the CLI; the semantic 4-plane review is DISPATCHED to the caller's own
+ * agent runtime — the `dz challenge` cartridge shape. All logic lives in harness-core's pure engine; this is
+ * the executor. Advisory exit codes (0 by default; `--strict` ⇒ 1 on `blocked`).
+ *
+ *   --slug <slug>            the feature under features/<slug> (required; featureDir derived internally)
+ *   --context-only           default mode: print artifact probes + the 4-plane review brief (no verdict)
+ *   --findings <f.json>      classify a fed-back findings array → write 10_delivery_review.md + print ready/blocked
+ *   --strict                 with --findings: exit 1 iff handoff === 'blocked' (CI gate)
+ *   --author <model>         cosmetic: the reviewer to dispatch, printed alongside the brief
+ *   --json                   machine contract { planesChecked, planesSkipped, findings, handoff, artifact }
+ */
+function cmdDeliveryCheck(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  let repoRoot = cwd;
+  try { repoRoot = execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || cwd; } catch { /* not git */ }
+
+  const json = flags.has('json');
+  const errOut = (error: string): number => {
+    if (json) write(JSON.stringify({ error, planesChecked: [], planesSkipped: [], findings: [], handoff: null, artifact: 'not-written' }, null, 2));
+    else { write(`dz delivery-check: ${error}`); write('  allowed: --slug <slug>, --findings <f.json>, --author <model>, --context-only, --strict, --json'); }
+    return 1;
+  };
+  // Strict allowlist (delivery finding: a typo'd --findings silently downgraded the --strict CI
+  // gate to a vacuous exit-0 pass — a mistyped option must be an ERROR, never a mode change).
+  const allowedFlags = new Set(['context-only', 'strict', 'json', 'help']);
+  const allowedOptions = new Set(['slug', 'findings', 'author']);
+  for (const flag of flags) if (!allowedFlags.has(flag)) return errOut(`unknown option --${flag}`);
+  for (const key of options.keys()) {
+    if (key.startsWith('_positional_')) return errOut(`unexpected argument "${options.get(key)}"`);
+    if (!allowedOptions.has(key)) return errOut(`unknown option --${key}`);
+  }
+
+  const slug = options.get('slug');
+  if (slug === undefined || slug.trim() === '') return errOut('pass --slug <slug> (the feature under features/<slug>)');
+  // Slug convention is a SECURITY boundary here (delivery finding, CONFIRMED traversal reproducer:
+  // --slug '../../outside/evil' wrote 10_delivery_review.md outside the repo). kebab-case Latin,
+  // <=40 chars — the repo's own slug rule as a layer-1 three-line check.
+  const slugTrimmed = slug.trim();
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(slugTrimmed) || slugTrimmed.length > 40) {
+    return errOut(`invalid --slug "${slugTrimmed}" — kebab-case Latin, max 40 chars (a path-like slug would redirect the report write)`);
+  }
+  const featureDir = join(repoRoot, 'features', slugTrimmed);
+
+  // --context-only is a real mode flag, not decoration: combining it with --findings contradicts
+  // itself (delivery finding — the flag was accepted and silently ignored).
+  if (flags.has('context-only') && options.get('findings') !== undefined) {
+    return errOut('--context-only and --findings are mutually exclusive (context-only prints the brief; findings classifies the verdict)');
+  }
+
+  // git status --porcelain — CLI layer only (the `no child_process in core` contract); a non-git target
+  // degrades to an empty list, which is honest (AM-10: changed-files is informational, never a required gate).
+  let changedFiles: string[] = [];
+  try {
+    const out = execSync('git status --porcelain', { cwd: repoRoot, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+    changedFiles = out.split('\n').map((l) => l.slice(3).trim()).filter((s) => s.length > 0);
+  } catch { /* non-git / unavailable → empty (honest) */ }
+
+  const facts = collectDeliveryFacts(featureDir, { changedFiles, repoRoot });
+  const plan = planDeliveryCheck(facts);
+  const author = options.get('author');
+
+  const findingsPath = options.get('findings');
+  if (findingsPath === undefined) {
+    // Default / --context-only: emit the led protocol (probes + brief). No verdict — the CLI has no model.
+    if (json) {
+      write(JSON.stringify({
+        planesChecked: [],
+        planesSkipped: plan.planes.map((p) => p.id),
+        findings: [],
+        handoff: null,
+        artifact: 'not-written',
+        probes: plan.probes,
+      }, null, 2));
+      return 0;
+    }
+    write(`dz delivery-check — ${slug} (portable 4-plane hand-off protocol; you drive the review)`);
+    for (const p of plan.probes) {
+      const mark = p.passed === true ? '✓' : p.passed === false ? '✗' : '○';
+      write(`  ${mark} ${p.description}${p.required ? ' [required]' : ' [informational]'}`);
+    }
+    write('');
+    write(renderDeliveryBrief(plan, facts));
+    // The hand-off criterion the verdict will be judged by, shown UP FRONT (this also makes
+    // plan.criterionTemplate a consumed surface, not dead product code — delivery finding).
+    write('\n── hand-off criterion (all must PASS for ready) ──');
+    for (const c of plan.criterionTemplate) write(`  ○ ${c.label}`);
+    if (author !== undefined && author.trim() !== '') write(`\n── reviewer to dispatch ──\n${author.trim()}`);
+    write('\n(next: run the four planes, then `dz delivery-check --slug ' + slug + ' --findings findings.json` for the verdict)');
+    return 0;
+  }
+
+  // --findings mode: parse (malformed/missing ⇒ [], a failed-plane input — fail-closed, never a throw).
+  let reviewResults: unknown[] = [];
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(resolve(cwd, findingsPath), 'utf-8'));
+    if (Array.isArray(parsed)) reviewResults = parsed;
+    else if (parsed !== null && typeof parsed === 'object' && Array.isArray((parsed as { planes?: unknown }).planes)) reviewResults = (parsed as { planes: unknown[] }).planes;
+    else reviewResults = [];
+  } catch { reviewResults = []; }
+
+  const verdict = classifyDelivery(plan, reviewResults as ({ findings?: readonly unknown[] } | null | undefined)[]);
+  // The SAME predicate as the fail-closed verdict (core-exported) — a local copy was a drift channel.
+  const planesChecked = plan.planes.filter((_, i) => isUsablePlaneResult(reviewResults[i])).map((p) => p.id);
+  const planesSkipped = plan.planes.filter((_, i) => !isUsablePlaneResult(reviewResults[i])).map((p) => p.id);
+
+  // Write the regenerable report (NOT augment-never-clobber — deliberately overwritten each run).
+  let artifact: 'written' | 'not-written' = 'not-written';
+  try {
+    const reviewPath = join(featureDir, '10_delivery_review.md');
+    mkdirSync(dirname(reviewPath), { recursive: true });
+    writeFileSync(reviewPath, renderDeliveryReview(verdict, facts));
+    artifact = 'written';
+  } catch { /* best-effort — the verdict is still returned */ }
+
+  if (json) {
+    write(JSON.stringify({ planesChecked, planesSkipped, findings: verdict.findings, handoff: verdict.handoff, artifact }, null, 2));
+  } else {
+    write(`dz delivery-check — ${slug}: ${verdict.handoff}`);
+    for (const c of verdict.criterion) {
+      const mark = c.status === 'PASS' ? '✓' : c.status === 'FAIL' ? '✗' : '○';
+      write(`  ${mark} ${c.label}: ${c.status}${c.detail ? ` — ${c.detail}` : ''}`);
+    }
+    write(artifact === 'written' ? `\n↳ wrote features/${slug}/10_delivery_review.md` : '\n↳ 10_delivery_review.md NOT written (verdict above is authoritative)');
+  }
+
+  if (flags.has('strict') && verdict.handoff === 'blocked') return 1;
+  return 0;
+}
+
 /**
  * `dz routing` — inspect the learned cost-optimal routing outcome store (feature learned-cost-routing). Shows
  * what `args.models[stage]='auto-cost'` currently believes per (stage, complexity-tier, model): gated
@@ -5852,6 +6001,8 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         return cmdChallenge(options, flags, cwd, write);
       case 'discrimination-check':
         return cmdDiscriminationCheck(options, flags, cwd, write);
+      case 'delivery-check':
+        return cmdDeliveryCheck(options, flags, cwd, write);
       case 'routing':
         return cmdRouting(options, flags, cwd, write);
       case 'bto-optimize':