devtime-ei 0.1.0__py3-none-any.whl

devtime/intelligence/context_pack.py

@@ -0,0 +1,276 @@
+"""Context Packs (Builder Edition, Chapter 14; Trust Repair v0.0.6).
+
+Context Packs are governed repository memory for humans and AI agents. Trust Repair
+makes them: (1) refuse to be authoritative when concept evidence is weak, (2) cap
+and rank recommended tests, and (3) attach a reason to every recommended test.
+"""
+
+from __future__ import annotations
+
+import posixpath
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+from devtime.intelligence.claims import ConceptIntelligence
+
+MODES = ("overview", "risk", "implementation", "testing", "onboarding", "security")
+MAX_TESTS = 8
+
+# Domain terms used to rank/justify test relevance per concept.
+DOMAIN_TERMS = {
+    "Billing Webhooks": ("stripe", "paypal", "billing", "payment", "invoice", "checkout", "webhook"),
+    "Authentication": ("auth", "jwt", "token", "login", "session", "oauth", "password"),
+    "Background Jobs": ("job", "queue", "worker", "task", "celery", "bullmq", "cron"),
+    "Data Export": ("export", "download", "csv", "report", "backup"),
+    "Admin Permissions": ("admin", "permission", "role", "rbac", "superuser"),
+    "File Uploads": ("upload", "multipart", "file", "attachment", "storage"),
+}
+
+# Specific import tokens that prove a test references a concept's implementation,
+# so the import reason fires even when the implementation file itself was not
+# captured as evidence (Codex blocker 3: Plane bg_tasks).
+CONCEPT_IMPORT_HINTS = {
+    "Background Jobs": ("bgtask", "bgtasks", "bg_task", "celery", "sidekiq", "bullmq", "worker"),
+    "Billing Webhooks": ("stripe", "paypal", "braintree", "chargebee"),
+    "Authentication": ("nextauth", "next-auth", "passport"),
+    "Data Export": (),
+    "Admin Permissions": (),
+    "File Uploads": ("multer", "busboy", "uploadfile"),
+}
+
+# Path segments that mark a directory as test-only. A test-only directory can never
+# be "the same directory as the implementation" (Codex blocker 1: __e2e__).
+_TEST_DIR_SEGMENTS = (
+    "tests", "test", "__tests__", "spec", "specs", "e2e", "__e2e__",
+    "integration", "unit", "cypress", "playwright", "e2e-tests", "__test__",
+)
+
+
+def _is_test_only_dir(dir_path: str) -> bool:
+    return any(seg in _TEST_DIR_SEGMENTS for seg in dir_path.lower().split("/"))
+
+
+@dataclass
+class TestRec:
+    path: str
+    reason: str
+    rank: int
+
+
+@dataclass
+class ContextPack:
+    concept: str
+    mode: str
+    purpose: str
+    limited: bool = False
+    supported_claims: list[str] = field(default_factory=list)
+    decisions: list[str] = field(default_factory=list)
+    uncertainty: list[str] = field(default_factory=list)
+    do_not_change: list[str] = field(default_factory=list)
+    tests_to_run: list[TestRec] = field(default_factory=list)
+    agent_guidance: str = ""
+    generated_at: str = ""
+
+
+def _is_weak(ci: ConceptIntelligence) -> bool:
+    return getattr(ci.concept, "weak_only", False) or ci.concept.confidence < 0.5
+
+
+def _do_not_change_warnings(ci: ConceptIntelligence) -> list[str]:
+    """Derive 'do not change' warnings from actual evidence, never a hardcoded table.
+    Weak/false concepts must not produce authoritative warnings."""
+    if _is_weak(ci):
+        return [
+            "Evidence weak - manual validation required before using this as agent context."
+        ]
+    kinds = {e.signal.kind for e in ci.evidence}
+    warnings: list[str] = []
+    if "webhook_signature_verification" in kinds:
+        warnings.append("Webhook signature verification behavior.")
+    if "token_usage" in kinds:
+        warnings.append("Token issuing and verification behavior.")
+    if "auth_dependency" in kinds or "middleware" in kinds:
+        warnings.append("Authorization / protected-route behavior.")
+    if "route" in kinds:
+        warnings.append(f"Request handling behavior for {ci.concept.name}.")
+    if "background_job" in kinds or "queue" in kinds:
+        warnings.append("Job/queue processing behavior.")
+    if not warnings:
+        warnings.append(f"Core behavior of {ci.concept.name} without a reviewer.")
+    return warnings
+
+
+# Generic path/monorepo tokens that are not specific enough to prove an import
+# relation (avoids "imports" matching on "src", "plane", "packages", etc).
+_COMMON_PATH_TOKENS = {
+    "app", "apps", "api", "src", "lib", "libs", "server", "servers", "service",
+    "services", "test", "tests", "spec", "specs", "package", "packages", "shared",
+    "web", "core", "common", "utils", "util", "index", "main", "models", "model",
+    "types", "type", "components", "component", "pages", "routes", "route",
+    "handlers", "handler", "dist", "build", "internal", "backend", "frontend",
+    "plane", "modules", "module", "config", "configs",
+}
+
+
+def _impl_modules(ci: ConceptIntelligence) -> set[str]:
+    """Specific identifier tokens from non-test evidence paths, for import matching.
+    Common monorepo/path tokens are excluded so an import match is meaningful."""
+    mods: set[str] = set()
+    for e in ci.evidence:
+        if e.path and e.signal.kind != "test":
+            stem = e.path.lower().replace("\\", "/").replace(".py", "").replace(".ts", "")
+            for part in stem.split("/"):
+                if len(part) >= 4 and part not in _COMMON_PATH_TOKENS:
+                    mods.add(part)
+    return mods
+
+
+def _impl_dirs_non_test(ci: ConceptIntelligence) -> set[str]:
+    """Directories of real (non-test) implementation evidence files. Excludes any
+    directory that is itself test-only (e2e/spec/unit/...)."""
+    dirs: set[str] = set()
+    for e in ci.evidence:
+        if not e.path or e.signal.kind == "test":
+            continue
+        d = posixpath.dirname(e.path)
+        if _is_test_only_dir(d):
+            continue  # a non-test file living under a test tree is not "the impl dir"
+        dirs.add(d)
+    return dirs
+
+
+def _rank_tests(ci: ConceptIntelligence) -> list[TestRec]:
+    """Recommend a test ONLY when the relation is provable, with a true reason
+    (Codex blockers 2 & 3):
+      1. import/reference to the implementation  (highest)
+      2. EXACT same directory as a real implementation file
+      otherwise omit - a missing recommendation beats a false reason.
+    "same directory" requires literally equal parent directories, never a shared
+    package/keyword/monorepo token."""
+    impl_dirs = _impl_dirs_non_test(ci)
+    impl_modules = _impl_modules(ci)
+    impl_paths = [
+        e.path.lower().rsplit(".", 1)[0]
+        for e in ci.evidence
+        if e.path and e.signal.kind != "test"
+    ]
+    hints = CONCEPT_IMPORT_HINTS.get(ci.concept.name, ())
+
+    recs: list[TestRec] = []
+    seen: set[str] = set()
+    for e in ci.evidence:
+        if e.signal.kind != "test" or not e.path or e.path in seen:
+            continue
+        seen.add(e.path)
+        d = posixpath.dirname(e.path)
+        imports = [str(i).lower() for i in e.signal.metadata.get("imports", [])]
+
+        # An import matches the implementation if it: references a specific impl
+        # module token, matches a dotted module path against an impl file path
+        # (plane.bgtasks.copy_s3_object -> plane/bgtasks/copy_s3_object), or hits a
+        # concept-specific import hint.
+        def _matches(imp: str) -> bool:
+            if any(m in imp for m in impl_modules):
+                return True
+            frag = imp.replace(".", "/")
+            if len(frag) >= 6 and any(frag in p for p in impl_paths):
+                return True
+            return any(h in imp for h in hints)
+
+        imported = any(_matches(imp) for imp in imports)
+        if imported:
+            recs.append(TestRec(
+                e.path,
+                "Recommended because it imports or tests the implementation.",
+                4,
+            ))
+        elif d in impl_dirs and not _is_test_only_dir(d):
+            recs.append(TestRec(
+                e.path,
+                "Recommended because it is in the same directory as the implementation.",
+                3,
+            ))
+        # No provable relation -> omit (do not invent a reason).
+
+    recs.sort(key=lambda r: r.rank, reverse=True)
+    return recs[:MAX_TESTS]
+
+
+def generate_context_pack(ci: ConceptIntelligence, mode: str = "risk") -> ContextPack:
+    if mode not in MODES:
+        mode = "risk"
+    weak = _is_weak(ci)
+
+    supported = [
+        f"{c.text} Evidence: "
+        f"{', '.join(dict.fromkeys(e.path for e in c.evidence if e.path)) or 'n/a'}"
+        for c in ci.claims
+        if c.type != "uncertainty" and c.state in ("supported", "weak", "partial")
+    ]
+    decisions = [
+        e.summary for e in ci.evidence if e.kind == "decision"
+    ] or ["No corroborated decision record found."]
+    uncertainty = [u.text for u in ci.uncertainties]
+    tests = _rank_tests(ci)
+
+    if weak:
+        purpose = (
+            f"Context Pack is limited because {ci.concept.name} evidence is weak. "
+            "Validate before using as authoritative agent context."
+        )
+        guidance = (
+            "Evidence is weak or generic. Do not treat this concept as established. "
+            "Validate against the implementation before acting."
+        )
+    else:
+        purpose = f"{ci.concept.name} is detected from repository evidence."
+        guidance = (
+            "Do not invent rationale for missing decisions. Ask a human or record a "
+            "corroborated decision before changing core behavior."
+            if ci.uncertainties
+            else "Preserve existing behavior and keep evidence links intact."
+        )
+
+    return ContextPack(
+        concept=ci.concept.name,
+        mode=mode,
+        purpose=purpose,
+        limited=weak,
+        supported_claims=supported,
+        decisions=decisions,
+        uncertainty=uncertainty,
+        do_not_change=_do_not_change_warnings(ci),
+        tests_to_run=tests,
+        agent_guidance=guidance,
+        generated_at=datetime.now(timezone.utc).isoformat(),
+    )
+
+
+def render_markdown(pack: ContextPack) -> str:
+    lines = [
+        f"# Context Pack: {pack.concept}",
+        f"Mode: {pack.mode}" + ("  (LIMITED - weak evidence)" if pack.limited else ""),
+        "Generated by: DevTime",
+        "Source: local repository memory",
+        "",
+        "## Purpose",
+        pack.purpose,
+        "",
+        "## Supported Claims",
+    ]
+    lines += [f"- {c}" for c in pack.supported_claims] or ["- None"]
+    lines += ["", "## Decisions"]
+    lines += [f"- {d}" for d in pack.decisions]
+    lines += ["", "## Uncertainty"]
+    lines += [f"- {u}" for u in pack.uncertainty] or ["- None"]
+    lines += ["", "## Do Not Change Without Review"]
+    lines += [f"- {w}" for w in pack.do_not_change]
+    lines += ["", f"## Tests To Run (top {MAX_TESTS}, ranked)"]
+    if pack.tests_to_run:
+        for t in pack.tests_to_run:
+            lines.append(f"- {t.path}")
+            lines.append(f"  - {t.reason}")
+    else:
+        lines.append("- No behavior-specific tests found.")
+    lines += ["", "## Agent Instruction", pack.agent_guidance]
+    return "\n".join(lines)

devtime/intelligence/evidence.py

@@ -0,0 +1,127 @@
+"""Evidence system (Builder Edition, Chapter 10).
+
+Evidence is the truth layer. It records what material supports a concept, how
+strong it is, and what claim types it can support.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from devtime.intelligence.concepts import ConceptCandidate
+from devtime.scanner.extractors.base import Signal
+
+# Signal kind -> evidence kind.
+_KIND_MAP = {
+    "route": "route",
+    "middleware": "middleware",
+    "auth_dependency": "auth",
+    "token_usage": "usage",
+    "webhook_signature_verification": "behavior",
+    "background_job": "worker",
+    "queue": "queue",
+    "dependency": "dependency",
+    "config": "config",
+    "test": "test",
+    "doc": "doc",
+    "decision": "decision",
+}
+
+# Evidence strength tiers (Chapter 10).
+STRONG_KINDS = {"route", "auth_dependency", "webhook_signature_verification", "decision"}
+MEDIUM_KINDS = {"middleware", "token_usage", "background_job", "config"}
+# "test" strength depends on whether it is behavior-specific; handled below.
+WEAK_KINDS = {"dependency", "doc"}
+
+
+@dataclass
+class EvidenceItem:
+    concept_slug: str
+    kind: str
+    strength: str
+    summary: str
+    path: str | None
+    start_line: int | None
+    end_line: int | None
+    signal: Signal
+    supports_claim_types: list[str] = field(default_factory=list)
+
+
+def map_signal_to_evidence_kind(kind: str) -> str:
+    return _KIND_MAP.get(kind, "other")
+
+
+def estimate_strength(s: Signal) -> str:
+    if s.kind == "test":
+        # E2E UI specs match keywords by accident -> weak (Reality Validation).
+        if s.metadata.get("e2e"):
+            return "weak"
+        # Behavior-specific test names are strong; bare test presence is medium.
+        return "strong" if s.name and len(s.name) > 8 else "medium"
+    if s.kind in STRONG_KINDS:
+        return "strong"
+    if s.kind in MEDIUM_KINDS:
+        return "medium"
+    return "weak"
+
+
+def _supports(kind: str) -> list[str]:
+    mapping = {
+        "route": ["concept", "behavior"],
+        "auth": ["concept", "behavior"],
+        "behavior": ["behavior"],
+        "usage": ["usage"],
+        "dependency": ["usage"],
+        "test": ["test", "behavior"],
+        "decision": ["decision"],
+        "config": ["usage"],
+        "doc": ["concept"],
+        "worker": ["concept", "behavior"],
+        "middleware": ["behavior"],
+    }
+    return mapping.get(kind, ["concept"])
+
+
+def summarize_signal(s: Signal) -> str:
+    if s.kind == "route":
+        return f"{s.name} route handles requests in {s.file_rel_path}."
+    if s.kind == "test":
+        return f"Test '{s.name}' in {s.file_rel_path}."
+    if s.kind == "dependency":
+        return f"Depends on '{s.name}' ({s.file_rel_path})."
+    if s.kind == "webhook_signature_verification":
+        return f"Verifies {s.name} webhook signatures in {s.file_rel_path}."
+    if s.kind == "auth_dependency":
+        return f"Auth dependency '{s.name}' in {s.file_rel_path}."
+    if s.kind == "decision":
+        return f"Decision record: {s.name} ({s.file_rel_path})."
+    if s.kind == "config":
+        return f"Config reference '{s.name}' in {s.file_rel_path}."
+    return f"{s.kind}: {s.name or ''} ({s.file_rel_path})".strip()
+
+
+def _rank_key(e: EvidenceItem) -> tuple[int, float]:
+    order = {"strong": 3, "medium": 2, "weak": 1, "contradictory": 0}
+    return (order.get(e.strength, 0), e.signal.confidence)
+
+
+def build_evidence(concept: ConceptCandidate) -> list[EvidenceItem]:
+    items: list[EvidenceItem] = []
+    for s in concept.signals:
+        kind = map_signal_to_evidence_kind(s.kind)
+        strength = estimate_strength(s)
+        items.append(
+            EvidenceItem(
+                concept_slug=concept.slug,
+                kind=kind,
+                strength=strength,
+                summary=summarize_signal(s),
+                path=s.file_rel_path,
+                start_line=s.start_line,
+                end_line=s.end_line,
+                signal=s,
+                supports_claim_types=_supports(kind),
+            )
+        )
+    items.sort(key=_rank_key, reverse=True)
+    return items

devtime/intelligence/lineage.py

@@ -0,0 +1,21 @@
+"""Lineage (Builder Edition / Full Book, Book III Ch.9).
+
+Lineage shows how meaning changes over time. V0 is a placeholder: it has no
+git-history backed evolution yet, but the seam exists so later versions can track
+how concepts evolve across code, decisions, tests, and risk.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class LineageEntry:
+    concept_slug: str
+    note: str
+
+
+def lineage_for(concept_slug: str) -> list[LineageEntry]:
+    # V0: no historical lineage yet.
+    return []

devtime/intelligence/risk.py

@@ -0,0 +1,267 @@
+"""Risk review (Builder Edition, Chapter 13; Trust Repair v0.0.6).
+
+Risk review checks a change against repository memory. It does not prove a PR is
+broken; it surfaces low-noise, specific, evidence-linked, actionable signals.
+
+Trust Repair makes the result *honest* with explicit states:
+  - review_failed          : DevTime could not read the diff (e.g. git failed).
+  - no_findings            : the diff was inspected; no supported rule found a problem.
+  - unsupported_change_class: known-concept files changed, but no rule covers this change.
+  - finding                : a supported rule found a risk.
+
+"No findings" never means "could not inspect" or "do not know this risk class".
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from devtime.intelligence.claims import ConceptIntelligence
+
+MAX_FINDINGS = 5
+
+STATE_REVIEW_FAILED = "review_failed"
+STATE_NO_FINDINGS = "no_findings"
+STATE_UNSUPPORTED = "unsupported_change_class"
+STATE_FINDING = "finding"
+
+
+@dataclass
+class RiskFinding:
+    severity: str
+    concept: str
+    type: str
+    text: str
+    changed_files: list[str] = field(default_factory=list)
+    missing: list[str] = field(default_factory=list)
+    suggested_action: str = ""
+    human_review_required: bool = False
+    why_it_matters: str = ""
+
+
+@dataclass
+class RiskReview:
+    state: str
+    findings: list[RiskFinding] = field(default_factory=list)
+    affected_concepts: list[str] = field(default_factory=list)
+    reason: str = ""  # populated for review_failed
+
+
+@dataclass
+class DiffInfo:
+    changed_files: list[str]
+    added_lines: list[str]
+    removed_lines: list[str]
+
+    @property
+    def changed_text(self) -> str:
+        return "\n".join(self.added_lines + self.removed_lines).lower()
+
+    @property
+    def code_lines(self) -> list[str]:
+        return [ln for ln in (self.added_lines + self.removed_lines) if not _is_comment(ln)]
+
+    @property
+    def has_code_change(self) -> bool:
+        """True if the diff contains at least one non-comment changed line."""
+        return any(ln.strip() for ln in self.code_lines)
+
+
+_COMMENT_RE = re.compile(r"""^\s*(//|#|/\*|\*|<!--|"""  r'"""' r"""|''')""")
+
+
+def _is_comment(line: str) -> bool:
+    return bool(_COMMENT_RE.match(line))
+
+
+def review_failed(reason: str) -> RiskReview:
+    return RiskReview(state=STATE_REVIEW_FAILED, reason=reason)
+
+
+def parse_unified_diff(diff_text: str) -> DiffInfo:
+    changed_files: list[str] = []
+    added: list[str] = []
+    removed: list[str] = []
+    for line in diff_text.splitlines():
+        m = re.match(r"^\+\+\+ b/(.+)$", line)
+        if m:
+            changed_files.append(m.group(1))
+            continue
+        if line.startswith("+++") or line.startswith("---"):
+            continue
+        if line.startswith("+"):
+            added.append(line[1:])
+        elif line.startswith("-"):
+            removed.append(line[1:])
+    return DiffInfo(changed_files=changed_files, added_lines=added, removed_lines=removed)
+
+
+def _concept_evidence_paths(ci: ConceptIntelligence) -> set[str]:
+    return {e.path for e in ci.evidence if e.path}
+
+
+def _concept_touched(ci: ConceptIntelligence, changed_files: list[str]) -> bool:
+    paths = _concept_evidence_paths(ci)
+    return any(cf in paths for cf in changed_files)
+
+
+def _behavior_changed(diff: DiffInfo, *keywords: str) -> bool:
+    # A comment-only diff is never a behavior change (Trust Repair). When there is
+    # real code change, keyword matches (including in adjacent comments) count.
+    if not diff.has_code_change:
+        return False
+    return any(k in diff.changed_text for k in keywords)
+
+
+def _test_changed(diff: DiffInfo, patterns: list[str]) -> bool:
+    for cf in diff.changed_files:
+        low = cf.lower()
+        if (".test." in low or ".spec." in low or "test" in low) and any(
+            p in low for p in patterns
+        ):
+            return True
+    return any(p in diff.changed_text for p in patterns) and "test" in diff.changed_text
+
+
+# --- JWT algorithm weakening (P0-2) ------------------------------------------
+
+_ALGO_UNSAFE_RE = re.compile(
+    r"""(?i)\b(alg|algorithm|jwt[_a-z]*algorithm|signing[_a-z]*algorithm)\b\s*[:=]\s*"""
+    r"""['"]?\s*(none|null)\s*['"]?""",
+)
+_ALGO_EMPTY_RE = re.compile(
+    r"""(?i)\b(alg|algorithm|jwt[_a-z]*algorithm|signing[_a-z]*algorithm)\b\s*[:=]\s*['"]\s*['"]""",
+)
+
+
+def _auth_evidence_files(intelligence: list[ConceptIntelligence]) -> set[str]:
+    files: set[str] = set()
+    for ci in intelligence:
+        if ci.concept.name == "Authentication":
+            files |= _concept_evidence_paths(ci)
+    return files
+
+
+def _looks_auth_path(path: str) -> bool:
+    low = path.lower()
+    return any(t in low for t in ("auth", "jwt", "token", "security", "login", "session"))
+
+
+def detect_jwt_algorithm_risk(
+    diff: DiffInfo, intelligence: list[ConceptIntelligence]
+) -> list[RiskFinding]:
+    """Value-aware: an algorithm constant changed to an unsafe value (none/empty).
+
+    Comment lines are excluded, and the changed line need not mention 'jwt'/'token'.
+    """
+    auth_files = _auth_evidence_files(intelligence)
+    findings: list[RiskFinding] = []
+    for line in diff.added_lines:
+        if _is_comment(line):
+            continue
+        if not (_ALGO_UNSAFE_RE.search(line) or _ALGO_EMPTY_RE.search(line)):
+            continue
+        in_auth = any(cf in auth_files for cf in diff.changed_files) or any(
+            _looks_auth_path(cf) for cf in diff.changed_files
+        )
+        severity = "high" if in_auth else "medium"
+        nearby_tests = _test_changed(diff, ["jwt", "token", "auth", "verify"])
+        suggested = "Run JWT verification/key-rotation tests and require human security review."
+        if not nearby_tests:
+            suggested += " No nearby JWT verification tests were found in this diff."
+        findings.append(
+            RiskFinding(
+                severity=severity,
+                concept="Authentication",
+                type="jwt_algorithm_weakening",
+                text="JWT signing algorithm appears to change to an unsafe value: none.",
+                changed_files=diff.changed_files,
+                missing=["security review", "JWT verification tests"],
+                suggested_action=suggested,
+                human_review_required=True,
+                why_it_matters="This may disable or weaken token signing/verification.",
+            )
+        )
+        break  # one precise finding is enough
+    return findings
+
+
+# --- Main entry --------------------------------------------------------------
+
+def review_diff(
+    diff: DiffInfo, intelligence: list[ConceptIntelligence]
+) -> RiskReview:
+    if not diff.changed_files:
+        return RiskReview(state=STATE_NO_FINDINGS)
+
+    affected = [ci for ci in intelligence if _concept_touched(ci, diff.changed_files)]
+
+    findings: list[RiskFinding] = []
+
+    # Value-aware JWT algorithm weakening can fire even when Authentication evidence
+    # is only path-adjacent (auth-looking file).
+    findings += detect_jwt_algorithm_risk(diff, intelligence)
+
+    for ci in affected:
+        name = ci.concept.name
+
+        if name == "Billing Webhooks" and _behavior_changed(
+            diff, "retry", "idempoten", "duplicate"
+        ):
+            if not _test_changed(diff, ["duplicate", "webhook", "retry"]):
+                findings.append(
+                    RiskFinding(
+                        severity="high",
+                        concept=name,
+                        type="missing_test_update",
+                        text="Retry behavior changed without duplicate-delivery test changes.",
+                        changed_files=diff.changed_files,
+                        missing=["duplicate-delivery test update", "retry strategy decision"],
+                        suggested_action=(
+                            "Update duplicate-delivery tests or record the retry "
+                            "behavior decision before merge."
+                        ),
+                        human_review_required=True,
+                        why_it_matters=(
+                            "Billing webhooks may receive duplicate events; retry without "
+                            "dedupe tests risks double-processing."
+                        ),
+                    )
+                )
+
+        if name == "Authentication" and _behavior_changed(diff, "token", "jwt", "refresh"):
+            has_decision = any(e.kind == "decision" for e in ci.evidence)
+            already_algo = any(f.type == "jwt_algorithm_weakening" for f in findings)
+            if not has_decision and not already_algo:
+                findings.append(
+                    RiskFinding(
+                        severity="medium",
+                        concept=name,
+                        type="missing_decision",
+                        text="Token behavior changed but no related decision was found.",
+                        changed_files=diff.changed_files,
+                        missing=["token strategy decision"],
+                        suggested_action="Record a token strategy decision or link an existing ADR.",
+                        human_review_required=True,
+                    )
+                )
+
+    if findings:
+        severity_rank = {"critical": 4, "high": 3, "medium": 2, "low": 1}
+        findings.sort(key=lambda f: severity_rank.get(f.severity, 0), reverse=True)
+        return RiskReview(
+            state=STATE_FINDING,
+            findings=findings[:MAX_FINDINGS],
+            affected_concepts=sorted({f.concept for f in findings}),
+        )
+
+    if affected:
+        # Known-concept files changed but no supported rule evaluated this change.
+        return RiskReview(
+            state=STATE_UNSUPPORTED,
+            affected_concepts=sorted({ci.concept.name for ci in affected}),
+        )
+
+    # Diff inspected; nothing DevTime tracks was touched.
+    return RiskReview(state=STATE_NO_FINDINGS)