intentdna 1.5.11 → 1.5.13

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "intentdna",
       "description": "DNA template compilation + runtime enforcement",
-      "version": "1.5.11",
+      "version": "1.5.13",
       "source": "./"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "intentdna",
-  "version": "1.5.11",
+  "version": "1.5.13",
   "description": "Declarative policy layer for AI agent governance"
 }

package/dist/compiler/cascade.d.ts

@@ -20,6 +20,11 @@ export interface CascadedDNA {
     source_ids: string[];
     /** Warnings from cascade process (e.g., cross-namespace gene collisions) */
     warnings?: string[];
+    context_files?: {
+        mandatory?: string[];
+        per_role?: Record<string, string[]>;
+        per_workflow?: Record<string, string[]>;
+    };
 }
 /**
  * Cascade multiple DNA layers into a single merged DNA.

package/dist/compiler/cascade.js

@@ -156,6 +156,13 @@ export function cascadeDNA(layers) {
             allMarkers.push(...dna.epigenetic.markers);
         }
     }
+    // context_files: highest-priority DNA wins (last in sorted layers)
+    let contextFiles;
+    for (const dna of sorted) {
+        if (dna.context_files) {
+            contextFiles = dna.context_files;
+        }
+    }
     return {
         genes: mergedGenes,
         contexts: mergedContexts,
@@ -164,5 +171,6 @@ export function cascadeDNA(layers) {
         epigenetic_markers: allMarkers,
         source_ids: sourceIds,
         warnings: warnings.length > 0 ? warnings : undefined,
+        context_files: contextFiles,
     };
 }

package/dist/compiler/compile.js

@@ -290,5 +290,6 @@ export function compileDNA(activated, cascaded) {
         roles_scope_map: rolesScopeMap.length > 0 ? rolesScopeMap : undefined,
         step_checkpoints: stepCheckpoints.length > 0 ? stepCheckpoints : undefined,
         workflows_ir: workflowsIR.length > 0 ? workflowsIR : undefined,
+        context_files: cascaded?.context_files,
     };
 }

package/dist/hooks/cli.js

@@ -18,8 +18,8 @@ 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, } from "./enforce.js";
-import { appendAudit, readWorkflowState, appendTrace, rotateTraces, readTraces, cleanStaleState, readSurgeonAttempts, writeSurgeonAttempts } from "./state.js";
+import { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, extractBashWritePaths, checkReflectionLimit, checkContextReadiness, } 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";
 const VALID_EVENTS = new Set([
@@ -164,6 +164,34 @@ async function main() {
     const durationMs = Date.now() - start;
     // Surgeon reflection gate (PostToolUse only, async)
     if (event === "PostToolUse") {
+        // 1. Track session reads
+        try {
+            const toolName = String(rawInput.tool_name ?? "");
+            if (toolName === "Read") {
+                const readPath = typeof rawInput.tool_input?.file_path === "string"
+                    ? rawInput.tool_input.file_path : undefined;
+                if (readPath) {
+                    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 {
             const reflectionOutput = await handleSurgeonReflection(ir, rawInput, projectDir, sessionId);
             if (reflectionOutput) {
@@ -476,6 +504,33 @@ async function loadReflectionConfig(projectDir, _workflowName, _stepId) {
         return null;
     }
 }
+// ── Context Gate ─────────────────────────────────────────
+/**
+ * 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.
+ */
+async function handleContextGate(ir, wfState, projectDir, sessionId) {
+    if (!ir.context_files)
+        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]);
+    }
+    if (ir.context_files.per_workflow?.[wfState.workflow]) {
+        required.push(...ir.context_files.per_workflow[wfState.workflow]);
+    }
+    if (required.length === 0)
+        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;
+}
 // ── Entry Point ────────────────────────────────────────────
 main().catch(() => {
     // Fail-open: never block Claude Code on unexpected errors

package/dist/hooks/enforce.d.ts

@@ -148,3 +148,12 @@ export interface ReflectionResult {
  * Pure function — no I/O.
  */
 export declare function checkReflectionLimit(failCount: number, maxAttempts: number, handoffCount: number, maxHandoffs: number): ReflectionResult;
+export interface ContextReadinessResult {
+    ready: boolean;
+    missing: string[];
+}
+/**
+ * Check if all required context files have been read in this session.
+ * Pure function — no I/O.
+ */
+export declare function checkContextReadiness(sessionReads: string[], required: string[]): ContextReadinessResult;

package/dist/hooks/enforce.js

@@ -703,3 +703,12 @@ export function checkReflectionLimit(failCount, maxAttempts, handoffCount, maxHa
     }
     return { action: "skip", reason: `No progress after ${maxAttempts} attempts and ${maxHandoffs} handoffs exhausted — skipping` };
 }
+/**
+ * Check if all required context files have been read in this session.
+ * Pure function — no I/O.
+ */
+export function checkContextReadiness(sessionReads, required) {
+    const readSet = new Set(sessionReads);
+    const missing = required.filter(f => !readSet.has(f));
+    return { ready: missing.length === 0, missing };
+}

package/dist/hooks/state.d.ts

@@ -90,6 +90,23 @@ export declare function readSurgeonAttempts(projectDir: string, sessionId?: stri
  * Write surgeon attempt state atomically.
  */
 export declare function writeSurgeonAttempts(projectDir: string, state: SurgeonAttemptState, sessionId?: string): Promise<void>;
+/** Tracks which files a session has Read — for context gate enforcement */
+export interface SessionReadsState {
+    session_id: string;
+    read_files: string[];
+}
+/**
+ * Read session reads state. Returns empty reads if not found.
+ */
+export declare function readSessionReads(projectDir: string, sessionId?: string): Promise<SessionReadsState>;
+/**
+ * Write session reads state atomically.
+ */
+export declare function writeSessionReads(projectDir: string, state: SessionReadsState, sessionId?: string): Promise<void>;
+/**
+ * Append a file path to session reads (dedup).
+ */
+export declare function appendSessionRead(projectDir: string, filePath: string, sessionId?: string): Promise<void>;
 /** Trace entry for hook call observability */
 export interface TraceEntry {
     trace_id: string;

package/dist/hooks/state.js

@@ -173,6 +173,39 @@ export async function writeSurgeonAttempts(projectDir, state, sessionId) {
     const filePath = join(stateDir, SURGEON_ATTEMPTS_FILE);
     await atomicWrite(filePath, JSON.stringify(state, null, 2));
 }
+const SESSION_READS_FILE = "workflow/session-reads.json";
+/**
+ * Read session reads state. Returns empty reads if not found.
+ */
+export async function readSessionReads(projectDir, sessionId) {
+    const stateDir = resolveStateDir(projectDir, sessionId);
+    const filePath = join(stateDir, SESSION_READS_FILE);
+    try {
+        const raw = await readFile(filePath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return { session_id: sessionId ?? "", read_files: [] };
+    }
+}
+/**
+ * Write session reads state atomically.
+ */
+export async function writeSessionReads(projectDir, state, sessionId) {
+    const stateDir = resolveStateDir(projectDir, sessionId);
+    const filePath = join(stateDir, SESSION_READS_FILE);
+    await atomicWrite(filePath, JSON.stringify(state, null, 2));
+}
+/**
+ * Append a file path to session reads (dedup).
+ */
+export async function appendSessionRead(projectDir, filePath, sessionId) {
+    const state = await readSessionReads(projectDir, sessionId);
+    if (!state.read_files.includes(filePath)) {
+        state.read_files.push(filePath);
+        await writeSessionReads(projectDir, state, sessionId);
+    }
+}
 const TRACE_DIR = "trace";
 const MAX_TRACE_SIZE = 10 * 1024 * 1024; // 10MB
 const TRACE_RETENTION_DAYS = 7;

package/dist/runtime/skill-adapter.js

@@ -42,6 +42,41 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
         lines.push("</Purpose>");
         lines.push("");
     }
+    // Required Context — context files that must be read before any work
+    if (ir?.context_files) {
+        const contextFiles = [];
+        if (ir.context_files.mandatory)
+            contextFiles.push(...ir.context_files.mandatory);
+        // per_workflow for this workflow
+        if (ir.context_files.per_workflow?.[plan.source_workflow]) {
+            contextFiles.push(...ir.context_files.per_workflow[plan.source_workflow]);
+        }
+        // per_role for all roles used in this workflow
+        if (ir.context_files.per_role) {
+            for (const step of plan.steps) {
+                const roleFiles = ir.context_files.per_role[step.role];
+                if (roleFiles) {
+                    for (const f of roleFiles) {
+                        if (!contextFiles.includes(f))
+                            contextFiles.push(f);
+                    }
+                }
+            }
+        }
+        if (contextFiles.length > 0) {
+            lines.push("<Required_Context>");
+            lines.push("Your context is EMPTY at startup. You MUST read these files first:");
+            lines.push("");
+            for (let i = 0; i < contextFiles.length; i++) {
+                lines.push(`${i + 1}. ${contextFiles[i]}`);
+            }
+            lines.push("");
+            lines.push("Without reading these, you cannot perform your role.");
+            lines.push("Hook will warn on first Edit/Bash/Write until these are read.");
+            lines.push("</Required_Context>");
+            lines.push("");
+        }
+    }
     // Steps — each step MUST be executed via Agent() tool call
     const usedRoles = new Set(plan.steps.map((s) => s.role));
     // Pre-compute handoff targets: steps that are pointed to by another step's handoff_to

package/dist/schema/types.d.ts

@@ -232,6 +232,11 @@ export interface IntentDNA {
     workflows?: Record<string, WorkflowDef>;
     variables?: Record<string, string | VariableDef>;
     mcp?: Record<string, MCPServerDef>;
+    context_files?: {
+        mandatory?: string[];
+        per_role?: Record<string, string[]>;
+        per_workflow?: Record<string, string[]>;
+    };
     epigenetic: {
         markers: EpigeneticMarker[];
     };
@@ -338,6 +343,11 @@ export interface ConstraintIR {
     roles_scope_map?: RoleScopeEntry[];
     step_checkpoints?: StepCheckpointIR[];
     workflows_ir?: WorkflowIR[];
+    context_files?: {
+        mandatory?: string[];
+        per_role?: Record<string, string[]>;
+        per_workflow?: Record<string, string[]>;
+    };
 }
 /** A compiled workflow step with resolved metadata */
 export interface WorkflowStep {

package/dist/schema/validate.js

@@ -478,6 +478,33 @@ export function validateDNA(dna) {
             }
         }
     }
+    // Validate context_files
+    if (dna.context_files) {
+        const cf = dna.context_files;
+        if (cf.per_role) {
+            for (const [roleName, paths] of Object.entries(cf.per_role)) {
+                if (roleNamesSet.size > 0 && !roleNamesSet.has(roleName)) {
+                    warnings.push({ path: `context_files.per_role.${roleName}`, message: `references unknown role '${roleName}'` });
+                }
+                if (!Array.isArray(paths)) {
+                    errors.push({ path: `context_files.per_role.${roleName}`, message: "must be an array of strings" });
+                }
+            }
+        }
+        if (cf.per_workflow) {
+            const wfNames = new Set(Object.keys(dna.workflows ?? {}));
+            if (dna.workflow)
+                wfNames.add(dna.workflow.name);
+            for (const [wfName, paths] of Object.entries(cf.per_workflow)) {
+                if (wfNames.size > 0 && !wfNames.has(wfName)) {
+                    warnings.push({ path: `context_files.per_workflow.${wfName}`, message: `references unknown workflow '${wfName}'` });
+                }
+                if (!Array.isArray(paths)) {
+                    errors.push({ path: `context_files.per_workflow.${wfName}`, message: "must be an array of strings" });
+                }
+            }
+        }
+    }
     // Validate epigenetic markers
     for (let i = 0; i < (dna.epigenetic?.markers?.length ?? 0); i++) {
         const marker = dna.epigenetic.markers[i];

package/dist/templates/flutter-rewrite.dna.yaml

@@ -119,6 +119,24 @@ genes:
 
 contexts: {}
 
+# 上下文文件 — subagent 必读清单
+context_files:
+  mandatory:
+    - CLAUDE.md
+    - docs/refactoring-workflow-v2.md
+    - v2/docs/PROVIDER_DESIGN.md
+    - v2/docs/memory/flutter_architecture_guide.md
+  per_role:
+    analyzer:
+      - "docs/behavior/{{ARGUMENTS}}.md"
+    analysis_reviewer:
+      - "docs/behavior/{{ARGUMENTS}}.md"
+      - ".omc/specs/diagnosis-{{ARGUMENTS}}.md"
+    surgeon:
+      - ".omc/specs/diagnosis-{{ARGUMENTS}}.md"
+    test_runner:
+      - "docs/behavior/{{ARGUMENTS}}.md"
+
 
 roles:
   # ── Phase 0/3: behavior-lock 角色 ──
@@ -183,6 +201,7 @@ roles:
       read: ["**/*"]
       write: ["lib/**", "v2/**", "test/**"]
     instructions:
+      - "REQUIRED FIRST: Read context files — CLAUDE.md, docs/refactoring-workflow-v2.md, v2/docs/PROVIDER_DESIGN.md, and the diagnosis spec (.omc/specs/diagnosis-$ARGUMENTS.md). Then read v1 corresponding file before any Edit. Hook will block Edit if context files are not read."
       - Fix only the identified breakpoint or missing implementation
       - Read v1 to understand intent, rewrite in v2 framework style
       - Do not copy v1 code verbatim — adapt to v2 architecture
@@ -214,6 +233,51 @@ roles:
       - Do not add methods v1 doesn't have
       - Do not remove methods v1 has
 
+  # ── v2 角色: diagnosis + fix workflow ──
+  analyzer:
+    description: "Reads code and classifies failing tests. Read-only."
+    tool_permissions:
+      allow: [Read, Grep, Glob]
+      deny: [Bash, Edit, Write, NotebookEdit]
+    scope:
+      read: ["**/*"]
+      write: []
+    instructions:
+      - "REQUIRED FIRST: Read all context files listed in SKILL.md"
+      - "For each failing test: read test code + v1 impl + v2 impl"
+      - "Classify each failure as BUG / INFRA / REMOVED / TEST_BUG"
+      - "Output diagnosis spec with v1 code snippets + v2 current state"
+      - "DO NOT run tests. DO NOT edit code. Analysis only."
+
+  analysis_reviewer:
+    description: "Reviews analyzer output quality. Read-only."
+    tool_permissions:
+      allow: [Read, Grep, Glob]
+      deny: [Bash, Edit, Write, NotebookEdit]
+    scope:
+      read: ["**/*"]
+      write: []
+    instructions:
+      - "REQUIRED FIRST: Read all context files listed in SKILL.md"
+      - "Verify analyzer spec: v1 references exist? Classifications sound?"
+      - "Check missing: any failing test not covered?"
+      - "Output: APPROVE or REQUEST_REANALYSIS with specific feedback"
+
+  test_runner:
+    description: "Runs tests and reports progress delta."
+    tool_permissions:
+      allow: [Read, Grep, Glob, Bash]
+      deny: [Edit, Write, NotebookEdit]
+    scope:
+      read: ["**/*"]
+      write: []
+    instructions:
+      - "Run flutter test for the target module"
+      - "Parse output: green/red/skip counts"
+      - "Compare with baseline: fixed / new_red / stable"
+      - "Classify red tests by type (compile/logic/widget/hung)"
+      - "Output progress delta, not test content"
+
 workflows:
   behavior-lock:
     name: Behavior Lock
@@ -253,9 +317,7 @@ workflows:
           Scenario 2 (re-run/incremental):
           - Read the incremental diff from behavior doc
           - Update existing tests incrementally — do NOT rewrite all tests (preserves rescue progress)
-          - Run `flutter test {{test_path}}/$ARGUMENTS/ --timeout 30s` — per-test safety net (hung tests marked fail, continues to next)
-          - Classify results: passed / failed (behavior mismatch) / hung (timed out = mock infrastructure issue, NOT behavior failure)
-          - Append baseline to behavior doc with hung/failed distinction
+          - Run ALL tests (do NOT skip previously green tests). Compare with previous baseline: GREEN→RED = REGRESSION (mark HIGH_PRIORITY), RED→GREEN = FIXED, NEW = new coverage. Update baseline with complete results.
           - Git commit: "behavior-lock($ARGUMENTS): N tests (X green, Y red from behavior change)"
 
           BANNED patterns:
@@ -436,3 +498,120 @@ workflows:
         role: core_aligner
         description: "Compare {{v1_path}}/ and {{v2_path}}/core/ module by module. Fix mismatches."
         prompt: "Compare v1 ({{v1_path}}/) and v2 core ({{v2_path}}/core/lib/). List mismatches. Fix by copying v1 logic, only changing DI (GetX→Riverpod). Run flutter analyze after each fix."
+
+  diagnosis:
+    name: Diagnosis
+    description: "Analyze failing tests, classify root causes, output diagnosis spec for module $ARGUMENTS"
+    steps:
+      - id: analyze
+        role: analyzer
+        max_attempts: 2
+        on_fail: retry_with_feedback
+        description: "Classify failing tests and output diagnosis spec"
+        prompt: |
+          Read all required context files first (enforced by hook).
+
+          For module $ARGUMENTS, analyze failing tests in baseline:
+          1. Read behavior doc: docs/behavior/$ARGUMENTS.md
+          2. Read test results from last behavior-lock run
+          3. For each failing test:
+             a. Read test code (what behavior does it expect?)
+             b. Read v1 implementation (how did v1 do this?)
+             c. Read v2 current state (what's missing/wrong?)
+             d. Classify: BUG / INFRA / REMOVED / TEST_BUG
+          4. Write .omc/specs/diagnosis-$ARGUMENTS.md with:
+             - For each failure: v1 code snippet + v2 current state + classification
+             - NO fix prescriptions (surgeon decides how to implement)
+             - NO running tests (analysis only)
+        handoff:
+          produces:
+            - type: file
+              path: ".omc/specs/diagnosis-$ARGUMENTS.md"
+              description: "Diagnosis spec for module"
+
+      - id: review
+        role: analysis_reviewer
+        depends_on: [analyze]
+        max_attempts: 2
+        description: "Review analyzer output quality"
+        prompt: |
+          Read context files + .omc/specs/diagnosis-$ARGUMENTS.md
+
+          Verify:
+          1. All failing tests from baseline covered?
+          2. v1 code references actually exist at claimed locations?
+          3. Classifications reasonable? (INFRA not mistaken for BUG)
+          4. Enough detail for surgeon to act?
+
+          APPROVE → diagnosis complete
+          REQUEST_REANALYSIS → list specific gaps, back to analyze
+        handoff:
+          consumes:
+            - type: file
+              path: ".omc/specs/diagnosis-$ARGUMENTS.md"
+              description: "Diagnosis spec from analyzer"
+          produces:
+            - type: summary
+              description: "Review verdict (APPROVE or REQUEST_REANALYSIS)"
+
+  fix:
+    name: Fix
+    description: "Read diagnosis spec and fix v2 code for module $ARGUMENTS with reflection gate"
+    steps:
+      - id: fix_bugs
+        role: surgeon
+        max_attempts: 3
+        on_fail: handoff
+        handoff_to: fix_bugs
+        max_handoffs: 3
+        on_handoff_exhausted: skip
+        blocked_items_path: "docs/behavior/blocked_items.md"
+        description: "Fix issues according to diagnosis spec classifications"
+        prompt: |
+          Read .dna/state/workflow/experience.md first if it exists. It contains previous failed approaches — do NOT repeat them.
+
+          Read context + diagnosis spec first.
+
+          Process issues in priority order: INFRA → BUG → TEST_BUG
+          (REMOVED skipped — needs user confirmation)
+
+          For each issue:
+          - BUG: read v1 file, edit v2 (use Riverpod per refactoring-workflow-v2.md)
+          - INFRA: edit test_helpers only, do NOT touch v2/lib
+          - TEST_BUG: re-read v1, edit test to match v1 behavior
+
+          After each fix: run tests ONCE for that specific file.
+
+          If experience_chain is non-empty:
+          - You have tried approaches that failed
+          - Read them, use a DIFFERENT approach
+        handoff:
+          consumes:
+            - type: file
+              path: ".omc/specs/diagnosis-$ARGUMENTS.md"
+              description: "Diagnosis spec"
+          produces:
+            - type: git_commit
+              description: "Fix commit"
+
+      - id: progress_check
+        role: test_runner
+        depends_on: [fix_bugs]
+        description: "Verify progress and output report"
+        prompt: |
+          Run full module test suite for $ARGUMENTS.
+          Compare with diagnosis spec baseline.
+
+          Output report:
+          - Fixed: N tests now green
+          - New red: M tests that regressed
+          - Blocked: K tests skipped (see blocked_items.md)
+          - Remaining: R tests still failing
+        handoff:
+          consumes:
+            - type: git_commit
+              from: fix_bugs
+              description: "Fix commit from surgeon"
+          produces:
+            - type: summary
+              description: "Progress report with test delta"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intentdna",
-  "version": "1.5.11",
+  "version": "1.5.13",
   "description": "Intent DNA — Declarative policy layer for AI agent behavior",
   "type": "module",
   "main": "dist/index.js",

package/spec/hooks-infra-harness-hardening.md

@@ -0,0 +1,695 @@
+# Hooks 基础设施优化 + Harness 加固 — 整合实施方案
+
+## Metadata
+- Generated: 2026-04-18
+- Status: APPROVED
+- 预计测试增量: +100
+- 预计工期: 1 周
+- 前置版本: v1.5.12
+
+## 背景
+
+两个独立方案的合并：
+1. **Hooks 基础设施优化**（上次三方评审通过）— Schema validation, EnforceResult, StateManager, Integration tests
+2. **Harness 加固**（本次 deep interview 产出）— Context gate, Reflection gate, Stop hook 智能编排, Workflow boundary
+
+上层（Harness 加固）依赖底层（Hooks 基础设施）。合并后减少重复工作。
+
+## 依赖图
+
+```
+Phase 0 (模板修复) ← 立即可做，无依赖
+  
+Phase 1A (Schema) ──→ Phase 1B (EnforceResult) ──→ Phase 2B (Gates)
+                                                       ↓
+Phase 2A (StateManager) ────────────────────────→ Phase 2B (Gates)
+                                                       ↓
+                                                  Phase 3 (Stop hook + Integration)
+                                                       ↓
+                                                  Phase 4 (Dogfood)
+
+可并行：1A + 2A
+必须串行：1B 依赖 1A；2B 依赖 1B + 2A；3 依赖 2B；4 依赖 3
+```
+
+---
+
+## Phase 0: 模板即时修复
+
+**目标**: 修复当前模板的 3 个已知缺陷，零风险
+**文件**: `src/templates/flutter-rewrite.dna.yaml`
+**测试**: +0（模板内容变更不影响单测，dna validate 验证）
+**破坏性**: 无
+
+### 0.1 Surgeon instructions 加必读清单
+
+找到 `roles.surgeon.instructions`，在现有 instructions 列表**最前面**插入一行：
+
+```yaml
+instructions:
+  - "REQUIRED FIRST: Read context files — CLAUDE.md, docs/refactoring-workflow-v2.md, v2/docs/PROVIDER_DESIGN.md, and the diagnosis spec (.omc/specs/diagnosis-$ARGUMENTS.md). Then read v1 corresponding file before any Edit. Hook will block Edit if context files are not read."
+  # ... 保留所有现有 instructions
+```
+
+### 0.2 Fix workflow experience chain 自读
+
+找到 `workflows.fix.steps` 中 `id: fix_bugs` 的 step，在 prompt 最前面加：
+
+```
+Read .dna/state/workflow/experience.md first if it exists.
+It contains previous failed approaches — do NOT repeat them.
+```
+
+### 0.3 Behavior-lock 全量回归
+
+找到 `workflows.behavior-lock.steps` 中 `id: write_tests` 的 step prompt，场景 2 (re-run) 部分，替换测试执行逻辑为：
+
+```
+Scenario 2 (re-run/incremental):
+- Read the incremental diff from behavior doc
+- Update existing tests incrementally — do NOT rewrite all tests
+- Run ALL tests (do NOT skip previously green tests)
+- Compare with previous baseline:
+  GREEN→RED = REGRESSION (mark HIGH_PRIORITY — v2 broke something)
+  RED→GREEN = FIXED
+  NEW = new coverage
+  REMOVED = coverage shrunk (verify intentional)
+- Update baseline with complete results
+- Git commit includes regression count if any
+```
+
+### 0.4 验证
+
+```bash
+dna validate src/templates/flutter-rewrite.dna.yaml
+npm test
+```
+
+---
+
+## Phase 1A: Boundary Schema + Contract Tests
+
+**目标**: CC ↔ dna-hook 边界的显式 schema 验证，防止 session_id 类 boundary bug
+**测试**: +20
+**破坏性**: 无（纯增量）
+
+### 1A.1 新建 src/hooks/schema.ts
+
+```typescript
+/**
+ * Hook input validation — CC protocol boundary.
+ * Zero external dependencies. Hand-written validators.
+ * Fail-open: invalid input → log warning + return { valid: false, ... }
+ */
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  normalized?: Record<string, unknown>;  // camelCase 归一化后的输入
+}
+
+export function validateHookInput(event: string, raw: unknown): ValidationResult
+// 对每种 event 类型验证必填字段：
+// PreToolUse: tool_name, tool_input 必须存在
+// PostToolUse: tool_name, tool_output 必须存在
+// SessionStart: session_id (camelCase 归一化)
+// SubagentStop: agent_type
+// UserPromptSubmit: (minimal)
+// Notification: title, message
+// PreCompact: (minimal)
+// Stop: (minimal)
+
+export function normalizeSessionId(input: Record<string, unknown>): string | undefined
+// 处理 session_id / sessionId / CLAUDE_SESSION_ID 的归一化
+```
+
+### 1A.2 修复 enforce.ts:38-42 snake_case bug
+
+找到 `SessionStartInput` 接口定义（enforce.ts 约 38 行），确认字段用 camelCase（和其他 Input 类型一致）。如果有 `session_id`（snake_case），改为 `sessionId`。
+
+### 1A.3 新建 test/fixtures/cc-hook-inputs/
+
+从 lwk_flutter_v2-rewrite 的 `.dna/state/trace/trace-2026-04-17.jsonl` 中提取 8 个真实 CC hook input fixture：
+
+```
+pre-tool-use-edit.json         — Edit 工具调用
+pre-tool-use-bash.json         — Bash 工具调用
+pre-tool-use-read.json         — Read 工具调用
+post-tool-use-bash-test.json   — Bash 跑 flutter test 的输出
+session-start.json             — SessionStart 事件
+subagent-stop-surgeon.json     — surgeon subagent 停止
+subagent-stop-investigator.json — investigator subagent 停止
+stop-event.json                — Stop 事件
+```
+
+### 1A.4 新建 test/contract/hook-contract.test.ts
+
+对每个 fixture：`fixture → validateHookInput() → enforce*() → 验证输出格式`
+
+全链路 contract test：确保真实 CC 输入能正确通过验证 + enforce 链。
+
+### 1A.5 验证
+
+```bash
+npm test  # 全绿，+20 新测试
+```
+
+---
+
+## Phase 1B: EnforceResult 类型
+
+**目标**: enforce 函数返回结构化结果，消除 cli.ts 的 decision 猜测逻辑
+**测试**: +15（改约 30 处现有断言）
+**破坏性**: 是（限定在此 phase）
+**依赖**: Phase 1A
+
+### 1B.1 protocol.ts 新增类型
+
+```typescript
+export interface TraceMetadata {
+  matched_rule: MatchedRule;
+  gene_id?: string;
+  step_id?: string;
+  role?: string;
+}
+
+export type MatchedRule =
+  | "scope"
+  | "filter"
+  | "gate"
+  | "schema"
+  | "handoff"
+  | "step_rule"
+  | "output_schema"
+  // Phase 2B 新增（先定义，后实现）：
+  | "context_gate"
+  | "reflection_gate"
+  | "workflow_boundary";
+
+export interface EnforceResult {
+  output: HookOutput;
+  trace?: TraceMetadata;
+}
+```
+
+### 1B.2 更新 enforce.ts 的 8 个函数
+
+每个 enforce* 函数的返回类型从 `HookOutput | null` 改为 `EnforceResult | null`。
+
+```typescript
+// 之前
+export function enforcePreToolUse(...): HookOutput | null {
+  return { decision: "block", reason: "..." };
+}
+
+// 之后
+export function enforcePreToolUse(...): EnforceResult | null {
+  return {
+    output: { decision: "block", reason: "..." },
+    trace: { matched_rule: "scope", gene_id: "scan_read_only", role: "scanner" }
+  };
+}
+```
+
+**注意**: trace metadata 不进入 HookOutput（CC 协议边界不该混入内部 metadata）。trace 由 cli.ts 读取后写入 trace log，不返回给 CC。
+
+### 1B.3 新增 3 个 enforce 纯函数
+
+```typescript
+// 已在 v1.5.12 实现 checkReflectionLimit，确认返回 EnforceResult
+export function checkReflectionLimit(
+  failCount: number, maxAttempts: number,
+  handoffCount: number, maxHandoffs: number
+): EnforceResult
+
+// 已在 v1.5.12 实现 checkContextReadiness，确认返回 EnforceResult
+export function checkContextReadiness(
+  sessionReads: string[], required: string[]
+): EnforceResult
+
+// 新增
+export function checkWorkflowBoundary(
+  workflowCompleted: boolean, targetSkill: string
+): EnforceResult
+```
+
+### 1B.4 更新 cli.ts
+
+cli.ts 从 enforce 结果中提取 trace metadata，写入 trace log：
+
+```typescript
+const result = enforcePreToolUse(ir, input, state);
+if (result) {
+  // 返回 HookOutput 给 CC
+  writeOutput(result.output);
+  // trace metadata 写 trace log（不返回给 CC）
+  if (result.trace) appendTrace({ ...result.trace, timestamp: now() });
+}
+```
+
+### 1B.5 更新 src/mcp/tools-enforce.ts
+
+检查 MCP enforce 工具是否调用 enforce 函数。如果调用了，同步更新返回类型处理。
+
+### 1B.6 更新测试
+
+约 30 处现有断言需要从 `expect(result).toEqual({ decision: "block", ... })` 改为 `expect(result.output).toEqual({ decision: "block", ... })`。
+
+```bash
+npm test  # 全绿，+15 新测试
+```
+
+---
+
+## Phase 2A: DNAStateManager
+
+**目标**: 统一所有 state 操作，支持 session reads + surgeon attempts + experience chain
+**测试**: +20
+**破坏性**: 无（旧函数 @deprecated 保留）
+**可与 Phase 1A 并行**
+
+### 2A.1 新建 src/hooks/state-manager.ts
+
+```typescript
+export class DNAStateManager {
+  constructor(private stateDir: string, private sessionId?: string) {}
+
+  // ── 现有 state 操作封装 ──
+  readWorkflowState(): WorkflowState | null
+  writeWorkflowState(state: WorkflowState): void
+  readAuditLog(): AuditEntry[]
+  appendAudit(entry: AuditEntry): void
+
+  // ── 新增: Session reads 追踪 ──
+  appendSessionRead(filePath: string): void
+  getSessionReads(): string[]
+  // 路径: .dna/state/workflow/session-reads.json
+
+  // ── 新增: Surgeon attempts 追踪 ──
+  readSurgeonAttempts(): SurgeonAttemptState
+  writeSurgeonAttempts(state: SurgeonAttemptState): void
+  // 路径: .dna/state/workflow/surgeon-attempts.json
+
+  // ── 新增: Experience chain ──
+  appendExperience(entry: ExperienceEntry): void
+  readExperienceChain(): ExperienceEntry[]
+  writeExperienceChain(chain: ExperienceEntry[]): void
+  // 路径: .dna/state/workflow/experience.md (markdown) 
+  //    + .dna/state/workflow/experience.json (structured)
+
+  // ── 生命周期 ──
+  init(): void          // 创建 session 目录结构
+  cleanup(): void       // 先算 summary（读 trace），再 rotate/clean
+  isStale(): boolean    // >2h 判定为 stale
+}
+
+export interface SurgeonAttemptState {
+  round: number;
+  edit_count: number;
+  bash_test_count: number;
+  last_green_count: number;
+  current_green_count: number;
+  fail_count: number;
+  handoff_count: number;
+  baseline_established: boolean;
+}
+
+export interface ExperienceEntry {
+  round: number;
+  analysis: string;
+  attempt: string;
+  result: string;
+  lesson: string;
+  timestamp: string;
+}
+```
+
+### 2A.2 保留 state.ts 向后兼容
+
+在现有 state.ts 函数上加 `@deprecated` 注释，内部改为调用 StateManager：
+
+```typescript
+/** @deprecated Use DNAStateManager instead */
+export function readWorkflowState(stateDir: string): WorkflowState | null {
+  return new DNAStateManager(stateDir).readWorkflowState();
+}
+```
+
+### 2A.3 测试
+
+```bash
+npm test  # 全绿，+20 新测试
+```
+
+---
+
+## Phase 2B: Context Gate + Reflection Gate + Workflow Boundary
+
+**目标**: 3 个核心 Harness 加固机制
+**测试**: +15
+**破坏性**: 无
+**依赖**: Phase 1B (EnforceResult) + Phase 2A (StateManager)
+
+### 2B.1 Context Gate — src/hooks/cli.ts
+
+在 PreToolUse 处理中新增：
+
+```typescript
+function handleContextGate(
+  input: PreToolUseInput,
+  ir: ConstraintIR,
+  stateManager: DNAStateManager,
+): EnforceResult | null {
+  // 只对 Edit/Write/Bash 触发
+  if (!["Edit", "Write", "Bash"].includes(input.tool_name)) return null;
+  
+  // 获取当前角色的必读文件列表
+  const role = getCurrentRole(ir, input);
+  if (!role) return null;
+  
+  const required = getRoleContextFiles(ir, role);
+  if (required.length === 0) return null;
+  
+  // 检查 session reads
+  const reads = stateManager.getSessionReads();
+  const result = checkContextReadiness(reads, required);
+  
+  if (!result.output.decision || result.output.decision === "allow") return null;
+  
+  // Block — 返回缺失文件清单
+  return result;
+}
+```
+
+**注意：直接 block，不是 warn。** 之前讨论的 Phase 1 warn 已取消，直接上 block。
+
+### 2B.2 Reflection Gate — src/hooks/cli.ts
+
+在 PostToolUse 处理中新增：
+
+```typescript
+function handleSurgeonReflection(
+  input: PostToolUseInput,
+  stepDef: WorkflowStepDef | null,
+  stateManager: DNAStateManager,
+): EnforceResult | null {
+  if (!stepDef?.max_attempts) return null;
+  
+  const attempts = stateManager.readSurgeonAttempts();
+  
+  // 追踪 Edit/Bash 调用
+  if (input.tool_name === "Edit") {
+    attempts.edit_count++;
+  }
+  
+  if (input.tool_name === "Bash" && looksLikeTestOutput(input.tool_output)) {
+    attempts.bash_test_count++;
+    const greenCount = parseGreenCount(input.tool_output);
+    if (greenCount !== null) {
+      attempts.current_green_count = greenCount;
+      if (!attempts.baseline_established) {
+        attempts.baseline_established = true;
+        attempts.last_green_count = greenCount;
+      }
+    }
+  }
+  
+  // 判定进展（只在有 baseline 后）
+  if (attempts.baseline_established && 
+      attempts.edit_count >= 2 && 
+      attempts.bash_test_count >= 1) {
+    if (attempts.current_green_count <= attempts.last_green_count) {
+      // 无进展
+      const result = checkReflectionLimit(
+        attempts.fail_count + 1, stepDef.max_attempts,
+        attempts.handoff_count, stepDef.max_handoffs ?? 3
+      );
+      attempts.fail_count++;
+      stateManager.writeSurgeonAttempts(attempts);
+      
+      if (result.output.decision !== "allow") {
+        return result;  // warn / handoff / skip
+      }
+    } else {
+      // 有进展，重置计数
+      attempts.last_green_count = attempts.current_green_count;
+      attempts.edit_count = 0;
+      attempts.bash_test_count = 0;
+    }
+  }
+  
+  stateManager.writeSurgeonAttempts(attempts);
+  return null;
+}
+
+function parseGreenCount(output: string): number | null {
+  // 匹配 flutter test 输出格式
+  // "00:05 +23: All tests passed!" → 23
+  // "00:05 +23 -5: Some tests failed." → 23
+  // "5 passed, 3 failed" → 5
+  const patterns = [
+    /\+(\d+)(?:\s|:)/,           // flutter test format: +N
+    /(\d+)\s+passed/i,           // generic: N passed
+    /(\d+)\s+tests?\s+passed/i,  // verbose: N tests passed
+  ];
+  for (const p of patterns) {
+    const m = output.match(p);
+    if (m) return parseInt(m[1], 10);
+  }
+  return null;  // 解析失败 → fail-open
+}
+```
+
+### 2B.3 Workflow Boundary — src/hooks/cli.ts
+
+在 PreToolUse 处理中新增：
+
+```typescript
+function handleWorkflowBoundary(
+  input: PreToolUseInput,
+  stateManager: DNAStateManager,
+): EnforceResult | null {
+  // 只检测 Skill 工具调用
+  if (input.tool_name !== "Skill") return null;
+  
+  const wfState = stateManager.readWorkflowState();
+  if (!wfState?.completed) return null;
+  
+  return checkWorkflowBoundary(true, input.tool_input?.skill ?? "unknown");
+}
+```
+
+### 2B.4 PostToolUse 追踪
+
+```typescript
+// 在 PostToolUse 处理中，所有 Read 调用记录到 session reads
+if (input.tool_name === "Read" && input.tool_input?.file_path) {
+  stateManager.appendSessionRead(input.tool_input.file_path);
+}
+```
+
+### 2B.5 测试
+
+```
+test/hooks-harness.test.ts 新增：
+- context gate: 未读必需文件 + Edit → block
+- context gate: 已读必需文件 + Edit → allow
+- reflection gate: 3 次无进展 → warn(handoff)
+- reflection gate: 有进展 → 不触发
+- reflection gate: parseGreenCount 解析 3 种格式
+- workflow boundary: completed + Skill → block
+- workflow boundary: not completed + Skill → allow
+- session reads 追踪正确
+```
+
+```bash
+npm test  # 全绿，+15 新测试
+```
+
+---
+
+## Phase 3: Stop Hook 智能编排 + Integration Tests
+
+**目标**: Stop hook 从"继续工作"升级为"输出下一步 Agent 调用"；全链路集成测试
+**测试**: +25
+**破坏性**: 无
+**依赖**: Phase 2B
+
+### 3.1 Stop Hook 智能编排 — src/hooks/cli.ts
+
+在 enforceStop 中，读 workflow state 后输出明确的下一步指令：
+
+```typescript
+function buildWorkflowGuidance(
+  ir: ConstraintIR,
+  stateManager: DNAStateManager,
+): string | null {
+  const wfState = stateManager.readWorkflowState();
+  if (!wfState) return null;
+  
+  const attempts = stateManager.readSurgeonAttempts();
+  const stepDef = getStepDef(ir, wfState.current_step);
+  
+  // 情况 1: surgeon 无进展，需要重新分析
+  if (wfState.current_step === "fix_bugs" && 
+      stepDef?.max_attempts && 
+      attempts.fail_count >= stepDef.max_attempts) {
+    const experience = stateManager.readExperienceChain();
+    return `[DNA WORKFLOW] Surgeon 已无进展 ${attempts.fail_count} 次。
+下一步: 重新分析。执行:
+Agent(subagent_type="dna-frw-analyzer", prompt="重新分析 module，
+读 .dna/state/workflow/experience.md 了解 ${experience.length} 次历史失败")`;
+  }
+  
+  // 情况 2: workflow 完成
+  if (wfState.completed) {
+    return `[DNA WORKFLOW] Workflow "${wfState.workflow}" 完成。
+输出最终报告并停止。不要启动其他 workflow。`;
+  }
+  
+  // 情况 3: 正常继续
+  return null;
+}
+```
+
+在 enforceStop 的 reason 中追加 workflow guidance（如果有）。
+
+### 3.2 Integration Tests — test/integration/
+
+新建 test/integration/hook-lifecycle.test.ts：
+
+```typescript
+// spawn 真实 dna-hook 进程，通过 stdin/stdout 模拟完整 workflow
+
+describe("hook lifecycle integration", () => {
+  it("context gate blocks Edit before reading context files", async () => {
+    // stdin: PreToolUse Edit event (surgeon, no prior reads)
+    // expected stdout: { decision: "block", reason: "...Missing: CLAUDE.md..." }
+  });
+
+  it("context gate allows Edit after reading required files", async () => {
+    // stdin: PostToolUse Read CLAUDE.md → PostToolUse Read workflow.md → PreToolUse Edit
+    // expected stdout: (no block)
+  });
+
+  it("reflection gate triggers after 3 no-progress cycles", async () => {
+    // stdin: sequence of Edit + Bash(test, same green count) × 3
+    // expected: warn with handoff message
+  });
+
+  it("stop hook injects workflow guidance", async () => {
+    // setup workflow state with fail_count >= max
+    // stdin: Stop event
+    // expected: reason contains "[DNA WORKFLOW]" + Agent() call
+  });
+});
+```
+
+### 3.3 Property Tests — test/property/
+
+新建 test/property/enforce-invariants.test.ts（使用 fast-check）：
+
+```typescript
+import fc from "fast-check";
+
+// 不变量 1: fail-open — 任何无效输入都不 throw
+// 不变量 2: scope 一致性 — deny 的 tool 永远 block
+// 不变量 3: context gate 幂等 — 同一输入多次调用结果相同
+// 不变量 4: reflection limit 单调 — fail_count 只增不减（除非 reset）
+// 不变量 5: parseGreenCount null 安全 — 任意字符串不 throw
+// 不变量 6: checkReflectionLimit 边界 — maxAttempts=0 时总是 handoff
+// 不变量 7: workflow boundary 完成判定 — completed=false 时总是 allow
+```
+
+### 3.4 验证
+
+```bash
+npm test  # 全绿，+25 新测试
+```
+
+---
+
+## Phase 4: Dogfood + Cleanup
+
+**目标**: 真实项目验证 + 清理
+**测试**: +5
+**依赖**: Phase 3
+
+### 4.1 intentdna 项目验证
+
+```bash
+dna verify --health  # 7 项检查全通过
+dna sync             # 无报错
+npm test             # 全绿
+```
+
+### 4.2 lwk_flutter_v2-rewrite 验证
+
+```bash
+cd /Users/samuel/lawark/lwk_flutter_v2-rewrite
+dna sync                        # 新 agent/skill 生成
+/dna-frw-diagnosis home          # 验证: analyzer 不跑 Bash, 输出 diagnosis spec
+                                 # 验证: context gate block 生效
+                                 # 验证: analysis_reviewer 审查
+/dna-frw-fix home                # 验证: surgeon 先读 context 再 Edit
+                                 # 验证: reflection gate 触发
+                                 # 验证: workflow boundary 阻止跨 workflow
+```
+
+### 4.3 清理
+
+如果 StateManager 稳定，考虑移除 state.ts 中 @deprecated 函数。
+
+### 4.4 发版
+
+```bash
+/dna-release patch "hooks infra + harness hardening — schema validation, EnforceResult, StateManager, context/reflection/boundary gates"
+```
+
+---
+
+## 验收清单
+
+### Phase 0
+- [ ] surgeon instructions 第一行是 REQUIRED FIRST
+- [ ] fix_bugs prompt 包含读 experience.md
+- [ ] behavior-lock 场景 2 全量回归
+
+### Phase 1A
+- [ ] schema.ts validateHookInput() 实现
+- [ ] 8 个真实 CC fixture 文件
+- [ ] contract tests 全链路通过
+- [ ] SessionStartInput snake_case bug 已修
+
+### Phase 1B
+- [ ] EnforceResult + TraceMetadata 类型定义
+- [ ] matched_rule 包含 context_gate / reflection_gate / workflow_boundary
+- [ ] 8 个 enforce 函数返回 EnforceResult
+- [ ] cli.ts 不再猜 decision
+- [ ] trace metadata 不进入 HookOutput（CC 协议边界）
+- [ ] mcp/tools-enforce.ts 同步更新
+
+### Phase 2A
+- [ ] DNAStateManager class 实现
+- [ ] Session reads 追踪
+- [ ] Surgeon attempts 追踪
+- [ ] Experience chain 读写
+- [ ] init/cleanup 生命周期
+- [ ] state.ts 旧函数 @deprecated 保留
+
+### Phase 2B
+- [ ] Context gate: block Edit/Bash/Write if context files not read
+- [ ] Reflection gate: detect no-progress, warn/handoff/skip
+- [ ] Workflow boundary: block Skill() after workflow completed
+- [ ] PostToolUse Read → appendSessionRead
+- [ ] parseGreenCount 支持 3 种格式 + null 安全
+
+### Phase 3
+- [ ] Stop hook 读 workflow state 输出 Agent() 调用指令
+- [ ] Integration tests: spawn dna-hook 全链路
+- [ ] Property tests: 7 个不变量
+
+### Phase 4
+- [ ] dna verify --health 通过
+- [ ] lwk_flutter diagnosis → fix 流程验证
+- [ ] 发版