# Agent-Squad 接入 agent-intent 意图闸门（可选能力）

对应设计：Agent-Intent 仓 `docs/records/2026-09-29-decoupling-and-llm-layering.md`（第三节 a，决策 D1/D2/D4/D5 按推荐执行）。跨仓总测试报告：Agent-Intent 仓 `docs/records/2026-09-29-squad-native-integration-report.md`。

## 形态与边界

- `squad/intent.go`：`IntentGate` 窄端口 + `IntentDecision`（Reject / BlueprintKey / nil=透传），`Options.IntentGate`，`Run()` 入口一次裁决（澄清续跑不重复过闸；显式 TaskKey 优先）。约 60 行，零外部依赖。
- `squadintent/`：**全仓唯一 import agent-intent 处**。`New` 无来源返回 nil 闸门（= 未启用）；分支映射 GuardHit→Reject、Matched+`metadata.blueprint`→蓝图定向、其余→nil；识别错误 fail-closed。
- cli：`--intent-root` flag + `AGENT_SQUAD_INTENT_ROOT` env（run/serve）；配置非法 fail-closed 拒绝启动。
- 错误码：守卫拒绝 `squad.intent_refused`；意图定向的蓝图缺失 `squad.blueprint_not_found`（复用）。
- 运行审计：`state.json` 记录 `intent_id` / `intent_blueprint`，`task_key` 与 `planning_mode` 随定向变化。

## 解耦证明

1. 结构：`GOWORK=off go list -deps ./squad ./server ./store` 不含 agent-intent（0 命中）。
2. 零配置等价：`squad.TestIntentGateNilDecisionKeepsOriginalPath`（闸门恒不干预 ⇒ 与无闸门引擎结果一致）；`squadintent.TestNewWithEmptyOverlayActsAsDisabled`（来源存在但零内容 ⇒ Decide 恒 nil）；`squadintent.TestEngineWithoutGateKeepsOriginalBehavior`。
3. 等价回归：既有 `conformance` 全链路套件在本次改动后原样通过。
4. 一致性：`scripts/submodule-consistency.sh` 扩展为对 `deps/agent-native` 与 `deps/agent-intent` 两处嵌套副本的 8 项比对，全部 ok。

## 验证证据（2026-09-29，go vet/test/-race 全绿）

| 层 | 用例 | 期望与结果 |
|---|---|---|
| 引擎 | TestIntentGateBlueprintRouting | 无闸门=自主规划；有闸门=定向到模板步骤 b_intent ✅ |
| 引擎 | TestIntentGateRejectFailsWithStableCode | RunFailed + `squad.intent_refused` ✅ |
| 引擎 | TestIntentGateUnknownBlueprintFailsClosed | RunFailed + `squad.blueprint_not_found` ✅ |
| 引擎 | TestIntentGateErrorFailsClosed | 闸门错误 ⇒ 失败运行 ✅ |
| 引擎 | TestIntentGateExplicitTaskKeyBypassesGate | TaskKey 时闸门零调用 ✅ |
| 适配器 | TestDecideGuardHitRejectsWithGuidance / RouteToBlueprint / AmbiguousFallbackPassThrough / ExplicitTaskKeyWins / NewWithoutSourcesNil / EmptyOverlayDisabled / BadConfigFailClosed | 全通过 ✅ |
| 集成 | TestEngineEndToEndWithAdapterGate | 识别→决策→蓝图→规划→脚本后端执行→质检完成；守卫输入拒绝 ✅（`-race` 同过） |

E2E（真实 CLI，输出摘录见总报告）：同一守卫文本，外挂意图→`squad.intent_refused` 拒绝；无意图→自主规划跑完。同一不含关键词的目标，外挂意图→1 步模板计划（`intent_id`/`intent_blueprint` 落盘）；无意图→4 步自主计划。

## 回退程序

删 `squadintent/`、`squad/intent.go`、cli 接线（assemble 的 intentRoot 参数与闸门构造、run/serve 的 flag、usage 两行）、go.mod 的 agent-intent require/replace、`.gitmodules` 条目与 submodule、一致性脚本两段。`squad` 引擎除 Options 一个可选字段与 Run() 入口一个 nil 可跳过的块外无其他改动。