@polymorphism-tech/morph-spec 7.3.0 → 7.4.0

package/framework/hooks/claude-code/core/gate-guard.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * gate-guard.js — PostToolUse hook (detect-and-warn, never block)
+ *
+ * Closes the gap from issue #63: the trust-mode contract lived only in skill
+ * pseudocode, with nothing verifying the LLM actually honored it. This hook
+ * compares the OBSERVED gate action against the decision the skill persisted
+ * to state.json (`features[feature].gateDecisions[gate]`) and injects a
+ * non-blocking warning when they disagree.
+ *
+ * It is a silent guardrail, NOT an orchestrator (per MORPH.md): it never
+ * blocks, never writes state, and fails open on any error or missing data.
+ *
+ * Two mismatch directions:
+ *  - LLM PAUSED (AskUserQuestion on a gate) but the persisted decision said
+ *    pause:false  → over-pausing under trust:auto. Warn.
+ *  - LLM AUTO-APPROVED (gate became approvedBy:"auto") but the persisted
+ *    decision said pause:true → skipped a required human pause. Warn.
+ *
+ * Coherent action, no persisted decision, or any error → silence.
+ */
+
+import { readFileSync } from 'fs';
+import { loadState, stateExists } from '../../shared/state-reader.js';
+import { injectContext, pass } from '../../shared/hook-response.js';
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8') || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function projectDir() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function findActiveFeature(state) {
+  if (!state.features) return null;
+  const entries = Object.entries(state.features);
+  const active = entries.find(([, f]) => f.status === 'in_progress');
+  if (active) return active[0];
+  return entries[0]?.[0] ?? null;
+}
+
+/** Map a gate question's text to a gate id. Mirrors state-sync.js. */
+function gateFromQuestion(question) {
+  if (typeof question !== 'string') return null;
+  const lower = question.toLowerCase();
+  if (lower.includes('gate 1') || lower.includes('proposta')) return 'proposal';
+  if (lower.includes('gate 2') || lower.includes('plano') || lower.includes('plan')) return 'plan';
+  if (lower.includes('gate 3') || lower.includes('review')) return 'review';
+  return null;
+}
+
+function getDecision(state, feature, gate) {
+  const d = state.features?.[feature]?.gateDecisions?.[gate];
+  if (!d || typeof d.pause !== 'boolean') return null;
+  return d;
+}
+
+/**
+ * The LLM just asked a gate question. If the persisted decision said this
+ * gate should auto-pass (pause:false), the human was interrupted needlessly.
+ */
+function checkAskUserQuestion(input, state, feature) {
+  // Questions live in tool_input.questions[]; answers in tool_response.
+  const questions = input.tool_input?.questions;
+  const askedTexts = [];
+  if (Array.isArray(questions)) {
+    for (const q of questions) {
+      if (typeof q?.question === 'string') askedTexts.push(q.question);
+      if (typeof q?.header === 'string') askedTexts.push(q.header);
+    }
+  }
+  // Fallback: some payloads only surface answered question keys.
+  const answers = input.tool_response?.answers ?? input.tool_response?.responses;
+  if (answers && typeof answers === 'object') {
+    askedTexts.push(...Object.keys(answers));
+  }
+
+  for (const text of askedTexts) {
+    const gate = gateFromQuestion(text);
+    if (!gate) continue;
+    const decision = getDecision(state, feature, gate);
+    if (!decision) continue; // no persisted decision → nothing to verify
+    if (decision.pause === false) {
+      return injectContext(
+        `⚠️ [morph-spec] GATE OVER-PAUSE — você apresentou o Gate "${gate}" via AskUserQuestion, ` +
+        `mas a decisão registrada em state.json (gateDecisions.${gate}) era pause:false ` +
+        `(trust:${decision.trust ?? 'auto'}, nenhum sinal de risco). ` +
+        `Sob trust:auto sem risco, este gate deveria auto-passar com um summary curto, sem interromper o humano. ` +
+        `Se a pausa foi intencional (você detectou um risco que o registro não capturou), atualize gateDecisions.${gate}.signals antes de prosseguir; ` +
+        `caso contrário, evite pausar gates auto-aprováveis.`
+      );
+    }
+  }
+  return pass();
+}
+
+/**
+ * The LLM just edited state.json. If a gate flipped to approvedBy:"auto" but
+ * the persisted decision said pause:true, a required human pause was skipped.
+ */
+function checkStateEdit(input, state, feature) {
+  const filePath = String(input.tool_input?.file_path ?? '').replace(/\\/g, '/');
+  if (!filePath.endsWith('.morph/state.json')) return pass();
+
+  const gates = state.features?.[feature]?.approvalGates ?? {};
+  for (const gate of ['proposal', 'plan', 'review']) {
+    const g = gates[gate];
+    const autoApproved = g?.approved === true && g?.approvedBy === 'auto';
+    if (!autoApproved) continue;
+    const decision = getDecision(state, feature, gate);
+    if (!decision) continue;
+    if (decision.pause === true) {
+      return injectContext(
+        `⚠️ [morph-spec] GATE SKIPPED PAUSE — o Gate "${gate}" foi marcado approvedBy:"auto" em state.json, ` +
+        `mas a decisão registrada (gateDecisions.${gate}) era pause:true ` +
+        `(sinal: ${decision.reason || 'risco detectado'}). ` +
+        `Um sinal de risco exigia pausa humana via AskUserQuestion — uma auto-aprovação aqui ignora o trust mode. ` +
+        `Reabra o gate com AskUserQuestion (label "aprovado, prosseguir") ou corrija o sinal de risco antes de avançar.`
+      );
+    }
+  }
+  return pass();
+}
+
+function main() {
+  const cwd = projectDir();
+  if (!stateExists(cwd)) return pass();
+
+  const input = readStdin();
+  const toolName = input.tool_name;
+
+  // Short-circuit before loading state: a Write/Edit only matters if it touched
+  // state.json. Skip the disk read for the dozens of unrelated edits per feature.
+  if (toolName === 'Edit' || toolName === 'Write') {
+    const fp = String(input.tool_input?.file_path ?? '').replace(/\\/g, '/');
+    if (!fp.endsWith('.morph/state.json')) return pass();
+  } else if (toolName !== 'AskUserQuestion') {
+    return pass();
+  }
+
+  try {
+    const state = loadState(cwd);
+    if (!state) return pass();
+    const feature = findActiveFeature(state);
+    if (!feature) return pass();
+
+    if (toolName === 'AskUserQuestion') return checkAskUserQuestion(input, state, feature);
+    if (toolName === 'Edit' || toolName === 'Write') return checkStateEdit(input, state, feature);
+  } catch {
+    // fail-open
+  }
+  return pass();
+}
+
+main();

package/framework/hooks/claude-code/core/state-sync.js

@@ -173,9 +173,21 @@ function handleAskUserQuestion(input, cwd) {
     if (!gate) continue;
 
     state.features[featureName].approvalGates ??= {};
-    if (state.features[featureName].approvalGates[gate] !== true) {
-      state.features[featureName].approvalGates[gate] = true;
-      state.features[featureName].updatedAt = new Date().toISOString();
+    const existing = state.features[featureName].approvalGates[gate];
+    const alreadyApproved = existing === true || existing?.approved === true;
+    if (!alreadyApproved) {
+      // An "aprovado" answer to AskUserQuestion is a human approving in the
+      // loop — record it as such. Write the canonical gate shape
+      // ({ approved, timestamp, approvedBy }) used by setApprovalGate so the
+      // audit trail is consistent and a manual approval is distinguishable
+      // from a policy auto-approval (approvedBy: "auto").
+      const now = new Date().toISOString();
+      state.features[featureName].approvalGates[gate] = {
+        approved: true,
+        timestamp: now,
+        approvedBy: 'manual'
+      };
+      state.features[featureName].updatedAt = now;
       changed = true;
     }
   }

package/framework/hooks/claude-code/core/validate-completion.js

@@ -25,6 +25,96 @@ import {
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { logHookActivity, logEvent } from '../../shared/activity-logger.js';
 
+/**
+ * Audit recap.md against tasks.json + standard-citation rule.
+ *
+ * Returns an array of human-readable warnings. Empty array = audit clean.
+ *
+ * Two checks:
+ *   1. Task IDs that appear as a "## T<n>" heading in recap.md but still
+ *      carry status != 'done' in tasks.json — claim/state divergence.
+ *   2. Task headings without a "**Standard:**" line nearby (within 10 lines
+ *      after the heading) — no standard citation = unauditable decision.
+ */
+function auditRecapAndTasks(featurePath) {
+  const warnings = [];
+  const recapPath = join(featurePath, '3-implement', 'recap.md');
+  const tasksJsonPath = join(featurePath, '2-plan', 'tasks.json');
+  if (!existsSync(recapPath) || !existsSync(tasksJsonPath)) return warnings;
+
+  let recap, tasksJson;
+  try {
+    recap = readFileSync(recapPath, 'utf-8');
+    tasksJson = JSON.parse(readFileSync(tasksJsonPath, 'utf-8'));
+  } catch {
+    return warnings;
+  }
+
+  const tasks = Array.isArray(tasksJson.tasks) ? tasksJson.tasks : [];
+  if (tasks.length === 0) return warnings;
+
+  // Index recap by task ID — collect line numbers where each task is mentioned
+  // as completed. Supports two formats agents commonly use:
+  //   (a) "## T<n>"           — heading style (per the SKILL.md template)
+  //   (b) "| T<n> | ... done" — markdown table row with done in same row
+  const lines = recap.split('\n');
+  const recapMentions = new Map(); // id → starting line index
+  const headingRe = /^##\s+(T\d+)\b/;
+  const tableRowRe = /^\|\s*(T\d+)\s*\|.*\bdone\b/i;
+  lines.forEach((ln, i) => {
+    const heading = ln.match(headingRe);
+    if (heading && !recapMentions.has(heading[1])) {
+      recapMentions.set(heading[1], i);
+      return;
+    }
+    const tableRow = ln.match(tableRowRe);
+    if (tableRow && !recapMentions.has(tableRow[1])) {
+      recapMentions.set(tableRow[1], i);
+    }
+  });
+
+  // Check 1: status drift — task mentioned as done in recap but tasks.json
+  // still shows it as pending/in_progress.
+  for (const t of tasks) {
+    if (recapMentions.has(t.id) && t.status !== 'done') {
+      warnings.push(
+        `tasks.json drift: ${t.id} appears as done in recap.md but tasks.json shows status="${t.status}". Run writeTasksJson to sync.`
+      );
+    }
+  }
+
+  // Check 2: missing Standard citation per task mention. Skip pure
+  // table-row mentions (they're a summary, the heading-style block
+  // is where the standard belongs) — only flag when the agent did
+  // not produce a heading block at all for a task that is also marked
+  // done in tasks.json.
+  const standardRe = /\*\*Standard:\*\*|\bStandard\s*consulted\b|\bstandards?\s+used\b/i;
+  const headingMentions = new Map();
+  lines.forEach((ln, i) => {
+    const m = ln.match(headingRe);
+    if (m && !headingMentions.has(m[1])) headingMentions.set(m[1], i);
+  });
+  for (const t of tasks) {
+    if (t.status !== 'done') continue;
+    const lineIdx = headingMentions.get(t.id);
+    if (lineIdx === undefined) {
+      // Task is done but has no heading block at all — recap is summary-only.
+      warnings.push(
+        `recap.md task ${t.id} (status=done in tasks.json) has no detailed "## ${t.id}" block. Per morph-implement SKILL.md, each done task needs a heading block with a "**Standard:** ..." citation so the reviewer can audit the decision.`
+      );
+      continue;
+    }
+    const window = lines.slice(lineIdx, lineIdx + 12).join('\n');
+    if (!standardRe.test(window)) {
+      warnings.push(
+        `recap.md task ${t.id} is missing a "**Standard:** ..." citation within 12 lines of its heading. Cite which standard from STANDARDS.json justified the implementation (or "ad-hoc (see decisions.md ADR-N)" if intentional).`
+      );
+    }
+  }
+
+  return warnings;
+}
+
 // Phases where compaction is strongly recommended before starting
 const COMPACT_TRIGGER_PHASES = new Set(['implement']);
 
@@ -104,6 +194,21 @@ try {
   }
   // ────────────────────────────────────────────────────────────────────────
 
+  // ── Recap + tasks.json audit ──────────────────────────────────────────────
+  // Surface drift between recap.md and tasks.json, plus missing standard
+  // citations. Advisory warnings only — Stop hook never blocks.
+  try {
+    const featurePath = join(cwd, '.morph', 'features', name);
+    const recapWarnings = auditRecapAndTasks(featurePath);
+    if (recapWarnings.length > 0) {
+      warnings.push('📋 Recap audit:');
+      for (const w of recapWarnings) warnings.push(`  • ${w}`);
+    }
+  } catch {
+    // Fail-open — audit must never block Stop
+  }
+  // ────────────────────────────────────────────────────────────────────────
+
   // ── Session snapshot ──────────────────────────────────────────────────────
   // Save session state for next session's "getting up to speed" routine.
   try {