intentdna 1.5.14 → 1.5.16

package/.claude-plugin/marketplace.json

@@ -1,16 +1,29 @@
 {
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "intentdna",
-  "description": "Declarative policy layer for AI agent governance",
+  "description": "Intent DNA plugin marketplace for Claude Code",
   "owner": {
-    "name": "Samuel",
-    "email": "wanglushan3344@gmail.com"
+    "name": "Samuel"
   },
   "plugins": [
     {
       "name": "intentdna",
-      "description": "DNA template compilation + runtime enforcement",
-      "version": "1.5.14",
-      "source": "./"
+      "description": "Declarative policy layer for AI agent behavior with plugin-managed hook runtime for Claude Code.",
+      "version": "1.5.16",
+      "author": {
+        "name": "Samuel"
+      },
+      "source": "./",
+      "category": "development",
+      "homepage": "https://github.com/lushan1314/intentdna-repo",
+      "tags": [
+        "agent",
+        "policy",
+        "guardrails",
+        "hooks",
+        "development"
+      ]
     }
-  ]
+  ],
+  "version": "1.5.16"
 }

package/.claude-plugin/plugin.json

@@ -1,5 +1,19 @@
 {
   "name": "intentdna",
-  "version": "1.5.14",
-  "description": "Declarative policy layer for AI agent governance"
+  "version": "1.5.16",
+  "description": "Declarative policy layer for AI agent behavior",
+  "author": {
+    "name": "Samuel"
+  },
+  "repository": "https://github.com/lushan1314/intentdna-repo",
+  "homepage": "https://github.com/lushan1314/intentdna-repo",
+  "license": "Apache-2.0",
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "agent",
+    "policy",
+    "dna",
+    "guardrails"
+  ]
 }

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(() => {

package/dist/hooks/enforce.d.ts

@@ -14,11 +14,11 @@
  * Step checkpoints are handled by the CLI, not here.
  */
 import type { ConstraintIR, RoleDef, CompletedArtifactEntry } from "../schema/types.js";
-import type { PreToolUseInput, PostToolUseInput, UserPromptSubmitInput, SubagentStopInput, NotificationInput, HookOutput } from "./protocol.js";
+import type { PreToolUseInput, PostToolUseInput, UserPromptSubmitInput, SubagentStopInput, NotificationInput, EnforceResult } from "./protocol.js";
 /** SessionStart input fields */
 export interface SessionStartInput {
     cwd?: string;
-    session_id?: string;
+    sessionId?: string;
     trigger?: string;
 }
 export interface EnforceState {
@@ -41,22 +41,22 @@ export interface EnforceState {
  *
  * Optional `roles` parameter provides output_schema enforcement.
  */
-export declare function enforcePreToolUse(ir: ConstraintIR, input: PreToolUseInput, state?: EnforceState, roles?: Record<string, RoleDef>): HookOutput;
+export declare function enforcePreToolUse(ir: ConstraintIR, input: PreToolUseInput, state?: EnforceState, roles?: Record<string, RoleDef>): EnforceResult | null;
 /**
  * Enforce PostToolUse validators.
  * 1. Runs post-execution validators (audit)
  * 2. Verifies Bash write paths were within scope (defense-in-depth)
  */
-export declare function enforcePostToolUse(ir: ConstraintIR, input: PostToolUseInput): HookOutput;
+export declare function enforcePostToolUse(ir: ConstraintIR, input: PostToolUseInput): EnforceResult | null;
 /**
  * Inject DNA policy reminders on each user prompt.
  * Only injects when there are high-priority directives.
  */
-export declare function enforceUserPromptSubmit(ir: ConstraintIR, _input: UserPromptSubmitInput): HookOutput;
+export declare function enforceUserPromptSubmit(ir: ConstraintIR, _input: UserPromptSubmitInput): EnforceResult | null;
 /**
  * Audit role scope compliance when a subagent finishes.
  */
-export declare function enforceSubagentStop(ir: ConstraintIR, input: SubagentStopInput): HookOutput;
+export declare function enforceSubagentStop(ir: ConstraintIR, input: SubagentStopInput): EnforceResult | null;
 /**
  * Preserve DNA directive summary before context compaction.
  * Includes: high-priority directives, role scope map, active workflow state.
@@ -65,21 +65,21 @@ export declare function enforcePreCompact(ir: ConstraintIR, workflowContext?: {
     workflow: string;
     current_step: string;
     current_role: string;
-} | null): HookOutput;
+} | null): EnforceResult | null;
 /**
  * Check if a notification is a DNA violation and return audit info.
  * The CLI handles actual audit file writes.
  */
-export declare function enforceNotification(ir: ConstraintIR, input: NotificationInput): HookOutput;
+export declare function enforceNotification(ir: ConstraintIR, input: NotificationInput): EnforceResult | null;
 /**
  * Initialize DNA state and inject policy summary on session start.
  * Returns silent if no DNA policies are active.
  */
-export declare function enforceSessionStart(ir: ConstraintIR, input: SessionStartInput): HookOutput;
+export declare function enforceSessionStart(ir: ConstraintIR, input: SessionStartInput): EnforceResult | null;
 /** Stop enforcement input — includes workflow awareness */
 export interface StopEnforceInput {
     cwd?: string;
-    session_id?: string;
+    sessionId?: string;
     stop_reason?: string;
 }
 /** Workflow state context for stop enforcement */
@@ -103,7 +103,7 @@ export interface StopWorkflowContext {
  * Block when:
  *   - Workflow active + unmet checkpoints for current step
  */
-export declare function enforceStop(ir: ConstraintIR, input: StopEnforceInput, workflowState: StopWorkflowContext | null): HookOutput;
+export declare function enforceStop(ir: ConstraintIR, input: StopEnforceInput, workflowState: StopWorkflowContext | null): EnforceResult | null;
 /**
  * Enforce handoff produces — verify that the current step has produced
  * its declared artifacts. Called at stop/checkpoint time.
@@ -113,7 +113,7 @@ export declare function enforceHandoffProduces(ir: ConstraintIR, wfState: {
     current_step: string;
     workflow: string;
     completed_artifacts?: CompletedArtifactEntry[];
-}): HookOutput | null;
+}): EnforceResult | null;
 /** Check if a file path is allowed by a list of write globs (prefix matching). */
 export declare function checkWriteAllowed(filePath: string, allowedGlobs: string[]): boolean;
 /**
@@ -157,3 +157,4 @@ export interface ContextReadinessResult {
  * Pure function — no I/O.
  */
 export declare function checkContextReadiness(sessionReads: string[], required: string[]): ContextReadinessResult;
+export declare function checkWorkflowBoundary(workflowCompleted: boolean, targetSkill: string): EnforceResult;