feat(agent99): establish enterprise AI automation work ledger

2026-07-10 15:20:23 +08:00
parent a8080e13b9
commit 579d12c3fa
10 changed files with 1283 additions and 2 deletions
--- a/apps/api/src/services/agent99_enterprise_ai_automation_work_items.py
+++ b/apps/api/src/services/agent99_enterprise_ai_automation_work_items.py
@@ -0,0 +1,177 @@
+"""Agent99 enterprise AI-automation work-item readback."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from src.services.snapshot_paths import default_operations_dir
+
+_DEFAULT_OPERATIONS_DIR = default_operations_dir(Path(__file__))
+_SNAPSHOT_FILE = "agent99-enterprise-ai-automation-work-items.snapshot.json"
+_SCHEMA_VERSION = "agent99_enterprise_ai_automation_work_items_v1"
+_VALID_PRIORITIES = {"P0", "P1", "P2"}
+_VALID_STATUSES = {"planned", "in_progress", "in_progress_blocked", "complete"}
+
+
+def load_latest_agent99_enterprise_ai_automation_work_items(
+    operations_dir: Path | None = None,
+) -> dict[str, Any]:
+    """Load and validate the canonical Agent99 enterprise work ledger."""
+    directory = operations_dir or _DEFAULT_OPERATIONS_DIR
+    path = directory / _SNAPSHOT_FILE
+    with path.open(encoding="utf-8") as handle:
+        payload = json.load(handle)
+
+    if not isinstance(payload, dict):
+        raise ValueError(f"{path}: expected JSON object")
+    if payload.get("schema_version") != _SCHEMA_VERSION:
+        raise ValueError(f"{path}: unexpected schema_version")
+
+    coverage = _require_dict(payload, "coverage", path)
+    hosts = _require_list(coverage, "hosts", path)
+    products = _require_list(coverage, "products", path)
+    public_surfaces = _require_list(coverage, "public_surfaces", path)
+    work_items = _require_list(payload, "work_items", path)
+    summary = _require_dict(payload, "summary", path)
+    current_p0 = _require_dict(payload, "current_p0", path)
+    promotion_contract = _require_dict(payload, "promotion_contract", path)
+    required_p0_fields = _require_list(
+        promotion_contract,
+        "required_item_fields",
+        path,
+    )
+
+    _require_count(summary, "host_count", len(hosts), path)
+    _require_count(summary, "product_count", len(products), path)
+    _require_count(summary, "public_surface_count", len(public_surfaces), path)
+    _require_count(summary, "work_item_count", len(work_items), path)
+
+    ids: list[str] = []
+    orders: list[int] = []
+    priority_counts = {priority: 0 for priority in _VALID_PRIORITIES}
+    status_counts = {status: 0 for status in _VALID_STATUSES}
+    p0_ids: list[str] = []
+
+    for index, item in enumerate(work_items, start=1):
+        if not isinstance(item, dict):
+            raise ValueError(f"{path}: work_items[{index - 1}] must be an object")
+        item_id = item.get("id")
+        order = item.get("order")
+        priority = item.get("priority")
+        item_status = item.get("status")
+        if not isinstance(item_id, str) or not item_id:
+            raise ValueError(f"{path}: work_items[{index - 1}].id is required")
+        if not isinstance(order, int):
+            raise ValueError(f"{path}: {item_id}.order must be an integer")
+        if priority not in _VALID_PRIORITIES:
+            raise ValueError(f"{path}: {item_id}.priority is invalid")
+        if item_status not in _VALID_STATUSES:
+            raise ValueError(f"{path}: {item_id}.status is invalid")
+        if order != index:
+            raise ValueError(f"{path}: {item_id}.order must equal {index}")
+
+        ids.append(item_id)
+        orders.append(order)
+        priority_counts[priority] += 1
+        status_counts[item_status] += 1
+        if priority == "P0":
+            p0_ids.append(item_id)
+            missing = [field for field in required_p0_fields if item.get(field) is None]
+            if missing:
+                raise ValueError(f"{path}: {item_id} missing P0 fields: {missing}")
+
+    if len(ids) != len(set(ids)):
+        raise ValueError(f"{path}: duplicate work item id")
+    if orders != list(range(1, len(work_items) + 1)):
+        raise ValueError(f"{path}: work item order is not contiguous")
+
+    current_p0_id = current_p0.get("id")
+    if current_p0_id not in p0_ids:
+        raise ValueError(f"{path}: current_p0.id is not a P0 work item")
+    if not p0_ids or p0_ids[0] != current_p0_id:
+        raise ValueError(f"{path}: current_p0 must be the first ordered P0")
+    if payload.get("next_execution_order") != p0_ids:
+        raise ValueError(f"{path}: next_execution_order must equal ordered P0 ids")
+
+    _require_count(summary, "p0_count", priority_counts["P0"], path)
+    _require_count(summary, "p1_count", priority_counts["P1"], path)
+    _require_count(summary, "p2_count", priority_counts["P2"], path)
+    _require_count(summary, "planned_count", status_counts["planned"], path)
+    _require_count(
+        summary,
+        "in_progress_count",
+        status_counts["in_progress"],
+        path,
+    )
+    _require_count(
+        summary,
+        "in_progress_blocked_count",
+        status_counts["in_progress_blocked"],
+        path,
+    )
+    _require_count(summary, "complete_count", status_counts["complete"], path)
+    _require_count(summary, "current_p0_count", 1, path)
+
+    return payload
+
+
+def build_agent99_enterprise_priority_projection(
+    payload: dict[str, Any],
+) -> dict[str, Any]:
+    """Build the bounded projection embedded in the main priority endpoint."""
+    coverage = payload["coverage"]
+    summary = payload["summary"]
+    return {
+        "schema_version": payload["schema_version"],
+        "generated_at": payload["generated_at"],
+        "status": payload["status"],
+        "scope_complete": payload["scope_complete"],
+        "current_p0": payload["current_p0"],
+        "coverage": {
+            "host_count": len(coverage["hosts"]),
+            "product_count": len(coverage["products"]),
+            "public_surface_count": len(coverage["public_surfaces"]),
+            "service_domain_count": len(coverage["service_domains"]),
+            "package_domain_count": len(coverage["package_domains"]),
+        },
+        "work_item_counts": {
+            "total": summary["work_item_count"],
+            "p0": summary["p0_count"],
+            "p1": summary["p1_count"],
+            "p2": summary["p2_count"],
+            "in_progress": summary["in_progress_count"],
+            "in_progress_blocked": summary["in_progress_blocked_count"],
+            "planned": summary["planned_count"],
+            "complete": summary["complete_count"],
+        },
+        "next_execution_order": payload["next_execution_order"],
+        "full_readback_api": "/api/v1/agents/agent99-enterprise-ai-automation-work-items",
+    }
+
+
+def _require_dict(payload: dict[str, Any], key: str, path: Path) -> dict[str, Any]:
+    value = payload.get(key)
+    if not isinstance(value, dict):
+        raise ValueError(f"{path}: {key} must be an object")
+    return value
+
+
+def _require_list(payload: dict[str, Any], key: str, path: Path) -> list[Any]:
+    value = payload.get(key)
+    if not isinstance(value, list):
+        raise ValueError(f"{path}: {key} must be an array")
+    return value
+
+
+def _require_count(
+    summary: dict[str, Any],
+    key: str,
+    expected: int,
+    path: Path,
+) -> None:
+    if summary.get(key) != expected:
+        raise ValueError(
+            f"{path}: summary.{key}={summary.get(key)!r}, expected {expected}"
+        )
--- a/apps/api/src/services/awoooi_priority_work_order_readback.py
+++ b/apps/api/src/services/awoooi_priority_work_order_readback.py
@@ -17,6 +17,10 @@ from pathlib import Path
 from typing import Any
 from zoneinfo import ZoneInfo

+from src.services.agent99_enterprise_ai_automation_work_items import (
+    build_agent99_enterprise_priority_projection,
+    load_latest_agent99_enterprise_ai_automation_work_items,
+)
 from src.services.snapshot_paths import default_operations_dir

 _DEFAULT_OPERATIONS_DIR = default_operations_dir(Path(__file__))
@@ -870,11 +874,38 @@ def load_latest_awoooi_priority_work_order_readback(
    )
    _require_mainline_consistency(payload, str(path))
    _apply_commander_inserted_requirement_work_items(payload)
+    _apply_agent99_enterprise_ai_automation_projection(payload, directory)
    _mark_runtime_generated_at(payload)
    apply_ai_automation_node_receipts(payload)
    return payload


+def _apply_agent99_enterprise_ai_automation_projection(
+    payload: dict[str, Any],
+    operations_dir: Path,
+) -> None:
+    """Attach a bounded projection while keeping fixture-only snapshots usable."""
+    try:
+        enterprise = load_latest_agent99_enterprise_ai_automation_work_items(
+            operations_dir
+        )
+    except FileNotFoundError:
+        return
+
+    payload["agent99_enterprise_ai_automation"] = (
+        build_agent99_enterprise_priority_projection(enterprise)
+    )
+    source_refs = payload.setdefault("source_refs", {})
+    if isinstance(source_refs, dict):
+        source_refs["agent99_enterprise_ai_automation_work_items"] = (
+            "docs/operations/"
+            "agent99-enterprise-ai-automation-work-items.snapshot.json"
+        )
+        source_refs["agent99_enterprise_ai_automation_work_items_api"] = (
+            "/api/v1/agents/agent99-enterprise-ai-automation-work-items"
+        )
+
+
 def load_controlled_cd_lane_live_metric_readback(
    metrics_url: str = _CONTROLLED_CD_LANE_NODE_EXPORTER_URL,
    prometheus_query_url: str = _CONTROLLED_CD_LANE_PROMETHEUS_QUERY_URL,