@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/runtime/retrieval-record.js

@@ -0,0 +1,293 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { taskStoreDir, taskRecord, resolveTaskScope } = require('./task-scope.js');
+const { assertSafeTaskId } = require('./evidence-ledger.js');
+const { readTaskState, updateTaskState } = require('./task-state.js');
+const { storeFile, activeAttempt } = require('./task-attempts.js');
+const { projectRoot: lifecycleProjectRoot } = require('./lifecycle/root.js');
+
+/**
+ * Path of a task's retrieval-plan store.
+ *
+ * The task id is validated by the evidence ledger's own rule, unchanged: it becomes a filename, so
+ * it must never be able to name a path.
+ * @param {string} projectRoot
+ * @param {string} taskId
+ * @param {string|null} [slug]
+ * @returns {string}
+ */
+function planPath(projectRoot     , taskId     , slug      = null)         {
+  const dir = taskStoreDir({ projectRoot, store: 'retrieval', taskId: assertSafeTaskId(taskId), slug });
+  return path.join(dir, `${taskId}.json`);
+}
+
+/**
+ * Reads and validates one task's retrieval plan via readTaskState.
+ * Returns null when the plan file does not exist.
+ * @param {string} projectRoot
+ * @param {string} taskId
+ * @param {string|null} [slug]
+ * @param {any} [fsImpl]
+ * @returns {any|null}
+ */
+function readPlan(projectRoot     , taskId     , slug      = null, fsImpl      = fs)             {
+  return readTaskState(fsImpl, taskRecord({ projectRoot, store: 'retrieval', taskId: assertSafeTaskId(taskId), slug, fsImpl }).read);
+}
+
+/**
+ * Updates a task's retrieval plan under the task-state lock.
+ * @param {string} projectRoot
+ * @param {string} taskId
+ * @param {string|null} slug
+ * @param {(disk: any|null) => any} build
+ * @param {any} [fsImpl]
+ * @returns {string} the written file path
+ */
+function updatePlan(projectRoot     , taskId     , slug     , build     , fsImpl      = fs, prepare      )         {
+  const { file, seed } = taskRecord({ projectRoot, store: 'retrieval', taskId: assertSafeTaskId(taskId), slug, fsImpl });
+  return updateTaskState({ fsImpl, file, build, prepare: () => { seed(); if (prepare) prepare(); } });
+}
+
+/** Move a syntactically unreadable plan aside before its replacement is written under the lock. */
+function moveCorruptPlanAside(projectRoot     , taskId     , slug      = null, fsImpl      = fs)                {
+  const file = planPath(projectRoot, taskId, slug);
+  if (!fsImpl.existsSync(file)) return null;
+  try {
+    JSON.parse(fsImpl.readFileSync(file, 'utf8'));
+    return null;
+  } catch (error     ) {
+    if (!(error instanceof SyntaxError)) throw error;
+    const corruptFile = `${file}.corrupt-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+    fsImpl.renameSync(file, corruptFile);
+    return corruptFile;
+  }
+}
+
+/**
+ * Mints a new plan id: rp_<base36 ms>_<4 hex>.
+ * @returns {string}
+ */
+function mintPlanId()         {
+  return `rp_${Date.now().toString(36)}_${crypto.randomBytes(2).toString('hex')}`;
+}
+
+/**
+ * Formats declared intents from a plan: sorted, comma-joined, or 'none declared'.
+ *
+ * @param {any} plan
+ * @returns {string}
+ */
+function declaredIntentList(plan     , sep = ', ')         {
+  const declaredIntents = Array.isArray(plan?.needs)
+    ? plan.needs.map((n     ) => n.intent).filter(Boolean).sort()
+    : [];
+  return declaredIntents.length > 0 ? declaredIntents.join(sep) : 'none declared';
+}
+
+/**
+ * Resolves a declared need from a plan for a given intent.
+ *
+ * @param {any} plan
+ * @param {string} intent
+ * @param {string} taskId
+ * @returns {{ ok: true, queryRef: string, need: any } | { ok: false, message: string }}
+ */
+function resolveNeed(plan     , intent        , taskId        )      {
+  if (!plan) {
+    const message = `no retrieval plan is declared for task '${taskId}', so --need '${intent}' names nothing. Declare one first: doflow retrieval-plan --task-id ${taskId} --action declare --need ${intent}, then re-run.`;
+    return { ok: false, message };
+  }
+  const list = declaredIntentList(plan);
+
+  if (!plan.planId) {
+    const message = `the retrieval plan for task '${taskId}' was declared before query binding and has no plan id. Re-declare it: doflow retrieval-plan --task-id ${taskId} --action declare --need ${declaredIntentList(plan, ',')}, then re-run.`;
+    return { ok: false, message };
+  }
+
+  const need = Array.isArray(plan.needs) ? plan.needs.find((n     ) => n.intent === intent) : null;
+  if (!need) {
+    const message = `'${intent}' is not a declared need of task '${taskId}' (plan ${plan.planId}). Declared: ${list}. Re-run with one of them, or re-declare the plan with this need.`;
+    return { ok: false, message };
+  }
+
+  if (!need.queryRef) {
+    const message = `the retrieval plan for task '${taskId}' was declared before query binding and has no plan id. Re-declare it: doflow retrieval-plan --task-id ${taskId} --action declare --need ${declaredIntentList(plan, ',')}, then re-run.`;
+    return { ok: false, message };
+  }
+
+  return {
+    ok: true,
+    queryRef: need.queryRef,
+    need,
+  };
+}
+
+/** Resolve the plan's query binding and the task's active attempt in one reusable operation. */
+function resolveRetrievalBinding({ projectRoot, taskId, intent, slug = null, fsImpl = fs, attemptRoot = null }     )      {
+  const plan = readPlan(projectRoot, taskId, slug, fsImpl);
+  const resolved = resolveNeed(plan, intent, taskId);
+  if (!resolved.ok) return resolved;
+  return {
+    ok: true,
+    plan,
+    queryRef: resolved.queryRef,
+    need: resolved.need,
+    attemptRef: activeAttemptRef(projectRoot, taskId, slug, fsImpl, attemptRoot),
+  };
+}
+
+/** Append one validated provider attempt under the retrieval-plan state lock. */
+function appendRetrievalAttempt({
+  projectRoot, taskId, intent, provider, status, reason, note = null, indexState,
+  slug = null, attemptRef = undefined, fsImpl = fs, expectedCapability = undefined,
+  expectedPrimaryProvider = undefined, registeredProviders = undefined,
+}     )      {
+  const allowedIndexStates = ['FRESH', 'STALE', 'UNKNOWN', 'NOT_APPLICABLE'];
+  if (!allowedIndexStates.includes(indexState)) {
+    throw new Error(`attempt indexState '${indexState}' is invalid; expected one of ${allowedIndexStates.join(', ')}`);
+  }
+  const allowedReasons                           = {
+    EMPTY: ['empty-answer', 'index-stale', 'index-unverifiable'],
+    UNREACHED: ['provider-unavailable', 'policy-bypass', 'provider-error', 'timeout'],
+    UNVERIFIED: ['index-unverifiable'],
+  };
+  if (status === 'RETRIEVED') throw new Error('RETRIEVED is derived from evidence and cannot be appended as a provider attempt');
+  if (!Object.prototype.hasOwnProperty.call(allowedReasons, status) || !allowedReasons[status].includes(reason)) {
+    throw new Error(`attempt reason '${reason}' is not valid for status '${status}'`);
+  }
+  if (!Array.isArray(registeredProviders) || !registeredProviders.includes(provider)) {
+    throw new Error(`provider '${provider}' is not registered for this capability`);
+  }
+  if (note !== null && String(note).length > 160) throw new Error('attempt note is longer than 160 characters');
+
+  let savedAttempt      = null;
+  const file = updatePlan(projectRoot, taskId, slug, (disk     ) => {
+    if (disk === null) throw new Error(`the retrieval plan for task ${taskId} was removed during the update; re-declare it`);
+    const current = disk;
+    const targetNeed = Array.isArray(current.needs) ? current.needs.find((need     ) => need.intent === intent) : null;
+    if (!targetNeed) throw new Error(`need '${intent}' missing from disk plan during update`);
+    if (expectedCapability !== undefined && targetNeed.capability !== expectedCapability) {
+      throw new Error(`need '${intent}' capability changed during update`);
+    }
+    if (expectedPrimaryProvider !== undefined && targetNeed.provider !== expectedPrimaryProvider) {
+      throw new Error(`need '${intent}' provider changed during update`);
+    }
+    if (provider === undefined || provider === null || String(provider).trim() === '') throw new Error('attempt provider is required');
+    if (!Array.isArray(targetNeed.attempts)) targetNeed.attempts = [];
+    const n = targetNeed.attempts.reduce((max        , prior     ) => Math.max(max, Number.isInteger(prior?.n) ? prior.n : 0), 0) + 1;
+    const role = provider === targetNeed.provider ? 'primary' : 'fallback';
+    savedAttempt = {
+      n, provider, capability: targetNeed.capability, role, status, reason,
+      note: note !== undefined && note !== null ? String(note) : null,
+      indexState,
+      attemptRef: attemptRef === undefined ? activeAttemptRef(projectRoot, taskId, slug, fsImpl) : attemptRef,
+      evidenceIds: [],
+      recordedAt: new Date().toISOString(),
+      recordedBy: 'caller',
+    };
+    targetNeed.attempts.push(savedAttempt);
+    return current;
+  }, fsImpl);
+  return { file, attempt: savedAttempt };
+}
+
+/**
+ * Reads the 070 active attempt ref for a task, returning `${taskId}#${token}` or null.
+ *
+ * Resolves the feature slug via resolveTaskScope, reads storeFile(lifecycleProjectRoot(projectRoot), featureSlug),
+ * and finds the active attempt for the task. If no slug, no store, no entry or no active attempt exists,
+ * or if any failure occurs finding or reading the store, returns null (IC-005: "no attempt" never fails the write).
+ *
+ * @param {string} projectRoot
+ * @param {string} taskId
+ * @param {string|null} [slug]
+ * @param {any} [fsImpl]
+ * @returns {string|null}
+ */
+function activeAttemptRef(projectRoot     , taskId     , slug      = null, fsImpl      = fs, attemptRoot      = null)                {
+  try {
+    const featureSlug = resolveTaskScope({ projectRoot, taskId, slug }).slug;
+    if (!featureSlug) return null;
+
+    const file = storeFile(attemptRoot || lifecycleProjectRoot(projectRoot), featureSlug);
+    if (!fsImpl.existsSync(file)) return null;
+
+    const data = readTaskState(fsImpl, file);
+    if (!data || !data.tasks || !data.tasks[taskId]) return null;
+
+    const active = activeAttempt(data.tasks[taskId]);
+    if (!active || active.token === undefined || active.token === null) return null;
+
+    return `${taskId}#${active.token}`;
+  } catch {
+    return null;
+  }
+}
+
+/** Binds active evidence to declared query refs and explains evidence that could have matched. */
+function bindEvidence(plan     , items       ) {
+  const byNeed = new Map               ();
+  const unbound        = [];
+  const needs = Array.isArray(plan?.needs) ? plan.needs : [];
+  for (const need of needs) byNeed.set(need.intent, []);
+  for (const item of items) {
+    if (item.status !== 'active') continue;
+    const source = item.source || {};
+    const exact = needs.find((need     ) => need.queryRef && need.queryRef === source.queryRef);
+    if (exact) {
+      if (plan.attemptRef && source.attemptRef && plan.attemptRef !== source.attemptRef) {
+        unbound.push({ id: item.id, cause: 'other-attempt' });
+      } else {
+        const matches = byNeed.get(exact.intent);
+        if (matches) matches.push(item);
+      }
+      continue;
+    }
+    if (source.queryRef) {
+      unbound.push({ id: item.id, cause: 'replaced-plan' });
+    } else if (needs.some((need     ) => need.capability && need.capability === source.capability)) {
+      unbound.push({ id: item.id, cause: 'no-query-ref' });
+    }
+  }
+  return { byNeed, unbound };
+}
+
+/** Selects the highest-precedence recorded attempt, with the earliest attempt winning ties. */
+function deriveOutcome(need     ) {
+  const precedence                         = { RETRIEVED: 0, EMPTY: 1, UNVERIFIED: 3, UNREACHED: 4 };
+  const attempts = (Array.isArray(need?.attempts) ? need.attempts : []).filter((attempt     ) =>
+    !(attempt.recordedBy === 'derived' && attempt.basis !== 'report-need'
+      && (!Array.isArray(attempt.evidenceIds) || attempt.evidenceIds.length === 0)));
+  const ranked = [...attempts].sort((a, b) => {
+    const rank = (attempt     ) => attempt.status === 'EMPTY' && ['STALE', 'UNKNOWN'].includes(attempt.indexState)
+      ? (attempt.indexState === 'STALE' ? 2 : 3)
+      : (precedence[attempt.status] ?? 4);
+    return rank(a) - rank(b) || a.n - b.n;
+  });
+  const winner = ranked[0];
+  return {
+    result: winner ? winner.status : 'UNREACHED',
+    resolvedBy: winner ? winner.n : null,
+    viaFallback: Boolean(winner && winner.role === 'fallback'),
+  };
+}
+
+module.exports = {
+  planPath,
+  readPlan,
+  updatePlan,
+  moveCorruptPlanAside,
+  mintPlanId,
+  resolveNeed,
+  resolveRetrievalBinding,
+  appendRetrievalAttempt,
+  activeAttemptRef,
+  declaredIntentList,
+  bindEvidence,
+  deriveOutcome,
+};

package/src/runtime/review/command.js

@@ -0,0 +1,246 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { validateFindings, countFindings, reviewAdvisories, invalidProjectCandidate, invalidPresetCandidate, telemetryProtocol } = require('./findings.js');
+const { resolveActiveFeature } = require('../feature-resolve.js');
+const { TelemetryWriter } = require('../trace/telemetry.js');
+const { finishRuntime } = require('../cli-result.js');
+const { handleReviewStart, validSlug } = require('./start.js');
+const { crossCheckAuthor, authoringIdentities } = require('./identity.js');
+const { isQualifiedId } = require('../../helper/package-ids.js');
+
+                                        
+                                              
+                                                                                      
+                                                                 
+                                                                                       
+
+const TELEMETRY_COUNT_KEYS = Object.freeze([
+  'rounds', 'seats', 'seat_findings', 'converged', 'blocker', 'should_fix', 'note',
+  'open', 'fixed', 'refuted', 'user_accepted', 'pre_existing', 'escaped', 'confirmed',
+  'plausible', 'unverified_blockers', 'bug_classes',
+]);
+
+// Inherited location variables would point the check at another repository (C-8).
+const GIT_LOCATION_KEYS = Object.freeze([
+  'GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY', 'GIT_COMMON_DIR',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+]);
+
+function defaultGit(args          , cwd        , env     )                            {
+  const gitEnv = { ...env };
+  for (const key of GIT_LOCATION_KEYS) delete gitEnv[key];
+  return spawnSync('git', ['-C', cwd, ...args], { cwd, env: gitEnv, stdio: 'ignore' });
+}
+
+/** The project's `review.sameFamily` (119 L-C3), read for the checkout the verb runs in. A settings view that cannot
+ * load, or an invalid project or local value for the key (C-6: the resolver would fall back to the default without a
+ * word), is `warn` plus `unread`; the caller turns `unread` into an error. Never a crash, never a silent `refuse`. */
+function readSameFamily(load                                                     , cwd        , env     )                                                {
+  try {
+    const resolution = load({ projectRoot: path.resolve(cwd), env }).get('review.sameFamily');
+    if (invalidProjectCandidate(resolution)) return { value: 'warn', unread: true };
+    return { value: resolution.value === 'refuse' ? 'refuse' : 'warn', unread: false };
+  } catch {
+    return { value: 'warn', unread: true };
+  }
+}
+
+/** The effective `review.preset` (C-2 closure), read for the checkout the verb runs in. A settings view that cannot
+ * load, or an invalid user, project or local value (the resolver would fall back to `auto` without a word), is `unread`;
+ * the caller turns `unread` into an error, so a broken setting never relaxes the check. */
+function readPreset(load                                                     , cwd        , env     )                                     {
+  try {
+    const resolution = load({ projectRoot: path.resolve(cwd), env }).get('review.preset');
+    if (invalidPresetCandidate(resolution)) return { value: 'auto', unread: true };
+    return { value: typeof resolution.value === 'string' ? resolution.value : 'auto', unread: false };
+  } catch {
+    return { value: 'auto', unread: true };
+  }
+}
+
+// A preset id: a core one as protocols.ts validates it (`^[a-z][a-z0-9-]*$`), or a package preset's qualified id
+// (`<package>.<preset>`, 122 IC-003). Whether it is available and strict enough is the resolver's answer (IC-014).
+const CORE_PRESET_ID = /^[a-z][a-z0-9-]*$/;
+const presetIdShape = (value         )          => typeof value === 'string' && (CORE_PRESET_ID.test(value) || isQualifiedId(value));
+
+function usage(message        , json         , out                        )         {
+  out(json
+    ? JSON.stringify({ ok: false, error: 'usage', message })
+    : `doflow review: ${message}`);
+  return finishRuntime(2);
+}
+
+function hasValue(value         )          {
+  return value !== undefined && value !== null;
+}
+
+function emptyValue(value         )          {
+  return typeof value === 'string' && value.trim().length === 0;
+}
+
+function handleReviewCommand({
+  action,
+  slug,
+  path: recordPath,
+  base,
+  preset,
+  adviceClient,
+  json = false,
+  cwd = process.cwd(),
+  env = process.env,
+  git = defaultGit,
+  loadSettings = (options                                   ) => require('../settings/resolve.js').loadSettings(options),
+  writer,
+  resolve = resolveActiveFeature,
+  out = (line        ) => console.log(line),
+}      = {})                           {
+  if (action !== 'check' && action !== 'start') return usage('action must be check or start', json, out);
+  if (emptyValue(slug) || emptyValue(recordPath) || emptyValue(base) || emptyValue(preset)) return usage('flag values must not be empty', json, out);
+  if (action === 'start') {
+    // 095b IC-001: the start verb reads no record path, and the slug becomes a file name.
+    if (hasValue(recordPath)) return usage('--path is not valid with --action start', json, out);
+    if ((hasValue(slug) && !validSlug(slug)) || (hasValue(base) && typeof base !== 'string')) {
+      return usage('--slug must be a plain feature name and --base a string', json, out);
+    }
+    if (hasValue(preset) && !presetIdShape(preset)) {
+      return usage('--preset must be a preset id (lower-case letters, digits and hyphens, or <package>.<preset> for a package preset)', json, out);
+    }
+    return handleReviewStart({ slug: hasValue(slug) ? slug : null, base: hasValue(base) ? base : null, preset: hasValue(preset) ? preset : null, json, cwd, env, resolve, adviceClient, out });
+  }
+  if (hasValue(base)) return usage('--base is valid only with --action start', json, out);
+  if (hasValue(preset)) return usage('--preset is valid only with --action start', json, out);
+  if (hasValue(slug) && hasValue(recordPath)) return usage('use either --slug or --path, not both', json, out);
+  if ((hasValue(slug) && typeof slug !== 'string') || (hasValue(recordPath) && typeof recordPath !== 'string')) {
+    return usage('--slug and --path values must be strings', json, out);
+  }
+
+  const telemetryWriter               = writer || new TelemetryWriter({ env, start: cwd });
+  let file                = null;
+  let resolverMessage                = null;
+  if (hasValue(recordPath)) {
+    file = path.resolve(cwd, recordPath);
+  } else {
+    let feature     ;
+    try {
+      feature = (resolve                   )({ projectRoot: cwd, slug: hasValue(slug) ? slug : null });
+    } catch (error     ) {
+      feature = { error: 'resolver-failed', message: error?.message || String(error) };
+    }
+    if (feature?.error || typeof feature?.featureFolder !== 'string' || !feature.featureFolder) {
+      resolverMessage = typeof feature?.message === 'string' && feature.message
+        ? feature.message
+        : (typeof feature?.error === 'string' && feature.error ? feature.error : 'feature could not be resolved');
+    } else {
+      file = path.resolve(feature.featureFolder, 'review', 'findings.json');
+    }
+  }
+
+  const errors           = [];
+  const errorDetails = new Map                ();
+  const ancestryAdvisories           = [];
+  const identityAdvisories           = [];
+  let sameFamily                    = 'warn';
+  let reviewPreset = 'auto';
+  let authors        = [];
+  let record                      = null;
+  if (file === null) {
+    errors.push('missing');
+    errorDetails.set('missing', resolverMessage || 'feature record could not be located');
+  } else {
+    let raw        ;
+    try {
+      raw = fs.readFileSync(file, 'utf8');
+    } catch (error     ) {
+      if (error?.code === 'ENOENT') errors.push('missing');
+      else errors.push('unreadable');
+      if (error?.message) errorDetails.set(errors[0], error.message);
+      raw = '';
+    }
+
+    if (errors.length === 0) {
+      // Settings are read only for a record that declares an author: nothing else depends on them (L-C3).
+      let peek      = null;
+      try { peek = JSON.parse(raw); } catch { /* validateFindings reports `json` */ }
+      if (peek !== null && typeof peek === 'object' && Object.hasOwn(peek, 'author')) {
+        const read = readSameFamily(loadSettings, cwd, env);
+        sameFamily = read.value;
+        if (read.unread) errors.push('same-family-setting-unread');
+      }
+      // A record that omits `protocol` is held to the effective `review.preset` (C-2 closure), so it is read for every record.
+      if (peek !== null && typeof peek === 'object') {
+        const read = readPreset(loadSettings, cwd, env);
+        reviewPreset = read.value;
+        if (read.unread) errors.push('review-preset-setting-unread');
+      }
+      authors = authoringIdentities({ slug: peek?.slug, cwd, env, record: peek, fsImpl: fs });
+      const validation = validateFindings(raw, { sameFamily, preset: reviewPreset, authors });
+      for (const error of validation.errors) errors.push(error); // a spread overflows the stack at ~200k errors (C-6)
+      if (!validation.errors.includes('json')) {
+        try { record = JSON.parse(raw); } catch { record = null; }
+      }
+      if (validation.ok && record) {
+        if (Object.hasOwn(record, 'author')) identityAdvisories.push(...crossCheckAuthor({ record, cwd, env }));
+        for (const finding of record.converged) {
+          if (typeof finding.preExistingAt !== 'string') continue;
+          let status                           ;
+          try {
+            status = (git             )(
+              ['merge-base', '--is-ancestor', finding.preExistingAt, record.reviewedHead],
+              path.dirname(file),
+              env,
+            )?.status;
+          } catch {
+            status = null;
+          }
+          if (status === 1) errors.push(`preExistingAt-not-ancestor:${finding.id}`);
+          else if (status !== 0) ancestryAdvisories.push(`ancestry-unchecked:${finding.id}`);
+        }
+      }
+    }
+  }
+
+  const advisories = (record && validateFindings(record, { sameFamily, preset: reviewPreset, authors }).ok
+    ? reviewAdvisories(record, { sameFamily, authors }).concat(identityAdvisories)
+    : []).concat(ancestryAdvisories).sort();
+  const valid = errors.length === 0;
+  const counts = valid && record ? countFindings(record) : null;
+  const result = { schema: 1, path: file, valid, errors, advisories, counts };
+
+  if (json) {
+    out(JSON.stringify(result));
+  } else {
+    out(`review check: ${valid ? 'valid' : 'invalid'} (${errors.length} errors, ${advisories.length} advisories)`);
+    for (const error of errors) {
+      const detail = errorDetails.get(error);
+      out(`error: ${error}${detail ? `: ${detail}` : ''}`);
+    }
+    for (const advisory of advisories) out(`advisory: ${advisory}`);
+    if (counts) out(Object.entries(counts).map(([key, value]) => `${key}=${value}`).join(' '));
+  }
+
+  // Only a validated slug is a feature slug; an invalid record's slug can hold anything (C-1, IC-004).
+  const task = valid && record && typeof record.slug === 'string' ? record.slug : null;
+  const telemetryRecord               = {
+    kind: 'review.run',
+    task,
+    depth: null,
+    risk: null,
+    protocol: null,
+    head: null,
+    ...Object.fromEntries(TELEMETRY_COUNT_KEYS.map((key) => [key, null])),
+    advisories: advisories.length,
+    errors: errors.length,
+  };
+  if (counts && record) Object.assign(telemetryRecord, counts, { depth: record.depth ?? null, risk: record.risk ?? null, protocol: telemetryProtocol(record.protocol?.id), head: record.reviewedHead });
+  try { telemetryWriter.write([telemetryRecord]); } catch { /* telemetry never changes the check result */ }
+
+  return finishRuntime(valid ? 0 : 1);
+}
+
+module.exports = { handleReviewCommand };
+

package/src/runtime/review/dominance.js

@@ -0,0 +1,68 @@
+'use strict';
+
+// 122 IC-014: `dominates(P, B, context)`, the strictness comparison between two protocol presets. Pure:
+// no filesystem, no throw. P dominates B when every field that makes a review or debate stricter is at
+// least as strict in P. `context` carries the ordered core tiers (models.json `dispatchTiers.tiers`,
+// loosest first) and the synthesizer lattice (protocols.json `synthesizerStrength`). An unknown tier or
+// synthesizer has no rank and never dominates: no `indexOf` of -1 is read as a rank.
+
+const FAMILY_STRICTNESS                         = { any: 0, 'different-from-author': 1 };
+
+const isObject = (value     )          => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/** A rank from `ranks`, or null when `key` has none. */
+function rankOf(ranks                        , key     )                {
+  return typeof key === 'string' && Object.hasOwn(ranks, key) && Number.isInteger(ranks[key]) ? ranks[key] : null;
+}
+
+/** True when seat `p` covers seat `b`: a lens superset, a family at least as strict, a tier at least as high. */
+function seatCovers(p     , b     , tierRank                        )          {
+  if (!isObject(p) || !isObject(b) || !isObject(p.model) || !isObject(b.model)) return false;
+  const pLenses = new Set(Array.isArray(p.lenses) ? p.lenses : []);
+  if (!(Array.isArray(b.lenses) ? b.lenses : []).every((lens     ) => pLenses.has(lens))) return false;
+  const pFamily = rankOf(FAMILY_STRICTNESS, p.model.family ?? 'any');
+  const bFamily = rankOf(FAMILY_STRICTNESS, b.model.family ?? 'any');
+  if (pFamily === null || bFamily === null || pFamily < bFamily) return false;
+  const pTier = rankOf(tierRank, p.model.tier);
+  const bTier = rankOf(tierRank, b.model.tier);
+  return pTier !== null && bTier !== null && pTier >= bTier;
+}
+
+/**
+ * True when every B seat maps to a distinct P seat that covers it: a maximum bipartite matching by
+ * augmenting paths (Kuhn), so a first-fit choice never hides a matching that exists. Seats are few.
+ */
+function seatsMatch(pSeats       , bSeats       , tierRank                        )          {
+  if (bSeats.length > pSeats.length) return false;
+  const covers = bSeats.map((b) => pSeats.map((p) => seatCovers(p, b, tierRank)));
+  const owner           = new Array(pSeats.length).fill(-1); // P seat index -> B seat index
+  const augment = (bi        , seen           )          => {
+    for (let pi = 0; pi < pSeats.length; pi++) {
+      if (!covers[bi][pi] || seen[pi]) continue;
+      seen[pi] = true;
+      if (owner[pi] === -1 || augment(owner[pi], seen)) { owner[pi] = bi; return true; }
+    }
+    return false;
+  };
+  return bSeats.every((_, bi) => augment(bi, new Array(pSeats.length).fill(false)));
+}
+
+function dominates(P     , B     , context      = {})          {
+  if (!isObject(P) || !isObject(B) || !isObject(context)) return false;
+  const { tiers, synthesizerStrength } = context;
+  if (!Array.isArray(tiers) || !isObject(synthesizerStrength)) return false;
+  const tierRank                         = Object.fromEntries(tiers.map((tier        , i        ) => [tier, i]));
+
+  if (P.kind !== B.kind || P.decider !== B.decider) return false;
+  if (!Array.isArray(P.seats) || !Array.isArray(B.seats) || !seatsMatch(P.seats, B.seats, tierRank)) return false;
+  if (!isObject(P.rounds) || !isObject(B.rounds)) return false;
+  for (const field of ['default', 'min']) {
+    if (!Number.isInteger(P.rounds[field]) || !Number.isInteger(B.rounds[field]) || P.rounds[field] < B.rounds[field]) return false;
+  }
+  if (B.crossAnswer === true && P.crossAnswer !== true) return false;
+  const pSynth = rankOf(synthesizerStrength, P.synthesizer);
+  const bSynth = rankOf(synthesizerStrength, B.synthesizer);
+  return pSynth !== null && bSynth !== null && pSynth >= bSynth;
+}
+
+module.exports = { dominates };