跳到主要内容

ADR-003 supplement 2 — milestone 工作流执行 locus 与 gate 工具栈

1. 背景​

ADR-003 锁定了「OpenSpec + Archon + Claude Code 主理 + Codex 实现」的工程实施栈，但未明确每个 milestone 的 Archon workflow 在哪个仓执行、其确定性 gate 用什么工具栈。

M0 启动前置 A3（2026-05-29 Archon V1–V4 协作环境验证）实测暴露两个必须先定的缺口：

  1. 执行 locus 未定：.archon/workflows/milestone-M0.yaml 物理上托管在治理仓（Labs-FinTecAI，本知识/治理库），但 M0 产出（cognition/types.py、SQLite DDL、pytest）属于 FinBayes 工程仓。原 workflow 的 gate 写了治理仓的 npm run verify:kb / npm run derive:check（doc-gate），与工程仓产出混在一个 DAG，语义割裂。
  2. worktree 缺依赖（B4）：Archon 在 fresh git worktree 执行，gitignore 的依赖目录（node_modules / .venv）不随入；bash gate 跑 npm/pytest 因缺依赖 fail（V4 hello-world 实测 Cannot find module 'gray-matter'）。

2. 决策​

项目 owner 拍板（2026-05-29）：

  1. 执行 locus = FinBayes 工程仓。每个 milestone 的 Archon workflow 在工程仓执行（cwd = 工程仓），不在治理仓执行。
    • 治理仓的 doc-gate（verify:kb / derive:check / audit:cross-section）留在治理仓自己的 husky + CI，与 milestone workflow 解耦，不进 milestone DAG。
    • milestone workflow 的确定性 gate 改用工程仓自己的 lint / test。
  2. gate 工具栈 = uv + ruff + pytest（Python 工程仓默认；C-1 按工程仓 pyproject.toml 最终确认）。
    • 依赖安装：workflow 首节点 gate-deps-install（uv sync --dev）在 worktree 内建环境（解决 B4）。
    • 后续所有 bash gate 一律 uv run ...（uv run pytest / uv run ruff / uv run python），复用同一环境。
    • lint gate：uv run ruff check . && uv run ruff format --check .（替代原 doc-gate 的占位）。
  3. 契约托管不变：workflow 契约（可执行 milestone-MN.yaml + 规约 milestone-MN.spec.yaml）仍托管在治理仓 .archon/ 作单一事实源；C-1 启动时同步进工程仓 .archon/ 供工程仓 Archon 读取执行（运行态产物不回治理仓，符合 ADR-003 边界）。
  4. smoke test 例外：hello-world.yaml（通路验证，非 milestone、不产代码）用 worktree.enabled: false 在 live checkout 跑——只验 Archon→shell/npm/git plumbing，不需隔离，亦不需依赖 provisioning。

3. 备选与不选原因​

备选不选原因
workflow 在治理仓执行、产出回工程仓违反 ADR-003「运行态/代码不进治理仓」边界；跨仓写入复杂
worktree 用 copyFiles 拷 .venv 进 worktree跨平台/跨机器脆弱；不如 uv sync 干净可复现
milestone gate 节点全 worktree.enabled:false 在 live checkout 跑牺牲隔离性（M0 实施会写代码，需隔离）；只对 hello-world 这类只读 smoke test 适用
不定工具栈、留 C-1 临时决A3 已暴露缺口，悬而不决会在 C-1 第一节点即 fail，违背「尽早现实检验 spec」

4. 影响与落地​

  • 已落地（2026-05-29，本 supplement 同 commit 前序）：.archon/workflows/milestone-M0.yaml + .archon/specs/milestone-M0.spec.yaml 已按本决策重构（gate-deps-install 首节点 / gate-lint / 全 uv run / 移除 doc-gate / pr-open 写 Curvature-Lab/FinBayes）；archon validate workflows milestone-M0 通过。
  • C-1 执行项：工程仓建 pyproject.toml（uv 管理）+ 建 GitHub repo Curvature-Lab/FinBayes + gh auth + 同步契约进工程仓 .archon/。
  • 对 M1+ 的约束：后续 milestone workflow 一律遵循本 locus + 工具栈约定；M{N}.yaml 首节点为 gate-deps-install，gate 用 uv run。

5. 关联资产​

6. 变更记录​

  • 2026-05-29：首版。承接 M0 启动前置 A3（V1–V4 环境验证）实测暴露的执行 locus + worktree 依赖（B4）缺口，由项目 owner 拍板定 locus=工程仓 + 工具栈 uv/ruff/pytest，落地至 milestone-M0 契约。