intentdna 1.5.11 → 1.5.12

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "intentdna",
-  "version": "1.5.11",
+  "version": "1.5.12",
   "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 角色 ──
@@ -214,6 +232,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 +316,13 @@ 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 for this module (do NOT skip previously green tests)
+          - Compare with last baseline:
+            GREEN→RED = REGRESSION (mark HIGH_PRIORITY)
+            RED→GREEN = FIXED
+            NEW tests = new coverage
+            REMOVED tests = coverage shrunk
+          - Update baseline with full result
           - Git commit: "behavior-lock($ARGUMENTS): N tests (X green, Y red from behavior change)"
 
           BANNED patterns:
@@ -436,3 +503,118 @@ 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 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.12",
   "description": "Intent DNA — Declarative policy layer for AI agent behavior",
   "type": "module",
   "main": "dist/index.js",