Dairn

Adaptive Engineering Governance for Humans and AI Agents
自适应工程治理 · 可验证的质量保障 · 持续演进的项目工程记忆

让任何开发者、任何 Coding Agent，都能在最小必要治理成本下持续交付、验证和改进软件。

Dairn 不接管 Agent 的推理与编码过程；它让工程约束、真实检查、质量目标、历史决策和可信证据独立于 Agent 长期存在。

GitHub · 构建指南 · 治理指南 · MIT License

项目状态（截至 2026-10-24）：本 README 同时呈现当前可用的 MVP 和目标架构，以 2026-10-24 的 Analyzer 破坏性更名批次为代码核对基线。[Current] 表示已在源码中实现、有对应命令与测试；[Planned] 表示尚未落地，示例不可直接照搬执行。Dairn Analyzers 命名已落地：dairn analyzers、.dairn/analyzers.json（dairn.analyzers.v1）、guide impact --analyzer；旧 stubs 命令、.dairn/stubs.json、dairn-stub-v1 协议与 DAIRN_EXPECTED_STUBS_SHA256 已全部删除，无兼容层、无自动迁移。本文不宣称 GitHub 受保护 CI 已在本仓库生产部署。

---

为什么需要 Dairn？

AI 编程工具正在迅速增强。它们能读懂仓库、修改代码、运行测试，也能通过 Skills 和 Subagents 引入架构师、安全审计、测试、性能优化等专业能力。但一个软件项目的长期质量不能只依靠某个 Agent 的上下文和自我报告：

• 改动是否合理：对一个 README 拼写修改和对支付协议的修改，不能要求相同的审查与测试成本。
• 保障是否充分：测试通过，不一定代表公共接口、架构边界、数据安全或性能契约依然成立。
• 结果是否可信：Agent 声称“已经检查通过”，不等于真实 CI 执行，更不等于独立人工批准。
• 知识是否连续：Agent、开发者、仓库结构不断变化，过去的设计取舍、失败教训和技术债需要保留其来源与有效性。
• 治理是否值得：治理不能只增加流程、报告、等待时间和维护负担；必须证明它带来了实际的质量与效率收益。

Dairn 的回答不是再做一个 Agent Harness，而是在现有 Harness、Git、CI、SCM 与工程工具之上建立一层轻量、可验证、可演进的工程治理。

Dairn 与 Agent Harness 的边界

Agent Harness（Claude Code、Codex 等）	Dairn
组织模型推理、工具调用、上下文与代码修改	分析变更、约束风险、制定验证要求
选择并执行 Skills / Subagents	判断何时需要哪些专业能力，给出参与计划
执行命令并汇报结果	验证检查记录、证据来源和适用范围
优化当前任务的完成过程	保护跨 Agent、跨 PR、跨版本的长期工程质量

Dairn 不调用大模型、不替换 IDE、不接管代码修改、不另建 Agent 推理循环。没有 AI Agent，它也应该可以运行确定性检查并验证工程事实。

核心理念

1. Minimum Sufficient Governance（最小充分治理）：只执行当前风险与受信策略确实要求的保障，不把每个任务变成完整流程。
2. Evidence over Claims（证据优于声明）：记录真实执行、输入范围、工具与报告摘要；不把自然语言结论当成机器证明。
3. One Source of Truth（单一事实源）：代码属于 Git，审批属于 SCM，构建事实属于 CI，设计决策属于受控 Specs/ADR；Dairn 提供引用与派生视图，不复制第二套状态账本。
4. Agent-Agnostic（不绑定 Agent）：Claude Code、Codex、其他 Harness、人类开发者都可以消费相同的治理信息。
5. Quality Improvement, Not Score Chasing（质量改进而非刷分）：保护架构不变量、检测回归、观察趋势，连同治理开销一起衡量实际收益。
6. Composable, Optional Workflow（可组合、按需协作）：Check、Analyzer、Handoff 等基础能力独立可用；Work、Grill、Spec 和专项 Review 按任务需要加入。

---

整体架构（目标形态）

flowchart TD
    DEV["Developer / Claude Code / Codex / Any Harness"]
    SRC["Git · Specs · ADR · SCM · CI · Runtime Signals"]
    CTX["Project Context & Engineering Memory"]
    IMPACT["Change Impact & Risk Analysis"]
    GOV["Adaptive Governance Planner"]
    ANALYZE["Dairn Analyzers & Analysis Suites"]
    QUALITY["Quality Fitness & Improvement"]
    PARTICIPATION["Agent / Skill Participation Plan"]
    CHECK["Independent Check Plan & Check Run"]
    EVIDENCE["Evidence · Attestation · Trusted Gate"]
    FEEDBACK["Governance Feedback / Refactoring"]
    HANDOFF["Agent Handoff"]

    DEV --> IMPACT
    SRC --> CTX
    CTX --> IMPACT
    IMPACT --> GOV
    GOV --> ANALYZE
    GOV --> PARTICIPATION
    ANALYZE --> QUALITY
    QUALITY --> GOV
    GOV --> CHECK
    CHECK --> EVIDENCE
    QUALITY --> FEEDBACK
    EVIDENCE --> FEEDBACK
    CTX --> HANDOFF
    FEEDBACK --> CTX
    HANDOFF --> DEV
    PARTICIPATION --> DEV

图中包含已实现与规划能力；具体成熟度见下表。图中的反馈关系不是一个允许 Quality 或 Agent 覆盖受信 Policy 的循环：策略下限由受信来源决定，Quality 和 Agent 只能提供观测、缺口与改进建议。

当前能力成熟度

能力	状态	现有入口 / 说明
Cosmopolitan QuickJS APE、npm/PyPI/离线分发、项目 Launcher	[Current]	CLI 与运行时资产、可离线使用
项目 init / adopt / detect / doctor / validate	[Current]	项目接入、完整性与结构检查
Specs、Skills、Workflow 建议、Facts / Git Impact	[Current]	docs、skills、workflow、guide
风险分类与独立 Check / Run Evidence	[Current]	scope、check、evidence
Gate、Approval、Ed25519 Attestation 与发布辅助脚本	[Current — deployment verification pending]	代码有独立验证链；生产信任还取决于真实受保护 CI/SCM 配置
零仪式 Agent 交接	[Current · MVP]	handoff，不需 .dairn/ 或 Work
Adaptive Governance Planner	[Current · MVP]	governance plan/explain：最小保障计划、真实缺口、模块×检查矩阵
Capability Assessment 与仓库发现	[Current · MVP]	governance assess、adopt --discover --plan；工具可见性不等于执行成功
Refactor Contract 与已知债务比较	[Current · MVP]	refactor plan/status/compare/verify；部分退出条件需专项证明
Governance Feedback	[Current · MVP]	governance recommend：基于历史 Run 生成待验证假设，不自动调规则
可选 Work / Tasks、Hooks、Grill/Review 工作指导	[Current]	不应成为普通变更运行 Check 的前提
Dairn Analyzers（surface 域）	[Current · 原子更名完成]	analyzers list/templates/doctor/init、guide impact --analyzer；.dairn/analyzers.json（dairn.analyzers.v1）；旧 stubs 接口已删除、无兼容层
Analysis Suite / analyze run	[Current · MVP]	`analyze run
Report Adapters 与报告导入	[Current · MVP]	analyze import：SARIF 2.1.0 / JUnit XML / Dairn JSON → dairn.quality-observation.v1，来源恒为 unverified-import
Quality Fitness	[Current · MVP]	quality fitness：dairn.quality-goals.v1 目标 × 本地 Observation → PASS/FAIL/UNKNOWN/ADVISORY；缺数据绝不猜 PASS
Quality Fitness & Continuous Improvement	[Current · MVP]	可信基线比较、Coverage XML/LCOV 适配、长期趋势与债务收益
Capability-Aware Agent / Skill Participation	[Current · MVP]	触发面扩展（影响事件、检查失败）、输出契约消费与成本预算
Project Engineering Memory 的完整 Context Resolver	[Planned]	来源索引、当前适用性、任务/专业定向上下文；已有事实和 Handoff 是基础

测试与部署状态：基线前一提交 61d1db7 的提交说明报告“容器 141 项回归通过，原生五组测试退出码 0”；基线提交 0e62a11 本身是 CI Windows 环境中 Git 2.56 升级引发的集成回归修复，未附带新的容器回归记录。以上均为提交作者的测试记录，不是本 README 的独立复测结论。本仓库当前 main 仍未开启分支保护，Rulesets 为空；提交 CI 模板、Signer/Publisher 代码本身不构成已经上线的受保护证据链。

---

快速开始：当前可用功能

安装

Dairn 的 CLI 命令名为 dairn。npm 包为 @moorefu/dairn（unscoped dairn 曾被 npm 以与既有包过于相似为由拒绝），PyPI 包为 dairn。

渠道	安装示例	环境
npm	npm install -D @moorefu/dairn	Node.js 18+
npm 预发布	npm install -D @moorefu/dairn@next	Node.js 18+
PyPI	python -m pip install dairn	Python 3.10+
PyPI 预发布	python -m pip install --pre dairn	Python 3.10+
GitHub Release	下载对应平台的离线制品（APE/ZIP/tgz/Wheel）	自带 APE 与启动器

如果尚未发布正式版本，请使用预发布通道，或在 Releases 中选择实际存在的版本；安装命令不代表对应版本当前一定已在注册表发布。建议生产环境固定精确版本并校验制品摘要。

npm 本地安装可使用 npx dairn 调用，或通过 npm exec -- dairn 运行已安装版本。项目初始化后，优先使用项目内 Launcher，而不是让 Agent 临时安装一个全局版本。

试用零仪式交接：handoff

在已有 Git 仓库中运行：

# PATH / npm 已安装版本
npx --no-install dairn handoff

# 显式指定 Git 基线
npx --no-install dairn handoff --base origin/main

# 适合 Agent 解析的结构化输出
npx --no-install dairn handoff --json

handoff MVP 不需要 .dairn/、不需要 Work、默认不写入文件、不联网，也不执行测试。它可总结当前分支和 HEAD、最近变更、staged/unstaged/untracked 文件、当前本地可见的检查证据、阻塞信息与建议，并标明数据来源和限制。

也可以显式输出文件：

npx --no-install dairn handoff --out .dairn/tmp/handoff.md

此输出是只读交接摘要，不是 CI 证明或正确性保证。它无法读取编辑器中尚未保存的内容，也不会凭空知道其他设备上尚未同步的工作。

初始化一个示例项目

# 先确认 CLI 已安装（此处的 dairn 指已安装的命令）
dairn version

# 创建一个 Go 示例项目
dairn init --root ./demo --name demo --stack go --sample

# 初始化后通过项目内 Launcher 执行
a=./demo/.dairn/bin/dairn
"$a" doctor --root ./demo
"$a" validate --root ./demo
"$a" check --root ./demo --all

在 Windows 下使用 demo\.dairn\bin\dairn.cmd。检查会使用项目配置的真实工具链；Go 普通测试可能需要 Go 工具链，Go race/CGO 不属于默认验收。

接入已有项目：先发现，再决定是否写入

先在 Git 仓库中观察项目，不要让 Dairn 直接覆盖现有 README、CI 和工程配置：

# 本地 Dairn 命令已安装；以下在目标仓库根目录执行
dairn detect --root .

# 新增：只读探测技术栈、已有 CI 标志、测试工具标记，并输出接入计划
dairn adopt --root . --discover --plan

# 明确检查计划后，再决定是否真正接入
dairn adopt --root .

# 接入后优先调用项目内 Launcher
./.dairn/bin/dairn doctor --root .
./.dairn/bin/dairn validate --root .
./.dairn/bin/dairn guide impact --base origin/main --root .

adopt --discover --plan 不写入仓库；扫描到 go.mod、pom.xml 或 .github/workflows/ 只表示存在这些文件，不代表测试命令已可运行。adopt 写入模式应先在工作分支审阅变更；已经由 Dairn 管理的项目使用 upgrade --plan，而不是再次 adopt。

现在即可试用 Adaptive Governance [Current · MVP]

下面命令在已接入 Dairn、具有 Git Commit、能解析 origin/main 的目标仓库内执行。项目内 Launcher 负责定位固定版本；--base 是本地存在的 Git Ref，可以使用明确的提交 SHA。

# 显示风险、必须覆盖的模块×检查、可本地快跑的项、必须留给 CI 的项
dairn governance plan --base origin/main

# 解释每项保障需求的来源；计划本身不代表任何 Check 已通过
dairn governance explain --base origin/main

# 机器可读，便于 Harness 按需读取
dairn governance plan --base origin/main --json

# 检查当前环境是否发现了所需工具（不是实际验证通过）
dairn governance assess --risk L2 --json

# 运行真实的项目 Check；应在完成本次改动后执行
dairn check --base origin/main

# 只读交接：连带最近本地证据的来源、陈旧和不确定性
dairn handoff --base origin/main --json

Git 的影响范围要以已提交变更为准。 当前 Planner 使用 base..HEAD 的路径作为输入：未提交的工作区变更不会自动出现在该 Plan 的 change_paths 中；提交或正确限定 Source 后再评估。handoff 则会显示工作区的 staged/unstaged/untracked 路径，两者用途不同。

governance plan 的 ready-to-execute 仅表示所需执行器已经配置，不等于检查通过；governance assess 的 detected 仅表示命令入口可探测，不等于测试已运行，也不等于 ci-verified。强制放行必须由可信 Check、Evidence、SCM 和 CI 证明。

可选：从现有运行记录观察治理成本 [Current · MVP]

# 默认查看近期历史；可显式指定整数天数，如 90
dairn governance recommend --window 90 --json

当 Check Run 样本不足时返回 insufficient-evidence，不会硬凑出推荐。当前反馈实现会提出慢检查、重复运行及高失败比例相关假设；失败比例并不能单独证明 Flaky，必须进一步核实根因后才能修改策略，且不会自动削弱检查要求。

---

当前执行能力与长期目标如何协作

Dairn 当前已能生成治理计划、运行真实 Check、核查工具链、保持重构契约并提供 Handoff。未来增加 Analyzer / Fitness / Agent Participation 后，将由统一的保障需求驱动，而非强制执行一条固定的多 Agent 流程。

当前可执行的最短路径 [Current]：

dairn handoff --base origin/main
dairn governance plan --base origin/main
dairn governance assess --risk L1
dairn check --base origin/main

当前可用的新分析命令：

# 分析器目录、模板接入与显式 surface 精确影响分析
dairn analyzers list
dairn analyzers init --template python --id py-api --apply
dairn guide impact --base origin/main --analyzer py-api

# 受控执行：生成 advisory Analysis Run（不是 Check Run）
dairn analyze run py-api --base origin/main
dairn analyze run --suite service-quality --base origin/main

# 只读导入已有报告（SARIF/JUnit/Dairn JSON；恒为 unverified-import）
dairn analyze import ci-sarif --artifact reports/security.sarif

# 质量目标 vs 本地观察的 advisory 判定
dairn quality fitness --json

# 专业能力参与建议（不启动任何模型）
dairn capability plan --base origin/main

仍属目标 [Planned] 的命令：

# 依据长期目标的可信基线比较（当前 Fitness 为 local-only）
dairn quality fitness --base origin/main --trusted-baseline

# 定向交接项目工程记忆（现有 handoff 尚无 --for）
dairn handoff --for security.threat-analysis

变更场景	现在可直接试用	目标能力增强 [Planned]
README / 文档小改	L0 计划 + 实际 lint；无强制 Work	自动文档 Fitness，减少无意义专家调用
普通功能 / Bug Fix	L1 计划、Check、Workflow/Skills、Handoff	API/测试分析器、质量基线与任务定向上下文
鉴权、支付、协议修改	L2 完整检查矩阵、SCM 审批要求	安全分析器 + 威胁建模能力参与
分阶段跨模块重构	Refactor Contract、已知债务/新增回归区分	架构 Fitness、迁移趋势和债务收益分析
多 Agent 接手	真实 Git 状态与本地证据交接	按专业能力检索有效架构决策与质量记忆

原则：Plan 决定应做什么；Analyzers/Check 负责产生事实；Quality Fitness 判断质量目标；Agent 只负责专业执行；可信 Gate 独立计算是否可放行。

Adaptive Governance：从风险出发，而不是从流程出发

Dairn 将变更风险、治理深度和交互成本分开处理：

维度	含义	不代表什么
L0 / L1 / L2	变更风险等级及最低保障	不是 Agent 的信心评分
G0 / G1 / G2 / G3	治理深度；G3 面向重大事件/事故	不是组织成熟度
Zero-ceremony / Guided / Assured	交互方式和实际需要的流程支持	不是放宽安全约束的开关

例如，高风险变更可以不创建 Work Ledger，但不能因此跳过必要的 CI 或审批。

Governance Planner [Current · MVP]

确定性的 dairn.governance-plan.v1 已实现。当前它从项目策略、Git 变化、模块重要性和已登记的 Refactor Contract 生成所需保证条件，并形成可以解释的计划。

Project Policy + Git base..HEAD + Module Context
         + Approved Refactor Contracts
                       │
                       ▼
            Governance Plan v1
                       │
      ┌────────────────┼────────────────┐
      ▼                ▼                ▼
Required Checks    Execution Phase   Capability Gaps
(module×check)     local-fast / CI    + SCM Approval

示例（摘录字段，仅演示结构，不代表某次真实运行）：

{
  "schema": "dairn.governance-plan.v1",
  "classification": {
    "risk_floor": "L2",
    "effective_risk": "L2",
    "governance_mode": "G2"
  },
  "requirements": [
    {"id": "api.lint", "module_id": "api", "check_id": "lint", "required": true},
    {"id": "api.unit", "module_id": "api", "check_id": "unit", "required": true},
    {"id": "api.integration", "module_id": "api", "check_id": "integration", "required": true},
    {"id": "api.build", "module_id": "api", "check_id": "build", "required": true}
  ],
  "execution": {
    "local_fast": ["api.lint", "api.unit"],
    "ci_required": ["api.lint", "api.unit", "api.integration", "api.build"]
  },
  "status": "ready-to-execute"
}

计划内容通过 plan_sha256 绑定身份。这是输出结构示意，非可直接提交的完整 Schema。当前规划器重点覆盖 Check 和 Refactor 契约；Quality Goals、Analyzer 和专业 Agent 参与的自动合成仍待实现。

不可混淆的保障边界：

• L0/L1/L2 表示受信策略决定的变更风险下限；不能靠 Agent 自报低风险降级。
• 默认本地快速候选是 lint、unit；完整 ci_required 不因本地跳过而减少。
• 每个模块的每项必需检查必须分别满足；缺少执行器返回 MISSING_CAPABILITY。
• work_required: false 只是说明 Check 无需 Work Ledger；它不免除真实验证或必要的 SCM 审批。
• Planner 本身只输出计划及项目配置来源信息；不会因为输出 ready-to-execute 就赋予可信 CI 权限。

未来将增加 Quality Goal 和 Incident/Organization 的约束合成，但受信策略始终是最低下限。

Dairn Analyzers：传统工程工具的统一执行入口 [Current · surface 域已落地]

Analyzer 是唯一正式的工程分析扩展单元。 原子更名已完成：dairn stubs 命令、.dairn/stubs.json（schema:1/surface-analysis/dairn-stub-v1）与 DAIRN_EXPECTED_STUBS_SHA256 全部移除，出现旧配置即报 UNSUPPORTED_LEGACY_ANALYZER_CONFIG，无别名、无自动迁移。当前版本执行 domain=surface 的公共接口分析；报告适配与 Suite 编组属于后续批次。

典型接入对象包括：

分析领域	可复用的现有工具或技术	产出
源码接口	Go AST、Python ast、Java/TypeScript 项目分析脚本	公共符号与签名变化
静态质量	ESLint、Pylint、Checkstyle、SpotBugs、Clippy	规则发现、复杂度、可维护性
架构约束	ArchUnit、依赖图与模块规则	违例、循环依赖、禁止路径
测试	JUnit、pytest、Go test、契约测试	通过、失败、跳过及范围
覆盖率	JaCoCo、Coverage.py、LCOV、Cobertura	行/分支覆盖及分子分母
安全	Semgrep、CodeQL 生成的报告、依赖扫描	风险发现与定位
性能	Benchmark JSON、负载与基准测试	延迟、吞吐、资源消耗与测量条件

Dairn 不重新实现上述工具的全部分析算法。它统一管理可用性、执行边界、输入身份、报告适配、原始摘要和分析结果。

Analyzer 配置（当前实际格式）

以下 JSON 是当前实现的 dairn.analyzers.v1 配置（由 analyzers init --apply 生成；report/scope/inputs 等字段属于后续的 Runner/Adapter 批次，尚未实现）：

{
  "schema": "dairn.analyzers.v1",
  "analyzers": [
    {
      "id": "surface",
      "domain": "surface",
      "mode": "execute",
      "capabilities": ["quality.surface-diff"],
      "execution": {
        "argv": ["go", "run", "tools/dairn/analyzers/go/main.go"],
        "cwd": ".",
        "timeout_seconds": 120
      }
    }
  ]
}

项目分析配置统一放在 .dairn/analyzers.json，项目分析脚本放在 tools/dairn/analyzers/。分析请求为 dairn.analyzer-request.v1，响应为 dairn.surface-result.v1；受信 CI 环境要求外部固定的 DAIRN_EXPECTED_ANALYZERS_SHA256。

dairn analyzers templates                      # 查看 Python/JavaScript/Java/Shell 模板
dairn analyzers init --template python --id py-api --apply
dairn analyzers doctor                         # 只探测本地工具链
dairn guide impact --base origin/main --analyzer py-api

Analysis Run 不等于 Check Run

Analyzer 的执行和结果分三层：

1. Analysis Run：证明 Dairn 观察到了什么执行、什么退出状态、什么报告文件及输入快照。
2. Quality Observation：由适配器对 SARIF、JUnit、Coverage、Dairn JSON 等报告进行标准化，保留规则、范围、样本和原始证据引用。
3. Fitness Verdict / Trusted Gate：结合受信目标和检查矩阵判断是否满足要求；此层不能由 Analyzer 自己决定。

工具成功退出 不代表 零发现；报告缺失 不代表 零漏洞或 100% 覆盖率。外部导入报告若没有可信来源证明，不能自动提升为 ci-verified。

Quality Fitness & Continuous Improvement [Current · MVP]

dairn quality fitness 已落地：读取可选的 .dairn/governance/quality-goals.json（dairn.quality-goals.v1），对目标的 producer analyzer 现场执行或导入，输出 dairn.quality-fitness.v1 判定（PASS/FAIL/UNKNOWN/ADVISORY）。退出码：required FAIL → 1，required 数据不足 → 3。判定是质量层 advisory 结论，PASS 从不构成放行；required 目标的最终放行仍需可信 Check/Evidence/CI 链。

质量不能简化为一个“优秀程度得分”。Dairn 将质量目标分为三种：

类型	保护对象	默认处理
Architecture / Security Invariant	明确不允许破坏的架构与安全边界	在具备可信检查能力后可设为强制
Regression Constraint	新增严重发现、行为兼容、性能退化	需要可比较的基线与充分样本
Trend / Technical Debt	复杂度、耦合、重复、修改热点、技术债	默认观察趋势与给出建议

Quality Goals 示例

目标协议示例（未实现）：

{
  "schema": "dairn.quality-goals.v1",
  "objectives": [
    {
      "id": "check-work-independence",
      "attribute": "modularity",
      "type": "invariant",
      "metric": "architecture.no-path",
      "parameters": { "from": "checks", "to": "work" },
      "producer": "core-dependency",
      "enforcement": "required"
    },
    {
      "id": "complexity-trend",
      "attribute": "maintainability",
      "type": "trend",
      "metric": "complexity.cognitive.max",
      "producer": "complexity-analyzer",
      "enforcement": "advisory"
    }
  ]
}

这里的 producer 只指向 Analyzer，不意味着 Analyzer 可以自行设置风险下限或批准 PR。强制性来自受信 Policy 与 Governance Plan。

Quality Fitness 关注架构约束是否仍然成立、与历史相比是否引入新问题、重构是否真正降低长期成本。对复杂度、覆盖率等代理指标，必须考虑工具版本、规则集、统计范围、环境与采样方法；不可比较时应返回 UNKNOWN 而不是制造改善结论。

渐进重构与技术债 [Current · MVP]

Refactor Contract 已经可以跨 PR 记录重构范围、行为基线、允许的过渡债务和退出条件。它对适用变更只增加保证要求，不能降低 L2 风险。

# 定义/审查重构契约。contract.json 是下面示例的项目文件。
dairn refactor plan --id decouple-core --file contract.json

# 明确允许写入时，再添加到 .dairn/governance/refactors/
dairn refactor plan --id decouple-core --file contract.json --apply

# 查看状态及对照既有 Check Run 的债务基线
dairn refactor status --id decouple-core
dairn refactor compare --id decouple-core --run <run-id>

# 退出条件中未能由当前本地 Run 验证的部分会报告 needs-review
dairn refactor verify --id decouple-core --run <run-id>

例如以下契约声明重构将保持行为、消除旧模块调用方（示例中的 baseline.source_commit 必须替换为真实 Git 完整 SHA）：

{
  "schema": "dairn.refactor.v1",
  "id": "decouple-core",
  "intent": "behavior-preserving",
  "baseline": {
    "source_commit": "<full-git-sha>",
    "contracts": ["unit", "integration"]
  },
  "target": {"properties": ["legacy-callers-removed"]},
  "migration": {
    "strategy": "incremental",
    "exit_conditions": ["no-new-failures-beyond-baseline", "no-legacy-callers"]
  },
  "debt": {"allowed_transitional_items": [], "known_failures": []},
  "paths": ["src/legacy/"]
}

Dairn 将已知失败和本次新增失败区分为 within-baseline / new-failures / signature-drift。无法仅凭本地 Run 证明的退出条件返回 needs-review，不会谎称完成。目前的契约对比以 Check Run 为基础；它还不是完整的静态技术债分析、性能回归平台，也不能取代受信 Gate。为避免误绑定，建议显式传入当前变更对应的 --run <run-id>，不要依赖默认历史记录选择。

完整的质量趋势、重构收益和受控过渡质量预算仍属于 Quality Fitness 的下一阶段。

Capability-Aware Agent & Skill Participation [Current · MVP]

dairn capability plan 已落地：确定性规则把质量目标缺口与安全敏感路径映射为 dairn.participation-plan.v1（needs/gaps/not_selected）。必需能力无提供者时报告 GAP 并以退出码 3 提示；计划不启动模型、不授予权限、不含任何可提升信任的字段。

当某个工程保证目标不能仅靠确定性工具满足时，Dairn 计划推荐合适的专业能力：

• 架构师 Agent：跨模块边界、接口兼容、复杂依赖和重构设计。
• 测试专家 Agent / Skill：关键行为、负向场景、契约测试和质量缺口。
• 安全审计 Agent / Skill：信任边界、鉴权、支付、敏感配置和漏洞分析。
• 性能专家 Agent / Skill：有复现依据的性能回归和资源瓶颈。
• 前后端技术 Skills：适用技术栈的开发实践、测试与接口约束。

参与决策顺序：

Required Guarantees
    ↓
Existing Verified Checks & Analyzer Observations
    ↓
Unmet Capability Requirements
    ↓
Available Skills / Agents / Tool Capabilities
    ↓
Participation Plan（原因、时机、权限、输出、成本）
    ↓
原生 Harness 自主执行或人工选择

优先复用已有的可信机器检查；其次使用主 Agent 已有 Skill；确实需要独立调查、专业能力或上下文隔离时，才推荐只读专家 Subagent。

Dairn 不直接启动模型，不会因为配置中声明存在某个安全 Agent，就认定安全工作已完成。Agent 自己写的“PASS”也不能充当受保护 CI 或 SCM 人工审批。

对于未满足的强制能力要求，输出 GAP；不能在找不到专家时自动降低风险级别。对于简单变更，Participation Plan 可以为空。

Project Engineering Memory：项目自己的工程记忆

Dairn 不把工程记忆等同于“保存聊天记录”。项目真正值得长期保留的是：可追溯的事实、历史设计取舍、架构约束、关键缺陷、真实验证结果，以及这些知识在当前代码版本中的适用性。

工程记忆	当前权威源 / MVP 入口	长期目标
Project Facts	Git、源码、模块清单、Facts、guide impact	版本化的来源索引、语义关联
Change & Handoff	Git、handoff、可选 Work/Tasks	按任务和专业能力裁剪上下文
Decisions & Contracts	维护者的 Specs/ADR、refactor 契约	有效性、冲突和适用范围检测
Assurance History	check / Evidence / CI / SCM	保留强弱来源与当前适用性
Governance Learning	governance recommend 对 Run 的统计假设	治理调整的真实效果与审批闭环
Quality History	现有测试/Check Run；Analyzers 尚待落地	Fitness 趋势、债务热点、性能基线

Project Engineering Memory 是对既有权威来源的可重建视图，而不是要求开发者另填第二套 memory.json。 源代码归 Git、审批归 SCM、真实 CI 归 CI、设计决策归项目原始 Specs/ADR。缓存索引只能引用原始内容及 SHA，不能自称权威。

历史决定可以保留，但旧架构图不能永久冒充当前架构约束；旧性能基准也不应跨环境作为可靠比较值。未来 Context Resolver 应提供来源、Subject、摘要、有效性和不确定性标记。

# 当前可用：获取 Git 变化、本地 Run 证据与已有相关文件引用
dairn handoff --base origin/main --json

# 目标接口 [Planned]：当前尚不可调用
dairn context --module payment
dairn context --change origin/main
dairn handoff --for security.threat-analysis

Check · Evidence · Attestation · Trusted Gate

这一层是 Dairn 与一般 Agent 流程建议的重要区别：把「做过什么检查」与「能否据此放行」分开。

Trusted Policy / Required Checks
                ↓
Independent Check Execution
                ↓
Check Run + Subject + Input Snapshot
                ↓
Evidence Bundle + Raw Digests
                ↓
Isolated Attestation Verification
                ↓
SCM-native Approval + Trusted Gate

当前已有独立 Check、Run Evidence、Bundle、签名验证 CLI 和 Gate 代码；正式可信结果还依赖组织实际配置和验收的受保护 CI、外部固定策略/工具链、受隔离签名密钥和原生 SCM 审批。签名证明来源绑定，不证明软件绝对正确。

证据与信任分层

状态或来源	可以说明什么	不能说明什么
Local Observation	本地观察到真实命令输出与文件摘要	不能代替受保护 CI
Imported Analysis Report	读取了格式正确的报告及其原始内容	不能自行宣称报告来自受信 CI
Protected CI Evidence	在受信环境执行或验证了策略所要求的检查	不能证明未覆盖行为绝对正确
Verified Attestation	使用外部受信公钥验证了声明与绑定	不能自动代替 SCM 人工审批
SCM-native Human Approval	SCM 确认了符合规则的真实授权人	不能代替必需机器 Check

FAIL 或缺少必需证据时，不能降格成“Agent 判断可以继续”。对于来源无法确定的情况，可信 Gate 应保持 INDETERMINATE，并在强制 CI 中以非成功退出处理。

对 CI / SCM 的职责边界

Dairn 支持以现有 GitHub / GitLab 等 SCM 原生机制作为审批事实源；不复制一套“谁批准了 PR”的内部账本。ci/templates/ 中的受保护 CI 工作流模板需要由部署方真正接入、配置分支保护和证据信任根之后，才能宣称生产级保障。

治理反馈与自适应迭代 [Current · MVP]

governance recommend 现在能够读取项目本地历史 Check Run，针对运行耗时、重复执行和失败频率提出谨慎的优化建议。其历史统计不证明因果关系，也不会修改受信策略。

dairn governance recommend --window 90 --json

• 当历史样本少于当前实现要求时返回 insufficient-evidence，不会推断质量收益。
• 能给出 CI_SLOW、REPEATED_RUNS、POLICY_NOISE 之类的待调查提案，但不会修改策略。
• POLICY_NOISE 来自失败频率；失败次数或失败率本身不等于已证明 Flaky 或误报。
• 去重建议必须保留原始必需检查的可信证明，不能用本地缓存冒充 Protected CI。
• 目前只基于本地可读 Run 进行统计；真实缺陷逃逸、返工时长、A/B 效果和跨 CI Provider 的长期评价仍待建设。

完整的 Continuous Improvement 目标是同时衡量质量收益与治理代价，持续删除低价值的工作流步骤与重复检查，而不是不断累积更多规则。

工作流是可选的，不是工程事实的前提

Dairn 已提供 Skills、Specs、workflow recommend、Grill、Tasks、Work、Review、Hooks 和文档同步能力。它们适合复杂设计、长周期重构、跨会话协作，不应成为每次改动的前置手续。

# 返回建议的阶段与 Skills，不启动其他 Agent
dairn workflow recommend "修复支付接口重试时的状态错乱"

# 选用已有 Skills；不是强制使用
dairn skills catalog

dairn skills list

# 可选：针对明确的长期任务记录阶段和证据
dairn work list

最小路径：Edit → Check → (required Review) → CI/SCM。

复杂变更可增加：Orient → Resolve Decisions → Specify → Slice → Implement → Review → Synchronize。

重要区别：workflow recommend 当前按任务描述的关键词给出静态建议，不是已经完成的 Capability-Aware Agent Participation Planner。Agent 自述和 Work 状态不能替代实际 Check / Evidence / SCM 审批。

与 Claude Code、Codex 和其他开发环境集成

Dairn 尽量通过普通 CLI、JSON、Markdown、AGENTS.md 和 SKILL.md 交换信息，而不要求所有 Harness 使用同一种 SDK。

• Claude Code：可以读取 CLAUDE.md / AGENTS.md 与项目 Skills，按需使用 Dairn 的命令和结果。
• Codex：可以读取 AGENTS.md 和 Skills，根据 JSON / Markdown 结果调整具体执行步骤。
• 其他 Harness：能调用 CLI、读取报告和遵守工程规则即可接入。
• 传统开发者/CI：无需 Agent 也可执行检查、查看 Handoff、消费未来质量报告。

Harness 原生的文件与网络权限、工具授权和 Subagent 调度不由 Dairn 替代。第三方 Skill、报告和仓库中的指令文本应按不可信输入处理，不能自动获得更高权限。

推荐的目标项目结构

以下是按需启用后的示意结构，不是初始化一定生成所有文件。

my-project/
├── AGENTS.md                         # 项目自己的 Agent 导航
├── CLAUDE.md                         # 可选的 Harness 入口
├── README.md
├── docs/
│   ├── PROJECT_GUIDE.md              # 项目事实与导航
│   ├── GOVERNANCE_SPEC.md            # Dairn 规范导航
│   └── adr/                          # 可选：长期设计决策
├── .agents/
│   ├── skills/                       # 按需引入的 Skills
│   └── notes/                        # 可选：重要决策与经验
├── .dairn/
│   ├── bin/                          # 项目内 Launcher
│   ├── lock.json                     # 运行时/资产身份
│   ├── launcher.json                 # Launcher 解析信息
│   ├── governance/
│   │   ├── project.json              # 当前项目 Policy 基础
│   │   ├── adaptation.json           # 可选：治理适配（规划）
│   │   ├── quality-goals.json        # 可选：质量目标（规划）
│   │   ├── refactors/                # 可选：渐进重构契约（当前 MVP）
│   │   └── capabilities.json         # 可选：能力映射（规划）
│   ├── analyzers.json                # Analyzer Registry（规划）
│   ├── work/                         # 可选任务协作资料
│   ├── cache/                        # 可删除、可重建的派生缓存
│   └── tmp/                          # 临时报告和上下文
└── tools/dairn/analyzers/            # 项目自有分析包装器（规划）

单事实源原则：提交的是规范与必要的配置；扫描结果、临时运行文件、缓存和 Handoff 派生输出不应无条件全部提交。默认将 .dairn/cache/、.dairn/tmp/ 排除在版本控制之外。是否留存可信 Evidence 应遵照组织的受信存储与保留策略。

在无网络环境使用

Dairn 的运行内核使用 Cosmopolitan QuickJS APE。安装包携带运行时与完整性信息，项目可以选择 Vendored 模式，将已验证的运行时固定在仓库中。

目标项目的 Launcher 解析顺序为：

1. 用户显式指定的 DAIRN_BIN；
2. 项目内 .dairn/runtime/dairn-embedded.com；
3. PATH 中的 dairn；
4. 都不可用时，报告 DAIRN_NOT_AVAILABLE，不自行联网安装。

# 已有 Dairn 项目，在项目根目录预置官方受信运行时与摘要文件后：
dairn upgrade --root . --vendor-runtime .dairn/runtime --apply

# POSIX：以后通过项目 Launcher 运行
./.dairn/bin/dairn doctor

Windows 请使用 .dairn\bin\dairn.cmd。具体离线制品、平台限制、完整性校验和操作说明参见 构建指南。

Agent 安全规则：Launcher 缺失或版本校验失败时，应报告环境阻塞；Agent 不应绕过项目约定，在后台安装另一版本 Dairn 或修改全局环境。

---

设计中的安全与可靠性约束

• 信任必须分层：analysis completed、quality passed、CI verified、human approved 是不同的事实。
• PR 不能自我降低门禁：强制检查、组织质量下限和签名信任根必须来自受信策略，不能接受当前变更对自己的宽免。
• Analyzer 必须安全执行：argv 数组、无隐式 Shell、执行时限、报告大小限制、路径和 Symlink 校验、输入快照、源文件意外修改检测。配置声明 read-only 不等于真实沙箱。
• 必须区分工具执行失败和发现问题：扫描工具的非零退出码需要明确解释；报告缺失、未执行、过期或不可比较不能算 PASS。
• 不以质量总分代替质量目标：架构不变量、行为契约、性能与维护性应分维度评价，并考虑测量口径。
• 专业 Agent 默认建议模式：没有自动启动模型、自动扩大权限或使用 AI 投票替代 SCM Review 的特权路径。
• 工程记忆有时效性：历史决定可保留，但只有仍被当前 Spec、代码及事实支持的约束才能称为当前有效。
• 治理也应被治理：记录多余步骤、误报、耗时、计算成本和无效专家参与，持续减少治理技术债。

路线图

方向	最新状态	重点下一步
Project Bootstrap / Skills / Workflow / Work	[Current]	优化零仪式 UX、减少强制流程依赖
Independent Check / Evidence / Attestation / Gate	[Current — 需真实部署验收]	Protected CI/SCM 配置、端到端签名和发布验收
Handoff	[Current · MVP]	带验证来源的定向上下文、过期检测
Adaptive Governance Planner	[Current · MVP]	融合 Quality Goal / Analyzer Requirement；证明自适应减少无谓执行
Capability Assessment	[Current · MVP]	安全、无副作用的命令发现与真实执行能力区分
Refactor Contract / Technical Debt Baseline	[Current · MVP]	契约检查执行器、Subject/Run 与 Gate 强绑定，质量趋势
Governance Feedback	[Current · MVP]	纠正 Flaky 推断、引入缺陷/返工/成本实证与 A/B
Dairn Analyzers	[Current · A-01]	Runner/Suite/Report Adapter 与 analyze run/analyze import
Quality Fitness & Continuous Improvement	[Planned]	架构 Fitness、SARIF/JUnit/Coverage 导入、质量基线与趋势
Capability-Aware Agent & Skill Participation	[Planned]	发现专业能力、按需参与的建议和输出契约
Project Engineering Memory / Context Resolver	[Planned，已有部分基础]	来源/适用性索引、跨 Agent 有效上下文、拒绝陈旧事实

优先级原则：先验证真实受保护 CI 的信任边界和现有 Planner/Gate 约束一致性，再将新增 Quality 指标绑定到强制门禁。Analyzer 的只读执行与 Agent Capability Discovery 可并行推进。Analyzer 命名已落地（dairn analyzers）；旧 stubs 接口已删除，无兼容层。

小试牛刀：建议先做五个场景

不必先部署完整质量平台，也无需启用所有 Skills。建议在隔离分支或临时项目中，以相同 CI 与工程工具做对照：

场景	操作	应观察的证据	试点问题
L0 最小治理	README 提交后 governance plan --base <sha>	Risk L0，极少额外阶段与必需检查	小改动是否没有多余仪式？
L2 不可降级	修改认证/协议文件，执行 governance plan/explain	完整检查矩阵、SCM 人工审批需求	高风险保障是否被保留？
能力缺口	在隔离项目中故意移除必需检查执行器，运行 governance plan	MISSING_CAPABILITY、非成功状态	缺配置是否会被误认为通过？
渐进重构	新建 refactor 契约并运行 compare/verify	已知失败与新增失败分开，退出条件不明时报 needs-review	是否能管理跨 PR 技术债？
跨 Agent 接手	本地修改、运行检查后执行 handoff --json	Git HEAD/工作区指纹、Run 来源与陈旧标记	是否减少重复摸索？

补充运行 governance assess 和 governance recommend，分别观察当前能力是否真的可用、样本不足时是否拒绝得出过度结论。

参照已编写的试点方案做真实任务 A/B，至少记录：总体耗时、返工、回归缺陷、等待时间、CI 资源消耗、接手时间和治理维护工作量。Dairn 的成功标准不是调用更多 Agent 或输出更多报告，而是以更低的总体成本保持或改善工程保证。

---

从源码构建与测试

注意：本仓库本身是 Dairn 源码，不是一个已经 dairn init 的目标项目。不要在源码根目录直接使用目标项目的 Launcher，也不要把构建输出提交为源码。

# 需要 Python 3.10+ 和项目规定的构建环境
python tools/build.py

# 或者
npm run build

# POSIX：运行源码构建出的 CLI
./dairn.sh version
./dairn.sh docs check

Windows 使用 dairn.cmd。更改 quickjs/core/、quickjs/host/ 或 quickjs/main.mjs 后，需要重新构建运行时才能验证新源码；否则可能误测旧产物。

quickjs.lock.json 固定 QuickJS 运行时来源。构建涉及的完整步骤、离线缓存、平台矩阵和验证命令，参见 BUILDING.md。

核心实现与资源：

路径	说明
quickjs/core/	Dairn 确定性治理逻辑
quickjs/host/	QuickJS Host 的文件、进程与平台接口
quickjs/assets/specs/	分发的规范资源
quickjs/assets/skills/	分发的专业 Skills 与 Agent 导航
quickjs/tests/	QuickJS/Python 集成与平台测试
ci/	CI 模板、Provider 与受保护构建辅助脚本
tools/	构建、验证与开发工具

参与贡献

欢迎围绕以下方向讨论、提交 Issue 或 PR：

• Agent 无关的工程治理协议与 CLI 体验；
• Analyzer Runner、跨语言工具报告 Adapter 和可复用分析模板；
• 可执行 Architecture Fitness Functions、契约与性能回归验证；
• 受信 CI/SCM 证据绑定、负向测试与跨平台可靠性；
• 工程记忆、Agent Handoff、质量反馈与治理成本实证。

贡献原则：提供可运行的测试和真实观察结果；不要通过新增不必要的工作流或文档来替代确定性检查；涉及信任边界的变更必须包含失败/伪造/过期/缺失证据等负向场景。

开始前请阅读 AGENTS.md、BUILDING.md 和 docs/GOVERNANCE.md。

项目与许可证

• 源码：github.com/moorefu/dairn
• 发布版本：GitHub Releases
• npm：@moorefu/dairn
• PyPI：dairn
• 许可证：MIT
• 内嵌组件及第三方许可：licenses/

---

Dairn 不追求替 Agent 做更多事情，而是帮助项目在不断变化的 Agent、团队与工具之间，持续保持明确的工程约束、可核验的真实结果和可积累的质量改进。