feat(kanban): teach workers to flag collision hotspots instead of piling on

agent/prompt_builder.py

@@ -258,6 +258,12 @@ def _strip_yaml_frontmatter(content: str) -> str:
     "`kanban_create(title=..., assignee=<right-profile>, parents=[your-task-id])` "
     "to spawn a child task for the appropriate specialist profile instead of "
     "scope-creeping into the next thing.\n"
+    "7. **Flag collision hotspots; don't pile on.** If your change keeps "
+    "colliding with sibling branches in one file, or a file your diff touches "
+    "shows up in other cards' recent comments, do not silently add more to it: "
+    "leave a `kanban_comment` starting with `hotspot: <path> — <one-line reason>` "
+    "on your card and repeat the flag in your completion metadata, so the "
+    "orchestrator can decompose that file before more work lands on it.\n"
     "\n"
     "## Orchestrator mode\n"
     "\n"

skills/autonomous-ai-agents/merge-reconciler/SKILL.md

@@ -144,6 +144,10 @@ explicitly in the hand-back summary.
 - **Missing intents**: commit messages alone can be thin; prefer kanban
   completion summaries or PR bodies. If neither side's intent is recoverable,
   escalate instead of guessing.
+- **Repeat offenders**: repeated conflicts on the SAME file across rounds are
+  a hotspot signal, not routine reconciliation work — flag it (e.g. a
+  `hotspot: <path> — <reason>` kanban comment) so the orchestrator decomposes
+  that file, rather than serially reconciling every new collision on it.
 
 ## Verification
 

website/docs/user-guide/features/kanban.md

@@ -958,6 +958,29 @@ it receives both diffs *and* both intents. The bundled
 gives that worker the full procedure: classify each conflicted hunk, resolve
 impartially, verify, and hand back a summary naming every decision.
 
+### Collision hotspots in parallel campaigns
+
+In wide campaigns some files become collision magnets: many workers each add a
+little to the same file, nobody owns keeping it small, and it turns into the
+site of constant merge conflicts. The mitigation is a comment convention, not a
+new primitive. A worker that notices its diff keeps colliding with siblings in
+one file — or that a file it touches keeps appearing in other cards' recent
+comments — should not silently pile on. Instead it leaves a comment on its own
+card with a recognizable prefix:
+
+```
+hotspot: hermes_cli/kanban_db.py — third conflicting edit to the dispatch loop this wave
+```
+
+and repeats the flag in its completion `metadata`. Orchestrators (or humans
+reviewing the board) who see **two or more `hotspot:` comments naming the same
+path** should create a dedicated refactor/decomposition card for that file
+**before** queuing more work that touches it — splitting the magnet file is
+cheaper than reconciling every future collision it would cause. For conflicts
+that have *already* happened, use the reconciliation-card pattern above with
+the `merge-reconciler` skill; hotspot flagging is the upstream fix that keeps
+the reconciler from becoming a standing lane.
+
 ## Multi-tenant usage
 
 When one specialist fleet serves multiple businesses, tag each task with a tenant:

website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/kanban.md

@@ -703,6 +703,16 @@ EOF
 
 在工程流水线（使用 worktree 的 P1/P2）中，两个 worker 的分支合并时可能发生冲突。不要让任一 worker 自行裁决 —— 发生冲突的 agent 缺乏对方的上下文，往往会覆盖对方的改动或放弃自己的改动。正确做法是：创建一张调解卡片，指派给**第三个中立配置文件**，并把**两张**冲突卡片都链接为其父任务：父任务链接会把双方的完成摘要带入调解者的上下文，使其同时获得双方的 diff *和*双方的意图。内置的 [`merge-reconciler` 技能](https://github.com/NousResearch/hermes-agent/blob/main/skills/autonomous-ai-agents/merge-reconciler/SKILL.md) 为该 worker 提供完整流程：对每个冲突块分类、公正地解决、验证，并在交回摘要中说明每一项决定。
 
+### 并行战役中的碰撞热点（Collision hotspots）
+
+在大规模并行战役中，某些文件会成为碰撞磁石：许多 worker 各自往同一个文件里添加一点内容，没有人负责保持它精简，它于是成为持续合并冲突的发生地。缓解方式是一种注释约定，而非新原语。当 worker 发现自己的 diff 在某个文件上不断与兄弟分支冲突，或它触碰的某个文件反复出现在其他卡片最近的评论中时，不应默默继续叠加改动，而应在自己的卡片上留下带有可识别前缀的评论：
+
+```
+hotspot: hermes_cli/kanban_db.py — 本轮对 dispatch 循环的第三次冲突性编辑
+```
+
+并在完成时的 `metadata` 中重复该标记。编排者（或查看看板的人类）如果看到**两条或更多 `hotspot:` 评论指向同一路径**，应在继续排入任何触碰该文件的工作**之前**，为该文件创建一张专门的重构/分解卡片 —— 拆分磁石文件比调解它未来引发的每一次冲突更便宜。对于*已经*发生的冲突，请使用上文的调解卡片模式配合 `merge-reconciler` 技能；hotspot 标记是上游修复，能避免调解者变成一条常设车道。
+
 ## 多租户使用
 
 当一个专家团队为多个业务提供服务时，为每个任务添加租户标签：