intentdna 1.5.13 → 1.5.15

package/dist/cli/commands/init.d.ts

@@ -11,4 +11,8 @@ export interface InitOptions {
     register?: string;
     upgrade?: string | boolean;
 }
+/**
+ * Calculate SHA256 hash of template content (truncated to 16 hex chars).
+ */
+export declare function calculateTemplateHash(content: string): string;
 export declare function runInit(opts: InitOptions): Promise<number>;

package/dist/cli/commands/init.js

@@ -6,8 +6,9 @@
 import { writeFile, readFile, readdir, mkdir, copyFile, access } from "node:fs/promises";
 import { resolve, dirname, basename } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
 import { parseYAML } from "../../schema/yaml-parser.js";
-import { getPackageVersion, sanitizeTemplateName } from "../util/version.js";
+import { sanitizeTemplateName } from "../util/version.js";
 import { validateDNA } from "../../schema/validate.js";
 import { askString, askChoice, askNumber, askYesNo, closePrompt } from "../util/prompt.js";
 const TEMPLATES_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "templates");
@@ -65,17 +66,24 @@ async function listTemplates() {
     return results;
 }
 /**
- * Inject _source_template and _template_version fields after the namespace/type line in YAML content.
+ * Calculate SHA256 hash of template content (truncated to 16 hex chars).
  */
-function injectSourceTemplate(content, templateName, version) {
+export function calculateTemplateHash(content) {
+    return createHash("sha256").update(content, "utf-8").digest("hex").slice(0, 16);
+}
+/**
+ * Inject _source_template, _template_version, and _template_content_hash fields after the namespace/type line in YAML content.
+ */
+function injectSourceTemplate(content, templateName, templateVersion, templateHash) {
     const marker = /^(namespace:\s*.+)$/m;
     const typeMarker = /^(type:\s*.+)$/m;
     const match = content.match(marker) || content.match(typeMarker);
-    const versionLine = version ? `\n_template_version: "${version}"` : "";
+    const versionLine = templateVersion ? `\n_template_version: "${templateVersion}"` : "";
+    const hashLine = templateHash ? `\n_template_content_hash: "${templateHash}"` : "";
     if (match) {
-        return content.replace(match[0], `${match[0]}\n_source_template: ${templateName}${versionLine}`);
+        return content.replace(match[0], `${match[0]}\n_source_template: ${templateName}${versionLine}${hashLine}`);
     }
-    return `_source_template: ${templateName}${versionLine}\n${content}`;
+    return `_source_template: ${templateName}${versionLine}${hashLine}\n${content}`;
 }
 /**
  * Check namespace collision against existing configs in .dna/configs/.
@@ -164,9 +172,11 @@ async function upgradeConfig(configPath, templateName) {
     const srcDir = found.source === "project" ? PROJECT_TEMPLATES_DIR : TEMPLATES_DIR;
     const srcPath = resolve(srcDir, `${found.name}.dna.yaml`);
     let newContent = await readFile(srcPath, "utf-8");
-    // 4. Inject _source_template and _template_version
-    const pkgVersion = await getPackageVersion();
-    newContent = injectSourceTemplate(newContent, found.name, pkgVersion ?? undefined);
+    // 4. Inject _source_template, _template_version, and _template_content_hash
+    const templateData = parseYAML(newContent);
+    const templateVersion = typeof templateData.version === "string" ? templateData.version : undefined;
+    const templateHash = calculateTemplateHash(newContent);
+    newContent = injectSourceTemplate(newContent, found.name, templateVersion, templateHash);
     // 5. Replace VariableDef entries with user values where they exist
     for (const [key, value] of Object.entries(userVars)) {
         // Match multi-line VariableDef: "key:\n    description: ...\n    default: ..."
@@ -290,8 +300,11 @@ export async function runInit(opts) {
         const srcPath = resolve(srcDir, `${found.name}.dna.yaml`);
         const content = await readFile(srcPath, "utf-8");
         // Inject _source_template and _template_version metadata for upgrade tracking
-        const pkgVersion = await getPackageVersion();
-        const contentWithSource = injectSourceTemplate(content, found.name, pkgVersion ?? undefined);
+        // Inject _source_template, _template_version, and _template_content_hash for upgrade tracking
+        const templateData = parseYAML(content);
+        const templateVersion = typeof templateData.version === "string" ? templateData.version : undefined;
+        const templateHash = calculateTemplateHash(content);
+        const contentWithSource = injectSourceTemplate(content, found.name, templateVersion, templateHash);
         // Check namespace collision against existing configs
         const srcData = parseYAML(content);
         const srcNs = typeof srcData.namespace === "string" ? srcData.namespace : undefined;

package/dist/cli/commands/sync.d.ts

@@ -40,6 +40,12 @@ export interface SyncOptions {
  *   → ALSO write settings.json to register dna-hook events
  */
 export declare function detectMode(): Promise<"plugin" | "bin">;
+/**
+ * Remove stale DNA-managed files from a directory.
+ * Only removes files matching activeNamespaces (dna-{ns}-*).
+ * Returns list of removed paths.
+ */
+export declare function cleanStaleDNAFiles(dir: string, type: "agents" | "skills", activeNamespaces: string[]): Promise<string[]>;
 /**
  * Auto-detect DNA configs: multi-config (.dna/configs/*.yaml) or legacy single-config.
  * Returns array of absolute paths.
@@ -70,11 +76,10 @@ export interface TemplateUpgradeInfo {
     availableVersion: string;
 }
 /**
- * Check template versions against current package version.
- * Returns upgrade info for outdated configs and prints human-readable suggestions.
+ * Check template versions against current template content hashes.
+ * Returns upgrade info for changed configs and prints human-readable suggestions.
  *
- * U1: Semver-aware comparison — only suggests upgrades when package is strictly newer.
- * Handles missing _template_version (old configs created before versioning).
+ * Uses content hash comparison instead of semver — detects any template content change.
  */
 export declare function checkTemplateVersions(configPaths: string[]): Promise<TemplateUpgradeInfo[]>;
 export declare function runSync(opts: SyncOptions): Promise<number>;

package/dist/cli/commands/sync.js

@@ -17,7 +17,6 @@ import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline";
 import { loadDNA, compileFromFiles } from "../../compiler/index.js";
 import { parseYAML } from "../../schema/yaml-parser.js";
-import { getPackageVersion } from "../util/version.js";
 import { compileToMarkdown, injectIntoFile, removeFromFile } from "../../runtime/markdown.js";
 import { compileAllRolesToAgentMD, writeAgentMDFiles, removeAgentMDFiles } from "../../runtime/agent-md.js";
 import { removeWorkflowScripts } from "../../runtime/workflow-runner.js";
@@ -72,6 +71,32 @@ const LEGACY_BASH_HOOKS = [
     "dna-pre-compact.sh",
     "dna-notification.sh",
 ];
+const TEMPLATES_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "templates");
+function calculateTemplateHash(content) {
+    return createHash("sha256").update(content, "utf-8").digest("hex").slice(0, 16);
+}
+async function findTemplateFile(templateName) {
+    // Try direct filename match first
+    const directPath = resolve(TEMPLATES_DIR, `${templateName}.dna.yaml`);
+    if (await fileExists(directPath))
+        return directPath;
+    // Fallback: search by id or name field
+    try {
+        const files = await readdir(TEMPLATES_DIR);
+        for (const file of files) {
+            if (!file.endsWith(".dna.yaml") && !file.endsWith(".dna.yml"))
+                continue;
+            const fullPath = resolve(TEMPLATES_DIR, file);
+            const content = await readFile(fullPath, "utf-8");
+            const data = parseYAML(content);
+            if (data.id === templateName || data.name === templateName) {
+                return fullPath;
+            }
+        }
+    }
+    catch { /* fail-open */ }
+    return null;
+}
 /**
  * Remove legacy bash hook scripts written by previous Intent DNA versions.
  * Only removes files that contain the sentinel comment.
@@ -93,15 +118,22 @@ async function removeLegacyBashHooks(hooksDir) {
 }
 /**
  * Remove stale DNA-managed files from a directory.
- * Scans for files/dirs containing the sentinel marker and deletes them.
+ * Only removes files matching activeNamespaces (dna-{ns}-*).
  * Returns list of removed paths.
  */
-async function cleanStaleDNAFiles(dir, type) {
+export async function cleanStaleDNAFiles(dir, type, activeNamespaces) {
     const removed = [];
     try {
         const entries = await readdir(dir, { withFileTypes: true });
         for (const entry of entries) {
             const fullPath = resolve(dir, entry.name);
+            // Extract namespace from filename: dna-{namespace}-*
+            const nsMatch = entry.name.match(/^dna-([a-z0-9_-]+)-/);
+            const fileNamespace = nsMatch ? nsMatch[1] : null;
+            // Skip if namespace doesn't match active namespaces
+            if (!fileNamespace || !activeNamespaces.includes(fileNamespace)) {
+                continue;
+            }
             if (type === "agents" && entry.isFile() && entry.name.endsWith(".md")) {
                 const content = await readFile(fullPath, "utf-8").catch(() => "");
                 if (content.includes(DNA_SENTINEL)) {
@@ -276,42 +308,44 @@ export function compareSemver(a, b) {
     return 0;
 }
 /**
- * Check template versions against current package version.
- * Returns upgrade info for outdated configs and prints human-readable suggestions.
+ * Check template versions against current template content hashes.
+ * Returns upgrade info for changed configs and prints human-readable suggestions.
  *
- * U1: Semver-aware comparison — only suggests upgrades when package is strictly newer.
- * Handles missing _template_version (old configs created before versioning).
+ * Uses content hash comparison instead of semver — detects any template content change.
  */
 export async function checkTemplateVersions(configPaths) {
-    const pkgVersion = await getPackageVersion();
-    if (!pkgVersion)
-        return [];
     const upgrades = [];
     for (const configPath of configPaths) {
         try {
             const content = await readFile(configPath, "utf-8");
             const data = parseYAML(content);
-            const tmplVersion = typeof data._template_version === "string" ? data._template_version : undefined;
             const tmplName = typeof data._source_template === "string" ? data._source_template : undefined;
-            if (tmplName && !tmplVersion) {
-                // Old config without version tracking — suggest upgrade
+            const tmplHash = typeof data._template_content_hash === "string" ? data._template_content_hash : undefined;
+            const tmplVersion = typeof data._template_version === "string" ? data._template_version : undefined;
+            if (!tmplName)
+                continue;
+            const templatePath = await findTemplateFile(tmplName);
+            if (!templatePath)
+                continue;
+            const currentTemplateContent = await readFile(templatePath, "utf-8");
+            const currentHash = calculateTemplateHash(currentTemplateContent);
+            if (!tmplHash) {
                 upgrades.push({
                     configPath,
                     templateName: tmplName,
-                    currentVersion: "unknown",
-                    availableVersion: pkgVersion,
+                    currentVersion: tmplVersion ?? "unknown",
+                    availableVersion: "content-changed",
                 });
-                process.stderr.write(`Upgrade available: "${tmplName}" has no version tag. Run: dna init --upgrade ${tmplName}\n`);
+                process.stderr.write(`Upgrade available: "${tmplName}" has no content hash. Run: dna init --upgrade ${tmplName}\n`);
             }
-            else if (tmplVersion && tmplName && compareSemver(pkgVersion, tmplVersion) > 0) {
-                // Package is strictly newer than template — suggest upgrade
+            else if (currentHash !== tmplHash) {
                 upgrades.push({
                     configPath,
                     templateName: tmplName,
-                    currentVersion: tmplVersion,
-                    availableVersion: pkgVersion,
+                    currentVersion: tmplVersion ?? "unknown",
+                    availableVersion: "content-changed",
                 });
-                process.stderr.write(`Upgrade available: "${tmplName}" ${tmplVersion} → ${pkgVersion}. Run: dna init --upgrade ${tmplName}\n`);
+                process.stderr.write(`Template content changed: "${tmplName}". Run: dna init --upgrade ${tmplName}\n`);
             }
         }
         catch {
@@ -544,10 +578,14 @@ export async function runSync(opts) {
         else if (opts.plugin && opts.settingsPath) {
             process.stderr.write(`Plugin mode: hooks managed by plugin framework (skipping settings.json)\n`);
         }
+        // Extract active namespaces from loaded DNAs for namespace-scoped cleanup
+        const activeNamespaces = loadedDNAs
+            .map(d => d.namespace)
+            .filter((ns) => typeof ns === "string");
         // Step 5: Generate agent MD files
         if (opts.agentsDir) {
             // Clean stale DNA-managed agents before regenerating
-            const staleAgents = await cleanStaleDNAFiles(opts.agentsDir, "agents");
+            const staleAgents = await cleanStaleDNAFiles(opts.agentsDir, "agents", activeNamespaces);
             if (staleAgents.length > 0) {
                 process.stderr.write(`Cleaned ${staleAgents.length} stale agent file(s)\n`);
             }
@@ -608,7 +646,7 @@ export async function runSync(opts) {
         // Step 7: Generate skill files from workflows
         if (opts.skillsDir) {
             // Clean stale DNA-managed skills before regenerating
-            const staleSkills = await cleanStaleDNAFiles(opts.skillsDir, "skills");
+            const staleSkills = await cleanStaleDNAFiles(opts.skillsDir, "skills", activeNamespaces);
             if (staleSkills.length > 0) {
                 process.stderr.write(`Cleaned ${staleSkills.length} stale skill dir(s)\n`);
             }

package/dist/hooks/cli.d.ts

@@ -14,6 +14,9 @@
  *
  * Fail-open: all errors → { continue: true, suppressOutput: true }
  */
+import type { ConstraintIR } from "../schema/types.js";
+import { blockOutput } from "./protocol.js";
+import { readWorkflowState } from "./state.js";
 export interface SessionSummary {
     total: number;
     blocks: number;
@@ -34,3 +37,30 @@ export declare function computeSummary(traces: Array<{
     reason?: string;
 }>): SessionSummary;
 export declare function formatSummary(s: SessionSummary): string | null;
+/**
+ * Evaluate PreToolUse gates in priority order:
+ *   1. Workflow Boundary — block Skill() after workflow completed
+ *   2. Context Gate — block Edit/Write/Bash when required context files unread
+ *
+ * Returns the first triggered block, or null if all gates pass.
+ * Fail-open on any exception.
+ */
+export declare function handlePreToolGates(ir: ConstraintIR, rawInput: Record<string, unknown>, wfState: Awaited<ReturnType<typeof readWorkflowState>>, projectDir: string, sessionId?: string): Promise<{
+    output: ReturnType<typeof blockOutput>;
+    matched_rule: "workflow_boundary" | "context_gate";
+} | null>;
+/**
+ * Build next-step guidance for Stop hook.
+ * Returns a string to append to the Stop output's reason, or null if
+ * no explicit guidance applies (normal flow).
+ *
+ * Guidance cases:
+ *   1. Surgeon stalled — fail_count has reached the step's max_attempts
+ *      for a step that defines handoff_to. Emit Agent() dispatch to the
+ *      handoff role with experience chain context.
+ *   2. Workflow complete — wfState exists but active=false. Emit STOP
+ *      directive so the assistant doesn't auto-start another workflow.
+ *
+ * Fail-open: any exception returns null.
+ */
+export declare function buildWorkflowGuidance(projectDir: string, wfState: Awaited<ReturnType<typeof readWorkflowState>>, sessionId?: string): Promise<string | null>;

package/dist/hooks/cli.js

@@ -17,8 +17,9 @@
 import { readFile, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
-import { readStdin, writeOutput, silentOutput, allowOutput } from "./protocol.js";
-import { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, extractBashWritePaths, checkReflectionLimit, checkContextReadiness, } from "./enforce.js";
+import { readStdin, writeOutput, silentOutput, allowOutput, blockOutput } from "./protocol.js";
+import { validateHookInput } from "./schema.js";
+import { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, extractBashWritePaths, checkReflectionLimit, checkContextReadiness, checkWorkflowBoundary, } from "./enforce.js";
 import { appendAudit, readWorkflowState, appendTrace, rotateTraces, readTraces, cleanStaleState, readSurgeonAttempts, writeSurgeonAttempts, appendSessionRead, readSessionReads } from "./state.js";
 // ── Constants ──────────────────────────────────────────────
 const DEFAULT_IR_PATH = ".dna/compiled/ir.json";
@@ -80,12 +81,19 @@ async function main() {
         irPath = args[irFlagIdx + 1];
     }
     // Read stdin
-    const rawInput = await readStdin(5000);
+    const rawStdin = await readStdin(5000);
+    // Validate + normalize input against CC hook protocol schema.
+    // Fail-open: invalid input → write stderr warning + silent exit.
+    const validation = validateHookInput(event, rawStdin);
+    if (!validation.valid) {
+        process.stderr.write(`\n  Intent DNA: invalid ${event} input — ${validation.errors.join("; ")}\n`);
+        writeOutput(silentOutput());
+        return;
+    }
+    const rawInput = validation.normalized;
     // Resolve project directory from input or cwd
     const projectDir = typeof rawInput.cwd === "string" ? rawInput.cwd : process.cwd();
-    const sessionId = typeof rawInput.session_id === "string" ? rawInput.session_id
-        : typeof rawInput.sessionId === "string" ? rawInput.sessionId
-            : undefined;
+    const sessionId = typeof rawInput.sessionId === "string" ? rawInput.sessionId : undefined;
     // Load compiled IR
     const resolvedIRPath = resolve(projectDir, irPath);
     const ir = await loadIR(resolvedIRPath);
@@ -94,24 +102,46 @@ async function main() {
         return;
     }
     const state = {};
+    let wfStateRaw = null;
     // Load workflow state for events that need it (handoff context + PreCompact preservation)
     if (event === "PreToolUse" || event === "PreCompact") {
-        const wfState = await readWorkflowState(projectDir, sessionId);
-        if (wfState && wfState.active) {
+        wfStateRaw = await readWorkflowState(projectDir, sessionId);
+        if (wfStateRaw && wfStateRaw.active) {
             state.workflowState = {
-                current_step: wfState.current_step,
-                workflow: wfState.workflow,
-                current_role: wfState.current_role,
-                completed_artifacts: wfState.completed_artifacts,
-                iteration: wfState.iteration, // G4: pass iteration for state-driven rules
+                current_step: wfStateRaw.current_step,
+                workflow: wfStateRaw.workflow,
+                current_role: wfStateRaw.current_role,
+                completed_artifacts: wfStateRaw.completed_artifacts,
+                iteration: wfStateRaw.iteration, // G4: pass iteration for state-driven rules
             };
             // Re-run fallback: scan consumed artifact paths on disk so
             // enforceHandoffConsumes can skip blocks for files that already exist.
             if (event === "PreToolUse") {
-                state.existingArtifactPaths = await scanConsumedArtifactPaths(projectDir, ir, wfState.workflow, wfState.current_step);
+                state.existingArtifactPaths = await scanConsumedArtifactPaths(projectDir, ir, wfStateRaw.workflow, wfStateRaw.current_step);
             }
         }
     }
+    // Phase 2B: PreToolUse gates (workflow boundary + context gate).
+    // Run before dispatch so the block shortcircuits the rest of the pipeline.
+    if (event === "PreToolUse") {
+        const gateResult = await handlePreToolGates(ir, rawInput, wfStateRaw, projectDir, sessionId);
+        if (gateResult) {
+            writeOutput(gateResult.output);
+            appendTrace(projectDir, {
+                trace_id: randomUUID(),
+                event,
+                tool_name: typeof rawInput.tool_name === "string" ? rawInput.tool_name : undefined,
+                agent_type: typeof rawInput.agent_type === "string" ? rawInput.agent_type : undefined,
+                workflow: wfStateRaw?.workflow,
+                step: wfStateRaw?.current_step,
+                decision: "block",
+                reason: gateResult.output.reason,
+                duration_ms: 0,
+                timestamp: new Date().toISOString(),
+            }, sessionId).catch(() => { });
+            return;
+        }
+    }
     // Special handling for Stop — needs async workflow state read + session summary
     if (event === "Stop") {
         const wfState = await readWorkflowState(projectDir, sessionId);
@@ -123,11 +153,12 @@ async function main() {
             started_at: wfState.started_at,
             completed_artifacts: wfState.completed_artifacts,
         } : null;
-        let stopOutput = enforceStop(ir, {
+        let stopResult = enforceStop(ir, {
             cwd: typeof rawInput.cwd === "string" ? rawInput.cwd : undefined,
-            session_id: sessionId,
+            sessionId: sessionId,
             stop_reason: typeof rawInput.stop_reason === "string" ? rawInput.stop_reason : undefined,
         }, stopContext);
+        let stopOutput = stopResult?.output ?? silentOutput();
         // Session summary: aggregate block/warn stats from trace
         try {
             const traces = await readTraces(projectDir, 1, sessionId);
@@ -135,16 +166,29 @@ async function main() {
             const summaryText = formatSummary(summary);
             if (summaryText) {
                 if (stopOutput.suppressOutput) {
-                    // Was silent → upgrade to allow with summary
                     stopOutput = allowOutput(summaryText, "Stop");
                 }
                 else if (stopOutput.reason) {
-                    // Was a block → append summary to reason
                     stopOutput.reason += "\n\n" + summaryText;
                 }
             }
         }
         catch { /* fail-open: summary failure never blocks */ }
+        // Phase 3: Smart orchestration guidance.
+        // Appended to Stop output so the next assistant turn sees explicit
+        // next-step instructions (Agent() call + workflow boundary).
+        try {
+            const guidance = await buildWorkflowGuidance(projectDir, wfState, sessionId);
+            if (guidance) {
+                if (stopOutput.suppressOutput) {
+                    stopOutput = allowOutput(guidance, "Stop");
+                }
+                else if (stopOutput.reason) {
+                    stopOutput.reason += "\n\n" + guidance;
+                }
+            }
+        }
+        catch { /* fail-open */ }
         writeOutput(stopOutput);
         // Trace for Stop
         appendTrace(projectDir, {
@@ -160,11 +204,12 @@ async function main() {
     }
     // Dispatch to enforcement engine with timing
     const start = Date.now();
-    let output = dispatch(event, ir, rawInput, state);
+    let result = dispatch(event, ir, rawInput, state);
+    let output = result?.output ?? silentOutput();
     const durationMs = Date.now() - start;
-    // Surgeon reflection gate (PostToolUse only, async)
+    // PostToolUse side effects: session read tracking + surgeon reflection gate.
+    // Context gate moved to PreToolUse (block mode) in Phase 2B.
     if (event === "PostToolUse") {
-        // 1. Track session reads
         try {
             const toolName = String(rawInput.tool_name ?? "");
             if (toolName === "Read") {
@@ -174,22 +219,6 @@ async function main() {
                     await appendSessionRead(projectDir, readPath, sessionId);
                 }
             }
-            // 2. Context gate (Phase 1: warn mode)
-            const writeTools = new Set(["Edit", "Write", "Bash"]);
-            if (writeTools.has(toolName)) {
-                const wfStateForCtx = await readWorkflowState(projectDir, sessionId);
-                if (wfStateForCtx?.active && ir.source_dna_ids.length > 0) {
-                    const contextGateOutput = await handleContextGate(ir, wfStateForCtx, projectDir, sessionId);
-                    if (contextGateOutput) {
-                        if (output.suppressOutput) {
-                            output = contextGateOutput;
-                        }
-                        else if (output.reason) {
-                            output = { ...output, reason: output.reason + "\n" + (contextGateOutput.reason ?? "") };
-                        }
-                    }
-                }
-            }
         }
         catch { /* fail-open */ }
         try {
@@ -306,16 +335,16 @@ function dispatch(event, ir, input, state) {
                 message: typeof input.message === "string" ? input.message : undefined,
             });
         case "Stop":
-            return silentOutput(); // DNA doesn't block stops
+            return null;
         case "SessionStart":
             return enforceSessionStart(ir, {
                 cwd: typeof input.cwd === "string" ? input.cwd : undefined,
-                session_id: typeof input.session_id === "string" ? input.session_id
+                sessionId: typeof input.session_id === "string" ? input.session_id
                     : typeof input.sessionId === "string" ? input.sessionId : undefined,
                 trigger: typeof input.trigger === "string" ? input.trigger : undefined,
             });
         default:
-            return silentOutput();
+            return null;
     }
 }
 // ── IR Loading ─────────────────────────────────────────────
@@ -504,32 +533,112 @@ async function loadReflectionConfig(projectDir, _workflowName, _stepId) {
         return null;
     }
 }
-// ── Context Gate ─────────────────────────────────────────
+// ── PreToolUse Gates (Phase 2B) ──────────────────────────
+/**
+ * Evaluate PreToolUse gates in priority order:
+ *   1. Workflow Boundary — block Skill() after workflow completed
+ *   2. Context Gate — block Edit/Write/Bash when required context files unread
+ *
+ * Returns the first triggered block, or null if all gates pass.
+ * Fail-open on any exception.
+ */
+export async function handlePreToolGates(ir, rawInput, wfState, projectDir, sessionId) {
+    try {
+        const toolName = typeof rawInput.tool_name === "string" ? rawInput.tool_name : "";
+        const toolInput = typeof rawInput.tool_input === "object" && rawInput.tool_input !== null
+            ? rawInput.tool_input : {};
+        // Gate 1: Workflow Boundary — Skill invoked after workflow finished.
+        // Interpret "completed" as a state record existing with active === false.
+        if (toolName === "Skill" && wfState && wfState.active === false) {
+            const skillName = typeof toolInput.skill === "string"
+                ? toolInput.skill
+                : typeof toolInput.name === "string" ? toolInput.name : "unknown";
+            const result = checkWorkflowBoundary(true, skillName);
+            if (result.output.continue === false) {
+                return { output: result.output, matched_rule: "workflow_boundary" };
+            }
+        }
+        // Gate 2: Context Gate — block write tools when required context files unread.
+        const writeTools = new Set(["Edit", "Write", "Bash"]);
+        if (writeTools.has(toolName) && wfState?.active && ir.context_files) {
+            const required = [];
+            if (ir.context_files.mandatory)
+                required.push(...ir.context_files.mandatory);
+            if (ir.context_files.per_role?.[wfState.current_role]) {
+                required.push(...ir.context_files.per_role[wfState.current_role]);
+            }
+            if (ir.context_files.per_workflow?.[wfState.workflow]) {
+                required.push(...ir.context_files.per_workflow[wfState.workflow]);
+            }
+            if (required.length > 0) {
+                const sessionReadsState = await readSessionReads(projectDir, sessionId);
+                const ready = checkContextReadiness(sessionReadsState.read_files, required);
+                if (!ready.ready) {
+                    return {
+                        output: blockOutput(`[Intent DNA] Context Gate: required context files not yet read — ${ready.missing.join(", ")}. Read them before attempting ${toolName}.`),
+                        matched_rule: "context_gate",
+                    };
+                }
+            }
+        }
+    }
+    catch {
+        // Fail-open: gate failures never block execution
+    }
+    return null;
+}
+// ── Stop guidance (Phase 3) ───────────────────────────────
 /**
- * Check if required context files have been read before allowing writes.
- * Phase 1: warn mode (allow + inject warning).
- * Returns null if all context files read or no context_files configured.
+ * Build next-step guidance for Stop hook.
+ * Returns a string to append to the Stop output's reason, or null if
+ * no explicit guidance applies (normal flow).
+ *
+ * Guidance cases:
+ *   1. Surgeon stalled — fail_count has reached the step's max_attempts
+ *      for a step that defines handoff_to. Emit Agent() dispatch to the
+ *      handoff role with experience chain context.
+ *   2. Workflow complete — wfState exists but active=false. Emit STOP
+ *      directive so the assistant doesn't auto-start another workflow.
+ *
+ * Fail-open: any exception returns null.
  */
-async function handleContextGate(ir, wfState, projectDir, sessionId) {
-    if (!ir.context_files)
+export async function buildWorkflowGuidance(projectDir, wfState, sessionId) {
+    if (!wfState)
         return null;
-    const required = [];
-    if (ir.context_files.mandatory)
-        required.push(...ir.context_files.mandatory);
-    if (ir.context_files.per_role?.[wfState.current_role]) {
-        required.push(...ir.context_files.per_role[wfState.current_role]);
+    // Case 2: workflow marked completed (inactive state record still present).
+    if (wfState.active === false) {
+        return `[DNA WORKFLOW] Workflow "${wfState.workflow}" is complete. ` +
+            `Output the final report and STOP. Do NOT start another workflow.`;
     }
-    if (ir.context_files.per_workflow?.[wfState.workflow]) {
-        required.push(...ir.context_files.per_workflow[wfState.workflow]);
+    // Case 1: surgeon stalled — load reflection config sidecar + current attempts.
+    try {
+        const reflectionConfig = await loadReflectionConfig(projectDir, wfState.workflow, wfState.current_step);
+        if (!reflectionConfig?.max_attempts)
+            return null;
+        const attempts = await readSurgeonAttempts(projectDir, sessionId);
+        if (attempts.fail_count < reflectionConfig.max_attempts)
+            return null;
+        const handoffTo = reflectionConfig.handoff_to ?? "handoff role";
+        const agentType = `dna-${toKebabCase(handoffTo)}`;
+        const expCount = attempts.experience_chain?.length ?? 0;
+        return `[DNA WORKFLOW] Surgeon stalled — ${attempts.fail_count} consecutive no-progress attempts ` +
+            `(limit: ${reflectionConfig.max_attempts}).\n` +
+            `Next step: re-analyze via handoff. Dispatch:\n` +
+            `Agent(\n` +
+            `  subagent_type="${agentType}",\n` +
+            `  prompt="Re-analyze the current step. Read .dna/state/workflow/experience.md ` +
+            `for ${expCount} previous failure notes — do NOT repeat those approaches."\n` +
+            `)`;
     }
-    if (required.length === 0)
+    catch {
         return null;
-    const sessionReadsState = await readSessionReads(projectDir, sessionId);
-    const result = checkContextReadiness(sessionReadsState.read_files, required);
-    if (!result.ready) {
-        return allowOutput(`WARN [Intent DNA] Context Gate: Required files not yet read: ${result.missing.join(", ")}. Read them before continuing.`);
     }
-    return null;
+}
+function toKebabCase(s) {
+    return s
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/[_\s]+/g, "-")
+        .toLowerCase();
 }
 // ── Entry Point ────────────────────────────────────────────
 main().catch(() => {