本目录记录 AppGenesisForge 模板自身的架构决策——团队机制、流水线、契约同步、Apple 轨等。每个 ADR 一个决策、独立编号、append-only：被后续决策演进的标
Superseded-in-part by+ 指针、正文保留为历史，不删不合并。写新 ADR 用 skillagf-writing-adr。
ADR-000是技术栈的唯一详尽 SSOT（CLAUDE.md## Tech Stack只放版本摘要 + 指回这里）；任何技术栈调整必须新开 ADR。
| # | 决策 | 状态 | 一句话 |
|---|---|---|---|
| 000 | 系统架构基线 | Accepted | 技术栈详尽决策 SSOT（语言 / 框架 / DB / 目录 / 本地开发流程），栈调整必新开 ADR |
| 001 | Multi-instance Worker Pool | Accepted | 同 type ≥2 任务自动 fan-out 多实例并行，pool 上限按角色分档 |
| 002 | Dynamic Workflows 窄引入 | Accepted · 边界由 005 扩展 | 显式触发的多 agent workflow 做高风险 review / 审计（安全实证 + 成本门基底仍有效） |
| 003 | verdict 从 findings 推导 | Accepted · 部分被 010 取代 | code-review verdict 必从 severity 计数推导 + hook 守门，堵「有 Critical 却 approve」 |
| 004 | teammateMode 默认值 | Accepted · 默认值 Superseded-in-part by 022 | split-pane 显示模式选型：默认 auto（2026-07-08 由 iterm2 回退，ADR-022），iterm2 降 opt-in |
| 005 | Workflow 阶段嵌入 | Accepted · agf-understand 阶段被 021 取代 | 把 Dynamic Workflows 从「仅 review / 审计」扩为按交付阶段嵌入的加速层 |
| 006 | 前后端契约同步 | Accepted | OpenAPI = SSOT，前端 orval 生成类型 / hooks / mock，禁手写 fetch / 类型 / mock |
| 007 | Apple 原生技术栈 | Accepted | Swift 6 + SwiftUI + 单一多平台 Xcode 工程（macOS / iOS） |
| 008 | Apple 契约同步 | Accepted | swift-openapi-generator 构建期生成 client，禁手写 URLSession / DTO / mock |
| 009 | Apple 发布流水线 | Accepted | fastlane match 签名 + notarytool 公证 + 四渠道分发 lane |
| 010 | 结构化 verdict 契约 | Accepted | verdict 载体统一到 frontmatter SSOT + 推导硬拦扩到 SIT Audit / QA 客观底线 |
| 011 | 交付流水线提效 | Accepted | 并行 UAT 用例 + 结构化 SIT 门 + 规模分 full / fast lane |
| 012 | 行为规格 + 变更文件夹 | Accepted | OpenSpec 风格活规格 + delta；变更文件夹取代 PRD 作需求入口 |
| 013 | 设计纪律层 | Accepted | 审美判断治理层（AI Tells / 三刻度 / Design Read），补 token 层与机械审查层之间空白；DESIGN.md SSOT 地位背书 |
| 014 | hook 运行时增强 | Accepted · 遥测部分被 026 D6 退役 | profile（AGF_HOOK_PROFILE，ADR-011 fast lane 的机械实现）+ 治理事件留痕 + 减化遥测；仿 ECC run-with-flags bash 等价 |
| 015 | agent Prompt Defense Baseline | Accepted | system prompt 层注入防御（写进 CLAUDE.md 一处、全员继承，非 ECC 67 份重复） |
| 016 | Skill Stocktake | Accepted | 自有 skill 内容质量审计流程（5 维含 Gate 绑定，裁剪 ECC chunk-resume） |
| 017 | Hook 安全扩展 | Accepted | block-no-verify（堵 scan-commit --no-verify 旁路）+ block-config-edit（防 agent 改 lint 配置弱化规则） |
| 018 | enforce-write-scope 运行时门 | Accepted | PreToolUse Edit|Write 读 payload agent_type 按 roles.yaml boundary.write_scope 拦越界写（reviewer/qa/deploy），补 A-F1 |
| 019 | 部署/发布门授权归因 | Accepted | TaskCreated gate-deploy-release-auth 强制 deploy/apple-release 派单含 用户授权: 归因（归因+审计+摩擦层，非硬门），补 A-F4 |
| 020 | 回派熔断 / 强制升级归因 | Accepted | TaskCreated gate-redo-fuse 数 feature 的 blocking 评审报告，≥阈值（默认 3）强制升级 tech-lead 归因（熔断豁免: sentinel），补 A-F3 |
| 021 | 代码理解引擎（Deeply Understand / codemap） | Accepted · 替换 005 的 agf-understand 阶段 | Python 原生（tree-sitter 多语言 + SQLite 图谱 + 影响分析 + dashboard）替换 agf-understand workflow，成接手遗留代码必选项 |
| 022 | Agent Teams 上游依赖硬化 | Accepted · Supersedes-in-part 004 | teammateMode 默认回退 auto（iterm2 fail-blocking）+ teammate model-pin resume 丢失的文档化 / 纪律缓解 |
| 023 | 诚实层（deny 非回归 + claims-audit + known-limitations 三态 + static/executed） | Accepted | 对标 claude-code-harness：agf-deny-baseline.sh（deny 收缩硬阻断）+ agf-claims-audit.sh（声称↔现实硬阻断，消灭 written≠working）+ docs/known-limitations.md（强制强度 + 证据三态诚实 SSOT）+ sit-precheck static/executed advisory |
| 024 | 模块级可达性 advisory（codemap orphans / 写了没接线） | Accepted · wiring-check 流程门被 026 D2 退役（orphans 子命令保留） | codemap 加 orphans 子命令 + agf-wiring-check.sh advisory 报零 imports 入边的代码模块；诚实定粒度=模块（codemap 无 call-graph → 函数级不可判）、Web-only、不进硬门；对标 harness enforcelink/rulecoverage 空壳门的真实版 |
| 025 | 实例生命周期（过门即关，不复用） | Accepted · 细化 001 | 消 idle 僵尸：实例最后一道可回派门通过后即逐实例关（reviewer/qa=fan-in / dev=UAT），不复用（复用=context bleed 且 teammate 无法清上下文，查证）、新任务 fresh spawn |
| 026 | 模板结构性精简（体检第 4 步） | Accepted · 阶段 1+2（D2-D7）已实施 v6.26.0/v6.27.0，剩 D1 待渠道；D3 安装 TUI 部分被 027 局部逆转 | 7 项决策分阶段：codemap 拆独立包（D1，待渠道）· advisory 层合并单入口 + wiring-check 退役为手动子命令（D2）· setup TUI 三脚本退役、入口统一「install-to-existing + /agf-init」（D3）· preset 补 web-only/apple 维度 + 按轨联删（D4）· review-sweep 退役（D5）· 遥测三件套退役（D6）· tasks/board 视图收敛（D7）；依据 2026-07-10 体检报告 |
| 027 | 重纳入安装 TUI（局部逆转 026 D3） | Accepted | 恢复 agf-install.sh + agf-tui.sh（薄 wrapper，从 8e56d86 复原）；test-install.sh 新增 preset 一致性 + 非 TTY 降级两条防漂移护栏机械锁死 D3 的删除理由；启动 TUI（agf-team-start.sh）保持退役 |
| 028 | 团队分屏就绪探测 + it2 引导 | Accepted · 补充 022 | 补 auto 唯一盖不住的「iTerm2 缺 it2 → 没分屏」缺口：可复用双轴探测脚本(机器能力 + 当前终端 → 6 verdict)+ /agf-init 报诊断并征同意后 uv tool install it2；保持 auto 默认、只读不改配置 |
| 029 | codemap 复用校验门 + 符号语义层 | Accepted | 三轨符号级指纹（signature/body 骨架/semantic）+ reuse/duplicates 子命令 + review 复用审计门（warning 档）+ adapter 填 signature/summary；延续 021/024；Python/TS/Java、advisory 非硬门 |
| 030 | AI 代码膨胀观测层 | Accepted | 死代码 advisory（vulture/knip，缺则 skip）+ Rule of Three/YAGNI 写进 coding.md；增长仪表盘 + 删除任务化二期；补 024 模块级之外的符号级死代码 |
被后续决策扩展或部分取代的 ADR 保留不删（append-only 历史）：
- Dynamic Workflows：002（窄引入：仅 review / 审计）→ 005（扩为按阶段嵌入的加速层）→ 026 D5（唯一预制 saved workflow
agf-review-sweep退役；高风险深审改 Review pool 维度分工 / 内置/code-review ultra）。002 的显式触发 / 成本门基底对按需自写 workflow 继续有效。 - verdict 守门：003（从 findings 推导 + hook，载体注释块）→ 010（载体改 frontmatter SSOT，覆盖扩到 SIT Audit + QA）。003 正文留作历史记录。
- 代码理解：005 的 agf-understand（轻量理解加速器，≤8 agent）→ 021 codemap（持久化 SQLite 图谱 + tree-sitter + 影响分析 + dashboard，成接手遗留代码必选项）。
agf-understand.js+ skill 已删，入口改/agf-code-map。后续扩展（同引擎、advisory）：024（orphans 模块级可达性）→ 029（复用校验门 + 符号语义层）→ 030（膨胀观测：死代码 + Rule of Three）。 - teammateMode 默认：004（auto → tmux → iterm2 沿革，选 iterm2 fail-loud）→ 022（默认回退 auto：实测 iterm2 在非 iTerm2 会话硬阻断 spawn）→ 028（不改默认，加 init 时分屏就绪探测 + it2 引导补 auto 缺口）。004 正文留作历史沿革。
- 安装入口：026 D3（setup TUI 层——安装 TUI + 启动 TUI——整体退役，入口统一「install-to-existing + /agf-init」/
/agf-team-start）→ 027（局部逆转：重纳入安装 TUI，test-install.sh加两条防漂移护栏机械锁死原删除理由；启动 TUI 部分保持退役，D3 对启动侧仍完全有效）。026 D3 正文留作历史记录。
| 主题 | ADR |
|---|---|
| 基线 | 000（Tech Stack SSOT） |
| 团队机制 | 001 + 025（Pool / 实例生命周期过门即关）· 003 + 010（verdict 守门）· 004 + 022 + 028（显示模式 / Agent Teams 上游依赖硬化 / 分屏就绪探测） |
| Workflow | 002 + 005（Dynamic Workflows） |
| 契约同步 | 006（Web orval）· 008（Apple swift-openapi-generator） |
| Apple 轨 | 007（栈）· 008（契约）· 009（发布） |
| 交付流水线 | 011（lane / SIT 门）· 012（需求入口 / 活规格）· 016（Skill Stocktake 自有 skill 内容质量审计） |
| 设计治理 | 013（审美纪律层 / DESIGN.md SSOT 背书） |
| Hook 运行时 / 防御 | 014（profile / 治理 / 遥测）· 015（agent Prompt Defense）· 017（安全扩展）· 018（write-scope 门）· 019（部署/发布授权归因）· 020（回派熔断）· 023（诚实层：deny 非回归 + claims-audit + known-limitations 三态） |
| 代码理解 | 021（codemap / DU 引擎，替换 agf-understand）· 024（orphans 模块级可达性 advisory）· 029（复用校验门 + 符号语义层）· 030（膨胀观测：死代码 + Rule of Three） |
| 模板形态 | 026（结构性精简：codemap 外迁 / advisory 收敛 / TUI 退役 / preset 补全 / review-sweep·遥测·双视图退役）· 027（安装 TUI 局部重纳入，逆转 026 D3） |
这些是 AGF 模板自身的 meta 决策。装到你的仓库时，安装器不会把 001–013 拷进你的 docs/adr/（只放 000-system-architecture.md.agf-template 供你重写为本项目架构基线）——你已有的 ADR 编号零冲突。/agf-init 保留你全部现有 ADR，仅处理 000 这个「系统架构基线」槽位。