deepflow 0.1.87 → 0.1.89

package/bin/install.js

@@ -187,7 +187,7 @@ async function main() {
   console.log('  skills/          — gap-discovery, atomic-commits, code-completeness, browse-fetch, browse-verify');
   console.log('  agents/          — reasoner (/df:auto — autonomous execution via /loop)');
   if (level === 'global') {
-    console.log('  hooks/           — statusline, update checker, invariant checker');
+    console.log('  hooks/           — statusline, update checker, invariant checker, worktree guard');
   }
   console.log('  hooks/df-spec-*  — spec validation (auto-enforced by /df:spec and /df:plan)');
   console.log('  env/             — ENABLE_LSP_TOOL (code navigation via goToDefinition, findReferences, workspaceSymbol)');
@@ -238,6 +238,11 @@ async function configureHooks(claudeDir) {
   const updateCheckCmd = `node "${path.join(claudeDir, 'hooks', 'df-check-update.js')}"`;
   const consolidationCheckCmd = `node "${path.join(claudeDir, 'hooks', 'df-consolidation-check.js')}"`;
   const quotaLoggerCmd = `node "${path.join(claudeDir, 'hooks', 'df-quota-logger.js')}"`;
+  const toolUsageCmd = `node "${path.join(claudeDir, 'hooks', 'df-tool-usage.js')}"`;
+  const dashboardPushCmd = `node "${path.join(claudeDir, 'hooks', 'df-dashboard-push.js')}"`;
+  const executionHistoryCmd = `node "${path.join(claudeDir, 'hooks', 'df-execution-history.js')}"`;
+  const worktreeGuardCmd = `node "${path.join(claudeDir, 'hooks', 'df-worktree-guard.js')}"`;
+  const invariantCheckCmd = `node "${path.join(claudeDir, 'hooks', 'df-invariant-check.js')}"`;
 
   let settings = {};
 
@@ -323,10 +328,10 @@ async function configureHooks(claudeDir) {
     settings.hooks.SessionEnd = [];
   }
 
-  // Remove any existing quota logger from SessionEnd
+  // Remove any existing quota logger / dashboard push from SessionEnd
   settings.hooks.SessionEnd = settings.hooks.SessionEnd.filter(hook => {
     const cmd = hook.hooks?.[0]?.command || '';
-    return !cmd.includes('df-quota-logger');
+    return !cmd.includes('df-quota-logger') && !cmd.includes('df-dashboard-push');
   });
 
   // Add quota logger to SessionEnd
@@ -336,7 +341,59 @@ async function configureHooks(claudeDir) {
       command: quotaLoggerCmd
     }]
   });
-  log('Quota logger configured');
+
+  // Add dashboard push to SessionEnd (fire-and-forget, skips when dashboard_url unset)
+  settings.hooks.SessionEnd.push({
+    hooks: [{
+      type: 'command',
+      command: dashboardPushCmd
+    }]
+  });
+  log('Quota logger + dashboard push configured (SessionEnd)');
+
+  // Configure PostToolUse hook for tool usage instrumentation
+  if (!settings.hooks.PostToolUse) {
+    settings.hooks.PostToolUse = [];
+  }
+
+  // Remove any existing deepflow tool usage / execution history / worktree guard / invariant check hooks from PostToolUse
+  settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(hook => {
+    const cmd = hook.hooks?.[0]?.command || '';
+    return !cmd.includes('df-tool-usage') && !cmd.includes('df-execution-history') && !cmd.includes('df-worktree-guard') && !cmd.includes('df-invariant-check');
+  });
+
+  // Add tool usage hook
+  settings.hooks.PostToolUse.push({
+    hooks: [{
+      type: 'command',
+      command: toolUsageCmd
+    }]
+  });
+
+  // Add execution history hook
+  settings.hooks.PostToolUse.push({
+    hooks: [{
+      type: 'command',
+      command: executionHistoryCmd
+    }]
+  });
+
+  // Add worktree guard hook (blocks Write/Edit to main-branch files when df/* worktree exists)
+  settings.hooks.PostToolUse.push({
+    hooks: [{
+      type: 'command',
+      command: worktreeGuardCmd
+    }]
+  });
+
+  // Add invariant check hook (exits 1 on hard failures after git commit)
+  settings.hooks.PostToolUse.push({
+    hooks: [{
+      type: 'command',
+      command: invariantCheckCmd
+    }]
+  });
+  log('PostToolUse hook configured');
 
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
 }
@@ -518,7 +575,7 @@ async function uninstall() {
   ];
 
   if (level === 'global') {
-    toRemove.push('hooks/df-statusline.js', 'hooks/df-check-update.js', 'hooks/df-consolidation-check.js', 'hooks/df-invariant-check.js', 'hooks/df-quota-logger.js');
+    toRemove.push('hooks/df-statusline.js', 'hooks/df-check-update.js', 'hooks/df-consolidation-check.js', 'hooks/df-invariant-check.js', 'hooks/df-quota-logger.js', 'hooks/df-tool-usage.js', 'hooks/df-dashboard-push.js', 'hooks/df-execution-history.js', 'hooks/df-worktree-guard.js');
   }
 
   for (const item of toRemove) {
@@ -556,17 +613,26 @@ async function uninstall() {
         if (settings.hooks?.SessionEnd) {
           settings.hooks.SessionEnd = settings.hooks.SessionEnd.filter(hook => {
             const cmd = hook.hooks?.[0]?.command || '';
-            return !cmd.includes('df-quota-logger');
+            return !cmd.includes('df-quota-logger') && !cmd.includes('df-dashboard-push');
           });
           if (settings.hooks.SessionEnd.length === 0) {
             delete settings.hooks.SessionEnd;
           }
         }
+        if (settings.hooks?.PostToolUse) {
+          settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(hook => {
+            const cmd = hook.hooks?.[0]?.command || '';
+            return !cmd.includes('df-tool-usage') && !cmd.includes('df-execution-history') && !cmd.includes('df-worktree-guard') && !cmd.includes('df-invariant-check');
+          });
+          if (settings.hooks.PostToolUse.length === 0) {
+            delete settings.hooks.PostToolUse;
+          }
+        }
         if (settings.hooks && Object.keys(settings.hooks).length === 0) {
           delete settings.hooks;
         }
         fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
-        console.log(`  ${c.green}✓${c.reset} Removed SessionStart/SessionEnd hooks`);
+        console.log(`  ${c.green}✓${c.reset} Removed SessionStart/SessionEnd/PostToolUse hooks`);
       } catch (e) {
         // Fail silently
       }

package/hooks/df-dashboard-push.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * deepflow dashboard push — SessionEnd hook
+ * Collects session summary (tokens, duration, tool calls, model), gets
+ * git user.name, and POSTs to dashboard_url from .deepflow/config.yaml.
+ * Silently skips if dashboard_url is not configured.
+ * Fire-and-forget: exits immediately after spawning background worker.
+ */
+
+'use strict';
+
+// Spawn background process so the hook returns immediately
+if (process.argv[2] !== '--background') {
+  const { spawn } = require('child_process');
+  const child = spawn(process.execPath, [__filename, '--background'], {
+    detached: true,
+    stdio: 'ignore',
+    // Pass stdin data through env so background process can read it
+    env: { ...process.env, _DF_HOOK_INPUT: getStdinSync() }
+  });
+  child.unref();
+  process.exit(0);
+}
+
+// --- Background process ---
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFileSync } = require('child_process');
+const https = require('https');
+const http = require('http');
+
+function getStdinSync() {
+  // Non-blocking stdin read for the parent process (limited buffer)
+  try {
+    return fs.readFileSync('/dev/stdin', { encoding: 'utf8', flag: 'rs' }) || '';
+  } catch (_e) {
+    return '';
+  }
+}
+
+/** Read .deepflow/config.yaml and extract dashboard_url (no yaml dep — regex parse). */
+function getDashboardUrl(cwd) {
+  const configPath = path.join(cwd, '.deepflow', 'config.yaml');
+  if (!fs.existsSync(configPath)) return null;
+  try {
+    const content = fs.readFileSync(configPath, 'utf8');
+    const match = content.match(/^\s*dashboard_url\s*:\s*(.+)$/m);
+    if (!match) return null;
+    const val = match[1].trim().replace(/^['"]|['"]$/g, '');
+    return val || null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+/** Get git user.name in the given directory. Returns 'unknown' on failure. */
+function getGitUser(cwd) {
+  try {
+    return execFileSync('git', ['config', 'user.name'], {
+      cwd,
+      encoding: 'utf8',
+      timeout: 3000,
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim() || 'unknown';
+  } catch (_e) {
+    return process.env.USER || 'unknown';
+  }
+}
+
+/** POST JSON payload to url. Returns true on 200. */
+function postJson(url, payload) {
+  return new Promise((resolve) => {
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch (_e) {
+      resolve(false);
+      return;
+    }
+
+    const body = JSON.stringify(payload);
+    const isHttps = parsed.protocol === 'https:';
+    const lib = isHttps ? https : http;
+
+    const options = {
+      hostname: parsed.hostname,
+      port: parsed.port || (isHttps ? 443 : 80),
+      path: parsed.pathname,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body)
+      },
+      timeout: 10000
+    };
+
+    const req = lib.request(options, (res) => {
+      res.resume();
+      res.on('end', () => resolve(res.statusCode === 200));
+    });
+
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+    req.write(body);
+    req.end();
+  });
+}
+
+async function main() {
+  try {
+    const cwd = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    const dashboardUrl = getDashboardUrl(cwd);
+
+    // Silently skip if not configured
+    if (!dashboardUrl) process.exit(0);
+
+    // Parse session data from hook input (passed via env)
+    let hookData = {};
+    try {
+      const raw = process.env._DF_HOOK_INPUT || '';
+      if (raw) hookData = JSON.parse(raw);
+    } catch (_e) {
+      // fallback: empty data, we'll still send what we know
+    }
+
+    const gitUser = getGitUser(cwd);
+    const projectName = path.basename(cwd);
+    const ts = new Date().toISOString();
+
+    // Extract token fields from hook data (Claude Code SessionEnd format)
+    const usage = hookData.usage || hookData.context_window?.current_usage || {};
+    const inputTokens = usage.input_tokens || 0;
+    const outputTokens = usage.output_tokens || 0;
+    const cacheReadTokens = usage.cache_read_input_tokens || usage.cache_read_tokens || 0;
+    const cacheCreationTokens = usage.cache_creation_input_tokens || usage.cache_creation_tokens || 0;
+    const model = hookData.model?.id || hookData.model?.display_name || hookData.model || 'unknown';
+    const sessionId = hookData.session_id || hookData.sessionId || `${gitUser}:${projectName}:${ts}`;
+    const durationMs = hookData.duration_ms || null;
+    const toolCalls = hookData.tool_calls || hookData.tool_use_count || 0;
+
+    const payload = {
+      user: gitUser,
+      project: projectName,
+      session_id: sessionId,
+      model,
+      tokens: {
+        [model]: {
+          input: inputTokens,
+          output: outputTokens,
+          cache_read: cacheReadTokens,
+          cache_creation: cacheCreationTokens
+        }
+      },
+      started_at: hookData.started_at || ts,
+      ended_at: ts,
+      duration_ms: durationMs,
+      tool_calls: toolCalls
+    };
+
+    const ingestUrl = dashboardUrl.replace(/\/$/, '') + '/api/ingest';
+    await postJson(ingestUrl, payload);
+  } catch (_e) {
+    // Never break session end
+  }
+  process.exit(0);
+}
+
+main();

package/hooks/df-execution-history.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * deepflow execution history recorder
+ * PostToolUse hook: fires when the Agent tool completes.
+ * Appends task_start + task_end records to {cwd}/.deepflow/execution-history.jsonl.
+ * Exits silently (code 0) on all errors — never blocks tool execution (REQ-8).
+ *
+ * Output record fields:
+ *   type, task_id, spec, session_id, timestamp, status
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Extract task_id from Agent prompt.
+ * Pattern: T{n} anywhere in the prompt, e.g. "T21: fix bug" → "T21"
+ * Falls back to DEEPFLOW_TASK_ID env var (C-6).
+ */
+function extractTaskId(prompt) {
+  if (prompt) {
+    const match = prompt.match(/T(\d+)/);
+    if (match) return `T${match[1]}`;
+  }
+  return process.env.DEEPFLOW_TASK_ID || null;
+}
+
+/**
+ * Extract spec name from Agent prompt.
+ * Looks for pattern: "spec: {name}" or "spec:{name}"
+ */
+function extractSpec(prompt) {
+  if (!prompt) return null;
+  const match = prompt.match(/spec:\s*(\S+)/i);
+  return match ? match[1] : null;
+}
+
+/**
+ * Parse task status from tool_response content.
+ * Looks for TASK_STATUS:{pass|revert|fail} in the response text.
+ * Defaults to "unknown" if not found (REQ-2).
+ */
+function extractStatus(toolResponse) {
+  const responseStr = JSON.stringify(toolResponse || '');
+  const match = responseStr.match(/TASK_STATUS:(pass|revert|fail)/);
+  return match ? match[1] : 'unknown';
+}
+
+/**
+ * Resolve the project root from cwd.
+ * Walks up to find the .deepflow directory, or falls back to cwd itself.
+ */
+function resolveProjectRoot(cwd) {
+  if (!cwd) return process.cwd();
+  // If inside a worktree, strip down to the project root
+  const worktreeMatch = cwd.match(/^(.*?)(?:\/\.deepflow\/worktrees\/[^/]+)/);
+  if (worktreeMatch) return worktreeMatch[1];
+  return cwd;
+}
+
+// Read all stdin, then process
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { raw += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(raw);
+
+    // Only fire for Agent tool calls
+    if (data.tool_name !== 'Agent') {
+      process.exit(0);
+    }
+
+    const prompt = (data.tool_input && data.tool_input.prompt) || '';
+    const taskId = extractTaskId(prompt);
+
+    // Only record if we have a task_id
+    if (!taskId) {
+      process.exit(0);
+    }
+
+    const cwd = data.cwd || process.cwd();
+    const projectRoot = resolveProjectRoot(cwd);
+    const historyFile = path.join(projectRoot, '.deepflow', 'execution-history.jsonl');
+
+    const timestamp = new Date().toISOString();
+    const sessionId = data.session_id || null;
+    const spec = extractSpec(prompt);
+    const status = extractStatus(data.tool_response);
+
+    const startRecord = {
+      type: 'task_start',
+      task_id: taskId,
+      spec,
+      session_id: sessionId,
+      timestamp,
+    };
+
+    const endRecord = {
+      type: 'task_end',
+      task_id: taskId,
+      session_id: sessionId,
+      status,
+      timestamp,
+    };
+
+    const logDir = path.dirname(historyFile);
+    if (!fs.existsSync(logDir)) {
+      fs.mkdirSync(logDir, { recursive: true });
+    }
+
+    fs.appendFileSync(historyFile, JSON.stringify(startRecord) + '\n');
+    fs.appendFileSync(historyFile, JSON.stringify(endRecord) + '\n');
+  } catch (_e) {
+    // Fail silently — never break tool execution (REQ-8)
+  }
+  process.exit(0);
+});

package/hooks/df-invariant-check.js

@@ -1020,6 +1020,130 @@ function checkInvariants(diff, specContent, opts = {}) {
   return { hard, advisory };
 }
 
+// ── Hook entry point (REQ-5 AC-7) ────────────────────────────────────────────
+//
+// When called as a PostToolUse hook, Claude Code pipes a JSON payload on stdin:
+//   { tool_name, tool_input, tool_response, cwd, ... }
+//
+// We fire after any Bash call that looks like a git commit, extract the diff
+// from HEAD~1, load the active spec from .deepflow/, and exit(1) on hard failures.
+//
+// Detection: if stdin is not a TTY we treat it as hook mode and attempt JSON parse.
+// If the payload is not a git-commit Bash call we exit(0) silently.
+
+function loadActiveSpec(cwd) {
+  const deepflowDir = path.join(cwd, '.deepflow');
+  let specContent = null;
+
+  try {
+    // Look for doing-*.md specs first (in-progress)
+    const entries = fs.readdirSync(deepflowDir);
+    const doingSpec = entries.find((e) => e.startsWith('doing-') && e.endsWith('.md'));
+    if (doingSpec) {
+      specContent = fs.readFileSync(path.join(deepflowDir, doingSpec), 'utf8');
+      return specContent;
+    }
+
+    // Fall back to specs/ subdirectory
+    const specsDir = path.join(cwd, 'specs');
+    if (fs.existsSync(specsDir)) {
+      const specEntries = fs.readdirSync(specsDir);
+      const doingInSpecs = specEntries.find((e) => e.startsWith('doing-') && e.endsWith('.md'));
+      if (doingInSpecs) {
+        specContent = fs.readFileSync(path.join(specsDir, doingInSpecs), 'utf8');
+        return specContent;
+      }
+    }
+  } catch (_) {
+    // Cannot read .deepflow or specs dir — return null
+  }
+
+  return null;
+}
+
+function extractDiffFromLastCommit(cwd) {
+  try {
+    return execSync('git diff HEAD~1 HEAD', {
+      encoding: 'utf8',
+      cwd,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch (_) {
+    return null;
+  }
+}
+
+function isGitCommitBash(toolName, toolInput) {
+  if (toolName !== 'Bash') return false;
+  const cmd = (toolInput && (toolInput.command || toolInput.cmd || '')) || '';
+  return /git\s+commit\b/.test(cmd);
+}
+
+// Run hook mode when stdin is not a TTY (i.e., piped payload from Claude Code)
+if (!process.stdin.isTTY) {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { raw += chunk; });
+  process.stdin.on('end', () => {
+    let data;
+    try {
+      data = JSON.parse(raw);
+    } catch (_) {
+      // Not valid JSON — not a hook payload, exit silently
+      process.exit(0);
+    }
+
+    try {
+      const toolName = data.tool_name || '';
+      const toolInput = data.tool_input || {};
+
+      // Only run after a git commit bash call
+      if (!isGitCommitBash(toolName, toolInput)) {
+        process.exit(0);
+      }
+
+      const cwd = data.cwd || process.cwd();
+
+      const diff = extractDiffFromLastCommit(cwd);
+      if (!diff) {
+        // No diff available (e.g. initial commit) — pass through
+        process.exit(0);
+      }
+
+      const specContent = loadActiveSpec(cwd);
+      if (!specContent) {
+        // No active spec found — not a deepflow project or no spec in progress
+        process.exit(0);
+      }
+
+      const results = checkInvariants(diff, specContent, { mode: 'auto', taskType: 'implementation', projectRoot: cwd });
+
+      if (results.hard.length > 0) {
+        console.error('[df-invariant-check] Hard invariant failures detected:');
+        const outputLines = formatOutput(results);
+        for (const line of outputLines) {
+          if (results.hard.some((v) => formatViolation(v) === line)) {
+            console.error(`  ${line}`);
+          }
+        }
+        process.exit(1);
+      }
+
+      if (results.advisory.length > 0) {
+        console.warn('[df-invariant-check] Advisory warnings:');
+        for (const v of results.advisory) {
+          console.warn(`  ${formatViolation(v)}`);
+        }
+      }
+
+      process.exit(0);
+    } catch (_err) {
+      // Unexpected error — fail open so we never break non-deepflow projects
+      process.exit(0);
+    }
+  });
+} else {
+
 // ── CLI entry point (REQ-6) ───────────────────────────────────────────────────
 if (require.main === module) {
   const args = process.argv.slice(2);
@@ -1091,6 +1215,8 @@ if (require.main === module) {
   process.exit(results.hard.length > 0 ? 1 : 0);
 }
 
+} // end else (TTY / CLI mode)
+
 module.exports = {
   checkInvariants,
   checkLspAvailability,

package/hooks/df-spec-lint.js

@@ -22,6 +22,62 @@ const REQUIRED_SECTIONS = [
   ['Technical Notes', 'architecture notes', 'architecture', 'tech notes', 'implementation notes'],
 ];
 
+// ── Spec layers (onion model) ───────────────────────────────────────────
+// Each layer defines sections that must ALL be present (cumulative with prior layers).
+// The computed layer is the highest where all cumulative sections exist.
+//
+// L0: Problem defined        → spikes only
+// L1: Requirements known     → targeted spikes
+// L2: Verifiable             → implementation tasks
+// L3: Fully constrained      → full impact analysis + optimize tasks
+const LAYER_DEFINITIONS = [
+  { layer: 0, sections: ['Objective'] },
+  { layer: 1, sections: ['Requirements'] },
+  { layer: 2, sections: ['Acceptance Criteria'] },
+  { layer: 3, sections: ['Constraints', 'Out of Scope', 'Technical Notes'] },
+];
+
+/**
+ * Compute the spec layer from its content.
+ * Returns the highest layer (0–3) where ALL cumulative required sections are present.
+ * Returns -1 if not even L0 (no Objective).
+ */
+function computeLayer(content) {
+  const headersFound = [];
+  for (const line of content.split('\n')) {
+    const m = line.match(/^##\s+(.+)/i);
+    if (m) {
+      const raw = m[1].trim().replace(/^\d+\.\s*/, '');
+      headersFound.push(raw.toLowerCase());
+    }
+  }
+
+  // Inline *AC: lines satisfy the Acceptance Criteria requirement
+  const hasInlineAC = /\*AC[:.]/.test(content);
+
+  let currentLayer = -1;
+  for (const { layer, sections } of LAYER_DEFINITIONS) {
+    const allPresent = sections.every((section) => {
+      // Find the REQUIRED_SECTIONS entry for aliases
+      const entry = REQUIRED_SECTIONS.find(
+        ([canonical]) => canonical.toLowerCase() === section.toLowerCase()
+      );
+      const allNames = entry
+        ? [entry[0], ...entry.slice(1)].map((n) => n.toLowerCase())
+        : [section.toLowerCase()];
+
+      if (section === 'Acceptance Criteria' && hasInlineAC) return true;
+      return headersFound.some((h) => allNames.includes(h));
+    });
+    if (allPresent) {
+      currentLayer = layer;
+    } else {
+      break; // layers are cumulative — can't skip
+    }
+  }
+  return currentLayer;
+}
+
 /**
  * Validate a spec's content against hard invariants and advisory checks.
  *
@@ -34,7 +90,11 @@ function validateSpec(content, { mode = 'interactive', specsDir = null } = {}) {
   const hard = [];
   const advisory = [];
 
-  // ── (a) Required sections ────────────────────────────────────────────
+  const layer = computeLayer(content);
+
+  // ── (a) Required sections (layer-aware) ──────────────────────────────
+  // Hard-fail only for sections required by the CURRENT layer.
+  // Missing sections beyond the current layer are advisory (hints to deepen).
   const headersFound = [];
   for (const line of content.split('\n')) {
     const m = line.match(/^##\s+(.+)/i);
@@ -45,13 +105,25 @@ function validateSpec(content, { mode = 'interactive', specsDir = null } = {}) {
     }
   }
 
+  // Collect all sections required up to the current layer
+  const layerRequiredSections = new Set();
+  for (const { layer: l, sections } of LAYER_DEFINITIONS) {
+    if (l <= layer) {
+      for (const s of sections) layerRequiredSections.add(s.toLowerCase());
+    }
+  }
+
   for (const [canonical, ...aliases] of REQUIRED_SECTIONS) {
     const allNames = [canonical, ...aliases].map((n) => n.toLowerCase());
     const found = headersFound.some((h) => allNames.includes(h.toLowerCase()));
     if (!found) {
       // Inline *AC: lines satisfy the Acceptance Criteria requirement
       if (canonical === 'Acceptance Criteria' && /\*AC[:.]/.test(content)) continue;
-      hard.push(`Missing required section: "## ${canonical}"`);
+      if (layerRequiredSections.has(canonical.toLowerCase())) {
+        hard.push(`Missing required section: "## ${canonical}"`);
+      } else {
+        advisory.push(`Missing section for deeper layer: "## ${canonical}"`);
+      }
     }
   }
 
@@ -161,7 +233,7 @@ function validateSpec(content, { mode = 'interactive', specsDir = null } = {}) {
     hard.push(...advisory.splice(0, advisory.length));
   }
 
-  return { hard, advisory };
+  return { layer, hard, advisory };
 }
 
 /**
@@ -230,7 +302,9 @@ if (require.main === module) {
     console.log('All checks passed.');
   }
 
+  console.log(`Spec layer: L${result.layer} (${['problem defined', 'requirements known', 'verifiable', 'fully constrained'][result.layer] || 'incomplete'})`);
+
   process.exit(result.hard.length > 0 ? 1 : 0);
 }
 
-module.exports = { validateSpec, extractSection };
+module.exports = { validateSpec, extractSection, computeLayer };