sourcecode 2.5.11__tar.gz → 2.5.12__tar.gz

{sourcecode-2.5.11 → sourcecode-2.5.12}/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## [2.5.12] — 2026-07-18
+
+**F-1 (the Evidence Reconciliation Layer) is closed and its rule core frozen.** This release
+lands the reconciliation gap-fixes accumulated since 2.5.11 and completes INV-F1-4 across
+every surface that narrates an architectural result — the layer's last open honesty debt.
+No new rule, no widened heuristic; the frozen core (`reconciliation.py`) was not touched.
+
+### Fixed
+
+- **INV-F1-4 closed across the narrating surfaces** (`architecture_analyzer.py`,
+  `prepare_context.py`): `036eaa9` made the producer record every architecture refutation on
+  `arch.limitations`, but only the serializer surface transported them — `prepare-context`/
+  onboard computed the analysis and threw the refutations away, so ofbiz's pruned modules and
+  a refuted layered claim vanished silently there. onboard now runs the analysis once (a
+  single owned `sm.architecture`) and carries the refutation lines into `limitations`, the
+  same sink the serializer uses. A reader can distinguish *"no architecture"* from *"claim
+  refuted"* on every narrating surface. One ownership model governs which surface shows,
+  degrades, or only transports a refutation (ADR-0005 §6.5).
+
+- **Directory contamination that manufactured phantom refutations** (`architecture_analyzer.py`):
+  `flatten_file_tree` emits directory nodes, so `sm.file_paths` carried entries like
+  `src/main` that `_detect_layers` counted as jvm-less module members — a directory holding
+  all the Java transitively read as "no jvm code" and was refuted (petclinic phantom
+  `orchestration`; the directory half of `data`). The layer census now drops ancestor
+  (directory) paths; leaf files, including template view-layers, are untouched. Side effect:
+  pattern detection on the previously-polluted input is corrected (petclinic → `mvc`).
+
+- **The web-pattern cross-check is now an F-1 rule (gap #4)** (`reconciliation.py`,
+  `architecture_summary.py`): `_qualify_web_pattern` was an ad-hoc `if`; it is now the seventh
+  rule, `web_pattern_endpoint_attestation`. The migration fixed a latent lie — the gate
+  degraded at `high < 5`, so a repo with 1–4 real controllers reported *"no HTTP controllers
+  detected"*. The honest predicate is `high == 0` (provable absence), and the authority is
+  Java-file coverage (`stack == "java"`), not the JVM family.
+
+- **A reconciliation rule that raises can no longer read as "no contradiction" (gap #2)**
+  (`reconciliation.py` and all six consumers): each entry point wraps rules per-rule; an
+  exception yields an execution-error finding routed to a surfaced channel, never silence.
+
+- **JVM checks gate on the runtime family, reconciled to one source (gap #3)**
+  (`reconciliation.py`, `classifier.py`): `stack_runtime_family` is the single owner; the two
+  incomplete `{java,kotlin}` copies are gone. The mvc/rest-api authority gate is separately
+  corrected to Java-file coverage, fixing a Kotlin/Scala/Groovy false-negation (INV-F1-1).
+
+### Documentation
+
+- **ADR-0005 marked Accepted & FROZEN.** Seven rules, six invariants closed, ownership model
+  ratified (§6.5), freeze & re-open conditions recorded (§10). Stale "six rules" / "INV-F1-4
+  violated" text removed. Closure report and surface-integration map in `.planning/`.
+
 ## [2.5.11] — 2026-07-17
 
 **Two ways a tool can lie by omission: analyze the wrong repository without

{sourcecode-2.5.11 → sourcecode-2.5.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 2.5.11
+Version: 2.5.12
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm

{sourcecode-2.5.11 → sourcecode-2.5.12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "2.5.11"
+version = "2.5.12"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-2.5.11 → sourcecode-2.5.12}/src/sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "2.5.11"
+__version__ = "2.5.12"

{sourcecode-2.5.11 → sourcecode-2.5.12}/src/sourcecode/architecture_analyzer.py

@@ -286,6 +286,11 @@ class ArchitectureAnalyzer:
         # architecture claim". `_detect_layers` and its helpers append the
         # findings' sink-neutral detail here; drained into `limitations` below.
         self._refutations: list[str] = []
+        # Gap #2 (fail-open): a reconciliation rule that could not be evaluated
+        # is NOT a clean result — surfaced here as its own limitation, never as a
+        # refutation and never silently, so an unverified pattern cannot ship as
+        # confirmed.
+        self._reconciliation_errors: list[str] = []
 
         # Step 1: filter paths
         filtered = self._filter_paths(sm.file_paths)
@@ -498,6 +503,14 @@ class ArchitectureAnalyzer:
                 continue
             _seen.add(_detail)
             limitations.append(f"Architecture claim refuted on evidence: {_detail}")
+        # Fail-open sink: a rule that could not run is surfaced distinctly — the
+        # pattern it would have checked is reported UNVERIFIED, never certified.
+        _seen_err: set[str] = set()
+        for _detail in self._reconciliation_errors:
+            if _detail in _seen_err:
+                continue
+            _seen_err.add(_detail)
+            limitations.append(f"Architecture reconciliation could not run: {_detail}")
 
         return ArchitectureAnalysis(
             requested=True,
@@ -644,6 +657,24 @@ class ArchitectureAnalyzer:
         return domains
 
     def _detect_layers(self, paths: list[str]) -> tuple[str, list[ArchitectureLayer]]:
+        # Drop directory ENTRIES. `flatten_file_tree` emits every node — files AND
+        # the directories above them — so `sm.file_paths` carries `src`, `src/main`,
+        # `src/main/java/.../model` … A directory is not a file: counting it as a
+        # layer/module member makes it read as jvm-less in `runtime_census` (it holds
+        # no file OF ITS OWN, only children), and a directory that transitively holds
+        # all the Java is then refuted as "no jvm code" — the demonstrated
+        # contamination (petclinic phantom `orchestration` = `src/main`; the
+        # directory half of `data` = `.../model`). A path that is an ancestor of
+        # another path in the set is such an entry; leaf files (incl. template
+        # view-layers) are never ancestors and are kept untouched.
+        _norm = [p.replace("\\", "/") for p in paths]
+        _ancestors: set[str] = set()
+        for _p in _norm:
+            _segs = _p.split("/")
+            for _k in range(1, len(_segs)):
+                _ancestors.add("/".join(_segs[:_k]))
+        paths = [p for p, n in zip(paths, _norm) if n not in _ancestors]
+
         # Exclude non-source paths (tests, benchmarks, docs, tooling, vendored assets)
         # from layer scoring. Also exclude anything under a `resources/` segment: in
         # Maven/Gradle layouts `src/main/resources/**` is bundled config/assets — e.g.
@@ -721,6 +752,11 @@ class ArchitectureAnalyzer:
             for _f in reconcile_architecture_evidence(
                 pattern=pattern_name, layer_files=_layer_paths, repo_files=source_paths
             ):
+                if _f.error:
+                    # A rule that could not run is surfaced always (not tied to
+                    # whether this candidate wins) and never as a refutation.
+                    self._reconciliation_errors.append(_f.detail)
+                    continue
                 _refs.append(_f.detail)
                 if _f.rule == "composition_runtime_split":
                     # A claim that IS a runtime split must show one: JobRunr, a JVM
@@ -922,6 +958,9 @@ class ArchitectureAnalyzer:
         # pruning here directly shapes the returned result (fewer layers, or a
         # drop below 2 that falls through to flat/unknown) — surface it.
         for _f in reconcile_code_modules(layer_files=non_empty, repo_files=paths):
+            if _f.error:
+                self._reconciliation_errors.append(_f.detail)
+                continue
             for _bad in _f.symbols:
                 non_empty.pop(_bad, None)
             self._refutations.append(_f.detail)
@@ -957,6 +996,9 @@ class ArchitectureAnalyzer:
         # eureka "images" (five PNGs). The real modules survive untouched.
         # INV-F1-4: same as the layered path — surface each refuted module.
         for _f in reconcile_code_modules(layer_files=meaningful, repo_files=paths):
+            if _f.error:
+                self._reconciliation_errors.append(_f.detail)
+                continue
             for _bad in _f.symbols:
                 meaningful.pop(_bad, None)
             self._refutations.append(_f.detail)

{sourcecode-2.5.11 → sourcecode-2.5.12}/src/sourcecode/architecture_summary.py

@@ -210,23 +210,38 @@ class ArchitectureSummarizer:
         # welds a foreign runtime's framework onto the primary's label. Drop what
         # the claimed stack does not attest, and never let the TYPE label — which
         # those same frameworks drove — survive its own evidence (P2-F).
-        from sourcecode.reconciliation import type_claim_unattested, unattested_frameworks
+        from sourcecode.reconciliation import (
+            has_execution_error,
+            reconcile_headline_evidence,
+            type_claim_unattested,
+        )
 
-        foreign = unattested_frameworks(primary.stack, sm.project_type, sm.stacks)
-        attested = [name for name in fw_names if name not in foreign]
-        dropped = [name for name in fw_names if name in foreign]
-        if dropped and not attested and type_claim_unattested(
+        _headline_findings = reconcile_headline_evidence(
             claimed_stack=primary.stack, project_type=sm.project_type, stacks=sm.stacks
-        ):
-            return self._describe_foreign_evidence(sm, stack_label, runtime, dropped)
-        fw_names = attested
+        )
+        if has_execution_error(_headline_findings):
+            # Fail-open guard (gap #2): the attestation rule could not run, and
+            # this prose surface has no gap channel to warn on. Rather than assert
+            # an unverified weld ("C#/.NET … using JAX-RS"), withhold the framework
+            # clause — the claim is not made when its check did not execute.
+            fw_names = []
+        else:
+            foreign = frozenset(s for f in _headline_findings for s in f.symbols)
+            attested = [name for name in fw_names if name not in foreign]
+            dropped = [name for name in fw_names if name in foreign]
+            if dropped and not attested and type_claim_unattested(
+                claimed_stack=primary.stack, project_type=sm.project_type, stacks=sm.stacks
+            ):
+                return self._describe_foreign_evidence(sm, stack_label, runtime, dropped)
+            fw_names = attested
 
         fw_str = f" using {', '.join(fw_names)}" if fw_names else ""
         if runtime:
             # BUG #4: never assert "rest api" in the headline unless the endpoints
-            # command actually backs it (Java/Kotlin only — that is where we have an
-            # authoritative extractor). Degrade to a qualified, consistent phrasing.
-            if sm.project_type == "api" and primary.stack in {"java", "kotlin"}:
+            # command actually backs it. Authority is Java ONLY: extract_java_endpoints
+            # reads *.java and is blind to .kt — a Kotlin REST API would otherwise
+            # degrade to "only 0 endpoints detected" over routes it cannot see.
+            if sm.project_type == "api" and primary.stack == "java":
                 total, high = self._endpoint_support()
                 if high < _MIN_REST_ENDPOINTS_FOR_LABEL:
                     plural = "s" if total != 1 else ""
@@ -310,23 +325,62 @@ class ArchitectureSummarizer:
 
     def _qualify_web_pattern(self, arch: Any, arch_line: str, sm: SourceMap) -> str:
         """BUG #1 (Jenkins field test): the "mvc" pattern is a directory-name
-        heuristic (dirs matching controller/model/view keywords). On a Java/Kotlin
-        repo, do not assert "MVC pattern with ... view layers" in prose when the
+        heuristic (dirs matching controller/model/view keywords). On a JVM repo,
+        do not assert "MVC pattern with ... view layers" in prose when the
         canonical endpoint extractor finds no HTTP controllers in the same run —
         Jenkins (Stapler web framework) matches model/view-ish dirs but declares
-        zero Spring MVC controllers. Cross-check against `endpoints` and degrade to
-        a consistent, non-committal phrasing instead of a categorical MVC claim."""
+        zero Spring MVC controllers.
+
+        This is a reconciliation rule (layer table × endpoint index), so the
+        judgement lives in F-1 (`reconcile_web_pattern_evidence`), not as an
+        ad-hoc `if` here (ADR-0005 §6.2/§8.4). The honest predicate is ZERO
+        modeled controllers, not `< 5`: with the old threshold, 1–4 real
+        controllers still degraded to the categorical "no HTTP controllers
+        detected" — a false statement. One controller backs the MVC claim; only
+        an empty index contradicts it.
+
+        **Authority = Java only.** The extractor (`extract_java_endpoints`) reads
+        `*.java`; it is blind to `.kt`/`.scala`/`.groovy`. So zero controllers is
+        a contradiction ONLY for a Java-primary repo. On Kotlin/Scala/Groovy an
+        empty index is the extractor's blindness, not absence of controllers —
+        degrading there asserted "no HTTP controllers detected" over real `.kt`
+        routes (INV-F1-1: never fire on absence of evidence). Gating the rule on
+        the JVM *family* was wrong; the boundary is the extractor's file coverage."""
+        from sourcecode.reconciliation import (
+            has_execution_error,
+            reconcile_web_pattern_evidence,
+        )
+
         if not arch_line or arch.pattern not in ("mvc", "spring_mvc_layered"):
             return arch_line
         primary = next((s for s in sm.stacks if s.primary), sm.stacks[0] if sm.stacks else None)
-        if primary is None or primary.stack not in {"java", "kotlin"}:
-            return arch_line
         _total, high = self._endpoint_support()
-        if high >= _MIN_REST_ENDPOINTS_FOR_LABEL:
-            return arch_line
-        # No controller backing → the MVC/view claim is unverified. Report the
-        # directory-derived layers without the framework label or the "view" claim.
+        # The endpoint extractor reads .java only — it is authoritative for a
+        # Java-primary repo, blind elsewhere.
+        _authoritative = bool(primary) and primary.stack == "java"
+        _findings = reconcile_web_pattern_evidence(
+            pattern=arch.pattern,
+            endpoint_evidence_authoritative=_authoritative,
+            modeled_endpoint_count=high,
+        )
         layer_names = [l.name for l in arch.layers[:4] if l.name != "view"] if arch.layers else []
+        if has_execution_error(_findings):
+            # Fail-open guard (gap #2): the cross-check could not run. Withhold the
+            # categorical MVC label AND the "no controllers" claim (both unverified);
+            # report only the directory-derived layers, or nothing.
+            if layer_names:
+                return (
+                    f"Layered code organization ({', '.join(layer_names)}; "
+                    "directory-based — endpoint cross-check unavailable)."
+                )
+            return ""
+        if not _findings:
+            # Non-Java (extractor blind), not a web pattern, or ≥1 controller backs
+            # the claim → keep. On Kotlin/Scala/Groovy the MVC label stays
+            # unverified rather than falsely negated.
+            return arch_line
+        # Contradiction: zero modeled controllers. Degrade — the claim is
+        # directory names, not routes; the "no HTTP controllers" wording is TRUE.
         if layer_names:
             return (
                 f"Layered code organization ({', '.join(layer_names)}; "

{sourcecode-2.5.11 → sourcecode-2.5.12}/src/sourcecode/classifier.py

@@ -207,7 +207,7 @@ class TypeClassifier:
         # structured codebase (e.g. JobRunr: core + per-framework adapter modules).
         # This is checked BEFORE the weak `bin/`-directory CLI heuristic so a build
         # output / wrapper `bin/` dir does not mislabel a library as a CLI.
-        if stack_names & {"java", "kotlin", "scala"} and self._is_multi_module(file_tree):
+        if stack_names & _JVM_STACKS and self._is_multi_module(file_tree):
             return "library"
 
         # Weak CLI heuristic: a top-level bin/ directory (only when nothing stronger).

{sourcecode-2.5.11 → sourcecode-2.5.12}/src/sourcecode/confidence_analyzer.py

@@ -120,6 +120,20 @@ class ConfidenceAnalyzer:
                 project_type=sm.project_type,
                 stacks=sm.stacks,
             ):
+                if _rf.error:
+                    # Fail-open guard (gap #2): the stack-attestation rule could
+                    # not run. Never let that read as "primary attests every
+                    # framework" — record it as an anomaly + gap, not silence.
+                    anomalies.append(
+                        "Stack/framework attestation could not be evaluated — "
+                        "primary-stack attribution is UNVERIFIED"
+                    )
+                    gaps.append(AnalysisGap(
+                        area="framework_stack_attestation",
+                        reason=_rf.detail,
+                        impact="medium",
+                    ))
+                    continue
                 anomalies.append(
                     f"{', '.join(_rf.symbols)} declared by another runtime, not by the "
                     f"{_primary.stack} primary stack"

{sourcecode-2.5.11 → sourcecode-2.5.12}/src/sourcecode/prepare_context.py

@@ -1249,6 +1249,17 @@ class TaskContextBuilder:
                 [ws.path for ws in workspace_analysis.workspaces],
             )
 
+        # F-1 single-ownership (ADR-0005 §INV-F1-4): run the architecture analysis
+        # ONCE, here, and keep it on sm.architecture — the single owned analysis.
+        # ArchitectureSummarizer/ContextSummarizer reuse it instead of each computing
+        # (and discarding) a private copy, and its refutations are transported into
+        # `limitations` below (surface #3, F1-SURFACE-INTEGRATION-2026-07-18).
+        from sourcecode.architecture_analyzer import ArchitectureAnalyzer as _ArchAnalyzer
+        try:
+            sm.architecture = _ArchAnalyzer().analyze(self.root, sm)
+        except Exception:
+            sm.architecture = None
+
         project_summary = ProjectSummarizer(self.root).generate(sm)
         architecture_summary = ArchitectureSummarizer(self.root).generate(sm)
 
@@ -1306,6 +1317,19 @@ class TaskContextBuilder:
         key_dependencies: list[dict[str, Any]] = []
         limitations: list[str] = []
 
+        # INV-F1-4 transport: this surface narrates the architecture, so it must
+        # carry the owner's refutations — the same lines surface #1 (serializer)
+        # emits. Only the F-1 refutation / execution-error lines (their fixed
+        # prefixes); pattern-inference notes stay out of the onboard surface. The
+        # analysis is the single owned one (sm.architecture) — no re-run, no re-judge.
+        if sm.architecture is not None:
+            for _arch_lim in (sm.architecture.limitations or []):
+                if _arch_lim.startswith((
+                    "Architecture claim refuted on evidence:",
+                    "Architecture reconciliation could not run:",
+                )):
+                    limitations.append(_arch_lim)
+
         if spec.enable_dependencies:
             from dataclasses import asdict
             from sourcecode.dependency_analyzer import DependencyAnalyzer

{sourcecode-2.5.11 → sourcecode-2.5.12}/src/sourcecode/reconciliation.py

@@ -62,17 +62,75 @@ from pathlib import Path
 
 @dataclass(frozen=True)
 class ReconciliationFinding:
-    """One positively-detected contradiction between two evidence views."""
+    """One reconciliation outcome that a consumer must not narrate away.
+
+    Two kinds ride this one type, distinguished by `error`:
+
+    - a **detected contradiction** (`error=False`, `symbols` non-empty): two
+      views positively disagree; the consumer degrades the claim and names it.
+    - an **execution error** (`error=True`, `symbols` empty): a rule could not be
+      evaluated. It exists so that a rule that raises is NEVER indistinguishable
+      from a rule that ran and found nothing — the fail-open that let an
+      exception silently certify the very claim the rule was meant to check.
+
+    A rule that is *not applicable*, or that ran and found the views consistent,
+    yields NO finding: both legitimately mean "no contradiction, the claim may
+    stand", and no consumer acts differently on them. Only the error case needed
+    a physical state of its own (ADR-0005 §8.2).
+    """
     rule: str                 # stable rule id, e.g. "endpoint_coverage"
     symbols: tuple[str, ...]  # symbols the contradiction is anchored to
     detail: str               # one-sentence human/agent-readable statement
+    error: bool = False       # True iff this marks a rule that could not run
 
     def to_dict(self) -> dict:
-        return {
+        d = {
             "rule": self.rule,
             "symbols": list(self.symbols),
             "detail": self.detail,
         }
+        # Healthy findings serialize byte-identically to before; the flag appears
+        # only when set, so no existing consumer/snapshot shifts.
+        if self.error:
+            d["error"] = True
+        return d
+
+
+def _execution_error(rule_id: str, exc: Exception) -> ReconciliationFinding:
+    """Build the finding that marks a rule which raised instead of running."""
+    return ReconciliationFinding(
+        rule=rule_id,
+        symbols=(),
+        error=True,
+        detail=(
+            f"the {rule_id} reconciliation rule could not be evaluated "
+            f"({type(exc).__name__}) — its consistency check did NOT run, so the "
+            "claim it guards is UNVERIFIED, not confirmed."
+        ),
+    )
+
+
+def _run_rule(rule_id: str, thunk) -> list[ReconciliationFinding]:
+    """Run one rule in isolation. On any exception, return an execution-error
+    finding instead of swallowing it — the core of the fail-open fix. Per-rule
+    (not per-surface) so one rule raising never blanks a sibling rule's finding.
+    """
+    try:
+        return list(thunk())
+    except Exception as exc:  # noqa: BLE001 — deliberate: convert, never swallow
+        return [_execution_error(rule_id, exc)]
+
+
+def execution_errors(
+    findings: "list[ReconciliationFinding]",
+) -> list[ReconciliationFinding]:
+    """The execution-error findings in a batch (empty if every rule ran)."""
+    return [f for f in findings if getattr(f, "error", False)]
+
+
+def has_execution_error(findings: "list[ReconciliationFinding]") -> bool:
+    """True iff any rule in the batch could not be evaluated."""
+    return any(getattr(f, "error", False) for f in findings)
 
 
 def http_handler_classes(cir) -> frozenset[str]:
@@ -142,14 +200,12 @@ def reconcile_impact_evidence(
         modeled_classes: classes the endpoint index has ≥1 route for
                          (endpoint_index.controller_fqns).
     """
-    findings: list[ReconciliationFinding] = []
-    try:
-        findings.extend(
-            _rule_endpoint_coverage(chain_classes, handler_classes, modeled_classes)
-        )
-    except Exception:
-        pass
-    return findings
+    return _run_rule(
+        "endpoint_coverage",
+        lambda: _rule_endpoint_coverage(
+            chain_classes, handler_classes, modeled_classes
+        ),
+    )
 
 
 # ---------------------------------------------------------------------------
@@ -387,11 +443,11 @@ def reconcile_code_modules(
         layer_files: {claimed module -> its files}.
         repo_files:  every source file, supplying the repo's own runtime.
     """
-    try:
+    def _run() -> list[ReconciliationFinding]:
         repo_runtimes = runtime_census({"_repo": list(repo_files)})["_repo"]
         return _rule_layer_code_attestation(runtime_census(layer_files), repo_runtimes)
-    except Exception:
-        return []
+
+    return _run_rule("layer_code_attestation", _run)
 
 
 def unattested_layers(
@@ -422,16 +478,22 @@ def reconcile_architecture_evidence(
         repo_files:  every source file considered — supplies the repo's own
                      runtime, the arbiter of which layers belong to the claim.
     """
-    findings: list[ReconciliationFinding] = []
     try:
         census = runtime_census(layer_files)
         repo_runtimes = runtime_census({"_repo": list(repo_files)})["_repo"]
-        findings.extend(
-            _rule_layer_language_coherence(pattern, census, repo_runtimes)
-        )
-        findings.extend(_rule_composition_runtime_split(pattern, census))
-    except Exception:
-        pass
+    except Exception as exc:
+        # Shared view prep failed — neither rule could run. One error finding,
+        # attributed to the primary architecture rule, carries that to the sink.
+        return [_execution_error("layer_language_coherence", exc)]
+    findings: list[ReconciliationFinding] = []
+    findings += _run_rule(
+        "layer_language_coherence",
+        lambda: _rule_layer_language_coherence(pattern, census, repo_runtimes),
+    )
+    findings += _run_rule(
+        "composition_runtime_split",
+        lambda: _rule_composition_runtime_split(pattern, census),
+    )
     return findings
 
 
@@ -487,6 +549,19 @@ _STACK_FAMILY: dict[str, str] = {
     "elixir": "beam", "erlang": "beam",
 }
 
+
+def stack_runtime_family(stack_id: str) -> str | None:
+    """Runtime family of a stack id (``jvm``/``js``/``python``/…), or None.
+
+    The single source of truth for "which stacks share a runtime". A consumer
+    that gates on JVM-ness (a Kotlin, Scala or Groovy repo is the SAME runtime as
+    a Java one) reads this instead of hardcoding ``{"java", "kotlin"}`` — which
+    silently dropped Scala and Groovy and let an unverified claim ship on them.
+    None means "unjudgeable", never a contradiction (INV-F1-1).
+    """
+    return _STACK_FAMILY.get(stack_id or "")
+
+
 # Project types that are SUPPOSED to span runtimes — their headline names a tier
 # split, so a framework from another runtime is the point, not a contradiction.
 # Same carve-out (and same names) as `_CROSS_RUNTIME_PATTERNS` for layer claims.
@@ -594,17 +669,13 @@ def reconcile_headline_evidence(
     """
     if project_type in _CROSS_RUNTIME_TYPES:
         return []
-    findings: list[ReconciliationFinding] = []
-    try:
-        findings.extend(
-            _rule_framework_stack_attestation(
-                _STACK_FAMILY.get(claimed_stack or ""),
-                framework_owner_families(stacks),
-            )
-        )
-    except Exception:
-        pass
-    return findings
+    return _run_rule(
+        "framework_stack_attestation",
+        lambda: _rule_framework_stack_attestation(
+            _STACK_FAMILY.get(claimed_stack or ""),
+            framework_owner_families(stacks),
+        ),
+    )
 
 
 def type_claim_unattested(
@@ -631,6 +702,12 @@ def type_claim_unattested(
             return False
         return not any(family in fams for fams in owners.values())
     except Exception:
+        # A bool predicate cannot carry an execution-error finding. It never
+        # decides alone: every caller runs `reconcile_headline_evidence` on the
+        # SAME stacks first (same `framework_owner_families` call), so an
+        # exception here has already surfaced as an execution-error finding
+        # there. Returning False adds NO extra clause — it does not certify a
+        # claim the paired findings call left unguarded.
         return False
 
 
@@ -646,6 +723,81 @@ def unattested_frameworks(
     return frozenset(out)
 
 
+# ---------------------------------------------------------------------------
+# Narrative reconciliation (web-pattern claim × endpoint index)
+# ---------------------------------------------------------------------------
+
+# Patterns that assert an HTTP/view tier. The claim is directory-derived (dirs
+# named controller/model/view); the endpoint index is the authoritative
+# controller evidence for the SAME run. They contradict when the pattern names a
+# web tier but the index modeled NO controller at all — Jenkins (Stapler)
+# matched model/view dirs and declared zero Spring MVC controllers.
+_WEB_PATTERNS: frozenset[str] = frozenset({"mvc", "spring_mvc_layered"})
+
+
+def _rule_web_pattern_attestation(
+    pattern: str, endpoint_evidence_authoritative: bool, modeled_endpoint_count: int
+) -> list[ReconciliationFinding]:
+    """A web/MVC pattern claim that the endpoint index does not back at all.
+
+    Provable ABSENCE, not a threshold: the rule fires only at ZERO modeled
+    controllers (`== 0`), never at "few". One controller backs the claim — the
+    pattern has real HTTP evidence and is not contradicted. The "< N is not
+    really a web app" judgement is a LABEL heuristic and stays in the consumer
+    (ADR-0005 limit 2: a rule may not carry a threshold).
+
+    **Authority gate (INV-F1-1).** Zero controllers is a CONTRADICTION only where
+    the endpoint extractor can actually see the code. The canonical extractor
+    reads `*.java` only — so on a Kotlin/Scala/Groovy repo an empty index is
+    *absence of evidence* (the extractor is blind to `.kt`/`.scala`/`.groovy`),
+    NOT a contradiction, and firing there is a false negative (measured: a Kotlin
+    `@RestController` with real routes read "no HTTP controllers detected"). The
+    caller passes `endpoint_evidence_authoritative`; when false, the rule stays
+    silent. The consumer decides authority (it owns the extractor fact), keeping
+    this rule free of any language/extractor coupling.
+    """
+    if pattern not in _WEB_PATTERNS or not endpoint_evidence_authoritative:
+        return []
+    if modeled_endpoint_count > 0:
+        return []
+    return [
+        ReconciliationFinding(
+            rule="web_pattern_endpoint_attestation",
+            symbols=(pattern,),
+            detail=(
+                f"the '{pattern}' claim names an HTTP/view tier but the endpoint "
+                "index modeled no controller — the layers are directory names, "
+                "not routes."
+            ),
+        )
+    ]
+
+
+def reconcile_web_pattern_evidence(
+    *,
+    pattern: str,
+    endpoint_evidence_authoritative: bool,
+    modeled_endpoint_count: int,
+) -> list[ReconciliationFinding]:
+    """Run the web-pattern attestation rule. Never raises.
+
+    Args:
+        pattern:                        the claimed architecture pattern.
+        endpoint_evidence_authoritative: True iff the endpoint extractor can see
+                                        this repo's controllers (it reads .java
+                                        only — the consumer owns this fact). When
+                                        False, zero endpoints is absence, not a
+                                        contradiction (INV-F1-1), and no finding.
+        modeled_endpoint_count:         high-confidence controllers modeled.
+    """
+    return _run_rule(
+        "web_pattern_endpoint_attestation",
+        lambda: _rule_web_pattern_attestation(
+            pattern, endpoint_evidence_authoritative, modeled_endpoint_count
+        ),
+    )
+
+
 def reconcile_extraction_evidence(
     *,
     type_decl_files: frozenset[str],
@@ -657,9 +809,7 @@ def reconcile_extraction_evidence(
         type_decl_files: files whose masked source declares a Java type.
         extracted_files: files symbol extraction produced ≥1 symbol for.
     """
-    findings: list[ReconciliationFinding] = []
-    try:
-        findings.extend(_rule_parse_coverage(type_decl_files, extracted_files))
-    except Exception:
-        pass
-    return findings
+    return _run_rule(
+        "parse_coverage",
+        lambda: _rule_parse_coverage(type_decl_files, extracted_files),
+    )