@dzhechkov/harness-cli 0.5.4 → 0.6.1

package/dist/core-compat.d.ts

@@ -39,7 +39,7 @@
  * standing test (`test/core-import-floor.test.ts`, F1) fails if the two drift apart,
  * because a guard that says 0.4.7 while npm may install 0.4.2 is worse than no guard.
  */
-export declare const MIN_CORE = "0.5.4";
+export declare const MIN_CORE = "0.6.1";
 /** The npm name of the guarded package — one literal, used by every leg below. */
 export declare const CORE_PACKAGE_NAME = "@dzhechkov/harness-core";
 /**

package/dist/core-compat.js

@@ -42,7 +42,7 @@ import { fileURLToPath } from 'node:url';
  * standing test (`test/core-import-floor.test.ts`, F1) fails if the two drift apart,
  * because a guard that says 0.4.7 while npm may install 0.4.2 is worse than no guard.
  */
-export const MIN_CORE = '0.5.4';
+export const MIN_CORE = '0.6.1';
 /** The npm name of the guarded package — one literal, used by every leg below. */
 export const CORE_PACKAGE_NAME = '@dzhechkov/harness-core';
 /**

package/keys/README.md

@@ -1,8 +1,47 @@
 # Trust root
 
-`dz.pub` — the pinned Ed25519 public key that `dz doctor` / `dz upgrade` use to verify **other**
-`skills-*` packs. It is not here yet: no project key has been generated (see task #36). Until it is,
-every pack reports `no-trust-root`, and nothing fails.
+`dz.pub` — the pinned Ed25519 **public** key that `dz doctor`, `dz drift-check` and `dz upgrade` fall
+back to when verifying installed skill packs against their `.dz-manifest.json`.
 
-This key verifies other packs, never `harness-cli` itself. A compromised verifier is outside the threat
-model: you have already executed its code. See `features/verify-apply-leg/03_adr/001-keyring-in-the-verifier.md`.
+**It is here now.** Until 2026-08-21 this directory shipped without `dz.pub` — it contained only this
+README, which claimed no project key had been generated. The key had in fact existed at the repo root
+since 2026-07-19. Measured with one binary run from two places on the same day:
+
+```
+$ dz doctor                        # inside the harness repo, which has its own keys/dz.pub
+  signatures: 25 verified, 0 unsigned, 1 TAMPERED, 0 unverifiable; trust root: repo (keys/dz.pub)
+$ dz doctor --project /tmp/consumer
+  signatures: 0 verified, 0 unsigned, 0 TAMPERED, 26 unverifiable; trust root: none
+```
+
+So **every installation that relied on the packaged key** — that is, one passing no `--pubkey` and
+holding no project-local `keys/dz.pub` — had a verifier that verified nothing, and said so in a
+summary line that scrolls past.
+
+## Resolution order
+
+An explicit `--pubkey` wins; then `keys/dz.pub` inside the project being checked; then this packaged
+key. A `--pubkey` that lives INSIDE the pack being verified is refused — an artifact must never supply
+the key that verifies it.
+
+## What a signature proves, and what it does not
+
+It proves that the files **listed in that pack's `.dz-manifest.json`** still hash to the values
+recorded when it was signed. It says nothing about any file the manifest does not list, nothing about
+whether the skill is any good, and nothing about whether the signer deserves trust: pinning this key
+decides which key is ACCEPTED, which is a different question from whether its holder is trustworthy.
+
+## Diagnosing a `TAMPERED` verdict
+
+`TAMPERED` means the bytes on disk disagree with the signed manifest. Before assuming modification,
+check which trust root was actually used — the summary line names it, and an explicit or project-local
+key takes precedence over this one, so a verdict may be reported against a key you did not intend.
+
+Re-signing is a **publisher-side** operation, not a consumer repair: it is correct only when you own
+the pack, have reviewed what changed, and are re-issuing it. The usual innocent cause is an edit made
+after signing, and its remedy is procedural — sign LAST, immediately before packing. A consumer facing
+`TAMPERED` should report it, not silence it.
+
+**Never** place a private key in this directory. The signing key lives outside the repository
+(`~/.dz/keys/dz.key`, mode 0600), `dz sign` refuses to write it anywhere inside the tree, and a test
+asserts no private-key PEM header appears anywhere in the published tarball.

package/keys/dz.pub

@@ -0,0 +1,3 @@
+-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAENTvPc1jcIhqkXHVbrqkcvRpJ56GtOFZByXxwzXEZhM=
+-----END PUBLIC KEY-----

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.5.4",
+  "version": "0.6.1",
   "description": "The dz CLI — install AI skills for Claude Code, Codex, OpenCode, Hermes, OpenClaude, GitHub Copilot. 67 commands, 14 presets, 10 platform targets.",
   "type": "module",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "sbom.json"
   ],
   "dependencies": {
-    "@dzhechkov/harness-core": "^0.5.4",
+    "@dzhechkov/harness-core": "^0.6.1",
     "@dzhechkov/harness-presets": "^0.5.0",
     "@dzhechkov/scout": "^0.8.0",
     "@dzhechkov/skills-devops": "^0.3.0",

package/sbom.json

@@ -15,7 +15,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "9555ead768fef7963e735b0c6af21a64412811531534108be3df61bc65b51021"
+          "content": "b99db6be2d9e6d46f0a9d3ff0877c445efac7b9e90d5fe1db9f5bfa2cb6dc107"
         }
       ]
     },
@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "0d475969dbc98308bf0e23a15700c537ed4947b3cf910b334e647e3972fc78fe"
+          "content": "696aae63a95e8f8726eecc1aa0e68f20d7980e99bb4008b22f2e1058ca67c6c0"
         }
       ]
     },
@@ -105,7 +105,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7c64ed0d976d79fd8f3970ced13e664db1e97c43f96a7b153d7b993948cc5f9f"
+          "content": "8d15372b27f7d79f54df09671b01d5944e8f3f3d87075ba4ece7f0131fc1103e"
         }
       ]
     },
@@ -115,7 +115,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "8052367d84a5a1c4a9f7fb3397a6297edf707031bbfa59b945d240d17e221f04"
+          "content": "be3648deb68dca8a48cc323f34f54c77c05f0ddf0d86982ea9d6f2cc8e073349"
         }
       ]
     },
@@ -125,7 +125,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "f759949bcfaa04c3f4eaebbccde688192d44f129b61115313533f8828f7376f8"
+          "content": "47bcecfe2c9f1daeb73056b3a2c1e10e6b77c465c1bb0d6169690f2276a9cc77"
         }
       ]
     },
@@ -135,7 +135,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "f89dbd282c83fa64f23c8fff3c83bc85c08c8deef451fd4d525e33784c2a0e13"
+          "content": "b735a6c18bfbe5adf17bbcfe6e2eeae71477b877e958c36e0a5e73e59f100d6a"
         }
       ]
     },
@@ -155,7 +155,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "66fd34797f007aa0607698a159fb367a772f32f5be1c2a90748c20cbf4b973cf"
+          "content": "6d052e0a7352e9824bc1d4a319d03b42320f6551210f7dfd360afbdca4e556f0"
         }
       ]
     },
@@ -215,7 +215,17 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "204deec657a7f147bf3016441082c2f868f6f11051776f4edc13ec6b44745192"
+          "content": "142fc5d0d59003476b8e7367d6fc21fe40ce9e0bf70159318a05abdb10502b8a"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "keys/dz.pub",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "353885160582f8e0cfb2a97ef9e51f77997f0120841f92a1ce50d202ebf5dd73"
         }
       ]
     },
@@ -225,7 +235,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "797bfd035a68dc039ca33393f02f4ed1fe97e1021559e01906a0fbbc9b28c1dc"
+          "content": "a43608842dab18914486c96c1989b294031f35118bb91c1e8bd0807041a10ddd"
         }
       ]
     },
@@ -245,7 +255,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "9338e5f5dd5cbb1f3692cb7db53531f103bc28450c109765bf161664a7598a5b"
+          "content": "d39fa1f437401419889965674889df3e5091d4ed76242e36f8e70f18683d4e4a"
         }
       ]
     },
@@ -255,7 +265,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "ba96d37f80c98618a1d8ca61cf071c9d26c74dab8d277106e9079068428a5b71"
+          "content": "5fef10b3d968d299eb7463157e8b164413872f7cc8bf5e9ca1c605e63569a9f7"
         }
       ]
     },
@@ -279,6 +289,16 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "test/amendment-check-cli.test.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "3dd543fd3032f1fca5c063af98a7501b4cccb9d7e42f6c307074b67f2d55d231"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "test/cli.test.ts",
@@ -295,7 +315,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "f744cfe02805f567312a196805ebc49486c3e2a8e3f64de1700be276481f0cc1"
+          "content": "d9677688116c0a35591cb7e53ab1502566e44336959ac0ea449f5e8a1c5e31e3"
         }
       ]
     },
@@ -349,6 +369,16 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "test/feature-adr-record-cli.test.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "e1a2687a1ae2bc2d32cbcc852487d30f9451ce1ea4a132e188186dd4251c49d1"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "test/fixtures/discrimination-check/fake-runner.sh",
@@ -639,6 +669,16 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "test/packaged-trust-root.test.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "46c0af5494ad717eb4d936489f4bde2199b40cd756ab6c8adb0cd1714a971304"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "test/parallel-worktree-smoke.test.ts",
@@ -655,7 +695,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "be010af797aeae754a3dd3e9f6f25d6f01066d4bf2037a01322554453d943ee3"
+          "content": "fafa2d1ff56bd41a6496b7ce569be671f2f617deac07425f47ad6e87b3ec00ce"
         }
       ]
     },

package/src/cli.ts

@@ -399,7 +399,20 @@ import {
   serializeBundle,
   parseBundle,
   planImport,
+  decideCheckpointWrite,
+  amendmentSection,
+  planSaysNoAmendments,
+  parseAmendments,
+  resolveAmendments,
+  decideAmendmentOutcome,
+  amendmentVerdictLine,
+  amendmentsMissingFromPlan,
+  AMENDMENT_VACUITY_NOTE,
+  decideRecordWrite,
+  decideReadBack,
+  recordVerdictLine,
 } from '@dzhechkov/harness-core';
+import type { RecordKind, RecordDecision } from '@dzhechkov/harness-core';
 import type { MutationEntryResult, MutationObservation, MutationRegistryEntry } from '@dzhechkov/harness-core';
 import type { SkillApplyFailure, SkillLoadFailure } from '@dzhechkov/harness-core';
 import type { ReqeDebt } from '@dzhechkov/harness-core';
@@ -449,6 +462,9 @@ Usage:
   dz epoch-replay --judge <filled-work-order.json> [--out <file>]   (blind judge prompts from the filled plans)
   dz epoch-replay --score <judgments.json> --work-order <file> [--slice <name>] [--json]   (un-blind against the pre-registered assignment → SUPPORTED only when the two 95% Wilson CIs are DISJOINT, else FALSIFIED / INCONCLUSIVE)
   dz score --slug <feature> [--project <dir>] [--json]   (process scorecard for ONE feature-adr run, from its artifacts: ADR confirmation, discrimination, cross-model QE grade, live verification, README-first, learning loop, amendments — descriptive-only, a low score exits 0)
+  dz amendment-check --slug <slug> | --feature-dir <dir> | --all [--json]   (the deterministic Step-8 amendment gate: every AM-N row must resolve to a test found INSIDE the file the row names; the PLAN is authoritative when it carries rows, and an ideation amendment the plan drops is a failure. exit 0 pass/skip, 1 fail, 3 NOT-ESTABLISHED — a section that parsed ZERO rows is never a pass. --all is a CENSUS and always exits 0. Does NOT prove non-vacuity — that is dz discrimination-check)
+  dz feature-adr-record --kind ledger|training-pair --stage <s> [--slug <s>] [--row|--pair <json>] [--mark <n>] [--once] [--json]   (the witnessed writer for the run-cost ledger and training pairs: the payload arrives as an ARGUMENT, never as shell; a malformed or wrong-kind payload is REFUSED before any write; the timestamp is stamped before serialising; the append is verified by re-reading the tail. exit 0 written|duplicate|skipped, 2 refused, 3 not-verified — a record failure is never blocking)
+  dz feature-adr-checkpoint (--slug <feature> | --feature-dir <abs>) --stage <s> --input-hash <h> --result <json> [--artifact a,b] [--json]   (record a pipeline stage ONLY after measuring its artifacts on disk; refuses a null result, an absent artifact, or a stage that declares none — the subagent runs a COMMAND instead of hand-writing durable state)
   dz reqe [--slug <feature> [--done --report <f>]] [--json]   (the re-QE debt ledger: a usage-switched run whose Step-8 QE ran on the coder's OWN family records a debt; list debts, print the cross-family review brief, settle FAIL-CLOSED against a graded report — the settlement lands in 08_qe_report.md)
   dz qe-bridge --family claude --slug <feature> [--coder-family codex|claude] [--model <id>] [--files a,b] [--out <f>] [--timeout <s>] [--allow-same-family] [--json]   (the REVERSE QE bridge: run an INDEPENDENT Claude reviewer over a feature's Step-8 artifacts from ANY host — a Codex session included, plain shell, no Claude agent plane needed — and land a PARSED signoff. The reviewer runs ISOLATED: an EMPTY temp cwd plus --safe-mode --strict-mcp-config --tools '' --no-session-persistence, so no CLAUDE.md/skills/plugins/hooks/MCP load, and the verdict is read from the --output-format json RESULT ENVELOPE — text a session customization printed onto the same stdout can never become a signoff. Probes the model before trusting it; sends SCOPED extracts with a loud 200k-char ceiling (never silent truncation); the grade must AGREE across three LAST-anchored channels (terminal marker line, fenced qe-bridge-signoff JSON, the report's own GRADE line) AND the marker must be the FINAL content — empty, gradeless, self-contradicting or miscounted output is one of 18 NAMED failures with an audit record under features/<slug>/.fa-state/qe-bridge/ (runId, resolved executable + binOverride, prompt sha256, channel offsets, requestedOut, reportWritten, retained raw stdout; 0600 files in a 0700 dir), never a clean review. A --coder-family that contradicts the recorded reqe debt is refused. Writes features/<slug>/08b_reqe_report.md, which dz reqe --done settles unchanged. DISCLOSURE: the extracts you scope are sent to the Claude runtime; the bridge cannot classify secrets. DZ_QE_BRIDGE_CLAUDE_BIN is a TEST SEAM, not a flag. exit 0 signoff parsed (ANY grade — it reports, it does not gate) / 1 named failure / 2 usage)
   dz mutation-gate [--package <dir>] [--registry <file>] [--test-cmd "<cmd>"] [--only <id[,id]>] [--timeout <ms>] [--rebaseline per-entry|final] [--keep-scratch] [--json]   (prove each NAMED protection has a test that DISCRIMINATES: copy the package to a scratch dir, verify the baseline suite is green, apply each registry mutation, run the suite, REQUIRE red, restore. The red must be BEHAVIOURAL: a mutation that no longer parses is MUTATION_UNPARSEABLE; a red run whose OWN output reports a test FILE failing to load (node --test file-level not-ok with exitCode, vitest Failed Suites) is MUTATION_LOAD_FATAL — the signal comes from the same run as the failing count, never from a separate isolated import; red output whose shape matches no known runner is INCONCLUSIVE (a runner-coverage gap, loud, never PROVEN); a count far above the entry's bound is OVER_FAILING; a restored tree that does not reproduce green makes the entry INCONCLUSIVE (flaky). Mutation writes are realpath-contained to the scratch copy: a symlink escape or a node_modules/ target is refused (exit 2), the real tree is never written. A mutation that does not apply, a green suite, or an inconclusive run is a FAILURE — never a skip. exit 0 all proven / 1 gate failed / 2 setup error)
@@ -4789,7 +4805,7 @@ function cmdPublish(options: Map<string, string>, flags: Set<string>, cwd: strin
   // 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', 'require-signing', 'provenance', 'no-provenance']);
-  const allowedOptions = new Set(['filter', 'claim-check', 'no-guard']);
+  const allowedOptions = new Set(['filter', 'claim-check', 'no-guard', 'sign-key']);
   const allowedHelp = '  allowed: --dry-run (default), --yes/--confirm/--no-dry-run (go live), --bump-only, --filter <substr>, --claim-check <off|warn|error>, --no-guard "<reason>" (skip the guard pre-flight; logged)';
   for (const flag of flags) {
     if (!allowedFlags.has(flag)) {
@@ -4939,7 +4955,29 @@ function cmdPublish(options: Map<string, string>, flags: Set<string>, cwd: strin
     }
   }
 
-  const report = publishPackages(cwd, { provenance, dryRun, filter, bumpOnly, claimGate: claimCheckOpt });
+  // A signed pack must be RE-SIGNED after publish's own bump and README sync (feature
+  // `sign-after-bump`): publish mutates the pack, so any earlier signature describes files that no
+  // longer exist. Default to the same path `dz sign --init` writes, so the ordinary operator needs no
+  // new flag; `--sign-key` overrides it.
+  const signKey = (options.get('sign-key') ?? join(homedir(), '.dz', 'keys', 'dz.key')).trim();
+  const report = publishPackages(cwd, {
+    provenance,
+    dryRun,
+    filter,
+    bumpOnly,
+    claimGate: claimCheckOpt,
+    signKey: signKey === '' ? undefined : resolve(cwd, signKey),
+    reSign: (packDir: string, keyPath: string): void => {
+      // The same three steps `dz sign` performs, including the SBOM — a manifest refreshed without
+      // its SBOM would leave the two describing different trees.
+      const files = packFiles(packDir);
+      if (files.length === 0) throw new Error(`refusing to sign an empty pack: ${packDir}`);
+      const manifest = buildManifest(packDir, basename(packDir), files);
+      const signed = signManifest(manifest, readFileSync(keyPath, 'utf-8'));
+      writeFileSync(join(packDir, MANIFEST_NAME), `${JSON.stringify(signed, null, 2)}\n`);
+      writeFileSync(join(packDir, SBOM_NAME), `${JSON.stringify(buildSbom(manifest), null, 2)}\n`);
+    },
+  });
 
   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`);
@@ -8937,6 +8975,290 @@ function scanOneReqeRoot(
  * `dz reqe` — the re-QE debt ledger (backlog 6b40e667): list usage-switched same-family QE debts,
  * print the cross-family review brief, settle FAIL-CLOSED against a graded report.
  */
+/**
+ * `dz feature-adr checkpoint` — record a pipeline stage, but only after WITNESSING its artifacts.
+ *
+ * Why this is a command and not a line of shell (2026-08-21). The workflow script is sandboxed with
+ * no filesystem, so it delegated checkpoint writes to a subagent by handing it a finished JSON line
+ * and saying "append this". The subagent verified nothing. A safety classifier read that shape as one
+ * party instructing another to declare a verification gate complete, and blocked NINE consecutive
+ * writes in one run — router, four design substages, plan, code, qe, and the cost-ledger row. The
+ * measured consequence: `.fa-state/checkpoints.jsonl` was never created, resume was silently dead,
+ * and the six-hour run still reported success.
+ *
+ * The classifier's premise was wrong for those particular writes — every stage had run. Its instinct
+ * was not: the old mechanism could not tell a real completion from a fabricated one, which is exactly
+ * what a cross-family reviewer had already filed against the `fleet` stage. So the subagent now runs
+ * THIS, and the verification lives in code under test instead of in the wording of a prompt.
+ *
+ * It measures `--artifact` paths on disk itself. A caller cannot assert presence; it can only name
+ * what must be there.
+ */
+/**
+ * `dz amendment-check` — the deterministic half of the Step-8 amendment gate (ADR-001).
+ *
+ * The gate used to be prompt text asking the QE agent to confirm every `AM-N` row names a real test.
+ * That is layer 4 on the cost-of-detection ladder, and `features/qe-scoped-review` shipped with five
+ * dangling ids and a plan recording `## Amendments: None`. This command owns I/O and the exit code;
+ * `harness-core/src/amendment-trace.ts` owns the grammar and the rules.
+ */
+/**
+ * `dz feature-adr-record` — the witnessed writer for the run-cost ledger and training pairs
+ * (ADR-001 … ADR-003). The subagent stops being a COURIER handed a shell pipeline and becomes a
+ * CALLER handed arguments: this command owns the paths, the refusal, the append, the READ-BACK and
+ * the exit code. A courier can neither refuse nor verify, which is how four workflow runs finished
+ * with no cost row at all.
+ */
+function cmdFeatureAdrRecord(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  const json = flags.has('json');
+  const kind = (options.get('kind') ?? '').trim() as RecordKind;
+  const stage = (options.get('stage') ?? '').trim();
+  const slug = (options.get('slug') ?? '').trim();
+  const payloadRaw = options.get('row') ?? options.get('pair') ?? '';
+
+  const emit = (d: RecordDecision, extra: Record<string, unknown> = {}): number => {
+    if (json) {
+      write(JSON.stringify({ ok: d.exit === 0, kind, stage, verdict: d.verdict, exit: d.exit, reason: d.reason, blocking: d.blocking, ...extra }));
+    } else {
+      write(recordVerdictLine(kind === 'ledger' || kind === 'training-pair' ? kind : 'ledger', stage, d));
+    }
+    return d.exit;
+  };
+
+  if (kind !== 'ledger' && kind !== 'training-pair') {
+    write('dz feature-adr-record: --kind must be ledger or training-pair');
+    return 2;
+  }
+  if (payloadRaw === '') {
+    write('dz feature-adr-record: --row (ledger) or --pair (training-pair) is required');
+    return 2;
+  }
+
+  const repo = (options.get('project') ?? cwd).trim() || cwd;
+  const target = kind === 'ledger'
+    ? join(repo, '.dz', 'feature-adr', 'run-cost-ledger.jsonl')
+    : join(repo, '.dz', 'fa-training', slug === '' ? 'unknown' : slug, `${stage.replace(/[^\w.-]/g, '_')}.jsonl`);
+  const markDir = join(repo, '.dz', 'fa-training', '.backfill-marks');
+  const markName = (options.get('mark') ?? '').trim();
+  const markPath = markName === '' ? null : join(markDir, markName.replace(/[^\w.-]/g, '_'));
+
+  const decision = decideRecordWrite({
+    kind,
+    payloadRaw,
+    stage,
+    stageProducedResult: flags.has('no-result') ? false : true,
+    markExists: markPath !== null && existsSync(markPath),
+    targetExists: existsSync(target),
+    targetHasPair: flags.has('once') && existsSync(target),
+    timestamp: new Date().toISOString(),
+  });
+  if (decision.line === null) return emit(decision);
+
+  // MEASURE, never assume: an unwritable target is a LOUD refusal, because a swallowed mkdir failure
+  // is exactly how a write becomes a silent no-op (acid case A4).
+  try {
+    mkdirSync(dirname(target), { recursive: true });
+    if (markPath !== null) {
+      mkdirSync(markDir, { recursive: true });
+      mkdirSync(markPath);
+    }
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (markPath !== null && code === 'EEXIST') {
+      // A stale mark (target absent) was already decided as writable above; re-taking it is a no-op,
+      // not a duplicate. Only a mark WITH its target means another run got here first.
+      if (decision.staleMark !== true) {
+        return emit({ verdict: 'duplicate', exit: 0, reason: 'a mark for this record already exists — another run captured it first', blocking: false, line: null });
+      }
+    }
+    return emit({ verdict: 'refused', exit: 2, reason: `the target could not be prepared: ${(err as Error).message}`, blocking: false, line: null });
+  }
+
+  try {
+    appendFileSync(target, `${decision.line}\n`, 'utf-8');
+  } catch (err) {
+    return emit({ verdict: 'refused', exit: 2, reason: `the append failed: ${(err as Error).message}`, blocking: false, line: null });
+  }
+
+  // ADR-002: the write is verified against the disk, never inferred from the absence of an error.
+  let lastLine: string | null = null;
+  try {
+    const body = readFileSync(target, 'utf-8');
+    const lines = body.split('\n').filter((l) => l !== '');
+    lastLine = lines.length > 0 ? (lines[lines.length - 1] as string) : null;
+  } catch {
+    lastLine = null;
+  }
+  return emit(decideReadBack(decision.line, lastLine), { target });
+}
+
+function cmdAmendmentCheck(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  const json = flags.has('json');
+  const readOr = (abs: string): string | null => {
+    try {
+      return readFileSync(abs, 'utf-8');
+    } catch {
+      return null;
+    }
+  };
+
+  const checkOne = (featureDir: string): { decision: ReturnType<typeof decideAmendmentOutcome>; resolutions: ReturnType<typeof resolveAmendments>; slug: string } => {
+    const slug = basename(featureDir);
+    const ideation = readOr(join(featureDir, '03.5_ideation_report.md'));
+    const plan = readOr(join(featureDir, '06_implementation_plan.md'));
+    if (ideation === null) {
+      return {
+        slug,
+        resolutions: [],
+        decision: decideAmendmentOutcome({ sectionPresent: false, rows: [], resolutions: [], planSaysNone: false }),
+      };
+    }
+    const sectionPresent = amendmentSection(ideation) !== null;
+    const ideationRows = parseAmendments(ideation);
+    const planRows = plan === null ? [] : parseAmendments(plan);
+    // The PLAN is authoritative when it carries rows: Step 6 owes "carry AM-N into the plan
+    // verbatim", and the ideation report is the historical record — rewriting its rows to match
+    // tests named later would close the trail by falsifying it. Coverage keeps that honest below.
+    const rows = planRows.length > 0 ? planRows : ideationRows;
+    const missingFromPlan = planRows.length > 0 ? amendmentsMissingFromPlan(ideationRows, planRows) : [];
+    // Paths in an amendment row are repo-relative, so they resolve against the repo root — not
+    // against the feature directory, and not against wherever the caller happened to stand.
+    const resolutions = resolveAmendments(rows, { readFile: (rel) => readOr(resolve(cwd, rel)) });
+    const decision = decideAmendmentOutcome({
+      sectionPresent,
+      rows,
+      resolutions,
+      planSaysNone: plan !== null && planSaysNoAmendments(plan),
+      missingFromPlan,
+    });
+    return { slug, decision, resolutions };
+  };
+
+  // --all is a CENSUS, not a gate (ADR-003): a gate that is red on arrival over 21 historical
+  // features gets disabled, and then the mechanism is gone along with the debt it was to surface.
+  if (flags.has('all')) {
+    const featuresDir = join(cwd, 'features');
+    let slugs: string[] = [];
+    try {
+      slugs = readdirSync(featuresDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+    } catch {
+      if (json) write(JSON.stringify({ ok: true, mode: 'all', features: [], note: 'no features/ directory' }));
+      else write('amendment traceability census: no features/ directory');
+      return 0;
+    }
+    const rowsOut: Record<string, unknown>[] = [];
+    for (const slug of slugs) {
+      try {
+        const r = checkOne(join(featuresDir, slug));
+        rowsOut.push({ slug, outcome: r.decision.outcome, counts: r.decision.counts, reasons: r.decision.reasons.length });
+      } catch (err) {
+        // AM-6: one unreadable feature becomes its own row. Dropping it silently would make the
+        // census read like coverage it does not have.
+        rowsOut.push({ slug, outcome: 'read-error', error: (err as Error).message });
+      }
+    }
+    if (json) {
+      write(JSON.stringify({ ok: true, mode: 'all', note: AMENDMENT_VACUITY_NOTE, features: rowsOut }));
+    } else {
+      const tally = new Map<string, number>();
+      for (const r of rowsOut) tally.set(String(r['outcome']), (tally.get(String(r['outcome'])) ?? 0) + 1);
+      for (const r of rowsOut) {
+        if (r['outcome'] !== 'pass' && r['outcome'] !== 'skip') write(`  [${String(r['outcome'])}] ${String(r['slug'])}`);
+      }
+      write(`amendment traceability census over ${rowsOut.length} feature(s): ${[...tally].map(([k, v]) => `${v} ${k}`).join(', ')}`);
+      write(AMENDMENT_VACUITY_NOTE);
+    }
+    return 0;
+  }
+
+  const explicitDir = (options.get('feature-dir') ?? '').trim();
+  const slug = (options.get('slug') ?? '').trim();
+  if (explicitDir === '' && slug === '') {
+    write('dz amendment-check: one of --slug / --feature-dir is required (or --all for a census)');
+    return 2;
+  }
+  const featureDir = explicitDir !== '' ? resolve(cwd, explicitDir) : join(cwd, 'features', slug);
+  const { decision, resolutions } = checkOne(featureDir);
+  if (json) {
+    write(JSON.stringify({
+      ok: decision.outcome === 'pass' || decision.outcome === 'skip',
+      slug: basename(featureDir),
+      outcome: decision.outcome,
+      exit: decision.exit,
+      counts: decision.counts,
+      reasons: decision.reasons,
+      rows: resolutions,
+      note: AMENDMENT_VACUITY_NOTE,
+    }));
+  } else {
+    for (const r of resolutions) {
+      if (r.verdict !== 'resolved') write(`  [${r.verdict}] ${r.id}${r.testId === null ? '' : ` \`${r.testId}\``} — ${r.detail}`);
+    }
+    write(AMENDMENT_VACUITY_NOTE);
+    // The verdict is the LAST line, in the K2 gate's own shape, so a caller that reads the tail of
+    // the output reads a verdict rather than a finding.
+    write(amendmentVerdictLine(decision));
+  }
+  return decision.exit;
+}
+
+function cmdFeatureAdrCheckpoint(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  const json = flags.has('json');
+  const emit = (payload: Record<string, unknown>, human: string, code: number): number => {
+    if (json) write(JSON.stringify(payload));
+    else write(human);
+    return code;
+  };
+  const slug = (options.get('slug') ?? '').trim();
+  const stage = (options.get('stage') ?? '').trim();
+  const inputHash = (options.get('input-hash') ?? '').trim();
+  const resultRaw = options.get('result') ?? '';
+  const artifacts = (options.get('artifact') ?? '')
+    .split(',')
+    .map((a) => a.trim())
+    .filter((a) => a !== '');
+  if ((slug === '' && (options.get('feature-dir') ?? '').trim() === '') || stage === '' || inputHash === '') {
+    return emit({ ok: false, reason: 'usage' }, 'dz feature-adr checkpoint: --stage, --input-hash and one of --slug / --feature-dir are required', 2);
+  }
+  let result: unknown;
+  try {
+    result = JSON.parse(resultRaw);
+  } catch {
+    return emit({ ok: false, reason: 'result is not valid JSON' }, 'dz feature-adr checkpoint: --result must be valid JSON', 2);
+  }
+  // --feature-dir wins when given: the workflow knows the absolute path already, and depending on
+  // cwd resolution there would make the command's behaviour depend on where the subagent happened to
+  // stand. --slug stays for humans running this by hand from a repo root.
+  const explicitDir = (options.get('feature-dir') ?? '').trim();
+  const featureDir = explicitDir !== '' ? explicitDir : join(cwd, 'features', slug);
+  // MEASURE, never trust: presence is established here, by this process, on this disk.
+  const present = artifacts.filter((rel) => {
+    const abs = join(featureDir, rel);
+    try {
+      return statSync(abs).isFile();
+    } catch {
+      return false;
+    }
+  });
+  const verdict = decideCheckpointWrite({ stage, inputHash, result, artifacts, present });
+  if (!verdict.ok) {
+    return emit({ ok: false, stage, reason: verdict.reason }, 'dz feature-adr checkpoint: REFUSED — ' + verdict.reason, 1);
+  }
+  const stateDir = join(featureDir, '.fa-state');
+  try {
+    mkdirSync(stateDir, { recursive: true });
+    appendFileSync(join(stateDir, 'checkpoints.jsonl'), verdict.line + '\n', 'utf-8');
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return emit({ ok: false, stage, reason }, 'dz feature-adr checkpoint: write failed — ' + reason, 1);
+  }
+  return emit(
+    { ok: true, stage, witnessed: verdict.witnessed },
+    'dz feature-adr checkpoint: recorded ' + stage + ' (witnessed ' + verdict.witnessed.length + ' artifact(s))',
+    0,
+  );
+}
+
 function cmdReqe(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
   const json = flags.has('json');
   if (flags.has('help')) {
@@ -11697,6 +12019,12 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         return cmdEpochReplay(options, flags, cwd, write);
       case 'score':
         return cmdScore(options, flags, cwd, write);
+      case 'feature-adr-record':
+        return cmdFeatureAdrRecord(options, flags, cwd, write);
+      case 'amendment-check':
+        return cmdAmendmentCheck(options, flags, cwd, write);
+      case 'feature-adr-checkpoint':
+        return cmdFeatureAdrCheckpoint(options, flags, cwd, write);
       case 'reqe':
         return cmdReqe(options, flags, cwd, write);
       case 'qe-bridge':

package/src/core-compat.ts

@@ -44,7 +44,7 @@ import { fileURLToPath } from 'node:url';
  * standing test (`test/core-import-floor.test.ts`, F1) fails if the two drift apart,
  * because a guard that says 0.4.7 while npm may install 0.4.2 is worse than no guard.
  */
-export const MIN_CORE = '0.5.4';
+export const MIN_CORE = '0.6.1';
 
 /** The npm name of the guarded package — one literal, used by every leg below. */
 export const CORE_PACKAGE_NAME = '@dzhechkov/harness-core';