@dzhechkov/harness-core 0.3.125 → 0.3.127

package/src/parity.ts

@@ -0,0 +1,211 @@
+/**
+ * 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' }],
+  },
+  {
+    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',
+};
+
+/** 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 };
+  });
+}