fix(kanban): validate created card handoffs

hermes_cli/kanban_db.py

@@ -1841,6 +1841,68 @@ def release_stale_claims(conn: sqlite3.Connection) -> int:
     return reclaimed
 
 
+def _validate_created_cards_handoff(
+    conn: sqlite3.Connection,
+    task_id: str,
+    metadata: Optional[dict],
+) -> None:
+    """Validate ``metadata.created_cards`` before accepting completion."""
+    if not metadata or "created_cards" not in metadata:
+        return
+    raw_ids = metadata.get("created_cards")
+    if not isinstance(raw_ids, list):
+        raise ValueError("metadata.created_cards must be a list of task ids")
+    if any(not isinstance(tid, str) or not tid.strip() for tid in raw_ids):
+        raise ValueError("metadata.created_cards must contain non-empty task ids")
+    card_ids = [tid.strip() for tid in raw_ids]
+    if not card_ids:
+        return
+
+    task_row = conn.execute(
+        "SELECT assignee, current_run_id FROM tasks WHERE id = ?",
+        (task_id,),
+    ).fetchone()
+    allowed_creators: set[str] = set()
+    if task_row:
+        if task_row["assignee"]:
+            allowed_creators.add(str(task_row["assignee"]))
+        if task_row["current_run_id"]:
+            run_row = conn.execute(
+                "SELECT profile FROM task_runs WHERE id = ?",
+                (int(task_row["current_run_id"]),),
+            ).fetchone()
+            if run_row and run_row["profile"]:
+                allowed_creators.add(str(run_row["profile"]))
+
+    linked_children = set(child_ids(conn, task_id))
+    missing: list[str] = []
+    unrelated: list[str] = []
+    for card_id in card_ids:
+        row = conn.execute(
+            "SELECT created_by FROM tasks WHERE id = ?", (card_id,),
+        ).fetchone()
+        if row is None:
+            missing.append(card_id)
+            continue
+        if card_id in linked_children:
+            continue
+        if row["created_by"] and str(row["created_by"]) in allowed_creators:
+            continue
+        unrelated.append(card_id)
+
+    if missing:
+        raise ValueError(
+            "metadata.created_cards references unknown task id(s): "
+            + ", ".join(missing)
+        )
+    if unrelated:
+        raise ValueError(
+            "metadata.created_cards must name tasks linked as children of "
+            f"{task_id} or created by its worker profile; unrelated id(s): "
+            + ", ".join(unrelated)
+        )
+
+
 def complete_task(
     conn: sqlite3.Connection,
     task_id: str,
@@ -1864,6 +1926,7 @@ def complete_task(
     """
     now = int(time.time())
     with write_txn(conn):
+        _validate_created_cards_handoff(conn, task_id, metadata)
         cur = conn.execute(
             """
             UPDATE tasks

tests/hermes_cli/test_kanban_core_functionality.py

@@ -1544,6 +1544,99 @@ def test_completed_event_payload_summary_none_when_missing(kanban_home):
         conn.close()
 
 
+def test_complete_rejects_missing_created_cards_metadata(kanban_home):
+    conn = kb.connect()
+    try:
+        tid = kb.create_task(conn, title="x", assignee="worker")
+        kb.claim_task(conn, tid)
+
+        with pytest.raises(ValueError, match="unknown task id"):
+            kb.complete_task(
+                conn,
+                tid,
+                summary="created follow-up",
+                metadata={"created_cards": ["t_missing"]},
+            )
+
+        assert kb.get_task(conn, tid).status == "running"
+    finally:
+        conn.close()
+
+
+def test_complete_accepts_created_cards_linked_to_parent(kanban_home):
+    conn = kb.connect()
+    try:
+        tid = kb.create_task(conn, title="x", assignee="worker")
+        child = kb.create_task(
+            conn,
+            title="follow-up",
+            assignee="worker",
+            parents=[tid],
+            created_by="someone-else",
+        )
+        kb.claim_task(conn, tid)
+
+        ok = kb.complete_task(
+            conn,
+            tid,
+            summary="created follow-up",
+            metadata={"created_cards": [child]},
+        )
+
+        assert ok is True
+        assert kb.get_task(conn, tid).status == "done"
+        assert kb.latest_run(conn, tid).metadata == {"created_cards": [child]}
+    finally:
+        conn.close()
+
+
+def test_complete_rejects_unrelated_created_cards_metadata(kanban_home):
+    conn = kb.connect()
+    try:
+        tid = kb.create_task(conn, title="x", assignee="worker")
+        other = kb.create_task(
+            conn,
+            title="unrelated",
+            assignee="worker",
+            created_by="someone-else",
+        )
+        kb.claim_task(conn, tid)
+
+        with pytest.raises(ValueError, match="unrelated"):
+            kb.complete_task(
+                conn,
+                tid,
+                summary="created unrelated follow-up",
+                metadata={"created_cards": [other]},
+            )
+
+        assert kb.get_task(conn, tid).status == "running"
+    finally:
+        conn.close()
+
+
+def test_complete_accepts_created_cards_created_by_worker(kanban_home):
+    conn = kb.connect()
+    try:
+        tid = kb.create_task(conn, title="x", assignee="worker")
+        child = kb.create_task(
+            conn,
+            title="follow-up",
+            assignee="worker",
+            created_by="worker",
+        )
+        kb.claim_task(conn, tid)
+
+        assert kb.complete_task(
+            conn,
+            tid,
+            summary="created follow-up",
+            metadata={"created_cards": [child]},
+        )
+    finally:
+        conn.close()
+
+
 # -------------------------------------------------------------------------
 # Deep-scan fixes (Apr 2026 second audit)
 # -------------------------------------------------------------------------

tools/kanban_tools.py

@@ -474,8 +474,10 @@ def _handle_link(args: dict, **kw) -> str:
                 "description": (
                     "Free-form dict of structured facts about this "
                     "attempt — {\"changed_files\": [...], \"tests_run\": 12, "
-                    "\"findings\": [...]}. Surfaced to downstream "
-                    "workers alongside ``summary``."
+                    "\"findings\": [...]}. If you claim follow-up cards, "
+                    "put their real ids in \"created_cards\": [\"t_...\"]; "
+                    "completion rejects missing or unrelated ids. Surfaced "
+                    "to downstream workers alongside ``summary``."
                 ),
             },
             "result": {