sourcecode 2.5.8__tar.gz → 2.5.12__tar.gz

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

@@ -1,5 +1,143 @@
 # 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
+saying so, and refute a claim without saying so.** Both closed here. Also lands
+ADR-0005, which ratifies the Evidence Reconciliation Layer as infrastructure and
+records — with measurements — which of its "missing pieces" were never needed.
+
+### Fixed
+
+- **`ask <path> <subcommand>` silently analyzed the current directory instead
+  (P2-G)** (`cli.py`): the argument preprocessor popped the first positional into
+  a path that only the top-level `main` reads. Every subcommand declares its own
+  `path = Argument(".")`, so a leading path before a subcommand was not
+  misparsed — it was **discarded**, and the subcommand fell back to the CWD.
+  `ask spaghetti-api endpoints` reported **1077 endpoints from every repo in the
+  parent directory** (the real surface was 7), exit 0, no warning — an agent
+  consuming that JSON could not tell it was reading someone else's code. Now
+  refused: exit 2, empty stdout, naming the correct invocation. Reordering cannot
+  be guessed (`impact <symbol> <path>` has no free slot). The false-positive
+  guard (an option *value* that happens to match a subcommand name, e.g.
+  `--files endpoints`) is covered. The test suite was itself a victim: four tests
+  invoked the wrong-order form and passed while analyzing atlas-cli — they
+  asserted only "valid JSON", which any repo produces. Corrected to assert an
+  artifact only the intended fixture yields.
+
+- **Refuted architecture claims were pruned silently (INV-F1-4)**
+  (`architecture_analyzer.py`, `reconciliation.py`): three reconciliation rules
+  (`layer_language_coherence`, `composition_runtime_split`,
+  `layer_code_attestation`) were consumed through name-only projections that
+  discarded the finding's explanation. The analyzer dropped a layer or rejected a
+  pattern and told the reader nothing — ofbiz showed fewer modules, jobrunr's
+  "fullstack" vanished, keycloak's foreign `view` layer disappeared, each without
+  a trace. A reader could not distinguish *"this repo has no architecture"* from
+  *"we refuted the architecture claim"* — the exact distinction the analyzer's
+  degrade-to-N/A discipline exists to preserve. Refutations that shape the
+  reported result now surface in `limitations`, prefixed *"Architecture claim
+  refuted on evidence: …"*. Scoped to avoid noise: the winning pattern's pruned
+  layers, the runtime-split contradiction that removed a contender, and every
+  pruning in the fallback paths (which run only when nothing else qualified).
+
+### Added
+
+- **ADR-0005 — Evidence Reconciliation Layer (F-1)**
+  (`docs/architecture/adr/0005-evidence-reconciliation.md`): the layer's contract,
+  invariants and limits. Ratifies the contract as **data** (immutable views +
+  pure-function rules + `ReconciliationFinding`) and **rejects** the proposed
+  provider protocol — an ABC spanning the six consumers would constrain nothing.
+  Documents that the "precursors" slated for migration (the Confidence envelope,
+  `coverage_confidence`, `zero_result_reason`, readiness N/A) are single-view
+  mechanisms that must stay out of F-1, and that pipelines — not commands — are
+  the unit of coverage (`onboard`/`review-pr`/`fix-bug` inherit reconciliation
+  from `prepare_context`).
+
+## [2.5.9] — 2026-07-17
+
+**A silently dead fast path.** The backlog carried the `entry_points`
+list-vs-dict drift as a schema tidiness item. It was not: the drift had disabled
+a feature, quietly, on exactly the repositories that feature exists for.
+
+### Fixed
+
+- **RIS stored `entry_points` in whichever shape it was handed
+  (P2-F-RESIDUE(b))** (`ris.py`): `agent_view` emits that key in two shapes under
+  one `schema_version` — `{"bootstrap": [path…], "security": […],
+  "controllers": {counts}}` when a bootstrap entry point is detected, otherwise
+  `[{"path": …, "kind": …}, …]`. RIS copied either one verbatim into
+  `structural_map["entrypoints"]`, a key its readers treat as a list of path
+  **strings**: they slice it, then guard `isinstance(fp, str)`.
+
+  Both shapes broke it, measured against the real function:
+
+  | shape | result |
+  |---|---|
+  | dict (Spring, …) | `entrypoints[:10]` → `KeyError: slice(None, 10, None)`. `prepare_context._try_ris_fast_path` wraps its whole body in `except Exception: return None`, so **the RIS fast path was silently dead on Java/Spring repos** — falling back to full analysis with no warning. |
+  | list of dicts (everything else) | `isinstance(fp, str)` is false for every item → **zero entry-point files recovered**, silently. |
+
+  The fast path therefore recovered entry points for **no repository at all**,
+  and a bare `except` kept it quiet. `_entrypoint_paths()` now normalizes either
+  shape — plus plain path lists and junk — to the paths RIS promises. Only
+  `bootstrap`/`security` carry paths, so the `controllers` count summary cannot
+  leak into the list.
+
+  The public shape drift is deliberately untouched: unifying it changes a
+  documented `schema_version` and belongs in its own release. RIS's contract now
+  holds whichever shape it is handed, which is what its readers depend on.
+
+3 new tests; suite `3466 passed, 5 skipped, 1 deselected` (the deselection is a
+pre-existing `file_chunker` failure unrelated to this work).
+
 ## [2.5.8] — 2026-07-17
 
 **A count must name what it counted.** 2.5.7 taught the headline to say *"Polyglot

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 2.5.8
+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.8 → sourcecode-2.5.12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "2.5.8"
+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.8 → 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.8"
+__version__ = "2.5.12"

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

@@ -5,9 +5,8 @@ from pathlib import Path
 from typing import Literal, Optional
 
 from sourcecode.reconciliation import (
-    incoherent_layers,
-    pattern_contradicted,
-    unattested_layers,
+    reconcile_architecture_evidence,
+    reconcile_code_modules,
 )
 
 from sourcecode.schema import (
@@ -280,6 +279,18 @@ class ArchitectureAnalyzer:
     ) -> ArchitectureAnalysis:
         limitations: list[str] = []
         evidence: list[dict] = []
+        # INV-F1-4: reconciliation rules that refute a layer/pattern must not
+        # apply their verdict silently — a pruned layer or a rejected pattern is
+        # a positively-detected contradiction the reader is entitled to see, or
+        # "no architecture" becomes indistinguishable from "we refuted the
+        # 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)
@@ -482,6 +493,25 @@ class ArchitectureAnalyzer:
                     "confidence": "low",
                 })
 
+        # INV-F1-4 sink: surface every refutation that shaped the returned
+        # result. Prefix frames it as a refutation; the detail (unchanged) states
+        # the contradiction, keeping it sink-neutral (INV-F1-5). Dedup: the
+        # layered→modular fallthrough can refute the same directory twice.
+        _seen: set[str] = set()
+        for _detail in self._refutations:
+            if _detail in _seen:
+                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,
             pattern=pattern,
@@ -627,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.
@@ -665,6 +713,13 @@ class ArchitectureAnalyzer:
         best_priority = -1
         best_matched: dict[str, list[str]] = {}
         best_layer_files: dict[str, set[int]] = {}
+        # INV-F1-4: refutations that fired while assembling each candidate. Only
+        # those that shaped the RETURNED result are surfaced (below): the winning
+        # pattern's pruned layers, or — when no classical pattern qualifies — the
+        # contradictions that removed the contenders. A refutation of a candidate
+        # that lost on score anyway is not what the reader is being misled about.
+        cand_refutations: dict[str, list[str]] = {}
+        contradiction_details: list[str] = []
 
         for pattern_name, layer_keys in LAYER_PATTERNS.items():
             matched: dict[str, list[str]] = {}
@@ -692,16 +747,34 @@ class ArchitectureAnalyzer:
             # template/asset-only layers are untouched, so a real Spring-MVC
             # `templates/` view survives.
             _layer_paths = {k: [source_paths[i] for i in v] for k, v in layer_files.items()}
-            for _bad in incoherent_layers(pattern_name, _layer_paths, source_paths):
-                matched.pop(_bad, None)
-                layer_files.pop(_bad, None)
-
-            # A claim that IS a runtime split must show one: JobRunr, a JVM
-            # library, read "Fullstack with frontend, backend layers" off a
-            # `dashboard/ui/model/` package of 16 Java files. Nothing to prune —
-            # the pattern itself is what the evidence contradicts.
-            if pattern_contradicted(pattern_name, _layer_paths, source_paths):
+            _refs: list[str] = []
+            _split_contradicted = False
+            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
+                    # library, read "Fullstack with frontend, backend layers" off a
+                    # `dashboard/ui/model/` package of 16 Java files. Nothing to
+                    # prune — the pattern itself is what the evidence contradicts.
+                    _split_contradicted = True
+                else:
+                    # layer_language_coherence: drop the layers owned by a
+                    # different runtime; template/asset-only layers are untouched,
+                    # so a real Spring-MVC `templates/` view survives.
+                    for _bad in _f.symbols:
+                        matched.pop(_bad, None)
+                        layer_files.pop(_bad, None)
+            if _split_contradicted:
+                contradiction_details.extend(_refs)
                 continue
+            cand_refutations[pattern_name] = _refs
 
             # A pattern with unmet required keys cannot qualify (e.g. mvc needs a view).
             required = _PATTERN_REQUIRED_KEYS.get(pattern_name)
@@ -717,6 +790,10 @@ class ArchitectureAnalyzer:
                 best_layer_files = layer_files
 
         if best_score >= 2:
+            # The reported pattern is the one whose refutations misled the reader
+            # if left silent (keycloak's dropped `view` layer). Contradictions of
+            # OTHER, losing candidates did not shape this result — omit them.
+            self._refutations.extend(cand_refutations.get(best_pattern, []))
             layer_confidence: Literal["high", "medium", "low"] = "medium" if best_score >= 3 else "low"
             layers: list[ArchitectureLayer] = []
             for layer_key, matched_dirs in best_matched.items():
@@ -729,6 +806,11 @@ class ArchitectureAnalyzer:
                 ))
             return best_pattern, layers
 
+        # No classical pattern qualified. If a contender was removed by a runtime
+        # split contradiction (jobrunr's "fullstack"), that is why — and the
+        # eventual fallthrough result would otherwise look like a silent absence.
+        self._refutations.extend(contradiction_details)
+
         # 2. Spring domain-module detection (petclinic-style: deep common prefix + feature dirs)
         spring_result = self._detect_spring_domain_modules(source_paths)
         if spring_result is not None:
@@ -872,8 +954,16 @@ class ArchitectureAnalyzer:
         # Architecture with orchestration, data layers" rested on ONE directory
         # entry plus a settings.gradle, with 47 Java files visible and ignored.
         # A logical code layer that holds no code of this repo is not one.
-        for _bad in unattested_layers(non_empty, paths):
-            non_empty.pop(_bad, None)
+        # INV-F1-4: this path only runs when no classical pattern won, so a
+        # 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)
         if len(non_empty) >= 2:
             return "layered", [
                 ArchitectureLayer(name=k, pattern="layered", files=v, confidence="low")
@@ -904,8 +994,14 @@ class ArchitectureAnalyzer:
         # count alone let build and asset directories be reported as modules —
         # ofbiz "docker, framework, runtime, gradle", neo4j "packaging",
         # eureka "images" (five PNGs). The real modules survive untouched.
-        for _bad in unattested_layers(meaningful, paths):
-            meaningful.pop(_bad, None)
+        # 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)
         if len(meaningful) >= 2:
             return "modular", [
                 ArchitectureLayer(name=k, pattern="modular", files=v, confidence="low")

{sourcecode-2.5.8 → 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.8 → 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.8 → sourcecode-2.5.12}/src/sourcecode/cli.py

@@ -7,7 +7,7 @@ import sys
 import threading
 import time
 from pathlib import Path
-from typing import Any, Optional, cast
+from typing import Any, NoReturn, Optional, cast
 
 import typer
 
@@ -293,6 +293,30 @@ _OPTIONS_WITH_VALUE: frozenset[str] = frozenset({
 })
 
 
+def _reject_path_before_subcommand(path_token: str, subcommand: str) -> "NoReturn":
+    """Refuse `ask <path> <subcommand>` instead of silently scanning the CWD.
+
+    `_detected_path` is only read by the root analysis: a subcommand takes its own
+    `path` Argument, which defaults to the current directory. So the path token in
+    `ask spaghetti-api endpoints` was swallowed here and the subcommand ran against
+    the CWD — from a directory of checkouts that is every repository at once.
+    Measured: it answered with 1077 endpoints from keycloak, neo4j and eureka
+    instead of spaghetti-api's 7, exit code 0, no warning.
+
+    A wrong answer that looks right is the one failure this tool must not produce,
+    and the token order cannot be repaired by guessing: subcommands disagree about
+    where a path sits (`impact-chain <symbol> <path>`), so there is no slot to move
+    it to. Name the correct command and stop.
+    """
+    print(
+        f"error: path '{path_token}' comes before the '{subcommand}' subcommand, "
+        f"so it would be ignored and the current directory scanned instead.\n"
+        f"       use: ask {subcommand} {path_token}",
+        file=sys.stderr,
+    )
+    raise SystemExit(2)
+
+
 def _preprocess_args(args: list[str]) -> list[str]:
     """Extract a repository path token from an args list and store it in _detected_path.
 
@@ -300,6 +324,8 @@ def _preprocess_args(args: list[str]) -> list[str]:
     Correctly skips option values (e.g. ``yaml`` in ``--format yaml``).
     If the first non-flag, non-value positional token is a known subcommand name,
     args are returned unchanged so Click can dispatch the subcommand.
+    A path token followed by a subcommand is rejected — see
+    ``_reject_path_before_subcommand``.
     """
     result = list(args)
     skip_next = False
@@ -315,11 +341,17 @@ def _preprocess_args(args: list[str]) -> list[str]:
                 skip_next = True
             continue
         if arg in _SUBCOMMANDS:
+            if _path_index >= 0:
+                # A path already claimed a slot, so this subcommand can only be
+                # the wrong-order form: the path would be dropped and the CWD
+                # scanned in its place.
+                _reject_path_before_subcommand(result[_path_index], arg)
             return result  # known subcommand — leave for Click to dispatch
+        if _path_index >= 0:
+            continue  # a later positional is the subcommand's own business
         # First genuine positional: treat as repository path
         _set_detected_path(arg)
         _path_index = i
-        break
     if _path_index >= 0:
         result.pop(_path_index)
     return result

{sourcecode-2.5.8 → 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.8 → 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