@polymorphism-tech/morph-spec 7.2.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

@@ -1,136 +1,241 @@
-#!/usr/bin/env node
-
-/**
- * Stop Hook: Phase Transition Alert + Build Check + Session Snapshot
- *
- * Event: Stop
- *
- * 1. Detects transitions into the `implement` phase and recommends /compact.
- * 2. Runs stack-aware build check — warns only on failure (silent on pass).
- * 3. Saves session snapshot for next-session orientation.
- *
- * Phase transition tracking: stores last-seen phase per feature in
- * .morph/memory/phase-watch.json so the alert fires exactly once.
- *
- * Fail-open: exits 0 on any error.
- */
-
-import { readFileSync, writeFileSync, existsSync } from 'fs';
-import { join } from 'path';
-import { runBuildCheck } from '../../shared/build-check.js';
-import { saveSessionSnapshot } from '../../shared/session-snapshot.js';
-import {
-  stateExists, getActiveFeature, getMostRecentFeature, derivePhaseForFeature,
-} from '../../shared/state-reader.js';
-import { injectContext, pass } from '../../shared/hook-response.js';
-import { logHookActivity, logEvent } from '../../shared/activity-logger.js';
-
-// Phases where compaction is strongly recommended before starting
-const COMPACT_TRIGGER_PHASES = new Set(['implement']);
-
-// Phases where compaction is suggested when arriving (heavy spec phases)
-const HEAVY_SOURCE_PHASES = new Set(['plan', 'uiux']);
-
-try {
-  // Prevent infinite loop
-  if (process.env.MORPH_STOP_HOOK_ACTIVE === '1') pass();
-
-  if (!stateExists()) pass();
-
-  // getActiveFeature() only returns in_progress/draft features.
-  // Fall back to the most recently updated feature when all features are 'done'.
-  let active = getActiveFeature() || getMostRecentFeature();
-  if (!active) pass();
-
-  const { name, feature } = active;
-  const cwd  = process.cwd();
-  const warnings = [];
-
-  // ── Phase transition detection ────────────────────────────────────────────
-  const currentPhase = feature.phase || derivePhaseForFeature(name, cwd);
-
-  const watchPath = join(cwd, '.morph', 'memory', 'phase-watch.json');
-  let phaseWatch  = {};
-  try {
-    if (existsSync(watchPath)) phaseWatch = JSON.parse(readFileSync(watchPath, 'utf-8'));
-  } catch { /* corrupt file — start fresh */ }
-
-  const lastPhase = phaseWatch[name];
-
-  // Update stored phase (always, so the alert only fires once per transition)
-  try {
-    phaseWatch[name] = currentPhase;
-    writeFileSync(watchPath, JSON.stringify(phaseWatch, null, 2), 'utf-8');
-  } catch { /* non-blocking */ }
-
-  // Alert when entering implement from a heavy spec phase
-  const isPhaseTransition = lastPhase && lastPhase !== currentPhase;
-  const enteringImplement = COMPACT_TRIGGER_PHASES.has(currentPhase);
-  const comingFromHeavyPhase = HEAVY_SOURCE_PHASES.has(lastPhase);
-
-  if (isPhaseTransition && enteringImplement && comingFromHeavyPhase) {
-    warnings.push(
-      `⚡ Phase advanced: ${lastPhase} → implement`,
-      ``,
-      `💡 Recommended before starting implementation:`,
-      `   Run /compact to free up context — spec.md, mandate.md and tasks.md`,
-      `   loaded during planning take significant space. A compact now gives`,
-      `   Claude a clean slate focused on writing code.`,
-      ``,
-      `   After /compact, resume with: /morph-apply ${name}`,
-    );
-  }
-
-  // ── Build/typecheck verification ──────────────────────────────────────────
-  // Stack-aware build check — advisory warning if build fails.
-  // Success is silent (no output on pass).
-  try {
-    const configPath = join(cwd, '.morph', 'config', 'config.json');
-    if (existsSync(configPath)) {
-      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
-      const stack = config?.project?.stack;
-      if (stack && currentPhase === 'implement') {
-        const buildResult = runBuildCheck(cwd, stack);
-        if (buildResult.status === 'fail') {
-          warnings.push('⚠ Build/typecheck failed:');
-          warnings.push(buildResult.output);
-          warnings.push('Fix build errors before ending session.');
-        }
-        // pass and skip → silent (success is silent)
-      }
-    }
-  } catch {
-    // Fail-open — build check must never block Stop
-  }
-  // ────────────────────────────────────────────────────────────────────────
-
-  // ── Session snapshot ──────────────────────────────────────────────────────
-  // Save session state for next session's "getting up to speed" routine.
-  try {
-    if (active) {
-      const { name } = active;
-      saveSessionSnapshot({
-        feature: name,
-        phase: currentPhase,
-        buildStatus: 'skip',
-        lastEditedFiles: [],
-      }, cwd);
-    }
-  } catch {
-    // Fail-open — snapshot save must never block Stop
-  }
-  // ────────────────────────────────────────────────────────────────────────
-
-  if (warnings.length === 0) pass();
-
-  const message = [
-    'MORPH-SPEC:',
-    ...warnings.map(w => `  ${w}`),
-  ].join('\n');
-
-  logHookActivity('validate-completion', 'Stop', `warnings(${warnings.length})`);
-  logEvent('session_end', { feature: name, phase: currentPhase, warnings: warnings.length });
-  injectContext(message);
-} catch {
-  process.exit(0);
-}
+#!/usr/bin/env node
+
+/**
+ * Stop Hook: Phase Transition Alert + Build Check + Session Snapshot
+ *
+ * Event: Stop
+ *
+ * 1. Detects transitions into the `implement` phase and recommends /compact.
+ * 2. Runs stack-aware build check — warns only on failure (silent on pass).
+ * 3. Saves session snapshot for next-session orientation.
+ *
+ * Phase transition tracking: stores last-seen phase per feature in
+ * .morph/memory/phase-watch.json so the alert fires exactly once.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { runBuildCheck } from '../../shared/build-check.js';
+import { saveSessionSnapshot } from '../../shared/session-snapshot.js';
+import {
+  stateExists, getActiveFeature, getMostRecentFeature, derivePhaseForFeature,
+} from '../../shared/state-reader.js';
+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']);
+
+// Phases where compaction is suggested when arriving (heavy spec phases)
+const HEAVY_SOURCE_PHASES = new Set(['plan', 'uiux']);
+
+try {
+  // Prevent infinite loop
+  if (process.env.MORPH_STOP_HOOK_ACTIVE === '1') pass();
+
+  if (!stateExists()) pass();
+
+  // getActiveFeature() only returns in_progress/draft features.
+  // Fall back to the most recently updated feature when all features are 'done'.
+  let active = getActiveFeature() || getMostRecentFeature();
+  if (!active) pass();
+
+  const { name, feature } = active;
+  const cwd  = process.cwd();
+  const warnings = [];
+
+  // ── Phase transition detection ────────────────────────────────────────────
+  const currentPhase = feature.phase || derivePhaseForFeature(name, cwd);
+
+  const watchPath = join(cwd, '.morph', 'memory', 'phase-watch.json');
+  let phaseWatch  = {};
+  try {
+    if (existsSync(watchPath)) phaseWatch = JSON.parse(readFileSync(watchPath, 'utf-8'));
+  } catch { /* corrupt file — start fresh */ }
+
+  const lastPhase = phaseWatch[name];
+
+  // Update stored phase (always, so the alert only fires once per transition)
+  try {
+    phaseWatch[name] = currentPhase;
+    writeFileSync(watchPath, JSON.stringify(phaseWatch, null, 2), 'utf-8');
+  } catch { /* non-blocking */ }
+
+  // Alert when entering implement from a heavy spec phase
+  const isPhaseTransition = lastPhase && lastPhase !== currentPhase;
+  const enteringImplement = COMPACT_TRIGGER_PHASES.has(currentPhase);
+  const comingFromHeavyPhase = HEAVY_SOURCE_PHASES.has(lastPhase);
+
+  if (isPhaseTransition && enteringImplement && comingFromHeavyPhase) {
+    warnings.push(
+      `⚡ Phase advanced: ${lastPhase} → implement`,
+      ``,
+      `💡 Recommended before starting implementation:`,
+      `   Run /compact to free up context — spec.md, mandate.md and tasks.json`,
+      `   loaded during planning take significant space. A compact now gives`,
+      `   Claude a clean slate focused on writing code.`,
+      ``,
+      `   After /compact, resume with: /morph-apply ${name}`,
+    );
+  }
+
+  // ── Build/typecheck verification ──────────────────────────────────────────
+  // Stack-aware build check — advisory warning if build fails.
+  // Success is silent (no output on pass).
+  try {
+    const configPath = join(cwd, '.morph', 'config', 'config.json');
+    if (existsSync(configPath)) {
+      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+      const stack = config?.project?.stack;
+      if (stack && currentPhase === 'implement') {
+        const buildResult = runBuildCheck(cwd, stack);
+        if (buildResult.status === 'fail') {
+          warnings.push('⚠ Build/typecheck failed:');
+          warnings.push(buildResult.output);
+          warnings.push('Fix build errors before ending session.');
+        }
+        // pass and skip → silent (success is silent)
+      }
+    }
+  } catch {
+    // Fail-open — build check must never block Stop
+  }
+  // ────────────────────────────────────────────────────────────────────────
+
+  // ── 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 {
+    if (active) {
+      const { name } = active;
+      saveSessionSnapshot({
+        feature: name,
+        phase: currentPhase,
+        buildStatus: 'skip',
+        lastEditedFiles: [],
+      }, cwd);
+    }
+  } catch {
+    // Fail-open — snapshot save must never block Stop
+  }
+  // ────────────────────────────────────────────────────────────────────────
+
+  if (warnings.length === 0) pass();
+
+  const message = [
+    'MORPH-SPEC:',
+    ...warnings.map(w => `  ${w}`),
+  ].join('\n');
+
+  logHookActivity('validate-completion', 'Stop', `warnings(${warnings.length})`);
+  logEvent('session_end', { feature: name, phase: currentPhase, warnings: warnings.length });
+  injectContext(message);
+} catch {
+  process.exit(0);
+}