intentdna 1.5.4 → 1.5.6

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/dist/runtime/skill-adapter.js

@@ -42,7 +42,7 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
         lines.push("</Purpose>");
         lines.push("");
     }
-    // Steps
+    // Steps — each step MUST be executed via Agent() tool call
     const usedRoles = new Set(plan.steps.map((s) => s.role));
     lines.push("<Steps>");
     let stepNumber = 0;
@@ -51,24 +51,44 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
         for (const stepId of group.step_ids) {
             stepNumber++;
             const step = plan.steps.find((s) => s.id === stepId);
-            const agent = `@dna-${toKebabCase(step.role)}`;
-            const runIf = step.run_if ? ` (${step.run_if})` : "";
+            const agentType = `dna-${toKebabCase(step.role)}`;
+            const runIf = step.run_if ? `\n   **Condition**: ${step.run_if}` : "";
             const optional = step.optional ? " (optional)" : "";
-            lines.push(`${stepNumber}. **${step.id}** → ${agent}${runIf}${optional}`);
-            lines.push(`   ${step.description}`);
-            if (step.prompt) {
-                lines.push(`   Prompt: ${step.prompt}`);
+            // Build agent prompt: anti-recursion + role identity + task
+            const promptParts = [
+                "Do NOT spawn sub-agents.",
+                `You are the ${agentType} agent.`,
+                step.prompt || step.description,
+            ];
+            const agentPrompt = escapePrompt(promptParts.join(" "));
+            lines.push(`${stepNumber}. **${step.id}**${optional}`);
+            lines.push(`   ${step.description}${runIf}`);
+            lines.push("");
+            lines.push(`   Execute with Agent tool — DO NOT perform this work yourself:`);
+            lines.push(`   \`\`\``);
+            lines.push(`   Agent(`);
+            lines.push(`     subagent_type="${agentType}",`);
+            lines.push(`     prompt="${agentPrompt}"`);
+            lines.push(`   )`);
+            lines.push(`   \`\`\``);
+            lines.push(`   Wait for agent to complete. Read the output before proceeding.`);
+            if (step.handoff?.produces && step.handoff.produces.length > 0) {
+                const artifacts = step.handoff.produces.map(p => p.description).join(", ");
+                lines.push(`   Verify produced artifacts: ${artifacts}`);
             }
+            lines.push("");
         }
     }
     lines.push("</Steps>");
     lines.push("");
-    // Execution Policy — force-complete standard
+    // Execution Policy — force Agent dispatch
     lines.push("<Execution_Policy>");
+    lines.push("- **CRITICAL**: Each step MUST be executed by spawning an Agent using the Agent tool with the specified subagent_type. DO NOT perform any step's work directly in the main session.");
     lines.push("- Use TodoWrite to track each step as pending/in_progress/completed.");
     lines.push("- After completing each step, immediately proceed to the next — do not stop, summarize, or wait for confirmation.");
     lines.push("- If a step fails, mark it as failed in TodoWrite, log the error, and continue to the next non-dependent step.");
     lines.push("- Do not ask the user for permission between steps — the workflow is pre-approved.");
+    lines.push("- Wait for each Agent to complete and read its output before proceeding to the next step.");
     lines.push("</Execution_Policy>");
     lines.push("");
     // Tool_Usage — only if roles have permissions or scope
@@ -232,3 +252,11 @@ export async function removeSkillFiles(outputDir) {
 function escapeYaml(s) {
     return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
+/** Escape prompt text for Agent() call template inside markdown code block. */
+function escapePrompt(s) {
+    return s
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/`{3,}/g, "` ` `")
+        .replace(/\n/g, "\\n");
+}

package/dist/schema/yaml-parser.d.ts

@@ -3,8 +3,8 @@
  *
  * Parses the YAML subset used by DNA templates and dna import output.
  * Supports: scalars, arrays (inline and block), objects (indentation),
- * comments, quoted strings. Does NOT support: anchors, aliases, tags,
- * multi-line scalars (|, >), complex keys, merge keys.
+ * comments, quoted strings, block scalars (|, >).
+ * Does NOT support: anchors, aliases, tags, complex keys, merge keys.
  *
  * Zero external dependencies.
  */

package/dist/schema/yaml-parser.js

@@ -3,8 +3,8 @@
  *
  * Parses the YAML subset used by DNA templates and dna import output.
  * Supports: scalars, arrays (inline and block), objects (indentation),
- * comments, quoted strings. Does NOT support: anchors, aliases, tags,
- * multi-line scalars (|, >), complex keys, merge keys.
+ * comments, quoted strings, block scalars (|, >).
+ * Does NOT support: anchors, aliases, tags, complex keys, merge keys.
  *
  * Zero external dependencies.
  */
@@ -49,6 +49,34 @@ function parseBlock(lines, startLine, baseIndent) {
             const key = content.slice(0, colonIdx).trim();
             const valueStr = content.slice(colonIdx + 1).trim();
             if (valueStr === "" || valueStr === "|" || valueStr === ">") {
+                // Block scalar: collect indented lines as a single string
+                if (valueStr === "|" || valueStr === ">") {
+                    const blockLines = [];
+                    let j = i + 1;
+                    const blockIndent = j < lines.length ? getIndent(lines[j]) : indent + 2;
+                    while (j < lines.length) {
+                        const bLine = lines[j];
+                        const bStripped = bLine.trimEnd();
+                        if (bStripped === "") {
+                            blockLines.push("");
+                            j++;
+                            continue;
+                        }
+                        const bIndent = getIndent(bLine);
+                        if (bIndent < blockIndent)
+                            break;
+                        blockLines.push(bLine.slice(blockIndent));
+                        j++;
+                    }
+                    // Trim trailing empty lines
+                    while (blockLines.length > 0 && blockLines[blockLines.length - 1] === "") {
+                        blockLines.pop();
+                    }
+                    const sep = valueStr === "|" ? "\n" : " ";
+                    obj[key] = blockLines.join(sep) + "\n";
+                    i = j;
+                    continue;
+                }
                 // Value is a nested block — check next line's indent
                 const nextNonEmpty = findNextNonEmptyLine(lines, i + 1);
                 if (nextNonEmpty < lines.length) {

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

@@ -98,6 +98,25 @@ genes:
         signal: uncertain_information
         response: escalate_to_human
 
+  minimal_change:
+    description: Each fix should be the smallest possible change
+    codons:
+      - type: attract
+        target: single_file_change
+      - type: repel
+        target: unnecessary_refactoring
+      - type: threshold
+        condition: "files_changed_per_round <= 5"
+        action: escalate
+
+  evidence_based:
+    description: All completion claims require fresh test evidence
+    codons:
+      - type: attract
+        target: run_tests_before_claiming_done
+      - type: repel
+        target: trust_without_evidence
+
 contexts: {}
 
 
@@ -147,6 +166,9 @@ roles:
       - Find where v2 diverges
       - Report with exact file paths and line numbers
       - Never suggest code changes
+      - "If round > 1: review previous round's git diff first, judge if direction is correct"
+      - "If previous fix produced 0 red→green transitions: warn 'no progress'"
+      - "Categorize by severity: CRITICAL (compile errors) > HIGH (logic failures) > LOW (widget/style)"
 
   surgeon:
     description: Fixes breakpoints and builds missing layers by understanding v1 intent and rewriting in v2 style.
@@ -165,6 +187,12 @@ roles:
       - After each change, run tests
       - If fix doesn't work, revert and re-analyze
       - Never "improve" code — preserve exact behavior
+      - "Before each fix: run `git diff` to confirm previous round's change scope"
+      - "After each file change: run `flutter analyze` to verify compilation"
+      - "Maximum 5 files per round — if more needed, the scope is too large, split it"
+      - "Same issue failed 3 times → STOP and report as blocked, do not retry"
+      - "Commit message must include: what changed, why, which test it targets"
+      - Do not introduce new abstractions or refactor unrelated code
 
   # ── Core align 角色 ──
   core_aligner:
@@ -188,18 +216,46 @@ workflows:
     steps:
       - id: scan
         role: scanner
-        description: "Scan v1 module in {{v1_path}}/. Output behavior doc to {{behavior_docs}}/$ARGUMENTS.md. List all user actions with call chains."
-        prompt: "Scan module '$ARGUMENTS' in {{v1_path}}/. For each page, list: action → function() → return value. Output to {{behavior_docs}}/$ARGUMENTS.md. Then immediately proceed to write_tests."
+        description: "Detect scenario (first-time vs re-run), scan v1 module accordingly."
+        prompt: |
+          Scenario detection:
+          - Check if {{test_path}}/$ARGUMENTS/ has test files AND {{behavior_docs}}/$ARGUMENTS.md exists
+          - Both missing → Scenario 1 (first-time): full scan, output complete behavior doc
+          - At least one exists → Scenario 2 (re-run/incremental): read existing behavior doc, compare against v1 source changes, output incremental diff only (do NOT rewrite the entire doc)
+
+          Scenario 1: Scan module '$ARGUMENTS' in {{v1_path}}/. For each page, list: action → function() → return value. Output to {{behavior_docs}}/$ARGUMENTS.md.
+          Scenario 2: Read {{behavior_docs}}/$ARGUMENTS.md. Compare against current v1 source in {{v1_path}}/. Output only the DIFF (added/removed/changed behaviors). Append changes to existing doc, do not rewrite.
         handoff:
           produces:
             - type: file
               path: "{{behavior_docs}}/$ARGUMENTS.md"
-              description: "Behavior document for module"
+              description: "Behavior document for module (full or incremental)"
       - id: write_tests
         role: test_writer
         depends_on: [scan]
-        description: "Read {{behavior_docs}}/$ARGUMENTS.md, write tests in {{test_path}}/$ARGUMENTS/, run baseline, commit."
-        prompt: "Read {{behavior_docs}}/$ARGUMENTS.md. Write tests in {{test_path}}/$ARGUMENTS/. Test ALL layers: logic, widget, navigation. Run tests, record red/green baseline. Append baseline to behavior doc. Git commit: behavior-lock($ARGUMENTS): X tests (Y red, Z skipped)"
+        description: "Write or update tests based on scenario, verify compilation."
+        prompt: |
+          Scenario detection (same as scan step):
+          - {{test_path}}/$ARGUMENTS/ has NO test files → Scenario 1 (first-time)
+          - {{test_path}}/$ARGUMENTS/ has existing tests → Scenario 2 (re-run)
+
+          Scenario 1 (first-time):
+          - Read {{behavior_docs}}/$ARGUMENTS.md
+          - Write tests in {{test_path}}/$ARGUMENTS/. Test ALL layers: logic, widget, navigation
+          - Run `flutter analyze` to verify compilation — do NOT run `flutter test` (no implementation yet)
+          - Git commit: "behavior-lock($ARGUMENTS): N tests (fresh, not yet runnable)"
+
+          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/` with NO timeout — record baseline
+          - Append baseline to behavior doc
+          - Git commit: "behavior-lock($ARGUMENTS): N tests (X green, Y red from behavior change)"
+
+          BANNED patterns:
+          - Do NOT use `sleep N && check` polling — run commands in foreground
+          - Do NOT use `timeout Nm flutter test` — let tests run to completion
+          - Do NOT rewrite existing test files from scratch — update incrementally
         handoff:
           consumes:
             - type: file
@@ -214,12 +270,25 @@ workflows:
 
   rescue:
     name: Rescue
-    description: "Fix v2 module $ARGUMENTS — logic layer first, then widget layer, commit when done"
+    description: "Fix v2 module $ARGUMENTS — investigate, fix, review, verify, report. Max 10 rounds with convergence protection."
+    max_rounds: 10
+    convergence_rule: "2 consecutive rounds with 0 test progress (green count not increasing) → STOP. Output blocked items + analysis."
     steps:
       - id: investigate
         role: investigator
-        description: "Run tests, assess current state, pick next targets."
-        prompt: "Run tests in {{test_path}}/$ARGUMENTS/. Categorize all non-passing tests: 1) RED (failing) — highest priority, fix first. 2) SKIPPED-logic — state/notifier/service tests, fix second. 3) SKIPPED-widget — widget/UI/navigation tests, fix after logic is done. For the highest priority category, pick a batch of related tests. Trace: what does v1 do vs what does v2 do? Find the breakpoints. Report findings and the plan for this round."
+        description: "Run tests, assess current state, pick next targets by severity."
+        prompt: |
+          Round context:
+          - If round > 1: review previous round's git diff first
+          - If previous round had 0 test progress (no red→green or skip→green): warn "no progress" and consider changing approach
+
+          Run tests in {{test_path}}/$ARGUMENTS/. Categorize all non-passing tests by severity:
+          CRITICAL: compile errors, import failures — fix first
+          HIGH: logic test failures (state/notifier/service) — fix second
+          LOW: widget test failures (rendering/navigation) — fix after logic is done
+
+          Pick highest severity batch. Trace: what does v1 do vs what does v2 do? Find the breakpoints.
+          Report findings and the plan for this round.
         handoff:
           produces:
             - type: summary
@@ -230,11 +299,20 @@ workflows:
       - id: fix
         role: surgeon
         depends_on: [investigate]
-        description: "Fix the identified issues. Handle both logic and widget layers."
+        description: "Fix identified issues. Max 5 files per round."
         checkpoints:
           - assert: clean_working_tree
-            message: "Commit all changes before proceeding to report step"
-        prompt: "Fix the identified breakpoints. Read v1 in {{v1_path}}/. Rewrite in v2 style in {{v2_path}}/. Logic tests: implement notifier/state/service code. Widget tests: copy widget from v1, change bindings (Obx→Consumer, Get.to→context.go), set up widget test infra (ProviderScope, mock providers, GoRouter) if needed. Run tests after each fix. Red→green or Skipped→green = done. Still failing = revert and re-analyze. Maximize test coverage per round. When done, commit all changes: rescue($ARGUMENTS): round N — X passed (+Y)"
+            message: "Commit all changes before proceeding"
+        prompt: |
+          Fix the identified breakpoints. Rules:
+          - Read v1 intent in {{v1_path}}/, rewrite in v2 style in {{v2_path}}/ (not copy v1 verbatim)
+          - Maximum 5 files per round — if more needed, split the scope
+          - Run `flutter analyze` after each file change
+          - Same issue failed 3 times → STOP, report as blocked, do not retry
+          - Logic tests: implement notifier/state/service code
+          - Widget tests: copy widget from v1, change bindings (Obx→Consumer, Get.to→context.go), set up infra (ProviderScope, mock providers, GoRouter) if needed
+          - Run tests after each fix. Red→green or Skip→green = progress. Still failing = revert and re-analyze
+          - Commit: "rescue($ARGUMENTS): round N — what changed, why, which tests targeted"
         handoff:
           consumes:
             - type: summary
@@ -243,11 +321,19 @@ workflows:
           produces:
             - type: git_commit
               description: "Rescue round commit"
-      - id: report
+      - id: review
         role: investigator
         depends_on: [fix]
-        description: "Summarize round, guide next steps."
-        prompt: "Run full test suite in {{test_path}}/$ARGUMENTS/. Report: 1) passed/skipped/failed delta vs last round. 2) List remaining skipped tests by category (logic vs widget vs platform). 3) If skipped tests remain, end with: Run /rescue $ARGUMENTS to continue. 4) If all tests pass, end with: Module $ARGUMENTS rescue complete."
+        description: "Read-only review of surgeon's changes."
+        prompt: |
+          Review surgeon's git diff (read-only, do NOT modify any files):
+          1. Are changes minimal? No unnecessary files touched?
+          2. Does the code match v2 patterns (Riverpod, GoRouter)?
+          3. Are mocks correct (not faked just to make tests pass)?
+          4. Any new issues introduced?
+
+          Verdict: APPROVE → proceed to verify
+          Verdict: REQUEST_CHANGES → describe specific problems. Next round's investigate step will include this feedback.
         handoff:
           consumes:
             - type: git_commit
@@ -255,7 +341,50 @@ workflows:
               description: "Committed fix from surgeon"
           produces:
             - type: summary
-              description: "Round summary with test delta"
+              description: "Review verdict (APPROVE or REQUEST_CHANGES)"
+      - id: verify
+        role: investigator
+        depends_on: [review]
+        description: "Independent test verification + regression check."
+        prompt: |
+          Run tests independently (do not trust surgeon's reported results):
+          1. `flutter test {{test_path}}/$ARGUMENTS/` (no timeout)
+          2. `flutter analyze` (compilation check)
+          3. Check for regressions in core module tests if applicable
+
+          Record test delta vs previous round.
+          Each acceptance criterion: VERIFIED / PARTIAL / MISSING
+          Verdict: PASS or FAIL
+        handoff:
+          consumes:
+            - type: summary
+              from: review
+              description: "Review verdict"
+          produces:
+            - type: test_result
+              path: "{{test_path}}/$ARGUMENTS/"
+              description: "Verified test results"
+      - id: report
+        role: investigator
+        depends_on: [verify]
+        description: "Round summary with convergence judgment."
+        prompt: |
+          Summary:
+          1. Test delta: +N green, -M red, ±K skipped vs last round
+          2. Remaining tests by category (logic vs widget vs platform)
+          3. Convergence check:
+             - If 2 consecutive rounds with no test progress → STOP, output blocked items + analysis
+             - If all green → "Module $ARGUMENTS rescue complete"
+             - Otherwise → "Run /rescue $ARGUMENTS to continue (round N+1 of max 10)"
+          4. If review verdict was REQUEST_CHANGES: include the specific feedback for next round
+        handoff:
+          consumes:
+            - type: test_result
+              from: verify
+              description: "Verified test results from verify step"
+          produces:
+            - type: summary
+              description: "Round summary with test delta and convergence status"
 
   core-align:
     name: Core Align

package/package.json

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

package/spec/agent-dispatch-fix.md

@@ -0,0 +1,116 @@
+# Spec: F5 Agent 调度漏洞修复
+
+## 问题（架构级）
+
+DNA 的 skill-adapter.ts 生成的 SKILL.md 用文字提示调度 agent：
+
+```
+1. **scan** → @dna-frw-scanner
+   Prompt: ...
+```
+
+LLM 把这当成建议，选择自己做而非 spawn agent。导致：
+
+- agent_type 为空 → role scope 不生效
+- tool_permissions deny 不生效（scanner 能写文件）
+- review/verify 步骤在主 session 做 → 自己审自己
+- handoff chain 无意义（没有跨 agent artifact 传递）
+- agent MD 文件从未被加载
+- 所有 role-based 治理形同虚设
+
+## 影响范围
+
+**以下交付物全部不生效：**
+
+| 功能 | 依赖 | 当前状态 |
+|------|------|---------|
+| Role scope (read/write 范围) | agent_type 匹配 | 不生效 |
+| tool_permissions deny | agent_type 匹配 | 不生效 |
+| review 步骤只读约束 | investigator agent spawn | 不生效 |
+| verify 步骤独立验证 | 独立 agent context | 不生效 |
+| merge-time scope gate | worktree + agent 隔离 | 不生效 |
+| handoff consumes/produces | 跨 agent artifact | 不生效 |
+| step enforce rules (G4) | workflow state + agent_type | 不生效 |
+| agent MD 文件加载 | agent spawn 时 CC 自动加载 | 从未加载 |
+
+## 根因
+
+OMC 用 Claude Code 原生 `Task(subagent_type=...)` API 强制 spawn agent：
+
+```
+Task(subagent_type="oh-my-claudecode:executor", prompt="implement caching")
+```
+
+这是 API 级调用，LLM 无法绕过。spawn 的 agent 有独立 context、独立 agent_type，hooks 能识别和 enforce。
+
+DNA 的 SKILL.md 只是文字提示，不是 API 调用。
+
+## 修复方案
+
+### skill-adapter.ts 改动
+
+生成的 SKILL.md `<Steps>` 部分从：
+
+```markdown
+1. **scan** → @dna-frw-scanner
+   Prompt: Scan module...
+```
+
+改为：
+
+```markdown
+1. **scan**
+   Execute with Agent tool — DO NOT perform this work in the main session:
+   ```
+   Agent(subagent_type="dna-frw-scanner", prompt="Scan module '$ARGUMENTS' in common/lib/. ...")
+   ```
+   Wait for agent to complete. Read the agent's output before proceeding.
+```
+
+### 关键设计要点
+
+1. **每步必须是 Agent() 调用**，不是文字描述
+2. **明确禁止主 session 做 agent 的工作**："DO NOT perform this work in the main session"
+3. **Agent 输出要读取**：Agent 完成后读取其 output，作为下一步的 handoff
+4. **Agent 工具参数完整**：subagent_type 用 DNA 编译的 agent 名称，prompt 用编译的步骤 prompt
+5. **参考 OMC 的 preamble 模式**：spawn 的 agent 不应再 spawn 子 agent（"Do NOT spawn sub-agents"）
+
+### 生成模板
+
+```typescript
+// skill-adapter.ts — 每个 workflow step 生成：
+function generateStepExecution(step, roleName, prompt) {
+  return `
+### Step: ${step.id}
+
+Execute with Agent tool — DO NOT perform this work yourself:
+
+\`\`\`
+Agent(
+  subagent_type="dna-${toKebabCase(roleName)}",
+  prompt="${escapePrompt(prompt)}"
+)
+\`\`\`
+
+Wait for agent to complete. Read the output.
+${step.handoff?.produces ? `Verify produced artifacts: ${step.handoff.produces.map(p => p.description).join(', ')}` : ''}
+`;
+}
+```
+
+### 验证方式
+
+修复后跑 behavior-lock(home)，检查 trace：
+- agent_type 应该有值（dna-frw-scanner, dna-frw-test-writer）
+- 不应该全是 "-"
+
+## Acceptance Criteria
+
+- [ ] skill-adapter.ts 生成强制 Agent() 调用格式
+- [ ] 每步明确禁止主 session 直接执行
+- [ ] Agent subagent_type 使用编译后的 role 名称
+- [ ] Agent prompt 包含完整步骤 prompt + variables 替换
+- [ ] spawn 的 agent 包含 "Do NOT spawn sub-agents" 约束
+- [ ] handoff produces 在 Agent 完成后验证
+- [ ] 测试：生成的 SKILL.md 包含 Agent() 调用模板
+- [ ] 实战验证：trace 中 agent_type 有值

package/spec/flutter-rewrite-template-optimization.md

@@ -0,0 +1,270 @@
+# Spec: flutter-rewrite 模板优化
+
+## 问题
+
+flutter-rewrite 模板的 behavior-lock 和 rescue 工作流都有设计缺陷，导致：
+1. behavior-lock 不区分首次和重跑，首次跑测试浪费时间
+2. rescue 没有 code review 和 verify 步骤，surgeon 自己写自己审
+3. 没有回归检查、收敛保护、diff 审查
+
+参考 OMC agent 设计（code-reviewer/verifier/executor/test-engineer）改进。
+
+---
+
+## 一、behavior-lock 优化
+
+### 场景检测
+
+```
+检查 {{test_path}}/$ARGUMENTS/ 是否已有测试文件
+检查 {{behavior_docs}}/$ARGUMENTS.md 是否已存在
+
+两者都不存在 → 场景 1（首次）
+至少一个存在 → 场景 2（重跑/增量）
+```
+
+### 场景 1: 首次
+
+```
+scan  → 全量扫描 v1，输出完整行为文档
+write → 写测试文件 → `flutter analyze` 验证编译 → 不跑 flutter test
+commit: "behavior-lock($MODULE): N tests (fresh, not yet runnable)"
+```
+
+### 场景 2: 重跑/增量
+
+```
+scan  → 读已有行为文档，对比 v1 变化，输出增量 diff
+write → 增量更新测试（不全量重写）→ `flutter test` 无超时 → 记录 baseline
+commit: "behavior-lock($MODULE): N tests (X green, Y red from behavior change)"
+```
+
+### scanner 增量
+
+场景 2 时 scanner 不重写行为文档，而是：
+1. 读已有 behavior doc
+2. 对比 v1 源码变化
+3. 增量更新
+4. 输出 diff 摘要
+
+### 禁止的模式
+
+| 禁止 | 原因 | 替代 |
+|------|------|------|
+| `sleep N && check` 轮询 | 浪费时间 | 前台跑 |
+| `timeout Nm flutter test` | 测试可能需要很久 | 不设超时 |
+| 全量重写已有测试 | 丢失 rescue 成果 | 增量更新 |
+| 首次跑 `flutter test` | 没实现，编译不过 | `flutter analyze` |
+
+---
+
+## 二、rescue 优化
+
+### 当前流程（缺陷）
+
+```
+investigate → fix → report → 重复
+              ↑ 无人审查
+              ↑ 无回归检查
+              ↑ 无收敛保护
+```
+
+### 优化后流程
+
+```
+investigate → fix → review → verify → report
+                     ↑ 只读审查 diff    ↑ 自己跑测试+回归
+```
+
+### 新增: review 步骤（参考 OMC code-reviewer）
+
+```yaml
+- id: review
+  role: investigator    # read-only，不能改代码
+  depends_on: [fix]
+  prompt: |
+    Review surgeon's changes (git diff):
+    1. 改动是否最小化？有没有改不该改的文件？
+    2. 是否匹配 v2 代码风格（Riverpod, GoRouter）？
+    3. mock 是否正确（不是为了让测试过而写假 mock）？
+    4. 有没有引入新问题？
+    
+    Verdict: APPROVE / REQUEST_CHANGES
+    如果 REQUEST_CHANGES → 说明具体问题，下轮 investigate 带上 review 意见
+```
+
+### 新增: verify 步骤（参考 OMC verifier）
+
+```yaml
+- id: verify
+  role: investigator    # read-only
+  depends_on: [review]  # review APPROVE 后才 verify
+  prompt: |
+    自己跑测试验证（不信任 surgeon 的报告）:
+    1. flutter test {{test_path}}/$ARGUMENTS/ （当前模块，无超时）
+    2. flutter test 核心模块（回归检查）
+    3. flutter analyze（编译检查）
+    
+    每个 acceptance criterion: VERIFIED / PARTIAL / MISSING
+    Verdict: PASS / FAIL
+```
+
+### surgeon 加约束（参考 OMC executor）
+
+```yaml
+surgeon:
+  instructions:
+    # 现有的保留，新增：
+    - 每次 fix 前先 `git diff` 确认上轮改动范围
+    - 每个文件改动后跑 `flutter analyze`
+    - 单轮最多改 5 个文件，超过说明范围太大需要拆分
+    - 同一问题失败 3 次 → 停止，报告卡点，不要无限重试
+    - commit message 必须包含：改了什么、为什么、对应哪个测试
+    - 不引入新抽象，不重构不相关代码
+```
+
+### investigator 加约束
+
+```yaml
+investigator:
+  instructions:
+    # 现有的保留，新增：
+    - 非首轮：先 review 上轮 git diff，判断方向是否正确
+    - 如果上轮 fix 没有让任何测试从 red→green，警告"无进展"
+    - 分类时标注严重度：CRITICAL（编译不过）> HIGH（逻辑错误）> LOW（widget 样式）
+```
+
+### 收敛保护
+
+```yaml
+rescue:
+  max_rounds: 10
+  convergence_rule: |
+    连续 2 轮无测试进展（green 数没增加）→ 停止
+    输出卡点分析 + 剩余问题清单
+  round_budget: |
+    每轮最多改 5 个文件
+    每轮必须让至少 1 个测试从 red/skip → green，否则视为无进展
+```
+
+### 完整 rescue workflow
+
+```yaml
+rescue:
+  name: Rescue
+  max_rounds: 10
+  steps:
+    - id: investigate
+      role: investigator
+      prompt: |
+        Round context:
+        - If round > 1: review previous round's git diff first
+        - If previous round had 0 progress: warn and consider changing approach
+        
+        Run tests, categorize by severity:
+        CRITICAL: compile errors, import failures
+        HIGH: logic test failures (state/notifier)
+        LOW: widget test failures (rendering/navigation)
+        
+        Pick highest severity batch. Trace v1 vs v2. Report breakpoints.
+
+    - id: fix
+      role: surgeon
+      depends_on: [investigate]
+      checkpoints:
+        - assert: clean_working_tree
+      prompt: |
+        Fix identified breakpoints. Rules:
+        - Read v1 intent, rewrite in v2 style (not copy v1 verbatim)
+        - Maximum 5 files per round
+        - flutter analyze after each file change
+        - Same issue failed 3 times → STOP, report as blocked
+        - Commit: rescue($ARGUMENTS): round N — what changed and why
+
+    - id: review
+      role: investigator
+      depends_on: [fix]
+      prompt: |
+        Review surgeon's git diff (read-only):
+        1. Changes minimal? No unnecessary files touched?
+        2. Matches v2 patterns (Riverpod, GoRouter)?
+        3. Mocks correct (not faked to pass)?
+        4. No new issues introduced?
+        Verdict: APPROVE → proceed to verify
+        Verdict: REQUEST_CHANGES → next round investigate includes review feedback
+
+    - id: verify
+      role: investigator
+      depends_on: [review]
+      prompt: |
+        Run independently (don't trust surgeon's results):
+        1. flutter test {{test_path}}/$ARGUMENTS/ (no timeout)
+        2. flutter analyze
+        3. Check: any regression in core tests?
+        Record delta vs last round. PASS or FAIL.
+
+    - id: report
+      role: investigator
+      depends_on: [verify]
+      prompt: |
+        Summary:
+        1. Test delta: +N green, -M red, ±K skipped
+        2. Remaining by category (logic vs widget vs platform)
+        3. Convergence: are we making progress?
+        4. If 2 rounds no progress → STOP, output blocked items
+        5. If all green → "Module $ARGUMENTS rescue complete"
+        6. Otherwise → "Run /rescue $ARGUMENTS to continue"
+```
+
+---
+
+## 三、全局规则（两个工作流共享）
+
+### DNA gene 层面
+
+```yaml
+genes:
+  # 现有 preserve_behavior 等保留，新增：
+  minimal_change:
+    description: Each fix should be the smallest possible change
+    codons:
+      - type: attract
+        target: single_file_change
+      - type: repel
+        target: unnecessary_refactoring
+      - type: threshold
+        condition: "files_changed_per_round <= 5"
+        action: escalate
+
+  evidence_based:
+    description: All completion claims require fresh test evidence
+    codons:
+      - type: attract
+        target: run_tests_before_claiming_done
+      - type: repel
+        target: trust_without_evidence
+```
+
+---
+
+## Acceptance Criteria
+
+### behavior-lock
+- [ ] 场景检测正确（首次 vs 重跑）
+- [ ] 首次: 只 analyze，不 test
+- [ ] 重跑: 增量更新测试，不全量重写
+- [ ] 重跑: 跑测试无超时
+- [ ] scanner 增量: 输出 diff 而非全量重写
+- [ ] 禁止 sleep 轮询模式
+
+### rescue
+- [ ] review 步骤: investigator 审查 surgeon 的 git diff
+- [ ] verify 步骤: 独立跑测试 + 回归检查
+- [ ] surgeon 约束: 最多 5 文件/轮，3 次失败停止
+- [ ] 收敛保护: 2 轮无进展 → 停止
+- [ ] 轮次上限: 最多 10 轮
+- [ ] report 包含收敛判断
+
+### 全局
+- [ ] minimal_change gene 编译到 IR
+- [ ] evidence_based gene 编译到 IR