@dzhechkov/harness-core 0.3.126 → 0.3.128

package/src/parity.ts

@@ -0,0 +1,231 @@
+/**
+ * Target-parity model (`dz parity`, feature target-parity-matrix, ADR-001).
+ *
+ * The honest map of "which harness feature works on which target, and HOW". The matrix does NOT
+ * exist as a hand-written document anywhere (the sitedoc lesson, b57e686: a hand-maintained
+ * duplicate list is a second drift surface) — this declarative model is the ONLY source, and the
+ * table is always COMPUTED from it.
+ *
+ * Honesty contract (FR-6): a capability flag states only what has been VERIFIED, each with its
+ * source in a comment. Unknown support is NOT flagged — a feature falsely promised on a target
+ * is worse than one conservatively marked absent.
+ *
+ * Derivation anchor (FR-4): `TARGET_CAPABILITIES` is typed `Record<TargetName, …>`, so ADDING an
+ * 11th target to the registry refuses to compile until it is classified here; the model test
+ * re-asserts coverage at runtime and validates every capability reference.
+ *
+ * @packageDocumentation
+ */
+
+import type { TargetName } from './targets.js';
+
+/** Runtime capabilities a target platform can provide to harness features. */
+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)
+  | '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)
+  | 'statusline'; // live status line (🚦 gates)
+
+/** All declared capabilities — the closed vocabulary the model test validates references against. */
+export const RUNTIME_CAPABILITIES: readonly RuntimeCapability[] = [
+  'shell',
+  'skills',
+  'hooks',
+  'mcp',
+  'mcp-configured',
+  'workflows',
+  'statusline',
+];
+
+/**
+ * What each target has been VERIFIED to provide (FR-6: source per line; conservative — an
+ * unverified capability stays absent until proven, never assumed).
+ */
+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'],
+  // MCP subsystem probed live: `codex mcp --help` + `codex mcp list` answer (2026-07-19).
+  codex: ['shell', 'skills', 'mcp'],
+  // Conservative v1: skills emission verified by the adapters; richer runtimes unproven.
+  opencode: ['shell', 'skills'],
+  hermes: ['shell', 'skills'],
+  openclaude: ['shell', 'skills'],
+  copilot: ['shell', 'skills'],
+  // Lowest common denominator: one merged AGENTS.md — skills arrive as a single managed file.
+  'agents-md': ['shell', 'skills'],
+  cursor: ['shell', 'skills'],
+  gemini: ['shell', 'skills'],
+  windsurf: ['shell', 'skills'],
+};
+
+/** 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). */
+  readonly form: string;
+  readonly requires: readonly RuntimeCapability[];
+  /** `full` = the complete experience; `manual` = works, but the user drives it by hand. */
+  readonly level: 'full' | 'manual';
+}
+
+export interface ParityFeature {
+  readonly id: string;
+  readonly title: string;
+  readonly forms: readonly FeatureForm[];
+}
+
+/**
+ * The harness feature inventory for the parity map. A feature may carry SEVERAL forms — parity
+ * for a target is the BEST form whose requirements the target provides (e.g. claim-check: the
+ * hook form is automatic on every Write/Edit; the CLI form works anywhere but must be invoked).
+ */
+export const PARITY_FEATURES: readonly ParityFeature[] = [
+  {
+    id: 'dz-cli',
+    title: 'dz CLI (all commands)',
+    forms: [{ form: 'shell command', requires: ['shell'], level: 'full' }],
+  },
+  {
+    id: 'skills-packs',
+    title: 'Skill packs (compiled per target)',
+    forms: [{ form: 'compiled skills via adapter', requires: ['skills'], level: 'full' }],
+  },
+  {
+    id: 'feature-adr',
+    title: 'feature-adr pipeline',
+    forms: [
+      { form: 'ultracode deterministic workflow', requires: ['workflows'], level: 'full' },
+      { form: 'interactive skill (plain /feature-adr)', requires: ['skills'], level: 'manual' },
+    ],
+  },
+  {
+    id: 'delivery-gate',
+    title: 'Step-10 Delivery Gate',
+    forms: [
+      { form: 'workflow delivery block', requires: ['workflows'], level: 'full' },
+      // Portable form (portable-gates, run #3): the CLI runs the deterministic parts (artifact probes,
+      // hand-off arithmetic, cross-validation bookkeeping) and DISPATCHES the semantic review to the
+      // target's own agent runtime — the `dz challenge` cartridge precedent. Requires only `shell`.
+      { form: 'dz delivery-check (CLI 4-plane hand-off protocol)', requires: ['shell'], level: 'manual' },
+    ],
+  },
+  {
+    id: 'challenge-panel',
+    title: 'Adversarial challenge-panel (plan gate)',
+    forms: [
+      { form: 'workflow plan gate', requires: ['workflows'], level: 'full' },
+      { form: 'dz challenge (CLI)', requires: ['shell'], level: 'manual' },
+    ],
+  },
+  {
+    id: 'claim-check',
+    title: 'Integrity claim-check',
+    forms: [
+      { form: 'PreToolUse hook (automatic on Write/Edit)', requires: ['hooks'], level: 'full' },
+      { form: 'dz claim-check (CLI) + publish gate', requires: ['shell'], level: 'manual' },
+    ],
+  },
+  {
+    id: 'learning-collect',
+    title: 'Self-learning: collect + rank (dz teach/recall)',
+    forms: [{ form: 'dz teach / consolidate / recall', requires: ['shell'], level: 'full' }],
+  },
+  {
+    id: 'learning-apply',
+    title: 'Self-learning: automatic apply-leg',
+    forms: [
+      { form: 'UserPromptSubmit hook (auto recall)', requires: ['hooks'], level: 'full' },
+      { form: 'manual dz recall before a task', requires: ['shell'], level: 'manual' },
+    ],
+  },
+  {
+    id: 'statusline-gates',
+    title: 'Live 🚦 gates status line',
+    forms: [{ form: 'statusline integration', requires: ['statusline'], level: 'full' }],
+  },
+  {
+    id: 'project-guards',
+    title: 'Deterministic project guards (setup --guards)',
+    forms: [{ form: 'zero-dependency check.mjs (runs anywhere node runs)', requires: ['shell'], level: 'full' }],
+  },
+  {
+    id: 'release-signing',
+    title: 'Verified release + signing (dz release/sign/sbom)',
+    forms: [{ form: 'dz release / sign / sbom / publish', requires: ['shell'], level: 'full' }],
+  },
+  {
+    id: 'mcp-memory',
+    title: 'MCP memory (AgentDB, agentic-qe)',
+    forms: [
+      { form: 'preconfigured MCP servers (.mcp.json ships in-repo)', requires: ['mcp-configured'], level: 'full' },
+      { form: 'manual MCP server config (e.g. `codex mcp add`)', requires: ['mcp'], level: 'manual' },
+    ],
+  },
+];
+
+/**
+ * Short column labels for the grid renderer — kept NEXT TO the model and covered by the same
+ * coverage test (a hand map in the CLI would be a second, unchecked target registry).
+ */
+export const TARGET_SHORT_LABELS: Record<TargetName, string> = {
+  'claude-code': 'cc',
+  codex: 'cdx',
+  opencode: 'ocd',
+  hermes: 'hrm',
+  openclaude: 'ocl',
+  copilot: 'cop',
+  'agents-md': 'amd',
+  cursor: 'cur',
+  gemini: 'gem',
+  windsurf: 'wsf',
+};
+
+/**
+ * The quality-GATE class of features — what the scaffolded gates doc lists under "Gates runnable
+ * here" (a full parity dump put "Skill packs — full" under a gates heading; delivery finding).
+ * Must stay a subset of PARITY_FEATURES ids (pinned by test).
+ */
+export const GATE_FEATURE_IDS: readonly string[] = [
+  'feature-adr',
+  'delivery-gate',
+  'challenge-panel',
+  'claim-check',
+  'project-guards',
+  'release-signing',
+];
+
+/** One computed parity cell: the best available form for a feature on a target. */
+export interface ParityCell {
+  readonly level: 'full' | 'manual' | 'none';
+  /** Which form delivers it (absent only when level is `none`) — AM-2: "partial" must name its path. */
+  readonly via?: string | undefined;
+}
+
+/** Compute the parity cell for one feature on one target (pure; best form wins, `full` first). */
+export function computeParity(feature: ParityFeature, capabilities: readonly RuntimeCapability[]): ParityCell {
+  const caps = new Set(capabilities);
+  const usable = feature.forms.filter((f) => f.requires.every((r) => caps.has(r)));
+  const full = usable.find((f) => f.level === 'full');
+  if (full !== undefined) return { level: 'full', via: full.form };
+  const manual = usable.find((f) => f.level === 'manual');
+  if (manual !== undefined) return { level: 'manual', via: manual.form };
+  return { level: 'none' };
+}
+
+export interface ParityMatrixRow {
+  readonly feature: ParityFeature;
+  readonly cells: Readonly<Record<TargetName, ParityCell>>;
+}
+
+/** The full computed matrix over every declared feature × every registered target. */
+export function buildParityMatrix(): ParityMatrixRow[] {
+  const targets = Object.keys(TARGET_CAPABILITIES) as TargetName[];
+  return PARITY_FEATURES.map((feature) => {
+    const cells = {} as Record<TargetName, ParityCell>;
+    for (const t of targets) cells[t] = computeParity(feature, TARGET_CAPABILITIES[t]);
+    return { feature, cells };
+  });
+}

package/src/sign.ts

@@ -113,23 +113,32 @@ export function checkManifestEntries(files: unknown): string | null {
   return null;
 }
 
+/**
+ * Directory names that are NOT pack content and are excluded from BOTH walks. node_modules/.git:
+ * installed deps / VCS metadata. `.agentic-qe`/`.dz`: LOCAL RUNTIME STATE (learning DBs, RVF
+ * stores, witness keys) that background workers create inside pack cwds — gitignored, machine-
+ * specific, never shipped. Signing them made 19 packs verify green LOCALLY (files present, hashes
+ * match) and TAMPERED in CI (clean checkout lacks the gitignored state) — found live on GH run
+ * #103, 2026-07-19. State is not content; the walks must never see it.
+ */
+const EXCLUDED_DIRS = new Set(['node_modules', '.git', '.agentic-qe', '.dz']);
+
 /** Every file under `root`, POSIX-relative, excluding the manifest and the SBOM themselves. */
 export function listPackFiles(root: string): string[] {
   const out: string[] = [];
   const walk = (dir: string, rel: string): void => {
     for (const e of readdirSync(dir, { withFileTypes: true })) {
-      // node_modules/.git are unsigned territory BY DESIGN (installed deps / VCS metadata — not pack
-      // content; npm tarballs ship neither). The SIGN and VERIFY walks MUST share these exclusions:
-      // an asymmetry here false-TAMPERs every pnpm workspace pack whose node_modules holds symlinks
-      // (found live arming task #36 — 10 of 23 skill packs flagged right after signing).
-      if (e.name === 'node_modules' || e.name === '.git') continue;
+      // Excluded dirs are unsigned territory BY DESIGN (see EXCLUDED_DIRS). The SIGN and VERIFY
+      // walks MUST share these exclusions: an asymmetry here false-TAMPERs every pnpm workspace
+      // pack whose node_modules holds symlinks (found live arming task #36 — 10 of 23 packs).
+      if (EXCLUDED_DIRS.has(e.name)) continue;
       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);
       // NOT else-isFile: a symlink (or other non-file) OUTSIDE the excluded dirs must stay VISIBLE to the
       // verify sweep — it fails as "present but not signed" / "is a symlink" (R3-4: a smuggled symlink is a
-      // finding, not something to silently ignore). Only node_modules/.git are exempt territory.
+      // finding, not something to silently ignore). Only EXCLUDED_DIRS are exempt territory.
       else out.push(r);
     }
   };
@@ -146,7 +155,7 @@ export function listSignablePackFiles(root: string): string[] {
   const out: string[] = [];
   const walk = (dir: string, rel: string): void => {
     for (const e of readdirSync(dir, { withFileTypes: true })) {
-      if (e.name === 'node_modules' || e.name === '.git') continue;
+      if (EXCLUDED_DIRS.has(e.name)) continue;
       if (e.name === MANIFEST_NAME || e.name === SBOM_NAME) continue;
       const abs = join(dir, e.name);
       const r = rel ? rel + '/' + e.name : e.name;