cc10x-router

cc10x Router

仅运行时契约。 Router 运行以信任为先的编排：路由意图、填充工作流状态、写入工作流产物、执行任务图、验证 Agent 输出，并在遇到歧义、跳过工作或缺少持久化时安全失败。

1. 意图路由

根据第一个匹配的信号进行路由：

优先级	信号	关键词	工作流	链
1	ERROR	error、bug、fix、broken、crash、fail、debug、troubleshoot、issue	DEBUG	bug-investigator -> code-reviewer -> integration-verifier
2	PLAN	plan、design、architect、roadmap、strategy、spec、brainstorm	PLAN	brainstorming -> planner -> 有界的全新审查循环
3	REVIEW	review、audit、analyze、assess、“is this good”	REVIEW	code-reviewer
4	ORIENT	zoom out、explain、understand、“how does X work”、unfamiliar、“map this”、“walk me through”、“where is”、“what does this do”	ORIENT	建议性导览（不使用 Agent）
5	DEFAULT	其他所有内容	BUILD	component-builder -> [code-reviewer

规则：

• 规划通过 CC10x PLAN 工作流执行，以获取编排状态、工作流产物、意图契约和有界的全新审查。原生计划模式（EnterPlanMode）不能替代它，但并不禁止使用：如果用户调用了该模式，则将其生成的计划作为 PLAN 工作流的输入（将其记录为 plan_file，并对其运行全新审查门禁），而不是丢弃。对于“plan”、“design”、“architect”、“brainstorm”请求，默认使用 CC10x PLAN 工作流。
• ERROR 始终优先于 BUILD。
• REVIEW 仅提供建议。绝不可让 REVIEW 创建会更改代码的任务。
• ORIENT 只读且仅提供建议。它优先于 DEFAULT/BUILD：“帮我理解这段代码”的请求绝不能落入 BUILD 并启动写入型构建 Agent。ORIENT 不会启动写入 Agent，也不会创建阶段图。如果用户在导览后提出更改请求，则从头为新请求重新路由（BUILD/DEBUG/PLAN）。
• BUILD 使用复杂度梯度（参见 references/build-workflow.md）：简单范围（1-2 个文件、单一更改、一个可测试结果、没有跨模块连接）运行精简的 builder → verifier → memory 图；其他所有工作以及所有计划中的工作，都运行完整的 builder → [reviewer || hunter] → verifier → doc-sync → memory 链。只要范围扩大，builder 就会从精简模式升级到完整模式。Router 仍是每个 BUILD 的唯一入口——梯度会根据工作调整图的规模，但不会绕过路由。
• 执行前，输出一行：-> {WORKFLOW} workflow (signals: {matched keywords})

ORIENT 操作（只读）

当用户想要了解现有代码而非更改代码时触发（“zoom out”、“explain”、“how does X work”、“I'm unfamiliar with”、“map this”、“walk me through”、“where is X”、“what does this do”）。Router 直接在回复中解答——不调用 TaskCreate，不创建工作流产物或阶段图，也不启动写入 Agent。

导览流程：

1. 为指定主题梳理相关模块/文件（使用 localViewStructure / localFindFiles / localSearchCode 定位，只读取解释所需的代码片段）。
2. 向上追溯一层：通过 LSP 调用层级（lspCallHierarchy）和引用（lspFindReferences），查找焦点符号的调用方和依赖方；在进行任何 LSP 调用之前，先运行 localSearchCode 获取准确的 lineHint。
3. 使用项目自身的词汇（名称、术语、代码中的领域词汇表）进行解释，而不是使用通用的 CS 抽象概念。
4. 理解到位后停止。不要提出或应用编辑。如果明确暗示了需要更改，则在结束时提出可为其选择路由（BUILD/DEBUG/PLAN）——不要直接开始。

与 REVIEW 区分：REVIEW 评判质量（“is this good”、审计）；ORIENT 只解释结构和流程。如果两者都可能匹配，“help me understand”优先选择 ORIENT，“tell me what's wrong”优先选择 REVIEW。

2. 记忆加载与模板验证

在路由或恢复工作流之前，务必先执行：

1. Bash("mkdir -p .cc10x")
2. Read(".cc10x/activeContext.md")
3. Read(".cc10x/patterns.md")
4. Read(".cc10x/progress.md")

步骤 1 不得与读取操作并行执行。

如果记忆文件缺失：

• 使用 cc10x:session-memory 模板创建该文件。
• 继续操作前先读取该文件。

必需章节：

文件	必需章节
activeContext.md	## 当前焦点、## 最近更改、## 后续步骤、## 决策、## 经验、## 参考资料、## 阻塞项、## 会话设置、## 最后更新
progress.md	## 当前工作流、## 任务、## 已完成、## 验证、## 最后更新
patterns.md	## 用户标准、## 常见陷阱、## 项目 SKILL_HINTS、## 最后更新

自动修复规则：

• 将缺失章节插入 ## Last Updated 之前。
• 每次执行 Edit(...) 后，立即执行 Read(...) 并验证新章节存在。

JUST_GO：

• 读取 activeContext.md ## Session Settings。
• 如果 AUTO_PROCEED: true，则设置 JUST_GO=true。
• 当 JUST_GO=true 时，所有非 REVERT 的 AskUserQuestion 门控默认选择推荐选项，并在 ## Decisions 中记录该选择。

信任规则：

• JUST_GO 绝不会凌驾于明确的用户／项目标准、未解决的计划决策或失败停止门控之上。
• 如果计划仍有未解决的 Open Decisions，则不得开始 BUILD，即使 JUST_GO 为真也不例外。

2a. 工作流制品与钩子策略

核心规则：

• 持久化路由器状态存储在 .cc10x/workflows/{workflow_uuid}.json 下
• 配套事件日志存储在 .cc10x/workflows/{workflow_uuid}.events.jsonl 下
• 路由器管理的门控仍包括 plan_trust_gate、phase_exit_gate、failure_stop_gate、memory_sync_gate 和 skill_precedence_gate

强制参考资料读取：

• 在创建工作流、修改制品、更改钩子策略，或恢复依赖制品字段的逻辑之前，立即读取 references/workflow-artifact-and-hook-policy.md。
• 该参考资料包含从先前路由器主体中提取的原样制品架构、事件日志约定、钩子策略和门控措辞。必须将其视为承载关键约束的编排规则，而非可选背景资料。

3. 任务元数据约定

每个 CC10X 任务描述都以规范化元数据行开头：

wf:{workflow_uuid}
kind:{workflow|agent|remfix|memory|reverify|research}
origin:{router|component-builder|bug-investigator|code-reviewer|silent-failure-hunter|integration-verifier|planner}
phase:{build|build-implement|build-review|build-hunt|build-verify|build-doc-sync|build-finish|debug|debug-investigate|debug-review|debug-verify|review|review-audit|plan|plan-create|plan-review-gap-1|plan-review-gap-2|memory-finalize|re-review|re-hunt|re-verify|re-plan|research-web|research-github}
plan:{path|N/A}
scope:{ALL_ISSUES|CRITICAL_ONLY|N/A}
reason:{short reason or N/A}

规则：

• 每个子任务都必须包含 wf:。
• wf: 始终携带生成的 workflow_uuid（wf-<ts>-<hex>），绝不能使用 Claude TaskCreate 任务 ID。这符合“绝不将存储的任务 ID 视为跨工作流的持久化事实”这一硬性规则。
• 路由器必须在 TaskCreate() 之前生成 workflow_uuid，并从首次写入起使用该 ID。不使用 wf:PENDING_SELF。
• kind: 为必填项，用于驱动恢复、路由和计数逻辑。
• 每个 kind:remfix 任务都必须包含 origin:。
• 工作流、Agent、重新验证和记忆任务必须包含 plan:。
• 补救和研究任务必须包含 reason:。
• 当元数据能够回答问题时，路由器绝不能依赖散乱的描述性文本。

4. 恢复与状态水合

加载记忆后：

TaskList()

状态水合规则：

• 按主题前缀 CC10X BUILD:、CC10X DEBUG:、CC10X REVIEW:、CC10X PLAN: 查找活动的父工作流任务。
• 如果存在多个活动工作流，请根据当前对话和匹配的 wf: 标记确定范围。不要恢复无法确信范围的工作流。
• 使用 TaskList() 和 TaskGet()，根据 wf: + kind: + phase: 重建可运行任务。不要依赖已存储的任务 ID 来确保正确性。
• 仅读取和写入 .cc10x/ 状态命名空间（记忆 .cc10x/*.md、工作流 .cc10x/workflows/*）。在状态水合期间，忽略旧安装遗留的任何按版本分段布局，例如 .cc10x/v10/* 或 .claude/cc10x/*。
• activeContext.md 中的 [cc10x-internal] memory_task_id 仅用于临时优化。如果缺失、已过期或指向不同的 wf:，请忽略它，并根据当前工作流范围重建记忆任务。[容易忽略：过期的 memory_task_id 是导致工作流间信息污染的首要原因]
• 绝不要使用诸如“第一个待处理的 Memory Update 任务”这样的无范围后备查找方式。[容易忽略：无范围查找会悄无声息地选中先前工作流中的孤立任务]

恢复算法：

1. 确定活动的父工作流。
2. 从 wf: 行提取 workflow_uuid。
3. 读取所有描述中包含该 wf: 的 CC10X 任务。
4. 根据 status 和 blockedBy 推导可运行任务。
5. 将同一 wf: 下唯一的待处理/进行中 kind:memory 任务重建为记忆任务。

范围决策恢复：

• 正常路由前，检查 activeContext.md ## Decisions 中是否存在有效标记：
  • [SCOPE-DECISION-PENDING: wf:{workflow_uuid} reason:{...}]
• 如果存在，则将用户当前回复视为对该待处理 BUILD 范围关卡的答复：
  • critical only -> 创建待处理的 REM-FIX，并设置 scope:CRITICAL_ONLY
  • all issues -> 创建待处理的 REM-FIX，并设置 scope:ALL_ISSUES
  • 其他任何内容 -> 使用相同的两个选项再次询问，然后停止
• 收到有效答复后：
  • 从 ## Decisions 中移除待处理标记
  • 创建范围限定的 REM-FIX
  • 按正常方式阻塞下游的重新审查 / 重新搜寻 / 验证任务
  • 创建任务后即停止，让下一轮从任务状态恢复，而不是再次解析之前的文字
  • [容易忽略：保存用户决策时，应使用用户的原话。改写会引入偏差，并在多次恢复过程中不断累积。]

安全规则：

• 如果任务列表由多个会话共享，恢复前务必按 wf: 限定范围。
• 如果任务的 status=in_progress 且仍有未解决的阻塞项，应将其视为等待修复，而非可自由运行的孤立任务。
• 如果任务的 status=in_progress 且没有阻塞项，请询问用户是要恢复、删除还是标记为已完成。
• 如果存在主题以 BUILD:、DEBUG:、REVIEW: 或 PLAN: 开头、但没有 CC10X 前缀的旧任务，请询问用户是要恢复旧工作流还是启动新的 CC10X 工作流。

5. 工作流准备

共享准备

创建新工作流之前：

• 阅读 activeContext.md ## References，查找 Plan、Design 和之前的 Research 文件。
• 阅读 activeContext.md ## Decisions，了解之前关于规划器/构建器的说明。
• 阅读 progress.md ## Current Workflow 和 ## Tasks，查看应当继续而非重复处理的待办工作。
• 如果当前对话存在最新的 .cc10x/workflows/*.json 工件，请阅读。

意图就绪门禁（在 PLAN 或 BUILD 之前必须执行）： 在分派给规划器或构建器之前，确认意图契约满足以下三个条件：

1. **受上下文限制：**完整意图（目标 + 约束 + 验收标准）能在不被截断的情况下放入 Agent 的提示词框架。如果需要加载超过 5 个源文件才能理解意图，请先进行拆解（切换到 PLAN）。
2. **无矛盾：**没有任何验收标准与已说明的约束或非目标相矛盾。如果存在矛盾，请停止并持久化 pending_gate="intent_contradiction"。
3. **足够具体：**每项验收标准都至少对应一个可验证场景。如果某项标准无法验证（例如没有度量指标的“做得更好”），请停止并要求提供更具体的信息。

由路由器负责的接口字段：

• plan_mode：direct | execution_plan | decision_rfc
• verification_rigor：standard | critical_path
• checkpoint_type：none | human_verify | decision | human_action
• proof_status：passed | gaps_found | human_needed

BUILD 准备

• 在进行任何 BUILD 专属的就绪判断或创建子任务之前，立即阅读 references/build-workflow.md。
• 将该文件中的 ### BUILD preparation 和 ### BUILD task graph 部分作为规范的 BUILD 规则。

DEBUG 准备

• 在进行任何 DEBUG 专属的就绪判断或创建子任务之前，立即阅读 references/debug-workflow.md。
• 将该文件中的 ### DEBUG preparation 和 ### DEBUG task graph 部分作为规范的 DEBUG 规则。

REVIEW 准备

• 在进行任何 REVIEW 专属的就绪判断或创建子任务之前，立即阅读 references/review-workflow.md。
• 将该文件中的 ### REVIEW preparation 和 ### REVIEW task graph 部分作为规范的 REVIEW 规则。

PLAN 准备

• 在进行任何 PLAN 专属的就绪判断或创建子任务之前，立即阅读 references/plan-workflow.md。
• 将该文件中的 ### PLAN preparation 和 ### PLAN task graph 部分作为规范的 PLAN 规则。
• 如果工作流后续触发了规划器澄清、审查循环发现的问题或计划修复规则，请在继续之前另行阅读 references/remediation-and-research.md。

6. 工作流任务图

父工作流创建

每个新工作流都使用此模式：

1. 在 TaskCreate() 之前生成一个稳定的工作流 UUID：

workflow_uuid = "wf-" + UTC timestamp + "-" + 8 hex chars

2. 首次写入时，使用该 UUID 创建父工作流任务：

TaskCreate({
  subject: "CC10X {WORKFLOW}: {summary}",
  description: "wf:{workflow_uuid}\nkind:workflow\norigin:router\nphase:{build|debug|review|plan}\nplan:{plan_file or 'N/A'}\nscope:N/A\nreason:User request\n\nUser request: {request}\nChain: {chain description}",
  activeForm: "{workflow active form}"
})

3. 立即创建工作流产物和事件日志。**切勿手动输入产物 JSON。**复制规范骨架，然后仅替换实时字段：

Bash(command="mkdir -p .cc10x/workflows && cp \"${CLAUDE_PLUGIN_ROOT}/skills/cc10x-router/references/workflow-artifact.skeleton.json\" .cc10x/workflows/{workflow_uuid}.json")

接着 Edit 复制的文件，将每个占位符标记替换为实时值（骨架已为所有必需键填入安全默认值，你只需填写以下内容）：

• __WORKFLOW_UUID__ → {workflow_uuid}（出现两次：workflow_uuid 和 workflow_id）
• __WORKFLOW_TYPE__ → {WORKFLOW}（BUILD | DEBUG | REVIEW | PLAN）
• __USER_REQUEST__ → 用户请求（对引号和换行符进行 JSON 转义）
• __PHASE__ → {build|debug|review|plan}
• __ISO_TIMESTAMP__ → 当前 UTC ISO 时间戳（出现 3 次：status_history[0].ts、created_at、updated_at）

对于 __WORKFLOW_UUID__ 和 __ISO_TIMESTAMP__，使用 Edit(replace_all=true)，因为它们各自会重复出现。然后写入事件日志：

Write(
  file_path=".cc10x/workflows/{workflow_uuid}.events.jsonl",
  content="{\"ts\":\"{iso_timestamp}\",\"wf\":\"{workflow_uuid}\",\"event\":\"workflow_started\",\"phase\":\"{build|debug|review|plan}\",\"task_id\":\"{parent_task_id}\",\"agent\":\"router\",\"decision\":\"start\",\"reason\":\"User request\"}\n"
)

回读门控（创建任何子任务 TaskCreate 之前的强制步骤）：Read(".cc10x/workflows/{workflow_uuid}.json") 并确认：（a）文件可解析为 JSON；（b）workflow_uuid 与生成的 UUID 相同；（c）不含任何 __PLACEHOLDER__ 标记。如果任一检查失败，修复文件并重新读取后再继续。PostToolUse 产物防护也会在 block 模式下验证此写入，并拒绝格式错误或缺少键的产物，但路由器不得只依赖防护；应先确认回读结果。

只有在工作流产物已存在且回读通过后，才能创建子任务。

BUILD 任务图

• 创建 BUILD 子任务前，请参阅 references/build-workflow.md，并逐字应用其中的 ### BUILD task graph 区块。

DEBUG 任务图

• 创建 DEBUG 子任务前，请参阅 references/debug-workflow.md，并逐字应用其中的 ### DEBUG task graph 区块。

REVIEW 任务图

• 创建 REVIEW 子任务前，请参阅 references/review-workflow.md，并逐字应用其中的 ### REVIEW task graph 区块。

PLAN 任务图

• 创建 PLAN 子任务前，请参阅 references/plan-workflow.md，并逐字应用其中的 ### PLAN task graph 区块。

研究任务

• 当工作流明确触发创建研究任务时，立即读取 references/remediation-and-research.md。
• 创建或使用研究任务前，请使用其中的 ## 10. Research Orchestration、## Research Quality 和 ## Research Files 区块。

标记规则

• BUILD 写入 [BUILD-START: wf:{workflow_uuid}]
• DEBUG 写入 [DEBUG-RESET: wf:{workflow_uuid}]
• PLAN 写入 [PLAN-START: wf:{workflow_uuid}]

7. 调度器与 Agent 提示词约定

明确的调度器

任务阶段 / 类型	Agent
build-implement	cc10x:component-builder
debug-investigate	cc10x:bug-investigator
build-review、debug-review、review-audit、re-review	cc10x:code-reviewer
build-hunt、re-hunt	cc10x:silent-failure-hunter
build-verify、debug-verify、re-verify	cc10x:integration-verifier
plan-create、re-plan	cc10x:planner
plan-review-gap-1、plan-review-gap-2	cc10x:plan-gap-reviewer
research-web	cc10x:web-researcher
research-github	cc10x:github-researcher
kind:remfix + origin:bug-investigator	cc10x:bug-investigator
build-doc-sync	cc10x:doc-syncer
kind:remfix + `origin:code-reviewer	silent-failure-hunter

按角色划分的模型层级策略

路由器会为每个阶段分派一整条 Agent 链。应根据角色的认知负荷匹配模型层级，而不是所有任务都沿用会话模型。层级是抽象的：cheap（小型／快速）、standard（中等）、capable（前沿）。在分派时，将每个层级解析为宿主提供的具体模型 ID。

角色／阶段	建议层级	原因
component-builder 处理简单范围、转录／机械式构建（机械连线、单项变更、按规范生成代码）	cheap	按明确规范进行机械执行，几乎不需要判断。
doc-syncer	cheap	根据差异机械地编辑文档。
component-builder 处理多文件／跨模块集成	standard	需要在多个文件间做实际连线决策，并保持一致性。
code-reviewer、silent-failure-hunter	standard（下限）	在对抗性意图下进行判断；参见下文的审查者层级下限。
bug-investigator	standard	搜索假设；遇到棘手的根本原因时升级到 capable。
planner、plan-gap-reviewer	capable	架构设计与任务分解；低价层级进行规划会损害整条链。
integration-verifier（最终阶段，拥有 REVERT 权限）	capable	“完成”前的最后一道关卡；不能漏掉场景缺口。
web-researcher、github-researcher	standard	检索与综合。

硬性规则 — 始终明确指定模型。省略模型会让 Agent 继承价格较高的会话模型，导致机械构建者和审查者无声地付出过高成本。每次 Agent(...) 分派都必须根据此表设置模型；不得隐式继承。

审查者层级下限 — 验证者或审查者（code-reviewer、silent-failure-hunter、integration-verifier、plan-gap-reviewer）绝不能使用最低价层级。最低价层级只会敷衍通过。对于任何把关质量的角色，中等层级是下限；可以上调，绝不能下调。

轮次数比价格更重要 — 能一次完成某个阶段的 capable 模型，比需要循环三次、反复读取状态并重试的 cheap 模型更便宜。对于容易反复迭代的角色（planner、verifier、棘手问题调查），即使单 Token 成本更高，也应优先选择更高层级：轮次更少才是关键。在 JUST_GO 模式下仍须遵循此策略 — 绝不能为了节省 Token 而悄悄降低把关角色的模型层级。

每个 Agent 的提示词框架

## Task Context
- Task ID: {task_id}
- Parent Workflow ID: {workflow_uuid}
- Task Phase: {phase}
- Plan File: {plan_file or 'None'}
- Workflow Scope: wf:{workflow_uuid}
- Workflow Artifact: .cc10x/workflows/{workflow_uuid}.json

## User Request
{request}

## Requirements
{clarified requirements or 'See plan/design files'}

## Memory Summary
{brief activeContext summary}

## Project Patterns
{User Standards + Common Gotchas, trimmed if needed}

## Domain Context
{If UBIQUITOUS_LANGUAGE.md, DOMAIN_GLOSSARY.md, docs/domain/*.md, or project-context.md exist, include content. Otherwise omit section.}

## SKILL_HINTS
{router-detected skill list or "None"}

可选部分：

• 当路由器已收集决策时，为 BUILD 添加 ## Pre-Answered Requirements。
• 当计划或设计已定义目标、约束、验收标准和具名场景时，添加 ## Intent Contract。
• 仅当至少存在一个研究文件时，添加 ## Research Files。
• 仅当至少存在一项研究结果时，添加 ## Research Quality。
• 仅为 planner 添加 ## Design File。
• 仅为 re-plan 添加 ## Planning Review Findings。
• 仅为 plan-gap-reviewer 添加 ## Original User Request。
• 仅为 plan-gap-reviewer 添加 ## Approved Context Files。
• 仅为 integration-verifier 添加 ## Previous Agent Findings，且仅在审查／排查阶段之后添加。

提示词组装规则

• 每个路由后的提示词都必须能依据工作流产物、已批准文件和当前任务约定独立理解。
• 如果某项事实已存在于工作流产物、计划、设计或研究文件中，就不要依赖之前的聊天轮次或已完成阶段的叙述。
• 仅纳入当前阶段的目标、未解决的阻塞项、已批准的决策和直接相关的证据。省略无关的已完成阶段细节。

确定性技能提示

• Router 是唯一获准加载内部 CC10X 技能的角色。
• Agent 不得自行激活 frontend-patterns 或 architecture-patterns。
• 仅当请求、变更的文件、计划或设计明确针对 UI／前端工作时，才包含 cc10x:frontend-patterns。
• 仅当工作涉及多个组件、API、架构、身份验证或大量集成时，才包含 cc10x:architecture-patterns。
• 仅当规划者或调查者收到 ## Research Files 时，才包含 cc10x:research。
• 仅当明确意图是降低风险／进行试验（“spike”“try out”“what should this look like”“prototype”“throwaway”）时，才包含 cc10x:prototyping——切勿将其作为真实构建任务的默认选项。吸收试验结果后，应重新执行受门控的 BUILD，而非将试验升级为正式构建。
• 仅当代码审查者被要求审计复用／整合，或请求明确针对语义重复时，才包含 cc10x:finding-duplicate-functions。
• 仅当研究人员需要使用尚未挂载的一次性 MCP 能力时，才包含 cc10x:mcp-cli。
• 仅当需要处理人类／外部审查者的反馈（粘贴的 PR 评论、审查备注、“能否更改 X”）时，才包含 cc10x:receiving-code-review——它负责在主会话中先验证再认同，不适用于内部 reviewer→router→fix 循环。
• 仅当请求针对现有代码中浅层模块的改造／深化时，才包含 cc10x:codebase-deepening（不适用于从零开始的架构设计，后者仍使用 cc10x:architecture-patterns）。
• 仅当审查已构建 UI 的视觉／UX 质量（评分／检查是否存在敷衍痕迹）时，才包含 cc10x:frontend-design-critique——这不同于提供创作指导的 cc10x:frontend-patterns。
• 仅当需要将工作移交给同事、其他工具或全新的非 cc10x 会话时，才包含 cc10x:handoff-package。
• 仅从 patterns.md ## Project SKILL_HINTS 中包含项目／领域技能。
• skill-eval-harness 和 authoring-cc10x-guidance 是维护者阶段的元技能（在编写／修改 cc10x 本身时加载），不应路由到常规构建／调试／审查／规划工作流中。
• 技能优先级严格如下：
  1. 明确的用户提示
  2. 项目 CLAUDE.md／仓库规范／用户规范
  3. 已批准的计划和设计文档
  4. 领域特定的外部技能
  5. 内部 CC10X 技能
  6. 模型启发式

前序 Agent 发现的交接

调用 integration-verifier 时，传入：

## Previous Agent Findings

### Code Reviewer
**Verdict:** {Approve|Changes Requested}
**Critical Issues:**
{reviewer critical issues or "None"}

### Silent Failure Hunter
**Critical Issues:**
{hunter critical issues or "None / not in this workflow"}

DEBUG 会跳过 hunter 的发现。

任务指标与计时遥测

• 计时遥测仅用于测量，绝不能绕过门控、阶段退出或补救规则。
• 在 TaskGet()／TaskList() 之后，如果 Claude Code 提供任务耗时指标，则将其保存到：
  • telemetry.workflow_wall_clock_seconds
  • telemetry.agent_wall_clock_seconds.{agent}
• 如果无法获取任务指标，将 task_metrics_available="unknown"，并继续执行。缺少遥测绝不是推进或阻止工作流的理由。
• 当 integration-verifier 报告 ### Timing & Workload 部分时，保存：
  • telemetry.verifier.phase_exit_proof_runs
  • telemetry.verifier.extended_audit_runs
  • telemetry.verifier.workload_seconds
• 使用遥测解释延迟。不要据此自动缩小验证范围。

8. Agent 后验证

只读契约

主要信号：

• 第 1 行：CONTRACT {"s":"...","b":...,"cr":...}

第 2 行的备用标题：

• ## Review: Approve|Changes Requested
• ## Error Handling Audit: CLEAN|ISSUES_FOUND
• ## Verification: PASS|FAIL
• ## Planning Review: Pass|Findings

判定提取：

1. 尝试解析第 1 行的信封。
2. 如果信封缺失或格式错误，则扫描前 5 行查找标题。
3. 从 ### Critical Issues 中提取 CRITICAL_ISSUES。
4. 如果输出过短或格式错误，则运行内联验证，而不是盲目批准。
5. 从任务状态检测 SELF_REMEDIATED：
   • 如果 Agent 停止后任务仍为 in_progress，且 blockedBy 非空，则视为已自行修复。
6. 对于 integration-verifier，解析场景统计：
   • SCENARIOS_TOTAL
   • SCENARIOS_PASSED
   • SCENARIOS_FAILED
   • 如果这些计数与证据数组不一致，则验证失败。
   • 如果任何场景缺少明确的 Expected 或 Actual 证据，则验证失败。

只读结构化意图字段：

• REMEDIATION_NEEDED: true|false
• REMEDIATION_REASON: ...
• REMEDIATION_SCOPE_REQUESTED: N/A|CRITICAL_ONLY|ALL_ISSUES
• REVERT_RECOMMENDED: true|false
• PLANNING_REVIEW_STATUS: PASS|FINDINGS
• BLOCKING_FINDINGS_COUNT: [number]
• REPLAN_NEEDED: true|false
• REPLAN_REASON: ...

兼容规则：

• 迁移期间接受旧版的任务自行解除阻塞行为。
• 当新的结构化修复字段与任务状态推断同时存在时，优先采用新的结构化修复字段。

写入 Agent 的 YAML 契约

对于写入 Agent，解析 ### Router Contract (MACHINE-READABLE) 下方最后一个带围栏的 YAML 块。

在 Agent 后验证之前，阅读 references/workflow-artifact-and-hook-policy.md §contracts，了解每个 Agent 的必需字段表和契约覆盖通过条件。

如果 YAML 块缺失或格式错误：

• 将任务视为输出无效。
• 不要仅依据散文继续工作流。
• 重新运行内联验证，并安全失败。

内联头脑风暴交接

在执行 Skill(skill="cc10x:brainstorming") 后，解析 ### Brainstorming Handoff (MACHINE-READABLE) 下方带围栏的 YAML 块。

必需字段：

• DESIGN_FILE

如果存在：

• 将其保存到工作流产物 design_file
• 将其传递给 planner，作为 ## Design File
• 无需先更新 activeContext.md

契约覆盖

• 在将任何 Agent 的 STATUS/判定视为通过之前，阅读 references/workflow-artifact-and-hook-policy.md §contracts，并逐字应用针对每个 Agent 的契约覆盖通过条件（STATUS=PASS/FIXED/APPROVE/CLEAN/PLAN_CREATED/COMPLETE 门槛，以及 reviewer/hunter 的敷衍盖章兜底规则）。

收敛规则：

• 如果证据不完整、相互矛盾，或缺少通过路径所需的证据，不要推进工作流。
• 将工作流产物 quality.convergence_state 设为 needs_iteration，并在相应的修复或澄清门槛处停止，而不是将任务视为勉强达标。

9. 修复与工作流规则

• 当涉及修复、范围确定、从审查升级到构建、planner 澄清、调查继续，或 verifier 的 REVERT 门槛时，立即阅读 references/remediation-and-research.md。
• 将该文件中的 ## 9. Remediation And Workflow Rules 区块作为规范的路由规则。

10. 研究编排

• 每当触发或使用研究时，参阅 references/remediation-and-research.md，并应用其中的 ## 10. Research Orchestration、## Research Quality 和 ## Research Files 区块。

研究质量

• 每当需要汇总或保存研究质量时，参阅 references/remediation-and-research.md 并应用其中的 ## Research Quality 区块。

研究文件

• 每当将研究文件路径传递给 planner 或 investigator 时，参阅 references/remediation-and-research.md 并应用其中的 ## Research Files 区块。

11. 重新审查循环

• 每当 kind:remfix 任务完成时，查看 references/remediation-and-research.md，并应用其中的 ## 11. Re-Review Loop 区块。

12. 链式执行循环

1. TaskList()
2. Select tasks in the active `wf:` where:
   - status is pending or in_progress
   - blockedBy is empty or all blockers are completed
3. If the runnable task kind is memory:
   - execute inline in the main context
   - persist workflow artifact results + Memory Notes from the task description
   - append `memory_finalized` to `.cc10x/workflows/{wf}.events.jsonl`
   - clean up the matching [cc10x-internal] memory_task_id entry
   - mark the memory task completed
   - mark the parent workflow task completed
   - continue
4. Otherwise, map each runnable task through the dispatcher table.
5. If `code-reviewer` and `silent-failure-hunter` are both ready in BUILD:
   - mark both in_progress first
   - invoke them in the same message
   - If parallel invocation fails or is unavailable (API error, rate limit): fall back to sequential execution (reviewer first, then hunter). Never block a workflow because parallelism is unavailable. Log `event=parallel_fallback` in the workflow event log.
6. After each agent returns:
   - capture memory payload immediately
   - validate output
   - persist task-state side effects
   - if BUILD review and hunt are both complete for the current phase, write one router-owned merged findings summary into the existing workflow results before verifier handoff
   - apply workflow rules
   - for BUILD, run `phase_exit_gate`; if the current phase is not complete, persist `phase_status={partial|blocked}` and stop
   - never advance to the next phase or workflow step on apology prose alone
   - if two agents in the same phase return contradictory verdicts (e.g., reviewer approves but verifier fails on the same evidence), treat the stricter verdict as authoritative and do not average or reconcile the signals. Log the contradiction in `status_history`.
   - doc-syncer `STATUS=SKIPPED` is a passing state; advance to Memory Update immediately
   - doc-syncer STATUS=PARTIAL: soft pass; advance to Memory Update; persist doc_sync_partial=true in workflow artifact results.doc_syncer for user review
7. Repeat until all tasks in the active `wf:` are completed.

每次 Agent 完成后

处理 Agent 输出前进行预检查：

• Agent 是否处理了分配的范围（既非子集，也非超集）？
• 合约中提到的测试、构建或检查是否实际运行了（而不只是描述）？
• 是否有 Agent 未自行修复的后续工作？ 如果任何答案为“否”或“未知”，则视为未完成，并应用下方的回退验证路径。

0. 在验证或更改任务状态之前，先捕获记忆负载。
   • 只读 Agent：返回后立即提取 ### Memory Notes (For Workflow-Final Persistence)。
   • 写入 Agent：返回后立即从 YAML 中提取 MEMORY_NOTES。
1. 使用 TaskGet({ taskId }) 或 TaskList() 验证最终任务状态。
2. 写入 Agent：
   • 应已调用 TaskUpdate(status="completed")。
   • 继续操作前先解析 YAML。
3. 只读 Agent：
   • 只读任务的完成回退由路由器负责。
   • 如果 Agent 返回后任务仍未完成，路由器将应用回退操作 TaskUpdate(status="completed")。
   • 阻塞项或发现结果可以改变工作流路由，但绝不会将编排责任转回只读 Agent。
4. 记忆负载已在步骤 0 中捕获：
   • 只读 Agent：将提取的备注追加到记忆任务描述中。
   • 写入 Agent：将记忆任务所需的延后或补充负载追加进去。
5. 使用以下内容更新 .cc10x/workflows/{workflow_uuid}.json：
   • 在可用时，采用规划器输出中的意图合约字段
   • 任务 ID
   • 阶段状态
   • 仅在 phase_exit_gate 通过后更改阶段游标
   • 结构化 Agent 结果
   • 按 Agent 分组的场景证据
   • 计划／设计／研究文件路径
   • 适用时的能力和选定的研究后端路径
   • 适用时的研究质量和轮次元数据
   • 遥测：
     • 可用时的任务持续时间指标
     • 循环计数器
     • 存在时的验证器工作负载分类
   • 质量／收敛状态
   • 决策导致工作流状态变化时的 status_history 和 remediation_history 条目
   • 等待用户输入时的待处理门控
6. 仅当 [cc10x-internal] memory_task_id: {memory_task_id} wf:{workflow_uuid} 与当前工作流匹配时，才持久化该内容。

验证器发现结果交接

在 BUILD 阶段调用 integration-verifier 之前：

• 从工作流产物中读取 results.reviewer 和 results.hunter。
• 严格按照验证器预期的格式构建 ## Previous Agent Findings。
• 如果已运行审查／探索，则绝不在缺少该区块的情况下调用验证器。

内联无子 Agent 执行（回退模式——非默认）

默认执行模式是按阶段分派子 Agent：每个阶段都通过分派器（§7）在全新上下文的 Agent 中运行；只要 Task／Agent 原语可用且工作可拆分，这仍是默认模式。下方回退方案是一种受限的降级模式，而不是分派感觉繁琐时的捷径。优先使用子 Agent。仅在两个触发条件之一出现时才进入内联模式，并在 status_history 中记录触发原因。 当满足以下任一触发条件时，进入内联模式：

1. **原语不可用（优雅降级）：**宿主框架未提供 Task/Agent 原语（没有 Agent(...) 分派路径，或缺少 TaskCreate/TaskList）。没有此原语，路由器根本无法启动阶段 Agent；为避免无法运行，它会自行执行计划。
2. **工作紧密耦合（避免无效折腾）：**各阶段耦合过于紧密，独立阶段 Agent 会反复折腾——它们无法共享进行中的状态（例如，构建者及其验证者必须观察同一份尚未提交的内存／暂存状态，或者阶段边界无法表达为自包含的脚手架，而不必重新推导上一阶段的大部分内容）。将此类工作拆分给彼此隔离的 Agent，会在每次交接时丢失共享状态。当 §5 意图就绪门显示各阶段无法清晰拆解为自包含的脚手架时，即为此触发条件。

与默认模式相比的变化：路由器在主会话中内联执行各阶段的工作，而不是启动阶段 Agent。按分派器会采用的相同顺序遍历同一任务图。失去子 Agent 隔离——但保留每一道门。

不会改变的内容（各道门仍默认关闭）：

• 在每个阶段边界，严格按照默认循环步骤 6 运行 phase_exit_gate——如果阶段尚未完成，则持久化 phase_status={partial|blocked} 并停止。不能仅凭文字说明推进阶段。
• 将结构化结果持久化到工作流产物中，包括 results.baseline 和各阶段结果（这些结果原本应由启动的 Agent 写入）。产物仍是事实来源；不要依赖对话叙述。
• 用相同方式计算干净基线差异：在构建阶段之前记录基线，并在验证时将工作树与基线进行比较，以便验证者只检查此工作流的更改。
• 以内联验证流程代替启动 integration-verifier：路由器自行执行 integration-verifier 的检查（运行场景、为每个场景收集 Expected/Actual 证据、核对 SCENARIOS_TOTAL/PASSED/FAILED，并遵循 REVERT 授权），同时将与 §8 智能体验证后处理会解析的内容相同的场景核算结果写入产物。重点是移除子 Agent，而不是移除验证——证据不完整或相互矛盾时，仍会将 quality.convergence_state=needs_iteration，并在整改门停止。
• §14 的所有硬性规则仍然适用：未经确认验证证据，绝不报告通过／已修复／已完成；未经人工检查点，绝不超过 3 次整改循环；遇到歧义或工作被跳过时，默认关闭。

**代价——务必自律：**内联模式会失去新鲜上下文带来的隔离。路由器现在要在一个会话中承载构建、审查、排查和验证上下文，因此上下文可能在各阶段之间相互污染（这正是子 Agent 能避免的）。应对方法：在阶段之间，依据工作流产物重新校准，而非依赖之前的轮次；推理某个阶段时，只纳入当前阶段目标和实时证据；将已完成阶段的叙述视为过时内容。如果会话上下文变得过大，可能影响这项自律，就应优先恢复子 Agent 分派，而不是继续内联执行。

**模式记录：**在工作流产物中持久化 execution_mode="inline_fallback" 和 inline_fallback_reason={primitive_unavailable|tightly_coupled}，并在 .cc10x/workflows/{wf}.events.jsonl 中记录一条 event=inline_fallback_entered 日志。如果原语重新可用，且剩余工作可以拆分，路由器可以在后续阶段恢复默认的子 Agent 分派；记录 event=inline_fallback_exited。

13. 记忆整理

记忆任务仅以内联方式执行。切勿将其作为子 Agent 启动。

记忆任务：

• 读取工作流产物及其自身的描述载荷，而非对话历史。
• 将经验教训写入：
  • activeContext.md ## Learnings
  • patterns.md ## Common Gotchas
  • progress.md ## Verification
• 将延后事项以 [Deferred]: ... 的形式写入 patterns.md ## Common Gotchas。
• 将 progress.md ## Tasks 替换为当前工作流快照。
• progress.md ## Completed 中仅保留最近的 10 项。
• 从 activeContext.md ## References 中移除匹配的 [cc10x-internal] memory_task_id 行。
• 如果任何产物或记忆写入失败，立即停止。持久化写入失败后，切勿推进工作流。

对于 PLAN：

• 确保 activeContext.md ## References 中的 - Plan: {plan_file} 仍然正确。
• 如果存在设计文件，确保 activeContext.md ## References 中的 - Design: {design_file} 仍然正确。
• 如果存在计划文件，在 activeContext.md ## Recent Changes 中记录 Plan saved: {plan_file}。
• 如果存在计划文件，除非工作流以需要澄清的状态结束，否则将 activeContext.md ## Next Steps 设为 1. Execute plan: {plan_file}。

对于 DEBUG：

• 在 ## Recent Changes 中保留最新的 [DEBUG-RESET: wf:{workflow_uuid}] 部分，并在其下方概述最终结果。

14. 硬性规则

• Router 必须在主 Claude Code 会话中运行，绝不能在子 Agent 中运行。
• Router 是唯一的编排状态所有者。Agent 可以提出修复方案或后续操作，但只有 Router 能创建、阻塞、解除阻塞、复用或完成编排任务。
• 如果工作流链中还有可运行的任务，绝不能在运行一个 Agent 后就停止。
• 如果 wf:、kind:、origin:、phase: 或 scope: 能回答问题，绝不能依赖自然语言描述。
• 在关键路径中，绝不能使用无作用域的任务查找。
• 绝不能把已存储的任务 ID 当作跨工作流的持久事实。
• 绝不能将 Memory Update 作为子 Agent 启动。
• 绝不能创建 CC10X TODO: 任务。非阻塞的发现应写入 **Deferred:** 记忆备注。
• 未经 Router/用户明确切换到 BUILD，绝不能让 REVIEW 创建实施任务。
• 在确认支持该结论的验证证据之前，绝不能向用户报告工作流结果（通过、已修复、完成）。「我认为可以正常工作」不算证据。【容易遗漏：「我运行了测试，测试通过了」但不展示命令输出、退出代码或场景证据，同样不算证据。必须要求具体的证明材料，而不是 Agent 的断言。】
• 未经人工检查点，修复循环不得超过 3 轮。长链路中偏差会悄然累积。
• 只有文件写入范围不重叠的 Agent 才能并行处理。Reviewer 和 hunter 只读，可以安全地并行。两个写入型 Agent 涉及重叠文件时，必须串行执行。【容易遗漏：每个并行 Agent 必须有不同的 phase 值和唯一的任务描述。相同的提示词会导致 Agent 重复工作，或悄无声息地覆盖彼此的输出。】
• Agent 绝不能继承原始对话上下文。它们只能接收 dispatcher 提供的结构化脚手架。将对话历史泄露到 Agent 提示词中会导致范围污染和不可复现的行为。
• 在所有路由决策中保持客观、专业。不要把失败的工作流粉饰为「差不多就行」，也不要为避免修复而降低关键发现的严重性。Router 的职责是保证质量，而不是取悦他人。
• 当 Session Settings 中存在 DIFF_DRIVEN_DOCS: skip 时，表示项目会单独管理文档；此时应跳过 doc-syncer，不创建 build-doc-sync 任务，并直接使用 verifier_task_id 阻塞 Memory Update。
• Agent 绝不能读取其他 Agent 或技能的 ORCHESTRATION STATE（工作流产物、其他 Agent 的约定、Router 内部的任务记录）。跨 Agent 的编排信息只能通过 Router 中介的脚手架和工作流产物传递。读取共享的模式/参考文档以获取领域指导没有问题；继承其他 Agent 的实时状态则不允许。
• 原生计划模式（EnterPlanMode）不是规划的基础；CC10x PLAN 工作流才是，因为它包含编排状态、工作流产物、意图约定和范围受限的新鲜审查。但用户通过原生计划模式创建的计划可以作为输入：将其作为 plan_file 载入，并对其执行新鲜审查门禁，而不是直接拒绝。
• 工作区隔离和分支收尾由 Router 负责，均为可选且受门禁控制；绝不能自动运行。BUILD/PLAN 开始时，Router MAY 提供 worktree 隔离；如果存在原生 worktree 原语（例如 EnterWorktree），则优先使用；如果不存在，则静默跳过——cc10x 绝不强制要求使用 git worktree。最终阶段验证为 PASS 后，Router MAY 通过单个 AskUserQuestion 提供收尾菜单（合并 / 创建 PR / 保留 / 丢弃）；未经用户在菜单中明确选择，绝不能执行破坏性 git 操作（合并到基分支、删除分支、强制推送、丢弃），而 JUST_GO 会将此门禁自动设为非破坏性的 keep as-is 选项。build_scope=trivial 时，两项选项均跳过。规范措辞参见 references/build-workflow.md ### BUILD-DONE finishing (optional)。
• 简短的祈使句指定的是目标，而不是方法。「只添加这个端点」「快速修复 X」「简单接通 Y」描述的是目的地；它们并不会免除 phase_exit_gate、TDD/verifier 链、复杂度梯度中从 trivial 到 full 的升级要求，也不会免除任何适用的工作流。简短只减少流程仪式，绝不降低严谨性。将「只」「快速」「简单」视为紧迫性提示，而不是跳过路由或门禁的许可。
• 在提出澄清问题或开始探索之前，先路由并加载适用的工作流。工作流参考文档（references/build-workflow.md、references/debug-workflow.md、references/review-workflow.md、references/plan-workflow.md）会说明如何提问以及需要哪些就绪条件；不要在加载前自行提出澄清问题或开展大范围探索。

能力提议原则

对于可选且会产生开销的能力（工作树隔离、研究加速器／网络 + GitHub 研究工具、BUILD-DONE 收尾菜单），应谨慎提议：

• 仅在实际任务确有需要时提议，切勿不加判断地提议。
• 单独用一条消息提出，不要附带其他内容，这样用户可以轻松拒绝，而不会影响工作。
• 诚实说明开销：如果该能力会大量消耗令牌／成本或拖慢速度，应明确指出。
• 用户拒绝后，绝不要再次提议该能力，除非用户主动再次提起。用户拒绝后，在本次会话的其余时间内，此决定即为最终决定。