CUST-WP-0074-T02 follow-up: blocked_on / wait_until reach the hub read model

Migration f9a0b1c2d3e4 (revises e8f9a0b1c2d3) adds tasks.blocked_on
(String 200) and tasks.wait_until (Date); TaskCreate/Update/Read carry both.

Read model (api/services/wait_kind.py): a wait task is external when it has
a dependency edge, a blocked_on matching ^message-from: (rule 6), or a
wait_until date (a window clears by itself). human/both/unqualified and
blocked_kind are unchanged in shape.

fix-consistency: _task_wait_fields carries blocked_on and wait_until (ISO
date, PyYAML date objects normalised), so the C-06/C-11 creates and the
C-10 status PATCH send them, and C-41 compares and syncs them like the
other qualifiers. C-39 accepts wait_until: YYYY-MM-DD as a qualifier; C-40
also fires when wait_until is before UTC today (report only).

/state/deps: depends_on stubs gain from_task_id / from_task_title so
consumers see task-scoped edges; both optional, response otherwise as before.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Assistant: claude-code
Assistant-Model: sonnet
Assistant-Process: 237582@bnt-lap001
Assistant-Session: f2b3d9f1-8fb9-4b9c-bc2b-837ec5dfc826

api/models/task.py

@@ -60,6 +60,10 @@ class Task(Base, TimestampMixin):
     # "CCR-2026-0004" (CUST-WP-0074 Case B). Free text: the decision may live
     # in another repo and may not be indexed in the hub yet.
     decision_id: Mapped[str | None] = mapped_column(String(120), nullable=True)
+    # Owner-return marker "message-from:<agent>" (CUST-WP-0074 rule 6) and a
+    # date after which the wait clears by itself; either counts as external.
+    blocked_on: Mapped[str | None] = mapped_column(String(200), nullable=True)
+    wait_until: Mapped[date | None] = mapped_column(Date, nullable=True)
     parent_task_id: Mapped[uuid.UUID | None] = mapped_column(
         UUID(as_uuid=True),
         ForeignKey("tasks.id", ondelete="SET NULL", onupdate="CASCADE"),

api/routers/state.py

@@ -909,12 +909,15 @@ async def get_deps(
 
     dep_ws_ids: set = set()
     dep_task_ids: set = set()
+    open_ws_id_set = set(open_ws_ids)
     for d in dep_rows:
         dep_ws_ids.add(d.from_workplan_id)
         if d.to_workplan_id:
             dep_ws_ids.add(d.to_workplan_id)
         if d.to_task_id:
             dep_task_ids.add(d.to_task_id)
+        if d.from_task_id and d.from_workplan_id in open_ws_id_set:
+            dep_task_ids.add(d.from_task_id)
 
     ws_lookup: dict = {w.id: w for w in open_ws}
     extra_ids = dep_ws_ids - set(ws_lookup.keys())
@@ -933,16 +936,25 @@ async def get_deps(
     dep_index: dict = {w.id: {"depends_on": [], "blocks": []} for w in open_ws}
     for d in dep_rows:
         from_id, to_id, task_id = d.from_workplan_id, d.to_workplan_id, d.to_task_id
+        # Task-scoped edge (CUST-WP-0074): the waiting task on the from side,
+        # only surfaced on the workplan's own depends_on stubs.
+        from_task = task_lookup.get(d.from_task_id) if d.from_task_id else None
+        from_task_fields = {
+            "from_task_id": d.from_task_id,
+            "from_task_title": from_task.title if from_task is not None else None,
+        }
         if from_id in dep_index and to_id and to_id in ws_lookup:
             dep_index[from_id]["depends_on"].append(WorkstreamDepStub(
                 dep_id=d.id, target_type="workstream", relationship_type=d.relationship_type,
                 workstream_id=to_id, workstream_slug=ws_lookup[to_id].slug,
                 workstream_title=ws_lookup[to_id].title, description=d.description,
+                **from_task_fields,
             ))
         if from_id in dep_index and task_id and task_id in task_lookup:
             dep_index[from_id]["depends_on"].append(WorkstreamDepStub(
                 dep_id=d.id, target_type="task", relationship_type=d.relationship_type,
                 task_id=task_id, task_title=task_lookup[task_id].title, description=d.description,
+                **from_task_fields,
             ))
         if to_id and to_id in dep_index and from_id in ws_lookup:
             dep_index[to_id]["blocks"].append(WorkstreamDepStub(

api/schemas/task.py

@@ -46,6 +46,8 @@ class TaskCreate(TaskStatusMixin, TaskFlavorMixin, WorkplanIdCreateMixin):
     needs_human: bool = False
     intervention_note: str | None = None
     decision_id: str | None = None
+    blocked_on: str | None = None
+    wait_until: date | None = None
     parent_task_id: uuid.UUID | None = None
 
     @model_validator(mode="after")
@@ -67,6 +69,8 @@ class TaskUpdate(TaskStatusMixin, TaskFlavorMixin):
     needs_human: bool | None = None
     intervention_note: str | None = None
     decision_id: str | None = None
+    blocked_on: str | None = None
+    wait_until: date | None = None
     parent_task_id: uuid.UUID | None = None
     # Token passthrough — three tiers (highest precision wins):
     # 1. tokens_in + tokens_out  → exact counts; note defaults to "measured"
@@ -131,6 +135,8 @@ class TaskRead(TaskStatusMixin, WorkplanIdCompatMixin):
     needs_human: bool
     intervention_note: str | None = None
     decision_id: str | None = None
+    blocked_on: str | None = None
+    wait_until: date | None = None
     parent_task_id: uuid.UUID | None = None
     # Derived (CUST-WP-0074 rule 5): "external" | "human" | "both" |
     # "unqualified" while status is wait, else None. Set by

api/schemas/workplan_dependency.py

@@ -47,6 +47,10 @@ class WorkplanDepStub(BaseModel):
     )
     task_id: uuid.UUID | None = None
     task_title: str | None = None
+    # The waiting task on a task-scoped edge (workplan_dependencies.from_task_id);
+    # None on frontmatter edges.
+    from_task_id: uuid.UUID | None = None
+    from_task_title: str | None = None
     description: str | None = None
 
     @computed_field  # type: ignore[prop-decorator]

api/services/wait_kind.py

@@ -1,16 +1,20 @@
 """Derived wait qualifiers (CUST-WP-0074 rule 5) — read model only.
 
 A ``wait`` task is *external* when it carries at least one dependency edge
-(``workplan_dependencies.from_task_id``), *human* when ``needs_human`` is set,
-*both* when both hold and *unqualified* otherwise. A ``blocked`` workplan is
+(``workplan_dependencies.from_task_id``), an owner-return marker
+(``blocked_on: message-from:<agent>``, rule 6) or a ``wait_until`` date (a
+time window clears by itself); *human* when ``needs_human`` is set, *both*
+when both hold and *unqualified* otherwise. A ``blocked`` workplan is
 *human* when any of its wait tasks is human or both, else *external* when any
 is external, else *none*. Nothing here is stored; the routers call the
 ``annotate_*`` helpers and Pydantic picks the attributes up on serialisation.
 """
 from __future__ import annotations
 
+import re
 import uuid
 from collections.abc import Iterable, Sequence
+from datetime import date
 from typing import Any
 
 from sqlalchemy import select
@@ -31,16 +35,41 @@ BLOCKED_KIND_EXTERNAL = "external"
 BLOCKED_KIND_HUMAN = "human"
 BLOCKED_KIND_NONE = "none"
 
+# Rule 6 owner-return marker; mirrors _BLOCKED_ON_RE in scripts/consistency_check.py.
+MESSAGE_FROM_RE = re.compile(r"^message-from:.+$")
 
-def derive_wait_kind(status: Any, *, needs_human: bool, has_dependency: bool) -> str | None:
+
+def is_external_wait(
+    *,
+    has_dependency: bool,
+    blocked_on: str | None = None,
+    wait_until: date | None = None,
+) -> bool:
+    """Case A holds for a dependency edge, an owner-return marker or a wait window."""
+    if has_dependency or wait_until is not None:
+        return True
+    return bool(blocked_on and MESSAGE_FROM_RE.match(blocked_on.strip()))
+
+
+def derive_wait_kind(
+    status: Any,
+    *,
+    needs_human: bool,
+    has_dependency: bool,
+    blocked_on: str | None = None,
+    wait_until: date | None = None,
+) -> str | None:
     """Rule 1 / rule 5 for one task. ``None`` unless the task is waiting."""
     if normalize_task_status(status, default="todo") != "wait":
         return None
-    if has_dependency and needs_human:
+    external = is_external_wait(
+        has_dependency=has_dependency, blocked_on=blocked_on, wait_until=wait_until
+    )
+    if external and needs_human:
         return WAIT_KIND_BOTH
     if needs_human:
         return WAIT_KIND_HUMAN
-    if has_dependency:
+    if external:
         return WAIT_KIND_EXTERNAL
     return WAIT_KIND_UNQUALIFIED
 
@@ -79,6 +108,8 @@ async def annotate_tasks(session: AsyncSession, tasks: Sequence[Task]) -> Sequen
             task.status,
             needs_human=bool(task.needs_human),
             has_dependency=task.id in with_deps,
+            blocked_on=task.blocked_on,
+            wait_until=task.wait_until,
         )
     return tasks