feat: add proactive report gate lock evaluator

scripts/proactive_report_gate_lock.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+
+const LEGAL_FALLBACK_STATES = new Set(['paused', 'blocked', 'waiting_user', 'pending_verification']);
+const LEGAL_REPORT_MODES = new Set(['checkpoint_only', 'watchdog', 'button_path', 'direct_update']);
+
+function fail(code, message) {
+  process.stderr.write(`${code}: ${message}\n`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const args = { input: '', pretty: true };
+  for (let i = 2; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--input') {
+      const value = argv[i + 1];
+      if (!value || value.startsWith('--')) fail('CLI_ERROR', '--input requires a value');
+      args.input = value;
+      i += 1;
+    } else if (arg === '--compact') {
+      args.pretty = false;
+    } else {
+      fail('CLI_ERROR', `unknown argument: ${arg}`);
+    }
+  }
+  return args;
+}
+
+function readInput(inputPath) {
+  if (!inputPath || inputPath === '-') return fs.readFileSync(0, 'utf8');
+  return fs.readFileSync(inputPath, 'utf8');
+}
+
+function parseJson(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    fail('INVALID_JSON', 'input must be valid JSON');
+  }
+}
+
+function hasNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function isLongTask(input) {
+  return input?.classification === 'long_task';
+}
+
+function isSilentProgressionCandidate(input) {
+  if (typeof input?.silentContinuation === 'boolean') return input.silentContinuation;
+  if (typeof input?.silentCandidate === 'boolean') return input.silentCandidate;
+  if (input?.needsWaiting === true) return true;
+  if (input?.needsSubagent === true) return true;
+  return false;
+}
+
+function hasCheckpointOnlyEvidence(input) {
+  return hasNonEmptyString(input?.externalizedCheckpointPath) || hasNonEmptyString(input?.checkpointTrigger);
+}
+
+function isLegalFallbackState(value) {
+  return hasNonEmptyString(value) && LEGAL_FALLBACK_STATES.has(value.trim());
+}
+
+function isLegalReportMode(value) {
+  return hasNonEmptyString(value) && LEGAL_REPORT_MODES.has(value.trim());
+}
+
+function addRequiredEvidence(requiredEvidence, evidenceKey, acceptedFields, requiredValue) {
+  requiredEvidence.push({ evidenceKey, acceptedFields, requiredValue });
+}
+
+function evaluateGate(input) {
+  const reasons = [];
+  const requiredEvidence = [];
+  const allowedResponseModes = [];
+
+  if (!isLongTask(input)) {
+    return {
+      gate: 'proactive_report_gate_lock',
+      gateRequired: false,
+      gateStatus: 'not_applicable',
+      ok: true,
+      reasons: ['classification is not long_task'],
+      requiredEvidence: [],
+      allowedResponseModes: ['direct_reply'],
+      reportBindingStatus: 'not_applicable',
+    };
+  }
+
+  if (!isSilentProgressionCandidate(input)) {
+    return {
+      gate: 'proactive_report_gate_lock',
+      gateRequired: false,
+      gateStatus: 'not_applicable',
+      ok: true,
+      reasons: ['not a silent progression candidate'],
+      requiredEvidence: [],
+      allowedResponseModes: ['direct_reply', 'non_silent_follow_up'],
+      reportBindingStatus: 'not_required',
+    };
+  }
+
+  const firstReportTriggerOk = hasNonEmptyString(input?.firstReportTrigger);
+  const nextReportConditionOk = hasNonEmptyString(input?.nextReportCondition);
+  const fallbackStateOk = isLegalFallbackState(input?.fallbackState);
+  const reportModeOk = !hasNonEmptyString(input?.reportMode) || isLegalReportMode(input?.reportMode);
+
+  if (!firstReportTriggerOk) {
+    reasons.push('missing first proactive report trigger');
+    addRequiredEvidence(requiredEvidence, 'firstReportTrigger', ['firstReportTrigger'], 'non-empty string');
+  }
+
+  if (!nextReportConditionOk) {
+    reasons.push('missing next proactive report condition');
+    addRequiredEvidence(requiredEvidence, 'nextReportCondition', ['nextReportCondition'], 'non-empty string');
+  }
+
+  if (!fallbackStateOk) {
+    reasons.push('missing fallback state for stalled reporting');
+    addRequiredEvidence(
+      requiredEvidence,
+      'fallbackState',
+      ['fallbackState'],
+      'one of paused | blocked | waiting_user | pending_verification',
+    );
+  }
+
+  if (!reportModeOk) {
+    reasons.push('invalid proactive report mode');
+    addRequiredEvidence(
+      requiredEvidence,
+      'reportMode',
+      ['reportMode'],
+      'one of checkpoint_only | watchdog | button_path | direct_update',
+    );
+  }
+
+  const missingCoreBinding = !firstReportTriggerOk || !nextReportConditionOk || !fallbackStateOk;
+  if (missingCoreBinding && hasCheckpointOnlyEvidence(input)) {
+    reasons.push('checkpoint path alone does not satisfy proactive report binding');
+  }
+
+  if (input?.needsOwnerDecision === true && input?.handoffMode !== 'button_path') {
+    reasons.push('owner decision flow must preserve button-path handoff');
+    addRequiredEvidence(requiredEvidence, 'handoffMode', ['handoffMode'], 'button_path');
+  }
+
+  if (requiredEvidence.length > 0) {
+    allowedResponseModes.push('non_silent_follow_up');
+    if (input?.needsOwnerDecision === true) allowedResponseModes.push('button_path');
+
+    return {
+      gate: 'proactive_report_gate_lock',
+      gateRequired: true,
+      gateStatus: 'fail',
+      ok: false,
+      reasons,
+      requiredEvidence,
+      allowedResponseModes,
+      reportBindingStatus: 'missing',
+    };
+  }
+
+  if (input?.needsOwnerDecision === true && input?.handoffMode === 'button_path') {
+    reasons.push('owner decision flow preserves button-path handoff');
+    allowedResponseModes.push('button_path');
+  } else {
+    reasons.push('proactive report binding is complete for silent progression');
+    allowedResponseModes.push('silent_continuation');
+    allowedResponseModes.push('direct_reply');
+  }
+
+  return {
+    gate: 'proactive_report_gate_lock',
+    gateRequired: true,
+    gateStatus: 'pass',
+    ok: true,
+    reasons,
+    requiredEvidence: [],
+    allowedResponseModes,
+    reportBindingStatus: 'bound',
+  };
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const raw = readInput(args.input);
+  const input = parseJson(raw);
+  const output = evaluateGate(input);
+  process.stdout.write(`${JSON.stringify(output, null, args.pretty ? 2 : 0)}\n`);
+}
+
+const isMain = import.meta.url === new URL(`file://${process.argv[1]}`).href;
+if (isMain) {
+  main();
+}
+
+export { evaluateGate };