intentdna 1.7.4 → 1.8.0

package/spec/sync-target-plan.md

@@ -0,0 +1,158 @@
+# Sync Target Plan
+
+Status: active draft
+Last updated: 2026-06-04
+
+## Purpose
+
+This spec defines the boundary that should keep `dna sync` from accumulating every harness-specific rule.
+
+`sync` should orchestrate the operation. Target planners and adapters should decide what concrete artifacts a harness needs.
+
+## Problem
+
+The current CLI has grown from one proven surface:
+
+```text
+DNA -> Claude Code markdown / agents / skills / settings / hooks
+```
+
+Codex support now adds real artifacts through `dna sync --codex`:
+
+```text
+DNA -> AGENTS.intentdna.md
+    -> Codex plugin hooks
+    -> .codex/hooks.json
+    -> .codex/config.toml trust state
+    -> codex-policy-map.json
+    -> codex-adapter-evidence.json
+```
+
+This is the right product milestone, but it proves the need for a target-planning boundary. Without that boundary, each new capability can add another `runSync` branch.
+
+## Desired flow
+
+```text
+load / validate DNA
+  -> compile ConstraintIR and WorkflowIR
+  -> select sync target planners
+  -> produce SyncTargetPlan[]
+  -> write planned artifacts
+  -> record lock / summary / evidence
+```
+
+## Draft target plan shape
+
+```ts
+type SyncTarget = "claude_code" | "codex_cli";
+
+interface SyncTargetPlan {
+  target: SyncTarget;
+  mode: "write" | "remove" | "dry_run";
+  artifacts: PlannedArtifact[];
+  capability_report: AdapterCapabilityReport;
+  evidence_plan: EvidencePlan;
+  warnings: string[];
+  unsupported: string[];
+}
+
+interface PlannedArtifact {
+  kind: string;
+  path: string;
+  ownership: "intentdna_owned" | "owned_block" | "merge_preserve_user" | "diagnostic";
+  tracked_by_lock: boolean;
+  write?: () => Promise<void>;
+  remove?: () => Promise<void>;
+}
+
+interface EvidencePlan {
+  primary: "RuntimeDecisionEvent" | "none";
+  diagnostic_artifacts: string[];
+  classification: "enterprise_evidence" | "diagnostic_only" | "unsupported";
+  notes: string[];
+}
+```
+
+These interfaces are planning contracts, not committed implementation APIs yet.
+
+## Target responsibilities
+
+### CLI responsibilities
+
+- Resolve input files.
+- Validate DNA.
+- Run compile pipeline.
+- Select target planners from CLI flags.
+- Execute target plans.
+- Track generated outputs and lock entries.
+- Print warnings and unsupported gaps.
+
+The CLI should not need to understand whether a capability is implemented through a hook, settings file, plugin manifest, policy map, or generated instruction.
+
+### Target planner responsibilities
+
+- Decide which artifacts are needed.
+- Preserve user-authored files and hooks.
+- Encode install-mode semantics.
+- Produce capability support reports.
+- Produce evidence plans.
+- Keep unsupported gaps explicit.
+
+### Adapter responsibilities
+
+- Map IR channels to concrete harness surfaces.
+- Generate harness-specific artifacts.
+- Verify ownership/trust assumptions where possible.
+- Emit RuntimeDecisionEvent-compatible evidence through the existing state writer.
+
+## Current target inventory
+
+| Target | Current artifacts |
+|---|---|
+| Claude Code | `CLAUDE.md`, `.claude/agents`, `.claude/skills`, `.claude/settings.json`, `.claude/.mcp.json`, `.dna/compiled/ir.json` |
+| Codex CLI | `AGENTS.intentdna.md`, `codex-plugin/.codex-plugin/plugin.json`, `codex-plugin/hooks/hooks.json`, `.codex/hooks.json`, `.codex/config.toml`, `.dna/compiled/codex-policy-map.json`, `.dna/compiled/codex-adapter-evidence.json` |
+
+## Extraction sequence
+
+### Step 1: Codex target plan wrapper
+
+Codex already has a cohesive adapter function: `compileCodexAdapterArtifacts()`.
+
+The first extraction should wrap that function into a Codex target planner without changing artifact contents.
+
+Acceptance:
+
+- `dna sync --codex` output remains byte-for-byte equivalent except timestamps.
+- Tests for generation, dry-run, remove, preservation, and lock tracking still pass.
+
+### Step 2: Claude Code target plan wrapper
+
+Move existing Claude Code artifact planning behind a planner boundary.
+
+Acceptance:
+
+- Existing Claude Code sync behavior remains backward-compatible.
+- The CLI no longer needs to know the semantic reason for each artifact.
+
+### Step 3: Shared plan execution
+
+Move artifact execution into a shared executor:
+
+```text
+for each target plan:
+  print warnings
+  write/remove artifacts
+  track lockable outputs
+  summarize unsupported gaps
+```
+
+Acceptance:
+
+- Adding a new capability modifies schema/compiler/adapter/reporting, not `runSync` semantic branches.
+
+## Non-goals
+
+- Do not add new adapter targets.
+- Do not turn target plans into a runtime.
+- Do not move policy truth into target plans.
+- Do not hide diagnostic-only evidence behind successful artifact writes.

package/spec/workflow-capability-ir.md

@@ -0,0 +1,153 @@
+# Workflow Capability IR
+
+Status: active draft
+Last updated: 2026-06-04
+
+## Purpose
+
+This spec defines a capability vocabulary for AI-native workflow infrastructure.
+
+It does not require an immediate schema migration. The first use is interpretive: map existing workflow, role, IR, and adapter fields to capability requirements so the system can reason about what a workflow needs and what a harness can actually support.
+
+## Design rule
+
+Templates declare **what deterministic capability a workflow needs**.
+
+Adapters declare **how much of that capability a harness can support**.
+
+The CLI should not encode the business semantics of each capability.
+
+## Capability lifecycle
+
+```text
+workflow template field
+  -> WorkflowCapabilityRequirement
+  -> ConstraintIR / WorkflowIR / verifier specs
+  -> AdapterCapabilityReport
+  -> SyncTargetPlan
+  -> generated artifacts and RuntimeDecisionEvent evidence
+```
+
+## Capability support status
+
+```ts
+type CapabilitySupportStatus =
+  | "supported"
+  | "partial"
+  | "unknown"
+  | "unsupported";
+```
+
+Support is adapter-specific. A capability can be required by a workflow even when a specific harness only supports it partially.
+
+## Draft requirement shape
+
+```ts
+interface WorkflowCapabilityRequirement {
+  id: string;
+  capability: WorkflowCapability;
+  workflow_name: string;
+  step_id?: string;
+  role?: string;
+  source: "workflow" | "role" | "gene" | "verifier" | "adapter";
+  severity: "required" | "recommended" | "diagnostic";
+  evidence_required: boolean;
+  notes: string[];
+}
+```
+
+This shape is a planning contract, not a committed TypeScript API yet.
+
+## Initial capability vocabulary
+
+| Capability | Meaning |
+|---|---|
+| `intent_lock` | The workflow must preserve a clearly scoped user or organization intent across model turns. |
+| `boundary_constraint` | The workflow must constrain read/write/action scope. |
+| `context_control` | The workflow must control what context is required, optional, forbidden, or planning-only. |
+| `tool_policy` | The workflow must allow, deny, warn, or route tool usage by role/step. |
+| `approval_gate` | The workflow must require human or policy approval before a risky action. |
+| `checkpoint` | A step boundary condition must be evaluated after work. |
+| `completion_check` | A step must prove required artifacts or checks before handoff. |
+| `artifact_handoff` | Produced and consumed artifacts must be represented as resolver-backed facts. |
+| `isolation` | Parallel or risky work must run under a declared isolation mode. |
+| `dry_run` | The workflow or adapter must preview writes/actions before committing them. |
+| `rollback_or_compensation` | The workflow must reverse, compensate, or explicitly report irreversible side effects. |
+| `trace` | The workflow needs structured execution trace or lifecycle evidence. |
+| `runtime_decision_evidence` | Decisions must be recorded as RuntimeDecisionEvent-compatible evidence. |
+| `logic_equivalence_validation` | A transformation must prove behavioral or logical equivalence, especially in refactors. |
+
+## Existing field mapping
+
+| Existing field / IR | Capability |
+|---|---|
+| `WorkflowStepDef.prompt` | `intent_lock` |
+| workflow `description` | `intent_lock` |
+| role `scope` | `boundary_constraint` |
+| role `tool_permissions` | `tool_policy` |
+| `WorkflowStepDef.enforce.read_only` | `boundary_constraint`, `tool_policy` |
+| `WorkflowStepDef.enforce.additional_write_paths` | `boundary_constraint` |
+| `WorkflowStepDef.checkpoints` | `checkpoint` |
+| `WorkflowStepDef.completion` | `completion_check` |
+| `WorkflowStepDef.handoff` | `artifact_handoff` |
+| `WorkflowDef.produces` / `WorkflowDef.consumes` | `artifact_handoff` |
+| `WorkflowStepDef.isolation` | `isolation` |
+| `WorkflowDef.default_isolation` | `isolation` |
+| `context_injections` | `context_control` |
+| `context_sources` / `planning_context` | `context_control` |
+| `verifier_specs` | `checkpoint`, `completion_check`, `runtime_decision_evidence` |
+| `RuntimeDecisionEvent` | `runtime_decision_evidence`, `trace` |
+| Codex adapter `unsupported` list | adapter capability gap evidence |
+
+## Refactor equivalence workflow mapping
+
+The current dogfood target is a refactor workflow:
+
+```text
+intent lock
+  -> boundary freeze
+  -> baseline characterization
+  -> rewrite
+  -> equivalence verification
+  -> review
+  -> evidence package
+```
+
+Required capabilities:
+
+| Step | Required capabilities |
+|---|---|
+| intent lock | `intent_lock`, `context_control` |
+| boundary freeze | `boundary_constraint`, `tool_policy` |
+| baseline characterization | `checkpoint`, `completion_check`, `artifact_handoff` |
+| rewrite | `tool_policy`, `isolation`, `trace` |
+| equivalence verification | `logic_equivalence_validation`, `checkpoint`, `runtime_decision_evidence` |
+| review | `approval_gate`, `completion_check` |
+| evidence package | `artifact_handoff`, `runtime_decision_evidence`, `trace` |
+
+## Adapter reporting requirement
+
+Every adapter should report capability support without hiding gaps:
+
+```ts
+interface AdapterCapabilityReport {
+  adapter: string;
+  runtime?: string;
+  capabilities: Record<string, {
+    status: CapabilitySupportStatus;
+    surfaces: string[];
+    evidence_refs: string[];
+    notes: string[];
+  }>;
+  unsupported: string[];
+}
+```
+
+Codex is the active implementation reference. Claude Code remains the proven legacy surface. No additional adapters are implied by this spec.
+
+## Non-goals
+
+- This spec does not add a new runtime.
+- This spec does not replace ConstraintIR.
+- This spec does not make dashboard/report/state a policy source.
+- This spec does not claim support for a capability unless an adapter maps it to a concrete surface and evidence path.

package/spec/agent-dispatch-fix.md

@@ -1,116 +0,0 @@
-# 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 有值