fix(kanban): clarify downstream review inspection

agent/prompt_builder.py

@@ -240,13 +240,15 @@ KANBAN_GUIDANCE = (
     "5. **Finish with the review model encoded by the task graph.** Always "
     "include the structured handoff (`summary`, `metadata`) on the lifecycle "
     "transition itself; never put secrets, tokens, or raw PII in these durable "
-    "fields. If `kanban_show()` lists pre-created downstream review, "
-    "QA, or release children that depend on your task, call `kanban_complete`: "
-    "your implementation phase is done, and completion is what releases those "
-    "children. Never sticky-block that parent for `review-required` and never "
-    "request same-card review as well — either choice would strand or duplicate "
-    "the downstream lane. Otherwise, when this same task needs review before it "
-    "is final, call `kanban_request_review(summary=..., metadata=..., "
+    "fields. If `kanban_show()` lists child IDs, inspect those cards with "
+    "`kanban_show(task_id=...)` before choosing the terminal action. When any "
+    "pre-created review, QA, or release child depends on your task, call "
+    "`kanban_complete`: your implementation phase is done, and completion is "
+    "what releases those children. Never sticky-block that parent for "
+    "`review-required` and never request same-card review as well — either "
+    "choice would strand or duplicate the downstream lane. Otherwise, when "
+    "this same task needs review before it is final, call "
+    "`kanban_request_review(summary=..., metadata=..., "
     "reviewer=<optional-profile>)`. The reviewer approves with "
     "`kanban_complete`, returns actionable rework with "
     "`kanban_request_changes`, or uses `kanban_block` only for a genuine "

tests/hermes_cli/test_kanban_review_surfaces.py

@@ -163,7 +163,9 @@ def test_worker_guidance_distinguishes_same_card_and_downstream_review() -> None
     from agent.prompt_builder import KANBAN_GUIDANCE
     from hermes_cli.config_defaults import DEFAULT_CONFIG
 
-    assert "pre-created downstream review" in KANBAN_GUIDANCE
+    assert "lists child IDs" in KANBAN_GUIDANCE
+    assert "inspect those cards" in KANBAN_GUIDANCE
+    assert "pre-created review, QA, or release child" in KANBAN_GUIDANCE
     assert "call `kanban_complete`" in KANBAN_GUIDANCE
     assert "Never sticky-block that parent for `review-required`" in KANBAN_GUIDANCE
     assert "`kanban_request_changes`" in KANBAN_GUIDANCE

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

@@ -62,7 +62,7 @@ The kanban kernel enforces that exactly one of these terminates each run. A work
 For code-changing tasks, pick the review model encoded by the task graph:
 
 - **Same-card review:** call `kanban_request_review(summary=..., metadata=..., reviewer=...)`. The task enters `review` without touching block recurrence accounting. The dispatcher claims it with the bundled `sdlc-review` skill by default. The reviewer approves with `kanban_complete`, calls `kanban_request_changes(reason=...)` to close the review run and route the task back to its original implementer, or blocks only for a genuine external escalation.
-- **Pre-created downstream review/QA/release card:** call `kanban_complete` on the implementation phase. Its dependent child cannot promote until this parent is `done`/`archived`. Do not additionally request same-card review and never sticky-block the parent with `review-required:` — either choice strands or duplicates the downstream lane.
+- **Pre-created downstream review/QA/release card:** `kanban_show` lists child IDs; inspect those cards with `kanban_show(task_id=...)` before choosing the terminal action. When a child is the downstream review/QA/release phase, call `kanban_complete` on the implementation phase. It cannot promote until this parent is `done`/`archived`. Do not additionally request same-card review and never sticky-block the parent with `review-required:` — either choice strands or duplicates the downstream lane.
 - **Human-only boards:** set `kanban.review_dispatch: false`. A task can then remain in `review` until a human approves it or uses `reopen-review`/the dashboard to return it to `ready`/`todo`.
 
 Both review models carry their structured handoff on the lifecycle transition itself. Do not place secrets, tokens, or raw PII in `summary` or `metadata`; run rows are durable.

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

@@ -62,7 +62,7 @@ kanban 内核强制要求每次运行恰好由其中一项终止。既未调用
 代码变更任务必须按照任务图选择审查模型：
 
 - **同卡审查：**调用 `kanban_request_review(summary=..., metadata=..., reviewer=...)`。任务进入 `review`，不会触碰 block 循环计数。默认情况下，调度器使用内置 `sdlc-review` skill 启动 reviewer。Reviewer 用 `kanban_complete` 批准，用 `kanban_request_changes(reason=...)` 关闭审查 run 并将任务退回原 implementer，或只在真正需要外部决策时 block。
-- **预先创建的下游 review/QA/release 卡：**implementation 阶段必须调用 `kanban_complete`。依赖它的子卡只有在父卡为 `done`/`archived` 后才能启动。不要再请求同卡审查，也不要用 `review-required:` sticky-block 父卡，否则会让下游通道卡死或重复。
+- **预先创建的下游 review/QA/release 卡：**`kanban_show` 会列出 child ID；选择终止动作前，先用 `kanban_show(task_id=...)` 检查这些卡。如果 child 是下游 review/QA/release 阶段，implementation 阶段必须调用 `kanban_complete`。子卡只有在父卡为 `done`/`archived` 后才能启动。不要再请求同卡审查，也不要用 `review-required:` sticky-block 父卡，否则会让下游通道卡死或重复。
 - **纯人工审查看板：**设置 `kanban.review_dispatch: false`。任务会停在 `review`，直到人工批准，或通过 `reopen-review`/仪表盘退回 `ready`/`todo`。
 
 两种审查模型都在生命周期转换本身携带结构化 `summary` 和 `metadata`。这些字段会持久保存，因此不得写入 secret、token 或原始 PII。