docs: add Floatboat mechanism adoption plan

[oratis]

Summary

基于 Floatboat / Selfware 调研，提出用其治理机制优化 DeepCode 的整体方案 —— docs/FLOATBOAT_ADOPTION_PLAN.md。本 PR 只含提案，不含实现，等待评审后再拆实施 PR。

与 docs/CODEX_ALIGNMENT_PLAN.md 的关系是正交补充，不取代：alignment plan 收敛"运行时语义统一"（谁执行、怎么恢复、怎么中断），本文收敛"工作区治理"（凭什么能改、改了什么、怎么撤销）。

核心论点

DeepCode 缺的不是能力，是治理面。有三件事今天在 DeepCode 里表达不出来（均已对源码核实）：

#	说不出的话	为什么
1	".env 永远不许读"	权限规则是工具维度的，路径只有前缀比对，而 file_path 通常是绝对路径 —— Read(.env*) 匹配不到任何真实调用（config/permissions.ts parseRule/primaryInput）。沙箱层的 denyRead 能表达，但未配置时 resolveSandboxMode 落到 danger-full-access（sandbox/index.ts:69），且硬编码 deny 只覆盖 home 下凭证库，不覆盖项目内 .env
2	"上一轮 agent 改了什么、怎么撤销"	session 是消息流不是变更账本；MEMORY.md 存的是事实不是变更；snapshots 有但缺"意图 + 回滚句柄"索引
3	"这个 runtime 能写哪里、哪些动作要确认"	initialize() 的 capabilities 只声明协议特性，不声明权限与写边界（protocol/src/runtime.ts:112）

采纳 / 拒绝

	机制	优先级
✅	File Contract — 路径 × 读/写/执行 × 三态权限契约	P0
✅	Change Ledger — 带 rollbackHint 的 append-only 变更账本	P0
✅	Capability Manifest — 运行时可查询的写边界与确认动作	P1
✅	Combo — 把已完成的 thread 蒸馏成 SKILL.md 草稿	P1
✅	Trigger Profile — cron job 携带自己的权限档位	P1
❌	.self 自执行分发 / Tacit 被动观察 / FloatIM 跨组织网络 / loopback HTTP runtime / 日历集成	拒绝，理由见 §3

三个关键设计决定

1. 单向取严 — finalVerdict = mostRestrictive(toolVerdict, pathVerdict)。File Contract 只收紧不放宽，因此不可能降低现有安全性；无契约文件时 pathVerdict 恒为 no-match，结果与今天逐用例相等。
2. 只改 dispatcher 一处 — 遵守 AGENTS.md "All tool execution must pass through one explicit permission policy"。四个客户端零改动即生效；evaluatePermission 第三参数可选，签名向后兼容。
3. 诚实的能力边界 — Bash 明确不做静态路径推断（解析 shell 不可靠，假装能拦截比不拦截更危险）。契约含 read: deny 而沙箱关闭时，启动打印告警并在 doctor 长期可见。文档措辞必须是"减少误触与提示注入的可利用面，真正的隔离仍来自沙箱"，不得宣传成秘密防护。

独立的安全副产品

CronJob 今天不携带任何权限信息 —— 凌晨 3 点无人值守触发的任务，拿到的是与交互式会话相同的档位。方案提出 onApprovalRequired 默认 'deny'（拒绝该次调用并继续，而非静默放行或永久挂起）。这条不依赖方案其余部分，可作为 PR 0 独立先落地。

落地路线

8 个独立可合可 revert 的 PR，风险从低到高排序。建议的最小有价值切片是 PR 0 + 1 + 3（三个都低风险、无相互依赖）；File Contract 接入 dispatcher（PR 2）是唯一需要谨慎评审的一步。

文档同时写明了 4 条未解假设（契约默认值该多严、ledger 是否默认开、/combo 要不要调模型、与 alignment plan 的先后），需要评审拍板。

Test plan

纯文档 PR，无代码改动。

• node scripts/check-docs.mjs — Documentation consistency checks passed
• npx prettier --check docs/FLOATBOAT_ADOPTION_PLAN.md — All matched files use Prettier code style
• 文档引用的 16 个源码路径 / 文档路径逐个核实存在
• §0 三条"表达不出来"的论断均对 packages/core 源码逐条核实（非推测）
• pnpm typecheck / pnpm test / pnpm build — N/A（未触碰代码）

Documentation

• 新增了 docs/FLOATBOAT_ADOPTION_PLAN.md

§6 列出了实施后需要对 docs/security-model.md 威胁模型表追加的 3 条新威胁与 1 条增强，含残余风险声明；实施 PR 落地时同步更新。

Release notes label

• release-notes:internal — 设计提案，不出现在用户可见 changelog

Checklist

• PR 标题是 conventional commits 格式
• 所有 commits 都是 conventional commits 格式
• 添加了对应测试 — N/A（纯文档提案；每个采纳项的测试边界已写进文档）
• CI 全绿（待 CI 运行）

Related

调研依据见独立 PR https://github.com/oratis/deepcode/pull/235（`docs/research/floatboat.md`）。两个 PR 相互独立，可任意顺序合并 —— 本文档内的 research/floatboat.md 链接在两者都合并后生效。

🤖 Generated with Claude Code