flutter-ai-harness: Command for Claude Code

执行 $ARGUMENTS 中的任务卡。只有实现、验证、Review、修复和复审全部完成，任务卡才算完成。

前置检查

1. 对每个输入路径先做词法规范化，并确认规范化后仍是仓库 docs/tasks/ 直属目录下、文件名为 lowercase kebab-case 的普通非符号链接 Markdown 文件；从仓库根到任务文件的每个路径组件 都必须是非符号链接的普通目录或文件，解析后的真实路径也必须位于仓库内。拒绝 .. 逃逸、 done/、子目录、符号链接、特殊节点和仓库外路径，再读取任务内容。
2. 编辑前完整阅读所有卡片。
3. 按声明依赖排序，再按文件名排序。
4. 阻塞项未解决或外部依赖缺失时停止。
5. 保护无关工作树改动，并将 diff 限定在当前卡范围。

Executor 分流

• 缺少 executor：停止并报告无效任务卡，不猜测执行角色。
• 缺少 platforms 或 workKinds 的活动任务：停止并报告无效任务卡；归档历史任务按 Harness 兼容规则处理，不重新执行。
• task-executor：只执行 Dart Client、Flutter、文档、规划、Harness、传输中立 Capability Contract 及其允许的单 Runtime 工作。
• android-engineer：只执行 platforms: [android] 的 Native Module、Bridge Adapter 或 Android 单平台门禁，并加载 Kotlin/Android 与原生测试 Skill。
• ios-engineer：只执行 platforms: [ios] 的对应工作，并加载 Swift/iOS 与原生测试 Skill。
• bridge-engineer：只执行结构化 Wire Contract 或包含多个 Runtime 的最终集成，要求契约和 所有声明平台证据齐全。
• 其他值：停止并报告无效任务卡。

只依据 frontmatter 选择 Agent 并校验结构化范围，不根据文件名、正文或 diff 猜测平台。 Executor/范围冲突或跨平台实现未拆卡时停止；正文和实际 diff 是否诚实匹配声明范围由 Reviewer 检查。

普通 Review Profile 分流

普通 Review 只由任务完整 workKinds 确定，不增加任务字段，也不根据文件名、扩展名或 diff 猜测：

• flutter、dart-client、native、bridge-adapter、integration、quality-gate 选择 code-reviewer。
• harness 选择 harness-reviewer。
• capability-contract、bridge-contract 选择 contract-reviewer。
• documentation、planning 只有在没有命中上述实质 Profile 时才选择 contract-reviewer；作为实现 配套工作时不额外增加 Profile。

结果按 code-reviewer、harness-reviewer、contract-reviewer 固定顺序去重。一个任务可以命中多个 Profile。security-reviewer 是独立安全维度，不参与普通 Profile 映射。

单卡闭环

1. 严格按卡片范围实现代码和测试。
2. 格式化触碰的 Dart 文件。
3. 通过 scripts/quality/capture-evidence.sh 直接执行受影响静态分析、聚焦测试和 make lint，把 shell-safe 命令、工具版本、退出码、稳定结果或首个失败根因、完整脱敏输出行数/字节数与 SHA-256 的 bounded-v1 摘要写入 docs/reviews/test-evidence/<task-slug>.log。每个正式自动化 Gate 使用稳定的 canonical lowercase kebab-case ID，通过 --gate <gate-id> 更新；同一 Gate 只保留被后续尝试取代的 首次失败和最新结果，新 Gate 按首次出现顺序增加。命令只执行一次，原始输出只进入临时文件并在脱敏后删除。本地执行不伪造 Artifact；CI 通过 --artifact 把同次命令的完整脱敏输出交给固定 14 天上传步骤。不得直接重定向 stdout/stderr 到入库证据或 Artifact。
4. Harness 实现或修复轮使用 make harness-test-focus 显式声明受影响的 HARNESS_FIXTURE_CASES 或 HARNESS_FIXTURE_PATHS；Evidence 必须记录选择条件、实际 case 数和 ID。选择器缺失、非法、未知或零匹配 必须失败，聚焦 Gate 不得宣称未执行的 Fixture 已验证。新增 Harness 规则默认在所属领域 Dart 测试中从 明确合法 Fixture base 创建结构化 mutation；只有改变既有 Legacy Shell 场景或完整性迁移时才重采集 inventory/catalog。影响面无法可靠收窄，或修改共享 Entity、公共包 API、协议生成、DI 装配、路由或平台 契约时升级验证范围。
5. 首轮实现和自动化验证结束后冻结候选，在全部适用普通 Profile 与条件性 Security Review 返回前不得 修改实现、测试或任务范围。运行环境支持时并行启动独立审查；不支持时可顺序调用，但必须绑定同一候选， 且不得把任一 Reviewer 结论提供给其他 Reviewer。把普通 Profile 结论聚合写入唯一的 docs/reviews/execute-<task-slug>.md：frontmatter 必须包含与任务文件 basename 一致的 task slug、 status、当前未解决总数 p0、p1、reviewFormat: routed-v1，以及与映射结果完全相同的有序 reviewProfiles。正文按 Profile 分节，每条发现标出 ownerProfile；任一 Profile 仍有 P0/P1 时聚合 报告不得通过。
6. 判断是否需要 Security Review。任务声明 securityReview: required 时必须执行；未声明但实际 diff 引入或改变下列任一边界时，先把该字段补入活动任务卡再执行：
   • 认证、会话、授权、用户数据隔离、凭据、隐私数据或安全存储。
   • 网络、文件、Deep Link、WebView、不可信输入反序列化或其他攻击者可控输入。
   • MethodChannel/EventChannel、原生权限、Manifest、Entitlements 或平台安全配置。
   • 第三方依赖、GitHub Action、构建/安装/生成脚本或依赖来源。
   • .claude/settings.json、MCP、CI 权限，或 Command/Agent/Skill、适配生成器与脚本中会改变读写、命令、网络、凭据、提交或发布能力的执行语义；纯描述修正和未改变能力的生成适配同步不触发。
7. 需要时由调用工作流运行必要的只读验证，再调用没有 Bash/写入能力的 security-reviewer；写入 docs/reviews/security-<task-slug>.md 时列出实际审查的 implementationFiles，并在所属任务归档前用 implementation_digest.dart 为最终实现生成 implementationDigest。其首轮必须与所有普通 Profile 保持独立，不读取普通 Review 结论；不需要时不生成跳过报告。任务归档前任一 implementationFiles 内容变化都必须重新审查并更新摘要。
8. 全部首轮结论返回后一次性汇总 P0/P1，再使用 fix-review-findings 进行一个修复批次。每轮只重跑修复 实际影响的 Gate、发现所属普通 Profile、审查输入或语义被改变的其他普通 Profile，以及 implementationFiles 内容变化或新增/改变安全边界时的 Security Review。修复轮只更新实际重跑的 Gate，不为未执行命令制造记录；Evidence 的 Gate 更新、报告状态更新 或与结论无关的生成适配同步本身不使全部 Profile 失效；任务范围、验收标准或权威契约变化时，使所有 受影响 Profile 失效。把每轮 Gate/Profile/Security 失效判断及理由记录在聚合报告中。 execute-tasks 已包含实现授权；自动修复最多三轮，超过后停止并请求用户决策。
9. Harness 任务的全部 P0/P1、聚焦 Gate 和适用复审清零后，对最终准备归档的候选执行一次无过滤的 make harness-test 并记录 full Harness Gate；聚焦 Gate 不能替代它。完整回归失败时只修复实际失败区域并 重新执行受影响 Gate/Profile，形成新的最终候选后再运行完整回归。CI、make check 和发版检查始终全量。
10. 将完成任务卡移入 docs/tasks/done/，并更新其他仓库内任务引用；Review、Security Review、Evidence、 UI Spec、Audit 和 App Operator 报告都不得随任务移动或重写。
11. 归档完成后重新运行 make harness-check；归档任务缺少已完成依赖、通过的普通 Review、要求的 Security Review、合法的安全快照元数据或测试证据时门禁必须失败。已归档报告不要求其摘要匹配后来 工作树内容；后续修改由新的任务、Review、Evidence 和摘要负责。