intentdna 1.4.8 → 1.4.9

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/dist/hooks/enforce.js

@@ -383,10 +383,10 @@ function checkPathAgainstScope(rolesScopeMap, input, filePath) {
             continue;
         const writeGlobs = entry.scope.write ?? [];
         if (writeGlobs.length === 0) {
-            return blockOutput(`[Intent DNA]: Role '${entry.role_name}' has no write permission (path: ${filePath})`);
+            return allowOutput(`WARN [Intent DNA]: Role '${entry.role_name}' has no write permission (path: ${filePath}). Merge-time scope gate will filter.`);
         }
         if (!checkWriteAllowed(relativePath, writeGlobs)) {
-            return blockOutput(`[Intent DNA]: Role '${entry.role_name}' cannot write to '${filePath}' (allowed: ${writeGlobs.join(", ")})`);
+            return allowOutput(`WARN [Intent DNA]: Role '${entry.role_name}' cannot write to '${filePath}' (allowed: ${writeGlobs.join(", ")}). Merge-time scope gate will filter.`);
         }
         return null; // Role matched, write allowed
     }

package/dist/runtime/workflow-runner.js

@@ -258,11 +258,13 @@ function generateGroupExecution(group, stepMap, options, plan) {
         }
         // Merge worktrees back (escalate on conflict)
         lines.push("");
-        lines.push("  # Merge worktrees back to main branch");
+        lines.push("  # Scope gate + merge worktrees back to main branch");
         for (const id of group.step_ids) {
+            const step = stepMap.get(id);
             const varId = sanitizeForBash(id);
             const safeId = sanitizeForShell(id);
             lines.push(`  if [ "$STEP_${varId}_STATUS" -eq 0 ]; then`);
+            lines.push(`    scope_gate "${safeId}" "dna-wt-${safeId}" "${step.role}" "${safeId}"`);
             lines.push(`    merge_worktree "dna-wt-${safeId}" "${safeId}"`);
             lines.push("  fi");
         }
@@ -336,6 +338,77 @@ function generateMergeWorktreeFn() {
         "",
     ];
 }
+/**
+ * Generate the scope_gate bash helper function.
+ * Filters out-of-scope file changes from a worktree branch before merging.
+ * Reads role write scope from .dna/compiled/ir.json, reverts unauthorized files,
+ * and writes trace entries for each violation.
+ * Fail-open: never prevents merge from proceeding.
+ */
+function generateScopeGateFn() {
+    return [
+        "# Scope gate: filter out-of-scope changes before merge (three-layer defense L3)",
+        "scope_gate() {",
+        '  local name="$1" branch="$2" role="$3" step_id="$4"',
+        '  local ir_path="${PROJECT_ROOT}/.dna/compiled/ir.json"',
+        "",
+        '  [ ! -f "$ir_path" ] && return 0',
+        "",
+        "  # Read write scope globs for this role from IR",
+        "  local allowed_globs",
+        "  allowed_globs=$(jq -r --arg role \"$role\" \\",
+        "    '.roles_scope_map[]? | select(.role_name == $role) | .scope.write[]?' \\",
+        '    "$ir_path" 2>/dev/null)',
+        "",
+        "  # No scope defined — allow all changes",
+        '  [ -z "$allowed_globs" ] && return 0',
+        "",
+        "  # Get files changed by this branch vs main",
+        "  local changed",
+        '  changed=$(git diff --name-only "$MAIN_BRANCH...$branch" 2>/dev/null)',
+        '  [ -z "$changed" ] && return 0',
+        "",
+        "  local rejected=()",
+        '  while IFS= read -r file; do',
+        '    [ -z "$file" ] && continue',
+        "    local allowed=false",
+        '    while IFS= read -r glob; do',
+        '      [ -z "$glob" ] && continue',
+        "      # Prefix matching (consistent with enforce.ts globToPrefix)",
+        '      local prefix="${glob%%\\**}"',
+        '      if [ -z "$prefix" ] || [[ "$file" == "${prefix}"* ]]; then',
+        "        allowed=true",
+        "        break",
+        "      fi",
+        '    done <<< "$allowed_globs"',
+        '    if [ "$allowed" = false ]; then',
+        '      rejected+=("$file")',
+        "    fi",
+        '  done <<< "$changed"',
+        "",
+        '  [ ${#rejected[@]} -eq 0 ] && return 0',
+        "",
+        "  echo \"[Intent DNA] Scope gate: ${#rejected[@]} file(s) outside role '${role}' scope, reverted:\"",
+        '  printf "  - %s\\n" "${rejected[@]}"',
+        "",
+        "  # Revert out-of-scope files in worktree branch",
+        '  for file in "${rejected[@]}"; do',
+        '    (cd ".dna/worktrees/${name}" && git checkout "$MAIN_BRANCH" -- "$file") 2>/dev/null || true',
+        "  done",
+        '  (cd ".dna/worktrees/${name}" && git add -A && git commit --amend --no-edit) 2>/dev/null || true',
+        "",
+        "  # Write trace entries for scope violations",
+        '  local trace_dir="${PROJECT_ROOT}/.dna/state/trace"',
+        '  mkdir -p "$trace_dir" 2>/dev/null || true',
+        '  local trace_file="${trace_dir}/trace-$(date +%Y-%m-%d).jsonl"',
+        '  for file in "${rejected[@]}"; do',
+        "    printf '{\"trace_id\":\"%s\",\"event\":\"ScopeGate\",\"agent_type\":\"dna-%s\",\"step\":\"%s\",\"decision\":\"warn\",\"reason\":\"Merge-time scope gate reverted out-of-scope file\",\"target_path\":\"%s\",\"duration_ms\":0,\"timestamp\":\"%s\"}\\n' \\",
+        "      \"$(uuidgen | tr '[:upper:]' '[:lower:]')\" \"$role\" \"$step_id\" \"$file\" \"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)\" >> \"$trace_file\"",
+        "  done",
+        "}",
+        "",
+    ];
+}
 /**
  * Generate transition check code after all groups execute.
  */
@@ -404,9 +477,10 @@ export function compileWorkflowToShell(plan, options) {
     // run_agent function
     lines.push(...generateRunAgentFn(opts));
     lines.push("");
-    // merge_worktree function (only if needed)
+    // merge_worktree + scope_gate functions (only if needed)
     if (needsWorktreeSupport(plan)) {
         lines.push(...generateMergeWorktreeFn());
+        lines.push(...generateScopeGateFn());
     }
     // Main execution
     if (plan.retry.max_retries > 0) {

package/package.json

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

package/spec/parallel-isolation.md

@@ -19,8 +19,31 @@ DNA 模板可声明并行执行策略和文件隔离策略，编译到 workflow-
 | Schema 声明 | step 属性 + parallel block 双支持 | 灵活性 + 简洁性兼顾 |
 | auto 模式 | 编译时 scope overlap 检测 | DNA 独有能力——Role scope 编译时已知 |
 | merge 策略 | escalate only (MVP) | 冲突报告给用户，不自动解决 |
+| scope.write 语义 | merge-time accept filter | 不是运行时 block rule，是合并时的产出过滤器 |
 | 模型差异 | 暂不考虑 | 后续扩展 |
 
+## 设计哲学：默会知识与三层防御
+
+参考波兰尼（Michael Polanyi）默会知识理论：意图不能被规则穷尽，但可以通过适当的"身体"来实现。
+
+**核心洞察**：`scope.write: ["test/**"]` 表达的是模板作者的**意图**（"这个角色只该写测试文件"），不应该被实现为运行时工具拦截（显性规则，不完备），而应该被实现为物理隔离 + 出口把关（身体 + 审查）。
+
+### 为什么工具拦截不可靠
+
+路径级 scope enforce 通过拦截工具检查文件路径（Write/Edit/Bash/MCP...）。但写文件的工具不可枚举——每出现一个新工具就是一个绕过点。这是认识论问题，不是实现问题：显性规则永远追不上默会知识的丰富度。
+
+### 三层对应
+
+| 层 | 时机 | 机制 | 波兰尼对应 | 可靠度 |
+|---|---|---|---|---|
+| **工具控制** | PreToolUse | `tool_permissions.deny` — 禁止工具本身 | 显性知识（可完全条文化） | 高——工具名有限可枚举 |
+| **过程提示** | PreToolUse | 当前 scope enforce（保留为软防线） | 辅助线索（from） | 低——最佳努力，不可依赖 |
+| **出口把关** | Merge time | **scope gate 过滤 git diff** — 只接受 scope 内改动 | 焦点判断（to） | **确定性——基于实际产出** |
+
+scope.write 的真正语义：**merge 时的 accept filter**，不是运行时的 block rule。
+
+agent 在 worktree 内有完整读权限（理解上下文）和写自由（不被微管理），但只有符合角色意图的产出才能合并回主分支。如同管理者不盯每次敲键盘，而在 review 时评估产出。
+
 ## Schema 设计
 
 ### isolation 取值
@@ -152,6 +175,39 @@ git worktree remove .dna/worktrees/fix-auth 2>/dev/null
 git worktree remove .dna/worktrees/fix-api 2>/dev/null
 ```
 
+### Merge-time scope gate
+
+合并前过滤越权改动（scope.write 的真正执行点）：
+
+```bash
+# scope gate: 只接受 scope 内的改动
+scope_gate() {
+  local branch=$1 role=$2
+  # 获取该 role 的 write scope globs (从 IR 读取)
+  local allowed_globs=$(read_scope_globs "$role")
+  
+  # 检查所有改动文件
+  local changed=$(git diff --name-only HEAD...$branch)
+  local rejected=()
+  for file in $changed; do
+    if ! matches_any_glob "$file" $allowed_globs; then
+      rejected+=("$file")
+      # 在 worktree 中 revert 越权改动
+      (cd .dna/worktrees/$branch && git checkout HEAD -- "$file")
+    fi
+  done
+  
+  if [ ${#rejected[@]} -gt 0 ]; then
+    echo "[Intent DNA] Scope gate: ${#rejected[@]} file(s) outside scope, reverted:"
+    printf "  - %s\n" "${rejected[@]}"
+    # trace 记录越权尝试 → 表观遗传反馈
+  fi
+}
+
+scope_gate "fix-auth" "surgeon"
+scope_gate "fix-api" "surgeon"
+```
+
 ## Constraint IR 扩展
 
 ```typescript
@@ -175,11 +231,14 @@ interface WorkflowIR {
 
 | DNA 概念 | 在并行隔离中的角色 |
 |---|---|
+| **Role scope.write** | **merge-time scope gate 的输入**——决定哪些改动可以合并回主分支 |
 | **Role scope** | auto 模式的编译时 overlap 分析输入 |
+| **tool_permissions.deny** | 工具级控制（可靠层）——reviewer 不能用 Edit |
 | **Handoff** | 并行 step 的 artifact 传递（已实现） |
 | **Threshold codon** | 可声明 `parallel_without_isolation == false` 硬约束 |
 | **Attract codon** | `attract: worktree_per_task` 软提示（保留兼容） |
-| **Hooks enforce** | worktree 内 scope enforce 仍生效 |
+| **Hooks enforce (PreToolUse)** | 保留为过程提示（辅助软防线），不作为安全保障依赖 |
+| **表观遗传** | scope gate 越权记录 → trace → epigenetic marker 反馈 |
 
 ## 不做
 
@@ -187,6 +246,7 @@ interface WorkflowIR {
 - LLM 模型差异适配（暂不考虑）
 - context budget 管理（已由独立进程 + Handoff 解决）
 - container 级隔离（过度设计）
+- sparse-checkout（限制读权限会破坏 agent 理解上下文的能力）
 
 ## Acceptance Criteria
 
@@ -197,9 +257,12 @@ interface WorkflowIR {
 - [ ] Compiler: parallel block 展开为 step + depends_on
 - [ ] workflow-runner: isolation=none 行为不变（向后兼容）
 - [ ] workflow-runner: isolation=worktree 生成 git worktree 生命周期脚本
+- [ ] workflow-runner: merge 前执行 scope gate（过滤越权改动）
 - [ ] workflow-runner: merge 冲突时 escalate（报告 + 保留分支）
+- [ ] scope gate: 越权改动被 revert + trace 记录
 - [ ] E2E: 两个并行 step 写不同目录，auto → none，正确执行
 - [ ] E2E: 两个并行 step 写相同目录，auto → worktree，隔离执行 + merge
+- [ ] E2E: agent 写越权文件，scope gate 过滤 + trace 记录
 - [ ] Dogfood: flutter-rewrite rescue workflow 可配置 isolation
 - [ ] IR: ParallelGroup 包含 isolation + scope_overlap 信息
 - [ ] 测试覆盖所有新增代码