@dzhechkov/harness-core 0.3.106 → 0.3.108

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.106",
+  "version": "0.3.108",
   "description": "Shared harness logic - skill loading, additive apply, and the init/sync/verify/doctor operations.",
   "type": "module",
   "license": "MIT",
@@ -30,12 +30,12 @@
     "@dzhechkov/adapter-openclaude": "^0.1.0",
     "@dzhechkov/adapter-opencode": "^0.2.0",
     "yaml": "^2.0.0",
+    "@dzhechkov/adapter-copilot": "0.1.1",
     "@dzhechkov/adapter-agents-md": "0.1.1",
     "@dzhechkov/adapter-cursor": "0.1.1",
-    "@dzhechkov/adapter-copilot": "0.1.1",
+    "@dzhechkov/adapter-windsurf": "0.1.1",
     "@dzhechkov/adapter-gemini": "0.1.1",
     "@dzhechkov/core": "0.2.14",
-    "@dzhechkov/adapter-windsurf": "0.1.1",
     "@dzhechkov/memory": "0.2.9"
   },
   "peerDependenciesMeta": {

package/src/claim-check-hook-policy.ts

@@ -76,27 +76,15 @@ function formatFinding(f: ClaimFinding): string {
 }
 
 /**
- * Is the 1-based `line` inside a fenced ``` ``` ``` code block within `text`?
- * Counts fence toggles strictly BEFORE the line; an odd count ⇒ the line sits inside a fence.
- * Never throws — a non-string / out-of-range line returns `false` (treated as not-fenced).
+ * Is the 1-based `line` inside a fenced code block within `text`?
+ *
+ * MOVED to `claim-check.ts` and re-exported here. The engine skips fenced lines and this hook exempts
+ * them from its deny path — if the two ever computed "inside a fence" differently, the hook would deny
+ * a line the engine had already dismissed, or vice versa. Two implementations WILL drift; one cannot.
+ * The engine owns it because the engine is the pure module with no dependents.
  */
-export function isFenced(text: string, line: number): boolean {
-  if (typeof text !== 'string' || typeof line !== 'number' || !isFinite(line) || line < 1) return false;
-  const lines = text.split(/\r?\n/);
-  const upTo = Math.min(line - 1, lines.length);
-  // CommonMark allows BOTH ``` and ~~~ fences, and a fence is closed only by its OWN marker — a
-  // ``` inside a ~~~ block is literal content, not a toggle. A naive toggle counter that accepts
-  // either marker therefore mis-tracks nesting; track the open marker instead.
-  let open: '`' | '~' | null = null;
-  for (let i = 0; i < upTo; i++) {
-    const m = /^\s*(`{3,}|~{3,})/.exec(lines[i] || '');
-    if (!m) continue;
-    const marker = m[1]![0] as '`' | '~';
-    if (open === null) open = marker;
-    else if (open === marker) open = null;
-  }
-  return open !== null;
-}
+import { isFenced } from './claim-check.js';
+export { isFenced };
 
 /**
  * Is `excerpt` a NEW claim line (guard d)? True when there is no pre-image (`oldString` absent/empty —

package/src/claim-check.ts

@@ -34,7 +34,9 @@ export interface ClaimCheckResult {
 /** Phrases that signal a quantitative accuracy claim (safe as substrings). */
 const METRIC_TERMS = [
   // Generic accuracy vocabulary kept from ruview.
-  'accuracy', 'precision', 'recall',
+  // `recall` is NOT here — it is this repo's command name. It re-enters via RECALL_METRIC_RE, which
+  // demands a scoring context. `precision` stays: it has no command collision.
+  'accuracy', 'precision',
   'error rate', 'detection rate', 'true positive',
   // dz claim vocabulary — a harness monorepo claims coverage, test counts, catalogue sizes,
   // and performance numbers, not WiFi-sensing PCK/MPJPE.
@@ -42,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
@@ -88,19 +90,116 @@ function scrubLine(lower: string): string {
 
 function mentionsMetricTerm(lower: string, scrubbed: string): boolean {
   if (METRIC_TERMS.some((t) => lower.includes(t))) return true;
+  // `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));
 }
 
+/**
+ * The PARAGRAPH containing 1-based `line`: the maximal run of contiguous non-blank lines, bounded by
+ * a blank line, a heading, or a fence marker. The claim is DETECTED per line; its honesty tag and its
+ * reproducer may live anywhere in this run — prose wrapped at 100 columns routinely splits a number
+ * from its `MEASURED`, and flagging the author who tagged correctly is how a gate teaches its users to
+ * ignore it.
+ *
+ * LAUNDERING EXPOSURE, stated: one tag covers every claim in its paragraph. It cannot cross a blank
+ * line, a heading, or a fence.
+ */
+function paragraphAround(lines: readonly string[], i: number): string {
+  const bounds = (k: string): boolean => k.trim() === '' || HEADING_RE.test(k) || FENCE_RE.test(k);
+  let a = i;
+  let b = i;
+  while (a > 0 && !bounds(lines[a - 1] ?? '')) a--;
+  while (b < lines.length - 1 && !bounds(lines[b + 1] ?? '')) b++;
+  return lines.slice(a, b + 1).join('\n');
+}
+
 /** Tags that make a claim honest (case-insensitive). */
 // `estimated` agrees with the `estimated: true` honest-uncertainty marker `dz usage` already
 // emits — the two honesty systems must not contradict each other.
 const HONEST_TAGS = ['measured', 'claimed', 'synthetic', 'unvalidated', 'baseline', 'estimated'];
 
+/**
+ * Is the 1-based `line` inside a fenced code block within `text`?
+ *
+ * OWNED HERE, re-exported by `claim-check-hook-policy.ts`. The engine skips fenced lines; the hook
+ * exempts them from its deny path. Two implementations of "inside a fence" would drift; one cannot.
+ *
+ * CommonMark allows BOTH ``` and ~~~ fences, and a fence closes only on its OWN marker — a ``` inside
+ * a ~~~ block is literal content, not a toggle. A naive toggle counter that accepts either marker
+ * mis-tracks nesting, so track the open marker instead. Never throws.
+ */
+export function isFenced(text: string, line: number): boolean {
+  if (typeof text !== 'string' || typeof line !== 'number' || !isFinite(line) || line < 1) return false;
+  const lines = text.split(/\r?\n/);
+  const upTo = Math.min(line - 1, lines.length);
+  let open: '`' | '~' | null = null;
+  for (let i = 0; i < upTo; i++) {
+    const m = FENCE_RE.exec(lines[i] || '');
+    if (!m) continue;
+    const marker = m[1]![0] as '`' | '~';
+    if (open === null) open = marker;
+    else if (open === marker) open = null;
+  }
+  return open !== null;
+}
+
+const FENCE_RE = /^\s*(`{3,}|~{3,})/;
+const HEADING_RE = /^\s{0,3}#{1,6}\s/;
+
+/**
+ * `recall` is ruview's completeness metric AND this repo's command name (`dz recall`). Matching it as
+ * a bare term produced 31 false positives (MEASURED — reproducer `dz claim-check --json`), every one
+ * of them prose about the command. It counts as a metric only in a scoring context: paired with
+ * `precision`, or immediately followed by a score (`recall@5`, `recall rate`, `recall of 0.9`,
+ * `recall = 0.9`, `recall score`).
+ */
+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
+ * evidence. The allowlist boundary is exactly that: an unknown binary is a claim ABOUT evidence.
+ */
+const SHELL_REPRO_RE =
+  /`\s*\$?\s*(?:ps|stat|lsof|time|git|npm|npx|node|pnpm|yarn|dz|curl|wc|grep|find|cargo|make|docker|kubectl|awk|sed|du|df|vitest|pytest)\b[^`]*`/i;
+
 /** Reproducer references that count as evidence backing a MEASURED claim. */
 const REPRODUCER_HINTS = [
   // Generic evidence hints kept from ruview.
-  'baseline', 'reproduce', 'sha256', 'tarball', 'cargo test',
+  // 'reproduce' was inherited from ruview and is SELF-CERTIFYING: it makes the bare word "reproducer"
+  // count as its own evidence, so `(MEASURED — reproducer)` passed. Removed (D5). Evidence must be a
+  // named command or artifact — see SHELL_REPRO_RE for the structural form.
+  'baseline', 'sha256', 'tarball', 'cargo test',
   // Packaging-claim reproducers (npm reviews): the tarball itself.
   'npm pack', 'npm view', 'npm i ', 'npm install',
   // dz reproducers — the actual commands/artifacts that back a dz claim.
@@ -130,14 +229,25 @@ export function claimCheck(text: string): ClaimCheckResult {
   lines.forEach((raw, i) => {
     const original = raw.trim();
     if (!original) return;
+    // A fenced block is CODE, not prose. The hook already exempts fenced lines from its deny path
+    // (it re-exports `isFenced` from here); the engine flagging them was not a policy, it was a bug —
+    // 127 of this repo's 488 findings lived inside fences, and NONE of them was `high`
+    // (MEASURED — reproducer `dz claim-check --json`).
+    // EXPOSURE, accepted: a claim written inside a fence is now unreachable. That is exactly the right
+    // the inline backtick escape already grants; a fence is its block-level form.
+    if (isFenced(text, i + 1)) return;
     // Analyse the URL-stripped line, but report the ORIGINAL so the excerpt stays recognisable.
     const line = stripUrls(original);
     if (!line.trim()) return;
     const lower = line.toLowerCase();
 
-    const hasPercent = PERCENT_RE.test(line);
-    PERCENT_RE.lastIndex = 0; // reset stateful global regex
     const scrubbed = scrubLine(lower);
+    // The percent TRIGGER reads the code-span-scrubbed line. Before this, `hasPercent` was computed on
+    // the UN-scrubbed line while metric terms were matched on the scrubbed one, so a backticked `99%`
+    // still opened the scan: the backtick escape downgraded a quoted claim from `high` to `medium`
+    // instead of silencing it. Documentation that quotes a forbidden claim was punished for doing so.
+    const hasPercent = PERCENT_RE.test(scrubbed);
+    PERCENT_RE.lastIndex = 0; // reset stateful global regex
     // DELIBERATE DIVERGENCE from ruview, which matched METRIC_TERMS against the UNSCRUBBED line.
     // dz's vocabulary contains path-like words ('packages', 'commands', 'skills'), so a code span
     // such as `packages/x/usage.test.ts:42` registered as a metric mention and produced a false
@@ -147,8 +257,13 @@ export function claimCheck(text: string): ClaimCheckResult {
     const mentionsMetric = mentionsMetricTerm(scrubbed, scrubbed);
     if (!hasPercent && !mentionsMetric) return;
 
-    const tagged = HONEST_TAGS.some((t) => lower.includes(t));
-    const hasReproducer = REPRODUCER_HINTS.some((h) => lower.includes(h));
+    // The claim is detected on its own line; its honesty tag and reproducer may live anywhere in the
+    // same paragraph. Wrapped prose routinely puts `MEASURED` on the next line.
+    const para = stripUrls(paragraphAround(lines, i));
+    const paraLower = para.toLowerCase();
+    const tagged = HONEST_TAGS.some((t) => paraLower.includes(t));
+    const hasReproducer =
+      REPRODUCER_HINTS.some((h) => paraLower.includes(h)) || SHELL_REPRO_RE.test(para);
     const perfect = PERFECT_WORD_RE.test(line) || (mentionsMetric && PERFECT_PCT_RE.test(line));
 
     if (perfect && !lower.includes('retract')) {
@@ -209,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;
+}

package/src/feature-adr-routing.ts

@@ -626,3 +626,274 @@ export function mergeOpts<B extends object, E extends object>(base: B, extra: E)
   for (const k in extra) out[k] = (extra as Record<string, unknown>)[k];
   return out as B & E;
 }
+
+// ── CODEX DISPATCH BY DELIVERABLE (ADR-001) ──────────────────────────────────
+//
+// `codex:codex-rescue` is a fire-and-forget Claude WRAPPER: it dispatches to Codex and returns
+// immediately, so its return value is a stub. That is correct for a stage whose deliverable is a
+// FILE written out-of-band (Step 7 code, behind the Step-7.5 landed barrier) and catastrophic for a
+// stage whose deliverable is its RETURN VALUE — a stub reads exactly like a clean review.
+//
+// The workflow script is sandboxed (no `child_process`), so it cannot shell out to `codex exec`
+// itself. An ordinary Claude agent runs the command and returns Codex's stdout verbatim: the agent
+// is the shell.
+
+/**
+ * Stages whose deliverable is a FILE written out-of-band, and which already verify the write landed
+ * before trusting the stub. `code` polls `git status` (Step-7.5). `plan` requires its
+ * `06_implementation_plan.md` to appear and otherwise falls back to the Claude planner — it never
+ * fabricates. Both are legitimate wrapper users; everything else returns its deliverable.
+ */
+const WRAPPER_STAGES: Record<string, number> = { code: 1, plan: 1 };
+
+export type CodexDispatch = 'wrapper' | 'exec';
+
+/** Dispatch by what the stage's deliverable IS, never by which knob named it. */
+export function codexDispatchMode(stage: string): CodexDispatch {
+  return WRAPPER_STAGES[stage] ? 'wrapper' : 'exec';
+}
+
+/**
+ * A SANITY bound on prompt size, not a stall guard.
+ *
+ * The earlier 1200-char ceiling was justified by "codex exec stalls on a 55-line payload". Twin
+ * experiments refuted that (2026-07-10): 4000 chars of padding answered in 4s, and a 3156-char /
+ * 56-line adversarial code review answered in 14s. The stalls are INTERMITTENT latency — the same
+ * input hung at 60s and answered at 14s minutes apart. Size is not the variable.
+ *
+ * So the real guard is the bounded timeout plus the CODEX_UNAVAILABLE sentinel: a slow exec becomes
+ * an explicit "unavailable", never a passed review. This constant only stops us from shipping an
+ * absurdly large prompt.
+ */
+export const CODEX_EXEC_PROMPT_CEILING_CHARS = 24_000;
+
+/** The sentinel an exec agent returns when the command failed, timed out, or Codex refused. */
+export const CODEX_UNAVAILABLE = 'CODEX_UNAVAILABLE';
+
+export interface CodexExecPlanInput {
+  readonly stage: string;
+  readonly promptChars: number;
+  readonly probedId: string | null;
+}
+
+export interface CodexExecPlanResult {
+  readonly mode: 'exec' | 'wrapper' | 'claude';
+  readonly reason: string;
+}
+
+/** Decide, before spending an agent, whether Codex can honestly serve this stage. */
+export function codexExecPlan(input: CodexExecPlanInput): CodexExecPlanResult {
+  if (codexDispatchMode(input.stage) === 'wrapper') {
+    return { mode: 'wrapper', reason: 'deliverable is a file written out-of-band' };
+  }
+  if (!input.probedId) {
+    return { mode: 'claude', reason: 'no codex model id answered the probe' };
+  }
+  if (input.promptChars > CODEX_EXEC_PROMPT_CEILING_CHARS) {
+    return {
+      mode: 'claude',
+      reason:
+        'prompt is ' +
+        input.promptChars +
+        ' chars, over the ' +
+        CODEX_EXEC_PROMPT_CEILING_CHARS +
+        '-char codex exec ceiling (it would stall)',
+    };
+  }
+  return { mode: 'exec', reason: 'codex exec on ' + input.probedId };
+}
+
+/** A model id is user input (`args.codexModel`) and lands in a shell command. Shell-safe ids only. */
+export function isSafeCodexId(id: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(id);
+}
+
+/**
+ * A liveness probe. The allowlist says a name is spellable; only this says it answers.
+ *
+ * Found by cross-model review (codex exec, 2026-07-10): the id was interpolated into a shell command
+ * unquoted, so a malformed `args.codexModel` could corrupt or extend the command the agent runs.
+ * Reject anything that is not a plain id, and single-quote it anyway.
+ */
+export function codexProbeCommand(id: string): string | null {
+  if (!isSafeCodexId(id)) return null;
+  return "timeout 60 codex exec -m '" + id + "' 'Reply with exactly: OK'";
+}
+
+export interface CodexProbeOutput {
+  readonly stdout: string;
+  readonly exitCode: number;
+}
+
+export function interpretCodexProbe(out: CodexProbeOutput): boolean {
+  if (out.exitCode !== 0) return false;
+  return /\bOK\b/.test(out.stdout);
+}
+
+/** First id that actually answers. `null` means: route this stage to Claude. */
+export async function pickAvailableCodexId(
+  ids: readonly string[],
+  probe: (id: string) => Promise<boolean>,
+): Promise<string | null> {
+  for (const id of ids) {
+    if (await probe(id)) return id;
+  }
+  return null;
+}
+
+export interface CodexExecResult {
+  readonly ok: boolean;
+  readonly text: string;
+  readonly reason: string;
+}
+
+/**
+ * Risk R2, the most dangerous line in this change: an EMPTY reply must never read as "no findings".
+ * A genuine clean review has to say something. Empty, whitespace, or the sentinel ⇒ not ok ⇒ the
+ * caller falls back to a Claude reviewer.
+ */
+/**
+ * Extract an A–D grade. Cross-model review flagged that "Looks good" would otherwise pass as a
+ * review; a verdict must NAME its grade. No grade ⇒ no verdict ⇒ the caller falls back to Claude.
+ */
+export function parseCodexGrade(text: string): string | null {
+  const m = /\bgrade\s*[:=]?\s*([A-D])\b/i.exec(text);
+  const g = m && m[1] ? m[1] : null;
+  return g ? g.toUpperCase() : null;
+}
+
+export function parseCodexExecResult(text: string | null | undefined): CodexExecResult {
+  const t = typeof text === 'string' ? text.trim() : '';
+  if (t.length === 0) return { ok: false, text: '', reason: 'codex exec returned no text' };
+  if (t.indexOf(CODEX_UNAVAILABLE) !== -1) {
+    return { ok: false, text: t, reason: 'codex exec reported it could not run' };
+  }
+  return { ok: true, text: t, reason: 'codex answered' };
+}
+
+/** CX-3: a workflow that names an agent type the harness does not have must fall back, not die. */
+export function isAgentTypeMissingError(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err ?? '');
+  return /agent type .*not found|unknown agent type|no such agent/i.test(msg);
+}
+
+/**
+ * Run a Codex-routed agent so that a missing agent type demotes to `null` (→ the caller's Claude
+ * fallback) instead of throwing and killing the whole run. Any other error still propagates: we do
+ * not want to swallow real bugs behind a fallback.
+ */
+export async function safeCodexAgent<T>(
+  agentFn: (prompt: string, opts: object) => Promise<T>,
+  prompt: string,
+  opts: object,
+  log: (msg: string) => void,
+): Promise<T | null> {
+  try {
+    return await agentFn(prompt, opts);
+  } catch (err) {
+    if (isAgentTypeMissingError(err)) {
+      log('codex: agent type unavailable — falling back to Claude (' + String(err) + ')');
+      return null;
+    }
+    throw err;
+  }
+}
+
+// ── ABSOLUTE ARTIFACT ROOT (ADR-001, absolute-artifact-paths) ────────────────
+//
+// `FDIR` (and `BRAIN`, which derives from the same value) used to be relative, because
+// `args.repo` defaults to `'.'`. A relative path means different things to different agents: once a
+// coder `cd`s elsewhere, a later agent resolves `./features/<slug>/03_adr` against another cwd, finds
+// nothing, and reports a confident FALSE BLOCKER while the artifacts sit at the workflow root.
+//
+// The workflow script is sandboxed — no filesystem, no Node API — so it cannot call `process.cwd()`.
+// The absolute root arrives either as an absolute `args.repo`, or from an agent that runs `pwd`.
+// The resolver below takes `cwd` as a PARAMETER so it is testable without ambient state.
+
+/** True for a POSIX absolute path. */
+export function isAbsolutePosix(p: string): boolean {
+  return typeof p === 'string' && p.charAt(0) === '/';
+}
+
+/**
+ * Collapse `a//b`, `a/./b` and a trailing slash. Deliberately does NOT resolve `..` — a workflow root
+ * containing `..` is a caller error we would rather surface than silently normalise away.
+ */
+export function normalizeRepoPath(p: string): string {
+  const collapsed = p.replace(/\/{2,}/g, '/').replace(/\/\.(?=\/|$)/g, '');
+  const trimmed = collapsed.replace(/\/+$/, '');
+  return trimmed === '' ? '/' : trimmed;
+}
+
+/**
+ * Resolve the artifact root to an absolute path.
+ *
+ * `raw` is `args.repo` (may be `'.'`, `'./x'`, `'x/'`, or already absolute).
+ * `cwd` is the absolute working directory, obtained ONCE from a `pwd` agent — never ambient.
+ * An already absolute `raw` ignores `cwd` entirely (zero agents on that path).
+ */
+export function absolutizeRepo(raw: string, cwd: string): string {
+  const r = typeof raw === 'string' && raw.length > 0 ? raw : '.';
+  if (isAbsolutePosix(r)) return normalizeRepoPath(r);
+  const base = normalizeRepoPath(cwd);
+  const rel = r.replace(/^\.\/+/, '').replace(/^\.$/, '');
+  return rel === '' ? base : normalizeRepoPath(base + '/' + rel);
+}
+
+/** The instruction appended to prompts that embed an artifact path (FR-3). */
+export const ABSOLUTE_PATH_NOTE =
+  ' All artifact paths in this prompt are ABSOLUTE. Read and write them exactly as given; do not cd' +
+  ' first and do not re-relativize them.';
+
+/**
+ * Pick the absolute path out of possibly chatty `pwd` output.
+ *
+ * Cross-model review (codex exec, 2026-07-10) found `.split('\n').pop()` selects the LAST line — so a
+ * `pwd` agent that appends "Done" would degrade the run despite having printed a valid path. Take the
+ * last line that actually looks like an absolute path.
+ */
+export function pickAbsolutePathLine(text: string | null | undefined): string | null {
+  if (typeof text !== 'string') return null;
+  const abs = text
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => isAbsolutePosix(l));
+  return abs.length ? (abs[abs.length - 1] as string) : null;
+}
+
+/** `args.repo` may be anything the caller passed. A non-string must not throw on `.replace`. */
+export function coerceRepoArg(raw: unknown): string {
+  return typeof raw === 'string' && raw.length > 0 ? raw.replace(/\/+$/, '') : '.';
+}
+
+
+/**
+ * Round-2 cross-model review (codex exec, 2026-07-10) — three path-safety defects, all real:
+ *   1. `..` segments survived normalisation, so `args.repo='../evil'` produced an absolute-but-unstable
+ *      root. Under the fail-fast stance this is a refusal, not a normalisation.
+ *   2. A newline in `args.repo` could split an embedded path across lines in a prompt.
+ *   3. `SLUG` was concatenated raw: `'../../outside'` escapes the `features/` directory entirely.
+ */
+const UNSAFE_PATH_CHARS = /[\u0000-\u001f\u007f]/;
+const DOT_DOT_SEGMENT = /(^|\/)\.\.(\/|$)/;
+
+export function hasUnsafePathChars(p: string): boolean {
+  return UNSAFE_PATH_CHARS.test(String(p));
+}
+
+export function hasDotDotSegment(p: string): boolean {
+  return DOT_DOT_SEGMENT.test(String(p));
+}
+
+/** The slug names a directory under `features/`. Kebab-case, Latin, max 40 chars — the documented rule. */
+export function isSafeSlug(slug: string): boolean {
+  return typeof slug === 'string' && /^[a-z0-9][a-z0-9-]{0,39}$/.test(slug);
+}
+
+/** Returns an error message, or `null` when the root is safe to embed in a prompt. */
+export function checkArtifactRoot(root: string): string | null {
+  if (!isAbsolutePosix(root)) return 'artifact root is not absolute: ' + JSON.stringify(root);
+  if (hasUnsafePathChars(root)) return 'artifact root contains control characters';
+  if (hasDotDotSegment(root)) return 'artifact root contains a ".." segment: ' + root;
+  return null;
+}

package/src/index.ts

@@ -17,6 +17,8 @@ export type { BundleOptions, BundleResult, BundledSkill } from './bundle.js';
 export * from './targets.js';
 export * from './operations.js';
 export * from './workflows.js';
+export * from './sign.js';
+export * from './skill-schema.js';
 export { createSkill } from './create-skill.js';
 export type { CreateSkillOptions, CreateSkillResult } from './create-skill.js';
 export { checkUpstream, checkAllUpstream, discoverSourcePackages, loadSourcesManifest } from './sync-upstream.js';
@@ -119,8 +121,8 @@ export type { PluginManifest } from './plugin.js';
 export type { SetupOptions, SetupResult, SetupStep } from './setup.js';
 export type { PretrainResult, DetectedTech } from './pretrain.js';
 export type { RecommendationReport, SkillRecommendation } from './recommend.js';
-export { claimCheck, summarize } from './claim-check.js';
-export type { ClaimFinding, ClaimCheckResult } from './claim-check.js';
+export { claimCheck, summarize, decideClaimCheckText, severityCounts, isGated } from './claim-check.js';
+export type { ClaimFinding, ClaimCheckResult, ClaimTextDecision, FailOn } from './claim-check.js';
 export { hookDecision, isFenced, isNewLine, ESCAPE_TEACHING } from './claim-check-hook-policy.js';
 export type { HookDecision, HookDecisionOpts } from './claim-check-hook-policy.js';
 export { step8ClaimGate } from './feature-adr-claim-gate.js';
@@ -159,12 +161,12 @@ export type {
   RecallUsagePatternRow,
   RecallUsageReport,
 } from './recall-usage.js';
-export { discoverPackages, publishPackages, bumpPatch, compareVersions, findUnpackagedSkills, orderByDependencies, syncReadmeVersion } from './publish.js';
+export { decideProvenance, environmentCanMintProvenance, publishArgv, discoverPackages, publishPackages, bumpPatch, compareVersions, findUnpackagedSkills, orderByDependencies, syncReadmeVersion } from './publish.js';
 export { fetchAllDownloads } from './downloads.js';
 export type { PackageDownloads, DownloadsReport } from './downloads.js';
 export { discoverInstalled, checkUpgrades } from './upgrade.js';
 export type { InstalledSkill, UpgradeCheck, UpgradeReport } from './upgrade.js';
-export type { PublishResult, PublishReport } from './publish.js';
+export type { PublishResult, PublishReport, ProvenanceMode, ProvenanceDecision } from './publish.js';
 export { computeRiskScore } from './risk-scoring.js';
 export type { RiskScore, RiskThresholds } from './risk-scoring.js';
 export {