intentdna 1.7.5 → 1.8.0

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

@@ -1,301 +0,0 @@
-# Spec: flutter-rewrite 模板优化
-
-## 最终目标
-
-**把 v1 (GetX) 重写为 v2 (Riverpod)，行为完全一致。**
-
-- behavior-lock: 写测试 = 定义"v1 的行为是什么"
-- rescue: 写代码让测试通过 = "v2 的行为和 v1 一样"
-- 完成标志: 所有测试 green = 重写成功，行为完全一致
-
-所有设计决策必须服务于这个目标。timeout 是安全网（防卡死），不是解法。挂死的测试意味着行为没被验证——rescue 必须修复它们，不能跳过。
-
-## 问题
-
-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 摘要
-
-### 超时策略
-
-| 操作 | 允许？ | 原因 |
-|------|--------|------|
-| `flutter test --timeout 30s` | **允许** | per-test 安全网，挂死标 fail 继续下一个 |
-| `timeout Nm flutter test` | 禁止 | 外部杀进程，丢失所有结果 |
-| `sleep N && check` 轮询 | 禁止 | 浪费时间 |
-| 全量重写已有测试 | 禁止 | 丢失 rescue 成果 |
-| 首次跑 `flutter test` | 禁止 | 没实现，编译不过，用 `flutter analyze` |
-
-**挂死的测试分类**：标记为 `hung: needs mock infrastructure`，不是 `failed`。区别：
-- `failed` = 行为不一致，rescue 修 v2 代码
-- `hung` = mock 不完整，rescue 先修测试基础设施
-
----
-
-## 二、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-INFRA: mock 不完整导致 test hang（阻塞行为验证，rescue 优先修）
-      HIGH-LOGIC: 逻辑测试 fail（行为不一致）
-      MEDIUM: widget 测试 fail（渲染/导航差异）
-      LOW: 样式差异
-    - hung 测试 ≠ failed 测试。hung = mock 基础设施问题，不是 v2 行为问题
-```
-
-### 收敛保护
-
-```yaml
-rescue:
-  max_rounds: 10
-  convergence_rule: |
-    连续 2 轮无测试进展（green 数没增加）→ 停止
-    输出卡点分析 + 剩余问题清单
-  round_budget: |
-    每轮最多改 5 个文件
-    每轮必须让至少 1 个测试从 red/skip/hung → green，否则视为无进展
-  priority_order: |
-    Phase 1: 修 CRITICAL（编译错误）
-    Phase 2: 修 HIGH-INFRA（mock 基础设施，让 hung 测试能跑）
-    Phase 3: 修 HIGH-LOGIC（逻辑测试，让 red 变 green）
-    Phase 4: 修 MEDIUM（widget 测试，让 red 变 green）
-    每个 phase 完成后才进入下一个
-```
-
-**为什么 HIGH-INFRA 优先于 HIGH-LOGIC？**
-
-hung 的测试 = 行为没被验证 = 重写目标的盲区。如果跳过 mock 修复直接改逻辑，可能 20 个 widget 行为从来没被检验过。先让所有测试能跑（pass 或 fail），再让它们变绿。
-
-### 完整 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

package/spec/foundation-hardening.md

@@ -1,178 +0,0 @@
-# Spec: DNA 基础设施加固
-
-## Metadata
-- Interview: 5 rounds, final ambiguity 20%
-- Date: 2026-04-15
-- Status: 设计完成
-
-## Goal
-
-全面审视 DNA 基础设施的薄弱点，从可靠性 → 治理能力 → 工具体验三个维度加固，对标 OMC 补齐差距，为组织级治理奠基。
-
-## 成功标准
-
-- 零已知缺陷
-- 关键路径测试覆盖 >90%
-- 可交付给他人使用（不需要作者盯着）
-- 架构可扩展（后续治理功能不需要重构基础）
-
-## 优先级: 可靠性 → 治理能力 → 工具体验
-
----
-
-## 第一阶段: 可靠性加固
-
-### R1: Config 编译前验证
-
-**问题**: `dna compile` 绕过 `validateDNA()`，无效 DNA 静默编译。
-
-**修复**: sync/compile 入口统一调用 `validateDNA()`，验证失败 → 报错退出。
-
-### R2: Trace 并发安全
-
-**问题**: 多 session 同时 `appendFile` 写 trace.jsonl，可能 corrupt。
-
-**修复**:
-- 方案 A: trace 文件按 session 隔离 → `trace-{date}-{sessionId}.jsonl`
-- 方案 B: 使用 `O_APPEND` 原子追加（POSIX 保证 ≤ PIPE_BUF 的 write 原子性）
-- 推荐 A（简单、和 OMC 一致）
-
-### R3: IR 版本迁移
-
-**问题**: `ir_version` 字段存在但无迁移逻辑。破坏性 IR 变更让旧 hook 静默失败。
-
-**修复**:
-- dna-hook 检测 `ir_version` 不匹配 → 输出明确错误 "IR version mismatch, run dna sync"
-- 保留 fail-open（不 block，但警告）
-
-### R4: 原子写入
-
-**问题**: state 写入使用普通 `writeFile`，进程中断可能 corrupt。
-
-**修复**: 参考 OMC 的 temp+rename 模式（state.ts 已有，确认所有写入路径都用）
-
-### R5: Stale 状态清理
-
-**问题**: 无超时机制，残留 state 文件永久存在。
-
-**修复**: 参考 OMC 的 2h stale 超时。SessionStart 时检查并清理过期 state。
-
----
-
-## 第二阶段: 治理能力
-
-### G1: Session 隔离
-
-**问题**: `.dna/state/` 无 session 目录，多 session 状态冲突。
-
-**修复**: 
-```
-.dna/state/
-  sessions/
-    {sessionId}/
-      workflow.json
-      trace.jsonl        ← session 级 trace
-  trace/
-    trace-{date}.jsonl   ← 全局 trace（合并视图）
-```
-
-### G2: MCP Server — 状态管理工具
-
-DNA 的第一个 MCP server，提供：
-- `dna_state_read(mode)` — 读 workflow/enforce 状态
-- `dna_state_write(mode, data)` — 写状态
-- `dna_trace_query(filters)` — 查询 trace 数据
-- `dna_workflow_status()` — 当前 workflow 进度
-
-实现方式: 参考 OMC 的 `createSdkMcpServer()`，注册为 Claude Code plugin 的 MCP server。
-
-### G3: MCP Server — 编译工具链
-
-- `dna_compile(config_path)` — 编译 DNA 到 IR
-- `dna_sync()` — 一键同步（等同 CLI dna sync）
-- `dna_generate(description)` — 从描述生成 DNA
-
-让 LLM 直接操作 DNA，不需要 Bash 中转。
-
-### G4: 状态驱动 Enforce
-
-**问题**: enforce 只读静态 IR，不能根据 workflow 运行时状态调整。
-
-**修复**: enforce 接受 state 参数，支持条件规则：
-- "rescue 第 3 轮后放宽 scope"
-- "scan 步骤只读，fix 步骤可写"
-- 当前 WorkflowState 已传入 enforce，但只用于 checkpoint。扩展为通用条件。
-
-### G5: MCP Server — 远程治理通信（后续）
-
-- 上报审计数据到中央服务器
-- 拉取企业级 DNA 策略
-- 接收策略更新推送
-
-这是 Phase 7 的企业治理基础，当前只做架构预留。
-
----
-
-## 第三阶段: 工具体验
-
-### U1: dna sync 自动检测升级
-
-sync 时对比 `_template_version`，有更新 → 提示升级。
-
-### U2: 冷启动优化
-
-**问题**: 每次 hook 调用 spawn Node.js ~50ms。
-
-**方案**:
-- 短期: IR 缓存到内存（MCP server 常驻进程时自然解决）
-- 长期: MCP server 内置 enforce，hook 调用走 MCP 而非 spawn
-
-### U3: 错误信息优化
-
-hook 报错时输出人类可读的提示而非 JSON。`dna verify` 输出友好的健康报告。
-
----
-
-## 与 OMC 差距对标
-
-| 差距 | 对应任务 | 阶段 |
-|------|---------|------|
-| 无 session 隔离 | G1 | 二 |
-| 无 MCP 工具 | G2 + G3 | 二 |
-| 每次冷启动 | U2 | 三 |
-| 纯静态 enforce | G4 | 二 |
-| trace 并发 | R2 | 一 |
-| 无原子写入 | R4 | 一 |
-| 无 stale 清理 | R5 | 一 |
-
-## DNA 已有优势（保持）
-
-| 优势 | 不要丢 |
-|------|--------|
-| 纯函数 enforce | 不引入 I/O 到 enforce.ts |
-| 编译时 IR | 保持预编译模式，MCP 是补充不是替代 |
-| Fail-open | 所有错误 → allow |
-| 确定性 | 同 IR + 同 input = 同 output |
-
-## Acceptance Criteria
-
-### 第一阶段
-- [ ] dna compile/sync 编译前调用 validateDNA()
-- [ ] trace 写入 session 隔离或原子追加
-- [ ] IR 版本不匹配 → 明确警告
-- [ ] 所有 state 写入使用 temp+rename
-- [ ] SessionStart 清理 >2h stale state
-- [ ] 测试覆盖所有修复
-
-### 第二阶段
-- [x] .dna/state/sessions/{id}/ 目录结构
-- [x] MCP server 提供 state_read/write/trace_query
-- [x] MCP server 提供 compile/sync/generate
-- [x] enforce 支持 WorkflowState 条件规则
-- [x] 远程通信架构预留（接口定义，不实现）
-
-### 第三阶段
-- [x] dna sync 自动检测模板版本 + 提示升级
-- [x] MCP server 常驻进程复用完整 hook runtime + IR cache
-- [ ] Claude settings hook 零进程调度（后续性能优化）
-- [x] 错误信息人类可读