@0dai-dev/cli 4.3.5 → 4.3.7

package/lib/python/graph_legacy.py

@@ -0,0 +1,2052 @@
+#!/usr/bin/env python3
+# pragma: loc-waiver — #1069 split: pure helpers extracted to graph_legacy_helpers.py (2245->2052); residual surplus is stateful graph-mutation + constraint/outcome/deliberation + CLI logic, deferred to a follow-up
+"""0dai Project Context Graph — typed knowledge graph for project state.
+
+Implements the schema from docs/project-context-graph.md (derived from
+`user_submitted/project context graph schema.pdf`):
+
+  - 10 node types (§1): Component, Technology, Decision, Requirement, Risk,
+    TestPlan, Endpoint, DesignArtifact, MarketEntity, Session, Deliberation
+  - 20+ edge types (§2): architecture, decision, quality, design, market,
+    ownership, session
+  - JSON adjacency list format (§3): `project_graph.json`
+  - Traversal algorithm (§4): anchor extraction → BFS 2-hop expand →
+    role-filter → serialize ≤400 tokens
+  - Query patterns (§8): decisions_for, tech_context, open_risks, impact,
+    stale_tech, unsatisfied_reqs
+
+Distinct from `scripts/generate_project_layer.py` (which generates flat
+YAML) — this module manages the TYPED graph that deliberations mutate.
+
+Bootstrap from project-layer.yaml is in `scripts/generate_project_graph.py`.
+Integration into working_group._build_context_slice is M14 work.
+
+Design notes:
+  - Flat JSON adjacency list until graph exceeds 500 nodes (per PDF §6.3).
+    Migration path to Kuzu/SurrealDB/Neo4j is a future concern.
+  - No PyYAML dependency. Stdlib only (constraint_no_go in project-layer).
+  - Node IDs follow `<type_prefix>_<slug>` convention for grep-friendly
+    category filtering without reading node.type field.
+  - Thread-safe for single-writer (working_group orchestrator) only.
+    Concurrent mutation from multiple processes is not supported.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import fnmatch  # noqa: F401 retained for back-compat re-export (graph facade star-imports graph_legacy)
+import json
+import logging
+import pathlib
+import re
+from typing import Any, Iterable, Optional
+
+from graph_legacy_helpers import (  # noqa: F401 re-export for back-compat (#757 #1069)
+    _extract_keywords,
+    _extract_violation_pattern,
+    _line_matches_constraint_rule,
+    _parse_constraints_yaml,
+    _parse_diff_lines,
+    _path_patterns_overlap,
+    matches_constraint_diff,
+)
+
+log = logging.getLogger("0dai.graph")
+
+SCHEMA_VERSION = 1
+
+# ---------------------------------------------------------------------------
+# Node + edge type registries (PDF §1-§2)
+# ---------------------------------------------------------------------------
+
+# Node types — the 10 taxonomic categories plus meta categories.
+# Each node's `type` field MUST be a member of this set, or validation fails.
+#
+# `Outcome` added in M13 P2 for EP-02 (Outcome Tracking & Error Memory).
+# An Outcome node records what actually happened after a Decision was
+# applied in practice — status, lessons learned, tags for semantic search.
+NODE_TYPES = frozenset({
+    "Component",        # product parts: services, modules, pages
+    "Technology",       # external tech: frameworks, languages, libraries
+    "Decision",         # architectural/product decisions from deliberations
+    "Requirement",      # functional + non-functional requirements
+    "Risk",             # identified concerns + open risks
+    "TestPlan",         # test strategy nodes
+    "Endpoint",         # API endpoints + entry points
+    "DesignArtifact",   # UX mockups, flows, brand artifacts
+    "MarketEntity",     # competitors, target segments, market forces
+    "Session",          # meta: a work session
+    "Deliberation",     # meta: a working-group deliberation
+    "Outcome",          # M13 P2 EP-02: retrospective evaluation of a Decision
+    "Artifact",         # M19 P0: release artifacts (versions, tags)
+    "Event",            # M19 P0: session/meta events for timeline queries
+    "Constraint",       # #479: architecture constraints — hard rules from decisions
+})
+
+# Prefix convention for node IDs. Helps filter/grep by category without
+# loading the full node object.
+NODE_ID_PREFIXES: dict[str, str] = {
+    "Component": "comp",
+    "Technology": "tech",
+    "Decision": "dec",
+    "Requirement": "req",
+    "Risk": "risk",
+    "TestPlan": "test",
+    "Endpoint": "ep",
+    "DesignArtifact": "design",
+    "MarketEntity": "mkt",
+    "Session": "session",
+    "Deliberation": "delib",
+    "Outcome": "outcome",  # M13 P2 EP-02
+    "Artifact": "artifact",  # M19 P0: release artifacts
+    "Event": "event",        # M19 P0: session/meta events
+    "Constraint": "cstr",    # #479: architecture constraints
+}
+
+# Edge types — the 20+ relation categories. Each edge's `type` field MUST
+# be a member of this set. See docs/project-context-graph.md §2 for
+# direction semantics + allowed source/target type pairs.
+EDGE_TYPES = frozenset({
+    # Architecture
+    "uses",            # Component -> Technology
+    "depends_on",      # Component -> Component
+    "exposes",         # Component -> Endpoint
+    "part_of",         # Component -> Component (sub-module relation)
+    # Decision
+    "affects",         # Decision -> Component | Technology | Requirement
+    "chose",           # Decision -> Technology (picked this over alt)
+    "satisfies",       # Decision -> Requirement
+    "supersedes",      # Decision -> Decision (new replaces old)
+    "introduces",      # Decision -> Risk (new risk from this choice)
+    "mitigates",       # Decision -> Risk (resolves existing risk)
+    "decided_in",      # Decision -> Deliberation
+    # Quality
+    "covers",          # TestPlan -> Component | Requirement
+    "tests",           # TestPlan -> Component
+    "blocks",          # Risk -> Component | Decision
+    "violates",        # Component -> Requirement (currently failing)
+    # Design
+    "designs",         # DesignArtifact -> Component
+    "follows",         # DesignArtifact -> DesignArtifact (style guide)
+    # Market
+    "targets",         # Component | Decision -> MarketEntity
+    "competes_with",   # MarketEntity -> MarketEntity
+    # Ownership
+    "owned_by",        # Component -> Session (last-touched bookkeeping)
+    "identified_by",   # Risk -> Session | Deliberation
+    "created_by",      # Decision -> Deliberation
+    "approved_by",     # Decision -> Session
+    # Session
+    "produced",        # Session -> Decision | Component
+    "updated",         # Session -> Component
+    # M13 P2 EP-02: Outcome Tracking
+    "evaluates",       # Outcome -> Decision (retrospective evaluation)
+    "decision_outcome",  # Decision -> Outcome (task-result feedback loop)
+    # EP: Decision Ancestry
+    "decision_ancestry",  # Decision -> Decision (child influenced by parent)
+    # M19 P0: Graph dogfood
+    "released_as",     # Decision -> Artifact (decision shipped in version)
+    "contains",        # Artifact -> Decision (version contains decisions)
+    "triggered_by",    # Event -> Session (event caused by session)
+    "observed_in",     # Event -> Artifact (event observed in version)
+    # #479: Architecture Constraints
+    "declared_by",     # Constraint -> Decision (constraint derived from this decision)
+    "implies",         # Constraint -> Constraint (constraint A implies constraint B)
+    "constrains",      # Constraint -> Component | Technology (scope of constraint)
+    "forbids",         # Constraint -> Component | Technology (anti-pattern scope)
+})
+
+# Valid status values for Outcome nodes per PDF enhancement pack EP-02.
+# `confirmed`: decision played out as predicted
+# `revised`: decision needed adjustment but core idea was sound
+# `reverted`: decision was rolled back, lesson learned
+# `partially_applied`: decision implemented partially, rest is still pending
+OUTCOME_STATUSES = frozenset({
+    "confirmed",
+    "revised",
+    "reverted",
+    "partially_applied",
+})
+
+# Stage-based review threshold for outcomes (PDF EP-02).
+# Decisions older than this threshold without an Outcome get flagged.
+# Matches project-layer.yaml `stage` values; fallback is 30 days.
+STAGE_OUTCOME_THRESHOLDS_DAYS: dict[str, int] = {
+    "idea": 14,
+    "mvp": 14,
+    "growth": 30,
+    "scale": 60,
+}
+DEFAULT_STAGE_THRESHOLD_DAYS = 30
+
+# Role type-interest map (PDF §4 step 3). When building a context slice
+# for a given role, only include nodes whose type is in the role's
+# interest set. Unknown roles fall back to ALL_TYPES (no filter).
+ROLE_TYPE_INTERESTS: dict[str, frozenset[str]] = {
+    "cto": frozenset({"Decision", "Technology", "Risk", "Component", "Requirement", "Constraint"}),
+    "arch": frozenset({"Component", "Technology", "Endpoint", "Requirement", "Risk", "Constraint"}),
+    "designer": frozenset({"DesignArtifact", "Component", "Requirement"}),
+    "art_director": frozenset({"DesignArtifact", "Component", "MarketEntity"}),
+    "qa": frozenset({"TestPlan", "Component", "Risk", "Requirement", "Constraint"}),
+    "security": frozenset({"Risk", "Requirement", "Component", "Technology", "Constraint"}),
+    "sre": frozenset({"Component", "Technology", "Risk", "Endpoint", "Constraint"}),
+    "cmo": frozenset({"MarketEntity", "Requirement", "Component", "Decision"}),
+}
+
+# Default edge weight when caller does not supply one. Traversal uses
+# weight to decide whether hop-2 edges are worth following (threshold
+# in expand_bfs).
+DEFAULT_EDGE_WEIGHT = 1.0
+HOP2_WEIGHT_THRESHOLD = 0.5  # hop-2 edges below this are pruned
+
+# Serialization token budget for context slice (PDF §4 step 4).
+# 4 chars per token is a coarse but conservative estimate (matches OpenAI
+# tokenizer for English text).
+CHARS_PER_TOKEN = 4
+DEFAULT_SLICE_TOKEN_BUDGET = 400
+
+# ---------------------------------------------------------------------------
+# M14: Provenance — "what 0dai KNOWS vs what 0dai THINKS" (Torvalds critique)
+# ---------------------------------------------------------------------------
+#
+# Every node carries a `source_type` field indicating how the data was
+# derived. Deterministic sources (file_parse, git_diff, operator) are
+# "KNOWS" — they can be trusted as facts. LLM-derived sources
+# (scout_ai, deliberation_ai) are "THINKS" — they're opinions that may
+# hallucinate. CLI output must visually distinguish the two so users
+# don't treat LLM opinions as facts.
+#
+# Per Torvalds (2026-04-08 01:06 UTC):
+#   "Чётко раздели: вот что 0dai ЗНАЕТ (из графа, из файлов, из API headers).
+#    Вот что 0dai ДУМАЕТ (из LLM inference). Никогда не смешивай."
+
+DETERMINISTIC_SOURCES = frozenset({
+    "bootstrap",        # generate_project_graph.py from project-layer.yaml
+    "file_parse",       # detected from package.json, pyproject.toml, etc.
+    "git_diff",         # parsed from git diff (regex, not LLM)
+    "operator",         # manually entered via 0dai graph add / 0dai learn
+    "tool_output",      # npm_audit, eslint, lighthouse, etc. (EP-03)
+})
+
+AI_DERIVED_SOURCES = frozenset({
+    "scout_ai",         # scout CLI web search findings
+    "deliberation_ai",  # working-group synthesis extraction
+    "hard_block",       # parsed from deliberation hard block strings (LLM-derived)
+    "red_team_ai",      # EP-04 adversarial review
+    "forecast_ai",      # EP-14 temporal simulation
+    "pattern_ai",       # EP-09 cross-project pattern matching
+})
+
+DEFAULT_SOURCE = "operator"
+
+
+def is_deterministic_source(source_type: str) -> bool:
+    """Return True if the source is considered 'KNOWS' (vs 'THINKS')."""
+    return source_type in DETERMINISTIC_SOURCES
+
+
+def source_marker(source_type: str) -> str:
+    """Return a visual marker for CLI output: ✓ for KNOWS, ~ for THINKS."""
+    if is_deterministic_source(source_type):
+        return "✓"
+    if source_type in AI_DERIVED_SOURCES:
+        return "~"
+    return "?"
+
+
+# ---------------------------------------------------------------------------
+# Graph construction helpers
+# ---------------------------------------------------------------------------
+
+def empty_graph() -> dict:
+    """Return a fresh, empty graph with schema metadata populated.
+
+    Callers should prefer this over building a dict by hand — it
+    guarantees `nodes`, `edges`, and `meta` keys are present with the
+    right types, which keeps validation passing.
+    """
+    now = _now_iso()
+    return {
+        "nodes": {},
+        "edges": [],
+        "meta": {
+            "schema_version": SCHEMA_VERSION,
+            "created_at": now,
+            "updated_at": now,
+            "node_count": 0,
+            "edge_count": 0,
+        },
+    }
+
+
+def _now_iso() -> str:
+    """Return UTC timestamp in ISO 8601 format with trailing Z."""
+    return _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _slug(text: str) -> str:
+    """Produce a grep-friendly id fragment from arbitrary text."""
+    cleaned = re.sub(r"[^a-zA-Z0-9]+", "_", text.strip().lower())
+    return cleaned.strip("_") or "unnamed"
+
+
+def make_node_id(node_type: str, name: str) -> str:
+    """Construct a canonical node id from type + free-form name.
+
+    Example:
+        make_node_id("Technology", "Next.js 14") -> "tech_next_js_14"
+    """
+    prefix = NODE_ID_PREFIXES.get(node_type)
+    if not prefix:
+        raise ValueError(f"unknown node type: {node_type}")
+    return f"{prefix}_{_slug(name)}"
+
+
+def add_node(
+    graph: dict,
+    node_id: str,
+    node_type: str,
+    name: str,
+    *,
+    status: str = "active",
+    description: str = "",
+    source_type: str = DEFAULT_SOURCE,
+    extra: Optional[dict[str, Any]] = None,
+) -> dict:
+    """Add (or update in place) a node in the graph.
+
+    Returns the node dict after insertion. Idempotent — calling twice
+    with the same id updates the existing node's fields instead of
+    raising. This matches the mutation-queue conflict resolution policy
+    from PDF §5.3 (duplicate id → update).
+
+    M14 addition: `source_type` marks the node as deterministic (KNOWS)
+    or AI-derived (THINKS). See DETERMINISTIC_SOURCES / AI_DERIVED_SOURCES
+    module-level constants. CLI output distinguishes the two so users
+    don't treat LLM opinions as facts (per Torvalds critique).
+    """
+    if node_type not in NODE_TYPES:
+        raise ValueError(f"unknown node type: {node_type!r}")
+    if not node_id:
+        raise ValueError("node id must be non-empty")
+
+    now = _now_iso()
+    existing = graph["nodes"].get(node_id)
+    if existing:
+        existing["type"] = node_type
+        existing["name"] = name
+        existing["status"] = status
+        existing["description"] = description
+        existing["updated_at"] = now
+        # Source-type update rules (M14 Torvalds-separation):
+        # - new is deterministic: always overwrite (operator/file wins)
+        # - new is AI AND existing is deterministic: REJECT (protect facts)
+        # - new is AI AND existing is AI: overwrite (fresher AI signal)
+        existing_source = existing.get("source_type", DEFAULT_SOURCE)
+        if is_deterministic_source(source_type):
+            existing["source_type"] = source_type
+        elif not is_deterministic_source(existing_source):
+            existing["source_type"] = source_type
+        # else: AI trying to overwrite deterministic → silently ignored
+        if extra:
+            existing.update(extra)
+        graph["meta"]["updated_at"] = now
+        return existing
+
+    node = {
+        "id": node_id,
+        "type": node_type,
+        "name": name,
+        "status": status,
+        "description": description,
+        "source_type": source_type,
+        "created_at": now,
+        "updated_at": now,
+    }
+    if extra:
+        node.update(extra)
+    graph["nodes"][node_id] = node
+    graph["meta"]["node_count"] = len(graph["nodes"])
+    graph["meta"]["updated_at"] = now
+    return node
+
+
+def add_edge(
+    graph: dict,
+    source: str,
+    target: str,
+    edge_type: str,
+    *,
+    weight: float = DEFAULT_EDGE_WEIGHT,
+    extra: Optional[dict[str, Any]] = None,
+) -> dict:
+    """Add a directed edge to the graph.
+
+    No duplicate detection — callers that want "upsert" semantics should
+    check first with `find_edge`. This matches PDF §5.2: mutation queue
+    applies atomically, and orchestrator is the single writer.
+
+    Edge format:
+        {"from": source, "to": target, "type": edge_type,
+         "weight": weight, "created_at": iso}
+
+    Raises ValueError if source/target don't exist in graph (placeholder
+    nodes should be created first per §5.3 conflict resolution).
+    """
+    if edge_type not in EDGE_TYPES:
+        raise ValueError(f"unknown edge type: {edge_type!r}")
+    if source not in graph["nodes"]:
+        raise ValueError(f"edge source {source!r} not in graph")
+    if target not in graph["nodes"]:
+        raise ValueError(f"edge target {target!r} not in graph")
+
+    edge = {
+        "from": source,
+        "to": target,
+        "type": edge_type,
+        "weight": float(weight),
+        "created_at": _now_iso(),
+    }
+    if extra:
+        edge.update(extra)
+    graph["edges"].append(edge)
+    graph["meta"]["edge_count"] = len(graph["edges"])
+    graph["meta"]["updated_at"] = edge["created_at"]
+    return edge
+
+
+def find_edge(
+    graph: dict,
+    source: str,
+    target: str,
+    edge_type: Optional[str] = None,
+) -> Optional[dict]:
+    """Return first matching edge or None."""
+    for edge in graph["edges"]:
+        if edge["from"] == source and edge["to"] == target:
+            if edge_type is None or edge["type"] == edge_type:
+                return edge
+    return None
+
+
+def outgoing_edges(graph: dict, node_id: str) -> list[dict]:
+    """Return all edges where node_id is the source."""
+    return [e for e in graph["edges"] if e["from"] == node_id]
+
+
+def incoming_edges(graph: dict, node_id: str) -> list[dict]:
+    """Return all edges where node_id is the target."""
+    return [e for e in graph["edges"] if e["to"] == node_id]
+
+
+def nodes_by_type(graph: dict, node_type: str) -> list[dict]:
+    """Return all nodes of a given type, sorted by id for stability."""
+    return sorted(
+        (n for n in graph["nodes"].values() if n.get("type") == node_type),
+        key=lambda n: n["id"],
+    )
+
+
+def _usage_path(path: pathlib.Path) -> pathlib.Path:
+    """Return the sidecar path used for graph usage counters."""
+    path = pathlib.Path(path)
+    return path.with_name(f"{path.stem}_usage{path.suffix}")
+
+
+def _default_usage() -> dict:
+    """Return a fresh graph usage payload."""
+    return {
+        "schema_version": 1,
+        "updated_at": _now_iso(),
+        "totals": {
+            "loads": 0,
+            "queries": 0,
+            "updates": 0,
+            "saves": 0,
+        },
+        "operations": {},
+        "recent": [],
+    }
+
+
+def load_graph_usage(path: pathlib.Path) -> dict:
+    """Load graph usage counters for a graph path."""
+    usage_path = _usage_path(path)
+    if not usage_path.exists():
+        return _default_usage()
+    try:
+        payload = json.loads(usage_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return _default_usage()
+
+    default = _default_usage()
+    if not isinstance(payload, dict):
+        return default
+
+    totals = payload.get("totals")
+    if not isinstance(totals, dict):
+        payload["totals"] = default["totals"]
+    else:
+        for key, value in default["totals"].items():
+            totals[key] = int(totals.get(key, value) or 0)
+
+    operations = payload.get("operations")
+    if not isinstance(operations, dict):
+        payload["operations"] = {}
+
+    recent = payload.get("recent")
+    if not isinstance(recent, list):
+        payload["recent"] = []
+
+    payload["schema_version"] = int(payload.get("schema_version", 1) or 1)
+    payload["updated_at"] = str(payload.get("updated_at") or default["updated_at"])
+    return payload
+
+
+def save_graph_usage(path: pathlib.Path, usage: dict) -> None:
+    """Persist graph usage counters to the sidecar file."""
+    usage_path = _usage_path(path)
+    usage_path.parent.mkdir(parents=True, exist_ok=True)
+    usage_path.write_text(json.dumps(usage, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def record_graph_usage(
+    graph: dict,
+    operation: str,
+    *,
+    kind: str = "queries",
+    count: int = 1,
+) -> None:
+    """Increment usage counters for a graph-backed operation.
+
+    Graphs loaded through load_graph() carry a private `_usage_path`
+    marker so callers can bump counters without threading file paths
+    through every query helper.
+    """
+    usage_path_raw = graph.get("_usage_path")
+    if not usage_path_raw:
+        return
+
+    try:
+        graph_path = pathlib.Path(str(usage_path_raw))
+        payload = load_graph_usage(graph_path)
+    except (TypeError, ValueError):
+        return
+
+    totals = payload.setdefault("totals", _default_usage()["totals"])
+    if kind in totals:
+        totals[kind] = int(totals.get(kind, 0) or 0) + count
+    operations = payload.setdefault("operations", {})
+    operations[operation] = int(operations.get(operation, 0) or 0) + count
+    payload["updated_at"] = _now_iso()
+    recent = payload.setdefault("recent", [])
+    recent.insert(0, {
+        "operation": operation,
+        "kind": kind,
+        "count": count,
+        "at": payload["updated_at"],
+    })
+    del recent[20:]
+
+    try:
+        save_graph_usage(graph_path, payload)
+    except OSError:
+        return
+
+
+def summarize_graph_usage(path: pathlib.Path) -> dict:
+    """Load a graph usage ledger and add a compact top-operations view."""
+    usage = load_graph_usage(path)
+    operations = usage.get("operations", {})
+    if isinstance(operations, dict):
+        usage["top_operations"] = [
+            {"operation": name, "count": count}
+            for name, count in sorted(
+                ((str(name), int(count or 0)) for name, count in operations.items()),
+                key=lambda item: (-item[1], item[0]),
+            )[:8]
+        ]
+    else:
+        usage["top_operations"] = []
+    return usage
+
+
+# ---------------------------------------------------------------------------
+# Validation (for round-trip + bootstrap safety)
+# ---------------------------------------------------------------------------
+
+class GraphValidationError(ValueError):
+    """Raised when a graph fails structural validation."""
+
+
+def validate_graph(graph: dict) -> list[str]:
+    """Return a list of validation errors (empty list == valid).
+
+    Soft-checks (logs warning but does NOT fail):
+      - orphan nodes (no incoming + no outgoing edges)
+      - dangling edges (referencing unknown node id)
+
+    Hard-checks (appended to error list):
+      - missing `nodes`, `edges`, `meta` keys
+      - node missing `type` or `id`
+      - node type not in NODE_TYPES
+      - edge type not in EDGE_TYPES
+      - schema_version mismatch
+    """
+    errors: list[str] = []
+
+    for key in ("nodes", "edges", "meta"):
+        if key not in graph:
+            errors.append(f"missing top-level key: {key}")
+    if errors:
+        return errors
+
+    if not isinstance(graph["nodes"], dict):
+        errors.append("nodes must be a dict")
+    if not isinstance(graph["edges"], list):
+        errors.append("edges must be a list")
+    if errors:
+        return errors
+
+    meta_version = graph["meta"].get("schema_version")
+    if meta_version != SCHEMA_VERSION:
+        errors.append(
+            f"schema_version mismatch: expected {SCHEMA_VERSION}, got {meta_version}"
+        )
+
+    for node_id, node in graph["nodes"].items():
+        if node.get("id") != node_id:
+            errors.append(f"node id mismatch: key={node_id}, node.id={node.get('id')}")
+        node_type = node.get("type")
+        if node_type not in NODE_TYPES:
+            errors.append(f"node {node_id} has unknown type: {node_type!r}")
+        for field in ("name", "status", "created_at", "updated_at"):
+            if field not in node:
+                errors.append(f"node {node_id} missing required field: {field}")
+
+    seen_edges: set[tuple] = set()
+    for i, edge in enumerate(graph["edges"]):
+        for field in ("from", "to", "type"):
+            if field not in edge:
+                errors.append(f"edge[{i}] missing field: {field}")
+                continue
+        edge_type = edge.get("type")
+        if edge_type not in EDGE_TYPES:
+            errors.append(f"edge[{i}] has unknown type: {edge_type!r}")
+        src, tgt = edge.get("from"), edge.get("to")
+        if src not in graph["nodes"]:
+            log.warning("edge[%d] dangling source: %s", i, src)
+        if tgt not in graph["nodes"]:
+            log.warning("edge[%d] dangling target: %s", i, tgt)
+        key = (src, tgt, edge_type)
+        if key in seen_edges:
+            log.warning("edge[%d] duplicate: %s -> %s [%s]", i, src, tgt, edge_type)
+        seen_edges.add(key)
+
+    return errors
+
+
+# ---------------------------------------------------------------------------
+# JSON I/O
+# ---------------------------------------------------------------------------
+
+def load_graph(path: pathlib.Path) -> dict:
+    """Load graph from a JSON file. Returns empty_graph() if file absent.
+
+    Absence is not an error — many 0dai projects start without a graph
+    and bootstrap lazily. Callers that need "must exist" semantics should
+    check path.exists() first.
+    """
+    path = pathlib.Path(path)
+    if not path.exists():
+        log.info("graph file %s does not exist; returning empty graph", path)
+        graph = empty_graph()
+        graph["_usage_path"] = str(path)
+        record_graph_usage(graph, "load_graph", kind="loads")
+        return graph
+
+    with path.open("r", encoding="utf-8") as f:
+        data = json.load(f)
+    data["_usage_path"] = str(path)
+    record_graph_usage(data, "load_graph", kind="loads")
+
+    errors = validate_graph(data)
+    if errors:
+        raise GraphValidationError(
+            f"graph at {path} failed validation:\n  " + "\n  ".join(errors)
+        )
+    return data
+
+
+def save_graph(path: pathlib.Path, graph: dict, *, validate: bool = True) -> None:
+    """Write graph to a JSON file with stable key ordering.
+
+    Stable ordering is critical for Git-friendly diffs (per M13 plan
+    "Git-friendly — stable file names, predictable frontmatter order,
+    minimal diff noise"). Nodes sorted by id, edges sorted by
+    (from, to, type).
+    """
+    path = pathlib.Path(path)
+    if validate:
+        errors = validate_graph(graph)
+        if errors:
+            raise GraphValidationError(
+                "refusing to save invalid graph:\n  " + "\n  ".join(errors)
+            )
+
+    graph["meta"]["updated_at"] = _now_iso()
+    graph["meta"]["node_count"] = len(graph["nodes"])
+    graph["meta"]["edge_count"] = len(graph["edges"])
+
+    stable = {
+        "meta": graph["meta"],
+        "nodes": dict(sorted(graph["nodes"].items())),
+        "edges": sorted(
+            graph["edges"],
+            key=lambda e: (e.get("from", ""), e.get("to", ""), e.get("type", "")),
+        ),
+    }
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as f:
+        json.dump(stable, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+    graph["_usage_path"] = str(path)
+    record_graph_usage(graph, "save_graph", kind="saves")
+
+
+# ---------------------------------------------------------------------------
+# Traversal: anchor extraction → BFS expand → role filter → serialize (§4)
+# ---------------------------------------------------------------------------
+
+def extract_anchors(graph: dict, task_text: str, max_anchors: int = 8) -> list[str]:
+    """Find node ids that plausibly anchor to the task text (PDF §4 step 1).
+
+    Matching strategy (in priority order):
+      1. Exact node id match (`comp_api_gateway` appears verbatim in text)
+      2. Node name substring match (case-insensitive)
+      3. Slugified name match (for tech like "Next.js" -> "next_js")
+
+    Returns at most `max_anchors` ids, deduped, order preserved by
+    match score (id match beats name match beats slug match).
+
+    Empty task text returns an empty list — traversal caller should
+    fall back to "all tech nodes" via tech_context() in that case.
+    """
+    record_graph_usage(graph, "extract_anchors", kind="queries")
+    if not task_text.strip():
+        return []
+
+    text_lower = task_text.lower()
+    scores: dict[str, int] = {}
+
+    for node_id, node in graph["nodes"].items():
+        # Score 3: exact id match
+        if node_id in task_text:
+            scores[node_id] = max(scores.get(node_id, 0), 3)
+            continue
+
+        name = node.get("name", "")
+        name_lower = name.lower()
+        if name_lower and name_lower in text_lower:
+            scores[node_id] = max(scores.get(node_id, 0), 2)
+            continue
+
+        slug = _slug(name)
+        if slug and len(slug) >= 3 and slug in text_lower:
+            scores[node_id] = max(scores.get(node_id, 0), 1)
+
+    ranked = sorted(scores.items(), key=lambda kv: (-kv[1], kv[0]))
+    return [node_id for node_id, _score in ranked[:max_anchors]]
+
+
+def expand_bfs(
+    graph: dict,
+    anchors: Iterable[str],
+    *,
+    hops: int = 2,
+    hop2_weight_threshold: float = HOP2_WEIGHT_THRESHOLD,
+) -> set[str]:
+    """BFS expand from anchor nodes up to `hops` (PDF §4 step 2).
+
+    Hop 1 follows all edges unconditionally. Hop 2 only follows edges
+    with weight >= hop2_weight_threshold (the "edge weight filter" from
+    the spec — prevents hop-2 explosion for densely-connected graphs).
+
+    Both outgoing and incoming edges are traversed — for a context
+    slice, "components that use this tech" and "tech used by this
+    component" are equally relevant.
+    """
+    record_graph_usage(graph, "expand_bfs", kind="queries")
+    if hops < 1:
+        raise ValueError(f"hops must be >= 1, got {hops}")
+
+    visited: set[str] = set()
+    frontier: set[str] = set()
+
+    for anchor in anchors:
+        if anchor in graph["nodes"]:
+            visited.add(anchor)
+            frontier.add(anchor)
+
+    for hop in range(1, hops + 1):
+        next_frontier: set[str] = set()
+        for node_id in frontier:
+            for edge in graph["edges"]:
+                if edge["from"] != node_id and edge["to"] != node_id:
+                    continue
+                if hop >= 2 and edge.get("weight", DEFAULT_EDGE_WEIGHT) < hop2_weight_threshold:
+                    continue
+                neighbor = edge["to"] if edge["from"] == node_id else edge["from"]
+                if neighbor not in visited and neighbor in graph["nodes"]:
+                    next_frontier.add(neighbor)
+                    visited.add(neighbor)
+        if not next_frontier:
+            break
+        frontier = next_frontier
+
+    return visited
+
+
+def filter_by_role(
+    graph: dict,
+    node_ids: Iterable[str],
+    role: str,
+) -> set[str]:
+    """Keep only nodes whose type is in the role's interest set (§4 step 3).
+
+    Unknown roles (not in ROLE_TYPE_INTERESTS) return the input set
+    unchanged — cautious default, better to over-include for an
+    unfamiliar role than drop context silently.
+    """
+    record_graph_usage(graph, "filter_by_role", kind="queries")
+    interests = ROLE_TYPE_INTERESTS.get(role)
+    if interests is None:
+        return set(node_ids)
+
+    result: set[str] = set()
+    for node_id in node_ids:
+        node = graph["nodes"].get(node_id)
+        if node and node.get("type") in interests:
+            result.add(node_id)
+    return result
+
+
+def serialize_slice(
+    graph: dict,
+    node_ids: Iterable[str],
+    *,
+    token_budget: int = DEFAULT_SLICE_TOKEN_BUDGET,
+) -> str:
+    """Render selected nodes as compact text for prompt injection (§4 step 4).
+
+    Format is deliberately terse — one line per node, grouped by type.
+    Edges between selected nodes are rendered as trailing `→ <target>`
+    suffixes when they fit in the token budget.
+
+    Token budget uses the CHARS_PER_TOKEN constant (coarse estimate).
+    When the budget is exceeded, nodes are truncated tail-first with a
+    `... (N more)` sentinel.
+
+    Returns empty string if no nodes selected.
+    """
+    record_graph_usage(graph, "serialize_slice", kind="queries")
+    selected = [graph["nodes"][nid] for nid in node_ids if nid in graph["nodes"]]
+    if not selected:
+        return ""
+
+    char_budget = token_budget * CHARS_PER_TOKEN
+
+    by_type: dict[str, list[dict]] = {}
+    for node in selected:
+        by_type.setdefault(node["type"], []).append(node)
+
+    selected_ids = {n["id"] for n in selected}
+    edges_by_source: dict[str, list[str]] = {}
+    for edge in graph["edges"]:
+        src, tgt = edge["from"], edge["to"]
+        if src in selected_ids and tgt in selected_ids:
+            edges_by_source.setdefault(src, []).append(f"{edge['type']}->{tgt}")
+
+    lines: list[str] = []
+    for node_type in sorted(by_type.keys()):
+        lines.append(f"[{node_type}]")
+        for node in sorted(by_type[node_type], key=lambda n: n["id"]):
+            parts = [f"  {node['id']}: {node.get('name', '')}"]
+            status = node.get("status", "")
+            if status and status != "active":
+                parts.append(f"({status})")
+            desc = node.get("description", "")
+            if desc:
+                parts.append(f"— {desc[:100]}")
+            out_edges = edges_by_source.get(node["id"], [])
+            if out_edges:
+                parts.append(f"[{', '.join(out_edges[:3])}]")
+            lines.append(" ".join(parts))
+
+    text = "\n".join(lines)
+
+    if len(text) > char_budget:
+        truncated_lines: list[str] = []
+        running = 0
+        for line in lines:
+            if running + len(line) + 1 > char_budget:
+                remaining = len(lines) - len(truncated_lines)
+                truncated_lines.append(f"... ({remaining} more)")
+                break
+            truncated_lines.append(line)
+            running += len(line) + 1
+        text = "\n".join(truncated_lines)
+
+    return text
+
+
+def build_context_slice(
+    graph: dict,
+    task_text: str,
+    role: str,
+    *,
+    hops: int = 2,
+    token_budget: int = DEFAULT_SLICE_TOKEN_BUDGET,
+) -> str:
+    """Full §4 pipeline: anchor → expand → filter → serialize.
+
+    This is the entry point M14's `working_group._build_context_slice`
+    will call. When the graph is empty or no anchors match, returns
+    empty string — caller should fall back to flat-YAML context.
+    """
+    record_graph_usage(graph, "build_context_slice", kind="queries")
+    anchors = extract_anchors(graph, task_text)
+    if not anchors:
+        return ""
+    expanded = expand_bfs(graph, anchors, hops=hops)
+    filtered = filter_by_role(graph, expanded, role)
+    return serialize_slice(graph, filtered, token_budget=token_budget)
+
+
+# ---------------------------------------------------------------------------
+# Query patterns (PDF §8)
+# ---------------------------------------------------------------------------
+
+def decisions_for(graph: dict, node_id: str) -> list[dict]:
+    """Return all Decision nodes that `affect` or `satisfy` the given node.
+
+    Useful for "why did we choose X for this component?" queries.
+    Supersede chains followed — superseded decisions are marked in
+    their `status` field but still returned for history.
+    """
+    record_graph_usage(graph, "decisions_for", kind="queries")
+    results: list[dict] = []
+    for edge in graph["edges"]:
+        if edge["to"] != node_id:
+            continue
+        if edge["type"] not in ("affects", "satisfies", "chose"):
+            continue
+        dec = graph["nodes"].get(edge["from"])
+        if dec and dec.get("type") == "Decision":
+            results.append(dec)
+    return sorted(results, key=lambda n: n.get("created_at", ""))
+
+
+def ancestors_of(graph: dict, node_id: str, max_depth: int = 10) -> list[dict]:
+    """Trace decision ancestry backward: which past decisions influenced this one.
+
+    Follows `decision_ancestry` edges (from=child -> to=parent) and
+    `supersedes` edges forward (from=newer -> to=older).
+    Returns a list of (decision, depth, edge_type) tuples as dicts.
+    """
+    record_graph_usage(graph, "ancestors_of", kind="queries")
+    visited: set[str] = {node_id}
+    results: list[dict] = []
+    queue: list[tuple[str, int, str]] = [(node_id, 0, "self")]
+
+    while queue:
+        current_id, depth, edge_type = queue.pop(0)
+        if depth >= max_depth:
+            continue
+        for edge in graph["edges"]:
+            # decision_ancestry: from=child -> to=parent
+            if edge["from"] == current_id and edge["type"] == "decision_ancestry":
+                parent_id = edge["to"]
+                if parent_id not in visited:
+                    visited.add(parent_id)
+                    parent = graph["nodes"].get(parent_id)
+                    if parent and parent.get("type") == "Decision":
+                        results.append({
+                            "node": parent,
+                            "depth": depth + 1,
+                            "edge_type": "decision_ancestry",
+                            "edge_reason": edge.get("reason", ""),
+                        })
+                        queue.append((parent_id, depth + 1, "decision_ancestry"))
+            # supersedes: from=newer -> to=older
+            if edge["from"] == current_id and edge["type"] == "supersedes":
+                old_id = edge["to"]
+                if old_id not in visited:
+                    visited.add(old_id)
+                    old = graph["nodes"].get(old_id)
+                    if old and old.get("type") == "Decision":
+                        results.append({
+                            "node": old,
+                            "depth": depth + 1,
+                            "edge_type": "supersedes",
+                            "edge_reason": edge.get("reason", ""),
+                        })
+                        queue.append((old_id, depth + 1, "supersedes"))
+
+    return results
+
+
+def descendants_of(graph: dict, node_id: str, max_depth: int = 10) -> list[dict]:
+    """Trace decision ancestry forward: which later decisions were influenced by this one.
+
+    Follows `decision_ancestry` edges in reverse (to=parent -> from=child)
+    and `supersedes` edges forward (to=older -> from=newer).
+    """
+    record_graph_usage(graph, "descendants_of", kind="queries")
+    visited: set[str] = {node_id}
+    results: list[dict] = []
+    queue: list[tuple[str, int, str]] = [(node_id, 0, "self")]
+
+    while queue:
+        current_id, depth, edge_type = queue.pop(0)
+        if depth >= max_depth:
+            continue
+        for edge in graph["edges"]:
+            # decision_ancestry: from=child -> to=parent, so to=current means current is parent
+            if edge["to"] == current_id and edge["type"] == "decision_ancestry":
+                child_id = edge["from"]
+                if child_id not in visited:
+                    visited.add(child_id)
+                    child = graph["nodes"].get(child_id)
+                    if child and child.get("type") == "Decision":
+                        results.append({
+                            "node": child,
+                            "depth": depth + 1,
+                            "edge_type": "decision_ancestry",
+                            "edge_reason": edge.get("reason", ""),
+                        })
+                        queue.append((child_id, depth + 1, "decision_ancestry"))
+            # supersedes: from=newer -> to=older, so to=current means current is older
+            if edge["to"] == current_id and edge["type"] == "supersedes":
+                new_id = edge["from"]
+                if new_id not in visited:
+                    visited.add(new_id)
+                    new = graph["nodes"].get(new_id)
+                    if new and new.get("type") == "Decision":
+                        results.append({
+                            "node": new,
+                            "depth": depth + 1,
+                            "edge_type": "supersedes",
+                            "edge_reason": edge.get("reason", ""),
+                        })
+                        queue.append((new_id, depth + 1, "supersedes"))
+
+    return results
+
+
+def tech_context(graph: dict) -> list[dict]:
+    """Return all Technology nodes in the graph, sorted by id."""
+    record_graph_usage(graph, "tech_context", kind="queries")
+    return nodes_by_type(graph, "Technology")
+
+
+def open_risks(graph: dict) -> list[dict]:
+    """Return Risk nodes that are not mitigated.
+
+    A risk is "mitigated" if any Decision has a `mitigates` edge
+    pointing to it. Otherwise it's "open".
+    """
+    record_graph_usage(graph, "open_risks", kind="queries")
+    mitigated: set[str] = set()
+    for edge in graph["edges"]:
+        if edge["type"] == "mitigates":
+            mitigated.add(edge["to"])
+
+    return [
+        n for n in nodes_by_type(graph, "Risk")
+        if n["id"] not in mitigated and n.get("status", "active") != "resolved"
+    ]
+
+
+def impact(graph: dict, node_id: str) -> dict[str, list[str]]:
+    """Return "what depends on this node" impact analysis.
+
+    Groups incoming edges by edge type for easy scanning:
+      {
+        "uses": ["comp_api", "comp_worker"],
+        "depends_on": ["comp_admin"],
+        "blocks": ["risk_042"],
+      }
+    """
+    record_graph_usage(graph, "impact", kind="queries")
+    result: dict[str, list[str]] = {}
+    for edge in graph["edges"]:
+        if edge["to"] != node_id:
+            continue
+        result.setdefault(edge["type"], []).append(edge["from"])
+    return result
+
+
+def stale_tech(graph: dict, max_age_days: int = 7) -> list[dict]:
+    """Return Technology nodes whose `scout_checked_at` is older than threshold.
+
+    Used by scout integration (PDF §6.1 STEP 0) — fresh data prevents
+    redundant web searches. A tech node without `scout_checked_at` is
+    considered stale (never checked).
+    """
+    record_graph_usage(graph, "stale_tech", kind="queries")
+    cutoff = _dt.datetime.now(_dt.timezone.utc) - _dt.timedelta(days=max_age_days)
+    result: list[dict] = []
+    for node in nodes_by_type(graph, "Technology"):
+        checked_at_raw = node.get("scout_checked_at")
+        if not checked_at_raw:
+            result.append(node)
+            continue
+        try:
+            checked_at = _dt.datetime.strptime(
+                checked_at_raw.replace("Z", "+0000"),
+                "%Y-%m-%dT%H:%M:%S%z",
+            )
+        except (ValueError, AttributeError):
+            result.append(node)
+            continue
+        if checked_at < cutoff:
+            result.append(node)
+    return result
+
+
+def unsatisfied_reqs(graph: dict) -> list[dict]:
+    """Return Requirement nodes that have no satisfying Decision.
+
+    A requirement is "satisfied" when any Decision has a `satisfies`
+    edge pointing to it. Violated requirements (Component->Req via
+    `violates`) are also flagged as unsatisfied regardless of Decision
+    state.
+    """
+    record_graph_usage(graph, "unsatisfied_reqs", kind="queries")
+    satisfied: set[str] = set()
+    violated: set[str] = set()
+    for edge in graph["edges"]:
+        if edge["type"] == "satisfies":
+            satisfied.add(edge["to"])
+        elif edge["type"] == "violates":
+            violated.add(edge["to"])
+
+    return [
+        n for n in nodes_by_type(graph, "Requirement")
+        if n["id"] not in satisfied or n["id"] in violated
+    ]
+
+
+# ---------------------------------------------------------------------------
+# M13 P2 EP-02: Outcome Tracking & Error Memory
+# ---------------------------------------------------------------------------
+
+def record_outcome(
+    graph: dict,
+    decision_id: str,
+    status: str,
+    actual_result: str,
+    lessons_learned: str = "",
+    tags: Optional[list[str]] = None,
+    recorded_by: str = "operator",
+) -> dict:
+    """Record an Outcome node for an existing Decision.
+
+    Creates a new Outcome node with id `outcome_{decision_id}` and adds
+    an `evaluates` edge from Outcome → Decision. If an Outcome already
+    exists for this decision, it is updated in place per §5.3 conflict
+    resolution (duplicate id → update).
+
+    Args:
+        graph: the graph dict (will be mutated)
+        decision_id: id of the Decision being evaluated (must exist)
+        status: one of OUTCOME_STATUSES
+        actual_result: free-form description of what happened
+        lessons_learned: optional guidance for future similar decisions
+        tags: optional semantic tags for find_similar_outcomes matching
+        recorded_by: who recorded this (default "operator")
+
+    Returns:
+        The Outcome node dict.
+
+    Raises:
+        ValueError: if decision_id not in graph, status invalid, or
+                    target node is not a Decision.
+    """
+    record_graph_usage(graph, "record_outcome", kind="updates")
+    if status not in OUTCOME_STATUSES:
+        raise ValueError(
+            f"invalid outcome status {status!r}; "
+            f"must be one of {sorted(OUTCOME_STATUSES)}"
+        )
+    target = graph["nodes"].get(decision_id)
+    if target is None:
+        raise ValueError(f"decision {decision_id!r} not in graph")
+    if target.get("type") != "Decision":
+        raise ValueError(
+            f"node {decision_id!r} is type {target.get('type')!r}, "
+            f"expected Decision"
+        )
+
+    outcome_id = f"outcome_{decision_id}"
+    name = f"Outcome of {target.get('name', decision_id)[:60]}"
+    description = actual_result.strip()
+
+    # Idempotent add/update — re-running replaces the outcome content
+    # but preserves the stable edge.
+    already_existed = outcome_id in graph["nodes"]
+
+    add_node(
+        graph,
+        outcome_id,
+        "Outcome",
+        name=name,
+        description=description,
+        # M14: outcomes recorded by operator are ground truth ("KNOWS").
+        # When future auto-outcome extraction from git history lands,
+        # pass source_type="git_diff" or "operator" explicitly.
+        source_type="operator",
+        extra={
+            "decision_id": decision_id,
+            "outcome_status": status,
+            "actual_result": actual_result.strip(),
+            "lessons_learned": lessons_learned.strip(),
+            "tags": list(tags or []),
+            "recorded_by": recorded_by,
+        },
+    )
+
+    if not already_existed:
+        add_edge(graph, outcome_id, decision_id, "evaluates")
+
+    return graph["nodes"][outcome_id]
+
+
+def outcome_for(graph: dict, decision_id: str) -> Optional[dict]:
+    """Return the Outcome node for a given decision, or None."""
+    return graph["nodes"].get(f"outcome_{decision_id}")
+
+
+def find_similar_outcomes(
+    graph: dict,
+    task_text: str,
+    limit: int = 3,
+) -> list[dict]:
+    """Find Outcome nodes relevant to the current task (PDF EP-02 STEP 2.5).
+
+    Ranking strategy:
+      1. Extract keywords from task_text (lowercased, deduped, stopwords dropped)
+      2. For each Outcome node:
+         - Count tag overlap with task keywords
+         - Check if decision name contains any task keyword
+         - Combine score = tag_overlap * 2 + decision_match
+      3. Rank by (score DESC, recency DESC) — recent outcomes win ties
+      4. Return top `limit` nodes
+
+    Only returns outcomes with status != "confirmed" by default —
+    confirmed outcomes are "things that went well", less actionable
+    than reverted/revised/partially_applied ones.
+
+    Args:
+        graph: the graph dict
+        task_text: the current deliberation goal/task string
+        limit: maximum number of outcomes to return (default 3)
+
+    Returns:
+        List of Outcome node dicts, ranked by relevance. Empty if no
+        keywords match or no outcomes exist.
+    """
+    if not task_text.strip():
+        return []
+
+    keywords = _extract_keywords(task_text)
+    if not keywords:
+        return []
+
+    scored: list[tuple[int, str, dict]] = []
+    for node in nodes_by_type(graph, "Outcome"):
+        # Skip confirmed outcomes — they're less useful as cautionary tales
+        if node.get("outcome_status") == "confirmed":
+            continue
+
+        # Score 1: tag overlap
+        node_tags = {str(t).lower() for t in node.get("tags", [])}
+        tag_overlap = len(node_tags & keywords)
+
+        # Score 2: decision name contains any task keyword
+        decision_id = node.get("decision_id", "")
+        decision = graph["nodes"].get(decision_id, {})
+        decision_name = decision.get("name", "").lower()
+        decision_match = sum(1 for kw in keywords if kw in decision_name)
+
+        score = tag_overlap * 2 + decision_match
+        if score > 0:
+            scored.append((score, node.get("updated_at", ""), node))
+
+    # Sort by (score DESC, recency DESC via created_at string compare)
+    scored.sort(key=lambda x: (-x[0], x[1]), reverse=False)
+    # Reverse ordering quirk: negative score + ascending tuple sort
+    scored.sort(key=lambda x: (-x[0], -ord(x[1][0]) if x[1] else 0))
+
+    return [outcome for _score, _ts, outcome in scored[:limit]]
+
+
+def decisions_without_outcome(
+    graph: dict,
+    stage: str = "",
+    now: Optional[_dt.datetime] = None,
+) -> list[dict]:
+    """Return Decision nodes older than the stage threshold that lack an Outcome.
+
+    Used by EP-02 operator review workflow: "Hey, this decision from
+    14 days ago never got an Outcome. What actually happened?"
+
+    Threshold by stage (PDF EP-02):
+      - idea / mvp: 14 days
+      - growth: 30 days
+      - scale: 60 days
+      - unknown stage: 30 days (DEFAULT_STAGE_THRESHOLD_DAYS)
+
+    Args:
+        graph: the graph dict
+        stage: project stage from project-layer.yaml (optional)
+        now: timestamp to compare against (defaults to current UTC time —
+             parameterized for deterministic testing)
+
+    Returns:
+        List of Decision node dicts, sorted by creation date (oldest first).
+    """
+    threshold_days = STAGE_OUTCOME_THRESHOLDS_DAYS.get(stage, DEFAULT_STAGE_THRESHOLD_DAYS)
+    now = now or _dt.datetime.now(_dt.timezone.utc)
+    cutoff = now - _dt.timedelta(days=threshold_days)
+
+    results: list[tuple[str, dict]] = []
+    for decision in nodes_by_type(graph, "Decision"):
+        created_at_raw = decision.get("created_at", "")
+        try:
+            created_at = _dt.datetime.strptime(
+                created_at_raw.replace("Z", "+0000"),
+                "%Y-%m-%dT%H:%M:%S%z",
+            )
+        except (ValueError, AttributeError):
+            # Unparseable timestamp — skip rather than crash
+            continue
+
+        if created_at > cutoff:
+            continue
+
+        # Skip if Outcome already exists
+        if outcome_for(graph, decision["id"]) is not None:
+            continue
+
+        results.append((created_at_raw, decision))
+
+    # Sort oldest first
+    results.sort(key=lambda x: x[0])
+    return [d for _ts, d in results]
+
+
+def format_lessons_block(outcomes: list[dict], graph: dict) -> str:
+    """Render a list of Outcome nodes as a `<lessons_learned>` text block.
+
+    Matches the PDF EP-02 STEP 2.5 format for injection into the
+    context slice. Empty list returns empty string.
+
+    Example output:
+        <lessons_learned>
+        Similar past decision "dec_002: Use Kafka for ingestion" was reverted.
+        Reason: Kafka ops overhead too high for 2-person backend team.
+        Lesson: Managed queue SQS/CloudTasks better for teams < 5.
+        </lessons_learned>
+    """
+    if not outcomes:
+        return ""
+
+    lines = ["<lessons_learned>"]
+    for outcome in outcomes:
+        decision_id = outcome.get("decision_id", "")
+        decision = graph["nodes"].get(decision_id, {})
+        decision_name = decision.get("name", decision_id)
+        status = outcome.get("outcome_status", "unknown")
+
+        lines.append(
+            f'Similar past decision "{decision_id}: {decision_name}" was {status}.'
+        )
+        actual = outcome.get("actual_result", "").strip()
+        if actual:
+            lines.append(f"Reason: {actual}")
+        lesson = outcome.get("lessons_learned", "").strip()
+        if lesson:
+            lines.append(f"Lesson: {lesson}")
+        lines.append("")  # blank line between entries
+
+    # Strip trailing blank before closing tag
+    while lines and not lines[-1]:
+        lines.pop()
+    lines.append("</lessons_learned>")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# CLI shim (optional — main entry is generate_project_graph.py)
+# ---------------------------------------------------------------------------
+
+def _summary(graph: dict) -> str:
+    """Produce a one-screen summary of graph state for CLI inspection."""
+    meta = graph["meta"]
+    by_type: dict[str, int] = {}
+    for node in graph["nodes"].values():
+        by_type[node["type"]] = by_type.get(node["type"], 0) + 1
+    by_edge_type: dict[str, int] = {}
+    for edge in graph["edges"]:
+        by_edge_type[edge["type"]] = by_edge_type.get(edge["type"], 0) + 1
+
+    lines = [
+        f"Project Context Graph (schema v{meta.get('schema_version')})",
+        f"  created_at: {meta.get('created_at')}",
+        f"  updated_at: {meta.get('updated_at')}",
+        f"  nodes: {meta.get('node_count', 0)}",
+        f"  edges: {meta.get('edge_count', 0)}",
+        "",
+        "Node types:",
+    ]
+    for node_type in sorted(by_type.keys()):
+        lines.append(f"  {node_type}: {by_type[node_type]}")
+    lines.append("")
+    lines.append("Edge types:")
+    for edge_type in sorted(by_edge_type.keys()):
+        lines.append(f"  {edge_type}: {by_edge_type[edge_type]}")
+    return "\n".join(lines)
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    """Minimal CLI: `python3 scripts/graph.py <path>` prints summary."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Inspect a 0dai project_graph.json file.",
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default="ai/manifest/project_graph.json",
+        help="Path to project_graph.json (default: ai/manifest/project_graph.json)",
+    )
+    parser.add_argument(
+        "--validate",
+        action="store_true",
+        help="Run full validation and report any errors",
+    )
+    args = parser.parse_args(argv)
+
+    path = pathlib.Path(args.path)
+    try:
+        graph = load_graph(path)
+    except GraphValidationError as exc:
+        print(f"error: {exc}")
+        return 2
+
+    print(_summary(graph))
+
+    if args.validate:
+        errors = validate_graph(graph)
+        if errors:
+            print("\nvalidation errors:")
+            for err in errors:
+                print(f"  - {err}")
+            return 1
+        print("\nvalidation: OK")
+
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# M19 P0: Graph dogfood — Artifact + Event helpers
+# ---------------------------------------------------------------------------
+
+def record_artifact(
+    graph: dict,
+    version: str,
+    *,
+    changelog: str = "",
+    commit_sha: str = "",
+    released_at: str = "",
+) -> dict:
+    """Record a release Artifact node in the graph.
+
+    Creates an Artifact node (artifact_vX_Y_Z) and links it to all
+    existing Decision nodes via 'contains' edges. Idempotent — calling
+    twice with the same version updates the existing node.
+
+    Returns the node dict after insertion.
+    """
+    record_graph_usage(graph, "record_artifact", kind="updates")
+    node_id = f"artifact_v{version.replace('.', '_')}"
+    description = f"Release v{version}"
+    if changelog:
+        description += f"\n\n{changelog[:500]}"
+
+    extra: dict[str, Any] = {
+        "version": version,
+        "commit_sha": commit_sha,
+    }
+    if released_at:
+        extra["released_at"] = released_at
+
+    node = add_node(
+        graph, node_id, "Artifact", f"v{version}",
+        status="active",
+        description=description,
+        source_type="KNOWS",
+        extra=extra,
+    )
+
+    # Link to all existing Decision nodes
+    for dec_node in nodes_by_type(graph, "Decision"):
+        add_edge(graph, node_id, dec_node["id"], "contains", weight=0.3)
+
+    return node
+
+
+def record_event(
+    graph: dict,
+    event_type: str,
+    name: str,
+    *,
+    description: str = "",
+    extra: Optional[dict[str, Any]] = None,
+) -> dict:
+    """Record a meta Event node in the graph.
+
+    Events capture session starts, meta-sessions, migrations, or any
+    significant project lifecycle moment that isn't a Decision or
+    Deliberation. Useful for timeline queries later.
+
+    Returns the node dict after insertion.
+    """
+    record_graph_usage(graph, "record_event", kind="updates")
+    slug = _slug(name)[:40]
+    ts = _now_iso().replace(":", "-").replace("T", "_")[:19]
+    node_id = f"event_{event_type}_{slug}_{ts}"
+
+    node = add_node(
+        graph, node_id, "Event", name,
+        status="active",
+        description=description,
+        source_type="KNOWS",
+        extra={"event_type": event_type, **(extra or {})},
+    )
+    return node
+
+
+def record_deliberation_outcome(
+    graph: dict,
+    deliberation_id: str,
+    verdict: str,
+    goal: str,
+    *,
+    synthesis: str = "",
+    resources: Optional[dict] = None,
+) -> dict:
+    """Record a Deliberation node + Outcome from a working-group deliberation.
+
+    Creates a Deliberation node (delib_{id}) and an Outcome node that
+    evaluates the deliberation's verdict. Links them via 'evaluates'.
+
+    Returns the Outcome node dict.
+    """
+    record_graph_usage(graph, "record_deliberation_outcome", kind="updates")
+    # Deliberation node
+    delib_id = f"delib_{deliberation_id}"
+    add_node(
+        graph, delib_id, "Deliberation", goal[:100],
+        status="active" if verdict not in ("REJECTED",) else "closed",
+        description=synthesis[:300] if synthesis else goal,
+        source_type="KNOWS",
+        extra={
+            "deliberation_id": deliberation_id,
+            "verdict": verdict,
+            "resources": resources or {},
+        },
+    )
+
+    # Outcome node — maps verdict to outcome status
+    outcome_status_map = {
+        "APPROVED": "confirmed",
+        "CONDITIONAL": "partially_applied",
+        "NEEDS_WORK": "revised",
+        "REJECTED": "reverted",
+    }
+    outcome_status = outcome_status_map.get(verdict, "revised")
+
+    outcome_id = f"outcome_{deliberation_id}"
+    outcome = add_node(
+        graph, outcome_id, "Outcome", f"Outcome: {goal[:80]}",
+        status=outcome_status,
+        description=f"Deliberation verdict: {verdict}\n\n{synthesis[:200]}",
+        source_type="KNOWS",
+        extra={
+            "deliberation_id": deliberation_id,
+            "verdict": verdict,
+            "auto_generated": True,
+        },
+    )
+
+    # Link: Outcome evaluates Deliberation
+    add_edge(graph, outcome_id, delib_id, "evaluates")
+
+    return outcome
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    raise SystemExit(main())
+
+
+# ---------------------------------------------------------------------------
+# #479: Architecture Constraints — first-class constraint nodes
+# ---------------------------------------------------------------------------
+
+# Valid enforcement levels for Constraint nodes.
+CONSTRAINT_ENFORCEMENTS = frozenset({
+    "hard",    # must never be violated — build/lint blocks
+    "soft",    # should be followed — warnings only
+    "guideline",  # best-effort suggestion
+})
+
+# Decision-key → constraint auto-derivation rules.
+# When a Decision node's name/description contains the key, the listed
+# constraint templates are auto-generated. Keys are matched
+# case-insensitively as substrings against the decision name.
+CONSTRAINT_DERIVATION_RULES: dict[str, list[dict[str, Any]]] = {
+    "docker": [
+        {
+            "constraint_id": "deployment_mode_containers",
+            "name": "Container-based deployment",
+            "diff_rules": [
+                "no-localhost-on-service-bound",
+            ],
+            "implies": [
+                "All services accessed by container name, not localhost",
+                "Environment variables via compose args, not hardcoded",
+            ],
+            "forbids": [
+                "localhost in connection strings",
+                "hardcoded file paths in app code",
+                "host-style port mapping in app logic",
+            ],
+        },
+    ],
+    "serverless": [
+        {
+            "constraint_id": "deployment_mode_serverless",
+            "name": "Serverless deployment",
+            "implies": [
+                "Stateless function handlers only",
+                "Cold-start optimization required",
+            ],
+            "forbids": [
+                "Local filesystem for persistent state",
+                "Long-running connections",
+                "In-process caching across invocations",
+            ],
+        },
+    ],
+    "monorepo": [
+        {
+            "constraint_id": "repo_structure_monorepo",
+            "name": "Monorepo structure",
+            "implies": [
+                "Shared dependency versions across packages",
+                "Cross-package imports via workspace protocol",
+            ],
+            "forbids": [
+                "Duplicated dependencies across packages",
+                "Relative imports crossing package boundaries",
+            ],
+        },
+    ],
+    "kubernetes": [
+        {
+            "constraint_id": "deployment_mode_k8s",
+            "name": "Kubernetes deployment",
+            "implies": [
+                "Health check endpoints required for all services",
+                "Configuration via ConfigMap and Secret resources",
+            ],
+            "forbids": [
+                "Hardcoded service addresses",
+                "Writing to container filesystem",
+            ],
+        },
+    ],
+    "postgresql": [
+        {
+            "constraint_id": "database_relational_postgres",
+            "name": "PostgreSQL as primary database",
+            "diff_rules": [
+                "connection-string-consistency",
+            ],
+            "implies": [
+                "SQL migrations managed by tooling (Alembic, Prisma, etc.)",
+                "Connection pooling required for production",
+            ],
+            "forbids": [
+                "Raw DDL in application code",
+                "Unparameterized SQL queries",
+            ],
+        },
+    ],
+    "redis": [
+        {
+            "constraint_id": "cache_redis",
+            "name": "Redis for caching/queue",
+            "implies": [
+                "Cache invalidation strategy required",
+                "TTL on all cache keys",
+            ],
+            "forbids": [
+                "Using Redis as primary data store",
+                "Unbounded key growth without eviction policy",
+            ],
+        },
+    ],
+}
+
+
+def add_constraint(
+    graph: dict,
+    constraint_id: str,
+    name: str,
+    *,
+    enforcement: str = "hard",
+    implies: Optional[list[str]] = None,
+    forbids: Optional[list[str]] = None,
+    declared_by: Optional[str] = None,
+    constrains: Optional[list[str]] = None,
+    description: str = "",
+    source_type: str = DEFAULT_SOURCE,
+) -> dict:
+    """Add an Architecture Constraint node to the graph.
+
+    Constraints encode hard rules that follow from architectural decisions.
+    Unlike context (soft suggestion), constraints are injected into agent
+    prompts as checklists that must be satisfied.
+
+    Args:
+        graph: the graph dict (will be mutated)
+        constraint_id: short slug for the constraint (e.g. "deployment_mode_containers")
+        name: human-readable name
+        enforcement: "hard" (blocks), "soft" (warns), or "guideline" (suggests)
+        implies: list of rules this constraint requires
+        forbids: list of anti-patterns this constraint prohibits
+        declared_by: node id of the Decision that produced this constraint
+        constrains: list of Component/Technology node ids this constraint scopes to
+        description: free-form description
+        source_type: provenance marker
+
+    Returns:
+        The Constraint node dict.
+
+    Raises:
+        ValueError: if enforcement is not in CONSTRAINT_ENFORCEMENTS, or
+                    declared_by/constrains reference non-existent nodes.
+    """
+    record_graph_usage(graph, "add_constraint", kind="updates")
+    if enforcement not in CONSTRAINT_ENFORCEMENTS:
+        raise ValueError(
+            f"invalid enforcement {enforcement!r}; "
+            f"must be one of {sorted(CONSTRAINT_ENFORCEMENTS)}"
+        )
+
+    node_id = make_node_id("Constraint", constraint_id)
+
+    node = add_node(
+        graph, node_id, "Constraint", name,
+        status="active",
+        description=description,
+        source_type=source_type,
+        extra={
+            "constraint_id": constraint_id,
+            "enforcement": enforcement,
+            "implies": list(implies or []),
+            "forbids": list(forbids or []),
+        },
+    )
+
+    # Edge: Constraint -> Decision (declared_by)
+    if declared_by:
+        if declared_by not in graph["nodes"]:
+            raise ValueError(f"declared_by node {declared_by!r} not in graph")
+        target = graph["nodes"][declared_by]
+        if target.get("type") != "Decision":
+            raise ValueError(
+                f"declared_by node {declared_by!r} is type "
+                f"{target.get('type')!r}, expected Decision"
+            )
+        if not find_edge(graph, node_id, declared_by, "declared_by"):
+            add_edge(graph, node_id, declared_by, "declared_by")
+
+    # Edges: Constraint -> Component|Technology (constrains)
+    for target_id in (constrains or []):
+        if target_id not in graph["nodes"]:
+            raise ValueError(f"constrains target {target_id!r} not in graph")
+        if not find_edge(graph, node_id, target_id, "constrains"):
+            add_edge(graph, node_id, target_id, "constrains")
+
+    return node
+
+
+def auto_derive_constraints(graph: dict) -> list[dict]:
+    """Auto-derive Constraint nodes from existing Decision nodes.
+
+    Scans Decision node names (case-insensitive) for known keywords
+    (docker, serverless, monorepo, etc.) and creates Constraint nodes
+    using the templates in CONSTRAINT_DERIVATION_RULES.
+
+    Idempotent — re-running does not create duplicate constraints. If a
+    constraint node already exists, it is updated with the current
+    implies/forbids lists.
+
+    Returns:
+        List of newly created or updated Constraint node dicts.
+    """
+    record_graph_usage(graph, "auto_derive_constraints", kind="updates")
+    results: list[dict] = []
+
+    for decision in nodes_by_type(graph, "Decision"):
+        dec_name = decision.get("name", "").lower()
+        dec_desc = decision.get("description", "").lower()
+        dec_text = f"{dec_name} {dec_desc}"
+
+        for keyword, templates in CONSTRAINT_DERIVATION_RULES.items():
+            if keyword.lower() not in dec_text:
+                continue
+
+            for tmpl in templates:
+                constraint = add_constraint(
+                    graph,
+                    tmpl["constraint_id"],
+                    tmpl["name"],
+                    enforcement="hard",
+                    implies=tmpl.get("implies"),
+                    forbids=tmpl.get("forbids"),
+                    declared_by=decision["id"],
+                    source_type="operator",
+                )
+                if tmpl.get("diff_rules"):
+                    constraint["diff_rules"] = list(tmpl["diff_rules"])
+                results.append(constraint)
+
+    return results
+
+
+def load_constraints_yaml(
+    graph: dict,
+    yaml_path: pathlib.Path,
+) -> list[dict]:
+    """Load manual constraints from an ai/constraints.yaml file.
+
+    The YAML file should contain a top-level `constraints` key with a
+    list of constraint entries. Each entry has:
+      - constraint_id (required)
+      - name (required)
+      - enforcement (optional, default "hard")
+      - implies (optional list of strings)
+      - forbids (optional list of strings)
+      - declared_by (optional Decision node id)
+      - constrains (optional list of Component/Technology node ids)
+      - description (optional)
+
+    No PyYAML dependency — uses a minimal line-based parser that handles
+    the common subset of YAML we need (string scalars, lists of strings).
+
+    Returns:
+        List of created/updated Constraint node dicts.
+
+    Raises:
+        FileNotFoundError: if yaml_path does not exist
+    """
+    record_graph_usage(graph, "load_constraints_yaml", kind="updates")
+    if not yaml_path.exists():
+        raise FileNotFoundError(f"constraints file not found: {yaml_path}")
+
+    raw = yaml_path.read_text(encoding="utf-8")
+    entries = _parse_constraints_yaml(raw)
+
+    results: list[dict] = []
+    for entry in entries:
+        constraint = add_constraint(
+            graph,
+            entry["constraint_id"],
+            entry["name"],
+            enforcement=entry.get("enforcement", "hard"),
+            implies=entry.get("implies"),
+            forbids=entry.get("forbids"),
+            declared_by=entry.get("declared_by"),
+            constrains=entry.get("constrains"),
+            description=entry.get("description", ""),
+            source_type="operator",
+        )
+        results.append(constraint)
+
+    return results
+
+
+def get_architecture_constraints(graph: dict) -> list[dict]:
+    """Return all Constraint nodes in the graph, sorted by enforcement level.
+
+    Hard constraints first, then soft, then guidelines. Within each
+    enforcement level, sorted by constraint_id for stability.
+    """
+    record_graph_usage(graph, "get_architecture_constraints", kind="queries")
+    constraints = nodes_by_type(graph, "Constraint")
+
+    enforcement_order = {"hard": 0, "soft": 1, "guideline": 2}
+    return sorted(
+        constraints,
+        key=lambda c: (
+            enforcement_order.get(c.get("enforcement", "hard"), 99),
+            c.get("constraint_id", ""),
+        ),
+    )
+
+
+def _constraint_scope_patterns(graph: dict, constraint_id: str) -> list[str]:
+    patterns: list[str] = []
+    for edge in outgoing_edges(graph, constraint_id):
+        if edge.get("type") != "constrains":
+            continue
+        raw = edge.get("path_patterns")
+        if isinstance(raw, str):
+            patterns.append(raw)
+        elif isinstance(raw, list):
+            patterns.extend(str(item) for item in raw if item)
+    return patterns
+
+
+def get_active_constraints(
+    target: pathlib.Path,
+    path_patterns: Optional[list[str]] = None,
+) -> list[dict]:
+    """Return active constraints for a repo target filtered by path patterns.
+
+    Constraints without any `constrains` edges are treated as globally active.
+    Constraints with `constrains` edges become active when one of the edge
+    `path_patterns` values overlaps the requested path patterns.
+    """
+    graph_path = pathlib.Path(target) / "ai" / "manifest" / "project_graph.json"
+    graph = load_graph(graph_path)
+    auto_derive_constraints(graph)
+    record_graph_usage(graph, "get_active_constraints", kind="queries")
+
+    requested = list(path_patterns or ["*"])
+    constraints = get_architecture_constraints(graph)
+    if not constraints:
+        return []
+
+    active: list[dict] = []
+    for constraint in constraints:
+        scope_patterns = _constraint_scope_patterns(graph, str(constraint.get("id") or ""))
+        if _path_patterns_overlap(requested, scope_patterns):
+            active.append(constraint)
+    return active
+
+
+def format_constraints_checklist(
+    graph: dict,
+    *,
+    constraints: Optional[list[dict]] = None,
+) -> str:
+    """Render all architecture constraints as a checklist for prompt injection.
+
+    Constraints are rendered as a checklist (not context) so agents see
+    them as hard rules that must be satisfied, not soft suggestions.
+
+    Format:
+        ARCHITECTURE CONSTRAINTS (must be satisfied):
+        ☐ No localhost in connection strings (deployment_mode=containers) [hard]
+        ☐ All env vars follow FOO_BAR pattern (env_naming_convention) [hard]
+        ☐ Prefer managed queues for small teams (queue_guideline) [guideline]
+        [before returning code]: self-check against this list
+
+    Returns empty string if no constraints exist.
+    """
+    record_graph_usage(graph, "format_constraints_checklist", kind="queries")
+    constraints = list(constraints) if constraints is not None else get_architecture_constraints(graph)
+    constraints = [c for c in constraints if c.get("enforcement", "hard") in {"hard", "soft"}]
+    if not constraints:
+        return ""
+
+    lines: list[str] = ["ARCHITECTURE CONSTRAINTS (must be satisfied):"]
+
+    for c in constraints:
+        enforcement = c.get("enforcement", "hard")
+        cid = c.get("constraint_id", c["id"])
+        bracket = f"[{enforcement}]" if enforcement != "hard" else ""
+
+        for rule in c.get("forbids", []):
+            parts = f"No {rule}"
+            lines.append(f"☐ {parts} ({cid}) {bracket}".rstrip())
+
+        for rule in c.get("implies", []):
+            lines.append(f"☐ {rule} ({cid}) {bracket}".rstrip())
+
+    lines.append("[before returning code]: self-check against this list")
+    return "\n".join(lines)
+
+
+def check_constraint_violations(
+    graph: dict,
+    code_artifacts: dict[str, str],
+) -> list[dict[str, Any]]:
+    """Check code artifacts against constraint rules and return violations.
+
+    Performs pattern-based matching of constraint `forbids` rules against
+    the provided code artifacts. Each forbids entry is matched as a
+    case-insensitive substring search across all artifact values.
+
+    Args:
+        graph: the graph dict
+        code_artifacts: dict of {filename: content} to check
+
+    Returns:
+        List of violation dicts, each with:
+          - constraint_id: the constraint that was violated
+          - rule: the specific forbids rule that matched
+          - file: the file containing the violation
+          - enforcement: the constraint's enforcement level
+
+    Example:
+        violations = check_constraint_violations(g, {
+            "db.py": "DB_HOST = 'localhost:5432'",
+            "app.py": "redis://my-redis:6379",
+        })
+        # Returns violation for "localhost in connection strings" in db.py
+    """
+    record_graph_usage(graph, "check_constraint_violations", kind="queries")
+    violations: list[dict[str, Any]] = []
+
+    for constraint in get_architecture_constraints(graph):
+        cid = constraint.get("constraint_id", constraint["id"])
+        enforcement = constraint.get("enforcement", "hard")
+
+        for rule in constraint.get("forbids", []):
+            # Extract key terms from the rule for pattern matching.
+            # e.g. "localhost in connection strings" → "localhost"
+            # e.g. "hardcoded file paths" → "hardcoded"
+            pattern = _extract_violation_pattern(rule)
+            if not pattern:
+                continue
+
+            for filename, content in code_artifacts.items():
+                content_lower = content.lower()
+                if pattern.lower() in content_lower:
+                    violations.append({
+                        "constraint_id": cid,
+                        "rule": rule,
+                        "file": filename,
+                        "enforcement": enforcement,
+                    })
+
+    return violations