@dzhechkov/harness-core 0.4.5 → 0.5.1

package/src/parity.ts

@@ -23,7 +23,13 @@ import type { TargetName } from './targets.js';
 export type RuntimeCapability =
   | 'shell' // can run the dz CLI, i.e. a shell WITH Node.js (what `npm i -g` implies on a dev machine)
   | 'skills' // consumes compiled skills (all adapters emit them; agents-md as one merged file)
-  | 'hooks' // pre/post tool-call hooks (auto claim-check, auto recall apply-leg)
+  // The blanket `hooks` capability is deliberately GONE (AM-21). The matrix is COMPUTED, so one
+  // word here moves several cells: granting a target `hooks` promoted BOTH `claim-check` (a
+  // GATE_FEATURE_IDS member) and `learning-apply` to `full` in one edit, and a caveat comment
+  // cannot move a computed cell back.
+  | 'hooks-write' // PreToolUse on FILE writes — what claim-check's automatic form needs
+  | 'hooks-shell' // PreToolUse on SHELL commands — what the codex veto leg ships
+  | 'hooks-prompt' // UserPromptSubmit — what the auto-recall apply leg ships
   | 'mcp' // Model Context Protocol client exists on the platform (servers still need configuring)
   | 'mcp-configured' // our MCP servers (AgentDB / agentic-qe) are wired up out of the box (.mcp.json)
   | 'workflows' // deterministic multi-agent Workflow runtime (ultracode feature-adr, delivery gate)
@@ -33,7 +39,9 @@ export type RuntimeCapability =
 export const RUNTIME_CAPABILITIES: readonly RuntimeCapability[] = [
   'shell',
   'skills',
-  'hooks',
+  'hooks-write',
+  'hooks-shell',
+  'hooks-prompt',
   'mcp',
   'mcp-configured',
   'workflows',
@@ -47,9 +55,18 @@ export const RUNTIME_CAPABILITIES: readonly RuntimeCapability[] = [
 export const TARGET_CAPABILITIES: Record<TargetName, readonly RuntimeCapability[]> = {
   // Daily-driven harness: hooks (claim-check PreToolUse, recall UserPromptSubmit), MCP servers,
   // Workflow runtime and the statusline are all exercised in this repo every session.
-  'claude-code': ['shell', 'skills', 'hooks', 'mcp', 'mcp-configured', 'workflows', 'statusline'],
+  'claude-code': ['shell', 'skills', 'hooks-write', 'hooks-shell', 'hooks-prompt', 'mcp', 'mcp-configured', 'workflows', 'statusline'],
   // MCP subsystem probed live: `codex mcp --help` + `codex mcp list` answer (2026-07-19).
-  codex: ['shell', 'skills', 'mcp'],
+  // hooks-shell + hooks-prompt: user-global `$CODEX_HOME/hooks.json`, installed and ARMED
+  // unattended, proved by a live two-sided block probe (2026-08-19, codex-cli 0.147.0 — the
+  // transcripts named in CAPABILITY_EVIDENCE). `hooks-write` is NOT granted: this leg ships no
+  // PreToolUse guard on Write/Edit, so `claim-check` stays `manual` on codex.
+  //
+  // Fact CORRECTED 2026-08-19: a project-level `<repo>/.codex/hooks.json` DOES load on 0.147.0
+  // (`source: "project"`, MEASURED). The earlier note that project-level files are ignored was
+  // measured on 0.144.6 and is stale. dz still writes only the user-global registry, but that is
+  // now a DECISION (one carrier, one removable unit) rather than a description of the runtime.
+  codex: ['shell', 'skills', 'mcp', 'hooks-shell', 'hooks-prompt'],
   // Conservative v1: skills emission verified by the adapters; richer runtimes unproven.
   opencode: ['shell', 'skills'],
   hermes: ['shell', 'skills'],
@@ -62,6 +79,242 @@ export const TARGET_CAPABILITIES: Record<TargetName, readonly RuntimeCapability[
   windsurf: ['shell', 'skills'],
 };
 
+/**
+ * WHY each capability grant is believed, as machine-readable DATA (AM-22).
+ *
+ * `parity.ts` has declared an honesty contract in prose since day one — *"a capability flag states
+ * only what has been VERIFIED, each with its source in a comment"*. A comment is documentation, not
+ * a gate. The pinned map in `parity.test.ts` catches an ACCIDENTAL capability, but updating a pin is
+ * a mechanical edit that demands no evidence, so the contract had no layer-1 half.
+ *
+ * This is that half. `parity_no_capability_grant_without_evidence` fails when a target declares a
+ * capability with no record here, when a `transcript` record points at a file that does not exist,
+ * or when **any cell computes `full` on a target whose deciding capability has no transcript**.
+ *
+ * `kind: 'transcript'` means a recorded live run is on disk at `evidence`; `kind: 'reproducer'`
+ * means `evidence` is a command anyone can re-run.
+ */
+export interface CapabilityEvidence {
+  readonly evidence: string;
+  readonly kind: 'transcript' | 'reproducer';
+  /** ISO date the evidence was produced. Stale evidence is still evidence — silence is not. */
+  readonly at: string;
+  /**
+   * The RUNTIME VERSION the evidence was measured on, verbatim from the runtime's own `--version`
+   * (e.g. `codex-cli 0.147.0`).
+   *
+   * ADR-006 pins capability grants to a runtime version, and the gate enforced only that a record
+   * existed and its file was on disk — so evidence recorded on codex 0.147 kept a grant alive on
+   * the installed 0.148 (independent review, finding 3). A hook registry is exactly the kind of
+   * surface a minor version moves. When this is set and the caller supplies a PROBED version that
+   * differs, the grant is reported `stale-runtime-version` — INCONCLUSIVE, not revoked: the fix is
+   * a fresh probe, and an absent probe flips nothing.
+   */
+  readonly runtimeVersion?: string;
+}
+
+export const CAPABILITY_EVIDENCE: Record<TargetName, Partial<Record<RuntimeCapability, CapabilityEvidence>>> = {
+  'claude-code': {
+    shell: { evidence: 'dz --version', kind: 'reproducer', at: '2026-07-19' },
+    skills: { evidence: 'dz compose --target claude-code', kind: 'reproducer', at: '2026-07-19' },
+    'hooks-write': { evidence: 'grep -n claim-check-hook .claude/settings.json', kind: 'reproducer', at: '2026-07-19' },
+    'hooks-shell': { evidence: 'grep -n PreToolUse .claude/settings.json', kind: 'reproducer', at: '2026-07-19' },
+    'hooks-prompt': { evidence: 'grep -n recall-hook.cjs .claude/settings.json', kind: 'reproducer', at: '2026-07-19' },
+    mcp: { evidence: 'cat .mcp.json', kind: 'reproducer', at: '2026-07-19' },
+    'mcp-configured': { evidence: 'cat .mcp.json', kind: 'reproducer', at: '2026-07-19' },
+    workflows: { evidence: 'ls .claude/workflows/feature-adr.js', kind: 'reproducer', at: '2026-07-19' },
+    statusline: { evidence: 'dz statusline', kind: 'reproducer', at: '2026-07-19' },
+  },
+  codex: {
+    shell: { evidence: 'codex exec -m <id> "Reply with exactly: OK"', kind: 'reproducer', at: '2026-07-19' },
+    skills: { evidence: 'dz compose --target codex', kind: 'reproducer', at: '2026-07-19' },
+    mcp: { evidence: 'codex mcp list', kind: 'reproducer', at: '2026-07-19' },
+    // The two-sided live block: our marker in the transcript AND the sentinel side effect absent,
+    // in a NON-bypassed run, with the entry reported `trusted` by codex's own `hooks/list`.
+    // RE-PROBED on the installed runtime at the independent-QE fix round (review finding 3): the
+    // 0.147.0 evidence was stale on a machine running 0.148.0, and re-running it was NOT a
+    // formality — the arming path had silently stopped working, because `hooks/list` spells its
+    // `eventName` field `preToolUse` on 0.148 while the trust KEY still says `pre_tool_use`.
+    // All four legs pass on 0.148.0 with the trust axis PARSED from `hooks/list` rather than
+    // hard-coded (the pre-fix grader asserted `trustStatus: 'trusted'` as a constant).
+    'hooks-shell': {
+      evidence: 'features/crossrt-2-codex-hooks/07_code_changes/probe-results/fixround/veto-armed.txt',
+      kind: 'transcript',
+      at: '2026-08-19',
+      runtimeVersion: 'codex-cli 0.148.0',
+    },
+    // NOT re-probed on 0.148: the recall canary is a separate live run (forced hit + removed twin)
+    // and this round did not execute it. The version it was measured on is recorded HONESTLY, so
+    // `findUnbackedCapabilities` reports it `stale-runtime-version` — INCONCLUSIVE — the moment a
+    // caller supplies the probed 0.148.0. That is the correct state: the grant is not withdrawn,
+    // it is awaiting its re-probe.
+    'hooks-prompt': {
+      evidence: 'features/crossrt-2-codex-hooks/07_code_changes/probe-results/recall-canary.md',
+      kind: 'transcript',
+      at: '2026-08-19',
+      runtimeVersion: 'codex-cli 0.147.0',
+    },
+  },
+  opencode: { shell: { evidence: 'adapter emit', kind: 'reproducer', at: '2026-07-19' }, skills: { evidence: 'dz compose --target opencode', kind: 'reproducer', at: '2026-07-19' } },
+  hermes: { shell: { evidence: 'adapter emit', kind: 'reproducer', at: '2026-07-19' }, skills: { evidence: 'dz compose --target hermes', kind: 'reproducer', at: '2026-07-19' } },
+  openclaude: { shell: { evidence: 'adapter emit', kind: 'reproducer', at: '2026-07-19' }, skills: { evidence: 'dz compose --target openclaude', kind: 'reproducer', at: '2026-07-19' } },
+  copilot: { shell: { evidence: 'adapter emit', kind: 'reproducer', at: '2026-07-19' }, skills: { evidence: 'dz compose --target copilot', kind: 'reproducer', at: '2026-07-19' } },
+  'agents-md': { shell: { evidence: 'adapter emit', kind: 'reproducer', at: '2026-07-19' }, skills: { evidence: 'dz compose --target agents-md', kind: 'reproducer', at: '2026-07-19' } },
+  cursor: { shell: { evidence: 'adapter emit', kind: 'reproducer', at: '2026-07-19' }, skills: { evidence: 'dz compose --target cursor', kind: 'reproducer', at: '2026-07-19' } },
+  gemini: { shell: { evidence: 'adapter emit', kind: 'reproducer', at: '2026-07-19' }, skills: { evidence: 'dz compose --target gemini', kind: 'reproducer', at: '2026-07-19' } },
+  windsurf: { shell: { evidence: 'adapter emit', kind: 'reproducer', at: '2026-07-19' }, skills: { evidence: 'dz compose --target windsurf', kind: 'reproducer', at: '2026-07-19' } },
+};
+
+export interface UnbackedCapability {
+  readonly target: TargetName;
+  readonly capability: RuntimeCapability;
+  /**
+   * `stale-runtime-version` is INCONCLUSIVE, not a refutation: the grant was proven, on a runtime
+   * that is no longer the installed one. It clears when a current-version probe is recorded.
+   */
+  readonly reason: 'no-evidence-record' | 'dangling-transcript' | 'stale-runtime-version';
+  readonly evidence?: string;
+  /** `recorded → probed`, for the stale case. */
+  readonly recordedVersion?: string;
+  readonly probedVersion?: string;
+}
+
+/**
+ * Runtime versions observed NOW, keyed by target — injected, never probed here (this module is
+ * pure). An absent entry means "not probed", which flips nothing.
+ */
+export type ProbedRuntimeVersions = Partial<Record<TargetName, string>>;
+
+/**
+ * Every capability grant that is NOT backed by usable evidence.
+ *
+ * PURE, with the filesystem injected as `transcriptExists`. That is deliberate: the property this
+ * enforces — *a grant with a dangling transcript is not a grant* — has to be provable without a
+ * repository on disk, or the mutation gate (which copies the PACKAGE, not the repo) could never
+ * turn its mutant red, and an unkillable mutant is a false green wearing a gate's clothes.
+ */
+export function findUnbackedCapabilities(
+  transcriptExists: (path: string) => boolean,
+  capabilities: Record<TargetName, readonly RuntimeCapability[]> = TARGET_CAPABILITIES,
+  evidence: Record<TargetName, Partial<Record<RuntimeCapability, CapabilityEvidence>>> = CAPABILITY_EVIDENCE,
+  probedVersions: ProbedRuntimeVersions = {},
+): UnbackedCapability[] {
+  const out: UnbackedCapability[] = [];
+  for (const target of Object.keys(capabilities) as TargetName[]) {
+    for (const capability of capabilities[target]) {
+      const record = evidence[target]?.[capability];
+      if (record === undefined) {
+        out.push({ target, capability, reason: 'no-evidence-record' });
+        continue;
+      }
+      if (record.kind === 'transcript' && !transcriptExists(record.evidence)) {
+        out.push({ target, capability, reason: 'dangling-transcript', evidence: record.evidence });
+        continue;
+      }
+      // Version pin (ADR-006, finding 3). Only fires when BOTH sides are known: an unprobed target
+      // stays silent rather than reporting every grant stale on a machine without the runtime.
+      const probed = probedVersions[target];
+      if (record.runtimeVersion !== undefined && probed !== undefined && probed !== record.runtimeVersion) {
+        out.push({
+          target,
+          capability,
+          reason: 'stale-runtime-version',
+          evidence: record.evidence,
+          recordedVersion: record.runtimeVersion,
+          probedVersion: probed,
+        });
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Compare two recorded runtime versions the way a version string means it.
+ *
+ * `null` when the two are not comparable (different product, unparseable) — which the caller reads
+ * as "not the newest", the conservative direction.
+ */
+function compareRuntimeVersions(a: string, b: string): number | null {
+  const parse = (v: string): { product: string; parts: number[] } | null => {
+    const m = /^(.*?)\s*(\d+(?:\.\d+)*)\s*$/.exec(v.trim());
+    if (m === null) return null;
+    return { product: (m[1] ?? '').trim(), parts: (m[2] ?? '').split('.').map((n) => Number(n)) };
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  if (pa === null || pb === null || pa.product !== pb.product) return null;
+  const len = Math.max(pa.parts.length, pb.parts.length);
+  for (let i = 0; i < len; i += 1) {
+    const x = pa.parts[i] ?? 0;
+    const y = pb.parts[i] ?? 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * The newest runtime version recorded among a target's TRANSCRIPT evidence, or `null`.
+ *
+ * This is what makes staleness detectable WITHOUT running anything: the records date themselves
+ * against each other. `dz parity` computes a matrix and must keep doing so deterministically — a
+ * `codex --version` subprocess inside it would make a pure report depend on the machine it prints
+ * on. Re-probing one capability is what dates the others (fix round 2, R2-3).
+ */
+export function newestRecordedRuntimeVersion(
+  target: TargetName,
+  evidence: Record<TargetName, Partial<Record<RuntimeCapability, CapabilityEvidence>>> = CAPABILITY_EVIDENCE,
+): string | null {
+  let newest: string | null = null;
+  for (const record of Object.values(evidence[target] ?? {})) {
+    if (record === undefined || record.kind !== 'transcript' || record.runtimeVersion === undefined) continue;
+    if (newest === null) {
+      newest = record.runtimeVersion;
+      continue;
+    }
+    const cmp = compareRuntimeVersions(newest, record.runtimeVersion);
+    if (cmp !== null && cmp < 0) newest = record.runtimeVersion;
+  }
+  return newest;
+}
+
+/**
+ * Transcript evidence that is out of date with the newest record for its own target.
+ *
+ * SCOPE, stated because it is a judgement and not a derivation: the version rule applies to
+ * `kind: 'transcript'` records only. A transcript FREEZES one runtime moment, so it can go stale; a
+ * `reproducer` is a command anyone can re-run, and calling it stale would report `dz --version` as
+ * expired. A transcript with NO `runtimeVersion` is stale too — an undated observation cannot be
+ * shown to be current.
+ *
+ * INCONCLUSIVE, never a refutation: the grant is not withdrawn, it is awaiting its re-probe.
+ */
+export function findStaleTranscriptEvidence(
+  capabilities: Record<TargetName, readonly RuntimeCapability[]> = TARGET_CAPABILITIES,
+  evidence: Record<TargetName, Partial<Record<RuntimeCapability, CapabilityEvidence>>> = CAPABILITY_EVIDENCE,
+): UnbackedCapability[] {
+  const out: UnbackedCapability[] = [];
+  for (const target of Object.keys(capabilities) as TargetName[]) {
+    const newest = newestRecordedRuntimeVersion(target, evidence);
+    if (newest === null) continue; // nothing version-pinned on this target ⇒ nothing to be stale against
+    for (const capability of capabilities[target]) {
+      const record = evidence[target]?.[capability];
+      if (record === undefined || record.kind !== 'transcript') continue;
+      const recorded = record.runtimeVersion;
+      if (recorded !== undefined && compareRuntimeVersions(recorded, newest) === 0) continue;
+      out.push({
+        target,
+        capability,
+        reason: 'stale-runtime-version',
+        evidence: record.evidence,
+        ...(recorded !== undefined ? { recordedVersion: recorded } : {}),
+        probedVersion: newest,
+      });
+    }
+  }
+  return out;
+}
+
 /** How a feature manifests on a platform: a concrete FORM with its runtime requirements. */
 export interface FeatureForm {
   /** Human-readable name of the form, shown as the `via` of a parity cell (AM-2). */
@@ -124,7 +377,7 @@ export const PARITY_FEATURES: readonly ParityFeature[] = [
     id: 'claim-check',
     title: 'Integrity claim-check',
     forms: [
-      { form: 'PreToolUse hook (automatic on Write/Edit)', requires: ['hooks'], level: 'full' },
+      { form: 'PreToolUse hook (automatic on Write/Edit)', requires: ['hooks-write'], level: 'full' },
       { form: 'dz claim-check (CLI) + publish gate', requires: ['shell'], level: 'manual' },
     ],
   },
@@ -137,7 +390,7 @@ export const PARITY_FEATURES: readonly ParityFeature[] = [
     id: 'learning-apply',
     title: 'Self-learning: automatic apply-leg',
     forms: [
-      { form: 'UserPromptSubmit hook (auto recall)', requires: ['hooks'], level: 'full' },
+      { form: 'UserPromptSubmit hook (auto recall)', requires: ['hooks-prompt'], level: 'full' },
       { form: 'manual dz recall before a task', requires: ['shell'], level: 'manual' },
     ],
   },
@@ -215,6 +468,42 @@ export function computeParity(feature: ParityFeature, capabilities: readonly Run
   return { level: 'none' };
 }
 
+/**
+ * A parity cell AS REPORTED — the computed level, plus the one thing the computation cannot know:
+ * whether the evidence behind the deciding capability is still current.
+ *
+ * `inconclusive` is a REPORTING level, not a model level: `computeParity` keeps answering the
+ * capability question, and this layer answers the evidence question. Keeping them apart is what
+ * lets the matrix stay a pure function of the capability model.
+ */
+export interface ParityReportCell {
+  readonly level: 'full' | 'manual' | 'none' | 'inconclusive';
+  readonly via?: string | undefined;
+  /** The stale capabilities the deciding form depends on (present only when `inconclusive`). */
+  readonly staleEvidence?: readonly RuntimeCapability[];
+}
+
+/**
+ * Downgrade a cell whose DECIDING form rests on stale evidence to `inconclusive`.
+ *
+ * The round-1 gate could tell that `hooks-prompt` evidence was stale and nothing a user runs ever
+ * asked it (fix round 2, R2-3): `dz parity` printed `full` for the auto-recall leg on codex off a
+ * transcript recorded on a runtime that is no longer installed. A cell that says `full` on evidence
+ * nobody has re-confirmed is the same class of claim this whole feature exists to refuse.
+ */
+export function downgradeForStaleEvidence(
+  feature: ParityFeature,
+  cell: ParityCell,
+  staleCapabilities: readonly RuntimeCapability[],
+): ParityReportCell {
+  if (cell.level === 'none' || cell.via === undefined || staleCapabilities.length === 0) return cell;
+  const form = feature.forms.find((f) => f.form === cell.via);
+  if (form === undefined) return cell;
+  const hit = form.requires.filter((r) => staleCapabilities.includes(r));
+  if (hit.length === 0) return cell;
+  return { level: 'inconclusive', via: cell.via, staleEvidence: hit };
+}
+
 export interface ParityMatrixRow {
   readonly feature: ParityFeature;
   readonly cells: Readonly<Record<TargetName, ParityCell>>;