atomadic-forge 0.3.2__py3-none-any.whl

atomadic_forge/a0_qk_constants/roi_constants.py

@@ -0,0 +1,96 @@
+"""Tier a0 — CISQ cost-model constants for ROI calculation.
+
+Golden Path Lane F W3.
+
+Data sources:
+  * CISQ "Cost of Poor Software Quality in the US" (2022 edition)
+    — $2.41 trillion total cost of poor software quality
+    — $1.52 trillion in accumulated technical debt
+    — Average cost per defect: $1,480 (detection) to $14,102 (production)
+  * IBM Systems Sciences Institute: defect cost multiplier 100× from
+    design to production
+  * NIST: "The Economic Impacts of Inadequate Infrastructure for
+    Software Testing" (2002) — $59.5B/yr avoidable with better tooling
+  * McKinsey Digital: 20-40% of technology spend on managing technical debt
+
+These constants are intentionally conservative (use lower-bound estimates)
+so Forge ROI claims remain defensible in enterprise sales contexts.
+"""
+from __future__ import annotations
+
+# ---------------------------------------------------------------------------
+# CISQ 2022 reference figures
+# ---------------------------------------------------------------------------
+
+CISQ_TOTAL_COST_USD: float = 2_410_000_000_000.0
+"""$2.41 trillion — total annual cost of poor software quality in the US (2022)."""
+
+CISQ_TECH_DEBT_USD: float = 1_520_000_000_000.0
+"""$1.52 trillion — accumulated technical debt burden (CISQ 2022)."""
+
+CISQ_REFERENCE_YEAR: str = "2022"
+
+# ---------------------------------------------------------------------------
+# Per-defect cost model (conservative / IBM lower-bound)
+# ---------------------------------------------------------------------------
+
+COST_PER_STRUCTURAL_DEFECT_USD: float = 1_480.0
+"""Cost to detect and fix one structural defect at the code-review stage ($1,480).
+
+Source: CISQ 2022 lower-bound detection cost. Use this for wire violations
+found by Forge (caught at the architecture layer, not production).
+"""
+
+COST_PER_DEFECT_PRODUCTION_USD: float = 14_102.0
+"""Cost of a defect that reaches production ($14,102).
+
+Use this as the *avoided* cost when Forge catches a violation pre-production.
+"""
+
+COST_PER_CERTIFY_AXIS_FAIL_USD: float = 2_200.0
+"""Cost estimate per certify-axis failure (documentation, test coverage, etc.).
+
+Conservative mid-point between review cost and rework cost.
+"""
+
+# ---------------------------------------------------------------------------
+# Hourly / per-symbol baselines
+# ---------------------------------------------------------------------------
+
+DEFAULT_TEAM_HOURLY_RATE_USD: float = 150.0
+"""Default fully-loaded engineering hourly rate used when no override provided."""
+
+HOURS_PER_STRUCTURAL_DEFECT_FIX: float = 4.0
+"""Average hours to fix one structural defect (architecture-layer violation)."""
+
+HOURS_PER_CERTIFY_AXIS_FIX: float = 8.0
+"""Average hours to address one failing certify axis (e.g. add test suite)."""
+
+ANNUAL_CARRY_COST_PER_KLOC_USD: float = 14_500.0
+"""Annual maintenance burden per KLOC of technical debt (McKinsey / CISQ composite)."""
+
+SYMBOLS_PER_KLOC: float = 50.0
+"""Empirical Python: ~50 public symbols per 1,000 lines for well-factored code."""
+
+# ---------------------------------------------------------------------------
+# Forge scoring thresholds for ROI bands
+# ---------------------------------------------------------------------------
+
+SCORE_THRESHOLD_PASS: float = 100.0
+SCORE_THRESHOLD_GOOD: float = 80.0
+SCORE_THRESHOLD_FAIR: float = 60.0
+SCORE_THRESHOLD_POOR: float = 40.0
+
+# ---------------------------------------------------------------------------
+# Report template strings
+# ---------------------------------------------------------------------------
+
+CISQ_CITATION: str = (
+    "CISQ, \"The Cost of Poor Software Quality in the U.S.: A 2022 Report,\" "
+    "Consortium for Information & Software Quality, 2022."
+)
+
+NIST_CITATION: str = (
+    "NIST Planning Report 02-3, \"The Economic Impacts of Inadequate "
+    "Infrastructure for Software Testing,\" May 2002."
+)

atomadic_forge/a0_qk_constants/semantic_types.py

@@ -0,0 +1,61 @@
+"""Tier a0 — types for semantic conflict resolution.
+
+When Forge absorbs from multiple repos and two symbols collide on name,
+we extract an *intent signature* from each and compute a similarity score
+to decide whether they're the same concept (merge), distinct flavours of
+the same concept (rename with semantic suffix), or genuinely different
+concepts (keep both, namespace by source module).
+
+This is the structured wire format for that pipeline.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+MergeDecision = Literal["merge", "rename_semantic", "rename_module"]
+
+
+class IntentSignature(TypedDict):
+    """Cheap, deterministic proxies for a class's intent.
+
+    None of these are "real" semantics — they're surface signals correlated
+    with intent.  The decisive design choice: combine many weak signals,
+    weighted, rather than rely on a single strong one.
+    """
+
+    name: str
+    fields: list[str]              # ``self.<x> = …`` left-hand sides
+    method_names: list[str]        # public methods only
+    field_types: dict[str, str]    # field → annotation text (when present)
+    doc_tokens: list[str]          # significant tokens from docstring
+    verb_signature: list[str]      # method-name verb prefixes (get/set/save/post/…)
+    sibling_imports: list[str]     # other names imported in the same file
+    base_classes: list[str]        # superclasses
+    file_path: str
+    source_root: str               # which repo it came from
+
+
+class SimilarityScore(TypedDict):
+    """Weighted-Jaccard breakdown for an intent-signature comparison."""
+
+    overall: float                 # 0.0 … 1.0
+    fields: float
+    method_names: float
+    field_types: float
+    doc_tokens: float
+    verb_signature: float
+    sibling_imports: float
+    discriminating_tokens: list[str]  # doc tokens unique to one side
+
+
+class ConflictResolution(TypedDict):
+    """The outcome of resolving one (A, B) conflict."""
+
+    name: str
+    decision: MergeDecision
+    score: float
+    rationale: list[str]
+    merged_signature: IntentSignature | None  # filled when decision == "merge"
+    proposed_names: list[str]                  # 1 for merge, 2 for rename
+    review_marker: str                         # "# REVIEW: …" line for the output

atomadic_forge/a0_qk_constants/sidecar_schema.py

@@ -0,0 +1,81 @@
+"""Tier a0 — .forge sidecar v1.0 wire-format schema.
+
+Golden Path Lane D W8 deliverable. The sidecar is a YAML file that
+sits beside any source file (e.g. ``src/pkg/auth.py.forge``) and
+declares the per-symbol contract:
+
+  effect:        what side effects each function performs
+                  (NetIO | KeyedCache | Logging | Pure | IO)
+  compose_with:  named symbols this one lawfully composes with
+                  (Bao-Rompf categorical effect functor — Lane D W20)
+  proves:        Lean4 proof obligation labels this symbol satisfies
+                  (Lane D W20 dispatches against aethel-nexus-proofs)
+
+a0 invariant: pure data shape, imports limited to __future__ + typing.
+The reader (a1.sidecar_parser) parses YAML into these dicts; the
+validator (Lane D W11) cross-checks against the source file's AST.
+"""
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+SCHEMA_VERSION_SIDECAR_V1 = "atomadic-forge.sidecar/v1"
+
+
+# v1 effect taxonomy — Bao-Rompf 2025 categorical effect lattice.
+EffectKind = Literal[
+    "Pure",         # no side effects
+    "IO",           # arbitrary I/O (filesystem, stdin/stdout)
+    "NetIO",        # network calls
+    "KeyedCache",   # writes to a content-addressed cache
+    "Logging",      # observability emission only
+    "Random",       # non-deterministic input (rng / time / uuid)
+    "Mutation",     # mutates passed-in arguments
+]
+
+VALID_EFFECTS: tuple[str, ...] = (
+    "Pure", "IO", "NetIO", "KeyedCache", "Logging", "Random", "Mutation",
+)
+
+
+class SidecarSymbol(TypedDict, total=False):
+    """One symbol's contract within a sidecar file.
+
+    Required:
+      name              — must match a top-level symbol in the source
+      effect            — one of VALID_EFFECTS
+
+    Optional:
+      compose_with      — ['module.symbol', ...] this symbol composes with
+      proves            — ['lemma_name', ...] obligations this discharges
+      tier              — caller may pin the tier (otherwise inferred)
+      notes             — free-form
+    """
+    name: str
+    effect: EffectKind
+    compose_with: list[str]
+    proves: list[str]
+    tier: str
+    notes: list[str]
+
+
+class SidecarFile(TypedDict, total=False):
+    """The full sidecar document.
+
+    Required:
+      schema_version    — atomadic-forge.sidecar/v1
+      target            — path of the source file this sidecar covers
+      symbols           — list of SidecarSymbol; one per public symbol
+    """
+    schema_version: str
+    target: str
+    symbols: list[SidecarSymbol]
+    # Forward-compat: future minors may add fields. Consumers MUST
+    # tolerate unknown keys.
+    extra: dict[str, object]
+
+
+REQUIRED_SIDECAR_FIELDS: tuple[str, ...] = (
+    "schema_version", "target", "symbols",
+)
+REQUIRED_SYMBOL_FIELDS: tuple[str, ...] = ("name", "effect")

atomadic_forge/a0_qk_constants/synergy_types.py

@@ -0,0 +1,62 @@
+"""Tier a0 — types for the Synergy Scan.
+
+Synergy Scan operates at the *feature / CLI verb* level (one level above
+Emergent Scan, which operates on symbols).  It finds pairs of features
+where one produces an artifact the other could consume — but no code path
+wires them together yet.  Optionally it generates an adapter that does.
+
+Wire format:
+
+* :class:`FeatureSurfaceCard` — one feature/CLI verb's I/O surface.
+* :class:`SynergyCandidateCard` — one (producer, consumer) pair with score.
+* :class:`SynergyScanReport` — top-level scan output.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+SynergyKind = Literal[
+    "json_artifact",        # producer emits --json-out, consumer takes file arg
+    "in_memory_pipe",       # producer's return type matches consumer's first arg
+    "shared_schema",        # both reference the same JSON schema name
+    "shared_vocabulary",    # high lexical overlap in help/docstrings
+    "phase_omission",       # natural phase chain skips a step
+]
+
+
+class FeatureSurfaceCard(TypedDict):
+    """One feature/CLI verb's input + output surface."""
+
+    name: str                   # CLI verb (e.g. "scout", "assimilate")
+    module: str                 # importable module path
+    help_text: str
+    inputs: list[str]           # canonical arg names (e.g. ["repo", "policy"])
+    input_files: list[str]      # filename patterns it accepts
+    outputs: list[str]          # canonical product names (e.g. ["scout-report"])
+    output_files: list[str]     # filename patterns it emits (e.g. ["*.json"])
+    schemas: list[str]          # schema names mentioned in help/docstring
+    vocabulary: list[str]       # unique tokens harvested from help+args
+    phase_hint: str             # heuristic phase tag (recon/ingest/.../emit)
+
+
+class SynergyCandidateCard(TypedDict):
+    """One detected synergy between two features."""
+
+    candidate_id: str
+    producer: str               # feature name
+    consumer: str               # feature name
+    kind: SynergyKind
+    why: list[str]              # human-readable signals supporting this synergy
+    score: float                # 0..100
+    score_breakdown: dict[str, float]
+    proposed_adapter_name: str  # kebab-case CLI verb for the auto-wired pair
+    proposed_summary: str
+
+
+class SynergyScanReport(TypedDict):
+    schema_version: str         # "atomadic-forge.synergy.scan/v1"
+    generated_at_utc: str
+    feature_count: int
+    candidate_count: int
+    candidates: list[SynergyCandidateCard]

atomadic_forge/a0_qk_constants/tier_names.py

@@ -0,0 +1,47 @@
+"""Tier a0 — canonical tier names and effect lattice."""
+
+from __future__ import annotations
+
+from typing import Final
+
+TIER_NAMES: Final[tuple[str, ...]] = (
+    "a0_qk_constants",
+    "a1_at_functions",
+    "a2_mo_composites",
+    "a3_og_features",
+    "a4_sy_orchestration",
+)
+
+TIER_PREFIX: Final[dict[str, str]] = {
+    "a0_qk_constants": "a0",
+    "a1_at_functions": "a1",
+    "a2_mo_composites": "a2",
+    "a3_og_features": "a3",
+    "a4_sy_orchestration": "a4",
+}
+
+# Effect lattice — what each tier is *allowed* to do.
+EFFECT_LATTICE: Final[dict[str, frozenset[str]]] = {
+    "a0_qk_constants": frozenset(),
+    "a1_at_functions": frozenset({"pure"}),
+    "a2_mo_composites": frozenset({"pure", "state"}),
+    "a3_og_features": frozenset({"pure", "state", "orchestrate"}),
+    "a4_sy_orchestration": frozenset({"pure", "state", "orchestrate", "io"}),
+}
+
+
+def tier_index(tier: str) -> int:
+    """Return 0..4 for the tier name; raise ValueError if unknown."""
+    try:
+        return TIER_NAMES.index(tier)
+    except ValueError as exc:
+        raise ValueError(f"unknown tier: {tier!r}") from exc
+
+
+def can_import(from_tier: str, to_tier: str) -> bool:
+    """Return True if ``from_tier`` is allowed to import from ``to_tier``.
+
+    Tiers compose **upward only**: a higher tier may import from any lower
+    tier, never the reverse.
+    """
+    return tier_index(from_tier) >= tier_index(to_tier)

atomadic_forge/a1_at_functions/__init__.py

@@ -0,0 +1 @@
+"""Tier a1 — pure stateless helpers. No side effects, no I/O, no state."""

atomadic_forge/a1_at_functions/agent_context_pack.py

@@ -0,0 +1,193 @@
+"""Tier a1 — pure agent context pack.
+
+Codex's 'Copilot's Copilot' primitive #1:
+
+  > Add one MCP tool that every agent calls first: forge_context_pack.
+  > Returns: repo purpose, architecture law, tier map, current
+  > blockers, best next action, test commands, release gate, risky
+  > files, recent lineage. Agents waste a lot of time rediscovering
+  > this.
+
+Pure: takes already-computed reports + a project root, returns a
+single bundle. The orchestration that runs the scans lives in a3.
+"""
+from __future__ import annotations
+
+import re
+from collections import Counter
+from pathlib import Path
+from typing import TypedDict
+
+from .agent_summary import summarize_blockers
+from .lineage_reader import read_lineage
+
+SCHEMA_VERSION_CONTEXT_PACK_V1 = "atomadic-forge.context_pack/v1"
+
+
+# The architecture law — pinned text, the same on every pack.
+_TIER_LAW = (
+    "Tier composition is upward-only. Files in a0_qk_constants/ "
+    "import nothing. a1_at_functions/ may import a0. a2_mo_composites/ "
+    "may import a0 + a1. a3_og_features/ may import a0..a2. "
+    "a4_sy_orchestration/ may import a0..a3. Never import upward; "
+    "never import sideways. Wire violations carry F-codes "
+    "F0040–F0049."
+)
+
+
+class ContextPack(TypedDict, total=False):
+    schema_version: str
+    project_root: str
+    repo_purpose: str
+    architecture_law: str
+    tier_map: dict[str, int]
+    primary_language: str
+    blockers_summary: dict
+    best_next_action: dict | None
+    test_commands: list[str]
+    release_gate: list[str]
+    risky_files: list[dict]
+    recent_lineage: list[dict]
+    pinned_resources: list[str]
+
+
+def _read_repo_purpose(project_root: Path) -> str:
+    """Best-effort: pull the first paragraph from the README, or the
+    pyproject description. Falls back to the directory name."""
+    for name in ("README.md", "README.rst", "README"):
+        readme = project_root / name
+        if not readme.exists():
+            continue
+        try:
+            text = readme.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        # First non-heading paragraph.
+        for para in text.split("\n\n"):
+            stripped = para.strip()
+            if not stripped or stripped.startswith("#"):
+                continue
+            # Strip leading badges and HTML <p> wrappers.
+            cleaned = re.sub(r"!\[[^\]]*\]\([^)]+\)", "", stripped)
+            cleaned = re.sub(r"\[[^\]]*\]\([^)]+\)", "", cleaned)
+            cleaned = re.sub(r"<[^>]+>", "", cleaned).strip()
+            if len(cleaned) >= 20:
+                return cleaned[:400]
+    pyproject = project_root / "pyproject.toml"
+    if pyproject.exists():
+        try:
+            text = pyproject.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            text = ""
+        m = re.search(r'description\s*=\s*"([^"]+)"', text)
+        if m:
+            return m.group(1)[:400]
+    return f"Repo at {project_root.name} (no README description found)"
+
+
+def _detect_test_commands(project_root: Path) -> list[str]:
+    cmds: list[str] = []
+    if (project_root / "pyproject.toml").exists():
+        cmds.append("python -m pytest")
+    if (project_root / "tox.ini").exists():
+        cmds.append("tox")
+    if (project_root / "package.json").exists():
+        cmds.append("npm test")
+    if (project_root / "Cargo.toml").exists():
+        cmds.append("cargo test")
+    if (project_root / "Makefile").exists():
+        # Look for a 'test' target.
+        try:
+            mk = (project_root / "Makefile").read_text(
+                encoding="utf-8", errors="replace")
+            if re.search(r"^test:", mk, re.MULTILINE):
+                cmds.append("make test")
+        except OSError:
+            pass
+    if not cmds:
+        cmds.append("# no test runner detected — add tests/ + pytest")
+    return cmds
+
+
+def _release_gate(project_root: Path) -> list[str]:
+    """Heuristic release gate: lint + tests + wire + certify ≥ 75."""
+    gate: list[str] = []
+    if (project_root / "pyproject.toml").exists():
+        gate.append("python -m ruff check .")
+    gate.extend([
+        "python -m pytest",
+        "forge wire src --fail-on-violations",
+        "forge certify . --fail-under 75",
+    ])
+    return gate
+
+
+def _risky_files(lineage: list[dict], top_n: int = 10) -> list[dict]:
+    """Files written most often in the recent lineage are 'risky' —
+    they're the ones the agent has been touching repeatedly. Useful
+    proxy for hot spots without a real edit-frequency analysis."""
+    counter: Counter[str] = Counter()
+    for entry in lineage:
+        path = entry.get("path") or entry.get("artifact")
+        if path:
+            counter[path] += 1
+    return [
+        {"path": p, "edit_count": n}
+        for p, n in counter.most_common(top_n)
+    ]
+
+
+def emit_context_pack(
+    *,
+    project_root: Path,
+    scout_report: dict | None = None,
+    wire_report: dict | None = None,
+    certify_report: dict | None = None,
+    plan: dict | None = None,
+) -> ContextPack:
+    """Build the first-call context bundle.
+
+    Reports may be None — the bundle degrades gracefully and reports
+    'unavailable' for missing sections.
+    """
+    project_root = Path(project_root).resolve()
+    tier_map = (scout_report or {}).get("tier_distribution") or {}
+    primary_language = (scout_report or {}).get("primary_language", "?")
+
+    blockers = summarize_blockers(
+        wire_report=wire_report, certify_report=certify_report,
+        package_root=project_root.name,
+    )
+    best_next: dict | None = None
+    if plan and plan.get("top_actions"):
+        best_next = plan["top_actions"][0]
+    elif blockers["blockers"]:
+        b = blockers["blockers"][0]
+        best_next = {
+            "id": "blocker." + (b.get("f_code") or "?"),
+            "title": b.get("title", ""),
+            "next_command": b.get("next_command", ""),
+            "kind": "blocker",
+        }
+
+    lineage = read_lineage(project_root, last=20)
+
+    return ContextPack(
+        schema_version=SCHEMA_VERSION_CONTEXT_PACK_V1,
+        project_root=str(project_root),
+        repo_purpose=_read_repo_purpose(project_root),
+        architecture_law=_TIER_LAW,
+        tier_map=dict(tier_map),
+        primary_language=primary_language,
+        blockers_summary=blockers,
+        best_next_action=best_next,
+        test_commands=_detect_test_commands(project_root),
+        release_gate=_release_gate(project_root),
+        risky_files=_risky_files(lineage),
+        recent_lineage=lineage[-10:] if lineage else [],
+        pinned_resources=[
+            "forge://docs/receipt",
+            "forge://docs/formalization",
+            "forge://summary/blockers",
+        ],
+    )

atomadic_forge/a1_at_functions/agent_memory.py

@@ -0,0 +1,139 @@
+"""Tier a1 — agent memory queries (Codex #5).
+
+Codex's prescription:
+
+  > Make .atomadic-forge/ a real agent memory substrate. Future
+  > agents can ask: why_did_this_change({file}),
+  > what_failed_last_time({area}). That's gold.
+
+Pure: queries lineage.jsonl + plan state files. No I/O beyond those
+two read paths.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TypedDict
+
+from .lineage_reader import read_lineage
+
+SCHEMA_VERSION_WHY_V1 = "atomadic-forge.why/v1"
+SCHEMA_VERSION_WHAT_FAILED_V1 = "atomadic-forge.what_failed/v1"
+
+
+class WhyDidThisChange(TypedDict, total=False):
+    schema_version: str
+    file: str
+    related_lineage: list[dict]
+    related_plan_events: list[dict]
+    summary: str
+
+
+class WhatFailedLastTime(TypedDict, total=False):
+    schema_version: str
+    area: str
+    failures: list[dict]
+    summary: str
+
+
+def why_did_this_change(
+    *,
+    file: str,
+    project_root: Path,
+) -> WhyDidThisChange:
+    """Return every lineage + plan event referencing ``file``.
+
+    Heuristic: an entry 'references' the file when:
+      * the entry's `path` field equals or contains the file path
+      * the entry is a plan event whose card.write_scope contains it
+
+    Pure: read-only lineage + plan-state walks.
+    """
+    project_root = Path(project_root).resolve()
+    lineage = read_lineage(project_root)
+    related_lineage = [
+        entry for entry in lineage
+        if entry.get("path", "") == file
+        or file in entry.get("path", "")
+    ]
+
+    plan_events: list[dict] = []
+    plans_dir = project_root / ".atomadic-forge" / "plans"
+    if plans_dir.is_dir():
+        import json
+        for state_file in plans_dir.glob("*.state.json"):
+            try:
+                state = json.loads(state_file.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                continue
+            for ev in state.get("events", []):
+                detail = ev.get("detail") or {}
+                # Direct path match in detail (e.g. README write).
+                if isinstance(detail.get("written"), str) \
+                        and detail["written"] == file:
+                    plan_events.append({**ev,
+                                          "plan_id": state.get("plan_id")})
+                    continue
+                if file in str(detail):
+                    plan_events.append({**ev,
+                                          "plan_id": state.get("plan_id")})
+
+    if related_lineage or plan_events:
+        last_ts = ""
+        for entry in related_lineage + plan_events:
+            ts = entry.get("ts_utc", "")
+            if ts > last_ts:
+                last_ts = ts
+        summary = (
+            f"{file} appears in {len(related_lineage)} lineage entries "
+            f"and {len(plan_events)} plan events; latest activity "
+            f"{last_ts or '(unknown)'}."
+        )
+    else:
+        summary = f"no recorded forge activity references {file}."
+
+    return WhyDidThisChange(
+        schema_version=SCHEMA_VERSION_WHY_V1,
+        file=file,
+        related_lineage=related_lineage,
+        related_plan_events=plan_events,
+        summary=summary,
+    )
+
+
+def what_failed_last_time(
+    *,
+    area: str,
+    project_root: Path,
+) -> WhatFailedLastTime:
+    """Return plan events with status 'failed' or 'rolled_back' that
+    relate to ``area`` (matched as a substring of card_id / detail).
+    """
+    project_root = Path(project_root).resolve()
+    failures: list[dict] = []
+    plans_dir = project_root / ".atomadic-forge" / "plans"
+    if plans_dir.is_dir():
+        import json
+        for state_file in plans_dir.glob("*.state.json"):
+            try:
+                state = json.loads(state_file.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                continue
+            for ev in state.get("events", []):
+                if ev.get("status") not in {"failed", "rolled_back"}:
+                    continue
+                blob = (ev.get("card_id", "") + " " +
+                        str(ev.get("detail", "")))
+                if not area or area.lower() in blob.lower():
+                    failures.append({**ev,
+                                       "plan_id": state.get("plan_id")})
+    summary = (
+        f"{len(failures)} prior failure(s) referencing area={area!r}."
+        if failures
+        else f"no prior failures recorded for area={area!r}."
+    )
+    return WhatFailedLastTime(
+        schema_version=SCHEMA_VERSION_WHAT_FAILED_V1,
+        area=area,
+        failures=failures,
+        summary=summary,
+    )