diff --git a/agent/prompt_builder.py b/agent/prompt_builder.py index 42f608d65540c..16f2db287f3c2 100644 --- a/agent/prompt_builder.py +++ b/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=)`. The reviewer approves with " "`kanban_complete`, returns actionable rework with " "`kanban_request_changes`, or uses `kanban_block` only for a genuine " diff --git a/tests/hermes_cli/test_kanban_review_surfaces.py b/tests/hermes_cli/test_kanban_review_surfaces.py index ff716b9ab7af0..57d4c40920682 100644 --- a/tests/hermes_cli/test_kanban_review_surfaces.py +++ b/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 diff --git a/website/docs/user-guide/features/kanban-worker-lanes.md b/website/docs/user-guide/features/kanban-worker-lanes.md index 3b12a53c1597d..c14025d49ebd0 100644 --- a/website/docs/user-guide/features/kanban-worker-lanes.md +++ b/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. diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/kanban-worker-lanes.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/kanban-worker-lanes.md index 424e8607f2a28..078c43944fa91 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/kanban-worker-lanes.md +++ b/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。