AP1.4e: Methodenprofile am Gate-Graph.
Deploy Development / deploy (push) Successful in 43s
Test Suite / pytest-backend (push) Failing after 2m18s
Test Suite / k6 /api/health Baseline (push) Has been skipped
Test Suite / playwright-smoke (push) Has been skipped
Test Suite / lint-backend (push) Successful in 2s
Test Suite / compose-smoke (push) Has been skipped

generic_operating ohne harte Blockade, Reifegrad-Methoden mit Erfuellungsgrad; Attention gate_graph_blocked fuer gate-orientierte Methoden.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
LarsandCursor committed 2026-07-11 08:06:42 +02:00
1 parent 4f8725e234
commit 1fa61b2dac
14 files changed
+426 -36

No files matched your search

+16 -3
View File
@@ -1,5 +1,18 @@
"""Roadmap graph read models (AP1.4d)."""
"""Roadmap graph read models (AP1.4d/4e)."""
from steering.graph.roadmap_engine import compute_initiative_graph_state
from steering.graph.profiles import GraphMethodProfile, get_graph_profile
from steering.graph.roadmap_engine import (
apply_graph_method_profile,
compute_initiative_graph_state,
compute_initiative_graph_state_with_profile,
load_initiative_graph_state,
)
__all__ = ["compute_initiative_graph_state"]
__all__ = [
"GraphMethodProfile",
"get_graph_profile",
"apply_graph_method_profile",
"compute_initiative_graph_state",
"compute_initiative_graph_state_with_profile",
"load_initiative_graph_state",
]
+51
View File
@@ -0,0 +1,51 @@
"""Method graph profiles — AP1.4e."""
from __future__ import annotations
from dataclasses import dataclass
DEFAULT_METHOD_KEY = "generic_operating"
@dataclass(frozen=True)
class GraphMethodProfile:
"""Steuert Graph-Read-Models pro steering_context.method_key."""
enforce_gate_blocking: bool
emphasize_fulfillment: bool
_STRICT = GraphMethodProfile(enforce_gate_blocking=True, emphasize_fulfillment=False)
_FULFILLMENT = GraphMethodProfile(enforce_gate_blocking=False, emphasize_fulfillment=True)
_LIGHT = GraphMethodProfile(enforce_gate_blocking=False, emphasize_fulfillment=False)
METHOD_GRAPH_PROFILES: dict[str, GraphMethodProfile] = {
"generic_operating": _LIGHT,
"queue_pull": _LIGHT,
"dispute_procedure": _LIGHT,
"continuous_product": _FULFILLMENT,
"maturity_progression": _FULFILLMENT,
"chapter_based_progression": _FULFILLMENT,
"product_milestone_driven": _STRICT,
"program_delivery": _STRICT,
"sequential_dependency": _STRICT,
"agile_iteration": _STRICT,
"recurring_control": _FULFILLMENT,
}
def get_graph_profile(method_key: str | None) -> GraphMethodProfile:
if not method_key:
return METHOD_GRAPH_PROFILES[DEFAULT_METHOD_KEY]
return METHOD_GRAPH_PROFILES.get(method_key, _STRICT)
def enforce_gate_blocking_for_method(method_key: str | None) -> bool:
return get_graph_profile(method_key).enforce_gate_blocking
def graph_profile_as_dict(profile: GraphMethodProfile) -> dict[str, bool]:
return {
"enforce_gate_blocking": profile.enforce_gate_blocking,
"emphasize_fulfillment": profile.emphasize_fulfillment,
}
+75 -3
View File
@@ -1,9 +1,16 @@
"""Roadmap gate graph read models — Plan-Zielzustand, kein Workflow (AP1.4d)."""
"""Roadmap graph read models — AP1.4d/4e."""
from __future__ import annotations
from typing import Any, Optional
from steering.graph.profiles import (
DEFAULT_METHOD_KEY,
GraphMethodProfile,
get_graph_profile,
graph_profile_as_dict,
)
TERMINAL_STATUSES = frozenset({"reached", "moved", "discarded"})
ACTIVE_STATUSES = frozenset({"planned", "active", "at_risk"})
BLOCKING_STATUSES = frozenset({"planned", "active", "at_risk"})
@@ -114,6 +121,7 @@ def compute_initiative_graph_state(
ratio = _fulfillment_ratio(criteria_progress.get(item_id))
item_states[item_id] = {
"status": status,
"blocked": blocked,
"ready": ready,
"blocked_by": blocked_by,
@@ -131,12 +139,72 @@ def compute_initiative_graph_state(
}
def _initiative_fulfillment_ratio(item_states: dict[str, dict[str, Any]]) -> Optional[float]:
ratios = [
st["fulfillment_ratio"]
for st in item_states.values()
if st.get("fulfillment_ratio") is not None
]
if not ratios:
return None
return round(sum(ratios) / len(ratios), 4)
def apply_graph_method_profile(
state: dict[str, Any], profile: GraphMethodProfile
) -> dict[str, Any]:
"""Passt blocked/ready an Methodenprofil an (AP1.4e)."""
if profile.enforce_gate_blocking:
state["graph_profile"] = graph_profile_as_dict(profile)
state["initiative_fulfillment_ratio"] = _initiative_fulfillment_ratio(state["items"])
return state
item_states = state["items"]
blocked_items: list[str] = []
ready_items: list[str] = []
for item_id, item_state in item_states.items():
would_block = item_state["blocked"]
item_state["would_block"] = would_block
item_state["blocked"] = False
status = item_state.get("status", "planned")
item_state["ready"] = status in ACTIVE_STATUSES
if item_state["ready"]:
ready_items.append(item_id)
state["items"] = item_states
state["blocked_items"] = blocked_items
state["ready_items"] = ready_items
state["graph_profile"] = graph_profile_as_dict(profile)
state["initiative_fulfillment_ratio"] = _initiative_fulfillment_ratio(item_states)
return state
def compute_initiative_graph_state_with_profile(
*,
items: list[dict[str, Any]],
dependencies: list[dict[str, Any]],
criteria_progress: Optional[dict[str, dict[str, int]]] = None,
method_key: Optional[str] = None,
) -> dict[str, Any]:
base = compute_initiative_graph_state(
items=items,
dependencies=dependencies,
criteria_progress=criteria_progress,
)
profile = get_graph_profile(method_key)
result = apply_graph_method_profile(base, profile)
result["method_key"] = method_key or DEFAULT_METHOD_KEY
return result
def load_initiative_graph_state(
*, tenant_id: str, initiative_id: str
) -> dict[str, Any]:
"""Lädt Items, Kanten und Kriterien-Fortschritt und berechnet Graph-State."""
"""Lädt Items, Kanten, Kriterien und Methodenprofil."""
from services import roadmap as roadmap_service
from services import roadmap_criteria as criteria_service
from services.steering_context import get_steering_context
items = roadmap_service.list_roadmap_items_for_initiative(
tenant_id=tenant_id, initiative_id=initiative_id
@@ -147,8 +215,12 @@ def load_initiative_graph_state(
criteria_progress = criteria_service.criteria_progress_for_initiative(
tenant_id=tenant_id, initiative_id=initiative_id
)
return compute_initiative_graph_state(
steering = get_steering_context(tenant_id=tenant_id, initiative_id=initiative_id)
method_key = (steering or {}).get("method_key") or DEFAULT_METHOD_KEY
return compute_initiative_graph_state_with_profile(
items=items,
dependencies=dependencies,
criteria_progress=criteria_progress,
method_key=method_key,
)
+67
View File
@@ -17,6 +17,7 @@ AttentionKind = Literal[
"initiative_without_next_action",
"stale_initiative",
"milestone_at_risk",
"gate_graph_blocked",
"overdue_action",
"review_due",
"recurring_due",
@@ -250,6 +251,71 @@ def _stale_initiatives(cur, ctx: TenantContext) -> list[dict[str, Any]]:
return [_serialize_attention(dict(r)) for r in cur.fetchall()]
def _graph_blocked_gates(cur, ctx: TenantContext) -> list[dict[str, Any]]:
from steering.graph.profiles import enforce_gate_blocking_for_method
from steering.graph.roadmap_engine import load_initiative_graph_state
cur.execute(
"""
SELECT sc.initiative_id, sc.method_key
FROM steering_contexts sc
JOIN initiatives i
ON i.id = sc.initiative_id AND i.tenant_id = sc.tenant_id
WHERE sc.tenant_id = %s AND i.status IN ('active', 'paused')
ORDER BY i.updated_at DESC
LIMIT 30
""",
(ctx.tenant_id,),
)
items: list[dict[str, Any]] = []
for row in cur.fetchall():
method_key = row.get("method_key") or "generic_operating"
if not enforce_gate_blocking_for_method(method_key):
continue
initiative_id = str(row["initiative_id"])
state = load_initiative_graph_state(
tenant_id=ctx.tenant_id, initiative_id=initiative_id
)
for gate_id in state.get("blocked_items", []):
cur.execute(
"""
SELECT title FROM roadmap_items
WHERE id = %s AND tenant_id = %s
""",
(gate_id, ctx.tenant_id),
)
gate_row = cur.fetchone()
if not gate_row:
continue
blocked_by = state["items"].get(gate_id, {}).get("blocked_by") or []
summary = (
"Graph-Voraussetzung noch nicht erreicht"
if len(blocked_by) != 1
else "Graph-Voraussetzung noch nicht erreicht"
)
items.append(
{
"kind": "gate_graph_blocked",
"severity": "warning",
"title": gate_row["title"],
"summary": summary,
"scope_type": "milestone",
"scope_id": gate_id,
"initiative_id": initiative_id,
"action_id": None,
"blocker_id": None,
"milestone_id": gate_id,
"reason_code": "gate_graph_blocked",
"data_source": "roadmap_graph",
}
)
if len(items) >= 20:
return items
return items
def _milestones_at_risk(cur, ctx: TenantContext) -> list[dict[str, Any]]:
cur.execute(
"""
@@ -424,6 +490,7 @@ def get_attention_items(ctx: TenantContext) -> list[dict[str, Any]]:
items.extend(_unassigned_actions(cur, ctx))
items.extend(_initiatives_without_next_action(cur, ctx))
items.extend(_stale_initiatives(cur, ctx))
items.extend(_graph_blocked_gates(cur, ctx))
items.extend(_milestones_at_risk(cur, ctx))
items.extend(_overdue_actions(cur, ctx))
items.extend(_actions_review_required(cur, ctx))
+27
View File
@@ -242,3 +242,30 @@ def test_initiative_roadmap_graph_state(client):
assert body["items"][gate_a["id"]]["blocked"] is True
assert gate_b["id"] in body["items"][gate_a["id"]]["blocked_by"]
assert gate_a["id"] not in body["ready_items"]
def test_graph_blocked_attention_for_gate_enforcing_method(client):
user = provision_user_in_tenant(tenant_role="member")
token = _login(client, user)
initiative_id = _create_initiative(client, token).json()["id"]
client.patch(
f"/api/steering/initiatives/{initiative_id}/context",
json={"method_key": "product_milestone_driven"},
headers=_auth(token),
)
gate_a = _create_roadmap_item(client, token, initiative_id, title="Gate A", sort_order=0).json()
gate_b = _create_roadmap_item(client, token, initiative_id, title="Gate B", sort_order=1).json()
client.post(
f"/api/roadmap-items/{gate_a['id']}/dependencies",
json={"to_item_id": gate_b["id"], "dependency_type": "requires"},
headers=_auth(token),
)
attention = client.get("/api/workspace/attention", headers=_auth(token))
assert attention.status_code == 200
assert any(
i["kind"] == "gate_graph_blocked" and i["milestone_id"] == gate_a["id"]
for i in attention.json()
)
@@ -0,0 +1,70 @@
"""Unit tests for graph method profiles (AP1.4e)."""
from steering.graph.profiles import get_graph_profile
from steering.graph.roadmap_engine import (
apply_graph_method_profile,
compute_initiative_graph_state,
compute_initiative_graph_state_with_profile,
)
def _item(item_id: str, status: str = "planned", **kwargs):
return {
"id": item_id,
"status": status,
"sort_order": kwargs.get("sort_order", 0),
"sequencing_mode": kwargs.get("sequencing_mode", "sequential"),
}
def test_generic_operating_does_not_enforce_blocking():
items = [
_item("first", "planned", sort_order=0),
_item("second", "planned", sort_order=1),
]
state = compute_initiative_graph_state_with_profile(
items=items,
dependencies=[],
method_key="generic_operating",
)
assert state["graph_profile"]["enforce_gate_blocking"] is False
assert state["items"]["second"]["would_block"] is True
assert state["items"]["second"]["blocked"] is False
assert state["items"]["second"]["ready"] is True
assert state["blocked_items"] == []
def test_product_milestone_enforces_blocking():
items = [
_item("first", "planned", sort_order=0),
_item("second", "planned", sort_order=1),
]
state = compute_initiative_graph_state_with_profile(
items=items,
dependencies=[],
method_key="product_milestone_driven",
)
assert state["graph_profile"]["enforce_gate_blocking"] is True
assert state["items"]["second"]["blocked"] is True
assert "second" in state["blocked_items"]
def test_maturity_progression_emphasizes_fulfillment():
profile = get_graph_profile("maturity_progression")
assert profile.emphasize_fulfillment is True
assert profile.enforce_gate_blocking is False
def test_initiative_fulfillment_ratio_average():
items = [_item("a", "active"), _item("b", "active")]
base = compute_initiative_graph_state(
items=items,
dependencies=[],
criteria_progress={
"a": {"total": 2, "closed": 2, "open": 0},
"b": {"total": 4, "closed": 2, "open": 2},
},
)
profile = get_graph_profile("maturity_progression")
state = apply_graph_method_profile(base, profile)
assert state["initiative_fulfillment_ratio"] == 0.75