intentdna 1.5.16 → 1.5.17

package/dist/signals/index.js

@@ -0,0 +1,117 @@
+import { extractGeneFromReason } from "../evolution/trace-bridge.js";
+function toSignalEvidence(result) {
+    const payload = {
+        target: result.target,
+        evidence: result.evidence,
+        exit_code: result.exit_code,
+        artifact: result.artifact,
+        message: result.message,
+    };
+    return Object.values(payload).some((value) => value !== undefined) ? payload : undefined;
+}
+function normalizeExternalSignals(adapterName, payload) {
+    const items = Array.isArray(payload) ? payload : [payload];
+    return items.map((item, index) => {
+        const timestamp = item.timestamp ?? new Date().toISOString();
+        return {
+            id: item.id ?? `${adapterName}:${item.source}:${timestamp}:${index}`,
+            kind: "external",
+            status: item.status,
+            timestamp,
+            gene: item.gene,
+            source: item.source,
+            detail: item.detail ?? item.message ?? item.evidence,
+            adapter: adapterName,
+            evidence_payload: toSignalEvidence(item),
+        };
+    });
+}
+export const newapiSignalAdapter = {
+    name: "newapi",
+    adapt(payload) {
+        return normalizeExternalSignals("newapi", payload);
+    },
+};
+export const gatewaySignalAdapter = {
+    name: "gateway",
+    adapt(payload) {
+        return normalizeExternalSignals("gateway", payload);
+    },
+};
+export function adaptSignals(adapter, payload) {
+    return adapter.adapt(payload);
+}
+export function traceToSignals(traces) {
+    const signals = [];
+    for (const trace of traces) {
+        const gene = extractGeneFromReason(trace.reason);
+        if (!gene)
+            continue;
+        const status = trace.decision === "allow" ? "positive" : trace.decision === "warn" ? "neutral" : "negative";
+        signals.push({
+            id: trace.trace_id,
+            kind: "trace",
+            status,
+            timestamp: trace.timestamp,
+            gene,
+            source: trace.event,
+            detail: trace.reason,
+        });
+    }
+    return signals;
+}
+export function verifierResultsToSignals(results) {
+    const signals = [];
+    for (const result of results) {
+        const genes = result.source_genes && result.source_genes.length > 0 ? result.source_genes : [undefined];
+        const status = result.status === "pass" ? "positive" : result.severity === "warn" ? "neutral" : "negative";
+        for (const gene of genes) {
+            signals.push({
+                id: `${result.verifier_id}:${gene ?? "unknown"}:${result.timestamp}`,
+                kind: "verifier",
+                status,
+                timestamp: result.timestamp,
+                gene,
+                source: result.verifier_id,
+                detail: result.message ?? result.evidence,
+                evidence_payload: toSignalEvidence(result),
+            });
+        }
+    }
+    return signals;
+}
+export function signalsToOutcomes(signals, dnaId = "default") {
+    const feedbackByGene = new Map();
+    for (const signal of signals) {
+        if (!signal.gene)
+            continue;
+        const effect = signal.status === "positive"
+            ? "helped"
+            : signal.status === "negative"
+                ? "hindered"
+                : "neutral";
+        const existing = feedbackByGene.get(signal.gene) ?? [];
+        existing.push({
+            gene: signal.gene,
+            effect,
+            detail: signal.detail ?? signal.evidence_payload?.message ?? signal.source,
+        });
+        feedbackByGene.set(signal.gene, existing);
+    }
+    const outcomes = [];
+    for (const [gene, feedback] of feedbackByGene) {
+        const hindered = feedback.filter((item) => item.effect === "hindered").length;
+        const helped = feedback.filter((item) => item.effect === "helped").length;
+        outcomes.push({
+            id: `signal_${gene}_${feedback.length}`,
+            timestamp: new Date().toISOString(),
+            dna_id: dnaId,
+            action: `signals:${gene} helped=${helped} hindered=${hindered}`,
+            active_genes: [gene],
+            constraints_applied: [gene],
+            success: helped >= hindered,
+            constraint_feedback: feedback,
+        });
+    }
+    return outcomes;
+}

package/dist/templates/code-review-pipeline.dna.yaml

@@ -71,6 +71,10 @@ roles:
 
 contexts: {}
 
+verifier_policy:
+  allow_command_prefixes:
+    - npm test
+    - npx tsc --noEmit
 
 workflow:
   name: review-cycle

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

@@ -137,6 +137,9 @@ context_files:
     test_runner:
       - "docs/behavior/{{ARGUMENTS}}.md"
 
+verifier_policy:
+  allow_builtin_asserts:
+    - clean_working_tree
 
 roles:
   # ── Phase 0/3: behavior-lock 角色 ──
@@ -244,10 +247,13 @@ roles:
       write: [".dna/specs/**"]
     instructions:
       - "REQUIRED FIRST: Read all context files listed in SKILL.md"
+      - "Treat docs/behavior/blocked_items.md as historical context only, never as the current run verdict"
       - "For each failing, skipped, and hung test: read test code + v1 impl + v2 impl"
       - "Classify each as BUG / UNIMPLEMENTED / INFRA / REMOVED / TEST_BUG (skipped tests are usually UNIMPLEMENTED)"
-      - "Output diagnosis spec with v1 code snippets + v2 current state"
-      - "DO NOT run tests. DO NOT edit code. Analysis only."
+      - "Output diagnosis spec with v1 code snippets + v2 current state + evidence paths"
+      - "If reanalyzing after REQUEST_REANALYSIS, update every reviewer sections_to_fix item and report sections_updated"
+      - "DO NOT include fix prescriptions, implementation order, call-site instructions, or Notes for Surgeon"
+      - "DO NOT run tests. DO NOT edit app code. Analysis only."
 
   analysis_reviewer:
     description: "Reviews analyzer output quality. Read-only."
@@ -261,7 +267,8 @@ roles:
       - "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"
+      - "Verify diagnosis remains evidence-only: no fix prescriptions, implementation order, call-site instructions, or Notes for Surgeon"
+      - "Output a structured verdict block with verdict, artifact_reviewed, sections_to_fix, evidence_paths, confidence, and summary"
 
   test_runner:
     description: "Runs tests and reports progress delta."
@@ -517,16 +524,19 @@ workflows:
 
           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, skipped, and hung test:
+          2. Read test results from last behavior-lock run. If no structured baseline artifact exists, state exactly which file(s) you used as the baseline source.
+          3. Treat docs/behavior/blocked_items.md as historical context only. It must never be used as the current run verdict.
+          4. For each failing, skipped, and hung 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 / UNIMPLEMENTED / INFRA / REMOVED / TEST_BUG
-          4. Write .dna/specs/diagnosis-$ARGUMENTS.md with:
+          5. Write .dna/specs/diagnosis-$ARGUMENTS.md with:
              - For each failure: v1 code snippet + v2 current state + classification
-             - NO fix prescriptions (surgeon decides how to implement)
+             - Evidence paths for every classification
+             - NO fix prescriptions, implementation order, call-site instructions, or "Notes for Surgeon"
              - NO running tests (analysis only)
+          6. If this is a reanalysis after REQUEST_REANALYSIS, read the reviewer verdict first, update every section listed in sections_to_fix plus the summary table, and report sections_updated in your final response. Reanalysis is not successful unless the spec artifact is rewritten.
         handoff:
           produces:
             - type: file
@@ -545,10 +555,23 @@ workflows:
           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
+          4. Enough evidence detail for surgeon to act without adding fix prescriptions?
+          5. Diagnosis remains evidence-only: no implementation order, call-site instructions, or "Notes for Surgeon"?
+
+          Output exactly one structured verdict block:
+          ```json
+          {
+            "verdict": "APPROVE" | "REQUEST_REANALYSIS",
+            "artifact_reviewed": ".dna/specs/diagnosis-$ARGUMENTS.md",
+            "sections_to_fix": ["section ids or titles; empty when approved"],
+            "evidence_paths": ["paths that justify the verdict"],
+            "confidence": "high" | "medium" | "low",
+            "summary": "brief reason"
+          }
+          ```
+
+          APPROVE → diagnosis complete.
+          REQUEST_REANALYSIS → sections_to_fix must be passed back to analyze. docs/behavior/blocked_items.md is historical context only and must not be treated as the current run verdict.
         handoff:
           consumes:
             - type: file

package/dist/templates/full-pipeline.dna.yaml

@@ -100,6 +100,10 @@ roles:
 
 contexts: {}
 
+verifier_policy:
+  allow_command_prefixes:
+    - npm test
+    - npx tsc --noEmit
 
 workflow:
   name: dev-pipeline

package/dist/templates/mobile-dev.dna.yaml

@@ -52,6 +52,11 @@ genes:
 
 contexts: {}
 
+verifier_policy:
+  allow_command_prefixes:
+    - dart analyze
+    - flutter test
+
 roles:
   mobile_dev:
     description: Mobile developer

package/hooks/hooks.json

@@ -6,7 +6,7 @@
     "SubagentStop": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "dna-hook SubagentStop", "timeout": 3 }] }],
     "PreCompact": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "dna-hook PreCompact", "timeout": 3 }] }],
     "Notification": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "dna-hook Notification", "timeout": 3 }] }],
-    "Stop": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "dna-hook Stop", "timeout": 3 }] }],
+    "Stop": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "dna-hook Stop", "timeout": 45 }] }],
     "SessionStart": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "dna-hook SessionStart", "timeout": 5 }] }]
   }
 }

package/package.json

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

package/spec/control-plane-convergence-handoff-2026-04-24.md

@@ -0,0 +1,432 @@
+# Spec: Control Plane Convergence Handoff
+
+## Metadata
+- Date: 2026-04-24
+- Status: 阶段性完成，可切新 session
+- Scope: control-plane positioning + legibility assets + verifier contract + normalized local signals
+- Note: `dna import` / harness reverse-parser 暂时不作为当前主线阻塞项
+
+---
+
+## 一、原始目标
+
+本轮工作的核心目标不是继续扩概念，而是把 Intent DNA 的方向和实现收束成一条更明确的治理主线：
+
+**legibility assets → verifiers → signals → evolution**
+
+同时完成两件事：
+
+1. 从项目叙事上明确：Intent DNA 是 **agent control plane / governance layer**，而不是业务系统执行平台。
+2. 从代码上把现有零散能力收束成一套更像 control plane 的一等公民 runtime contract。
+
+---
+
+## 二、已完成的文档调整
+
+### 1. 项目定位已重新收口
+
+已修改：
+- `README.md`
+- `DESIGN.md`
+- `ROADMAP.md`
+
+### 2. 已完成的定位调整内容
+
+#### README
+- 明确 Intent DNA 是 **declarative control plane for AI agent behavior**
+- 明确它治理的是运行在现有系统之上的 agent，而不是重写业务系统本体
+- 新增更清晰的 design principles
+- 收紧多框架表述，避免和 roadmap 冲突
+
+#### DESIGN
+- 新增 **边界定义**
+  - 业务系统是被操作对象
+  - agent 是执行者
+  - Intent DNA 是上层控制面
+- 新增 **设计哲学**
+  - 先治理，后执行
+  - 先声明，后编译
+  - 先约束，后能力
+  - 先闭环，后规模
+  - 先可插拔，后绑定
+- 把固定 Portkey 叙事收口为 **Gateway / Signal Layer**
+- `.intentdna/` / `.dna/` 表述统一为 `.dna/`
+
+#### ROADMAP
+- 当前节点新增：
+  - 强化 agent 可见性
+  - verifier / validator 闭环
+  - signals 接口
+  - 让治理从“约束”走向“可验证闭环”
+- 后续多框架 adapter wording 已和 README 对齐
+
+---
+
+## 三、已完成的代码调整
+
+## Phase 1 — Legibility assets first-class
+
+### 已完成内容
+
+把“agent 在行动前必须理解什么”从散落在 `context_files` 中的约定，升级为 typed schema：
+
+#### 新增 schema
+文件：`src/schema/types.ts`
+
+新增：
+- `LegibilityAssetType`
+  - `required_read`
+  - `repo_map`
+  - `manifest`
+  - `artifact_index`
+- `LegibilityAsset`
+- `LegibilityAssetMap`
+- `IntentDNA.legibility_assets`
+- `ConstraintIR.legibility_assets`
+
+#### 验证层
+文件：`src/schema/validate.ts`
+
+新增：
+- `legibility_assets` 的结构验证
+- role / workflow 引用校验
+- 非法 asset type 校验
+- `tags` 校验
+
+#### 级联层
+文件：`src/compiler/cascade.ts`
+
+新增：
+- `CascadedDNA.legibility_assets`
+- 级联时高优先级 DNA 的 `legibility_assets` 覆盖低优先级
+
+#### 编译层
+文件：`src/compiler/compile.ts`
+
+新增：
+- 把 `legibility_assets` 编译进 IR
+- 自动把 `required_read` 类型映射成兼容的 `context_files`
+- 若已有旧 `context_files`，保持旧字段优先，确保兼容性
+
+#### 运行时消费层
+文件：
+- `src/runtime/skill-adapter.ts`
+- `src/hooks/cli.ts`
+
+行为：
+- `Required_Context` 输出优先读 `legibility_assets.required_read`
+- `Context Gate` 也优先读 `legibility_assets.required_read`
+- 如果没有 `legibility_assets`，自动 fallback 到旧 `context_files`
+
+### 结果
+
+现在项目已经有：
+- typed legibility schema
+- backward-compatible runtime behavior
+- 不破坏旧模板/旧配置/旧 context gate 逻辑
+
+---
+
+## Phase 2 — Verifier contract
+
+### 已完成内容
+
+把 advisory validator 和真正可执行 verifier 分离。
+
+#### 新增 schema
+文件：`src/schema/types.ts`
+
+新增：
+- `VerifierWhen`
+  - `stop`
+  - `post_tool_use`
+- `VerifierSeverity`
+  - `block`
+  - `warn`
+- `VerifierKind`
+  - `checkpoint`
+  - `completion`
+- `VerifierSpec`
+- `ConstraintIR.verifier_specs`
+
+#### 编译层
+文件：`src/compiler/compile.ts`
+
+已完成：
+- 将 workflow step 的 `checkpoints` 编译为 `VerifierSpec(kind=checkpoint)`
+- 将 workflow step 的 `completion` 编译为 `VerifierSpec(kind=completion)`
+- `VerifierSpec` 中记录：
+  - workflow
+  - step
+  - role
+  - severity
+  - source
+  - source_genes（来自 role activates_genes 的 gene hint）
+
+#### runtime state
+文件：`src/hooks/state.ts`
+
+新增：
+- `VerifierResultEntry`
+- `appendVerifierResult()`
+- `readVerifierResults()`
+- `writeVerifierResults()`
+
+数据落在：
+- `.dna/state/sessions/<session>/workflow/verifier-results.json`
+
+并且现在 `readVerifierResults(projectDir)` 已支持跨 session 聚合读取。
+
+#### Stop hook 执行
+文件：`src/hooks/cli.ts`
+
+新增：
+- `runCheckpointVerifier()`
+- `runStopVerifiers()`
+- `clearBlockingVerifierCheckpoints()`
+
+行为：
+- Stop 时会执行 `verifier_specs.when === "stop"`
+- 对 `completion` verifier 执行：
+  - `file_exists`
+  - `file_not_empty`
+  - `file_contains`
+  - `command_success`
+- 对 `checkpoint` verifier 执行：
+  - `clean_working_tree`
+  - `no_test_regression`
+  - `lint_passing`
+  - `build_passing`
+  - 自定义 command
+- 结果写入 verifier-results state
+- 如果有 blocking verifier fail，会优先 block stop
+- 然后把对应 blocking checkpoint 从 `enforceStop()` 的 legacy checkpoint 路径里剔除，避免双重阻断
+
+#### hook 注册层
+文件：`src/runtime/settings-adapter.ts`
+
+已完成：
+- `HookEventKey` 新增 `stop`
+- `HOOK_EVENT_MAP` 新增 `Stop`
+- `detectEnabledEvents()` 在存在：
+  - stop verifiers
+  - checkpoints
+  - handoffs
+  时会启用 `stop` hook
+- 返回值去重
+
+### 结果
+
+现在 verifier 已不再只是“提示要验证”，而是：
+- 可编译
+- 可执行
+- 可落状态
+- 可参与 stop-time 阻断
+
+---
+
+## Phase 3 — Normalized local signals
+
+### 已完成内容
+
+#### 新增 signals 子系统
+文件：`src/signals/index.ts`
+
+新增：
+- `SignalKind`
+  - `trace`
+  - `verifier`
+- `SignalStatus`
+  - `positive`
+  - `negative`
+  - `neutral`
+- `SignalEnvelope`
+- `traceToSignals()`
+- `verifierResultsToSignals()`
+- `signalsToOutcomes()`
+
+#### evolution bridge
+文件：`src/evolution/trace-bridge.ts`
+
+现在：
+- `traceToOutcomes()` 已变成 normalized signals wrapper
+- 新增：
+  - `verifierResultsToOutcomes()`
+  - `mergeOutcomes()`
+
+也就是说，bridge 不再只理解 trace，而开始理解统一 signals。
+
+#### feedback 命令
+文件：`src/cli/commands/feedback.ts`
+
+已完成：
+- 读取 trace
+- 读取 verifier results
+- `--evolve` 时调用 `mergeOutcomes(traces, verifierResults)`
+- 当没有 trace 但有 verifier results 时，也能进入 evolve 路径
+- 错误提示从 only trace 改成 trace + verifier-aware
+
+### 结果
+
+现在 evolution 不再只盯着：
+- block / warn trace
+
+还开始吸收：
+- verifier pass / fail
+- positive / negative / neutral signal
+
+这意味着 epigenetic loop 的输入开始变得完整，而不是只从 friction 学习。
+
+---
+
+## 四、已修改文件清单
+
+### 文档
+- `README.md`
+- `DESIGN.md`
+- `ROADMAP.md`
+
+### Memory
+- `memory/project_signals_newapi_direction.md`
+- `memory/project_ignore_import_feature_temporarily.md`
+- `memory/MEMORY.md`
+
+### 核心代码
+- `src/schema/types.ts`
+- `src/schema/validate.ts`
+- `src/compiler/cascade.ts`
+- `src/compiler/compile.ts`
+- `src/runtime/skill-adapter.ts`
+- `src/runtime/settings-adapter.ts`
+- `src/hooks/state.ts`
+- `src/hooks/cli.ts`
+- `src/evolution/trace-bridge.ts`
+- `src/cli/commands/feedback.ts`
+- `src/signals/index.ts`
+
+### 测试
+- `test/schema.test.ts`
+- `test/compiler.test.ts`
+- `test/handoff.test.ts`
+- `test/hooks-harness.test.ts`
+- `test/checkpoint.test.ts`
+- `test/completion-audit.test.ts`
+- `test/hooks-cli.test.ts`
+- `test/hooks-state.test.ts`
+- `test/trace-bridge.test.ts`
+- `test/feedback.test.ts`
+- `test/signals.test.ts`
+
+### 计划文件
+- `/Users/samuel/.claude/plans/zippy-riding-wolf.md`
+
+---
+
+## 五、验证结果
+
+### 已通过
+
+#### build
+- `npm run build` ✅
+
+#### 本轮主线定向测试
+最后一次综合定向测试：
+- 12 个 test files
+- 280 passed
+- 0 failed
+
+#### 独立 verifier agent 结果
+- PASS
+- high confidence
+- 0 blockers
+
+它确认：
+1. `legibility_assets` + `context_files` 兼容链路成立
+2. `verifier_specs` 编译 / stop-time 执行 / state capture 成立
+3. normalized signals + feedback/evolve 消费 traces + verifier results 成立
+
+---
+
+## 六、当前未做 / 留给新 session 的内容
+
+### 1. `dna import` / reverse-parser 暂时忽略
+这条线不是当前 control-plane convergence 的主线。
+`test/import.test.ts` 对应的是 reverse import / harness2dna，不作为当前阻塞项。
+
+### 2. verifier 还没有继续扩到更多阶段
+当前已完成的是：
+- `when: stop`
+
+还没继续做：
+- `post_tool_use` verifier execution
+- `pre_handoff` verifier execution
+- `post_step` verifier execution
+- 更强的 evidence schema
+- verifier → audit event 更完整联动
+
+### 3. signals 目前还是本地最小闭环
+当前已完成：
+- traces
+- verifier results
+- normalized signals
+- feedback/evolve consumption
+
+还没继续做：
+- newapi / gateway adapter
+- 外部 signal ingestion
+- cost / latency / ROI / usage 指标接入
+- richer signal taxonomy
+
+### 4. 全量 `npm test` 还有既有仓库漂移问题
+说明：
+- 不是本轮 control-plane convergence 主线引入的阻塞
+- 主要是 `test/import.test.ts` 和当前仓库实际 `.claude/agents/` 生成物不一致
+- 当前 memory 已记录：这条线暂时忽略
+
+---
+
+## 七、建议的新 session 起点
+
+如果开新 session，建议按下面顺序推进：
+
+### 路线 A：继续 verifier 深化（推荐）
+优先级最高。
+
+建议下一步：
+1. 把 `VerifierWhen` 扩展到：
+   - `post_tool_use`
+   - `pre_handoff`
+   - `post_step`
+2. 让 verifier evidence 更结构化：
+   - target
+   - evidence
+   - exit code
+   - artifact path
+   - message
+3. 把 verifier result 接入 audit event
+4. 让 `settings-adapter` 继续自动启用必要 hook
+
+### 路线 B：继续 signals 外部化
+如果你先要做功能检查后接 newapi，这条线也适合。
+
+建议下一步：
+1. 给 `src/signals/` 增加 adapter boundary
+2. 定义 newapi / gateway ingestion interface
+3. 增加 metrics/cost/latency signal mapping
+4. 让 normalized signals 不只服务 evolve，也能服务 dashboard / governance
+
+---
+
+## 八、给新 session 的一句话 handoff
+
+这轮已经把 Intent DNA 从“约束 + hooks + feedback”推进成了更清晰的治理闭环骨架：
+
+**legibility assets → verifiers → signals → evolution**
+
+并且这三段最小可用实现已经落下、通过 build、通过定向测试、通过独立 verifier。
+
+当前最值得继续推进的是：
+- verifier 深化
+- signals 外部化
+
+`dna import` / reverse-parser 暂时忽略，不作为当前阻塞项。