agent-debrief 0.1.0__py3-none-any.whl

agent_debrief/__init__.py

@@ -0,0 +1,3 @@
+"""Agent Debrief — understand what your AI coding agent actually built."""
+
+__version__ = "0.1.0"

agent_debrief/__main__.py

@@ -0,0 +1,18 @@
+"""``python -m agent_debrief`` — also the entry point Claude Code hooks use."""
+
+import sys
+
+
+def _entry() -> None:
+    # Fast path: hooks run on every tool call, so avoid importing the CLI/web stack for them.
+    if len(sys.argv) >= 3 and sys.argv[1] == "hook":
+        from agent_debrief.cli.hook import run_hook
+
+        sys.exit(run_hook(sys.argv[2]))
+    from agent_debrief.cli.app import main
+
+    main()
+
+
+if __name__ == "__main__":
+    _entry()

agent_debrief/ai/__init__.py

@@ -0,0 +1 @@
+"""LLM orchestration: providers, prompts and validated structured outputs."""

agent_debrief/ai/orchestrator.py

@@ -0,0 +1,57 @@
+"""Runs one LLM workflow: build the call, validate the structured result, retry with feedback."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, TypeVar
+
+from pydantic import BaseModel, ValidationError
+
+from ..config.settings import AppConfig
+from .providers.base import LLMError, LLMProvider, run_sync
+from .providers.registry import build_provider
+
+log = logging.getLogger("agent_debrief.ai")
+M = TypeVar("M", bound=BaseModel)
+MAX_ATTEMPTS = 3
+
+
+class Orchestrator:
+    def __init__(self, config: AppConfig, provider: LLMProvider | None = None) -> None:
+        self.config = config
+        self.provider = provider if provider is not None else build_provider(config)
+
+    @property
+    def available(self) -> bool:
+        return self.provider is not None
+
+    @property
+    def provider_name(self) -> str | None:
+        return self.provider.name if self.provider else None
+
+    @property
+    def model_name(self) -> str | None:
+        return self.provider.model if self.provider else None
+
+    def run(self, workflow: str, system_prompt: str, context: dict[str, Any], model_cls: type[M]) -> M:
+        """Return a validated ``model_cls``. Raises :class:`LLMError` if the model cannot comply."""
+        if self.provider is None:
+            raise LLMError("No LLM provider is configured")
+        schema = model_cls.model_json_schema()
+        payload = dict(context)
+        last_problem = ""
+        for attempt in range(1, MAX_ATTEMPTS + 1):
+            if last_problem:
+                payload["previous_attempt_error"] = (
+                    "Your previous answer was rejected: " + last_problem
+                    + " Return a corrected answer that follows the schema."
+                )
+            try:
+                raw = run_sync(self.provider.generate_structured(system_prompt, payload, schema))
+                return model_cls.model_validate(raw)
+            except ValidationError as exc:
+                last_problem = "; ".join(f"{'.'.join(map(str, e['loc']))}: {e['msg']}" for e in exc.errors()[:5])
+                log.warning("%s attempt %d returned invalid structure: %s", workflow, attempt, last_problem)
+            except LLMError:
+                raise
+        raise LLMError(f"The model did not produce a valid {workflow} answer after {MAX_ATTEMPTS} attempts ({last_problem})")

agent_debrief/ai/prompts/__init__.py

@@ -0,0 +1 @@
+"""Prompt templates (one workflow = one focused prompt)."""

agent_debrief/ai/prompts/workflows.py

@@ -0,0 +1,66 @@
+"""One focused system prompt per workflow (never one giant prompt)."""
+
+RULES = """You are part of Agent Debrief, a tool that helps a developer understand what an AI coding \
+agent implemented.
+Ground rules — they matter more than style:
+1. Use ONLY the evidence in the provided JSON (`evidence`, `facts`, `changes`, `symbols`, `flow`...). \
+Never invent files, functions, endpoints, behaviour or test results.
+2. Every claim must list the `evidence_ids` that support it, copied exactly from the input. If you cannot \
+support a statement with evidence, leave `evidence_ids` empty rather than guessing.
+3. Put file names, function names and code identifiers in `backticks`, and only mention ones that appear \
+in the input.
+4. Keep the three kinds of statement distinct: what the code verifiably does, what the agent said it did, \
+and your own interpretation. Interpretation must be phrased as such ("this suggests…").
+5. If the evidence is incomplete, say so plainly in the limitations/notes field.
+6. Be concise. The reader is a developer who did not write this code."""
+
+LEVEL_GUIDE = {
+    "beginner": "Reader level: BEGINNER. Avoid jargon; define any technical term in a few words; use an everyday analogy if it helps; short sentences.",
+    "developer": "Reader level: DEVELOPER. Assume general programming knowledge but not familiarity with this codebase; be precise and brief.",
+    "advanced": "Reader level: ADVANCED. Skip basics; focus on design trade-offs, edge cases, failure modes and security/performance implications.",
+}
+
+TASK_SUMMARIZER = RULES + """
+
+Workflow: TASK SUMMARIZER. Produce at most FIVE bullets (<= 25 words each) that let the reader grasp the \
+completed task in 30 seconds: what was asked, what was actually built, how it works at a high level, how \
+it was tested, and what to watch out for. Put deeper technical detail in each bullet's `detail`. List \
+genuinely unfinished work in `remaining_work` only if the evidence (agent message, failing tests, missing \
+tests) shows it. Never claim the task is complete or correct — only report what the evidence shows."""
+
+CHANGE_EXPLAINER = RULES + """
+
+Workflow: CHANGE EXPLAINER. Explain HOW the implemented change works as 3-6 short claims, in execution \
+order (request in → processing → data access → response). Each claim must cite the code-range or diff \
+evidence it is based on. Mention error handling that exists, and note when none was found."""
+
+FLOW_GENERATOR = RULES + """
+
+Workflow: FLOW ANNOTATOR. The application flow graph is already built from static analysis; you may NOT \
+add, remove or reconnect nodes or edges. For the nodes provided, write: a one-sentence `description`, \
+`why_it_exists` (its role in the flow, based on who calls it and what it does), `inputs`, `outputs` and \
+`error_scenarios` (only those visible in the code: raised exceptions, status codes, guarded branches). \
+Use node ids exactly as given. Skip a node if you have nothing evidence-based to add."""
+
+CONCEPT_TUTOR = RULES + """
+
+Workflow: TUTOR. Teach each provided concept using THIS implementation. For each concept: \
+`simple_explanation` (the idea, at the reader level), `in_this_implementation` (point at the exact \
+functions/lines from the evidence and say what role the concept plays there), `why_needed`, \
+`failure_cases` (what goes wrong if it is missing or misused here), and a short `knowledge_check` \
+question with its answer. Do not add concepts that were not provided."""
+
+VOICE_ASSISTANT = RULES + """
+
+Workflow: VOICE EXPLAINER. Write what a friendly colleague would SAY out loud: short, natural spoken \
+sentences (max ~18 words each), no markdown, no bullet symbols, no code blocks, spell out symbols \
+("slash login" rather than "/login" only if it reads better). 5-10 sentences. Do not read file paths \
+character by character — name the function or file once and move on."""
+
+QA_ASSISTANT = RULES + """
+
+Workflow: QUESTION ANSWERING. Answer the developer's question about this specific task.
+Structure: (1) `direct_answer` first — the answer in 1-4 sentences; (2) `supporting_evidence_ids` — the \
+evidence that backs it; (3) `flow_explanation` — how the relevant code path works, if useful; (4) \
+`limitations` — what the evidence does not tell you (e.g. the agent's reasoning is only known if it said \
+so). If the evidence does not contain the answer, say so in `direct_answer` instead of guessing."""

agent_debrief/ai/providers/__init__.py

@@ -0,0 +1 @@
+"""LLM provider implementations."""

agent_debrief/ai/providers/anthropic.py

@@ -0,0 +1,60 @@
+"""Anthropic Messages API (structured output via a forced tool call)."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+
+from .base import LLMError, LLMProvider, scrub
+
+DEFAULT_BASE_URL = "https://api.anthropic.com"
+API_VERSION = "2023-06-01"
+
+
+class AnthropicProvider(LLMProvider):
+    name = "anthropic"
+
+    def __init__(self, api_key: str, model: str, base_url: str | None = None,
+                 max_tokens: int = 4096, timeout: float = 120) -> None:
+        self.api_key = api_key
+        self.model = model
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.max_tokens = max_tokens
+        self.timeout = timeout
+
+    async def generate_structured(
+        self, system_prompt: str, context: dict[str, Any], response_schema: dict[str, Any]
+    ) -> dict[str, Any]:
+        body = {
+            "model": self.model,
+            "max_tokens": self.max_tokens,
+            "system": system_prompt,
+            "messages": [{"role": "user", "content": json.dumps(context, ensure_ascii=False)}],
+            "tools": [{
+                "name": "respond",
+                "description": "Return your answer. Fill every field using only the supplied evidence.",
+                "input_schema": response_schema,
+            }],
+            "tool_choice": {"type": "tool", "name": "respond"},
+        }
+        headers = {"x-api-key": self.api_key, "anthropic-version": API_VERSION, "content-type": "application/json"}
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                response = await client.post(f"{self.base_url}/v1/messages", headers=headers, json=body)
+        except httpx.HTTPError as exc:
+            raise LLMError(scrub(f"Could not reach Anthropic: {exc}", self.api_key)) from exc
+        if response.status_code >= 400:
+            raise LLMError(scrub(f"Anthropic returned {response.status_code}: {_error_message(response)}", self.api_key))
+        for block in response.json().get("content", []):
+            if block.get("type") == "tool_use" and isinstance(block.get("input"), dict):
+                return block["input"]
+        raise LLMError("Anthropic returned no structured answer")
+
+
+def _error_message(response: httpx.Response) -> str:
+    try:
+        return str(response.json().get("error", {}).get("message") or response.text[:200])
+    except ValueError:
+        return response.text[:200]

agent_debrief/ai/providers/base.py

@@ -0,0 +1,56 @@
+"""LLM provider abstraction."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from collections.abc import Coroutine
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+class LLMError(RuntimeError):
+    """A provider call failed or returned something unusable. Messages never contain API keys."""
+
+
+class LLMProvider:
+    """Generate a JSON object that conforms to ``response_schema``."""
+
+    name: str = "base"
+    model: str = ""
+
+    async def generate_structured(
+        self, system_prompt: str, context: dict[str, Any], response_schema: dict[str, Any]
+    ) -> dict[str, Any]:
+        raise NotImplementedError
+
+
+def run_sync(coro: Coroutine[Any, Any, T]) -> T:
+    """Run a coroutine from synchronous code, even when called from inside a running event loop."""
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coro)
+    box: dict[str, Any] = {}
+
+    def runner() -> None:
+        try:
+            box["value"] = asyncio.run(coro)
+        except BaseException as exc:  # noqa: BLE001
+            box["error"] = exc
+
+    thread = threading.Thread(target=runner, daemon=True)
+    thread.start()
+    thread.join()
+    if "error" in box:
+        raise box["error"]
+    return box["value"]
+
+
+def scrub(message: str, *secrets: str | None) -> str:
+    """Remove credentials from an error message before it can be shown or logged."""
+    for secret in secrets:
+        if secret and len(secret) > 6:
+            message = message.replace(secret, "[REDACTED]")
+    return message[:500]

agent_debrief/ai/providers/openai_compat.py

@@ -0,0 +1,87 @@
+"""OpenAI Chat Completions — also any OpenAI-compatible server (Ollama, vLLM, OpenRouter, LM Studio…)."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+import httpx
+
+from .base import LLMError, LLMProvider, scrub
+
+DEFAULT_BASE_URL = "https://api.openai.com/v1"
+
+
+class OpenAICompatibleProvider(LLMProvider):
+    name = "openai"
+
+    def __init__(self, api_key: str | None, model: str, base_url: str | None = None,
+                 max_tokens: int = 4096, timeout: float = 120, name: str = "openai") -> None:
+        self.api_key = api_key
+        self.model = model
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.max_tokens = max_tokens
+        self.timeout = timeout
+        self.name = name
+
+    async def generate_structured(
+        self, system_prompt: str, context: dict[str, Any], response_schema: dict[str, Any]
+    ) -> dict[str, Any]:
+        system = (
+            system_prompt
+            + "\n\nReply with ONE JSON object that matches this JSON Schema exactly, and nothing else:\n"
+            + json.dumps(response_schema)
+        )
+        messages = [{"role": "system", "content": system},
+                    {"role": "user", "content": json.dumps(context, ensure_ascii=False)}]
+        headers = {"content-type": "application/json"}
+        if self.api_key:
+            headers["authorization"] = f"Bearer {self.api_key}"
+
+        formats: list[dict[str, Any] | None] = [
+            {"type": "json_schema", "json_schema": {"name": "response", "schema": response_schema, "strict": False}},
+            {"type": "json_object"},
+            None,
+        ]
+        last_error = "no response"
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            for fmt in formats:
+                body: dict[str, Any] = {"model": self.model, "messages": messages, "max_tokens": self.max_tokens}
+                if fmt:
+                    body["response_format"] = fmt
+                try:
+                    response = await client.post(f"{self.base_url}/chat/completions", headers=headers, json=body)
+                except httpx.HTTPError as exc:
+                    raise LLMError(scrub(f"Could not reach the LLM endpoint: {exc}", self.api_key)) from exc
+                if response.status_code == 400 and fmt is not None:
+                    last_error = response.text[:200]
+                    continue  # this server does not support that response_format — try a simpler one
+                if response.status_code >= 400:
+                    raise LLMError(scrub(f"LLM endpoint returned {response.status_code}: {response.text[:200]}", self.api_key))
+                try:
+                    text = response.json()["choices"][0]["message"]["content"]
+                except (KeyError, IndexError, ValueError, TypeError) as exc:
+                    raise LLMError("The LLM endpoint returned an unexpected response shape") from exc
+                return _parse_json(text)
+        raise LLMError(scrub(f"The LLM endpoint rejected every response format: {last_error}", self.api_key))
+
+
+def _parse_json(text: str) -> dict[str, Any]:
+    text = (text or "").strip()
+    fenced = re.match(r"^```(?:json)?\s*(.*?)\s*```$", text, re.S)
+    if fenced:
+        text = fenced.group(1)
+    try:
+        data = json.loads(text)
+    except ValueError:
+        match = re.search(r"\{.*\}", text, re.S)
+        if not match:
+            raise LLMError("The model did not return JSON") from None
+        try:
+            data = json.loads(match.group(0))
+        except ValueError as exc:
+            raise LLMError("The model returned malformed JSON") from exc
+    if not isinstance(data, dict):
+        raise LLMError("The model returned JSON that is not an object")
+    return data

agent_debrief/ai/providers/registry.py

@@ -0,0 +1,32 @@
+"""Build the configured provider (or ``None`` when running offline)."""
+
+from __future__ import annotations
+
+from ...config import resolve_api_key
+from ...config.settings import DEFAULT_MODELS, AppConfig
+from .anthropic import AnthropicProvider
+from .base import LLMProvider
+from .openai_compat import OpenAICompatibleProvider
+
+
+def build_provider(config: AppConfig) -> LLMProvider | None:
+    llm = config.llm
+    if llm.provider == "none":
+        return None
+    key, _ = resolve_api_key(llm)
+    model = llm.model or DEFAULT_MODELS.get(llm.provider) or ""
+    if llm.provider == "anthropic":
+        if not key or not model:
+            return None
+        return AnthropicProvider(key, model, llm.base_url, llm.max_output_tokens, llm.timeout_seconds)
+    if llm.provider in {"openai", "openai_compatible"}:
+        # Local OpenAI-compatible servers often need no key, but hosted OpenAI always does.
+        if (llm.provider == "openai" and not key) or not model:
+            return None
+        return OpenAICompatibleProvider(key, model, llm.base_url, llm.max_output_tokens, llm.timeout_seconds,
+                                        name=llm.provider)
+    return None
+
+
+def llm_configured(config: AppConfig) -> bool:
+    return build_provider(config) is not None

agent_debrief/ai/structured_outputs/__init__.py

@@ -0,0 +1 @@
+"""Pydantic schemas the LLM must answer with."""

agent_debrief/ai/structured_outputs/schemas.py

@@ -0,0 +1,73 @@
+"""What each LLM workflow must return. Validated with Pydantic; invalid output triggers a retry."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ClaimLLM(BaseModel):
+    text: str = Field(min_length=3, max_length=600)
+    evidence_ids: list[str] = Field(default_factory=list)
+
+
+class BulletLLM(BaseModel):
+    text: str = Field(min_length=3, max_length=300)
+    detail: str | None = Field(default=None, max_length=1200)
+    evidence_ids: list[str] = Field(default_factory=list)
+
+
+class SummaryLLM(BaseModel):
+    bullets: list[BulletLLM] = Field(min_length=1, max_length=5)
+    remaining_work: list[ClaimLLM] = Field(default_factory=list, max_length=6)
+
+
+class ChangeExplainLLM(BaseModel):
+    how_it_works: list[ClaimLLM] = Field(min_length=1, max_length=8)
+
+
+class NodeAnnotation(BaseModel):
+    node_id: str
+    description: str | None = Field(default=None, max_length=500)
+    why_it_exists: str | None = Field(default=None, max_length=400)
+    inputs: list[str] = Field(default_factory=list, max_length=8)
+    outputs: list[str] = Field(default_factory=list, max_length=8)
+    error_scenarios: list[str] = Field(default_factory=list, max_length=8)
+    evidence_ids: list[str] = Field(default_factory=list)
+
+
+class FlowAnnotationsLLM(BaseModel):
+    nodes: list[NodeAnnotation] = Field(default_factory=list, max_length=60)
+
+
+class KnowledgeCheckLLM(BaseModel):
+    question: str
+    options: list[str] = Field(default_factory=list, max_length=5)
+    answer: str
+    explanation: str
+
+
+class LessonLLM(BaseModel):
+    concept_id: str
+    simple_explanation: str = Field(max_length=900)
+    in_this_implementation: str = Field(max_length=900)
+    why_needed: str = Field(max_length=500)
+    failure_cases: list[str] = Field(default_factory=list, max_length=5)
+    knowledge_check: KnowledgeCheckLLM | None = None
+    evidence_ids: list[str] = Field(default_factory=list)
+
+
+class TutorLLM(BaseModel):
+    lessons: list[LessonLLM] = Field(default_factory=list, max_length=10)
+
+
+class VoiceLLM(BaseModel):
+    sentences: list[str] = Field(min_length=1, max_length=14)
+    evidence_ids: list[str] = Field(default_factory=list)
+
+
+class ChatLLM(BaseModel):
+    direct_answer: str = Field(min_length=1, max_length=1500)
+    supporting_evidence_ids: list[str] = Field(default_factory=list)
+    flow_explanation: str | None = Field(default=None, max_length=1500)
+    limitations: str | None = Field(default=None, max_length=600)
+    suggested_questions: list[str] = Field(default_factory=list, max_length=4)

agent_debrief/analysis/__init__.py

@@ -0,0 +1 @@
+"""Code and session analysis. The understanding engine's deterministic core."""

agent_debrief/analysis/architecture_analyzer.py

@@ -0,0 +1,105 @@
+"""Evidence-based architecture layering.
+
+Each symbol is placed in a layer with an explicit *basis* and confidence. Only decorators (a route,
+a background task) are strong enough to be called ``verified``; naming/path/import conventions are
+``inferred`` and say so. When nothing fits, the layer is ``other`` — uncertainty is allowed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import PurePosixPath
+
+from ..models.understanding import ArchitectureLayer
+from .ast_analyzer import SymbolInfo
+from .relationship_analyzer import Relationship, classify_external
+from .symbol_indexer import SymbolIndex
+
+PATH_TOKENS: dict[str, set[str]] = {
+    "api": {"routes", "route", "router", "routers", "api", "endpoints", "views", "controllers", "controller", "handlers", "resources"},
+    "service": {"service", "services", "usecases", "use_cases", "domain", "logic", "managers", "workflows"},
+    "database": {"repository", "repositories", "repo", "repos", "db", "database", "dao", "models", "orm", "crud", "queries", "storage", "store", "migrations"},
+    "external": {"clients", "client", "integrations", "adapters", "gateways", "providers", "connectors"},
+    "background": {"tasks", "jobs", "workers", "celery", "cron", "scheduler"},
+}
+CLASS_SUFFIX = {"Service": "service", "Repository": "database", "Repo": "database", "Controller": "api",
+                "Handler": "api", "Client": "external", "Gateway": "external", "Worker": "background"}
+BACKGROUND_DECORATORS = ("shared_task", ".task", "celery", "repeat_every", "scheduled", "cron", "periodic_task")
+FRONTEND_EXT = {".tsx", ".jsx", ".vue", ".svelte", ".html", ".css", ".scss", ".js", ".ts"}
+
+
+@dataclass
+class Placement:
+    layer: str
+    confidence: str  # high | medium | low
+    verification: str  # verified | inferred
+    basis: list[str] = field(default_factory=list)
+
+
+def classify_symbols(index: SymbolIndex, rels: list[Relationship]) -> dict[str, Placement]:
+    """qualified_name -> placement for every indexed function/method/class in the changed files."""
+    db_users: set[str] = set()
+    external_users: set[str] = set()
+    for rel in rels:
+        if rel.kind == "uses" and rel.target.startswith("external:"):
+            kind = classify_external(rel.target)
+            (db_users if kind == "database" else external_users if kind == "external" else set()).add(rel.source)
+
+    placements: dict[str, Placement] = {}
+    for rel_file, module in index.modules.items():  # changed files *and* the context they import
+        for sym in module.symbols:
+            placements[sym.qualified_name] = _place(sym, rel_file, db_users, external_users)
+    return placements
+
+
+def _place(sym: SymbolInfo, rel_file: str, db_users: set[str], external_users: set[str]) -> Placement:
+    if sym.routes:
+        route = sym.routes[0]
+        return Placement("api", "high", "verified", [f"route decorator for {route['method']} {route['path']}"])
+    if any(any(tok in d for tok in BACKGROUND_DECORATORS) for d in sym.decorators):
+        return Placement("background", "high", "verified", [f"decorator {sym.decorators[0]}"])
+    if sym.qualified_name in db_users:
+        return Placement("database", "medium", "inferred", ["calls into a database library / looks like a DB call"])
+    if sym.qualified_name in external_users:
+        return Placement("external", "medium", "inferred", ["calls into an external service client library"])
+    tokens = {t.lower() for t in PurePosixPath(rel_file).with_suffix("").parts}
+    for layer, words in PATH_TOKENS.items():
+        hit = tokens & words
+        if hit:
+            return Placement(layer, "medium", "inferred", [f"file path contains '{sorted(hit)[0]}'"])
+    for suffix, layer in CLASS_SUFFIX.items():
+        if sym.name.endswith(suffix) or (sym.parent or "").endswith(suffix):
+            return Placement(layer, "low", "inferred", [f"name ends with '{suffix}'"])
+    return Placement("other", "low", "inferred", ["no layer convention matched"])
+
+
+def build_architecture(
+    placements: dict[str, Placement], non_python_files: list[str], only: set[str] | None = None
+) -> list[ArchitectureLayer]:
+    """Summarise layers for the symbols in ``only`` (the changed ones); context symbols are skipped."""
+    grouped: dict[str, ArchitectureLayer] = {}
+    for qname, place in placements.items():
+        if place.layer == "other" or (only is not None and qname not in only):
+            continue
+        layer = grouped.setdefault(
+            place.layer,
+            ArchitectureLayer(layer=place.layer, confidence=place.confidence,  # type: ignore[arg-type]
+                              verification_status=place.verification),  # type: ignore[arg-type]
+        )
+        layer.symbols.append(qname)
+        for b in place.basis:
+            if b not in layer.basis and len(layer.basis) < 4:
+                layer.basis.append(b)
+        order = {"low": 0, "medium": 1, "high": 2}
+        if order[place.confidence] < order[layer.confidence]:
+            layer.confidence = place.confidence  # type: ignore[assignment]
+        if place.verification == "inferred":
+            layer.verification_status = "inferred"
+    frontend = [f for f in non_python_files if PurePosixPath(f).suffix.lower() in FRONTEND_EXT]
+    if frontend:
+        grouped["frontend"] = ArchitectureLayer(
+            layer="frontend", files=sorted(frontend), confidence="medium", verification_status="inferred",
+            basis=["changed files have front-end extensions (" + ", ".join(sorted({PurePosixPath(f).suffix for f in frontend})) + ")"],
+        )
+    order_names = ["frontend", "api", "service", "database", "external", "background"]
+    return sorted(grouped.values(), key=lambda a: order_names.index(a.layer) if a.layer in order_names else 99)