intentdna 1.7.4 → 1.8.0

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

@@ -1,432 +0,0 @@
-# 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 暂时忽略，不作为当前阻塞项。