@dzhechkov/harness-core 0.3.107 → 0.3.108

package/dist/sign.js

@@ -0,0 +1,325 @@
+/**
+ * `dz sign` / `dz verify` — Ed25519 tamper-evidence for a skill pack.
+ *
+ * SCOPE, stated once so a green check mark cannot overstate itself (recalled lesson, security,
+ * 2026-07-06): *"Verifying a signature against a public key EMBEDDED in the same signed object proves
+ * nothing about issuer identity. Trust must bind issuer -> a PINNED out-of-band key. Ed25519 gives
+ * provenance/tamper-evidence, never truthfulness."*
+ *
+ * So: `verifyManifest` takes the public key as a REQUIRED PARAMETER. There is no default, no fallback,
+ * and no lookup inside the pack. A `pubkey.pem` sitting in the pack is data, not a key.
+ *
+ * Zero dependencies: `node:crypto`, `node:fs`, `node:path`.
+ */
+import { createHash, sign as cryptoSign, verify as cryptoVerify, createPrivateKey, createPublicKey } from 'node:crypto';
+import { readFileSync, existsSync, readdirSync, openSync, fstatSync, closeSync, constants as fsConstants } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+export const MANIFEST_NAME = '.dz-manifest.json';
+export const SBOM_NAME = 'sbom.json';
+export const MANIFEST_VERSION = 1;
+/** sha256 of a file's bytes, hex. Follows symlinks — used only when building a manifest we control. */
+export function hashFile(absPath) {
+    return createHash('sha256').update(readFileSync(absPath)).digest('hex');
+}
+/**
+ * Round-2 review (codex exec): `lstat` then `readFile` is a TOCTOU window — the path can be swapped
+ * for a symlink between the two calls. Open ONCE with `O_NOFOLLOW`, `fstat` the descriptor, and read
+ * from that same descriptor. The bytes hashed are the bytes the stat described.
+ *
+ * Returns `null` when the path is not a regular file, or is a symlink.
+ */
+export function hashRegularFileNoFollow(absPath) {
+    let fd;
+    try {
+        fd = openSync(absPath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+        if (!fstatSync(fd).isFile())
+            return null;
+        return createHash('sha256').update(readFileSync(fd)).digest('hex');
+    }
+    catch {
+        return null; // ELOOP on a symlink, ENOENT, EACCES — all fail closed
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+/**
+ * Cross-model security review (codex exec, 2026-07-10) — a SIGNED manifest is not a TRUSTED manifest.
+ * Its own contents are attacker-controlled until the signature checks out, and even then they must be
+ * structurally sane before they touch the filesystem.
+ *
+ *   - `join(root, '../../etc/passwd')` escaped the pack (traversal).
+ *   - a newline in a path makes the canonical `<hex>  <path>\n` encoding ambiguous.
+ *   - duplicate paths make canonical bytes depend on input order — the sort is not a total order.
+ *   - a non-string `path` threw inside `hashFile` instead of failing closed.
+ */
+const SAFE_MANIFEST_PATH = /^[A-Za-z0-9._-][A-Za-z0-9._/-]*$/;
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+export function isSafeManifestPath(p) {
+    if (typeof p !== 'string' || p.length === 0 || p.length > 4096)
+        return false;
+    if (!SAFE_MANIFEST_PATH.test(p))
+        return false; // no control chars, no backslash, no leading /
+    if (p.split('/').some((seg) => seg === '..' || seg === '.' || seg === ''))
+        return false;
+    return true;
+}
+/** Returns an error message, or `null` when the entry list is structurally sound. */
+export function checkManifestEntries(files) {
+    if (!Array.isArray(files))
+        return 'manifest has no file list';
+    if (files.length === 0)
+        return 'manifest signs nothing';
+    const seen = new Set();
+    for (const f of files) {
+        if (!f || typeof f !== 'object')
+            return 'manifest entry is not an object';
+        const { path: pth, sha256 } = f;
+        if (!isSafeManifestPath(pth))
+            return 'manifest entry has an unsafe path: ' + JSON.stringify(pth);
+        if (typeof sha256 !== 'string' || !SHA256_HEX.test(sha256))
+            return 'manifest entry has a malformed sha256 for ' + pth;
+        // Round-2 review: an exact-string `seen` set misses collisions on case-insensitive filesystems
+        // (`Readme` vs `README`). Unicode normalization (`e\u0301.txt` vs `é.txt`) cannot arise: paths are
+        // ASCII-only by `SAFE_MANIFEST_PATH`, and a non-ASCII path is refused before it reaches here. An
+        // NFC check here would be unreachable code pretending to be a guard.
+        const fold = pth.toLowerCase();
+        if (seen.has(fold))
+            return 'manifest lists ' + pth + ' twice (case/unicode fold) — canonical bytes would depend on order';
+        seen.add(fold);
+    }
+    return null;
+}
+/** Every file under `root`, POSIX-relative, excluding the manifest and the SBOM themselves. */
+export function listPackFiles(root) {
+    const out = [];
+    const walk = (dir, rel) => {
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+            if (e.name === MANIFEST_NAME || e.name === SBOM_NAME)
+                continue;
+            const abs = join(dir, e.name);
+            const r = rel ? rel + '/' + e.name : e.name;
+            if (e.isDirectory())
+                walk(abs, r);
+            else
+                out.push(r);
+        }
+    };
+    walk(root, '');
+    return out.sort();
+}
+/**
+ * The bytes that get signed (FR-7). Sorted by path, LF endings, no trailing whitespace, and no
+ * dependence on JSON key order — a signature must not depend on how a serialiser felt that day.
+ * Format is `sha256sum`-compatible: `<hex>  <path>\n`.
+ */
+export function canonicalizeManifest(files) {
+    const sorted = [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const body = sorted.map((f) => f.sha256 + '  ' + f.path + '\n').join('');
+    return Buffer.from(body, 'utf8');
+}
+/**
+ * The bytes actually signed. Cross-model review (2026-07-10) found `pack` and `version` were carried
+ * in the manifest but NOT covered by the signature: an attacker could relabel a signed pack. Nothing
+ * is signed yet, so the format can change today. It can never change once packs are in the wild.
+ */
+export function canonicalizeSigned(manifest) {
+    const header = 'dz-manifest\nversion ' + String(manifest.version) + '\npack ' + manifest.pack + '\n';
+    return Buffer.concat([Buffer.from(header, 'utf8'), canonicalizeManifest(manifest.files)]);
+}
+/** Build a manifest for `files` (paths relative to `root`, POSIX separators). */
+export function buildManifest(root, pack, files) {
+    const entries = files.map((rel) => ({
+        path: rel.split(sep).join('/'),
+        sha256: hashFile(join(root, rel)),
+    }));
+    return { version: MANIFEST_VERSION, pack, files: entries };
+}
+export function signManifest(manifest, privateKeyPem) {
+    // Defence in depth (round-2 review): `pack` is interpolated into a newline-delimited signed header.
+    // `verifyManifest` already refuses an unsafe pack name, so an ambiguous header could never verify —
+    // but refusing to CREATE one is cheaper than reasoning about why it cannot be exploited.
+    if (!isSafeManifestPath(manifest.pack))
+        throw new Error('refusing to sign an unsafe pack name: ' + JSON.stringify(manifest.pack));
+    if (!Number.isInteger(manifest.version))
+        throw new Error('refusing to sign a non-integer manifest version');
+    const structural = checkManifestEntries(manifest.files);
+    if (structural)
+        throw new Error('refusing to sign a malformed manifest: ' + structural);
+    const key = createPrivateKey(privateKeyPem);
+    const sig = cryptoSign(null, canonicalizeSigned(manifest), key);
+    return { manifest, signature: sig.toString('base64') };
+}
+/**
+ * FR-8 / risk R1: every degenerate input FAILS CLOSED. Absence must never read as success — that is the
+ * failure mode that turns a security tool into a lie.
+ *
+ * `pubKeyPem` is required. It comes from the repo, never from `root`.
+ */
+/**
+ * Round-2 review killed the `expectedFiles` option: a caller could NARROW the added-file check and
+ * silently allow an unsigned `evil.js` to sit in the pack. A safety option that a caller may disable
+ * is not a safety option. The pack is always scanned.
+ */
+export function verifyManifest(root, signed, pubKeyPem) {
+    const fail = (path, reason) => ({ ok: false, failures: [{ path, reason }] });
+    if (!signed || typeof signed !== 'object')
+        return fail(MANIFEST_NAME, 'no manifest');
+    const { manifest, signature } = signed;
+    if (!manifest || typeof manifest !== 'object')
+        return fail(MANIFEST_NAME, 'manifest is missing');
+    if (typeof manifest.version !== 'number' || !Number.isInteger(manifest.version)) {
+        return fail(MANIFEST_NAME, 'manifest version is not an integer');
+    }
+    if (!isSafeManifestPath(manifest.pack)) {
+        return fail(MANIFEST_NAME, 'manifest pack name is unsafe: ' + JSON.stringify(manifest.pack));
+    }
+    const structural = checkManifestEntries(manifest.files);
+    if (structural)
+        return fail(MANIFEST_NAME, structural);
+    if (typeof signature !== 'string' || signature.length === 0) {
+        return fail(MANIFEST_NAME, 'manifest is unsigned');
+    }
+    if (typeof pubKeyPem !== 'string' || pubKeyPem.length === 0) {
+        return fail(MANIFEST_NAME, 'no public key supplied — refusing to verify');
+    }
+    // The signature first: if the manifest itself was rewritten, its file list is not evidence.
+    let sigOk = false;
+    try {
+        sigOk = cryptoVerify(null, canonicalizeSigned(manifest), createPublicKey(pubKeyPem), Buffer.from(signature, 'base64'));
+    }
+    catch {
+        return fail(MANIFEST_NAME, 'signature is malformed');
+    }
+    if (!sigOk)
+        return fail(MANIFEST_NAME, 'signature does not verify against the pinned key');
+    const failures = [];
+    for (const entry of manifest.files) {
+        const abs = join(root, entry.path);
+        if (!existsSync(abs)) {
+            failures.push({ path: entry.path, reason: 'listed in the manifest but absent' });
+            continue;
+        }
+        // One open, O_NOFOLLOW, fstat the descriptor, hash from it: no symlink follow, no TOCTOU window.
+        const digest = hashRegularFileNoFollow(abs);
+        if (digest === null) {
+            failures.push({ path: entry.path, reason: 'is a symlink or not a regular file — refusing to hash it' });
+            continue;
+        }
+        if (digest !== entry.sha256) {
+            failures.push({ path: entry.path, reason: 'content does not match its signed hash' });
+        }
+    }
+    // Bidirectional, always: hashing only what the manifest lists lets an attacker ADD a file.
+    const present = listPackFiles(root);
+    const listed = new Set(manifest.files.map((f) => f.path));
+    for (const rel of present) {
+        const p = rel.split(sep).join('/');
+        if (!listed.has(p))
+            failures.push({ path: p, reason: 'present in the pack but not signed' });
+    }
+    return { ok: failures.length === 0, failures };
+}
+/**
+ * FR-5, the one irreversible mistake. `.gitignore` covers `*.pem` and `*.key` and nothing else — a key
+ * written as `signing-key.json` would be committed without complaint. Refuse by location, not by name.
+ */
+export function isInsideTree(keyPath, repoRoot) {
+    const key = resolve(keyPath);
+    const root = resolve(repoRoot);
+    if (key === root)
+        return true;
+    const rel = relative(root, key);
+    // `relative` yields '' for the root itself, a '..'-prefixed path for anything outside, and an
+    // absolute path when the two share no root. Anything else is inside.
+    if (rel === '')
+        return true;
+    if (rel === '..' || rel.startsWith('..' + sep))
+        return false;
+    if (isAbsolute(rel))
+        return false;
+    return true;
+}
+export function assertKeyOutsideTree(keyPath, repoRoot) {
+    if (isInsideTree(keyPath, repoRoot)) {
+        throw new Error('refusing to write a private key inside the repository working tree: ' +
+            resolve(keyPath) +
+            ' (a leaked signing key cannot be reverted — it means a new key and re-signing every pack)');
+    }
+}
+/** CycloneDX 1.5 JSON, hand-built — it is JSON against a schema, not a reason for a dependency. */
+export function buildSbom(manifest) {
+    return {
+        bomFormat: 'CycloneDX',
+        specVersion: '1.5',
+        version: 1,
+        metadata: { component: { type: 'library', name: manifest.pack } },
+        components: manifest.files.map((f) => ({
+            type: 'file',
+            name: f.path,
+            hashes: [{ alg: 'SHA-256', content: f.sha256 }],
+        })),
+    };
+}
+export function decidePublishGate(input) {
+    if (!input.trustRootPresent) {
+        if (input.requireSigning) {
+            return { action: 'block', reason: 'no trust root (keys/dz.pub) and --require-signing was passed' };
+        }
+        return {
+            action: 'publish-unsigned',
+            reason: 'no trust root committed (keys/dz.pub) — packs publish UNSIGNED and unverifiable',
+        };
+    }
+    if (!input.manifestPresent) {
+        return { action: 'block', reason: 'trust root is present but the pack carries no signature manifest' };
+    }
+    if (!input.verifyOk) {
+        return { action: 'block', reason: 'the pack does not match its signed manifest' };
+    }
+    return { action: 'publish-verified', reason: 'manifest verified against the pinned key' };
+}
+/**
+ * Precedence, explicit and pure: `--pubkey` > repo `keys/dz.pub` > the packaged key.
+ * Never derived from the pack under verification.
+ */
+export function resolveTrustRoot(c) {
+    if (c.explicit)
+        return { source: 'explicit', path: c.explicit };
+    if (c.repo)
+        return { source: 'repo', path: c.repo };
+    if (c.packaged)
+        return { source: 'packaged', path: c.packaged };
+    return null;
+}
+/**
+ * The whole feature, as a table:
+ *
+ * | verdict        | requireSigning off | on   |
+ * |----------------|--------------------|------|
+ * | verified       | ok                 | ok   |
+ * | unsigned       | report             | fail |
+ * | tampered       | FAIL               | FAIL |
+ * | no-trust-root  | report             | fail |
+ *
+ * `tampered` is fatal in both columns; `no-trust-root` is never success. That is the load-bearing
+ * property. Today every pack is `unsigned` or `no-trust-root` — the leg is wired, not armed.
+ */
+export function decideVerifyPolicy(verdict, requireSigning) {
+    if (verdict === 'tampered') {
+        return { action: 'fail', reason: 'pack does not match its signed manifest' };
+    }
+    if (verdict === 'verified') {
+        return { action: 'ok', reason: 'verified against the pinned key' };
+    }
+    if (verdict === 'no-trust-root') {
+        return requireSigning
+            ? { action: 'fail', reason: 'no trust root available and --require-signing was passed' }
+            : { action: 'report', reason: 'no trust root available — nothing could be verified' };
+    }
+    return requireSigning
+        ? { action: 'fail', reason: 'pack is unsigned and --require-signing was passed' }
+        : { action: 'report', reason: 'pack is unsigned — not verified' };
+}
+//# sourceMappingURL=sign.js.map

package/dist/sign.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign.js","sourceRoot":"","sources":["../src/sign.ts"],"names":[],"mappings":"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"}

package/dist/skill-schema.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Single-source trustTier (ADR-001, trusttier-single-source).
+ *
+ * A skill's `schemas/output.json` used to hardcode `properties.trustTier.const` — a second copy of the
+ * `trust_tier` in its `SKILL.md` frontmatter. Nothing read the schema copy; the frontmatter is the
+ * single source (`registry.ts` reads it). Two copies of a value drift by construction, and this one
+ * had. This transform removes the value, leaving only a shape constraint.
+ */
+export interface TrustTierStripResult {
+    /** The schema object, mutated in place if a const was present. */
+    readonly schema: Record<string, unknown>;
+    /** True iff a `const` was found under `properties.trustTier` and replaced. */
+    readonly changed: boolean;
+}
+/**
+ * Replace `properties.trustTier.const: N` with `{ minimum: 1, maximum: 3 }`, preserving every sibling
+ * key (`type`, `description`, …). Idempotent: a schema that already uses a range, has no `const`, or has
+ * no `trustTier`, is returned unchanged with `changed: false`.
+ *
+ * Pure w.r.t. inputs it does not own: it mutates the passed object (the caller owns it) and returns it,
+ * so it is trivially testable without a filesystem.
+ */
+export declare function stripTrustTierConst(schema: Record<string, unknown>): TrustTierStripResult;
+//# sourceMappingURL=skill-schema.d.ts.map

package/dist/skill-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-schema.d.ts","sourceRoot":"","sources":["../src/skill-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,oBAAoB;IACnC,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,oBAAoB,CA4BzF"}

package/dist/skill-schema.js

@@ -0,0 +1,42 @@
+/**
+ * Single-source trustTier (ADR-001, trusttier-single-source).
+ *
+ * A skill's `schemas/output.json` used to hardcode `properties.trustTier.const` — a second copy of the
+ * `trust_tier` in its `SKILL.md` frontmatter. Nothing read the schema copy; the frontmatter is the
+ * single source (`registry.ts` reads it). Two copies of a value drift by construction, and this one
+ * had. This transform removes the value, leaving only a shape constraint.
+ */
+/**
+ * Replace `properties.trustTier.const: N` with `{ minimum: 1, maximum: 3 }`, preserving every sibling
+ * key (`type`, `description`, …). Idempotent: a schema that already uses a range, has no `const`, or has
+ * no `trustTier`, is returned unchanged with `changed: false`.
+ *
+ * Pure w.r.t. inputs it does not own: it mutates the passed object (the caller owns it) and returns it,
+ * so it is trivially testable without a filesystem.
+ */
+export function stripTrustTierConst(schema) {
+    const props = schema.properties;
+    if (!props || typeof props !== 'object')
+        return { schema, changed: false };
+    const tt = props.trustTier;
+    // Cross-model review: `'const' in tt` also matches an INHERITED const on the prototype, and
+    // `!== undefined` cannot tell 'key absent' from 'key present, value undefined'. Use own-property
+    // checks throughout so a crafted object cannot trick the transform.
+    if (!tt || typeof tt !== 'object' || !Object.hasOwn(tt, 'const'))
+        return { schema, changed: false };
+    // Preserve type/description; drop the value; add the range. Order kept sane for a clean diff:
+    // type (if any) → minimum → maximum → description (if any) → any other siblings.
+    const { const: _dropped, type, description, ...rest } = tt;
+    const rebuilt = {};
+    rebuilt.type = Object.hasOwn(tt, 'type') ? type : 'integer';
+    rebuilt.minimum = 1;
+    rebuilt.maximum = 3;
+    if (Object.hasOwn(tt, 'description'))
+        rebuilt.description = description;
+    // `rest` already excludes const/type/description via destructuring; Object.entries is own-keys only.
+    for (const [k, v] of Object.entries(rest))
+        rebuilt[k] = v;
+    props.trustTier = rebuilt;
+    return { schema, changed: true };
+}
+//# sourceMappingURL=skill-schema.js.map

package/dist/skill-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-schema.js","sourceRoot":"","sources":["../src/skill-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAA+B;IACjE,MAAM,KAAK,GAAG,MAAM,CAAC,UAAiD,CAAC;IACvE,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAE3E,MAAM,EAAE,GAAG,KAAK,CAAC,SAAgD,CAAC;IAClE,4FAA4F;IAC5F,iGAAiG;IACjG,oEAAoE;IACpE,IAAI,CAAC,EAAE,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAEpG,8FAA8F;IAC9F,iFAAiF;IACjF,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,IAAI,EAAE,GAAG,EAI7B,CAAC;IAE5B,MAAM,OAAO,GAA4B,EAAE,CAAC;IAC5C,OAAO,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5D,OAAO,CAAC,OAAO,GAAG,CAAC,CAAC;IACpB,OAAO,CAAC,OAAO,GAAG,CAAC,CAAC;IACpB,IAAI,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,aAAa,CAAC;QAAE,OAAO,CAAC,WAAW,GAAG,WAAW,CAAC;IACxE,qGAAqG;IACrG,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAE1D,KAAK,CAAC,SAAS,GAAG,OAAO,CAAC;IAC1B,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACnC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-core",
-  "version": "0.3.107",
+  "version": "0.3.108",
   "description": "Shared harness logic - skill loading, additive apply, and the init/sync/verify/doctor operations.",
   "type": "module",
   "license": "MIT",
@@ -30,11 +30,11 @@
     "@dzhechkov/adapter-openclaude": "^0.1.0",
     "@dzhechkov/adapter-opencode": "^0.2.0",
     "yaml": "^2.0.0",
-    "@dzhechkov/adapter-agents-md": "0.1.1",
     "@dzhechkov/adapter-copilot": "0.1.1",
+    "@dzhechkov/adapter-agents-md": "0.1.1",
     "@dzhechkov/adapter-cursor": "0.1.1",
-    "@dzhechkov/adapter-gemini": "0.1.1",
     "@dzhechkov/adapter-windsurf": "0.1.1",
+    "@dzhechkov/adapter-gemini": "0.1.1",
     "@dzhechkov/core": "0.2.14",
     "@dzhechkov/memory": "0.2.9"
   },

package/src/claim-check.ts

@@ -44,19 +44,19 @@ const METRIC_TERMS = [
   'packages', 'presets', 'downloads', 'benchmark', 'speedup', 'latency',
 ];
 
-// Short/ambiguous metric tokens (ADR-263 F11): 'map' is usually the English
-// word or a file extension, 'f1'/'o1' collide with finding/option labels.
-// They only count as metric mentions when word-bounded, not a `.map` file
-// reference, and the line (after scrubbing) carries a number — "mAP 62.3" is
-// a claim, "F-numbers map to findings" is not.
-// 'map' additionally must not be a `.map` file suffix or a hyphenated
-// compound ("map-free", "map-reduce") — mAP the metric never appears as either.
+// Short/ambiguous metric tokens (ADR-263 F11): 'f1'/'o1' collide with finding/option labels.
+// They only count as metric mentions when word-bounded, and the line (after scrubbing) carries a
+// number — "auc 0.9" is a claim, "F-numbers map to findings" is not.
 // `\d+ tests` is dz's single most-repeated headline claim ("2136 tests") and was slipping through:
 // the substring term is 'tests passed', so a bare count never fired. Anchor it to a PRECEDING number
 // rather than adding a bare 'test' term — otherwise every `usage.test.ts:42` path reference would
 // register as a metric mention.
+// NOTE: 'map' is NOT here. A line-wide "has a number" gate fired on the English word `map` next to any
+// incidental digit — a `FR-2` label, a `v2`, an `item 2` (MEASURED — features/claimcheck-map-fp).
+// mAP the metric is written with its score ADJACENT, so it gets a scoring-context regex (MAP_METRIC_RE),
+// exactly as `recall` does (RECALL_METRIC_RE), instead of the loose line-wide gate.
 const METRIC_TERMS_SHORT = [
-  /(?<![.\w])map\b(?!-)/, /\bf1\b/, /\bauc\b/, /\biou\b/,
+  /\bf1\b/, /\bauc\b/, /\biou\b/,
   /\b\d[\d,._]*\s+tests?\b/,
 ];
 // Finding/option labels (F1, O2, …) count as labels unless the token sits in a
@@ -93,6 +93,9 @@ function mentionsMetricTerm(lower: string, scrubbed: string): boolean {
   // `recall` only in a scoring context (see RECALL_METRIC_RE). `precision` on the line is enough:
   // "precision 0.9 / recall 0.8" is the canonical ML pair.
   if (RECALL_METRIC_RE.test(scrubbed)) return true;
+  // mAP: a metric only with a score adjacent (see MAP_METRIC_RE). The regex embeds its own number, so
+  // it is checked before the loose line-wide HAS_NUMBER gate — the same shape as recall above.
+  if (MAP_METRIC_RE.test(scrubbed)) return true;
   if (!HAS_NUMBER_RE.test(scrubbed)) return false;
   return METRIC_TERMS_SHORT.some((re) => re.test(scrubbed));
 }
@@ -158,6 +161,30 @@ const HEADING_RE = /^\s{0,3}#{1,6}\s/;
  */
 const RECALL_METRIC_RE = /\brecall\s*(?:@\s*\d|rate\b|score\b|of\s+[\d.]|[:=]\s*[\d.])/i;
 
+/**
+ * mAP (mean Average Precision) is both a metric AND the English word `map`. Matching it via the
+ * line-wide "has a number" gate fired on every line where `map` co-occurred with an unrelated digit —
+ * a `FR-2` label, a `v2`, an `item 2` (MEASURED — reproducer matrix in features/claimcheck-map-fp).
+ * Like `recall`, it counts as a metric only in a SCORING CONTEXT: a score sits ADJACENT to the token.
+ *
+ * Fires on: `mAP 62.3`, `mAP: 0.62`, `mAP=62`, `mAP@0.5`, `62.3 mAP`, `62% mAP`.
+ * Does not fire on: `the map imports` + `FR-2`, `.map` file, `map-reduce`, `a map of 3 zones`.
+ *
+ * A real mAP score is a DECIMAL or a PERCENT (`0.62`, `62.3`, `62%`) — never a bare integer and never a
+ * lone dot. Requiring that (not merely "a digit or dot", which cross-model review showed fires on
+ * `map: 3 zones`, `map @ 5 locations`, and even `map: .env`) is what separates the metric from prose:
+ * `map 3 items`, `a map of 3 zones`, `top 5 map layers` all stay prose. An optional `@`/`:`/`=` may sit
+ * between the token and its score. `(?<![.\w])` excludes `.map`; `(?!-)` excludes `map-reduce`/`map-free`.
+ *
+ * Known, accepted limitation (cross-model review): exotic notations `mAP50 62.3`, `mAP@[.5:.95]` are NOT
+ * matched — under-detection of rare forms, not a false positive. dz's own claims use `mAP 62.3`.
+ */
+const MAP_SCORE = String.raw`(?:\d+\.\d+|\.\d+|\d+\s*%)`;
+const MAP_METRIC_RE = new RegExp(
+  String.raw`(?<![.\w])map\b(?!-)\s*(?:[@:=]\s*)?${MAP_SCORE}|${MAP_SCORE}\s+(?<![.\w])map\b(?!-)`,
+  'i',
+);
+
 /**
  * A shell reproducer is STRUCTURAL, never a word. `(MEASURED — reproducer)` is self-certifying and
  * must not pass; a backticked span whose first token is a command this repo actually measures with is
@@ -297,3 +324,60 @@ export function summarize(result: ClaimCheckResult): string {
   const high = result.findings.filter((f) => f.severity === 'high').length;
   return `claim-check: ${result.findings.length} finding(s) (${high} high) — accuracy claims need MEASURED/CLAIMED tags + a reproducer.`;
 }
+
+// ── Voluntary text-vet policy (ADR-001, mcp-claim-check-text) ────────────────
+//
+// `claimCheck('')` returns {ok:true} — correct for a file (no claims), wrong for a VOLUNTARY vet: an
+// agent that asks "are my claims OK?" with nothing and hears "yes" is reassured about nothing. This
+// pure policy decides error-vs-run BEFORE the engine is called, so a wrapper (the MCP tool) can fail
+// closed without touching `claimCheck` itself.
+
+export type FailOn = 'high' | 'medium' | 'none';
+
+export interface ClaimTextDecision {
+  readonly kind: 'error' | 'run';
+  readonly reason?: string;
+}
+
+/** Empty / whitespace-only / non-string ⇒ error. A real paragraph ⇒ run. */
+export function decideClaimCheckText(text: unknown): ClaimTextDecision {
+  if (typeof text !== 'string') {
+    return { kind: 'error', reason: 'text must be a string, got ' + typeof text };
+  }
+  // Cross-model review: trim() leaves zero-width and format characters (U+200B ZWSP, U+200D ZWJ,
+  // U+FEFF BOM, other Cf), so a string of invisibles would pass as `run` and vet nothing. Strip all
+  // whitespace AND Unicode format/control characters before the emptiness test.
+  const visible = text.replace(/[\s\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]|\p{Cf}|\p{Cc}/gu, '');
+  if (visible.length === 0) {
+    return { kind: 'error', reason: 'text is empty or only invisible characters — nothing to vet' };
+  }
+  return { kind: 'run' };
+}
+
+/** Severity counts, so a caller can gate without re-walking the findings. */
+export function severityCounts(result: ClaimCheckResult): { high: number; medium: number } {
+  let high = 0;
+  let medium = 0;
+  for (const f of result.findings) {
+    if (f.severity === 'high') high++;
+    else if (f.severity === 'medium') medium++;
+  }
+  return { high, medium };
+}
+
+/**
+ * Whether a run RESULT trips the caller's threshold. Reporting only — never throws, never converts the
+ * fail-closed empty case (which is handled earlier by `decideClaimCheckText`) into a pass.
+ *   'high'   ⇒ gated iff any high finding
+ *   'medium' ⇒ gated iff any high OR medium finding
+ *   'none'   ⇒ never gated
+ */
+export function isGated(result: ClaimCheckResult, failOn: FailOn): boolean {
+  const { high, medium } = severityCounts(result);
+  if (failOn === 'none') return false;
+  if (failOn === 'high') return high > 0;
+  if (failOn === 'medium') return high > 0 || medium > 0;
+  // Cross-model review: an unknown failOn (only reachable via a direct call, since the Zod enum guards
+  // the tool) must not silently behave like 'medium'. Fail SAFE: gate on any finding.
+  return high > 0 || medium > 0;
+}