dw-kit 1.9.2 → 1.10.0

package/src/lib/trust.mjs

@@ -0,0 +1,139 @@
+// Trust Mode gate-resolution logic (ADR-0022).
+//
+// `dw:flow` human gates fall into two classes. Trust Mode may auto-approve the
+// *convenience* gates (reversible review of intent/output) when the user opts
+// in; it can NEVER relax the *safety* gates (irreversible / unsafe). This module
+// is the single source of truth for that taxonomy, so the skill, the CLI, and
+// the tests all agree on what is and isn't relaxable.
+
+import { getTrustConfig } from './config.mjs';
+import { logGoalEvent } from './goal-events.mjs';
+
+// Canonical gate ids and their class. Gate ids are the stable contract the
+// skill passes in (mapped from GATE A/B/C/D and the quick-depth Q1/Q2).
+export const GATES = {
+  scope: { class: 'convenience', maps: 'GATE A / Q1', configKey: 'scope' },
+  plan: { class: 'convenience', maps: 'GATE C', configKey: 'plan' },
+  changes: { class: 'convenience', maps: 'GATE D / Q2', configKey: 'changes' },
+  arch: { class: 'safety', maps: 'GATE B (TL architecture sign-off)', configKey: null },
+};
+
+/**
+ * Normalize a one-shot `--trust` flag into a predicate over gate ids.
+ * Accepts:
+ *   true            → trust every convenience gate this run
+ *   "plan"          → trust only that gate
+ *   "scope,plan"    → trust those gates
+ *   ["scope","plan"]→ same
+ *   undefined/false → no one-shot trust
+ */
+export function parseTrustFlag(flag) {
+  if (flag === true) return { all: true, gates: new Set() };
+  if (!flag) return { all: false, gates: new Set() };
+  // CLI passes strings; treat "true"/"all" (the bare `--trust`) as "every convenience gate".
+  const raw = Array.isArray(flag) ? flag : String(flag).split(',');
+  const gates = new Set(raw.map((g) => g.trim().toLowerCase()).filter(Boolean));
+  if (gates.has('true') || gates.has('all')) return { all: true, gates: new Set() };
+  return { all: false, gates };
+}
+
+/**
+ * Decide whether a single gate may be auto-approved.
+ *
+ * @param {object} params
+ * @param {string} params.gate        canonical gate id (see GATES)
+ * @param {object} params.config      loaded dw config (for workflow.trust)
+ * @param {*}      [params.flag]       one-shot `--trust` flag value (this run)
+ * @param {boolean}[params.hasCritical] true when a Critical review finding exists (GATE D)
+ * @param {object} [params.evidence]   EVD verify (ADR-0023): {tests:{exit},review:{critical}} — when
+ *                                     present, criticality/red-tests are derived from the evidence
+ *                                     itself, not just the caller's flag.
+ * @returns {{ autoApprove: boolean, reason: string, gateClass: string }}
+ */
+export function resolveGate({ gate, config, flag, hasCritical = false, evidence, runCount } = {}) {
+  const meta = GATES[gate];
+  if (!meta) {
+    return { autoApprove: false, reason: `unknown gate "${gate}" — manual`, gateClass: 'unknown' };
+  }
+
+  // Invariant: safety hard-stops are structurally unreachable by Trust Mode.
+  if (meta.class === 'safety') {
+    return {
+      autoApprove: false,
+      reason: `safety gate (${meta.maps}) — never auto-approved`,
+      gateClass: 'safety',
+    };
+  }
+
+  // EVD verify (ADR-0023): when evidence is supplied for GATE D, derive the
+  // safety signals from the evidence — stronger than a bare --critical flag the
+  // caller might forget. Evidence that shows a Critical finding or red tests
+  // forces a manual stop even when `changes` is trusted.
+  const criticalFromEvidence = gate === 'changes' && evidence?.review && Number(evidence.review.critical) >= 1;
+  // Only treat tests as failed when a real exit code is present and non-zero.
+  // A `tests` object without `exit` must NOT block (round-2 verify: false positive).
+  const exitCode = Number(evidence?.tests?.exit);
+  const testsFailedFromEvidence = gate === 'changes' && evidence?.tests && Number.isFinite(exitCode) && exitCode !== 0;
+
+  // Invariant: a Critical review finding forces GATE D to a manual stop even
+  // when `changes` is trusted.
+  if (gate === 'changes' && (hasCritical || criticalFromEvidence)) {
+    return {
+      autoApprove: false,
+      reason: 'Critical review finding — manual approval required',
+      gateClass: 'convenience',
+    };
+  }
+  if (testsFailedFromEvidence) {
+    return {
+      autoApprove: false,
+      reason: `tests not green (exit ${evidence.tests.exit}) — manual approval required`,
+      gateClass: 'convenience',
+    };
+  }
+
+  const trust = getTrustConfig(config);
+
+  // require_evidence (ADR-0023 follow-up): when set, GATE D will not auto-approve
+  // without an evidence object citing a REAL numeric review.critical count — an
+  // empty {review:{}} must NOT satisfy it (round-3 verify: bypass via empty object).
+  // Require a real numeric critical count — a boolean `false` or `[]` both coerce
+  // to 0 via Number(), so check the type, not just finiteness (final verify).
+  const hasReviewCount = typeof evidence?.review?.critical === 'number'
+    && Number.isFinite(evidence.review.critical);
+  if (gate === 'changes' && trust.require_evidence && !hasReviewCount) {
+    return {
+      autoApprove: false,
+      reason: 'workflow.trust.require_evidence — supply --evidence with a numeric review.critical count',
+      gateClass: 'convenience',
+    };
+  }
+
+  const oneShot = parseTrustFlag(flag);
+  if (oneShot.all || oneShot.gates.has(gate)) {
+    return { autoApprove: true, reason: `--trust (this run): ${meta.maps}`, gateClass: 'convenience' };
+  }
+
+  if (trust.enabled && trust.auto_approve[meta.configKey]) {
+    // Budget: once an unattended run reaches its cap, stop auto-approving so the
+    // bound is real at the decision point, not just advisory (round-2 verify: W-3).
+    if (trust.max_auto_subtasks > 0 && Number.isInteger(runCount) && runCount >= trust.max_auto_subtasks) {
+      return { autoApprove: false, reason: `budget reached (${runCount}/${trust.max_auto_subtasks} auto-approved) — manual`, gateClass: 'convenience' };
+    }
+    return { autoApprove: true, reason: `workflow.trust.auto_approve.${meta.configKey}`, gateClass: 'convenience' };
+  }
+
+  // Invariant: default is fully manual.
+  return { autoApprove: false, reason: 'manual (Trust Mode off for this gate)', gateClass: 'convenience' };
+}
+
+/**
+ * Audit an auto-approval to .dw/events-global.jsonl so the skipped human is
+ * always recoverable. Invariant 4 of ADR-0022.
+ */
+export function logTrustEvent({ gate, task, reason, evidence }, rootDir = process.cwd()) {
+  return logGoalEvent(
+    { event: 'gate_auto_approved', actor: 'trust-mode', gate, task: task || null, reason: reason || null, evidence: evidence || null },
+    rootDir,
+  );
+}